@takazudo/zfb 0.1.0-next.9 → 0.1.0-next.91

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 > **Newer releases:** see https://takazudomodular.com/pj/zudo-front-builder/docs/changelog/ for v0.1.0-next.5 and later. Entries below are historical (kept for npm readers).
 
+## Unreleased
+
+### New features
+
+**`VNode`, `VNodeArray`, `VNodeObject` exported from `"@takazudo/zfb"`** (#972):
+
+The structural JSX-node types are now part of the public API:
+
+```ts
+import type { VNode, VNodeArray, VNodeObject } from "@takazudo/zfb";
+```
+
+`VNode` now includes a bare `object` member (matching Preact's own `ComponentChild` design), making Preact's `ComponentChildren`, `VNode<Props>`, `JSX.Element`, and `JSX.Element[]` all assignable at `Island` input boundaries (`children` and `ssrFallback`) with zero `as unknown as` casts.
+
+**Name-collision caveat for Preact consumers:** if a consumer file already has `import { VNode } from "preact"`, use a qualified import to avoid the clash:
+
+```ts
+import type { VNode as ZfbVNode } from "@takazudo/zfb";
+```
+
+### Breaking changes (pre-1.0)
+
+**`linkValidation.allowExternal` removed** (#925):
+
+The `allowExternal` config knob has been removed. It was accepted but never did anything — external URL network validation is out of scope. Migration: delete `allowExternal` from your `linkValidation` config; external URLs continue to be silently skipped (unchanged runtime behaviour).
+
 ## 0.1.0-next.4
 
 ### Bug fixes

package/README.md

@@ -4,8 +4,8 @@
 
 The public SDK module for [zfb][zfb-site]: islands, content collections,
 pagination, config, plugins, and frontmatter helpers. User pages reach this
-package through the bare specifier `"zfb"` — the `zfb-render` runtime loader
-registers the source under that name at build time so user TSX can write:
+package through the bare specifier `"zfb"` — the build pipeline aliases that
+specifier to `@takazudo/zfb` so user TSX can write:
 
 ```tsx
 import { Island } from "zfb";
@@ -29,16 +29,22 @@ npm install @takazudo/zfb
 This package is the canonical TypeScript source for the `zfb` SDK
 surface. Today it covers:
 
-- `<Island when="visible|idle|load">` — JSX wrapper that marks a region
-  for client-side hydration.
+- `<Island when="visible|idle|load|media" media="...">` — JSX wrapper
+  that marks a region for client-side hydration. Passing `ssrFallback`
+  switches to the SSR-skip marker (`data-zfb-island-skip-ssr`).
 - `scheduleHydrate(target, when, fire)` — the runtime branching helper
   consumed by the hydration runtime.
+- `mountIslands(manifest)`, `mountNewIslands()`,
+  `cancelPendingIslands()`, and `unmountIslands(...)` — public island
+  lifecycle helpers used by the generated islands runtime and by the
+  client router after body swaps.
 - `When`, `WHEN_VALUES`, `DEFAULT_WHEN`, `isWhen`, `resolveWhen` — type
-  and runtime utilities pinning the spelling of the three modes.
-- `getCollection(name)`, `parseFrontmatter(raw)` — content collection
-  helpers exported from `zfb/content`. `parseFrontmatter` is part of the
-  public SDK surface so consumers can write custom content loaders that
-  reuse the v0 frontmatter parser without re-implementing it.
+  and runtime utilities pinning the spelling of the four modes.
+- `getCollection(name)`, `getEntry(name, slug)`, and
+  `parseFrontmatter(raw)` — content collection helpers exported from
+  `zfb/content`. `parseFrontmatter` is part of the public SDK surface so
+  consumers can write custom content loaders that reuse the v0
+  frontmatter parser without re-implementing it.
 - `defaultComponents` — eleven-entry per-element override map (`h2`, `h3`,
   `h4`, `p`, `a`, `strong`, `blockquote`, `ul`, `ol`, `table`, `code`)
   ported from zudo-doc's `htmlOverrides` convention. **`h1` is deliberately
@@ -53,12 +59,23 @@ surface. Today it covers:
 
   <entry.Content components={{ ...defaultComponents, h2: MyFancyH2 }} />
   ```
+- `mergeMdxComponents(globalSlot, perCall)` — precedence merge helper for
+  the MDX component map (`defaultComponents` < global slot < per-call
+  overrides).
 - `paginate(items, opts)`, plus `PaginatedPage<T>` / `PaginateRoute<T>` —
   exported from `zfb/paginate`.
 - `defineConfig(config)` — exported from `zfb/config` for the
   `zfb.config.ts` form (the recommended way to author a zfb project's
   configuration; the back-compat `zfb.config.json` form is still
   supported).
+- `definePlugin(plugin)` — identity helper exported from `zfb/plugins`
+  and the root barrel so plugin authors get typed lifecycle hooks without
+  changing runtime behavior.
+- `clientScript(name)` — SSR helper that returns the stable URL for a
+  named client-script asset.
+- `slugify(input)` and `SlugAllocator` — exported from the root barrel and
+  the `zfb/slugify` subpath for heading-id parity with the Rust content
+  pipeline.
 
 The package is JSX-runtime-agnostic: the `Island` component does not
 import preact or react, so it works under either framework adapter
@@ -89,35 +106,61 @@ export default function Page() {
       <Island when="visible">
         <Counter />
       </Island>
+
+      {/* Hydrate when a CSS media query first matches. */}
+      <Island when="media" media="(max-width: 720px)">
+        <Counter />
+      </Island>
+
+      {/* Skip SSR for the heavy child and render a placeholder instead. */}
+      <Island when="idle" ssrFallback={<div>Loading…</div>}>
+        <Counter />
+      </Island>
     </>
   );
 }
 ```
 
-## The three `when=` modes
+## The four `when=` modes
 
-| `when`      | Trigger                                                         | Fallback                                       |
-| ----------- | --------------------------------------------------------------- | ---------------------------------------------- |
-| `"load"`    | Synchronous, immediate fire after registration. **Default.**    | n/a                                            |
-| `"idle"`    | `requestIdleCallback`                                           | `setTimeout(0)` when not available             |
-| `"visible"` | `IntersectionObserver`, threshold 0, first intersection only    | Immediate fire when `IntersectionObserver` is missing |
+| `when`      | Trigger                                                        | Fallback                                           |
+| ----------- | -------------------------------------------------------------- | -------------------------------------------------- |
+| `"load"`    | Synchronous, immediate fire after registration. **Default.**   | n/a                                                |
+| `"idle"`    | `requestIdleCallback`                                         | `setTimeout(0)` when not available                 |
+| `"visible"` | `IntersectionObserver`, threshold 0, first intersection only   | Immediate fire when `IntersectionObserver` is missing |
+| `"media"`   | `matchMedia(media)`, first matching change only                | Immediate fire when `matchMedia` or `media` is missing |
 
 Unknown values produce a `console.warn` in development builds and fall
 back to `"load"`.
 
+`when="media"` requires a `media` prop containing a CSS media query
+string. Supplying `media` with any other `when` value is ignored and
+warns in development builds.
+
 ## Build-time output
 
-The wrapper is intentionally type-erased at the JSX boundary. At the
-call site, `<Island when="visible">{children}</Island>` renders as:
+The wrapper is intentionally type-erased at the JSX boundary. It reads
+the wrapped child's JSX type identity (`displayName`, then `name`, then
+host tag name) and writes the component name immediately. At the call
+site, `<Island when="visible"><Counter count={1} /></Island>` renders as:
 
 ```html
-<div data-zfb-island data-when="visible"><!-- children --></div>
+<div data-zfb-island="Counter" data-when="visible" data-props='{"count":1}'>
+  <!-- rendered child output -->
+</div>
 ```
 
-The `data-zfb-island` attribute is empty here. The hydration emit step
-in the `zfb-render` runtime walks rendered HTML and replaces it with
-`data-zfb-island="ComponentName"` so the client-side hydration runtime
-can look up the right module to call.
+`data-props` carries the wrapped child's serializable own props across
+the SSR-to-hydration boundary. The wrapper omits `children`, omits the
+attribute entirely when there is no useful props payload, and the runtime
+falls back to `{}` when the attribute is missing or malformed.
+
+When `ssrFallback` is supplied, the heavy child is not rendered at SSR
+time. The wrapper writes `data-zfb-island-skip-ssr="ComponentName"`
+instead of `data-zfb-island`, still includes `data-when` / `data-media`
+and `data-props` when applicable, and renders the fallback markup inside
+the wrapper. The client runtime treats that marker as a render target
+rather than a hydration target.
 
 ## Runtime helper
 
@@ -125,7 +168,13 @@ The hydration runtime imports (or inlines) `scheduleHydrate` from this
 package:
 
 ```ts
-import { scheduleHydrate } from "@takazudo/zfb/runtime";
+import {
+  scheduleHydrate,
+  mountIslands,
+  mountNewIslands,
+  cancelPendingIslands,
+  unmountIslands,
+} from "@takazudo/zfb/runtime";
 
 for (const el of document.querySelectorAll<HTMLElement>("[data-zfb-island]")) {
   const when = el.getAttribute("data-when") ?? "load";
@@ -137,6 +186,15 @@ for (const el of document.querySelectorAll<HTMLElement>("[data-zfb-island]")) {
 if hydration has not fired yet. After firing, calling `cancel` is a
 no-op.
 
+`mountIslands(manifest)` captures the generated island manifest and
+mounts both hydrated markers (`data-zfb-island`) and SSR-skip markers
+(`data-zfb-island-skip-ssr`). `mountNewIslands()` re-walks the current
+document after a client-router body swap using that captured manifest.
+`cancelPendingIslands()` cancels deferred `idle` / `visible` / `media`
+schedules before a swap, and `unmountIslands(root, incomingBody)` runs
+framework cleanup for discarded islands while preserving matching
+`data-zfb-transition-persist` islands.
+
 ## Markdown / GFM config
 
 `ZfbConfig.markdown.gfm` controls which GitHub-Flavored-Markdown

package/bin/detect-musl.mjs

@@ -0,0 +1,55 @@
+// Extracted from zfb.mjs so the detection decision can be unit-tested
+// without triggering zfb.mjs's top-level exec/spawn side effects. Pure and
+// dependency-injectable: production callers can omit every option.
+import { readdirSync } from "node:fs";
+
+const MUSL_LOADER_DIR = "/lib";
+const MUSL_LOADER_PREFIX = "ld-musl-";
+
+// True if a musl dynamic loader file is present (e.g. Alpine's
+// /lib/ld-musl-x86_64.so.1). Reading the directory and matching the prefix
+// covers every arch's loader filename with one probe instead of hardcoding
+// an existsSync path per arch. Mirrors the loader-file probe used by the
+// widely-adopted `detect-libc` npm package.
+function hasMuslLoaderFile(readdirSyncFn) {
+  try {
+    return readdirSyncFn(MUSL_LOADER_DIR).some((name) => name.startsWith(MUSL_LOADER_PREFIX));
+  } catch {
+    return false;
+  }
+}
+
+function defaultGetReport() {
+  return process.report?.getReport?.();
+}
+
+// True if Node's process.report exposes a glibc runtime version. glibc-built
+// Node populates header.glibcVersionRuntime; musl-built Node does not. Used
+// only as a fallback signal when the loader-file probe above is inconclusive.
+function hasGlibcVersionRuntime(getReportFn) {
+  try {
+    return Boolean(getReportFn()?.header?.glibcVersionRuntime);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Detects musl libc (e.g. Alpine) on Linux, where the gnu-built platform
+ * binary would otherwise fail with an opaque dynamic-loader exec error
+ * instead of a clear "not supported" message. Always returns false on
+ * non-linux platforms (darwin, win32) — zero behavior change there.
+ */
+export function detectMuslLinux({
+  platform = process.platform,
+  readdirSyncFn = readdirSync,
+  getReportFn = defaultGetReport,
+} = {}) {
+  if (platform !== "linux") return false;
+  // The glibc runtime report is authoritative when present: a Node process
+  // that reports a glibc version is definitely glibc-linked and will work,
+  // regardless of an unrelated musl loader file sitting on the filesystem
+  // (e.g. a `musl` package installed on Debian/Ubuntu for other reasons).
+  if (hasGlibcVersionRuntime(getReportFn)) return false;
+  return hasMuslLoaderFile(readdirSyncFn);
+}

package/bin/zfb.mjs

@@ -1,10 +1,16 @@
 #!/usr/bin/env node
 // Followed biome's pattern: pure os/cpu lookup → resolve platform package → spawn binary.
 // See: https://github.com/biomejs/biome (packages/js/biome/bin/biome.mjs reference)
+// Divergence from biome: async spawn + signal forwarding instead of spawnSync.
+// biome is a short-lived CLI, but `zfb dev` is a long-running server — without
+// forwarding, SIGTERM to the wrapper orphans the native binary (PPID 1) and
+// leaves the dev-server port bound (issue #873).
 import { existsSync } from "node:fs";
-import { spawnSync } from "node:child_process";
+import { spawn } from "node:child_process";
 import { createRequire } from "node:module";
+import { constants as osConstants } from "node:os";
 import { join } from "node:path";
+import { detectMuslLinux } from "./detect-musl.mjs";
 
 const require = createRequire(import.meta.url);
 
@@ -27,6 +33,18 @@ if (!pkg) {
   process.exit(1);
 }
 
+// The gnu-built binary above matches on os/cpu but not on libc: an
+// Alpine/musl-libc Linux install passes the os/cpu check yet would still
+// fail to exec, with a raw, confusing dynamic-loader error. Detect and fail
+// with a clear message before attempting to resolve/spawn the binary.
+if (detectMuslLinux()) {
+  console.error(
+    "[zfb] musl/Alpine is not supported yet — no @takazudo/zfb-linux-*-musl package exists.\n" +
+      "      Use a glibc-based Linux image (e.g. Debian/Ubuntu) instead of Alpine.",
+  );
+  process.exit(1);
+}
+
 let binPath;
 try {
   // Resolve the platform package's package.json to get the install directory.
@@ -57,26 +75,61 @@ if (!existsSync(binPath)) {
   process.exit(1);
 }
 
-const result = spawnSync(binPath, process.argv.slice(2), { stdio: "inherit" });
+const child = spawn(binPath, process.argv.slice(2), { stdio: "inherit" });
 
-// Surface spawn errors that spawnSync stores in result.error rather than
-// propagating to stderr. Without this, a 0644 binary (EACCES) is silently
-// swallowed and the process exits with code 1 and no message — making it
-// impossible for the user to diagnose a corrupted/incomplete npm install.
-// (Issue #447 / #441 — pnpm publish strips the executable bit.)
-if (result.error) {
-  if (result.error.code === "EACCES") {
+// Forward termination signals to the child. Supervisors (concurrently
+// --kill-others, Playwright webServer teardown, timeout(1), CI runners)
+// signal only the wrapper; without forwarding, the native server survives
+// with PPID 1 and keeps its port bound. Terminal Ctrl+C already signals the
+// whole foreground group, so the child may receive SIGINT twice — the native
+// binary treats repeated signals as the same shutdown request.
+// SIGHUP is POSIX-only: on Windows child.kill("SIGHUP") throws (libuv only
+// emulates SIGINT/SIGTERM/SIGKILL/SIGQUIT), and the OS tears down console
+// processes on window close anyway.
+const forwardedSignals =
+  process.platform === "win32" ? ["SIGINT", "SIGTERM"] : ["SIGINT", "SIGTERM", "SIGHUP"];
+const signalForwarders = new Map();
+for (const sig of forwardedSignals) {
+  const forward = () => child.kill(sig);
+  signalForwarders.set(sig, forward);
+  process.on(sig, forward);
+}
+
+// Surface spawn failures clearly. Without this, a 0644 binary (EACCES) is
+// silently swallowed and the process exits with code 1 and no message —
+// making it impossible for the user to diagnose a corrupted/incomplete npm
+// install. (Issue #447 / #441 — pnpm publish strips the executable bit.)
+child.on("error", (error) => {
+  if (error.code === "EACCES") {
     process.stderr.write(
       `[zfb] binary is not executable; was the install corrupt?\n` +
         `      ${binPath}\n` +
         `      Try reinstalling: npm install --include=optional\n`,
     );
   } else {
-    process.stderr.write(
-      `[zfb] failed to spawn binary: ${result.error.message}\n` + `      ${binPath}\n`,
-    );
+    process.stderr.write(`[zfb] failed to spawn binary: ${error.message}\n` + `      ${binPath}\n`);
   }
   process.exit(1);
-}
+});
 
-process.exit(result.status ?? 1);
+child.on("exit", (code, signal) => {
+  if (signal) {
+    // Re-raise the child's termination signal on ourselves so the caller
+    // sees the real cause of death (e.g. WIFSIGNALED), not a plain exit code.
+    // Remove our forwarding listener first or it would swallow the re-raise.
+    const forward = signalForwarders.get(signal);
+    if (forward) {
+      process.off(signal, forward);
+    }
+    try {
+      process.kill(process.pid, signal);
+    } catch {
+      // Signal cannot be re-raised on this platform (Windows emulation).
+    }
+    // Reached only if the re-raised signal did not terminate us — fall back
+    // to the shell's 128+n convention for death-by-signal.
+    const signum = osConstants.signals[signal];
+    process.exit(signum ? 128 + signum : 1);
+  }
+  process.exit(code ?? 1);
+});

package/dist/client-script.d.ts

@@ -0,0 +1,54 @@
+/**
+ * SSR helper for referencing a client-script asset URL in a page or layout.
+ *
+ * ## Usage
+ *
+ * ```tsx
+ * import { clientScript } from "@takazudo/zfb";
+ *
+ * export default function MyPage() {
+ *   return (
+ *     <html>
+ *       <head>
+ *         <script type="module" src={clientScript("search-widget")} />
+ *       </head>
+ *       <body>…</body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ *
+ * ## How it works
+ *
+ * `clientScript(name)` returns the **stable URL** for the named client-script
+ * entry: `${base}/assets/client/<name>.js`. The production build pipeline
+ * (`ProductionAssetPipeline`) rewrites every occurrence of this stable URL in
+ * rendered HTML to the content-hashed equivalent
+ * (`/assets/client/<name>-<hash>.js`), so the hash never needs to be known at
+ * SSR time.
+ *
+ * The `base` prefix is read from `globalThis.__zfb?.base` (emitted by the
+ * bundler when at least one `*.client.*` file exists in the project). For
+ * root-mounted sites (`base` is absent or `"/"`), the prefix is the empty
+ * string and `clientScript("search-widget")` returns
+ * `"/assets/client/search-widget.js"`. For a sub-path deploy
+ * (`base="/foo/"`), it returns `"/foo/assets/client/search-widget.js"`.
+ *
+ * ## SSR-only note (v1)
+ *
+ * This is an SSR-time helper. Calling it in browser-executed code works but
+ * the base prefix (`globalThis.__zfb.base`) is currently not shipped to the
+ * browser — `clientScript()` will return the unprefixed stable URL
+ * (`/assets/client/<name>.js`) in that context. For the common use-case of
+ * rendering a `<script src>` tag at SSR time this is not a problem.
+ */
+/**
+ * Returns the base-prefixed stable public URL for the named client-script entry.
+ *
+ * `name` is the entry name (file stem minus `.client`, e.g. `"search-widget"`
+ * for `search-widget.client.ts`).
+ *
+ * The returned URL is `${base}/assets/client/<name>.js`. The production
+ * pipeline rewrites it to the hashed URL; dev serves the stable URL directly.
+ */
+export declare function clientScript(name: string): string;

package/dist/client-script.js

@@ -0,0 +1,67 @@
+/**
+ * SSR helper for referencing a client-script asset URL in a page or layout.
+ *
+ * ## Usage
+ *
+ * ```tsx
+ * import { clientScript } from "@takazudo/zfb";
+ *
+ * export default function MyPage() {
+ *   return (
+ *     <html>
+ *       <head>
+ *         <script type="module" src={clientScript("search-widget")} />
+ *       </head>
+ *       <body>…</body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ *
+ * ## How it works
+ *
+ * `clientScript(name)` returns the **stable URL** for the named client-script
+ * entry: `${base}/assets/client/<name>.js`. The production build pipeline
+ * (`ProductionAssetPipeline`) rewrites every occurrence of this stable URL in
+ * rendered HTML to the content-hashed equivalent
+ * (`/assets/client/<name>-<hash>.js`), so the hash never needs to be known at
+ * SSR time.
+ *
+ * The `base` prefix is read from `globalThis.__zfb?.base` (emitted by the
+ * bundler when at least one `*.client.*` file exists in the project). For
+ * root-mounted sites (`base` is absent or `"/"`), the prefix is the empty
+ * string and `clientScript("search-widget")` returns
+ * `"/assets/client/search-widget.js"`. For a sub-path deploy
+ * (`base="/foo/"`), it returns `"/foo/assets/client/search-widget.js"`.
+ *
+ * ## SSR-only note (v1)
+ *
+ * This is an SSR-time helper. Calling it in browser-executed code works but
+ * the base prefix (`globalThis.__zfb.base`) is currently not shipped to the
+ * browser — `clientScript()` will return the unprefixed stable URL
+ * (`/assets/client/<name>.js`) in that context. For the common use-case of
+ * rendering a `<script src>` tag at SSR time this is not a problem.
+ */
+/** Stable public-URL prefix for client-script entries, matching the Rust constant. */
+const CLIENT_SCRIPTS_URL_PREFIX = "/assets/client/";
+/**
+ * Returns the base-prefixed stable public URL for the named client-script entry.
+ *
+ * `name` is the entry name (file stem minus `.client`, e.g. `"search-widget"`
+ * for `search-widget.client.ts`).
+ *
+ * The returned URL is `${base}/assets/client/<name>.js`. The production
+ * pipeline rewrites it to the hashed URL; dev serves the stable URL directly.
+ */
+export function clientScript(name) {
+    // `globalThis.__zfb?.base` is set to the resolved base prefix by the
+    // bundler when the project has at least one `*.client.*` entry (#978).
+    // For root-mounted or no-base builds the value is `""`, yielding
+    // `/assets/client/<name>.js` as expected. The `?? ""` fallback handles
+    // the edge case where __zfb.base was not emitted (zero-script project,
+    // or a browser context where the slot was never populated).
+    const base = globalThis.__zfb;
+    const prefix = base?.base ?? "";
+    return `${prefix}${CLIENT_SCRIPTS_URL_PREFIX}${name}.js`;
+}
+//# sourceMappingURL=client-script.js.map

package/dist/client-script.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-script.js","sourceRoot":"","sources":["../src/client-script.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,sFAAsF;AACtF,MAAM,yBAAyB,GAAG,iBAAiB,CAAC;AAEpD;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,qEAAqE;IACrE,uEAAuE;IACvE,iEAAiE;IACjE,uEAAuE;IACvE,uEAAuE;IACvE,4DAA4D;IAC5D,MAAM,IAAI,GAAI,UAAsC,CAAC,KAAsC,CAAC;IAC5F,MAAM,MAAM,GAAG,IAAI,EAAE,IAAI,IAAI,EAAE,CAAC;IAChC,OAAO,GAAG,MAAM,GAAG,yBAAyB,GAAG,IAAI,KAAK,CAAC;AAC3D,CAAC","sourcesContent":["/**\n * SSR helper for referencing a client-script asset URL in a page or layout.\n *\n * ## Usage\n *\n * ```tsx\n * import { clientScript } from \"@takazudo/zfb\";\n *\n * export default function MyPage() {\n *   return (\n *     <html>\n *       <head>\n *         <script type=\"module\" src={clientScript(\"search-widget\")} />\n *       </head>\n *       <body>…</body>\n *     </html>\n *   );\n * }\n * ```\n *\n * ## How it works\n *\n * `clientScript(name)` returns the **stable URL** for the named client-script\n * entry: `${base}/assets/client/<name>.js`. The production build pipeline\n * (`ProductionAssetPipeline`) rewrites every occurrence of this stable URL in\n * rendered HTML to the content-hashed equivalent\n * (`/assets/client/<name>-<hash>.js`), so the hash never needs to be known at\n * SSR time.\n *\n * The `base` prefix is read from `globalThis.__zfb?.base` (emitted by the\n * bundler when at least one `*.client.*` file exists in the project). For\n * root-mounted sites (`base` is absent or `\"/\"`), the prefix is the empty\n * string and `clientScript(\"search-widget\")` returns\n * `\"/assets/client/search-widget.js\"`. For a sub-path deploy\n * (`base=\"/foo/\"`), it returns `\"/foo/assets/client/search-widget.js\"`.\n *\n * ## SSR-only note (v1)\n *\n * This is an SSR-time helper. Calling it in browser-executed code works but\n * the base prefix (`globalThis.__zfb.base`) is currently not shipped to the\n * browser — `clientScript()` will return the unprefixed stable URL\n * (`/assets/client/<name>.js`) in that context. For the common use-case of\n * rendering a `<script src>` tag at SSR time this is not a problem.\n */\n\n/** Stable public-URL prefix for client-script entries, matching the Rust constant. */\nconst CLIENT_SCRIPTS_URL_PREFIX = \"/assets/client/\";\n\n/**\n * Returns the base-prefixed stable public URL for the named client-script entry.\n *\n * `name` is the entry name (file stem minus `.client`, e.g. `\"search-widget\"`\n * for `search-widget.client.ts`).\n *\n * The returned URL is `${base}/assets/client/<name>.js`. The production\n * pipeline rewrites it to the hashed URL; dev serves the stable URL directly.\n */\nexport function clientScript(name: string): string {\n  // `globalThis.__zfb?.base` is set to the resolved base prefix by the\n  // bundler when the project has at least one `*.client.*` entry (#978).\n  // For root-mounted or no-base builds the value is `\"\"`, yielding\n  // `/assets/client/<name>.js` as expected. The `?? \"\"` fallback handles\n  // the edge case where __zfb.base was not emitted (zero-script project,\n  // or a browser context where the slot was never populated).\n  const base = (globalThis as Record<string, unknown>).__zfb as { base?: string } | undefined;\n  const prefix = base?.base ?? \"\";\n  return `${prefix}${CLIENT_SCRIPTS_URL_PREFIX}${name}.js`;\n}\n"]}