@takazudo/zfb 0.1.0-next.2

package/dist/jsx-types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Structural JSX element (VNode). Framework-agnostic: both Preact and React
+ * produce objects that satisfy this shape when a JSX element is rendered.
+ *
+ * The `props` bag may itself contain `children` (nested VNodes) as well as
+ * HTML attribute values (strings, numbers, booleans). All fields are widened
+ * to `unknown` so the type stays opaque to callers that don't know which
+ * framework produced the value.
+ *
+ * `type` accepts BOTH function components (call signature) AND class
+ * components (construct signature). Preact and React both expose
+ * `ComponentType = FunctionComponent | ComponentClass`, and the JSX runtime
+ * stores either on `.type`. Without the construct signature, valid Preact
+ * `<MyComponent />` expressions fail to assign to `VNode` at the framework
+ * boundary (e.g. inside `<Island>` children) — even though class components
+ * are rare in modern Preact, the `ComponentType` union includes them.
+ */
+export type VNodeObject = {
+    readonly type: string | ((...args: unknown[]) => unknown) | (new (...args: unknown[]) => unknown);
+    readonly props: Readonly<Record<string, unknown>>;
+    readonly key: unknown;
+};
+/**
+ * A renderable JSX node: a primitive, `null`, `undefined`, an array, or a
+ * structured VNode object.
+ *
+ * This union covers every value both Preact and React treat as valid
+ * `children`. Importantly it does **not** reference any framework-specific
+ * type, so packages that depend on `zfb` need not install a React / Preact
+ * `@types` package to satisfy this type.
+ */
+export type VNode = string | number | boolean | null | undefined | bigint | VNodeArray | VNodeObject;
+export interface VNodeArray extends ReadonlyArray<VNode> {
+}
+/** @deprecated Use `VNode` instead. */
+export type ReactNode = VNode;
+//# sourceMappingURL=jsx-types.d.ts.map

package/dist/jsx-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsx-types.d.ts","sourceRoot":"","sources":["../src/jsx-types.ts"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,KAAK,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,CAAC;IAClG,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAClD,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,KAAK,GACb,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,SAAS,GACT,MAAM,GACN,UAAU,GACV,WAAW,CAAC;AAEhB,MAAM,WAAW,UAAW,SAAQ,aAAa,CAAC,KAAK,CAAC;CAAG;AAK3D,uCAAuC;AACvC,MAAM,MAAM,SAAS,GAAG,KAAK,CAAC"}

package/dist/jsx-types.js

@@ -0,0 +1,12 @@
+// Lightweight ambient JSX types so the public Island wrapper does not
+// hard-depend on either preact or react as a runtime/types dependency.
+//
+// BCI-4: `IslandProps.children` is now typed as `VNode` (a structural union)
+// rather than the old `ReactNode` alias, so non-React frameworks can
+// implement `IslandProps` without any React type dependency at the type level.
+//
+// Both Preact and React's `children` accept this structural union; the build
+// is type-erased so the actual rendering happens in the user's app under
+// whichever framework adapter they chose.
+export {};
+//# sourceMappingURL=jsx-types.js.map

package/dist/jsx-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsx-types.js","sourceRoot":"","sources":["../src/jsx-types.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,uEAAuE;AACvE,EAAE;AACF,6EAA6E;AAC7E,qEAAqE;AACrE,+EAA+E;AAC/E,EAAE;AACF,6EAA6E;AAC7E,yEAAyE;AACzE,0CAA0C"}

package/dist/paginate.d.ts

@@ -0,0 +1,43 @@
+/** Options accepted by [`paginate`]. */
+export type PaginateOptions<K extends string = string> = {
+    /** Items per page. Must be a positive integer (>= 1). */
+    pageSize: number;
+    /** Name of the dynamic param to fill (e.g. `"page"` for `[page].tsx`). */
+    param: K;
+};
+/** One page of paginated results. The shape consumed by the page component. */
+export type PaginatedPage<T> = {
+    /** Items belonging to this page. */
+    data: T[];
+    /** 1-based page number. */
+    page: number;
+    /** Total number of pages (>= 1). */
+    lastPage: number;
+    /** Items per page (echoed for convenience). */
+    pageSize: number;
+    /** Total item count across all pages. */
+    total: number;
+};
+/**
+ * Route entry returned by [`paginate`], one per page.
+ *
+ * The `K` generic carries the literal param name through, so consumers
+ * accessing e.g. `route.params.page` get `string` rather than
+ * `string | undefined` under `noUncheckedIndexedAccess`.
+ */
+export type PaginateRoute<T, K extends string = string> = {
+    params: Record<K, string>;
+    props: {
+        page: PaginatedPage<T>;
+    };
+};
+/**
+ * Slice `items` into pages of `opts.pageSize` and produce one route entry
+ * per page. The `param` option names the dynamic segment to fill — for
+ * `pages/blog/page/[page].tsx` pass `param: "page"`.
+ *
+ * Always emits at least one route. An empty input list yields a single
+ * empty page so the index route still renders rather than 404ing.
+ */
+export declare function paginate<T, K extends string = string>(items: readonly T[], opts: PaginateOptions<K>): PaginateRoute<T, K>[];
+//# sourceMappingURL=paginate.d.ts.map

package/dist/paginate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paginate.d.ts","sourceRoot":"","sources":["../src/paginate.ts"],"names":[],"mappings":"AAOA,wCAAwC;AACxC,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI;IACvD,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,KAAK,EAAE,CAAC,CAAC;CACV,CAAC;AAEF,+EAA+E;AAC/E,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI;IAC7B,oCAAoC;IACpC,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI;IACxD,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IAC1B,KAAK,EAAE;QAAE,IAAI,EAAE,aAAa,CAAC,CAAC,CAAC,CAAA;KAAE,CAAC;CACnC,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,EACnD,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,IAAI,EAAE,eAAe,CAAC,CAAC,CAAC,GACvB,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAgCvB"}

package/dist/paginate.js

@@ -0,0 +1,44 @@
+// `zfb/paginate` — paginate an array of items into per-page route entries.
+//
+// Mirrors the shape of Astro's `paginate()` so the bundled basic-blog template can
+// emit one route per page from a `paths()` export. The renderer treats
+// each returned object as `{ params, props }`, the same convention used
+// elsewhere by the routing engine.
+/**
+ * Slice `items` into pages of `opts.pageSize` and produce one route entry
+ * per page. The `param` option names the dynamic segment to fill — for
+ * `pages/blog/page/[page].tsx` pass `param: "page"`.
+ *
+ * Always emits at least one route. An empty input list yields a single
+ * empty page so the index route still renders rather than 404ing.
+ */
+export function paginate(items, opts) {
+    if (!Number.isInteger(opts.pageSize) || opts.pageSize < 1) {
+        throw new RangeError(`paginate: pageSize must be an integer >= 1, got ${String(opts.pageSize)}`);
+    }
+    if (typeof opts.param !== "string" || opts.param.length === 0) {
+        throw new TypeError(`paginate: param must be a non-empty string, got ${JSON.stringify(opts.param)}`);
+    }
+    const pageSize = opts.pageSize;
+    const total = items.length;
+    const lastPage = Math.max(1, Math.ceil(total / pageSize));
+    const routes = [];
+    for (let page = 1; page <= lastPage; page++) {
+        const start = (page - 1) * pageSize;
+        const slice = items.slice(start, start + pageSize);
+        routes.push({
+            params: { [opts.param]: String(page) },
+            props: {
+                page: {
+                    data: slice,
+                    page,
+                    lastPage,
+                    pageSize,
+                    total,
+                },
+            },
+        });
+    }
+    return routes;
+}
+//# sourceMappingURL=paginate.js.map

package/dist/paginate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paginate.js","sourceRoot":"","sources":["../src/paginate.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,EAAE;AACF,mFAAmF;AACnF,uEAAuE;AACvE,wEAAwE;AACxE,mCAAmC;AAoCnC;;;;;;;GAOG;AACH,MAAM,UAAU,QAAQ,CACtB,KAAmB,EACnB,IAAwB;IAExB,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,GAAG,CAAC,EAAE,CAAC;QAC1D,MAAM,IAAI,UAAU,CAClB,mDAAmD,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAC3E,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9D,MAAM,IAAI,SAAS,CACjB,mDAAmD,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAChF,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;IAC/B,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC;IAC3B,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,QAAQ,CAAC,CAAC,CAAC;IAC1D,MAAM,MAAM,GAA0B,EAAE,CAAC;IACzC,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,IAAI,QAAQ,EAAE,IAAI,EAAE,EAAE,CAAC;QAC5C,MAAM,KAAK,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,QAAQ,CAAC;QACpC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,QAAQ,CAAC,CAAC;QACnD,MAAM,CAAC,IAAI,CAAC;YACV,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,IAAI,CAAC,EAAuB;YAC3D,KAAK,EAAE;gBACL,IAAI,EAAE;oBACJ,IAAI,EAAE,KAAK;oBACX,IAAI;oBACJ,QAAQ;oBACR,QAAQ;oBACR,KAAK;iBACN;aACF;SACF,CAAC,CAAC;IACL,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/plugins.d.ts

@@ -0,0 +1,259 @@
+/**
+ * Logger handed to every plugin hook. The Rust side wraps `tracing` so
+ * the same lines show up alongside the rest of the build's structured
+ * logs. Hooks should prefer this over `console.log`.
+ */
+export type ZfbPluginLogger = {
+    info(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string): void;
+};
+/**
+ * One emitted route in the `postBuild` route manifest (#262).
+ * Present on `ctx.routes.routes` so a `postBuild` plugin can iterate
+ * every URL the build produced (e.g. to write a `sitemap.xml`).
+ */
+export type ZfbRouteEntry = {
+    /** Emitted URL path, e.g. `/`, `/blog/hello/`, `/sitemap.xml`. */
+    url: string;
+    /** Path under `outDir`, e.g. `index.html`, `blog/hello/index.html`, `sitemap.xml`. */
+    output: string;
+    /** File extension: `html`, `xml`, `rss`, `txt`, `json`, … */
+    extension: string;
+    /** Source page module relative to the project root, e.g. `pages/blog/[slug].tsx`. */
+    source: string;
+    /**
+     * `true` when the page is prerendered to disk (default / SSG); `false`
+     * when the page exports `prerender = false` and is served by the
+     * runtime adapter (SSR — no on-disk artifact under `outDir`).
+     *
+     * Indexes that enumerate on-disk URLs (sitemap.xml, search-index.json,
+     * etc.) should filter `r.prerender !== false` to avoid surfacing SSR
+     * routes that have no static output.
+     */
+    prerender: boolean;
+    /**
+     * Bound route parameters. Absent for static routes.
+     * Dynamic (`[slug]`) params are string scalars; catchall (`[...rest]`)
+     * params are string arrays.
+     */
+    params?: Record<string, string | string[]>;
+};
+/**
+ * The route manifest exposed on `ctx.routes` during a `postBuild` callback
+ * (#262). Sorted by `url` for byte-stable output across runs.
+ */
+export type ZfbRouteManifest = {
+    routes: ZfbRouteEntry[];
+};
+/**
+ * Context passed to `preBuild` and `postBuild`. `outDir` is the
+ * resolved absolute path of the configured `outDir` (default
+ * `<projectRoot>/dist`). `projectRoot` is the directory containing
+ * `zfb.config.ts`.
+ *
+ * `routes` is **only present on `postBuild`** calls; it is `undefined`
+ * on `preBuild`. This is intentional: the route manifest is not
+ * available until the build finishes writing `dist/` (#262).
+ */
+export type ZfbBuildHookContext = {
+    /** Project root — the directory containing `zfb.config.ts`. */
+    projectRoot: string;
+    /** Resolved absolute path of the build output directory. */
+    outDir: string;
+    /** The full loaded `ZfbConfig` (data-only view). */
+    config: import("./config.js").ZfbConfig;
+    /** Plugin-specific options block, copied verbatim from the matching `PluginConfig.options`. */
+    options: Record<string, unknown>;
+    /** Logger that wraps the Rust-side `tracing` subscriber. */
+    logger: ZfbPluginLogger;
+    /**
+     * All routes emitted by this build, sorted by URL (#262).
+     * Present only on `postBuild` calls; `undefined` on `preBuild`.
+     */
+    routes?: ZfbRouteManifest;
+};
+/**
+ * A request handed to a `devMiddleware` handler. Subset of the Node
+ * `http.IncomingMessage` surface intentionally — the dev server is
+ * Rust-side `axum`, not Node, so we expose only what survives a JSON
+ * envelope hop.
+ */
+export type ZfbDevMiddlewareRequest = {
+    method: string;
+    url: string;
+    /** Lower-cased header names → first value. */
+    headers: Record<string, string>;
+    /** Raw request body; absent for GET/HEAD. UTF-8 only — binary is out of scope for v1 dev plugins. */
+    body?: string;
+};
+/**
+ * Response returned by a `devMiddleware` handler. All fields optional
+ * except `status`. `body` may be a string (UTF-8) or a base64-encoded
+ * binary payload (set `bodyEncoding` to `"base64"` in that case).
+ */
+export type ZfbDevMiddlewareResponse = {
+    status: number;
+    headers?: Record<string, string>;
+    body?: string;
+    bodyEncoding?: "utf8" | "base64";
+};
+/**
+ * Handler signature for a `devMiddleware` registration. The `next` callback
+ * is reserved for future composition; v1 plugins should produce a response
+ * directly. Returning `undefined` from the handler signals "I did not handle
+ * this request" — the dev server then falls through to its built-in routes
+ * (the page cache, /__zfb/livereload.js, etc.).
+ */
+export type ZfbDevMiddlewareHandler = (req: ZfbDevMiddlewareRequest) => Promise<ZfbDevMiddlewareResponse | undefined> | ZfbDevMiddlewareResponse | undefined;
+/**
+ * Context passed to `devMiddleware`. The `register` callback installs
+ * one handler per URL path prefix. `path` is matched as an exact prefix
+ * — a registration on `/doc-history` matches `/doc-history` and
+ * `/doc-history/foo`, but NOT `/doc-historyx`.
+ */
+export type ZfbDevMiddlewareContext = {
+    projectRoot: string;
+    config: import("./config.js").ZfbConfig;
+    options: Record<string, unknown>;
+    logger: ZfbPluginLogger;
+    /** Register an HTTP handler at `path`. Calling twice on the same path overwrites. */
+    register(path: string, handler: ZfbDevMiddlewareHandler): void;
+};
+/**
+ * Loader signature for a virtual-module registration. Must return the
+ * **complete ESM module source text** as a string — the bundler /
+ * embedded V8 host feeds the returned string in as the module's
+ * source verbatim. The loader is invoked **exactly once per build**
+ * (and once per `zfb dev` host boot) the first time any consumer
+ * imports the registered specifier; subsequent imports of the same
+ * specifier re-use the memoised result.
+ *
+ * Example:
+ *
+ * ```ts
+ * addVirtualModule("virtual:my-data", () =>
+ *   `export default ${JSON.stringify(myJson)}`,
+ * );
+ * ```
+ */
+export type ZfbVirtualModuleLoader = () => string | Promise<string>;
+/**
+ * Context passed to the new `setup` hook (#255). Runs once per host
+ * boot, in `Config.plugins` declaration order, **before** `preBuild`.
+ *
+ * `ctx.command` tells the plugin which lifecycle is active so it can
+ * gate dev-only registrations:
+ *
+ * ```ts
+ * setup({ command, injectRoute }) {
+ *   if (command === "dev") {
+ *     injectRoute("/api/dev/x", "./scripts/dev-x.ts");
+ *   }
+ * }
+ * ```
+ *
+ * The hook's surface is intentionally **closed**: only
+ * `injectRoute`, `addVirtualModule`, `addAlias`. There is no
+ * `addRemarkPlugin` / `addRehypePlugin` / `addMarkdownVisitor` — by
+ * design (see the concept doc for the rationale).
+ */
+export type ZfbSetupContext = {
+    /**
+     * Active zfb command. `"build"` during `zfb build`; `"dev"` during
+     * `zfb dev`. Gates `injectRoute` (calling it during `"build"` is an
+     * error — see [`injectRoute`](#injectRoute)).
+     */
+    command: "build" | "dev";
+    /** Project root — the directory containing `zfb.config.ts`. */
+    projectRoot: string;
+    /** The full loaded `ZfbConfig` (data-only view). */
+    config: import("./config.js").ZfbConfig;
+    /** Plugin-specific options block, copied verbatim from `PluginConfig.options`. */
+    options: Record<string, unknown>;
+    /** Logger that wraps the Rust-side `tracing` subscriber. */
+    logger: ZfbPluginLogger;
+    /**
+     * Register an import alias. **Exact-match-only in v1**:
+     * `addAlias("@/foo", "./src/foo.tsx")` rewrites `import "@/foo"`
+     * but does NOT match `import "@/foo/bar"`. Prefix-matching is
+     * explicitly deferred to v2 — switch to one bare alias per file
+     * until then.
+     *
+     * `to` is resolved relative to the project root. Two plugins
+     * registering the same `from` with different `to` raises
+     * `AliasConflict` and aborts the build.
+     */
+    addAlias(from: string, to: string): void;
+    /**
+     * Register a virtual module. `specifier` is a bare import
+     * specifier (recommended `virtual:` prefix, not enforced).
+     * `loader` returns the complete ESM source text as a string and
+     * runs **exactly once per build** at first import.
+     *
+     * Two plugins registering the same `specifier` raises
+     * `VirtualModuleConflict` and aborts the build.
+     */
+    addVirtualModule(specifier: string, loader: ZfbVirtualModuleLoader): void;
+    /**
+     * Register a synthetic page route. The dev server routes the
+     * matched URL into the page rendering pipeline as if `entrypoint`
+     * were a `pages/<...>.tsx` file. `pattern` uses the same grammar
+     * as `pages/` filenames (`/blog/[slug]`, `/api/dev/x`,
+     * `/docs/[...rest]`).
+     *
+     * **Dev-only.** Calling `injectRoute` when `ctx.command === "build"`
+     * raises `InjectRouteInBuildMode` and aborts the build — synthetic
+     * routes during a static build would invite SSR-shaped pages that
+     * conflict with `output: 'static'`.
+     *
+     * Two plugins registering the same `pattern` raises
+     * `InjectRouteConflict`.
+     */
+    injectRoute(pattern: string, entrypoint: string): void;
+};
+/**
+ * The plugin-module shape. `name` is informational (the resolved module
+ * specifier wins for identification on the Rust side) and helps the
+ * plugin self-identify in logs.
+ *
+ * Four optional hooks; declaration-order matters when multiple plugins
+ * touch the same surface. Each hook is independent — a plugin may
+ * declare any subset:
+ *
+ * - `setup` (#255) — register virtual modules, aliases, injected
+ *   routes. Runs once at host boot, before `preBuild`.
+ * - `preBuild` — file-generation work that downstream stages will
+ *   see. Runs once per `zfb build` and once per `zfb dev` boot.
+ * - `postBuild` — finalisation work that runs after `dist/` has been
+ *   written.
+ * - `devMiddleware` — register HTTP handlers for ad-hoc dev-only
+ *   URLs. Per-request dispatch, distinct from `injectRoute` (which
+ *   goes through the page renderer).
+ */
+export type ZfbPlugin = {
+    /** Plugin display name; surfaces in error / log lines. */
+    name: string;
+    setup?(ctx: ZfbSetupContext): Promise<void> | void;
+    preBuild?(ctx: ZfbBuildHookContext): Promise<void> | void;
+    postBuild?(ctx: ZfbBuildHookContext): Promise<void> | void;
+    devMiddleware?(ctx: ZfbDevMiddlewareContext): Promise<void> | void;
+};
+/**
+ * Identity helper that types the supplied object as a [`ZfbPlugin`].
+ * Use as the default export of a plugin module so editors surface
+ * field-level types and typos surface at compile time.
+ *
+ * ```ts
+ * import { definePlugin } from "@takazudo/zfb/plugins";
+ *
+ * export default definePlugin({
+ *   name: "my-plugin",
+ *   async preBuild({ outDir, logger }) {
+ *     logger.info(`generating index into ${outDir}`);
+ *   },
+ * });
+ * ```
+ */
+export declare function definePlugin(plugin: ZfbPlugin): ZfbPlugin;
+//# sourceMappingURL=plugins.d.ts.map

package/dist/plugins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugins.d.ts","sourceRoot":"","sources":["../src/plugins.ts"],"names":[],"mappings":"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"}

package/dist/plugins.js

@@ -0,0 +1,42 @@
+// `zfb/plugins` — TypeScript helper for the zfb plugin lifecycle.
+//
+// A plugin is a JS module whose default export is a [`ZfbPlugin`] object.
+// `zfb.config.ts` references plugins by `name` (npm bare specifier or a
+// `./`-relative path); the zfb config loader resolves each `name` to an
+// absolute module specifier and the Rust-side plugin host loads the
+// module via dynamic `import()` and dispatches the lifecycle hooks.
+//
+// Sub 3 / issue #108 — initial drop. Three optional hooks: `preBuild`,
+// `postBuild`, `devMiddleware`. Astro-migration epic #253 / sub-issue
+// #255 adds a fourth: `setup`, which runs once before `preBuild` and
+// lets plugins register virtual modules, import aliases, and dev-only
+// injected routes. None of the hooks see real Node IPC objects across
+// the boundary; everything is JSON-friendly.
+//
+// ## Inline functions are NOT supported
+//
+// `PluginConfig` (in `./config.ts`) carries only data. A user cannot
+// inline a function in `zfb.config.ts` — the config goes through a
+// JSON round-trip and any function value would be silently dropped.
+// Plugins must live in their own module (npm package or local file)
+// and be referenced by `name`.
+/**
+ * Identity helper that types the supplied object as a [`ZfbPlugin`].
+ * Use as the default export of a plugin module so editors surface
+ * field-level types and typos surface at compile time.
+ *
+ * ```ts
+ * import { definePlugin } from "@takazudo/zfb/plugins";
+ *
+ * export default definePlugin({
+ *   name: "my-plugin",
+ *   async preBuild({ outDir, logger }) {
+ *     logger.info(`generating index into ${outDir}`);
+ *   },
+ * });
+ * ```
+ */
+export function definePlugin(plugin) {
+    return plugin;
+}
+//# sourceMappingURL=plugins.js.map

package/dist/plugins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugins.js","sourceRoot":"","sources":["../src/plugins.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,EAAE;AACF,0EAA0E;AAC1E,wEAAwE;AACxE,wEAAwE;AACxE,oEAAoE;AACpE,oEAAoE;AACpE,EAAE;AACF,uEAAuE;AACvE,sEAAsE;AACtE,qEAAqE;AACrE,sEAAsE;AACtE,sEAAsE;AACtE,6CAA6C;AAC7C,EAAE;AACF,wCAAwC;AACxC,EAAE;AACF,qEAAqE;AACrE,mEAAmE;AACnE,oEAAoE;AACpE,oEAAoE;AACpE,+BAA+B;AAmQ/B;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,YAAY,CAAC,MAAiB;IAC5C,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/runtime.d.ts

@@ -0,0 +1,101 @@
+import { type When } from "./types.js";
+/**
+ * Schedule a hydration `fire` callback for `target` according to `when`.
+ *
+ * Returns a `cancel` function that aborts the scheduling if it has not
+ * fired yet. After firing, calling `cancel` is a no-op. If the helper
+ * cannot find the relevant browser API (e.g. running in pure Node with no
+ * polyfill), it falls back to firing synchronously so server-side smoke
+ * tests still observe the call.
+ */
+export declare function scheduleHydrate(target: Element, when: When | string | undefined, fire: () => void): () => void;
+/**
+ * The shape of the default export each per-island bundle ships.
+ *
+ * `mode === "hydrate"` is used for SSR'd islands, `"render"` for
+ * SSR-skip islands.
+ */
+type IslandMount = (props: Record<string, unknown>, element: Element, mode: "hydrate" | "render") => void;
+type IslandUnmount = (element: Element) => void;
+interface IslandModule {
+    mount?: IslandMount;
+    default?: IslandMount;
+    unmount?: IslandUnmount;
+}
+/**
+ * Map of `componentName → island descriptor` baked into the runtime entry.
+ *
+ * Two descriptor shapes are accepted so the same `mountIslands` runtime
+ * handles both bundling strategies the build emits:
+ *
+ *   1. `string` — a per-island bundle URL. The runtime fetches it via
+ *      dynamic `import()` and reads `mount` / `default` off the loaded
+ *      module. Used by the per-island bundling path
+ *      (`bundle_per_island` / `render_runtime_entry_source`).
+ *
+ *   2. `IslandModule` — an inline module-shaped object whose `mount` (or
+ *      `default`) is called directly. Used by the shared-bundle path
+ *      (`render_shared_bundle_entry_source`): every island's source code
+ *      is already in the same bundle, so the synthesised entry can hand
+ *      the runtime the constructed mount functions inline without a
+ *      second HTTP fetch. This preserves the one-request shared-bundle
+ *      contract while giving up nothing on hydration semantics
+ *      (zudolab/zudo-doc#1355 wave 6).
+ */
+export type IslandManifestValue = string | IslandModule;
+export type IslandManifest = Readonly<Record<string, IslandManifestValue>>;
+/**
+ * Walk the DOM and mount every `[data-zfb-island]` / `[data-zfb-island-skip-ssr]`
+ * element using `manifest`.
+ *
+ * No-op when `document` is undefined (SSR, edge runtime). Safe to call
+ * multiple times: each element is mounted at most once thanks to the
+ * `mounted` WeakSet guard.
+ *
+ * The manifest is captured at module level so `mountNewIslands()` can re-use
+ * it after an SPA body swap without needing the caller to re-supply it.
+ */
+export declare function mountIslands(manifest: IslandManifest): void;
+/**
+ * Re-walk the current document body and mount any new island markers introduced
+ * by an SPA body swap. Uses the manifest captured by the previous `mountIslands`
+ * call — no manifest arg required.
+ *
+ * The caller (client-router `router.ts`) invokes this after `swap()` + `runScripts()`
+ * and before dispatching `zfb:page-load`, per W1B §12.2 contract.
+ *
+ * No-op when called before `mountIslands` (capturedManifest is null) or when
+ * `document` is undefined.
+ */
+export declare function mountNewIslands(): void;
+/**
+ * Cancel deferred-hydration callbacks for all islands in the old body before a
+ * swap. Prevents idle / visibility callbacks from running against orphan elements
+ * after `swapBodyElement` removes them from the live document. (W1B §12.5)
+ *
+ * Call this on `zfb:before-swap` (or equivalently, in the router's swap sequence
+ * before `swap()` mutates the DOM). Fire-and-forget; safe to call if nothing is
+ * pending.
+ */
+export declare function cancelPendingIslands(): void;
+/**
+ * Unmount all currently-mounted islands within `root` (default: `document.body`).
+ *
+ * Walks `root` for `[data-zfb-island]` and `[data-zfb-island-skip-ssr]` elements,
+ * looks up each element's unmount thunk in the `mounted` WeakMap, calls it (which
+ * triggers `render(null, element)` for Preact or `root.unmount()` for React), and
+ * removes the entry from the map so `mountNewIslands()` can re-mount later.
+ *
+ * Call this before `swapBodyElement(...)` so the OLD body's islands receive proper
+ * framework lifecycle cleanup (useEffect teardowns, etc.) before being discarded.
+ *
+ * No-op for elements not in the `mounted` map (e.g. never-mounted or already cleaned up).
+ */
+export declare function unmountIslands(root?: ParentNode): void;
+/**
+ * Test-only seam. Replace the module dynamic-import with a fake.
+ * Returns the previous implementation so tests can restore it.
+ */
+export declare function __setIslandImporterForTests(impl: (url: string) => Promise<IslandModule>): (url: string) => Promise<IslandModule>;
+export {};
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAe,KAAK,IAAI,EAAE,MAAM,YAAY,CAAC;AAkBpD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,SAAS,EAC/B,IAAI,EAAE,MAAM,IAAI,GACf,MAAM,IAAI,CAcZ;AAoHD;;;;;GAKG;AACH,KAAK,WAAW,GAAG,CACjB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,SAAS,GAAG,QAAQ,KACvB,IAAI,CAAC;AAEV,KAAK,aAAa,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;AAEhD,UAAU,YAAY;IACpB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,YAAY,CAAC;AACxD,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC,CAAC;AA8B3E;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAwB3D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAmBtC;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAK3C;AAiMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,IAAI,GAAE,UAA0B,GAAG,IAAI,CAUrE;AAqCD;;;GAGG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,CAAC,GAC3C,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,CAAC,CAIxC"}