@takazudo/zudo-doc 0.1.0

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,18 @@
+# @takazudo/zudo-doc
+
+Framework primitives that sit on top of zfb's engine — the framework layer that zfb deliberately doesn't ship (per ADR-003).
+
+This package is part of the **Astro→zfb migration** (super-epic [#473](https://github.com/zudolab/zudo-doc/issues/473)). It implements the [E5 epic](https://github.com/zudolab/zudo-doc/issues/474) and provides the missing-by-design framework concerns:
+
+- **Sidebar tree builder** (`./sidebar-tree`) — turns collection entries + `_category_.json` into a sidebar `SidebarNode[]`.
+- **Theme controls** (`./theme`) — color scheme provider + design-token tweak panel (Preact island that wraps an iframe).
+- **TOC** (`./toc`) — desktop and mobile TOC Preact islands fed by MDX `headings` export.
+- **Breadcrumb** (`./breadcrumb`) — JSX breadcrumb fed by the sidebar tree.
+- **DocLayout** (`./doclayout`) — composable layout shell with explicit `<Header>`, `<Sidebar>`, `<Main>`, `<Toc>`, `<Footer>` props; ships a `<DocLayoutWithDefaults>` wrapper that holds the 16 `create-zudo-doc` injection anchors.
+- **View Transitions** (`./transitions`) — native View Transitions API shim (Chrome/Edge/Safari 18+); persistent regions via `view-transition-name`. No-op fallback in Firefox.
+- **Head injection** (`./head`) — canonical, og:\*, twitter:\*, robots, preload hints, RSS link, sitemap link, theme-color — byte-equal to today's Astro output.
+- **SSR-skip wrappers** (`./ssr-skip`) — `<AiChatModalIsland>`, `<ImageEnlargeIsland>`, `<DesignTokenTweakPanelIsland>`, `<MockInitIsland>` — wrap zfb's `<Island ssrFallback>` with the right fallback markup so doc pages don't have to re-implement the SSR-skip pattern.
+
+## Pre-publish dev workflow
+
+Phase A npm publish is deferred (see super-epic comment 2026-04-28). During pre-publish dev, this package references zfb via the local checkout at `$HOME/repos/myoss/zfb`. Use `/refer-another-project zfb` to read zfb's APIs. If a zfb bug is discovered, fix it directly on zfb's `main` and push (zfb is not public yet).

package/dist/body-foot-util/body-foot-util-area.d.ts

@@ -0,0 +1,55 @@
+import { VNode } from 'preact';
+
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+
+/**
+ * Default label used when the consumer doesn't pass one. The legacy
+ * Astro template translated `doc.viewSource` via the project's i18n
+ * module; v2 stays framework-agnostic, so callers resolve their
+ * translation upstream and pass the result here. The English string
+ * is mirrored verbatim from the legacy translations table so the
+ * component degrades to the original wording when no override is
+ * supplied.
+ */
+declare const DEFAULT_VIEW_SOURCE_LABEL = "View source on GitHub";
+interface BodyFootUtilAreaProps {
+    /**
+     * Final, pre-computed GitHub source URL. The legacy template
+     * derived this from `settings.githubUrl + contentDir + entryId`; the
+     * v2 component delegates that computation to the consumer (no
+     * upstream dependency on the project settings module).
+     *
+     * When falsy, the view-source link is suppressed.
+     */
+    sourceUrl?: string | null;
+    /**
+     * Display text for the view-source link. Defaults to
+     * `"View source on GitHub"`; pass the i18n-resolved string from
+     * upstream to localise.
+     */
+    viewSourceLabel?: string;
+    /**
+     * Pre-built doc-history island — typically a zfb `<Island ssrFallback>`
+     * that renders the host's real DocHistory component. The host is
+     * responsible for assembling this so the page → real-component import
+     * chain is preserved (zfb's island scanner relies on that walk; see
+     * issue zudolab/zudo-doc#1355 Wave 8 Path A).
+     *
+     * Pass `null` / `undefined` to suppress the history trigger entirely.
+     */
+    docHistoryIsland?: VNode | null;
+}
+/**
+ * Footer utility area shown below an article body — composes the
+ * "View source on GitHub" link and the host-supplied doc-history
+ * island. JSX port of `src/components/body-foot-util-area.astro`.
+ *
+ * Returns `null` when neither slot has anything to render, mirroring
+ * the `hasContent && (...)` guard in the original template so the
+ * surrounding `<section>` (with its top border + spacing) doesn't
+ * appear as an empty band.
+ */
+declare function BodyFootUtilArea(props: BodyFootUtilAreaProps): VNode | null;
+
+export { BodyFootUtilArea, type BodyFootUtilAreaProps, DEFAULT_VIEW_SOURCE_LABEL };

package/dist/body-foot-util/body-foot-util-area.js

@@ -0,0 +1,71 @@
+import { Fragment, jsx, jsxs } from "preact/jsx-runtime";
+const DEFAULT_VIEW_SOURCE_LABEL = "View source on GitHub";
+function BodyFootUtilArea(props) {
+  const {
+    sourceUrl,
+    viewSourceLabel = DEFAULT_VIEW_SOURCE_LABEL,
+    docHistoryIsland
+  } = props;
+  const showSource = Boolean(sourceUrl);
+  const showHistory = Boolean(docHistoryIsland);
+  if (!showSource && !showHistory) return null;
+  return /* @__PURE__ */ jsxs(
+    "section",
+    {
+      class: "mt-vsp-xl border-t border-muted pt-vsp-md",
+      "aria-label": "Document utilities",
+      children: [
+        showSource && /* @__PURE__ */ jsx("div", { class: "mb-vsp-md", children: /* @__PURE__ */ jsxs(
+          "a",
+          {
+            href: sourceUrl,
+            target: "_blank",
+            rel: "noopener noreferrer",
+            class: "inline-flex items-center gap-hsp-2xs text-small text-muted hover:text-accent",
+            children: [
+              /* @__PURE__ */ jsxs(
+                "svg",
+                {
+                  xmlns: "http://www.w3.org/2000/svg",
+                  class: "h-[0.875rem] w-[0.875rem]",
+                  fill: "none",
+                  viewBox: "0 0 24 24",
+                  stroke: "currentColor",
+                  "stroke-width": "2",
+                  "aria-hidden": "true",
+                  children: [
+                    /* @__PURE__ */ jsx(
+                      "path",
+                      {
+                        "stroke-linecap": "round",
+                        "stroke-linejoin": "round",
+                        d: "M14 3h7m0 0v7m0-7L10 14"
+                      }
+                    ),
+                    /* @__PURE__ */ jsx(
+                      "path",
+                      {
+                        "stroke-linecap": "round",
+                        "stroke-linejoin": "round",
+                        d: "M5 5h5m-5 0a2 2 0 00-2 2v12a2 2 0 002 2h12a2 2 0 002-2v-5"
+                      }
+                    )
+                  ]
+                }
+              ),
+              /* @__PURE__ */ jsx("span", { children: viewSourceLabel })
+            ]
+          }
+        ) }),
+        showHistory && docHistoryIsland && /* @__PURE__ */ jsxs(Fragment, { children: [
+          /* @__PURE__ */ jsx("h2", { class: "sr-only", children: "Revision History" }),
+          docHistoryIsland
+        ] })
+      ]
+    }
+  );
+}
+export {
+  BodyFootUtilArea,
+  DEFAULT_VIEW_SOURCE_LABEL
+};

package/dist/body-foot-util/edit-link.d.ts

@@ -0,0 +1,45 @@
+import { VNode } from 'preact';
+
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+
+/**
+ * Default label used when the consumer doesn't pass one. The legacy
+ * Astro template translated `doc.editPage` via the project's i18n
+ * module; v2 stays framework-agnostic and lets the caller pass the
+ * already-translated label as `label` instead. The English string is
+ * mirrored verbatim from the legacy translations table.
+ */
+declare const DEFAULT_EDIT_LINK_LABEL = "Edit this page";
+interface EditLinkProps {
+    /**
+     * Final, pre-computed edit URL. The legacy Astro version derived
+     * this from `settings.editUrl + contentDir + entryId`; that
+     * computation belongs in the consumer (so this v2 component has no
+     * upward dependency on the project settings module).
+     *
+     * When `null` / `undefined` / empty string the link is suppressed
+     * entirely — the component returns `null` to mirror the
+     * `editUrl && (...)` guard in the original template.
+     */
+    editUrl?: string | null;
+    /**
+     * Display text for the link. The legacy template called
+     * `t("doc.editPage", locale)`; consumers should resolve their i18n
+     * lookup upstream and pass the result here. Defaults to
+     * `"Edit this page"` so the component degrades to the original
+     * English label when no translation is provided.
+     */
+    label?: string;
+}
+/**
+ * "Edit this page" link — JSX port of `src/components/edit-link.astro`.
+ *
+ * The legacy component owned three concerns: URL computation, i18n
+ * lookup, and presentation. v2 keeps only presentation; URL and label
+ * are pre-resolved by the caller. This matches the breadcrumb subpath
+ * pattern of "no settings/i18n imports inside the v2 package".
+ */
+declare function EditLink(props: EditLinkProps): VNode | null;
+
+export { DEFAULT_EDIT_LINK_LABEL, EditLink, type EditLinkProps };

package/dist/body-foot-util/edit-link.js

@@ -0,0 +1,42 @@
+import { jsx, jsxs } from "preact/jsx-runtime";
+const DEFAULT_EDIT_LINK_LABEL = "Edit this page";
+function EditLink(props) {
+  const { editUrl, label = DEFAULT_EDIT_LINK_LABEL } = props;
+  if (!editUrl) return null;
+  return /* @__PURE__ */ jsxs(
+    "a",
+    {
+      href: editUrl,
+      target: "_blank",
+      rel: "noopener noreferrer",
+      class: "inline-flex items-center gap-hsp-2xs text-small text-muted hover:text-accent",
+      children: [
+        /* @__PURE__ */ jsx(
+          "svg",
+          {
+            xmlns: "http://www.w3.org/2000/svg",
+            class: "h-[0.875rem] w-[0.875rem]",
+            fill: "none",
+            viewBox: "0 0 24 24",
+            stroke: "currentColor",
+            "stroke-width": "2",
+            "aria-hidden": "true",
+            children: /* @__PURE__ */ jsx(
+              "path",
+              {
+                "stroke-linecap": "round",
+                "stroke-linejoin": "round",
+                d: "M11 5H6a2 2 0 00-2 2v11a2 2 0 002 2h11a2 2 0 002-2v-5m-1.414-9.414a2 2 0 112.828 2.828L11.828 15H9v-2.828l8.586-8.586z"
+              }
+            )
+          }
+        ),
+        /* @__PURE__ */ jsx("span", { children: label })
+      ]
+    }
+  );
+}
+export {
+  DEFAULT_EDIT_LINK_LABEL,
+  EditLink
+};

package/dist/body-foot-util/index.d.ts

@@ -0,0 +1,3 @@
+export { BodyFootUtilArea, BodyFootUtilAreaProps, DEFAULT_VIEW_SOURCE_LABEL } from './body-foot-util-area.js';
+export { DEFAULT_EDIT_LINK_LABEL, EditLink, EditLinkProps } from './edit-link.js';
+import 'preact';

package/dist/body-foot-util/index.js

@@ -0,0 +1,11 @@
+import {
+  BodyFootUtilArea,
+  DEFAULT_VIEW_SOURCE_LABEL
+} from "./body-foot-util-area.js";
+import { EditLink, DEFAULT_EDIT_LINK_LABEL } from "./edit-link.js";
+export {
+  BodyFootUtilArea,
+  DEFAULT_EDIT_LINK_LABEL,
+  DEFAULT_VIEW_SOURCE_LABEL,
+  EditLink
+};

package/dist/breadcrumb/breadcrumb.d.ts

@@ -0,0 +1,57 @@
+import { ComponentChildren, VNode } from 'preact';
+import { BreadcrumbItem, SidebarNode } from './types.js';
+
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+
+/**
+ * Convert a sidebar tree + the current page's id into the ordered list
+ * of crumbs the renderer walks. The first crumb is the home rung
+ * (icon-only, label is the empty string), followed by each ancestor in
+ * the tree, ending with the current page (no `href` so the renderer
+ * paints it as plain text).
+ *
+ * Mirrors the legacy buildBreadcrumbs() behaviour from
+ * src/utils/docs.ts so the rendered output stays parity-equivalent
+ * with the original Astro breadcrumb component.
+ */
+declare function buildBreadcrumbItems(tree: SidebarNode[], currentId: string, homeHref: string): BreadcrumbItem[];
+interface BreadcrumbProps {
+    /** Pre-built items, or omit and pass `tree` + `currentId` instead. */
+    items?: BreadcrumbItem[];
+    /** Sidebar tree to derive the trail from. Required when `items` is omitted. */
+    tree?: SidebarNode[];
+    /** Id of the current page (matches SidebarNode.id). Required when `items` is omitted. */
+    currentId?: string;
+    /** Href for the leading home rung. Defaults to "/". */
+    homeHref?: string;
+    /**
+     * Optional slot rendered at the right end of the breadcrumb row.
+     * When provided, the breadcrumb nav and this slot are wrapped in a
+     * flex row that matches the original Astro doc-layout's combined
+     * breadcrumb + version-switcher row:
+     *
+     *   class="mb-vsp-sm flex flex-col items-start gap-vsp-xs
+     *          sm:flex-row sm:items-center sm:justify-between [&_nav]:mb-0"
+     *
+     * The `[&_nav]:mb-0` rule strips the nav's own `mb-vsp-md` so the
+     * wrapper margin controls spacing instead. Use this to place the
+     * VersionSwitcher pill inline at the right of the breadcrumb row,
+     * matching the reference site's layout on category index pages.
+     */
+    rightSlot?: ComponentChildren;
+}
+/**
+ * Breadcrumb trail — JSX port of src/components/breadcrumb.astro.
+ *
+ * Two usage shapes:
+ *   1. Pass pre-built `items` (existing call-sites that already
+ *      compute crumbs upstream).
+ *   2. Pass `tree` + `currentId` and the component derives the trail.
+ *
+ * Returns null when no items resolve, matching the Astro template's
+ * `items.length > 0 &&` guard.
+ */
+declare function Breadcrumb(props: BreadcrumbProps): VNode | null;
+
+export { Breadcrumb, type BreadcrumbProps, buildBreadcrumbItems };

package/dist/breadcrumb/breadcrumb.js

@@ -0,0 +1,113 @@
+import { Fragment, jsx, jsxs } from "preact/jsx-runtime";
+import { findPath } from "./find-path.js";
+function buildBreadcrumbItems(tree, currentId, homeHref) {
+  const items = [{ label: "", href: homeHref }];
+  const path = findPath(tree, currentId);
+  for (let i = 0; i < path.length; i++) {
+    const node = path[i];
+    const isLast = i === path.length - 1;
+    items.push({
+      label: node.label,
+      href: isLast ? void 0 : node.href
+    });
+  }
+  return items;
+}
+function SmartLabel({ label }) {
+  if (!isPathLike(label)) return label;
+  const parts = label.split(DELIM_SPLIT);
+  const nodes = [];
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i];
+    if (part === "") continue;
+    nodes.push(part);
+    if (i % 2 === 1) nodes.push(/* @__PURE__ */ jsx("wbr", {}, `wbr-${i}`));
+  }
+  return /* @__PURE__ */ jsx(Fragment, { children: nodes });
+}
+const DELIM_SPLIT = /([/\\\-_.:?#&=])/;
+function isPathLike(text) {
+  if (!text) return false;
+  if (text.includes("://")) return true;
+  if (/^\.{0,2}\//.test(text)) return true;
+  if (/^[A-Za-z]:[\\/]/.test(text)) return true;
+  const forwardMatches = text.match(/[A-Za-z0-9]\/[A-Za-z0-9]/g);
+  if (forwardMatches && forwardMatches.length >= 2) return true;
+  const backMatches = text.match(/[A-Za-z0-9]\\[A-Za-z0-9]/g);
+  if (backMatches && backMatches.length >= 2) return true;
+  const hasDomainDot = /[A-Za-z0-9]\.[A-Za-z0-9]/.test(text);
+  const hasSlash = /[\\/]/.test(text);
+  if (hasDomainDot && hasSlash) return true;
+  return false;
+}
+function ChevronIcon() {
+  return /* @__PURE__ */ jsx(
+    "svg",
+    {
+      xmlns: "http://www.w3.org/2000/svg",
+      class: "h-icon-xs w-icon-xs text-muted shrink-0",
+      fill: "none",
+      viewBox: "0 0 24 24",
+      stroke: "currentColor",
+      "stroke-width": "2",
+      "aria-hidden": "true",
+      children: /* @__PURE__ */ jsx(
+        "path",
+        {
+          "stroke-linecap": "round",
+          "stroke-linejoin": "round",
+          d: "M9 5l7 7-7 7"
+        }
+      )
+    }
+  );
+}
+function HomeIcon() {
+  return /* @__PURE__ */ jsx(
+    "svg",
+    {
+      xmlns: "http://www.w3.org/2000/svg",
+      class: "h-[1.575rem] w-[1.575rem] shrink-0",
+      fill: "none",
+      viewBox: "0 0 24 24",
+      stroke: "currentColor",
+      "stroke-width": "2",
+      "aria-hidden": "true",
+      children: /* @__PURE__ */ jsx(
+        "path",
+        {
+          "stroke-linecap": "round",
+          "stroke-linejoin": "round",
+          d: "M3 12l2-2m0 0l7-7 7 7M5 10v10a1 1 0 001 1h3m10-11l2 2m-2-2v10a1 1 0 01-1 1h-3m-4 0a1 1 0 01-1-1v-4a1 1 0 011-1h2a1 1 0 011 1v4a1 1 0 01-1 1h-2z"
+        }
+      )
+    }
+  );
+}
+function Breadcrumb(props) {
+  const items = props.items ?? (props.tree && props.currentId !== void 0 ? buildBreadcrumbItems(props.tree, props.currentId, props.homeHref ?? "/") : []);
+  if (items.length === 0) return null;
+  const nav = /* @__PURE__ */ jsx("nav", { class: "mb-vsp-md text-small", "aria-label": "Breadcrumb", children: /* @__PURE__ */ jsx("ol", { class: "flex flex-wrap items-center gap-x-hsp-xs", children: items.map((item, i) => /* @__PURE__ */ jsxs("li", { class: "flex items-center gap-x-hsp-xs", children: [
+    i > 0 && /* @__PURE__ */ jsx(ChevronIcon, {}),
+    item.href ? /* @__PURE__ */ jsxs(
+      "a",
+      {
+        href: item.href,
+        class: "text-muted underline hover:text-fg flex items-center gap-x-hsp-2xs",
+        children: [
+          i === 0 && /* @__PURE__ */ jsx(HomeIcon, {}),
+          /* @__PURE__ */ jsx(SmartLabel, { label: item.label })
+        ]
+      }
+    ) : /* @__PURE__ */ jsx("span", { class: "text-fg", children: /* @__PURE__ */ jsx(SmartLabel, { label: item.label }) })
+  ] }, `crumb-${i}`)) }) });
+  if (props.rightSlot === void 0) return nav;
+  return /* @__PURE__ */ jsxs("div", { class: "mb-vsp-sm flex flex-col items-start gap-vsp-xs sm:flex-row sm:items-center sm:justify-between [&_nav]:mb-0", children: [
+    nav,
+    props.rightSlot
+  ] });
+}
+export {
+  Breadcrumb,
+  buildBreadcrumbItems
+};

package/dist/breadcrumb/find-path.d.ts

@@ -0,0 +1,16 @@
+import { BreadcrumbNode, SidebarNode } from './types.js';
+
+/**
+ * Walk the sidebar tree and return the chain of nodes from the root
+ * level down to (and including) the node whose `id` matches `targetId`.
+ *
+ * Returns an empty array when no node matches. Pure: never mutates the
+ * input tree, never reads anything outside of it.
+ *
+ * Used by the breadcrumb component to derive the current page's
+ * ancestry. The home/root crumb is the renderer's responsibility — this
+ * helper deals strictly with the tree itself.
+ */
+declare function findPath<T extends BreadcrumbNode = SidebarNode>(nodes: readonly T[], targetId: string): T[];
+
+export { findPath };

package/dist/breadcrumb/find-path.js

@@ -0,0 +1,13 @@
+function findPath(nodes, targetId) {
+  for (const node of nodes) {
+    if (node.id === targetId) return [node];
+    if (node.children && node.children.length > 0) {
+      const sub = findPath(node.children, targetId);
+      if (sub.length > 0) return [node, ...sub];
+    }
+  }
+  return [];
+}
+export {
+  findPath
+};

package/dist/breadcrumb/index.d.ts

@@ -0,0 +1,4 @@
+export { Breadcrumb, BreadcrumbProps, buildBreadcrumbItems } from './breadcrumb.js';
+export { findPath } from './find-path.js';
+export { BreadcrumbItem, SidebarNode } from './types.js';
+import 'preact';

package/dist/breadcrumb/index.js

@@ -0,0 +1,7 @@
+import { Breadcrumb, buildBreadcrumbItems } from "./breadcrumb.js";
+import { findPath } from "./find-path.js";
+export {
+  Breadcrumb,
+  buildBreadcrumbItems,
+  findPath
+};

package/dist/breadcrumb/types.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Type contract for the breadcrumb component.
+ *
+ * Breadcrumb only walks the tree to find an ancestor chain — it does not
+ * need the full SidebarNode shape from sidebar-tree. We declare a minimal
+ * structural interface here. The canonical SidebarNode (from sidebar-tree)
+ * is structurally assignable to this, so callers can pass either shape
+ * unchanged.
+ */
+interface BreadcrumbNode {
+    type: "doc" | "category";
+    id: string;
+    label: string;
+    href?: string;
+    sidebar_position?: number;
+    children?: readonly BreadcrumbNode[];
+}
+/**
+ * Backward-compatible alias retained for callers that previously imported
+ * `SidebarNode` from this subpath.
+ */
+type SidebarNode = BreadcrumbNode;
+/**
+ * One rung of the breadcrumb trail. `href` is omitted on the final
+ * (current-page) item so the renderer can present it as plain text.
+ */
+interface BreadcrumbItem {
+    label: string;
+    href?: string;
+}
+
+export type { BreadcrumbItem, BreadcrumbNode, SidebarNode };

package/dist/code-syntax/code-block-enhancer-script.d.ts

@@ -0,0 +1,3 @@
+declare const CODE_BLOCK_ENHANCER_SCRIPT: string;
+
+export { CODE_BLOCK_ENHANCER_SCRIPT };