@takazudo/zfb 0.1.0-next.10

package/dist/index.js

@@ -0,0 +1,21 @@
+// Public entry point for the "@takazudo/zfb" package.
+//
+// User TSX pages reach this module via `import { Island } from "@takazudo/zfb"`.
+// The hydration runtime (Sub 3) reaches the helper via
+// `import { scheduleHydrate } from "@takazudo/zfb/runtime"` (or by inlining the
+// same logic; coordinated separately).
+export { ANONYMOUS_COMPONENT_NAME, HYDRATE_MARKER_ATTR, Island, SKIP_SSR_MARKER_ATTR, resolveWhen, } from "./island.js";
+export { scheduleHydrate, mountIslands, mountNewIslands, cancelPendingIslands, unmountIslands, } from "./runtime.js";
+export { DEFAULT_WHEN, isWhen, WHEN_VALUES } from "./types.js";
+// `defaultComponents` (htmlOverrides convention) is re-exported from the
+// root entry point so `import { defaultComponents } from "@takazudo/zfb"` is the
+// canonical access path. Each named override is also re-exported so
+// consumers can tree-shake-import a single one (`import { ContentLink } from "@takazudo/zfb"`)
+// without dragging in the whole map.
+// Plugin lifecycle types + `definePlugin` identity helper. Plugin
+// authors typically import these from "@takazudo/zfb/plugins" but the
+// root entry re-exports them so simple plugins can pull everything from
+// one path.
+export { definePlugin, } from "./plugins.js";
+export { ContentBlockquote, ContentCode, ContentH2, ContentH3, ContentH4, ContentLink, ContentOl, ContentParagraph, ContentStrong, ContentTable, ContentUl, defaultComponents, } from "./content.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sDAAsD;AACtD,EAAE;AACF,iFAAiF;AACjF,uDAAuD;AACvD,gFAAgF;AAChF,uCAAuC;AAEvC,OAAO,EACL,wBAAwB,EACxB,mBAAmB,EACnB,MAAM,EACN,oBAAoB,EACpB,WAAW,GAGZ,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,eAAe,EACf,YAAY,EACZ,eAAe,EACf,oBAAoB,EACpB,cAAc,GACf,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,EAAa,MAAM,YAAY,CAAC;AAE1E,yEAAyE;AACzE,iFAAiF;AACjF,oEAAoE;AACpE,+FAA+F;AAC/F,qCAAqC;AACrC,kEAAkE;AAClE,sEAAsE;AACtE,wEAAwE;AACxE,YAAY;AACZ,OAAO,EACL,YAAY,GAQb,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,iBAAiB,EACjB,WAAW,EACX,SAAS,EACT,SAAS,EACT,SAAS,EACT,WAAW,EACX,SAAS,EACT,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,SAAS,EACT,iBAAiB,GAGlB,MAAM,cAAc,CAAC"}

package/dist/island.d.ts

@@ -0,0 +1,121 @@
+import type { VNode } from "./jsx-types.js";
+import { type When } from "./types.js";
+export { resolveWhen } from "./types.js";
+/**
+ * Marker attribute the SSR wrapper writes when the child component should
+ * be hydrated client-side. The hydration runtime queries
+ * `[data-${HYDRATE_MARKER_ATTR}]` to find islands.
+ */
+export declare const HYDRATE_MARKER_ATTR = "data-zfb-island";
+/**
+ * Marker attribute the SSR wrapper writes when SSR is being skipped (the
+ * client:only-equivalent path). The hydration runtime queries
+ * `[data-${SKIP_SSR_MARKER_ATTR}]` to find these placeholders and renders
+ * the real component into them on hydration — there is no server output
+ * to patch up.
+ */
+export declare const SKIP_SSR_MARKER_ATTR = "data-zfb-island-skip-ssr";
+/** Fallback name surfaced when child identity cannot be determined. */
+export declare const ANONYMOUS_COMPONENT_NAME = "Anonymous";
+/**
+ * Attribute the SSR wrapper writes to ferry the wrapped component's props
+ * across the SSR → hydrate boundary. The hydration runtime parses this
+ * with `JSON.parse` and forwards the result to the per-island `mount()`
+ * call so the hydrated component sees the same props the SSR pass did.
+ *
+ * Omitted entirely when the wrapped child has no own data props (other
+ * than `children`) — `readProps` already falls back to `{}` when the
+ * attribute is missing, and emitting `data-props=""` would just bloat
+ * the SSR markup.
+ */
+export declare const PROPS_DATA_ATTR = "data-props";
+/** Props for `<Island>`. */
+export interface IslandProps {
+    /** Hydration scheduling strategy. Defaults to `"load"`. */
+    when?: When;
+    /**
+     * If supplied, switches the island into SSR-skip mode (Astro's
+     * `client:only` equivalent). The wrapper emits the
+     * `data-zfb-island-skip-ssr` marker, the heavy `children` are **not**
+     * evaluated server-side, and `ssrFallback` is rendered in their place.
+     * On hydration the client runtime swaps in the real component.
+     */
+    ssrFallback?: VNode;
+    /**
+     * Server-rendered children, hydrated client-side once `when` fires.
+     *
+     * Typed as `VNode` (structural union) rather than `ReactNode` so
+     * non-React frameworks can implement `IslandProps` without a React
+     * type dependency (BCI-4).
+     */
+    children?: VNode;
+}
+/**
+ * Public JSX-element shape returned by [`Island`]. Intentionally widened
+ * to a structural type so consumers don't infer through the internal
+ * `{ type, props, key }` VNode shape of either Preact or React. Both
+ * jsx-runtimes accept this object on either side of the boundary.
+ */
+export type IslandElement = {
+    readonly type: string;
+    readonly props: Readonly<Record<string, unknown>>;
+    readonly key: unknown;
+};
+/**
+ * `<Island>` JSX wrapper.
+ *
+ * Returns a JSX element shape compatible with both Preact and React. The
+ * runtime tag is `"div"`. In the default (hydrate) mode the wrapper emits
+ * `data-zfb-island="ComponentName"` and `data-when="<resolved-when>"`. In
+ * SSR-skip mode (when `ssrFallback` is provided) it emits
+ * `data-zfb-island-skip-ssr="ComponentName"` instead and renders the
+ * fallback rather than the heavy child.
+ *
+ * The component-name string is derived from the child JSX element's type
+ * identity (`type.displayName ?? type.name`). For string-typed children
+ * (host elements) the tag name is used. If no usable identity can be
+ * recovered, [`ANONYMOUS_COMPONENT_NAME`] is used so the marker still
+ * lines up with the hydration shim's manifest lookup.
+ *
+ * The return type is the public [`IslandElement`] shape — the internal
+ * VNode structure is deliberately not leaked so consumers never type-infer
+ * through it.
+ */
+export declare function Island(props: IslandProps): IslandElement;
+/**
+ * Pull a component-name string out of a JSX child.
+ *
+ * Both Preact and React store rendered VNodes as plain objects whose
+ * `.type` field is either:
+ * - the component function (look at `displayName ?? name`),
+ * - or the host element tag name as a string.
+ *
+ * If `children` is an array (multiple children), the first child with a
+ * usable identity wins. This is intentional: the typical island shape is
+ * `<Island><Foo /></Island>` (single child); when the caller wraps a
+ * fragment-like list we still want a deterministic, debuggable name.
+ *
+ * Exported for tests; not re-exported from `index.ts`.
+ */
+export declare function captureComponentName(children: unknown): string;
+/**
+ * Serialize the wrapped child's data props as a JSON string the runtime
+ * can parse out of the `data-props` attribute on the Island marker div.
+ *
+ * Mirrors [`captureComponentName`]'s array handling: when `children` is
+ * an array (multiple JSX siblings), the first child whose own props
+ * yield a non-empty serialization wins. This keeps the "first
+ * identifiable child" contract consistent across both attributes —
+ * whatever the marker name points at is what the data-props payload
+ * describes.
+ *
+ * Returns `undefined` (not `"{}"` and not `""`) when no usable props
+ * exist. The runtime's `readProps` already maps a missing attribute to
+ * `{}`, so omitting the attribute keeps the SSR markup smaller and
+ * preserves the invariant that the attribute, when present, always
+ * parses to a non-empty record.
+ *
+ * Exported for tests; not re-exported from `index.ts`.
+ */
+export declare function captureSerializableProps(children: unknown): string | undefined;
+//# sourceMappingURL=island.d.ts.map

package/dist/island.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"island.d.ts","sourceRoot":"","sources":["../src/island.ts"],"names":[],"mappings":"AA0CA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAe,KAAK,IAAI,EAAE,MAAM,YAAY,CAAC;AAMpD,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,oBAAoB,CAAC;AAErD;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,6BAA6B,CAAC;AAE/D,uEAAuE;AACvE,eAAO,MAAM,wBAAwB,cAAc,CAAC;AAEpD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,eAAe,CAAC;AAE5C,4BAA4B;AAC5B,MAAM,WAAW,WAAW;IAC1B,2DAA2D;IAC3D,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,KAAK,CAAC;IACpB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,KAAK,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAClD,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;CACvB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,aAAa,CAmCxD;AA2BD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,CAS9D;AAgBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAS9E"}

package/dist/island.js

@@ -0,0 +1,273 @@
+// Build-time `<Island when="...">` JSX wrapper.
+//
+// The wrapper is intentionally JSX-runtime-agnostic: it does not import
+// preact or react and never calls h() / createElement directly. Instead it
+// returns a plain object with a fixed shape that both Preact's and React's
+// jsx-runtime accept when the JSX transform turns the call site into a
+// jsx(Island, props) invocation.
+//
+// At build time, running through the SSR renderer (embedded V8 host):
+//
+//   <Island when="visible"><Counter /></Island>
+//
+// renders as:
+//
+//   <div data-zfb-island="Counter" data-when="visible">
+//     <Counter />
+//   </div>
+//
+// The component-name attribute (`data-zfb-island="ComponentName"`) is filled
+// in *here* by reading the child's JSX type identity (`displayName` first,
+// then `name`). Sub 3's hydration shim then `querySelectorAll`s these
+// markers and looks each one up in the islands manifest produced by the
+// scanner (see `crates/zfb-islands/src/manifest.rs` for the contract).
+//
+// SSR-skip mode: when the caller passes `ssrFallback`, the heavy child is
+// **not** evaluated at SSR time. Instead the wrapper emits a different
+// marker:
+//
+//   <Island ssrFallback={<div>Loading…</div>}><HeavyClientOnly /></Island>
+//   →
+//   <div data-zfb-island-skip-ssr="HeavyClientOnly">
+//     <div>Loading…</div>
+//   </div>
+//
+// On the client the hydration runtime distinguishes hydrate vs. render by
+// which marker attribute is present. This is the equivalent of Astro's
+// `client:only="preact"`.
+//
+// When validation: in development we console.warn for unknown `when`
+// values and fall back to the default. In production we silently fall
+// back to keep the bundle path small.
+import { resolveWhen } from "./types.js";
+// Re-export `resolveWhen` for back-compat: tests and downstream consumers
+// historically imported it from `./island.js`. The implementation lives in
+// `./types.js` so the runtime scheduler can pull it in without dragging
+// the JSX wrapper along for the ride.
+export { resolveWhen } from "./types.js";
+/**
+ * Marker attribute the SSR wrapper writes when the child component should
+ * be hydrated client-side. The hydration runtime queries
+ * `[data-${HYDRATE_MARKER_ATTR}]` to find islands.
+ */
+export const HYDRATE_MARKER_ATTR = "data-zfb-island";
+/**
+ * Marker attribute the SSR wrapper writes when SSR is being skipped (the
+ * client:only-equivalent path). The hydration runtime queries
+ * `[data-${SKIP_SSR_MARKER_ATTR}]` to find these placeholders and renders
+ * the real component into them on hydration — there is no server output
+ * to patch up.
+ */
+export const SKIP_SSR_MARKER_ATTR = "data-zfb-island-skip-ssr";
+/** Fallback name surfaced when child identity cannot be determined. */
+export const ANONYMOUS_COMPONENT_NAME = "Anonymous";
+/**
+ * Attribute the SSR wrapper writes to ferry the wrapped component's props
+ * across the SSR → hydrate boundary. The hydration runtime parses this
+ * with `JSON.parse` and forwards the result to the per-island `mount()`
+ * call so the hydrated component sees the same props the SSR pass did.
+ *
+ * Omitted entirely when the wrapped child has no own data props (other
+ * than `children`) — `readProps` already falls back to `{}` when the
+ * attribute is missing, and emitting `data-props=""` would just bloat
+ * the SSR markup.
+ */
+export const PROPS_DATA_ATTR = "data-props";
+/**
+ * `<Island>` JSX wrapper.
+ *
+ * Returns a JSX element shape compatible with both Preact and React. The
+ * runtime tag is `"div"`. In the default (hydrate) mode the wrapper emits
+ * `data-zfb-island="ComponentName"` and `data-when="<resolved-when>"`. In
+ * SSR-skip mode (when `ssrFallback` is provided) it emits
+ * `data-zfb-island-skip-ssr="ComponentName"` instead and renders the
+ * fallback rather than the heavy child.
+ *
+ * The component-name string is derived from the child JSX element's type
+ * identity (`type.displayName ?? type.name`). For string-typed children
+ * (host elements) the tag name is used. If no usable identity can be
+ * recovered, [`ANONYMOUS_COMPONENT_NAME`] is used so the marker still
+ * lines up with the hydration shim's manifest lookup.
+ *
+ * The return type is the public [`IslandElement`] shape — the internal
+ * VNode structure is deliberately not leaked so consumers never type-infer
+ * through it.
+ */
+export function Island(props) {
+    const when = resolveWhen(props.when);
+    const componentName = captureComponentName(props.children);
+    const isSkipSsr = props.ssrFallback !== undefined;
+    // Always source props from `props.children` (the heavy component VNode),
+    // never from `ssrFallback` — the fallback is just SSR placeholder markup;
+    // the hydrated component is the child, so its props are what `mount()`
+    // needs at hydrate time. (Same rationale as `captureComponentName`.)
+    const dataProps = captureSerializableProps(props.children);
+    if (isSkipSsr) {
+        const skipSsrProps = {
+            [SKIP_SSR_MARKER_ATTR]: componentName,
+            "data-when": when,
+            children: props.ssrFallback ?? null,
+        };
+        if (dataProps !== undefined)
+            skipSsrProps[PROPS_DATA_ATTR] = dataProps;
+        return makeVNode({
+            type: "div",
+            props: skipSsrProps,
+            key: null,
+        });
+    }
+    const hydrateProps = {
+        [HYDRATE_MARKER_ATTR]: componentName,
+        "data-when": when,
+        children: props.children,
+    };
+    if (dataProps !== undefined)
+        hydrateProps[PROPS_DATA_ATTR] = dataProps;
+    return makeVNode({
+        type: "div",
+        props: hydrateProps,
+        key: null,
+    });
+}
+/**
+ * Construct the structural JSX-element shape with `constructor` set to
+ * `undefined`.
+ *
+ * Why: `preact-render-to-string` (and Preact's diff path) recognise a
+ * VNode by checking `vnode.constructor === undefined`. A plain object
+ * literal `{ type, props, key }` inherits `Object` for `.constructor`,
+ * so the renderer treats it as foreign data and emits no markup —
+ * which would silently strip every `<Island>` from SSG output. Marking
+ * `constructor: undefined` is the documented sentinel that both
+ * Preact's and React's renderers treat as a structural VNode.
+ *
+ * The cast back to `IslandElement` keeps the public type tight; the
+ * extra runtime field is JS-only and is invisible to type consumers.
+ */
+function makeVNode(shape) {
+    const v = shape;
+    v.constructor = undefined;
+    return shape;
+}
+/**
+ * Pull a component-name string out of a JSX child.
+ *
+ * Both Preact and React store rendered VNodes as plain objects whose
+ * `.type` field is either:
+ * - the component function (look at `displayName ?? name`),
+ * - or the host element tag name as a string.
+ *
+ * If `children` is an array (multiple children), the first child with a
+ * usable identity wins. This is intentional: the typical island shape is
+ * `<Island><Foo /></Island>` (single child); when the caller wraps a
+ * fragment-like list we still want a deterministic, debuggable name.
+ *
+ * Exported for tests; not re-exported from `index.ts`.
+ */
+export function captureComponentName(children) {
+    if (Array.isArray(children)) {
+        for (const child of children) {
+            const name = nameFromSingle(child);
+            if (name)
+                return name;
+        }
+        return ANONYMOUS_COMPONENT_NAME;
+    }
+    return nameFromSingle(children) || ANONYMOUS_COMPONENT_NAME;
+}
+function nameFromSingle(child) {
+    if (!child || typeof child !== "object")
+        return "";
+    const c = child;
+    const t = c.type;
+    if (typeof t === "function") {
+        const fn = t;
+        if (typeof fn.displayName === "string" && fn.displayName)
+            return fn.displayName;
+        if (typeof fn.name === "string" && fn.name)
+            return fn.name;
+        return "";
+    }
+    if (typeof t === "string" && t)
+        return t;
+    return "";
+}
+/**
+ * Serialize the wrapped child's data props as a JSON string the runtime
+ * can parse out of the `data-props` attribute on the Island marker div.
+ *
+ * Mirrors [`captureComponentName`]'s array handling: when `children` is
+ * an array (multiple JSX siblings), the first child whose own props
+ * yield a non-empty serialization wins. This keeps the "first
+ * identifiable child" contract consistent across both attributes —
+ * whatever the marker name points at is what the data-props payload
+ * describes.
+ *
+ * Returns `undefined` (not `"{}"` and not `""`) when no usable props
+ * exist. The runtime's `readProps` already maps a missing attribute to
+ * `{}`, so omitting the attribute keeps the SSR markup smaller and
+ * preserves the invariant that the attribute, when present, always
+ * parses to a non-empty record.
+ *
+ * Exported for tests; not re-exported from `index.ts`.
+ */
+export function captureSerializableProps(children) {
+    if (Array.isArray(children)) {
+        for (const child of children) {
+            const json = propsFromSingle(child);
+            if (json !== undefined)
+                return json;
+        }
+        return undefined;
+    }
+    return propsFromSingle(children);
+}
+function propsFromSingle(child) {
+    if (!child || typeof child !== "object")
+        return undefined;
+    const c = child;
+    const raw = c.props;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    // Exclude `children` from the serialized payload: the SSR pass already
+    // emitted the rendered children into the DOM (the hydration target),
+    // and JSX child nodes are typically VNode trees with non-serializable
+    // shapes (functions, circular refs) that would either bloat the
+    // payload or throw inside JSON.stringify. The hydration runtime
+    // re-renders into the existing DOM, so it does not need the JSX
+    // children replayed through props.
+    //
+    // Note: JSON.stringify already silently drops function / symbol /
+    // undefined values from the output, so those don't need explicit
+    // pre-filtering here.
+    const propsRecord = raw;
+    let hasOwn = false;
+    const filtered = {};
+    for (const key of Object.keys(propsRecord)) {
+        if (key === "children")
+            continue;
+        filtered[key] = propsRecord[key];
+        hasOwn = true;
+    }
+    if (!hasOwn)
+        return undefined;
+    let json;
+    try {
+        json = JSON.stringify(filtered);
+    }
+    catch {
+        // Circular references, BigInt, or any other non-serializable input
+        // — silently fall through (no `data-props`) rather than ship a
+        // partial payload. The runtime already handles the missing-attribute
+        // case by returning `{}` from `readProps`.
+        return undefined;
+    }
+    // JSON.stringify can also return `undefined` (when the top-level value
+    // serializes to nothing) or `"{}"` (when every key was a function /
+    // symbol / undefined and got dropped). Treat both as "nothing useful
+    // to ship" so the marker stays clean.
+    if (json === undefined || json === "{}")
+        return undefined;
+    return json;
+}
+//# sourceMappingURL=island.js.map

package/dist/island.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"island.js","sourceRoot":"","sources":["../src/island.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,EAAE;AACF,wEAAwE;AACxE,2EAA2E;AAC3E,2EAA2E;AAC3E,uEAAuE;AACvE,iCAAiC;AACjC,EAAE;AACF,sEAAsE;AACtE,EAAE;AACF,gDAAgD;AAChD,EAAE;AACF,cAAc;AACd,EAAE;AACF,wDAAwD;AACxD,kBAAkB;AAClB,WAAW;AACX,EAAE;AACF,6EAA6E;AAC7E,2EAA2E;AAC3E,sEAAsE;AACtE,wEAAwE;AACxE,uEAAuE;AACvE,EAAE;AACF,0EAA0E;AAC1E,uEAAuE;AACvE,UAAU;AACV,EAAE;AACF,2EAA2E;AAC3E,MAAM;AACN,qDAAqD;AACrD,0BAA0B;AAC1B,WAAW;AACX,EAAE;AACF,0EAA0E;AAC1E,uEAAuE;AACvE,0BAA0B;AAC1B,EAAE;AACF,qEAAqE;AACrE,sEAAsE;AACtE,sCAAsC;AAGtC,OAAO,EAAE,WAAW,EAAa,MAAM,YAAY,CAAC;AAEpD,0EAA0E;AAC1E,2EAA2E;AAC3E,wEAAwE;AACxE,sCAAsC;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,iBAAiB,CAAC;AAErD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,0BAA0B,CAAC;AAE/D,uEAAuE;AACvE,MAAM,CAAC,MAAM,wBAAwB,GAAG,WAAW,CAAC;AAEpD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,YAAY,CAAC;AAoC5C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,MAAM,CAAC,KAAkB;IACvC,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACrC,MAAM,aAAa,GAAG,oBAAoB,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC3D,MAAM,SAAS,GAAG,KAAK,CAAC,WAAW,KAAK,SAAS,CAAC;IAClD,yEAAyE;IACzE,0EAA0E;IAC1E,uEAAuE;IACvE,qEAAqE;IACrE,MAAM,SAAS,GAAG,wBAAwB,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAE3D,IAAI,SAAS,EAAE,CAAC;QACd,MAAM,YAAY,GAA4B;YAC5C,CAAC,oBAAoB,CAAC,EAAE,aAAa;YACrC,WAAW,EAAE,IAAI;YACjB,QAAQ,EAAE,KAAK,CAAC,WAAW,IAAI,IAAI;SACpC,CAAC;QACF,IAAI,SAAS,KAAK,SAAS;YAAE,YAAY,CAAC,eAAe,CAAC,GAAG,SAAS,CAAC;QACvE,OAAO,SAAS,CAAC;YACf,IAAI,EAAE,KAAK;YACX,KAAK,EAAE,YAAY;YACnB,GAAG,EAAE,IAAI;SACV,CAAC,CAAC;IACL,CAAC;IAED,MAAM,YAAY,GAA4B;QAC5C,CAAC,mBAAmB,CAAC,EAAE,aAAa;QACpC,WAAW,EAAE,IAAI;QACjB,QAAQ,EAAE,KAAK,CAAC,QAAQ;KACzB,CAAC;IACF,IAAI,SAAS,KAAK,SAAS;QAAE,YAAY,CAAC,eAAe,CAAC,GAAG,SAAS,CAAC;IACvE,OAAO,SAAS,CAAC;QACf,IAAI,EAAE,KAAK;QACX,KAAK,EAAE,YAAY;QACnB,GAAG,EAAE,IAAI;KACV,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAS,SAAS,CAAC,KAIlB;IACC,MAAM,CAAC,GAAG,KAA6C,CAAC;IACxD,CAAC,CAAC,WAAW,GAAG,SAAS,CAAC;IAC1B,OAAO,KAAsB,CAAC;AAChC,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAAiB;IACpD,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC5B,KAAK,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;YAC7B,MAAM,IAAI,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;YACnC,IAAI,IAAI;gBAAE,OAAO,IAAI,CAAC;QACxB,CAAC;QACD,OAAO,wBAAwB,CAAC;IAClC,CAAC;IACD,OAAO,cAAc,CAAC,QAAQ,CAAC,IAAI,wBAAwB,CAAC;AAC9D,CAAC;AAED,SAAS,cAAc,CAAC,KAAc;IACpC,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,EAAE,CAAC;IACnD,MAAM,CAAC,GAAG,KAA2B,CAAC;IACtC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;IACjB,IAAI,OAAO,CAAC,KAAK,UAAU,EAAE,CAAC;QAC5B,MAAM,EAAE,GAAG,CAA8C,CAAC;QAC1D,IAAI,OAAO,EAAE,CAAC,WAAW,KAAK,QAAQ,IAAI,EAAE,CAAC,WAAW;YAAE,OAAO,EAAE,CAAC,WAAW,CAAC;QAChF,IAAI,OAAO,EAAE,CAAC,IAAI,KAAK,QAAQ,IAAI,EAAE,CAAC,IAAI;YAAE,OAAO,EAAE,CAAC,IAAI,CAAC;QAC3D,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IACzC,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,wBAAwB,CAAC,QAAiB;IACxD,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC5B,KAAK,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;YAC7B,MAAM,IAAI,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;YACpC,IAAI,IAAI,KAAK,SAAS;gBAAE,OAAO,IAAI,CAAC;QACtC,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,eAAe,CAAC,QAAQ,CAAC,CAAC;AACnC,CAAC;AAED,SAAS,eAAe,CAAC,KAAc;IACrC,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAC1D,MAAM,CAAC,GAAG,KAA4B,CAAC;IACvC,MAAM,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC;IACpB,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAE5E,uEAAuE;IACvE,qEAAqE;IACrE,sEAAsE;IACtE,gEAAgE;IAChE,gEAAgE;IAChE,gEAAgE;IAChE,mCAAmC;IACnC,EAAE;IACF,kEAAkE;IAClE,iEAAiE;IACjE,sBAAsB;IACtB,MAAM,WAAW,GAAG,GAA8B,CAAC;IACnD,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,MAAM,QAAQ,GAA4B,EAAE,CAAC;IAC7C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;QAC3C,IAAI,GAAG,KAAK,UAAU;YAAE,SAAS;QACjC,QAAQ,CAAC,GAAG,CAAC,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;QACjC,MAAM,GAAG,IAAI,CAAC;IAChB,CAAC;IACD,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAE9B,IAAI,IAAwB,CAAC;IAC7B,IAAI,CAAC;QACH,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,mEAAmE;QACnE,+DAA+D;QAC/D,qEAAqE;QACrE,2CAA2C;QAC3C,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,uEAAuE;IACvE,oEAAoE;IACpE,qEAAqE;IACrE,sCAAsC;IACtC,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAC1D,OAAO,IAAI,CAAC;AACd,CAAC"}

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"}