@takazudo/zfb 0.1.0-next.10

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+> **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).
+
+## 0.1.0-next.4
+
+### Bug fixes
+
+**Binary executable bit + launcher EACCES** (#441, #444 §1):
+
+- #441: The bundled `bin/zfb.mjs` launcher was missing its executable bit in the published tarball, causing `zfb: command not found` after `npm install -g`.
+- #444 §1: Companion fix ensuring the per-platform native binary receives its executable bit correctly on POSIX systems.
+
+**`--version` stamping** (#445, #444 §2):
+
+- #445: `zfb --version` printed `0.0.0` instead of the actual release version; the binary is now stamped with `ZFB_RELEASE_VERSION` at build time.
+- #444 §2: Ensures the version reported by `--version` matches the npm package version for all platforms.
+
+**`paths()` worker / `zfb/content` snapshot flow** (#442):
+
+- #442: Fixed a race in the content-snapshot flow where `paths()` could be invoked before the worker finished writing the snapshot, causing intermittent empty-route tables.
+
+**`@/` tsconfig path-alias regression** (#443):
+
+- #443: The `@/` TypeScript path alias was dropped during the build pipeline refactor in 0.1.0-next.3, breaking imports that relied on the alias in user projects.
+
+**`create-zfb` scaffold dist-tag** (#343):
+
+- #343: `npm create zfb@latest` was resolving the wrong dist-tag on the first install; scaffolded projects now pin to the exact CLI version (`=<ver>` rather than `^<ver>`) to prevent silent downgrade once the stable release lands.
+
+## 0.1.0-next.1
+
+Initial public prerelease on npm.
+
+- Rust-built static-site engine, distributed per-platform via npm optional-deps.
+- TypeScript SDK with subpath exports for `runtime`, `content`, `paginate`, `config`, `plugins`, `frontmatter`.
+- Bundled `basic-blog` template via `zfb new my-site` / `npm create zfb@latest my-site`.
+
+## Behavior change
+
+**Extra-dirs pass now honors `.gitignore`** (Fix B for #428, closes #433):
+
+- Gitignored top-level directories (e.g. `worktrees/`) are no longer copied into the shadow build tree. Previously the bundler would unconditionally materialise every non-infrastructure top-level directory.
+- Global git ignore (`~/.config/git/ignore`) and hidden-directory rules now apply at the top level in addition to `.gitignore`.
+- **Negation caveat:** if your `.gitignore` contains a pattern like `!worktrees/keep/` to opt a sub-path back in, the negation is silently ignored by this pass. The extra-dirs walk operates whole-directory-or-nothing at `max_depth=1`; the parent directory is excluded before the negation can apply. Consumers relying on negated sub-path opt-ins in an otherwise-excluded directory will need an alternative arrangement (e.g. move the directory outside the gitignored subtree).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Takeshi Takatsudo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,207 @@
+# @takazudo/zfb
+
+> Rust-built static-site engine for Astro and Next.js users — millisecond rebuilds, single binary.
+
+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:
+
+```tsx
+import { Island } from "zfb";
+```
+
+Full documentation: <https://takazudomodular.com/pj/zudo-front-builder/>.
+Source: <https://github.com/Takazudo/zudo-front-builder>.
+
+[zfb-site]: https://takazudomodular.com/pj/zudo-front-builder/
+
+## Install
+
+```sh
+npm install @takazudo/zfb
+# or: pnpm add @takazudo/zfb
+# or: yarn add @takazudo/zfb
+```
+
+## What lives here
+
+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.
+- `scheduleHydrate(target, when, fire)` — the runtime branching helper
+  consumed by the hydration runtime.
+- `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.
+- `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
+  omitted** because page titles render `<h1>` from frontmatter. Each entry
+  is a thin passthrough and is also exported as a named const
+  (`ContentParagraph`, `ContentLink`, …) so consumers can tree-shake-import a
+  single override. Spread into a `components` prop to compose with custom
+  overrides:
+
+  ```tsx
+  import { defaultComponents } from "zfb";
+
+  <entry.Content components={{ ...defaultComponents, h2: MyFancyH2 }} />
+  ```
+- `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).
+
+The package is JSX-runtime-agnostic: the `Island` component does not
+import preact or react, so it works under either framework adapter
+without bundling the wrong runtime.
+
+## Usage
+
+```tsx
+import { Island } from "zfb";
+import { Counter } from "../components/Counter.tsx"; // a "use client" component
+
+export default function Page() {
+  return (
+    <>
+      <h1>Welcome</h1>
+
+      {/* Hydrate immediately on page load (default). */}
+      <Island>
+        <Counter />
+      </Island>
+
+      {/* Hydrate during the next idle callback. */}
+      <Island when="idle">
+        <Counter />
+      </Island>
+
+      {/* Hydrate only when the island first scrolls into view. */}
+      <Island when="visible">
+        <Counter />
+      </Island>
+    </>
+  );
+}
+```
+
+## The three `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 |
+
+Unknown values produce a `console.warn` in development builds and fall
+back to `"load"`.
+
+## Build-time output
+
+The wrapper is intentionally type-erased at the JSX boundary. At the
+call site, `<Island when="visible">{children}</Island>` renders as:
+
+```html
+<div data-zfb-island data-when="visible"><!-- children --></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.
+
+## Runtime helper
+
+The hydration runtime imports (or inlines) `scheduleHydrate` from this
+package:
+
+```ts
+import { scheduleHydrate } from "@takazudo/zfb/runtime";
+
+for (const el of document.querySelectorAll<HTMLElement>("[data-zfb-island]")) {
+  const when = el.getAttribute("data-when") ?? "load";
+  scheduleHydrate(el, when, () => hydrateOne(el));
+}
+```
+
+`scheduleHydrate` returns a `cancel` function that aborts the schedule
+if hydration has not fired yet. After firing, calling `cancel` is a
+no-op.
+
+## Markdown / GFM config
+
+`ZfbConfig.markdown.gfm` controls which GitHub-Flavored-Markdown
+constructs the MDX parser recognises. The field accepts three shapes:
+
+1. **Shorthand boolean** — turn every GFM construct on or off in one
+   step. Use this when you want the full GFM surface.
+
+   ```ts
+   // zfb.config.ts
+   import { defineConfig } from "zfb/config";
+
+   export default defineConfig({
+     markdown: {
+       gfm: true, // strikethrough + table + autolink-literal + task-list-item + footnote-definition
+     },
+   });
+   ```
+
+2. **Partial object** — toggle individual constructs. Fields you omit
+   fall back to the conservative default (`strikethrough: true`,
+   `table: true`, everything else off).
+
+   ```ts
+   // zfb.config.ts
+   import { defineConfig } from "zfb/config";
+
+   export default defineConfig({
+     markdown: {
+       gfm: {
+         strikethrough: true,
+         table: true,
+         autolinkLiteral: false,    // explicit opt-out
+         taskListItem: false,
+         footnoteDefinition: false,
+       },
+     },
+   });
+   ```
+
+3. **Omitted entirely** — the parser uses the conservative default.
+   `~~text~~` parses as `<del>text</del>` and pipe tables render as
+   `<table>`; every other GFM construct stays off.
+
+   ```ts
+   export default defineConfig({
+     // no `markdown` field — strikethrough + table on, everything else off
+   });
+   ```
+
+The five constructs you can toggle are: `strikethrough`, `table`,
+`autolinkLiteral`, `taskListItem`, `footnoteDefinition`.
+
+Projects that previously relied on raw `~~text~~` passing through as
+literal characters should set `markdown: { gfm: { strikethrough: false } }`
+or `markdown: { gfm: false }` to restore the old behaviour.
+
+## Tests
+
+```sh
+pnpm --filter @takazudo/zfb test
+```
+
+The tests run under [vitest][vitest] with [happy-dom][happy-dom] as the
+DOM implementation; no real browser is required.
+
+[vitest]: https://vitest.dev/
+[happy-dom]: https://github.com/capricorn86/happy-dom

package/bin/zfb.mjs

@@ -0,0 +1,82 @@
+#!/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)
+import { existsSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+
+const require = createRequire(import.meta.url);
+
+// Map of os-cpu keys to the corresponding optional platform package name.
+// On Windows, npm generates zfb.cmd / zfb.ps1 wrappers from the bin field;
+// the shebang above is used on Unix only.
+const platformPackages = {
+  "darwin-arm64": "@takazudo/zfb-darwin-arm64",
+  "darwin-x64": "@takazudo/zfb-darwin-x64",
+  "linux-arm64": "@takazudo/zfb-linux-arm64-gnu",
+  "linux-x64": "@takazudo/zfb-linux-x64-gnu",
+  "win32-x64": "@takazudo/zfb-win32-x64-msvc",
+};
+
+const key = `${process.platform}-${process.arch}`;
+const pkg = platformPackages[key];
+
+if (!pkg) {
+  console.error(`[zfb] unsupported platform: ${key}`);
+  process.exit(1);
+}
+
+let binPath;
+try {
+  // Resolve the platform package's package.json to get the install directory.
+  const pkgJsonPath = require.resolve(`${pkg}/package.json`);
+  const pkgDir = pkgJsonPath.replace(/[\\/]package\.json$/, "");
+  const binName = process.platform === "win32" ? "zfb.exe" : "zfb";
+  binPath = join(pkgDir, binName);
+} catch {
+  console.error(
+    `[zfb] platform binary not installed: ${pkg}\n` +
+      "      Some installers skip optionalDependencies. Reinstall with full deps,\n" +
+      "      e.g. `npm install --include=optional` or `pnpm install` without\n" +
+      "      `--no-optional` / `--ignore-scripts`.",
+  );
+  process.exit(1);
+}
+
+// Explicit existence check: the package directory may be linked (e.g. via pnpm
+// workspace) even before the Wave-5 workflow places the real binary. Without
+// this guard, spawnSync would silently ENOENT instead of printing a clear error.
+if (!existsSync(binPath)) {
+  console.error(
+    `[zfb] platform binary not installed: ${pkg}\n` +
+      "      Some installers skip optionalDependencies. Reinstall with full deps,\n" +
+      "      e.g. `npm install --include=optional` or `pnpm install` without\n" +
+      "      `--no-optional` / `--ignore-scripts`.",
+  );
+  process.exit(1);
+}
+
+const result = spawnSync(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") {
+    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.exit(1);
+}
+
+process.exit(result.status ?? 1);