@takazudo/zfb 0.1.0-next.6 → 0.1.0-next.60

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/bin/zfb.mjs

@@ -1,9 +1,14 @@
 #!/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";
 
 const require = createRequire(import.meta.url);
@@ -57,26 +62,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,55 @@
+/**
+ * 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;
+//# sourceMappingURL=client-script.d.ts.map

package/dist/client-script.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-script.d.ts","sourceRoot":"","sources":["../src/client-script.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAKH;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAUjD"}

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