@takazudo/zfb 2.22.1 → 3.1.0

package/dist/island.d.ts

@@ -1,130 +1,14 @@
 import type { VNode } from "./jsx-types.js";
+import type { Description } from "./zudo-react/description.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;
-    /**
-     * CSS media query string for `when="media"` islands. The island hydrates
-     * when this query first matches (including later viewport changes). The
-     * runtime uses `window.matchMedia(media)` to register a listener.
-     *
-     * Ignored when `when` is not `"media"` (a dev warning is emitted).
-     * Required when `when === "media"` (omitting it falls back to DEFAULT_WHEN
-     * with a dev warning).
-     */
     media?: string;
-    /**
-     * 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 type IslandElement = Description;
 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;

package/dist/island.js

@@ -1,137 +1,13 @@
-// 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 { jsx } from "react/jsx-runtime";
+// Build-time Island wrapper for the owned zudo-react runtime.
+import { ownedIslandBoundary } from "./island-boundary.js";
 import { DEFAULT_WHEN, 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 resolvedWhen = resolveMediaProps(props);
-    const when = resolvedWhen.when;
-    const media = resolvedWhen.media;
-    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,
-        };
-        if (when === "media" && media !== undefined)
-            skipSsrProps["data-media"] = media;
-        if (dataProps !== undefined)
-            skipSsrProps[PROPS_DATA_ATTR] = dataProps;
-        return makeWrapper(skipSsrProps, props.ssrFallback ?? null);
-    }
-    const hydrateProps = {
-        [HYDRATE_MARKER_ATTR]: componentName,
-        "data-when": when,
-    };
-    if (when === "media" && media !== undefined)
-        hydrateProps["data-media"] = media;
-    if (dataProps !== undefined)
-        hydrateProps[PROPS_DATA_ATTR] = dataProps;
-    return makeWrapper(hydrateProps, props.children);
+    const { when, media } = resolveMediaProps(props);
+    return ownedIslandBoundary(props.children, props.ssrFallback, when, media);
 }
-/**
- * Validate and resolve the `when` / `media` props together.
- *
- * - `when="media"` without `media` → warn + fall back to `DEFAULT_WHEN`.
- * - `media` without `when="media"` → warn-and-ignore; `media` is dropped.
- */
 function resolveMediaProps(props) {
     const when = resolveWhen(props.when);
     const media = props.media;
@@ -153,160 +29,4 @@ function resolveMediaProps(props) {
     }
     return { when, media };
 }
-/**
- * Construct the wrapper element through the **automatic JSX runtime
- * factory**, called explicitly so this file stays plain `.ts` (no JSX
- * syntax).
- *
- * Why the explicit `jsx(...)` call rather than a hand-rolled
- * `{ type, props, key }` object literal: a plain literal is only valid for
- * Preact (whose diff path / `preact-render-to-string` recognise a VNode by
- * `vnode.constructor === undefined`). React's renderer rejects such an
- * object as a child with "Objects are not valid as a React child"
- * (minified error #31) because a real React element carries
- * `$$typeof: Symbol.for("react.element")`, which a literal cannot fake
- * portably. Calling `jsx` from `react/jsx-runtime` mints a real element:
- * in React mode it resolves natively; in Preact mode the engine rewrites
- * `react/jsx-runtime` → `preact/jsx-runtime` (bundler.rs ~2886), so the
- * Preact runtime mints the element. Same result the JSX `<div>` delegation
- * produced — but as plain `.ts`.
- *
- * Why `.ts` and NOT `.tsx`: esbuild rewrites a `.js` import specifier to
- * `.ts` but NOT to `.tsx`. The barrel `index.ts` imports `./island.js`;
- * when this file was `island.tsx`, source consumers (the dev `exports`
- * point at `src/*.ts`, e.g. the node-free template / smoke path) failed
- * with `Could not resolve "./island.js"`. The published `dist` worked
- * (tsc emits a real `island.js`), which masked the regression in
- * pnpm-pack/dist probes. Keeping this a `.ts` file makes the barrel resolve
- * `./island.js` → `./island.ts` from source everywhere, while tsc still
- * emits `dist/island.js` for the published package.
- *
- * The cast back to `IslandElement` keeps the public type tight; the
- * concrete element shape produced by the runtime is invisible to type
- * consumers.
- */
-function makeWrapper(props, children) {
-    return jsx("div", { ...props, children });
-}
-/**
- * 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

@@ -1 +1 @@
-{"version":3,"file":"island.js","sourceRoot":"","sources":["../src/island.ts"],"names":[],"mappings":"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","sourcesContent":["// Build-time `<Island when=\"...\">` JSX wrapper.\n//\n// The wrapper is intentionally JSX-runtime-agnostic: it does not import\n// preact or react and never calls h() / createElement directly. Instead it\n// returns a plain object with a fixed shape that both Preact's and React's\n// jsx-runtime accept when the JSX transform turns the call site into a\n// jsx(Island, props) invocation.\n//\n// At build time, running through the SSR renderer (embedded V8 host):\n//\n//   <Island when=\"visible\"><Counter /></Island>\n//\n// renders as:\n//\n//   <div data-zfb-island=\"Counter\" data-when=\"visible\">\n//     <Counter />\n//   </div>\n//\n// The component-name attribute (`data-zfb-island=\"ComponentName\"`) is filled\n// in *here* by reading the child's JSX type identity (`displayName` first,\n// then `name`). Sub 3's hydration shim then `querySelectorAll`s these\n// markers and looks each one up in the islands manifest produced by the\n// scanner (see `crates/zfb-islands/src/manifest.rs` for the contract).\n//\n// SSR-skip mode: when the caller passes `ssrFallback`, the heavy child is\n// **not** evaluated at SSR time. Instead the wrapper emits a different\n// marker:\n//\n//   <Island ssrFallback={<div>Loading…</div>}><HeavyClientOnly /></Island>\n//   →\n//   <div data-zfb-island-skip-ssr=\"HeavyClientOnly\">\n//     <div>Loading…</div>\n//   </div>\n//\n// On the client the hydration runtime distinguishes hydrate vs. render by\n// which marker attribute is present. This is the equivalent of Astro's\n// `client:only=\"preact\"`.\n//\n// When validation: in development we console.warn for unknown `when`\n// values and fall back to the default. In production we silently fall\n// back to keep the bundle path small.\n\nimport { jsx } from \"react/jsx-runtime\";\n\nimport type { VNode } from \"./jsx-types.js\";\nimport { DEFAULT_WHEN, resolveWhen, type When } from \"./types.js\";\n\n// Re-export `resolveWhen` for back-compat: tests and downstream consumers\n// historically imported it from `./island.js`. The implementation lives in\n// `./types.js` so the runtime scheduler can pull it in without dragging\n// the JSX wrapper along for the ride.\nexport { resolveWhen } from \"./types.js\";\n\n/**\n * Marker attribute the SSR wrapper writes when the child component should\n * be hydrated client-side. The hydration runtime queries\n * `[data-${HYDRATE_MARKER_ATTR}]` to find islands.\n */\nexport const HYDRATE_MARKER_ATTR = \"data-zfb-island\";\n\n/**\n * Marker attribute the SSR wrapper writes when SSR is being skipped (the\n * client:only-equivalent path). The hydration runtime queries\n * `[data-${SKIP_SSR_MARKER_ATTR}]` to find these placeholders and renders\n * the real component into them on hydration — there is no server output\n * to patch up.\n */\nexport const SKIP_SSR_MARKER_ATTR = \"data-zfb-island-skip-ssr\";\n\n/** Fallback name surfaced when child identity cannot be determined. */\nexport const ANONYMOUS_COMPONENT_NAME = \"Anonymous\";\n\n/**\n * Attribute the SSR wrapper writes to ferry the wrapped component's props\n * across the SSR → hydrate boundary. The hydration runtime parses this\n * with `JSON.parse` and forwards the result to the per-island `mount()`\n * call so the hydrated component sees the same props the SSR pass did.\n *\n * Omitted entirely when the wrapped child has no own data props (other\n * than `children`) — `readProps` already falls back to `{}` when the\n * attribute is missing, and emitting `data-props=\"\"` would just bloat\n * the SSR markup.\n */\nexport const PROPS_DATA_ATTR = \"data-props\";\n\n/** Props for `<Island>`. */\nexport interface IslandProps {\n  /** Hydration scheduling strategy. Defaults to `\"load\"`. */\n  when?: When;\n  /**\n   * CSS media query string for `when=\"media\"` islands. The island hydrates\n   * when this query first matches (including later viewport changes). The\n   * runtime uses `window.matchMedia(media)` to register a listener.\n   *\n   * Ignored when `when` is not `\"media\"` (a dev warning is emitted).\n   * Required when `when === \"media\"` (omitting it falls back to DEFAULT_WHEN\n   * with a dev warning).\n   */\n  media?: string;\n  /**\n   * If supplied, switches the island into SSR-skip mode (Astro's\n   * `client:only` equivalent). The wrapper emits the\n   * `data-zfb-island-skip-ssr` marker, the heavy `children` are **not**\n   * evaluated server-side, and `ssrFallback` is rendered in their place.\n   * On hydration the client runtime swaps in the real component.\n   */\n  ssrFallback?: VNode;\n  /**\n   * Server-rendered children, hydrated client-side once `when` fires.\n   *\n   * Typed as `VNode` (structural union) rather than `ReactNode` so\n   * non-React frameworks can implement `IslandProps` without a React\n   * type dependency (BCI-4).\n   */\n  children?: VNode;\n}\n\n/**\n * Public JSX-element shape returned by [`Island`]. Intentionally widened\n * to a structural type so consumers don't infer through the internal\n * `{ type, props, key }` VNode shape of either Preact or React. Both\n * jsx-runtimes accept this object on either side of the boundary.\n */\nexport type IslandElement = {\n  readonly type: string;\n  readonly props: Readonly<Record<string, unknown>>;\n  readonly key: unknown;\n};\n\n/**\n * `<Island>` JSX wrapper.\n *\n * Returns a JSX element shape compatible with both Preact and React. The\n * runtime tag is `\"div\"`. In the default (hydrate) mode the wrapper emits\n * `data-zfb-island=\"ComponentName\"` and `data-when=\"<resolved-when>\"`. In\n * SSR-skip mode (when `ssrFallback` is provided) it emits\n * `data-zfb-island-skip-ssr=\"ComponentName\"` instead and renders the\n * fallback rather than the heavy child.\n *\n * The component-name string is derived from the child JSX element's type\n * identity (`type.displayName ?? type.name`). For string-typed children\n * (host elements) the tag name is used. If no usable identity can be\n * recovered, [`ANONYMOUS_COMPONENT_NAME`] is used so the marker still\n * lines up with the hydration shim's manifest lookup.\n *\n * The return type is the public [`IslandElement`] shape — the internal\n * VNode structure is deliberately not leaked so consumers never type-infer\n * through it.\n */\nexport function Island(props: IslandProps): IslandElement {\n  const resolvedWhen = resolveMediaProps(props);\n  const when = resolvedWhen.when;\n  const media = resolvedWhen.media;\n  const componentName = captureComponentName(props.children);\n  const isSkipSsr = props.ssrFallback !== undefined;\n  // Always source props from `props.children` (the heavy component VNode),\n  // never from `ssrFallback` — the fallback is just SSR placeholder markup;\n  // the hydrated component is the child, so its props are what `mount()`\n  // needs at hydrate time. (Same rationale as `captureComponentName`.)\n  const dataProps = captureSerializableProps(props.children);\n\n  if (isSkipSsr) {\n    const skipSsrProps: Record<string, unknown> = {\n      [SKIP_SSR_MARKER_ATTR]: componentName,\n      \"data-when\": when,\n    };\n    if (when === \"media\" && media !== undefined) skipSsrProps[\"data-media\"] = media;\n    if (dataProps !== undefined) skipSsrProps[PROPS_DATA_ATTR] = dataProps;\n    return makeWrapper(skipSsrProps, props.ssrFallback ?? null);\n  }\n\n  const hydrateProps: Record<string, unknown> = {\n    [HYDRATE_MARKER_ATTR]: componentName,\n    \"data-when\": when,\n  };\n  if (when === \"media\" && media !== undefined) hydrateProps[\"data-media\"] = media;\n  if (dataProps !== undefined) hydrateProps[PROPS_DATA_ATTR] = dataProps;\n  return makeWrapper(hydrateProps, props.children);\n}\n\n/**\n * Validate and resolve the `when` / `media` props together.\n *\n * - `when=\"media\"` without `media` → warn + fall back to `DEFAULT_WHEN`.\n * - `media` without `when=\"media\"` → warn-and-ignore; `media` is dropped.\n */\nfunction resolveMediaProps(props: IslandProps): { when: When; media: string | undefined } {\n  const when = resolveWhen(props.when);\n  const media = props.media;\n\n  if (when === \"media\" && !media) {\n    if (typeof process !== \"undefined\" && process.env && process.env[\"NODE_ENV\"] !== \"production\") {\n      // eslint-disable-next-line no-console\n      console.warn(\n        `[zfb] <Island when=\"media\"> requires the \\`media\\` prop (a CSS media query string). ` +\n          `Falling back to \"${DEFAULT_WHEN}\".`,\n      );\n    }\n    return { when: DEFAULT_WHEN, media: undefined };\n  }\n\n  if (media && when !== \"media\") {\n    if (typeof process !== \"undefined\" && process.env && process.env[\"NODE_ENV\"] !== \"production\") {\n      // eslint-disable-next-line no-console\n      console.warn(\n        `[zfb] The \\`media\\` prop is only used when \\`when=\"media\"\\`. ` +\n          `Current when=\"${when}\" — \\`media\\` will be ignored.`,\n      );\n    }\n    return { when, media: undefined };\n  }\n\n  return { when, media };\n}\n\n/**\n * Construct the wrapper element through the **automatic JSX runtime\n * factory**, called explicitly so this file stays plain `.ts` (no JSX\n * syntax).\n *\n * Why the explicit `jsx(...)` call rather than a hand-rolled\n * `{ type, props, key }` object literal: a plain literal is only valid for\n * Preact (whose diff path / `preact-render-to-string` recognise a VNode by\n * `vnode.constructor === undefined`). React's renderer rejects such an\n * object as a child with \"Objects are not valid as a React child\"\n * (minified error #31) because a real React element carries\n * `$$typeof: Symbol.for(\"react.element\")`, which a literal cannot fake\n * portably. Calling `jsx` from `react/jsx-runtime` mints a real element:\n * in React mode it resolves natively; in Preact mode the engine rewrites\n * `react/jsx-runtime` → `preact/jsx-runtime` (bundler.rs ~2886), so the\n * Preact runtime mints the element. Same result the JSX `<div>` delegation\n * produced — but as plain `.ts`.\n *\n * Why `.ts` and NOT `.tsx`: esbuild rewrites a `.js` import specifier to\n * `.ts` but NOT to `.tsx`. The barrel `index.ts` imports `./island.js`;\n * when this file was `island.tsx`, source consumers (the dev `exports`\n * point at `src/*.ts`, e.g. the node-free template / smoke path) failed\n * with `Could not resolve \"./island.js\"`. The published `dist` worked\n * (tsc emits a real `island.js`), which masked the regression in\n * pnpm-pack/dist probes. Keeping this a `.ts` file makes the barrel resolve\n * `./island.js` → `./island.ts` from source everywhere, while tsc still\n * emits `dist/island.js` for the published package.\n *\n * The cast back to `IslandElement` keeps the public type tight; the\n * concrete element shape produced by the runtime is invisible to type\n * consumers.\n */\nfunction makeWrapper(props: Record<string, unknown>, children: unknown): IslandElement {\n  return jsx(\"div\", { ...props, children }) as unknown as IslandElement;\n}\n\n/**\n * Pull a component-name string out of a JSX child.\n *\n * Both Preact and React store rendered VNodes as plain objects whose\n * `.type` field is either:\n * - the component function (look at `displayName ?? name`),\n * - or the host element tag name as a string.\n *\n * If `children` is an array (multiple children), the first child with a\n * usable identity wins. This is intentional: the typical island shape is\n * `<Island><Foo /></Island>` (single child); when the caller wraps a\n * fragment-like list we still want a deterministic, debuggable name.\n *\n * Exported for tests; not re-exported from `index.ts`.\n */\nexport function captureComponentName(children: unknown): string {\n  if (Array.isArray(children)) {\n    for (const child of children) {\n      const name = nameFromSingle(child);\n      if (name) return name;\n    }\n    return ANONYMOUS_COMPONENT_NAME;\n  }\n  return nameFromSingle(children) || ANONYMOUS_COMPONENT_NAME;\n}\n\nfunction nameFromSingle(child: unknown): string {\n  if (!child || typeof child !== \"object\") return \"\";\n  const c = child as { type?: unknown };\n  const t = c.type;\n  if (typeof t === \"function\") {\n    const fn = t as { displayName?: unknown; name?: unknown };\n    if (typeof fn.displayName === \"string\" && fn.displayName) return fn.displayName;\n    if (typeof fn.name === \"string\" && fn.name) return fn.name;\n    return \"\";\n  }\n  if (typeof t === \"string\" && t) return t;\n  return \"\";\n}\n\n/**\n * Serialize the wrapped child's data props as a JSON string the runtime\n * can parse out of the `data-props` attribute on the Island marker div.\n *\n * Mirrors [`captureComponentName`]'s array handling: when `children` is\n * an array (multiple JSX siblings), the first child whose own props\n * yield a non-empty serialization wins. This keeps the \"first\n * identifiable child\" contract consistent across both attributes —\n * whatever the marker name points at is what the data-props payload\n * describes.\n *\n * Returns `undefined` (not `\"{}\"` and not `\"\"`) when no usable props\n * exist. The runtime's `readProps` already maps a missing attribute to\n * `{}`, so omitting the attribute keeps the SSR markup smaller and\n * preserves the invariant that the attribute, when present, always\n * parses to a non-empty record.\n *\n * Exported for tests; not re-exported from `index.ts`.\n */\nexport function captureSerializableProps(children: unknown): string | undefined {\n  if (Array.isArray(children)) {\n    for (const child of children) {\n      const json = propsFromSingle(child);\n      if (json !== undefined) return json;\n    }\n    return undefined;\n  }\n  return propsFromSingle(children);\n}\n\nfunction propsFromSingle(child: unknown): string | undefined {\n  if (!child || typeof child !== \"object\") return undefined;\n  const c = child as { props?: unknown };\n  const raw = c.props;\n  if (!raw || typeof raw !== \"object\" || Array.isArray(raw)) return undefined;\n\n  // Exclude `children` from the serialized payload: the SSR pass already\n  // emitted the rendered children into the DOM (the hydration target),\n  // and JSX child nodes are typically VNode trees with non-serializable\n  // shapes (functions, circular refs) that would either bloat the\n  // payload or throw inside JSON.stringify. The hydration runtime\n  // re-renders into the existing DOM, so it does not need the JSX\n  // children replayed through props.\n  //\n  // Note: JSON.stringify already silently drops function / symbol /\n  // undefined values from the output, so those don't need explicit\n  // pre-filtering here.\n  const propsRecord = raw as Record<string, unknown>;\n  let hasOwn = false;\n  const filtered: Record<string, unknown> = {};\n  for (const key of Object.keys(propsRecord)) {\n    if (key === \"children\") continue;\n    filtered[key] = propsRecord[key];\n    hasOwn = true;\n  }\n  if (!hasOwn) return undefined;\n\n  let json: string | undefined;\n  try {\n    json = JSON.stringify(filtered);\n  } catch {\n    // Circular references, BigInt, or any other non-serializable input\n    // — silently fall through (no `data-props`) rather than ship a\n    // partial payload. The runtime already handles the missing-attribute\n    // case by returning `{}` from `readProps`.\n    return undefined;\n  }\n\n  // JSON.stringify can also return `undefined` (when the top-level value\n  // serializes to nothing) or `\"{}\"` (when every key was a function /\n  // symbol / undefined and got dropped). Treat both as \"nothing useful\n  // to ship\" so the marker stays clean.\n  if (json === undefined || json === \"{}\") return undefined;\n  return json;\n}\n"]}
+{"version":3,"file":"island.js","sourceRoot":"","sources":["../src/island.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAG3D,OAAO,EAAE,YAAY,EAAE,WAAW,EAAa,MAAM,YAAY,CAAC;AAElE,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,MAAM,CAAC,MAAM,mBAAmB,GAAG,iBAAiB,CAAC;AACrD,MAAM,CAAC,MAAM,oBAAoB,GAAG,0BAA0B,CAAC;AAW/D,MAAM,UAAU,MAAM,CAAC,KAAkB;IACvC,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC;IACjD,OAAO,mBAAmB,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,WAAW,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;AAC7E,CAAC;AAED,SAAS,iBAAiB,CAAC,KAAkB;IAC3C,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACrC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;IAE1B,IAAI,IAAI,KAAK,OAAO,IAAI,CAAC,KAAK,EAAE,CAAC;QAC/B,IAAI,OAAO,OAAO,KAAK,WAAW,IAAI,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,YAAY,EAAE,CAAC;YAC9F,sCAAsC;YACtC,OAAO,CAAC,IAAI,CACV,sFAAsF;gBACpF,oBAAoB,YAAY,IAAI,CACvC,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IAClD,CAAC;IAED,IAAI,KAAK,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;QAC9B,IAAI,OAAO,OAAO,KAAK,WAAW,IAAI,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,YAAY,EAAE,CAAC;YAC9F,sCAAsC;YACtC,OAAO,CAAC,IAAI,CACV,+DAA+D;gBAC7D,iBAAiB,IAAI,gCAAgC,CACxD,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IACpC,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AACzB,CAAC","sourcesContent":["// Build-time Island wrapper for the owned zudo-react runtime.\nimport { ownedIslandBoundary } from \"./island-boundary.js\";\nimport type { VNode } from \"./jsx-types.js\";\nimport type { Description } from \"./zudo-react/description.js\";\nimport { DEFAULT_WHEN, resolveWhen, type When } from \"./types.js\";\n\nexport { resolveWhen } from \"./types.js\";\nexport const HYDRATE_MARKER_ATTR = \"data-zfb-island\";\nexport const SKIP_SSR_MARKER_ATTR = \"data-zfb-island-skip-ssr\";\n\nexport interface IslandProps {\n  when?: When;\n  media?: string;\n  ssrFallback?: VNode;\n  children?: VNode;\n}\n\nexport type IslandElement = Description;\n\nexport function Island(props: IslandProps): IslandElement {\n  const { when, media } = resolveMediaProps(props);\n  return ownedIslandBoundary(props.children, props.ssrFallback, when, media);\n}\n\nfunction resolveMediaProps(props: IslandProps): { when: When; media: string | undefined } {\n  const when = resolveWhen(props.when);\n  const media = props.media;\n\n  if (when === \"media\" && !media) {\n    if (typeof process !== \"undefined\" && process.env && process.env[\"NODE_ENV\"] !== \"production\") {\n      // eslint-disable-next-line no-console\n      console.warn(\n        `[zfb] <Island when=\"media\"> requires the \\`media\\` prop (a CSS media query string). ` +\n          `Falling back to \"${DEFAULT_WHEN}\".`,\n      );\n    }\n    return { when: DEFAULT_WHEN, media: undefined };\n  }\n\n  if (media && when !== \"media\") {\n    if (typeof process !== \"undefined\" && process.env && process.env[\"NODE_ENV\"] !== \"production\") {\n      // eslint-disable-next-line no-console\n      console.warn(\n        `[zfb] The \\`media\\` prop is only used when \\`when=\"media\"\\`. ` +\n          `Current when=\"${when}\" — \\`media\\` will be ignored.`,\n      );\n    }\n    return { when, media: undefined };\n  }\n\n  return { when, media };\n}\n"]}

package/dist/jsx-types.d.ts

@@ -1,46 +1,10 @@
-/**
- * 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.
- */
+/** Opaque description-shaped object accepted at the SDK boundary. */
 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, a
- * structured VNode object, or a bare `object`.
- *
- * This union covers every value both Preact and React treat as valid
- * `children`. The bare `object` member is required to make Preact's
- * `ComponentChildren` / `VNode<{}>` assignable without casts — Preact's own
- * `ComponentChild` uses the same widening pattern. The loosening is safe
- * because all SDK runtime code duck-types `unknown` at the boundary
- * (island.ts, content.ts) and the Rust pipeline is type-erased.
- *
- * Importantly, the union 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.
- *
- * **Name-collision note for Preact consumers:** if your file already has
- * `import { VNode } from "preact"`, use a qualifier on the zfb import:
- * `import type { VNode as ZfbVNode } from "@takazudo/zfb"`.
- */
+/** Broad authored child input; the owned renderer validates actual children. */
 export type VNode = string | number | boolean | null | undefined | bigint | VNodeArray | VNodeObject | object;
 export interface VNodeArray extends ReadonlyArray<VNode> {
 }
-/** @deprecated Use `VNode` instead. */
-export type ReactNode = VNode;

package/dist/jsx-types.js

@@ -1,12 +1,5 @@
-// 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.
+// Structural input types used by SDK helpers that inspect authored children.
+// The owned Island boundary validates descriptions and component identity
+// at runtime before rendering.
 export {};
 //# sourceMappingURL=jsx-types.js.map

package/dist/jsx-types.js.map

@@ -1 +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","sourcesContent":["// Lightweight ambient JSX types so the public Island wrapper does not\n// hard-depend on either preact or react as a runtime/types dependency.\n//\n// BCI-4: `IslandProps.children` is now typed as `VNode` (a structural union)\n// rather than the old `ReactNode` alias, so non-React frameworks can\n// implement `IslandProps` without any React type dependency at the type level.\n//\n// Both Preact and React's `children` accept this structural union; the build\n// is type-erased so the actual rendering happens in the user's app under\n// whichever framework adapter they chose.\n\n/**\n * Structural JSX element (VNode). Framework-agnostic: both Preact and React\n * produce objects that satisfy this shape when a JSX element is rendered.\n *\n * The `props` bag may itself contain `children` (nested VNodes) as well as\n * HTML attribute values (strings, numbers, booleans). All fields are widened\n * to `unknown` so the type stays opaque to callers that don't know which\n * framework produced the value.\n *\n * `type` accepts BOTH function components (call signature) AND class\n * components (construct signature). Preact and React both expose\n * `ComponentType = FunctionComponent | ComponentClass`, and the JSX runtime\n * stores either on `.type`. Without the construct signature, valid Preact\n * `<MyComponent />` expressions fail to assign to `VNode` at the framework\n * boundary (e.g. inside `<Island>` children) — even though class components\n * are rare in modern Preact, the `ComponentType` union includes them.\n */\nexport type VNodeObject = {\n  readonly type: string | ((...args: unknown[]) => unknown) | (new (...args: unknown[]) => unknown);\n  readonly props: Readonly<Record<string, unknown>>;\n  readonly key: unknown;\n};\n\n/**\n * A renderable JSX node: a primitive, `null`, `undefined`, an array, a\n * structured VNode object, or a bare `object`.\n *\n * This union covers every value both Preact and React treat as valid\n * `children`. The bare `object` member is required to make Preact's\n * `ComponentChildren` / `VNode<{}>` assignable without casts — Preact's own\n * `ComponentChild` uses the same widening pattern. The loosening is safe\n * because all SDK runtime code duck-types `unknown` at the boundary\n * (island.ts, content.ts) and the Rust pipeline is type-erased.\n *\n * Importantly, the union does **not** reference any framework-specific type,\n * so packages that depend on `zfb` need not install a React / Preact `@types`\n * package to satisfy this type.\n *\n * **Name-collision note for Preact consumers:** if your file already has\n * `import { VNode } from \"preact\"`, use a qualifier on the zfb import:\n * `import type { VNode as ZfbVNode } from \"@takazudo/zfb\"`.\n */\nexport type VNode =\n  | string\n  | number\n  | boolean\n  | null\n  | undefined\n  | bigint\n  | VNodeArray\n  | VNodeObject\n  | object;\n\nexport interface VNodeArray extends ReadonlyArray<VNode> {}\n\n// Back-compat alias — `ReactNode` was the previous name; code inside this\n// package that has not been migrated yet can still refer to it. New code\n// should use `VNode` directly.\n/** @deprecated Use `VNode` instead. */\nexport type ReactNode = VNode;\n"]}
+{"version":3,"file":"jsx-types.js","sourceRoot":"","sources":["../src/jsx-types.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,0EAA0E;AAC1E,+BAA+B","sourcesContent":["// Structural input types used by SDK helpers that inspect authored children.\n// The owned Island boundary validates descriptions and component identity\n// at runtime before rendering.\n\n/** Opaque description-shaped object accepted at the SDK boundary. */\nexport type VNodeObject = {\n  readonly type: string | ((...args: unknown[]) => unknown) | (new (...args: unknown[]) => unknown);\n  readonly props: Readonly<Record<string, unknown>>;\n  readonly key: unknown;\n};\n\n/** Broad authored child input; the owned renderer validates actual children. */\nexport type VNode =\n  | string\n  | number\n  | boolean\n  | null\n  | undefined\n  | bigint\n  | VNodeArray\n  | VNodeObject\n  | object;\n\nexport interface VNodeArray extends ReadonlyArray<VNode> {}\n"]}

package/dist/plugins.d.ts

@@ -63,6 +63,16 @@ export type ZfbRouteManifest = {
 export type ZfbBuildHookContext = {
     /** Project root — the directory containing `zfb.config.ts`. */
     projectRoot: string;
+    /**
+     * Absolute directory for the plugin's opaque intermediates
+     * (`<scratch root>/plugins`; `<projectRoot>/.zfb-build/plugins` by
+     * default). It is not an importable route location: generated route
+     * modules placed here are not staged into the bundle. zfb does not
+     * create it, so `mkdir(scratchDir, { recursive: true })` and use a
+     * `<scratchDir>/<plugin-name>/` subdirectory. Under `--scratch-dir`,
+     * plugin isolation only holds if the plugin adopts this directory.
+     */
+    scratchDir: string;
     /** Resolved absolute path of the build output directory. */
     outDir: string;
     /** The full loaded `ZfbConfig` (data-only view). */
@@ -118,6 +128,16 @@ export type ZfbDevMiddlewareHandler = (req: ZfbDevMiddlewareRequest) => Promise<
  */
 export type ZfbDevMiddlewareContext = {
     projectRoot: string;
+    /**
+     * Absolute directory for the plugin's opaque intermediates
+     * (`<scratch root>/plugins`; `<projectRoot>/.zfb-build/plugins` by
+     * default). It is not an importable route location: generated route
+     * modules placed here are not staged into the bundle. zfb does not
+     * create it, so `mkdir(scratchDir, { recursive: true })` and use a
+     * `<scratchDir>/<plugin-name>/` subdirectory. Under `--scratch-dir`,
+     * plugin isolation only holds if the plugin adopts this directory.
+     */
+    scratchDir: string;
     config: import("./config.js").ZfbConfig;
     options: Record<string, unknown>;
     logger: ZfbPluginLogger;
@@ -150,6 +170,16 @@ export type ZfbPreviewMiddlewareHandler = (req: ZfbDevMiddlewareRequest) => Prom
  */
 export type ZfbPreviewMiddlewareContext = {
     projectRoot: string;
+    /**
+     * Absolute directory for the plugin's opaque intermediates
+     * (`<scratch root>/plugins`; `<projectRoot>/.zfb-build/plugins` by
+     * default). It is not an importable route location: generated route
+     * modules placed here are not staged into the bundle. zfb does not
+     * create it, so `mkdir(scratchDir, { recursive: true })` and use a
+     * `<scratchDir>/<plugin-name>/` subdirectory. Under `--scratch-dir`,
+     * plugin isolation only holds if the plugin adopts this directory.
+     */
+    scratchDir: string;
     config: import("./config.js").ZfbConfig;
     options: Record<string, unknown>;
     logger: ZfbPluginLogger;
@@ -258,6 +288,16 @@ export type ZfbSetupContext = {
     command: "build" | "dev" | "preview";
     /** Project root — the directory containing `zfb.config.ts`. */
     projectRoot: string;
+    /**
+     * Absolute directory for the plugin's opaque intermediates
+     * (`<scratch root>/plugins`; `<projectRoot>/.zfb-build/plugins` by
+     * default). It is not an importable route location: generated route
+     * modules placed here are not staged into the bundle. zfb does not
+     * create it, so `mkdir(scratchDir, { recursive: true })` and use a
+     * `<scratchDir>/<plugin-name>/` subdirectory. Under `--scratch-dir`,
+     * plugin isolation only holds if the plugin adopts this directory.
+     */
+    scratchDir: string;
     /** The full loaded `ZfbConfig` (data-only view). */
     config: import("./config.js").ZfbConfig;
     /** Plugin-specific options block, copied verbatim from `PluginConfig.options`. */