Fix readme, jsdoc, integration doc

Author: Jiří Fencl

packages/preact/README.md

@@ -1,51 +1,75 @@
-<p align="center">
-  <a href="https://merkur.js.org/docs/getting-started" title="Getting started">
-    <img src="https://raw.githubusercontent.com/mjancarik/merkur/master/images/merkur-logo.png" width="100px" height="100px" alt="Merkur illustration"/>
-  </a>
-</p>
-
-# Merkur
+# @merkur/preact
 
 [![Build Status](https://github.com/mjancarik/merkur/workflows/CI/badge.svg)](https://github.com/mjancarik/merkur/actions/workflows/ci.yml)
-[![NPM package version](https://img.shields.io/npm/v/@merkur/core/latest.svg)](https://www.npmjs.com/package/@merkur/core)
-![npm bundle size (scoped version)](https://img.shields.io/bundlephobia/minzip/@merkur/core/latest)
+[![NPM package version](https://img.shields.io/npm/v/@merkur/preact/latest.svg)](https://www.npmjs.com/package/@merkur/preact)
+![npm bundle size (scoped version)](https://img.shields.io/bundlephobia/minzip/@merkur/preact/latest)
 [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)
 
-The [Merkur](https://merkur.js.org/) is tiny extensible javascript library for front-end microservices(micro frontends). It allows by default server side rendering for loading performance boost. You can connect it with other frameworks or languages because merkur defines easy API. You can use one of six predefined template's library [Preact](https://preactjs.com/), [µhtml](https://github.com/WebReflection/uhtml#readme), [Svelte](https://svelte.dev/) and [vanilla](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) but you can easily extend for others.
-
-## Features
- - Flexible templating engine
- - Usable with all tech stacks
- - SSR-ready by default
- - Easy extensible with plugins
- - Tiny - 1 KB minified + gzipped 
+Preact integration helpers for [Merkur](https://merkur.js.org/) widgets. Provides client and server entry points, rendering helpers, and CLI scaffolding support for Preact-based Merkur widgets.
 
-## Getting started
+## Installation
 
 ```bash
-npx @merkur/create-widget <name>
+npm install @merkur/preact
+```
 
-cd name
+Peer dependencies required:
 
-npm run dev // Point your browser at http://localhost:4444/
+```bash
+npm install @merkur/core @merkur/plugin-component
 ```
-![alt text](https://raw.githubusercontent.com/mjancarik/merkur/master/images/hello-widget.png "Merkur example, hello widget")
-## Documentation
 
-To check out [live demo](https://merkur.js.org/demo) and [docs](https://merkur.js.org/docs), visit [https://merkur.js.org](https://merkur.js.org).
+## Exports
 
-## Contribution
+| Export | Description |
+|--------|-------------|
+| `@merkur/preact/client` | Client-side Preact rendering helpers |
+| `@merkur/preact/server` | Server-side rendering helpers (uses `preact-render-to-string`) |
+| `@merkur/preact/entries/client.js` | Preact client widget entry point |
+| `@merkur/preact/entries/server.js` | Preact server widget entry point |
+| `@merkur/preact/cli` | CLI helpers for widget scaffolding |
 
-Contribute to this project via [Pull-Requests](https://github.com/mjancarik/merkur/pulls).
+## Documentation
 
-We are using [Changesets](https://github.com/changesets/changesets) for versioning and releasing. To add a changeset describing your changes, run `npm run changeset` from the root of the monorepo.
+Full documentation and setup guide at [merkur.js.org](https://merkur.js.org/docs/getting-started).
+
+## Breaking Changes
+
+### v0.47.0
+
+The `@merkur/preact/webpack` export (`applyBabelLoader`, `applyPreactConfig`) has been **removed**, along with the `@babel/preset-react`, `@merkur/tool-webpack`, and `babel-loader` peer dependencies.
+
+If your webpack config used these helpers, configure the Preact Babel preset manually:
+
+```javascript
+// webpack.config.js
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.(js|ts|tsx|jsx|mjs)$/,
+        exclude: /node_modules/,
+        use: {
+          loader: 'babel-loader',
+          options: {
+            presets: [
+              [
+                '@babel/preset-react',
+                { runtime: 'automatic', importSource: 'preact' },
+              ],
+            ],
+          },
+        },
+      },
+    ],
+  },
+};
+```
 
-> **Note:** The release process is documented in the [root README](https://github.com/mjancarik/merkur#release), which is the source of truth for all contribution and release guidelines.
+Alternatively, migrate to the Vite-based Storybook setup described in the [Storybook integration guide](https://merkur.js.org/docs/storybook-integration-into-merkur), which no longer requires webpack or Babel configuration.
 
----
+## Contribution
 
-Thank you to all the people who already contributed to Merkur!
+Contribute via [Pull-Requests](https://github.com/mjancarik/merkur/pulls).
 
-<a href="https://github.com/mjancarik/merkur/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=mjancarik/merkur" />
-</a>
+We use [Changesets](https://github.com/changesets/changesets) for versioning. Run `npm run changeset` from the monorepo root to add a changeset for your changes.

packages/tool-storybook/README.md

@@ -7,7 +7,63 @@
 
 The module enables integration of [Storybook](https://storybook.js.org/) into [Merkur](https://merkur.js.org/).
 
-**[Documentation for @merkur/tool-storybook](https://merkur.js.org/docs/storybook-integration-into-merkur).**
+**[Full documentation](https://merkur.js.org/docs/storybook-integration-into-merkur).**
+
+## API
+
+### `createPreviewConfig(options)`
+
+Registers a Merkur widget with Merkur's factory and returns a partial Storybook `preview.mjs` configuration (`{ loaders }`). Spread the result into your preview export.
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `widgetProperties` | `Object` | ✅ | Widget definition object — must include `name` and `version`. |
+| `render` | `Function` | — | Called each time the widget's update lifecycle fires, receives the widget instance. Defaults to a no-op. |
+| `createWidget` | `Function` | — | Widget factory function. Defaults to `createMerkurWidget` from `@merkur/core`. |
+
+```javascript
+import { createPreviewConfig } from '@merkur/tool-storybook';
+import widgetProperties from '../src/widget.js';
+
+export default {
+  ...createPreviewConfig({ widgetProperties, render: myRenderCallback }),
+};
+```
+
+### `createVanillaRenderer(options)`
+
+Creates a `render` / `update` pair for vanilla JavaScript widgets that produce HTML strings. Pass `render` as the Storybook story render function and `render: renderer.update` to `createPreviewConfig` so state changes trigger re-renders.
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `ViewComponent` | `Function \| Object<string, Function>` | ✅ | A single view function `(widget) => htmlString`, or a named map with a `"default"` key. |
+| `bindEvents` | `Function` | — | Called after every render: `(container, widget) => void`. Falls back to `widget.View.bindEvents` if present. |
+
+```javascript
+import { createPreviewConfig, createVanillaRenderer } from '@merkur/tool-storybook';
+import widgetProperties from '../src/widget.js';
+
+const renderer = createVanillaRenderer({
+  ViewComponent: { default: (widget) => `<div>${widget.state.counter}</div>` },
+  bindEvents(container, widget) {
+    container.querySelector('button')?.addEventListener('click', widget.onClick);
+  },
+});
+
+export default {
+  ...createPreviewConfig({ widgetProperties, render: renderer.update }),
+  render: renderer.render,
+};
+```
+
+### `createWidgetLoader(options)`
+
+Low-level factory that returns a single Storybook loader function. `createPreviewConfig` uses this internally. Use it directly when you need more control over widget registration.
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `widgetProperties` | `Object` | ✅ | Widget definition object — must include `name` and `version`. |
+| `render` | `Function` | — | Render callback invoked on widget updates. Defaults to a no-op. |
 
 ## About Merkur