@takazudo/zfb 0.1.0-next.2

package/dist/content.d.ts

@@ -0,0 +1,231 @@
+import { parseFrontmatter } from "./frontmatter.js";
+import type { ParsedFrontmatter } from "./frontmatter.js";
+import type { VNode } from "./jsx-types.js";
+export { parseFrontmatter };
+export type { ParsedFrontmatter };
+/**
+ * One entry in an embedded content snapshot. Mirrors
+ * `crates/zfb-content/src/content_bridge.rs::EntrySnapshot`. Re-exported
+ * by `@takazudo/zfb-runtime/snapshot` for the runtime-side bundle. See
+ * that module for field-by-field documentation.
+ */
+export interface SnapshotEntry {
+    readonly slug: string;
+    readonly frontmatter: unknown;
+    readonly body: string;
+    readonly module_specifier: string;
+    readonly rel_path: string;
+}
+/**
+ * Point-in-time snapshot of every configured collection. Mirrors
+ * `crates/zfb-content/src/content_bridge.rs::ContentSnapshot`.
+ */
+export interface Snapshot {
+    readonly collections: Readonly<Record<string, readonly SnapshotEntry[]>>;
+}
+/**
+ * Register a [`Snapshot`] so [`getCollection`] resolves from memory.
+ *
+ * Pass `undefined` to clear (used by tests that need to restore the v0
+ * filesystem path between runs). Idempotent: the latest call wins.
+ */
+export declare function setContentSnapshot(snapshot: Snapshot | undefined): void;
+/**
+ * Read the currently-installed [`Snapshot`], or `undefined` if none is
+ * registered. Exposed mostly for tests; production callers should not
+ * need to introspect the bridge state.
+ */
+export declare function getContentSnapshot(): Snapshot | undefined;
+/**
+ * Props accepted by an entry's [`CollectionEntry.Content`] component.
+ *
+ * `components` mirrors Astro's `<Content components={...}>` contract:
+ * a flat record of element-name → override component (e.g. `{ h1: MyH1 }`).
+ * The default-components convention ships from `zfb`'s root export
+ * (`defaultComponents`, lands in Sub 6) and users compose with their own
+ * via `{ ...defaultComponents, ...mine }`.
+ */
+export interface ContentProps {
+    /** Element-name → override component map. Optional. */
+    components?: Record<string, unknown>;
+}
+/**
+ * Public JSX-element shape returned by [`CollectionEntry.Content`].
+ *
+ * Matches the structural shape that both Preact's and React's `jsx-runtime`
+ * accept on either side of the boundary, mirroring the Island wrapper's
+ * approach. Consumers should treat this as opaque — its only contract is
+ * "renderable JSX value".
+ *
+ * Aliased as `JSX.Element` in the field signature: the JS runtime is
+ * type-erased and the actual VNode shape is supplied by the framework
+ * adapter at evaluation time.
+ */
+export type ContentElement = {
+    readonly type: string | ((...args: unknown[]) => unknown);
+    readonly props: Readonly<Record<string, unknown>>;
+    readonly key: unknown;
+};
+/**
+ * Generic shape returned for one entry in a content collection. The `data`
+ * field carries parsed frontmatter, typed by the caller via the generic
+ * parameter.
+ */
+export type CollectionEntry<T = Record<string, unknown>> = {
+    /** Filename without `.md` extension. Stable across runs. */
+    slug: string;
+    /** Parsed frontmatter. */
+    data: T;
+    /** Raw markdown body (frontmatter stripped). */
+    body: string;
+    /**
+     * Stable module specifier used as the bridge lookup key. Format:
+     * `mdx://<collection>/<slug>` (no hash component — the JS stub does
+     * not compile MDX, so it has no body hash to attach; the production
+     * Rust-side `zfb-content::collection::Entry::module_specifier` adds a
+     * `#<hash>` suffix and the bridge is responsible for matching either
+     * form against its registered components).
+     *
+     * This field is part of the v0+ JS surface so the bridge has something
+     * deterministic to key on without consulting per-call state.
+     */
+    module_specifier: string;
+    /**
+     * Renderable component for this entry.
+     *
+     * **Bridge contract.** At call time, `Content` consults
+     * `globalThis.__zfb?.content?.get(entry.module_specifier)`. If the
+     * bridge is present and returns a function, that function is invoked
+     * with `props` and its result returned verbatim.
+     *
+     * **Fallback.** Outside the renderer (unit tests, dev sandboxes, or any
+     * environment where `globalThis.__zfb.content.get` is absent or returns
+     * `undefined`), `Content` returns a JSX-shaped element rendering the
+     * raw markdown body inside a `<pre data-zfb-content-fallback>` block,
+     * with a leading `[zfb fallback render]` marker line so the visual
+     * distinction survives unstyled environments. The marker is also a
+     * grep target for "did the production renderer not run?" diagnostics.
+     *
+     * **Typed signature.** Returns `ContentElement` (a structural alias for
+     * `JSX.Element`) so consumers can drop `<entry.Content components={...} />`
+     * into both React and Preact JSX without per-framework type setup.
+     *
+     * @example
+     *   const post = (await getCollection("blog"))[0];
+     *   return <post.Content components={{ ...defaultComponents, h1: MyH1 }} />;
+     */
+    Content: (props: ContentProps) => ContentElement;
+};
+/**
+ * Load every `*.md` file in the named collection. Files starting with `.`
+ * or that lack a `.md` extension are ignored.
+ *
+ * **ADR-004 contract: this function is synchronous.** TSX page modules
+ * call it from anywhere — top-level, inside a render body, inside a
+ * `useMemo` — and SSR completes in a single pass without yielding. The
+ * snapshot path returns from memory; the filesystem fallback uses sync
+ * `node:fs` APIs so the surface stays unified. (The legacy async
+ * implementation was an oversight — the ADR predates it; SSG paths
+ * always saw a Promise where ADR-004 says they should see an array,
+ * which is why migrations from Astro tripped on `getCollection().filter
+ * is not a function`.)
+ *
+ * @example
+ *   const posts = getCollection<{ title: string; date: string }>("blog");
+ */
+export declare function getCollection<T = Record<string, unknown>>(name: string): CollectionEntry<T>[];
+/**
+ * @internal
+ *
+ * Convert a `path.relative()` result into a forward-slash-separated
+ * slug with the trailing `.md` extension stripped.
+ *
+ * Slugs are URL-flavored identifiers, not filesystem paths — they
+ * MUST use `/` regardless of the host OS so a nested entry like
+ * `2024/hello.md` produces the slug `2024/hello` on both POSIX and
+ * Windows. Without this normalisation, Windows callers would see
+ * `2024\hello`, which then leaks through to `module_specifier` and
+ * any URL the consumer derives from the slug.
+ *
+ * Exported solely so the unit test suite can pin the Windows
+ * behaviour without needing an actual Windows host. Do not depend on
+ * this from application code — name and signature may change.
+ */
+export declare function _relPathToSlug(relPath: string): string;
+/**
+ * Public JSX-element shape returned by every override in [`defaultComponents`].
+ *
+ * Mirrors [`ContentElement`] and [`IslandElement`]: a structural alias for
+ * `JSX.Element` so consumers can drop these overrides into both React and
+ * Preact JSX without per-framework type setup.
+ */
+export type ContentComponentElement = {
+    readonly type: string;
+    readonly props: Readonly<Record<string, unknown>>;
+    readonly key: unknown;
+};
+/**
+ * Props accepted by every default override. `children` and any extra
+ * attributes (`className`, `id`, `href`, …) are passed through verbatim
+ * to the underlying HTML element.
+ */
+export interface ContentComponentProps {
+    children?: VNode;
+    [key: string]: unknown;
+}
+/**
+ * `<h2>` passthrough override. Ported from zudo-doc's `HeadingH2`, stripped
+ * of styling — v0 ships pass-through behaviour; visual treatment is layered
+ * on by the consumer (or by a follow-up enhancement pass).
+ */
+export declare function ContentH2(props: ContentComponentProps): ContentComponentElement;
+/** `<h3>` passthrough override. See [`ContentH2`] for the contract. */
+export declare function ContentH3(props: ContentComponentProps): ContentComponentElement;
+/** `<h4>` passthrough override. See [`ContentH2`] for the contract. */
+export declare function ContentH4(props: ContentComponentProps): ContentComponentElement;
+/** `<p>` passthrough override. Mirrors zudo-doc's `ContentParagraph`. */
+export declare function ContentParagraph(props: ContentComponentProps): ContentComponentElement;
+/** `<a>` passthrough override. Mirrors zudo-doc's `ContentLink`. */
+export declare function ContentLink(props: ContentComponentProps): ContentComponentElement;
+/** `<strong>` passthrough override. Mirrors zudo-doc's `ContentStrong`. */
+export declare function ContentStrong(props: ContentComponentProps): ContentComponentElement;
+/** `<blockquote>` passthrough override. Mirrors zudo-doc's `ContentBlockquote`. */
+export declare function ContentBlockquote(props: ContentComponentProps): ContentComponentElement;
+/** `<ul>` passthrough override. Mirrors zudo-doc's `ContentUl`. */
+export declare function ContentUl(props: ContentComponentProps): ContentComponentElement;
+/** `<ol>` passthrough override. Mirrors zudo-doc's `ContentOl`. */
+export declare function ContentOl(props: ContentComponentProps): ContentComponentElement;
+/** `<table>` passthrough override. Mirrors zudo-doc's `ContentTable`. */
+export declare function ContentTable(props: ContentComponentProps): ContentComponentElement;
+/** `<code>` passthrough override. Mirrors zudo-doc's `ContentCode`. */
+export declare function ContentCode(props: ContentComponentProps): ContentComponentElement;
+/**
+ * Default per-element override map — eleven entries covering the markdown
+ * tags the zudo-doc convention overrides (`h2`, `h3`, `h4`, `p`, `a`,
+ * `strong`, `blockquote`, `ul`, `ol`, `table`, `code`).
+ *
+ * `h1` is intentionally absent: page titles render from frontmatter, per
+ * the zudo-doc convention.
+ *
+ * Spread into a `components` prop to compose with custom overrides:
+ *
+ * ```tsx
+ * import { defaultComponents } from "zfb";
+ *
+ * <entry.Content components={{ ...defaultComponents, h2: MyFancyH2 }} />
+ * ```
+ */
+export declare const defaultComponents: {
+    readonly h2: typeof ContentH2;
+    readonly h3: typeof ContentH3;
+    readonly h4: typeof ContentH4;
+    readonly p: typeof ContentParagraph;
+    readonly a: typeof ContentLink;
+    readonly strong: typeof ContentStrong;
+    readonly blockquote: typeof ContentBlockquote;
+    readonly ul: typeof ContentUl;
+    readonly ol: typeof ContentOl;
+    readonly table: typeof ContentTable;
+    readonly code: typeof ContentCode;
+};
+//# sourceMappingURL=content.d.ts.map

package/dist/content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content.d.ts","sourceRoot":"","sources":["../src/content.ts"],"names":[],"mappings":"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"}

package/dist/content.js

@@ -0,0 +1,449 @@
+// `zfb/content` — minimal v0 content collection loader.
+//
+// Reads `*.md` files from a content collection directory, parses YAML
+// frontmatter, and returns typed entries. This is a deliberately small
+// stub so the bundled basic-blog template can call `getCollection("blog")` today;
+// the production path lives in `crates/zfb-content` and will replace this
+// once the JS-runtime decision (ADR-001) lands and the renderer wires the
+// Rust pipeline back through to user code.
+//
+// Scope (v0):
+// - YAML-ish frontmatter only: `key: value`, plus `key:\n  - item` arrays.
+//   Quoted strings are unwrapped. ISO dates stay as strings.
+// - Body is the post content **after** the closing `---`, returned as raw
+//   text. This is intentionally NOT pre-rendered HTML: the markdown
+//   pipeline lives in the Rust crate and the JS stub does not duplicate
+//   it.
+// - Collection root is resolved from
+//   `process.env.ZFB_CONTENT_ROOT` (set by the dev/build pipeline), or
+//   `<cwd>/content` as a fallback for unit tests and direct invocation.
+//
+// TODO(zfb-content): swap this stub for the runtime-provided implementation
+// once the content engine ships end-to-end.
+import { parseFrontmatter } from "./frontmatter.js";
+// Re-export the parser surface so existing `zfb/content` consumers that
+// import `parseFrontmatter` / `ParsedFrontmatter` from the content
+// subpath keep working. The implementation now lives in `./frontmatter.ts`
+// (BCI-3 fs-free subpath) — this re-export is the bridge for callers
+// that have not migrated yet.
+export { parseFrontmatter };
+/**
+ * Module-level snapshot slot. `undefined` means "no snapshot installed";
+ * `getCollection` falls back to the Node `fs` path. The runtime package
+ * sets this once during init and (in dev mode) overwrites it on each
+ * rebuild.
+ */
+let installedSnapshot;
+/**
+ * Register a [`Snapshot`] so [`getCollection`] resolves from memory.
+ *
+ * Pass `undefined` to clear (used by tests that need to restore the v0
+ * filesystem path between runs). Idempotent: the latest call wins.
+ */
+export function setContentSnapshot(snapshot) {
+    installedSnapshot = snapshot;
+}
+/**
+ * Read the currently-installed [`Snapshot`], or `undefined` if none is
+ * registered. Exposed mostly for tests; production callers should not
+ * need to introspect the bridge state.
+ */
+export function getContentSnapshot() {
+    return installedSnapshot;
+}
+// Cached node:fs / node:path module references. Populated lazily on first
+// fs-path use (see [`loadNodeModules`]); reused on subsequent calls.
+let cachedNodeFs;
+let cachedNodePath;
+/**
+ * Synchronously load `node:fs` and `node:path`, caching the results.
+ *
+ * The node specifiers are concatenated at runtime (`"node:" + "fs"`) so
+ * esbuild's static analyzer cannot follow them — that's the load-bearing
+ * detail here, because this module is reachable from browser-bundled
+ * island chains via the `@takazudo/zfb` root barrel (see top-of-file note).
+ *
+ * Uses CommonJS `require` via [`createRequire`] (stable, sync) rather than
+ * `await import()` (async, would force `getCollection` async and violate
+ * ADR-004). `createRequire` itself is fetched from `node:module` through
+ * the same runtime-built specifier pattern.
+ *
+ * If `createRequire` cannot be obtained at all (i.e. truly running in a
+ * browser-shaped runtime — which would mean a misconfigured island
+ * bundle), throws so the failure is loud rather than silent.
+ */
+function loadNodeModules() {
+    if (cachedNodeFs !== undefined && cachedNodePath !== undefined) {
+        return { fs: cachedNodeFs, path: cachedNodePath };
+    }
+    // Runtime-built specifiers: opaque to esbuild's static analyzer.
+    const moduleSpecifier = "node:" + "module";
+    const fsSpecifier = "node:" + "fs";
+    const pathSpecifier = "node:" + "path";
+    // Strategy A: prefer the host `require` from a CommonJS context. We
+    // probe via `globalThis` and `Function`-built lookup so neither esbuild
+    // nor stricter ESM tooling errors out at the lookup site.
+    const dynamicGlobal = globalThis;
+    let nodeRequire = dynamicGlobal.require;
+    // Strategy B: ESM context — synthesize a require via `node:module`'s
+    // `createRequire`. Loading `node:module` itself through the same
+    // dynamic specifier shields it from esbuild's static walker.
+    if (typeof nodeRequire !== "function") {
+        // `Function("return require")()` returns the enclosing `require` when
+        // the bundler/loader injects one (Node CJS, esbuild default). Falls
+        // through if undefined — caught below.
+        try {
+            nodeRequire = new Function("return typeof require === 'function' ? require : undefined")();
+        }
+        catch {
+            nodeRequire = undefined;
+        }
+    }
+    if (typeof nodeRequire !== "function") {
+        // Last resort: synthesize via createRequire. Reaches `node:module`
+        // through a dynamic require we have to bootstrap somehow — the only
+        // way without a static `import` is `process.getBuiltinModule` (Node
+        // 22+) which exposes built-ins synchronously without a require.
+        const proc = globalThis.process;
+        const getBuiltin = proc?.getBuiltinModule;
+        if (typeof getBuiltin === "function") {
+            const mod = getBuiltin(moduleSpecifier);
+            nodeRequire = mod.createRequire(import.meta.url);
+        }
+    }
+    if (typeof nodeRequire !== "function") {
+        throw new Error("zfb/content: cannot load node:fs / node:path — no Node-style require available. " +
+            "This module's filesystem path requires a Node runtime; if you see this in a browser " +
+            "bundle, the bundler should externalize node:* imports (the islands bundler does so).");
+    }
+    cachedNodeFs = nodeRequire(fsSpecifier);
+    cachedNodePath = nodeRequire(pathSpecifier);
+    return { fs: cachedNodeFs, path: cachedNodePath };
+}
+/**
+ * Resolve the directory that holds a named content collection. Override
+ * via `ZFB_CONTENT_ROOT` so tests / fixtures can point at an arbitrary
+ * directory.
+ */
+function resolveCollectionDir(name) {
+    const { path } = loadNodeModules();
+    const envRoot = process.env["ZFB_CONTENT_ROOT"];
+    const root = envRoot ? path.resolve(envRoot) : path.resolve(process.cwd(), "content");
+    return path.join(root, name);
+}
+/**
+ * Build the v0 stub's bridge specifier for an entry. Mirrors the Rust-side
+ * convention (`mdx://<collection>/<slug>`) minus the body hash — the JS
+ * stub does not compile MDX, so it has no hash to attach. The bridge
+ * resolver on the renderer side is responsible for matching either form.
+ */
+function buildModuleSpecifier(collection, slug) {
+    return `mdx://${collection}/${slug}`;
+}
+/**
+ * Build the `Content` component for an entry. Captures `module_specifier`
+ * + `body` in the closure so the returned function takes only `props`.
+ *
+ * The bridge lookup is done lazily on every call (not at entry-construction
+ * time) so the renderer can install / swap `globalThis.__zfb.content` at
+ * any point before the first render without ordering hazards.
+ */
+function buildContentComponent(module_specifier, body) {
+    return function Content(props) {
+        const bridge = globalThis.__zfb?.content;
+        const renderer = bridge?.get(module_specifier);
+        if (typeof renderer === "function") {
+            // Trust the bridge to return a JSX-element-shaped value — we don't
+            // try to validate; both Preact and React JSX runtimes accept any
+            // structural `{ type, props, key }` object on either side of the
+            // boundary, and the renderer is the source of truth here.
+            return renderer(props);
+        }
+        return renderFallback(body);
+    };
+}
+/**
+ * Stamp the `constructor: undefined` sentinel on a structural JSX-element
+ * shape so `preact-render-to-string` (and Preact's diff path) treat it
+ * as a real VNode. Without this, Preact reads `.constructor` as `Object`
+ * — the value inherited from the literal — and silently drops the node,
+ * which is what produced the empty MDX bodies tracked in zudo-doc#505.
+ *
+ * Same trick `Island`'s `makeVNode` uses; kept private here so callers
+ * keep treating `ContentElement` / `ContentComponentElement` as opaque.
+ */
+function stampVNode(shape) {
+    shape.constructor = undefined;
+    return shape;
+}
+/**
+ * Build the structural JSX element returned when the bridge is absent.
+ *
+ * Shape: `<pre data-zfb-content-fallback>{marker}\n{body}</pre>` — the
+ * leading `[zfb fallback render]` marker line is part of the public
+ * fallback contract (it's both a visual signal and a grep target). Tests
+ * pin both the attribute and the marker line.
+ */
+function renderFallback(body) {
+    return stampVNode({
+        type: "pre",
+        props: {
+            "data-zfb-content-fallback": "",
+            children: `${FALLBACK_MARKER}\n${body}`,
+        },
+        key: null,
+    });
+}
+/** Leading marker line emitted by [`renderFallback`]. Public contract. */
+const FALLBACK_MARKER = "[zfb fallback render]";
+/**
+ * Load every `*.md` file in the named collection. Files starting with `.`
+ * or that lack a `.md` extension are ignored.
+ *
+ * **ADR-004 contract: this function is synchronous.** TSX page modules
+ * call it from anywhere — top-level, inside a render body, inside a
+ * `useMemo` — and SSR completes in a single pass without yielding. The
+ * snapshot path returns from memory; the filesystem fallback uses sync
+ * `node:fs` APIs so the surface stays unified. (The legacy async
+ * implementation was an oversight — the ADR predates it; SSG paths
+ * always saw a Promise where ADR-004 says they should see an array,
+ * which is why migrations from Astro tripped on `getCollection().filter
+ * is not a function`.)
+ *
+ * @example
+ *   const posts = getCollection<{ title: string; date: string }>("blog");
+ */
+export function getCollection(name) {
+    // Snapshot path: installed by `@takazudo/zfb-runtime`'s
+    // `createPageRouter` at Worker boot. Worker runtimes have no `fs`, so
+    // this branch is the production path under the embedded V8 host.
+    if (installedSnapshot !== undefined) {
+        const list = installedSnapshot.collections[name] ?? [];
+        return list.map((entry) => entryFromSnapshot(entry));
+    }
+    // Filesystem fallback (v0 path). Used by unit tests and direct Node
+    // invocations outside the Worker bundle.
+    //
+    // BCI-6: traversal is now recursive — subdirectories are walked so a
+    // collection rooted at `content/blog/` can contain nested `*.md` files
+    // (e.g. `content/blog/2024/hello.md`). Slugs are derived from the
+    // relative path so callers get stable, unique identifiers across nesting
+    // levels.
+    const dir = resolveCollectionDir(name);
+    let mdPaths;
+    try {
+        mdPaths = collectMdFilesSync(dir);
+    }
+    catch (err) {
+        // Guard the `code` access at runtime — a thrown non-`Error` value
+        // (rare, but possible) would otherwise crash here. We only swallow
+        // a true ENOENT; anything else propagates.
+        if (err !== null &&
+            typeof err === "object" &&
+            "code" in err &&
+            err.code === "ENOENT") {
+            return [];
+        }
+        throw err;
+    }
+    const { fs, path } = loadNodeModules();
+    return mdPaths.map((fullPath) => {
+        const raw = fs.readFileSync(fullPath, "utf8");
+        const { data, body } = parseFrontmatter(raw);
+        // Derive a stable slug from the relative path (relative to collection
+        // root), stripping the `.md` extension. For top-level files this
+        // produces the same value as before; for nested files it produces a
+        // path-based slug (e.g. `2024/hello`).
+        const rel = path.relative(dir, fullPath);
+        const slug = _relPathToSlug(rel);
+        const module_specifier = buildModuleSpecifier(name, slug);
+        return {
+            slug,
+            data: data,
+            body,
+            module_specifier,
+            Content: buildContentComponent(module_specifier, body),
+        };
+    });
+}
+/**
+ * Construct a [`CollectionEntry`] from a [`SnapshotEntry`]. The snapshot
+ * carries `frontmatter` as a possibly-`null` JSON value (matches the
+ * Rust contract for entries with no frontmatter); we normalise `null` /
+ * `undefined` to an empty object so consumers' `.data.title` reads
+ * never have to deal with `null`.
+ *
+ * **Type-safety note:** `T` is the caller-supplied frontmatter shape
+ * but we do **not** validate it at runtime — if the page declares a
+ * shape that the actual frontmatter doesn't match, the cast below
+ * lies. Callers are expected to keep their `getCollection<MySchema>()`
+ * generic in sync with the actual frontmatter; we acknowledge the
+ * unsafety with the explicit `unknown` indirection rather than a
+ * direct (and silently lossy) cast.
+ */
+function entryFromSnapshot(entry) {
+    const data = entry.frontmatter === null || entry.frontmatter === undefined
+        ? {}
+        : entry.frontmatter;
+    return {
+        slug: entry.slug,
+        data,
+        body: entry.body,
+        module_specifier: entry.module_specifier,
+        Content: buildContentComponent(entry.module_specifier, entry.body),
+    };
+}
+/**
+ * Recursively collect every `*.md` file under `dir` (synchronous).
+ *
+ * BCI-6: replaces the old flat `readdir(dir).filter(n => n.endsWith(".md"))`
+ * approach. Hidden files (names starting with `.`) and hidden directories
+ * are skipped at every nesting level, matching the top-level behaviour of
+ * the previous implementation.
+ *
+ * Returns absolute paths sorted lexicographically so the result order is
+ * deterministic across platforms and Node versions.
+ *
+ * Synchronous to honour ADR-004 — see [`getCollection`].
+ */
+function collectMdFilesSync(dir) {
+    const result = [];
+    const { fs, path } = loadNodeModules();
+    walkDirSync(fs, path, dir, result);
+    result.sort();
+    return result;
+}
+function walkDirSync(fs, path, current, out) {
+    const entries = fs.readdirSync(current, { withFileTypes: true });
+    for (const entry of entries) {
+        if (entry.name.startsWith("."))
+            continue;
+        const fullPath = path.join(current, entry.name);
+        // Skip symlinks to avoid infinite loops caused by cycles (e.g. a symlink
+        // pointing at a parent directory). Content files are expected to be plain
+        // regular files; following symlinks provides no value here.
+        if (entry.isSymbolicLink())
+            continue;
+        if (entry.isDirectory()) {
+            walkDirSync(fs, path, fullPath, out);
+        }
+        else if (entry.isFile() && entry.name.endsWith(".md")) {
+            out.push(fullPath);
+        }
+    }
+}
+/**
+ * @internal
+ *
+ * Convert a `path.relative()` result into a forward-slash-separated
+ * slug with the trailing `.md` extension stripped.
+ *
+ * Slugs are URL-flavored identifiers, not filesystem paths — they
+ * MUST use `/` regardless of the host OS so a nested entry like
+ * `2024/hello.md` produces the slug `2024/hello` on both POSIX and
+ * Windows. Without this normalisation, Windows callers would see
+ * `2024\hello`, which then leaks through to `module_specifier` and
+ * any URL the consumer derives from the slug.
+ *
+ * Exported solely so the unit test suite can pin the Windows
+ * behaviour without needing an actual Windows host. Do not depend on
+ * this from application code — name and signature may change.
+ */
+export function _relPathToSlug(relPath) {
+    const { path } = loadNodeModules();
+    const posix = path.sep === "/" ? relPath : relPath.split(path.sep).join("/");
+    // Some Node versions normalise `\` even when sep is `/`, so be
+    // defensive: collapse any straggling backslashes too.
+    const normalised = posix.includes("\\") ? posix.split("\\").join("/") : posix;
+    return normalised.endsWith(".md") ? normalised.slice(0, -".md".length) : normalised;
+}
+/** Internal helper: build a structural JSX element of the given tag. */
+function buildOverrideElement(tag, props) {
+    const { children, ...rest } = props;
+    // `stampVNode` sets `constructor: undefined` so Preact recognises the
+    // returned object as a VNode rather than foreign data — see the helper's
+    // docblock for context (zudo-doc#505).
+    return stampVNode({
+        type: tag,
+        props: { ...rest, children },
+        key: null,
+    });
+}
+/**
+ * `<h2>` passthrough override. Ported from zudo-doc's `HeadingH2`, stripped
+ * of styling — v0 ships pass-through behaviour; visual treatment is layered
+ * on by the consumer (or by a follow-up enhancement pass).
+ */
+export function ContentH2(props) {
+    return buildOverrideElement("h2", props);
+}
+/** `<h3>` passthrough override. See [`ContentH2`] for the contract. */
+export function ContentH3(props) {
+    return buildOverrideElement("h3", props);
+}
+/** `<h4>` passthrough override. See [`ContentH2`] for the contract. */
+export function ContentH4(props) {
+    return buildOverrideElement("h4", props);
+}
+/** `<p>` passthrough override. Mirrors zudo-doc's `ContentParagraph`. */
+export function ContentParagraph(props) {
+    return buildOverrideElement("p", props);
+}
+/** `<a>` passthrough override. Mirrors zudo-doc's `ContentLink`. */
+export function ContentLink(props) {
+    return buildOverrideElement("a", props);
+}
+/** `<strong>` passthrough override. Mirrors zudo-doc's `ContentStrong`. */
+export function ContentStrong(props) {
+    return buildOverrideElement("strong", props);
+}
+/** `<blockquote>` passthrough override. Mirrors zudo-doc's `ContentBlockquote`. */
+export function ContentBlockquote(props) {
+    return buildOverrideElement("blockquote", props);
+}
+/** `<ul>` passthrough override. Mirrors zudo-doc's `ContentUl`. */
+export function ContentUl(props) {
+    return buildOverrideElement("ul", props);
+}
+/** `<ol>` passthrough override. Mirrors zudo-doc's `ContentOl`. */
+export function ContentOl(props) {
+    return buildOverrideElement("ol", props);
+}
+/** `<table>` passthrough override. Mirrors zudo-doc's `ContentTable`. */
+export function ContentTable(props) {
+    return buildOverrideElement("table", props);
+}
+/** `<code>` passthrough override. Mirrors zudo-doc's `ContentCode`. */
+export function ContentCode(props) {
+    return buildOverrideElement("code", props);
+}
+/**
+ * Default per-element override map — eleven entries covering the markdown
+ * tags the zudo-doc convention overrides (`h2`, `h3`, `h4`, `p`, `a`,
+ * `strong`, `blockquote`, `ul`, `ol`, `table`, `code`).
+ *
+ * `h1` is intentionally absent: page titles render from frontmatter, per
+ * the zudo-doc convention.
+ *
+ * Spread into a `components` prop to compose with custom overrides:
+ *
+ * ```tsx
+ * import { defaultComponents } from "zfb";
+ *
+ * <entry.Content components={{ ...defaultComponents, h2: MyFancyH2 }} />
+ * ```
+ */
+export const defaultComponents = {
+    h2: ContentH2,
+    h3: ContentH3,
+    h4: ContentH4,
+    p: ContentParagraph,
+    a: ContentLink,
+    strong: ContentStrong,
+    blockquote: ContentBlockquote,
+    ul: ContentUl,
+    ol: ContentOl,
+    table: ContentTable,
+    code: ContentCode,
+};
+//# sourceMappingURL=content.js.map