@dogsbay/format-astro 0.2.0-beta.15 → 0.2.0-beta.151

package/dist/diff-decoration.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Diff decorations — DiffTree marks rendered through the NORMAL
+ * serializer (plans/tree-diff-rendering.md §2).
+ *
+ * `@dogsbay/tree-diff` annotates nodes with structural fields
+ * (`diff`, `diffInline`, `diffPeer`, `diffMovedFrom`); this module
+ * reads them STRUCTURALLY (no dependency on tree-diff) and decorates
+ * the serializer's output:
+ *
+ *  - block marks   → a `data-diff` attribute injected into the
+ *    rendered snippet's first opening tag (attribute injection works
+ *    uniformly for components, table rows, and plain tags — no
+ *    invalid wrapper elements inside tables/tabs), styled by the
+ *    generated theme CSS;
+ *  - changed prose → the word-level segments render as
+ *    `<ins>/<del>` runs (the merged reading view);
+ *  - changed code  → a before/after pair: the old side renders
+ *    through the same code renderer, labeled, above the new side.
+ *
+ * A tree with no marks renders byte-identically to before — the
+ * decoration layer is invisible until a DiffTree arrives.
+ */
+import type { TreeNode } from "@dogsbay/types";
+export { DIFF_CSS, buildMergedCodeDiff, diffMarksOf, hasDiffMarks, inlineSegmentsToHtml, type DiffMarks, type MergedCodeDiff, } from "@dogsbay/render-html/diff";
+/**
+ * Inject attributes into the FIRST opening tag of a rendered
+ * snippet. Handles components (`<TableRow`), plain tags (`<p`), and
+ * skips leading whitespace/JSX expressions.
+ */
+export declare function injectAttrs(rendered: string, attrs: string): string;
+/**
+ * Decorate one rendered node. `renderPeer` renders the other side of
+ * a changed pair through the same serializer (code before/after).
+ */
+export declare function decorateDiff(node: TreeNode, rendered: string, renderPeer: (peer: TreeNode) => string): string;

package/dist/diff-decoration.js

@@ -0,0 +1,101 @@
+import { diffMarksOf, inlineSegmentsToHtml, mergedCodeNode } from "@dogsbay/render-html/diff";
+// Shared with render-html, which marks the same DiffTree in its HTML
+export { DIFF_CSS, buildMergedCodeDiff, diffMarksOf, hasDiffMarks, inlineSegmentsToHtml, } from "@dogsbay/render-html/diff";
+/**
+ * Inject attributes into the FIRST opening tag of a rendered
+ * snippet. Handles components (`<TableRow`), plain tags (`<p`), and
+ * skips leading whitespace/JSX expressions.
+ */
+export function injectAttrs(rendered, attrs) {
+    const m = rendered.match(/<([A-Za-z][\w.-]*)((?:[^>"']|"[^"]*"|'[^']*')*?)(\/?)>/);
+    if (!m || m.index === undefined)
+        return rendered;
+    const insertAt = m.index + 1 + m[1].length;
+    return `${rendered.slice(0, insertAt)} ${attrs}${rendered.slice(insertAt)}`;
+}
+/**
+ * Decorate one rendered node. `renderPeer` renders the other side of
+ * a changed pair through the same serializer (code before/after).
+ */
+export function decorateDiff(node, rendered, renderPeer) {
+    const marks = diffMarksOf(node);
+    if (!marks.diff && !marks.diffInline)
+        return rendered;
+    // changed prose with word-level segments: replace the inline body
+    if (marks.diffInline && node.type !== "heading") {
+        return `<p data-diff="changed" class="db-diff-prose" set:html={${JSON.stringify(inlineSegmentsToHtml(marks.diffInline))}} />`;
+    }
+    // changed code: ONE unified-diff block (removed lines −, added
+    // lines +, via CodeRich's notation-diff pipeline) — the same
+    // merged reading view prose uses; the copy button copies the
+    // post-change code only. Falls back to a labeled before/after
+    // pair when merging is unsafe (size cap, marker collision).
+    if (marks.diff === "changed" && marks.diffPeer && node.type === "code") {
+        const merged = mergedCodeNode(node);
+        if (merged !== null) {
+            const mergedNode = merged.node;
+            // Whitespace-only edits stay FULLY marked (indentation is
+            // semantic in YAML/Python/markdown — never silently dropped),
+            // but they get NAMED: without the label the reader hunts a
+            // 3-space shift across two near-identical lines.
+            const wsOnly = merged.whitespaceOnly;
+            const cls = `db-diff-code${wsOnly ? " db-diff-code-ws" : ""}`;
+            // The clean twin is the already-rendered new side: shiki line
+            // spans keep their newlines OUTSIDE the span, so hiding removed
+            // lines under Hide highlights would leave blank lines — instead
+            // the whole merged block swaps for the clean render (CSS only).
+            return [
+                `<div data-diff="changed" class="${cls}">`,
+                `<div class="db-diff-code-merged">`,
+                renderPeer(mergedNode),
+                `</div>`,
+                `<div class="db-diff-code-clean">`,
+                rendered,
+                `</div>`,
+                `</div>`,
+            ].join("\n");
+        }
+        const before = injectAttrs(renderPeer(marks.diffPeer), 'data-diff="removed"');
+        const after = injectAttrs(rendered, 'data-diff="added"');
+        return [
+            `<div class="db-diff-pair" data-diff="changed">`,
+            `<div class="db-diff-pair-label">before</div>`,
+            before,
+            `<div class="db-diff-pair-label">after</div>`,
+            after,
+            `</div>`,
+        ].join("\n");
+    }
+    const attrs = marks.diff === "moved" && marks.diffMovedFrom
+        ? `data-diff="moved" data-diff-from="${marks.diffMovedFrom.join(" › ").replace(/"/g, "&quot;")}"`
+        : `data-diff="${marks.diff}"`;
+    // Raw HTML renders as <Fragment set:html>, which emits NO wrapper
+    // element — an injected attribute vanishes at build time (found via
+    // better-auth adapters/mysql: an invisible table change). Marked
+    // html blocks get a real wrapper div instead.
+    if (node.type === "html") {
+        // A CHANGED html block is opaque: we render the new markup
+        // faithfully (fidelity is the product), but a bare "changed" border
+        // told the reader NOTHING about what went — the mysql table lost a
+        // whole column and the page showed no trace of it (external review:
+        // "fidelity alone is insufficient if a meaningful deletion becomes
+        // invisible"). So the previous version rides along in a disclosure:
+        // the deletion is one click away, and the reader is never misled
+        // into thinking nothing was removed.
+        if (marks.diff === "changed" && marks.diffPeer) {
+            return [
+                `<div ${attrs} class="db-diff-html">`,
+                rendered,
+                `<details class="db-diff-html-before">`,
+                `<summary>Show previous version</summary>`,
+                `<div data-diff="removed">`,
+                renderPeer(marks.diffPeer),
+                `</div>`,
+                `</details>`,
+                `</div>`,
+            ].join("\n");
+        }
+        return `<div ${attrs}>\n${rendered}\n</div>`;
+    }
+    return injectAttrs(rendered, attrs);
+}

package/dist/granularity.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Granularity views — assemble a whole-book page from topic pages + nav.
+ *
+ * The additive-MVP core (see plans/granularity-views.md). Given the topic-grained
+ * `ExportPage[]` + the `NavItem[]` tree a site already produces, this reassembles
+ * an entire nav subtree into ONE "book" page:
+ *   - each nav node becomes a heading (level = nav depth; book title is the
+ *     implicit H1, so a top-level node is H2, its children H3, … clamped at H6);
+ *   - a topic's own body headings are shifted down by `level − 1` so they nest
+ *     under their topic's title;
+ *   - every node gets a stable, page-unique anchor, so a topic resolves to
+ *     `<book>/_book#<anchor>` (the "Read as single page" button target).
+ *
+ * Pure + source-agnostic: it never touches the network or the original source,
+ * only the already-converted `TreeNode` trees ("convert once, project many").
+ * The original topic trees are NOT mutated — each is deep-cloned before its
+ * headings are shifted.
+ *
+ * This is a platform generalization of `format-fluidtopics-rest/src/single-page.ts`
+ * (which is khub-coupled). The FT `--single-page` branch will fold into this.
+ */
+import type { ExportPage, NavItem, TreeNode } from "@dogsbay/types";
+/**
+ * Reserved route segment for the book rollup. NOT `_`-prefixed: Astro treats
+ * `src/pages/` files/dirs starting with `_` as private (non-routable), so a
+ * `_book.astro` would 404. `~book` is collision-proof instead — `slugify`
+ * strips `~`, so no content slug can ever produce this segment (no slugifier
+ * reservation needed).
+ */
+export declare const BOOK_SEGMENT = "~book";
+export interface AssembleBookOptions {
+    /** Route prefix the nav hrefs carry (e.g. "/docs" or ""); stripped to get slugs. */
+    hrefPrefix?: string;
+    /** Book page title; defaults to the first nav item's label. */
+    title?: string;
+    /** Reserved suffix segment for the rollup route. Default `_book`. */
+    bookSegment?: string;
+}
+export interface BookView {
+    /** The assembled book page (noindex; excluded from nav/sitemap/search/llms). */
+    page: ExportPage;
+    /**
+     * topic slug → its anchor on the book page. Powers the per-topic
+     * "Read as single page" button (`<bookRoute>#<anchor>`).
+     */
+    topicAnchors: Map<string, string>;
+}
+/**
+ * Rough estimate of a TreeNode[]'s textual content size in bytes — the sum of
+ * its prose text, pre-rendered html, and string prop values (code, etc.). Used
+ * as the granularity size cap's input: it tracks source size closely enough to
+ * catch the 10 MB+ rollups (rest_api, installing) that blow up build + DOM,
+ * without a full serialize. See docs-dev/granularity-book-perf.md.
+ */
+export declare function estimateTreeBytes(tree: TreeNode[]): number;
+/**
+ * Assemble one book page from a nav subtree + the topic pages it references.
+ * Returns null when the subtree references no actual pages.
+ */
+export declare function assembleBook(nav: NavItem[], pages: ExportPage[], opts?: AssembleBookOptions): BookView | null;
+/** The "Open as page ↗" affordance — a link from a book section back to its topic page. */
+export declare function openAsPageNode(slug: string, hrefPrefix: string): TreeNode;
+/** A heading node for a nav entry's title, carrying the explicit anchor id. */
+export declare function bookHeading(level: number, title: string, anchor: string): TreeNode;
+/** Shift every heading in a (topic body) tree down by `offset` ranks (max H6). */
+export declare function shiftHeadings(tree: TreeNode[], offset: number): void;
+/**
+ * Rewrite **intra-book** xrefs to in-page anchors so the reader stays in the
+ * book. A link is rewritten iff its target slug is in *this* book's
+ * `topicAnchors` (the "is it in this book?" test). Cross-book links (target not
+ * in the book) and external links are left untouched — they keep pointing at the
+ * canonical topic page, which is correct. Mutates `tree` (already a clone).
+ */
+export declare function rewriteIntraBookLinks(tree: TreeNode[], topicAnchors: Map<string, string>, hrefPrefix: string): void;
+/**
+ * Longest common path prefix (slash-segment-wise) of the member slugs — the
+ * book's base route (e.g. the FT book base `…/16.0`). Falls back to `fallback`.
+ */
+export declare function bookSlugFrom(slugs: string[], fallback: string): string;
+/** Strip the route prefix + leading slash + anchor/query from a nav href → slug. */
+export declare function slugFromHref(href: string | undefined, hrefPrefix: string): string;
+export declare function slugify(text: string): string;

package/dist/granularity.js

@@ -0,0 +1,246 @@
+/**
+ * Reserved route segment for the book rollup. NOT `_`-prefixed: Astro treats
+ * `src/pages/` files/dirs starting with `_` as private (non-routable), so a
+ * `_book.astro` would 404. `~book` is collision-proof instead — `slugify`
+ * strips `~`, so no content slug can ever produce this segment (no slugifier
+ * reservation needed).
+ */
+export const BOOK_SEGMENT = "~book";
+/**
+ * Rough estimate of a TreeNode[]'s textual content size in bytes — the sum of
+ * its prose text, pre-rendered html, and string prop values (code, etc.). Used
+ * as the granularity size cap's input: it tracks source size closely enough to
+ * catch the 10 MB+ rollups (rest_api, installing) that blow up build + DOM,
+ * without a full serialize. See docs-dev/granularity-book-perf.md.
+ */
+export function estimateTreeBytes(tree) {
+    let bytes = 0;
+    const walk = (nodes) => {
+        for (const node of nodes) {
+            const n = node;
+            if (typeof n.html === "string")
+                bytes += n.html.length;
+            if (n.props) {
+                for (const v of Object.values(n.props))
+                    if (typeof v === "string")
+                        bytes += v.length;
+            }
+            if (Array.isArray(n.inline)) {
+                for (const i of n.inline) {
+                    if (typeof i.text === "string")
+                        bytes += i.text.length;
+                    else if (typeof i.value === "string")
+                        bytes += i.value.length;
+                }
+            }
+            if (n.children?.length)
+                walk(n.children);
+        }
+    };
+    walk(tree);
+    return bytes;
+}
+/**
+ * Assemble one book page from a nav subtree + the topic pages it references.
+ * Returns null when the subtree references no actual pages.
+ */
+export function assembleBook(nav, pages, opts = {}) {
+    const hrefPrefix = opts.hrefPrefix ?? "";
+    const bookSegment = opts.bookSegment ?? BOOK_SEGMENT;
+    const bySlug = new Map(pages.map((p) => [p.slug, p]));
+    const topicAnchors = new Map();
+    const memberSlugs = [];
+    const seenAnchor = new Map();
+    const uniqueAnchor = (base) => {
+        const b = base || "section";
+        const n = seenAnchor.get(b) ?? 0;
+        seenAnchor.set(b, n + 1);
+        return n === 0 ? b : `${b}-${n}`;
+    };
+    const ordered = [];
+    const assign = (items, depth) => {
+        for (const item of items) {
+            const level = Math.min(depth + 2, 6);
+            const slug = slugFromHref(item.href, hrefPrefix);
+            const anchor = uniqueAnchor(slugify(slug ? lastSegment(slug) : item.label));
+            ordered.push({ label: item.label, level, slug, anchor });
+            if (slug && bySlug.has(slug)) {
+                topicAnchors.set(slug, anchor);
+                memberSlugs.push(slug);
+            }
+            if (item.children?.length)
+                assign(item.children, depth + 1);
+        }
+    };
+    assign(nav, 0);
+    if (memberSlugs.length === 0)
+        return null;
+    // Pass 2 — assemble: a heading per node, then the topic body (cloned, headings
+    // shifted to nest, and intra-book xrefs rewritten to in-page anchors).
+    const tree = [];
+    for (const { label, level, slug, anchor } of ordered) {
+        tree.push(bookHeading(level, label, anchor));
+        const page = slug ? bySlug.get(slug) : undefined;
+        if (page) {
+            // "Open as page ↗" — the way back from the book to the focused topic.
+            // Pushed OUTSIDE the body so rewriteIntraBookLinks (which runs on the
+            // clone only) doesn't collapse it to an in-page anchor.
+            tree.push(openAsPageNode(slug, hrefPrefix));
+            // Clone so we never mutate the topic page that is also emitted standalone.
+            const body = structuredClone(page.tree);
+            shiftHeadings(body, level - 1);
+            rewriteIntraBookLinks(body, topicAnchors, hrefPrefix);
+            tree.push(...body);
+        }
+    }
+    const title = opts.title ?? nav[0]?.label ?? "Book";
+    const base = bookSlugFrom(memberSlugs, slugify(title));
+    const slug = `${base}/${bookSegment}`;
+    const page = {
+        slug,
+        title,
+        tree,
+        headings: extractBookHeadings(tree),
+        // Quarantine marker — the emitters keep the book out of search / sitemap /
+        // llms and tag it noindex. Kept in frontmatter so it round-trips + is visible.
+        frontmatter: { noindex: true, granularity: "book" },
+    };
+    return { page, topicAnchors };
+}
+// ── pure helpers (ported from format-fluidtopics-rest/single-page.ts) ──────
+/** The "Open as page ↗" affordance — a link from a book section back to its topic page. */
+export function openAsPageNode(slug, hrefPrefix) {
+    const route = hrefPrefix ? `${hrefPrefix}/${slug}` : `/${slug}`;
+    return {
+        type: "paragraph",
+        props: { class: "dsb-open-as-page" },
+        children: [{ type: "prose", inline: [{ type: "link", href: route, children: [{ type: "text", text: "Open as page ↗" }] }] }],
+    };
+}
+/** A heading node for a nav entry's title, carrying the explicit anchor id. */
+export function bookHeading(level, title, anchor) {
+    return {
+        type: "heading",
+        props: { level, slug: anchor, text: title },
+        children: [{ type: "prose", inline: [{ type: "text", text: title }] }],
+    };
+}
+/** Shift every heading in a (topic body) tree down by `offset` ranks (max H6). */
+export function shiftHeadings(tree, offset) {
+    if (offset <= 0)
+        return;
+    for (const n of tree) {
+        if (n.type === "heading") {
+            const lvl = n.props?.level ?? 1;
+            if (!n.props)
+                n.props = {};
+            n.props.level = Math.min(lvl + offset, 6);
+        }
+        if (n.children)
+            shiftHeadings(n.children, offset);
+    }
+}
+/**
+ * Rewrite **intra-book** xrefs to in-page anchors so the reader stays in the
+ * book. A link is rewritten iff its target slug is in *this* book's
+ * `topicAnchors` (the "is it in this book?" test). Cross-book links (target not
+ * in the book) and external links are left untouched — they keep pointing at the
+ * canonical topic page, which is correct. Mutates `tree` (already a clone).
+ */
+export function rewriteIntraBookLinks(tree, topicAnchors, hrefPrefix) {
+    const rewriteInline = (nodes) => {
+        for (const n of nodes) {
+            if (n.type === "link" && typeof n.href === "string") {
+                const slug = slugFromHref(n.href, hrefPrefix);
+                const anchor = slug ? topicAnchors.get(slug) : undefined;
+                if (anchor)
+                    n.href = `#${anchor}`;
+            }
+            if (Array.isArray(n.children))
+                rewriteInline(n.children);
+        }
+    };
+    const walk = (ns) => {
+        for (const n of ns) {
+            if (n.inline)
+                rewriteInline(n.inline);
+            if (n.children)
+                walk(n.children);
+        }
+    };
+    walk(tree);
+}
+/**
+ * Longest common path prefix (slash-segment-wise) of the member slugs — the
+ * book's base route (e.g. the FT book base `…/16.0`). Falls back to `fallback`.
+ */
+export function bookSlugFrom(slugs, fallback) {
+    const parts = slugs.filter(Boolean).map((s) => s.split("/"));
+    if (!parts.length)
+        return fallback;
+    const first = parts[0];
+    let i = 0;
+    for (; i < first.length; i++) {
+        const seg = first[i];
+        if (!parts.every((p) => p[i] === seg))
+            break;
+    }
+    return first.slice(0, i).join("/") || fallback;
+}
+/** Strip the route prefix + leading slash + anchor/query from a nav href → slug. */
+export function slugFromHref(href, hrefPrefix) {
+    if (!href)
+        return "";
+    let s = href.split("#")[0].split("?")[0].trim();
+    if (hrefPrefix && s.startsWith(hrefPrefix))
+        s = s.slice(hrefPrefix.length);
+    return s.replace(/^\/+/, "").replace(/\/+$/, "");
+}
+function lastSegment(slug) {
+    return slug.split("/").pop() ?? slug;
+}
+/** Collect Heading[] from an assembled tree (nodes already carry props.slug/level/text). */
+function extractBookHeadings(tree) {
+    const out = [];
+    const walk = (ns) => {
+        for (const n of ns) {
+            if (n.type === "heading") {
+                out.push({
+                    depth: n.props?.level ?? 1,
+                    slug: n.props?.slug ?? "",
+                    text: n.props?.text ?? inlineText(n),
+                });
+            }
+            if (n.children)
+                walk(n.children);
+        }
+    };
+    walk(tree);
+    return out;
+}
+function inlineText(node) {
+    const parts = [];
+    const fromInline = (ns = []) => {
+        for (const n of ns) {
+            if (typeof n.text === "string")
+                parts.push(n.text);
+            else if (Array.isArray(n.children))
+                fromInline(n.children);
+        }
+    };
+    if (node.inline)
+        fromInline(node.inline);
+    if (node.children)
+        for (const c of node.children)
+            parts.push(inlineText(c));
+    return parts.join("").trim();
+}
+export function slugify(text) {
+    return (text
+        .toLowerCase()
+        .replace(/[^\w\s-]/g, "")
+        .replace(/\s+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .trim() || "section");
+}

package/dist/head-metadata.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Head metadata per page (dogsbay-ssg plans/head-metadata.md, Blume item 2):
+ * whether it is a home page (JSON-LD `WebSite`, og:type website), its
+ * `hreflang` alternates across languages, and its nav trail for JSON-LD
+ * `BreadcrumbList`. The builders are @dogsbay/site-files', shared with
+ * dogsbay-ssg; this file finds the inputs in the imported pages and the nav.
+ */
+import type { ExportPage, NavItem } from "@dogsbay/types";
+import { type HreflangLink } from "@dogsbay/site-files";
+export interface HeadMetadata {
+    home: boolean;
+    alternates: HreflangLink[];
+    breadcrumbJsonLd?: Record<string, unknown>;
+}
+export interface HeadMetadataOptions {
+    siteUrl?: string;
+    /** urlBase + basePath, as the sitemap takes it. */
+    basePath?: string;
+    defaultLocale?: string;
+    /** Pages the build writes (not fragments or excluded routes); others are never an alternate. Drafts and redirects are left out as well. */
+    isEmitted?: (p: ExportPage) => boolean;
+    /** Pages that list alternates: their own canonical and indexable (hreflang between non-canonical URLs is ignored by search engines). */
+    indexable?: (p: ExportPage) => boolean;
+}
+export declare function headMetadata(pages: ExportPage[], nav: NavItem[], o: HeadMetadataOptions): Map<string, HeadMetadata>;

package/dist/head-metadata.js

@@ -0,0 +1,55 @@
+import { buildBreadcrumbJsonLd, buildHreflangLinks } from "@dogsbay/site-files";
+import { normalizePrefix, originOf, pageHref } from "./sitemap.js";
+/** Path inside the page's source (`guide/install`), `index` for a home page. */
+function inside(p) {
+    const orig = (p.multiSource?.originalSlug ?? p.slug).replace(/^\/+|\/+$/g, "");
+    return orig === "" || orig === "index" ? "index" : orig.replace(/\/index$/, "");
+}
+export function headMetadata(pages, nav, o) {
+    const plan = new Map();
+    const live = (p) => !p.redirect && p.frontmatter?.draft !== true && p.frontmatter?.status !== "draft" && (o.isEmitted?.(p) ?? true);
+    const prefix = normalizePrefix(o.basePath);
+    const origin = o.siteUrl && /^https?:\/\//.test(o.siteUrl) ? originOf(o.siteUrl).replace(/\/+$/, "") : undefined;
+    const url = (slug) => (origin ? `${origin}${pageHref(slug, prefix)}` : undefined);
+    // Copies of one page across languages: same namespace, version and path inside the source.
+    const copies = new Map();
+    const locales = new Set(pages.map((p) => p.multiSource?.locale).filter(Boolean));
+    if (origin && locales.size >= 2) {
+        for (const p of pages) {
+            const m = p.multiSource;
+            if (!m?.locale || !live(p))
+                continue;
+            const key = `${m.namespace ?? ""}\0${m.version ?? ""}\0${inside(p)}`;
+            const list = copies.get(key) ?? [];
+            list.push({ lang: m.locale, url: url(p.slug) });
+            copies.set(key, list);
+        }
+    }
+    // The nav trail to each page: labels and hrefs from the top level down.
+    const trails = new Map();
+    const clean = (href) => href.replace(/[?#].*$/, "").replace(/^\/+|\/+$/g, "").replace(/(^|\/)index$/, "");
+    const mount = prefix.replace(/^\/+/, "");
+    const key = (href) => {
+        const h = clean(href);
+        return mount && (h === mount || h.startsWith(`${mount}/`)) ? h.slice(mount.length).replace(/^\/+/, "") : h;
+    };
+    const walk = (items, chain) => {
+        for (const it of items) {
+            const here = [...chain, { name: it.label, href: it.href }];
+            if (it.href && !/^[a-z][a-z0-9+.-]*:/i.test(it.href) && !it.href.includes("#") && !trails.has(key(it.href)))
+                trails.set(key(it.href), here);
+            if (it.children?.length)
+                walk(it.children, here);
+        }
+    };
+    walk(nav, []);
+    for (const p of pages) {
+        const home = inside(p) === "index";
+        const m = p.multiSource;
+        const alternates = m?.locale && live(p) && (o.indexable?.(p) ?? true) ? buildHreflangLinks(copies.get(`${m.namespace ?? ""}\0${m.version ?? ""}\0${inside(p)}`) ?? [], o.defaultLocale) : [];
+        const trail = origin && !home ? trails.get(clean(p.slug)) : undefined;
+        const breadcrumbJsonLd = trail ? buildBreadcrumbJsonLd(trail.map((t) => ({ name: t.name, url: t.href ? url(key(t.href)) : undefined }))) : undefined;
+        plan.set(p.slug, { home, alternates, ...(breadcrumbJsonLd ? { breadcrumbJsonLd } : {}) });
+    }
+    return plan;
+}

package/dist/index.d.ts

@@ -1,16 +1,36 @@
 export { treeToAstro, escapeExpr, escapeAttr, escapeTemplate } from "./serialize.js";
-export { detectLeadingNodes } from "./lead.js";
+export { writeFileSync, copyFileSync } from "./write-if-changed.js";
+export { ASTRO_CAPABILITIES } from "./capabilities.js";
+export { detectLeadingNodes, deriveDescription } from "./lead.js";
 export type { LeadingNodeInfo } from "./lead.js";
 export type { AstroGenResult, AstroGenOptions, AstroRenderMode } from "./serialize.js";
-export { DEFAULT_BASE_PATH, normalizeBasePath, basePathSegments, joinBaseUrl, buildCurrentPath, } from "./base-path.js";
+export { DEFAULT_BASE_PATH, normalizeBasePath, basePathSegments, joinBaseUrl, buildCurrentPath, parseSiteUrl, combinePrefix, resolvePrefixes, } from "./base-path.js";
 export { buildLlmsTxt, buildSectionLlmsTxt, buildLlmsFullTxt, extractFirstParagraph, } from "./llms-txt.js";
 export type { BuildLlmsTxtOptions, BuildLlmsFullTxtOptions, } from "./llms-txt.js";
-export { buildSitemap, buildSitemapIndex } from "./sitemap.js";
+export { assertLeafSitemap, buildSitemap, buildSitemapFiles, buildSitemapIndex } from "./sitemap.js";
+export { buildBlogData, blogAdjacency, emitBlogFiles, indexPageCount, readingMinutes, countWords, BLOG_DEFAULTS, } from "./blog.js";
+export type { BlogEmitConfig, BlogData, BlogPostRef, BlogAdjacency, } from "./blog.js";
 export type { BuildSitemapOptions } from "./sitemap.js";
-export { exportAstroProject, emitSiteScaffold, emitSiteConfig, emitAstroPages, emitConfigDerivedFiles, emitAgentReadinessFiles, emitSwitcherMap, emitMissingTranslationStubs, } from "./project.js";
-export type { AstroProjectOptions, SwitcherMap } from "./project.js";
+export { exportAstroProject, emitSiteScaffold, emitSiteConfig, emitAstroPages, emitConfigDerivedFiles, syncSiteDependencies, copyComponents, emitAgentReadinessFiles, emitSwitcherMap, emitMissingTranslationStubs, emitPassthroughAstroPages, emitDeployArtifacts, workersSubpathOutDir, makeSlugExcluder, dropUnsafeNavHrefs, } from "./project.js";
+export type { AstroProjectOptions, SwitcherMap, PassthroughCopy, } from "./project.js";
 export { emitPluginRuntime } from "./plugins.js";
 export type { EmitPluginRuntimeOptions, PluginClientModulesGroup, PluginStylesGroup, PluginClientConfig, } from "./plugins.js";
 export { buildTaxonomyData, emitTaxonomyForName, emitTaxonomyRoutes, getPageTerms, } from "./taxonomy.js";
 export type { TaxonomyEmitConfig, TaxonomyTerm, TaxonomyPageRef, TaxonomyData, } from "./taxonomy.js";
-//# sourceMappingURL=index.d.ts.map
+export { DIFF_CSS, decorateDiff, diffMarksOf, hasDiffMarks, injectAttrs, inlineSegmentsToHtml, } from "./diff-decoration.js";
+export type { DiffMarks } from "./diff-decoration.js";
+/**
+ * Granularity book view — assemble a nav subtree into one page.
+ *
+ * Exported because it is the PLATFORM generalization of the same algorithm
+ * `format-fluidtopics-rest/src/single-page.ts` implements against khub TOCs:
+ * without an export, no other package could reach it, which is a large part of
+ * why the fold described in that module never happened.
+ *
+ * See plans/granularity-views.md and docs/single-page-view.md.
+ */
+export { BOOK_SEGMENT, assembleBook, bookHeading, bookSlugFrom, estimateTreeBytes, openAsPageNode, rewriteIntraBookLinks, shiftHeadings, slugFromHref, } from "./granularity.js";
+export type { AssembleBookOptions, BookView } from "./granularity.js";
+export { pageUnitPrefix, inPageUnit, normalizeTarget, collectRedirects } from "./redirects.js";
+export { canonicalPlan } from "./canonical.js";
+export { TONES, CARD_TONE_CLASSES, TAB_VARIANTS, THEME_SCOPES } from "./tone-classes.js";

package/dist/index.js

@@ -1,18 +1,25 @@
 // Astro serializer (TreeNode[] → Astro component markup)
 export { treeToAstro, escapeExpr, escapeAttr, escapeTemplate } from "./serialize.js";
+export { writeFileSync, copyFileSync } from "./write-if-changed.js";
+// Component × format matrix: what the page output represents, per TreeNode type.
+export { ASTRO_CAPABILITIES } from "./capabilities.js";
 // Auto-lede detection — figures out whether a page tree already
 // has a leading H1 / paragraph so format-astro can decide whether
 // to inject frontmatter title + description at the top of <main>.
 // See plans/auto-lede.md.
-export { detectLeadingNodes } from "./lead.js";
+export { detectLeadingNodes, deriveDescription } from "./lead.js";
 // Base-path helpers — single source of truth for the `basePath` URL
 // prefix shared across project / nav / llms-txt / taxonomy emitters.
 // See plans/configurable-base-path.md.
-export { DEFAULT_BASE_PATH, normalizeBasePath, basePathSegments, joinBaseUrl, buildCurrentPath, } from "./base-path.js";
+export { DEFAULT_BASE_PATH, normalizeBasePath, basePathSegments, joinBaseUrl, buildCurrentPath, parseSiteUrl, combinePrefix, resolvePrefixes, } from "./base-path.js";
 // llms.txt + llms-full.txt builders (LLM discovery files)
 export { buildLlmsTxt, buildSectionLlmsTxt, buildLlmsFullTxt, extractFirstParagraph, } from "./llms-txt.js";
 // Sitemap builders (per-mount, sitemaps.org 0.9)
-export { buildSitemap, buildSitemapIndex } from "./sitemap.js";
+export { assertLeafSitemap, buildSitemap, buildSitemapFiles, buildSitemapIndex } from "./sitemap.js";
+// Blog emission — reverse-chron index + post adjacency. The sibling of
+// taxonomy.ts: same data-file + generated-route + writer-override shape,
+// sorted by date instead of grouped by term. See plans/blog-capability.md.
+export { buildBlogData, blogAdjacency, emitBlogFiles, indexPageCount, readingMinutes, countWords, BLOG_DEFAULTS, } from "./blog.js";
 // Project export — orchestrator + per-tier emitters
 //
 // `exportAstroProject` is the high-level entry: generates a complete
@@ -24,7 +31,14 @@ export { buildSitemap, buildSitemapIndex } from "./sitemap.js";
 // alone; `dogsbay site build` calls `emitAstroPages` +
 // `emitConfigDerivedFiles` + `emitAgentReadinessFiles`. Pure
 // `dogsbay convert --to astro` (Step 7) calls only `emitAstroPages`.
-export { exportAstroProject, emitSiteScaffold, emitSiteConfig, emitAstroPages, emitConfigDerivedFiles, emitAgentReadinessFiles, emitSwitcherMap, emitMissingTranslationStubs, } from "./project.js";
+export { exportAstroProject, emitSiteScaffold, emitSiteConfig, emitAstroPages, emitConfigDerivedFiles, syncSiteDependencies, copyComponents, emitAgentReadinessFiles, emitSwitcherMap, emitMissingTranslationStubs, emitPassthroughAstroPages, emitDeployArtifacts, 
+// Where a Workers subpath-mounted build actually lands. Consumers that
+// read the BUILT site (e.g. `dogsbay site check --dist`) must resolve
+// the same directory the emitter told Astro to write to, or they audit
+// an empty dist/ root.
+workersSubpathOutDir, makeSlugExcluder, 
+// Drops nav hrefs with a scheme other than http(s)/mailto/tel.
+dropUnsafeNavHrefs, } from "./project.js";
 // Plugin runtime codegen — emits the entry, virtual config modules,
 // stylesheets, and Vite alias file each plugin needs to participate
 // in the Astro / Vite build. See plans/plugin-api.md.
@@ -33,4 +47,19 @@ export { emitPluginRuntime } from "./plugins.js";
 // Per declared taxonomy in `dogsbay.config.yml`'s `taxonomies:` block,
 // emits a JSON data file + index/term .astro route files.
 export { buildTaxonomyData, emitTaxonomyForName, emitTaxonomyRoutes, getPageTerms, } from "./taxonomy.js";
-//# sourceMappingURL=index.js.map
+export { DIFF_CSS, decorateDiff, diffMarksOf, hasDiffMarks, injectAttrs, inlineSegmentsToHtml, } from "./diff-decoration.js";
+/**
+ * Granularity book view — assemble a nav subtree into one page.
+ *
+ * Exported because it is the PLATFORM generalization of the same algorithm
+ * `format-fluidtopics-rest/src/single-page.ts` implements against khub TOCs:
+ * without an export, no other package could reach it, which is a large part of
+ * why the fold described in that module never happened.
+ *
+ * See plans/granularity-views.md and docs/single-page-view.md.
+ */
+export { BOOK_SEGMENT, assembleBook, bookHeading, bookSlugFrom, estimateTreeBytes, openAsPageNode, rewriteIntraBookLinks, shiftHeadings, slugFromHref, } from "./granularity.js";
+export { pageUnitPrefix, inPageUnit, normalizeTarget, collectRedirects } from "./redirects.js";
+export { canonicalPlan } from "./canonical.js";
+// Variants, tones and scoped themes: the class tables both renderers draw from
+export { TONES, CARD_TONE_CLASSES, TAB_VARIANTS, THEME_SCOPES } from "./tone-classes.js";