@dogsbay/format-fluidtopics-rest 0.2.0-beta.101

package/README.md

@@ -0,0 +1,87 @@
+# @dogsbay/format-fluidtopics-rest
+
+Importer for a **live Fluid Topics portal** via the public **khub REST API**
+(Option B of the FT→Dogsbay migration). It reverse-engineers each topic's
+**DITA-OT HTML5** — where the DITA element vocabulary survives in `class` names
+(`conbody`/`taskbody`/`refbody`, `shortdesc`, `section`, CALS tables, `span.ph`,
+…) — into Dogsbay's universal `TreeNode` model, producing `ExportPage[]` +
+`NavItem[]`.
+
+Works on any **public** FT portal. Gated portals (RBAC) throw `KhubAuthError`.
+
+The sibling [`@dogsbay/format-fluidtopics-markdown`](../format-fluidtopics-markdown)
+does the same job from a Git Markdown export (Option A).
+
+## Usage
+
+```ts
+import { importFluidTopicsRest } from "@dogsbay/format-fluidtopics-rest";
+
+const { pages, nav } = await importFluidTopicsRest({
+  portalBase: "https://www.servicenow.com/docs", // or .../bas, docs.fluidtopics.com
+  titleFilter: "Customer Relationship Management", // or maps: ["<mapId>"]
+  hrefPrefix: "/docs",
+});
+```
+
+Or the low-level converter / client:
+
+```ts
+import { htmlToTree, KhubClient } from "@dogsbay/format-fluidtopics-rest";
+const { tree, title, topicType } = htmlToTree(htmlString); // topicType: concept|task|reference|topic
+```
+
+CLI: `dogsbay migrate-fluidtopics-rest <portal-url> [--map <id>] [--title-filter <s>] [--single-page] [-o <dir>]`.
+
+### Single-page (whole-book) mode
+
+Pass `--single-page` / `singlePage: true` to roll each map into **one page** (the
+whole book) instead of one page per topic — for readers who prefer a single long
+page over "bitty" topics, and to match FT portals that serve a book as one page.
+TOC nodes become nested headings (level = TOC depth), internal xrefs become
+in-page anchors, and the page lands at the book's common path prefix
+(e.g. `…/metasys-ui-and-jct-technical-bulletin/16.0`).
+
+## What it does
+
+- **khub harvest** — `maps` → `maps/{id}/toc` → `maps/{id}/topics/{cid}/content`; path-scoped bases (`…/bas/api/khub`); polite throttling; 401/403 → `KhubAuthError`.
+- **HTML5 → TreeNode** — topic type from the body class; DITA sections flattened to headings; CALS tables → structured `table` nodes; `span.ph`/`keyword`/`uicontrol` unwrapped, `codeph` → inline code; FT chrome (`zDocs*`, `ai-summary`, `sentence`, `css-…`, `toggle/summary/tooltip`) stripped.
+- **Frontmatter** — `topic_type` → `type`, plus `lang`/`version` from the map metadata.
+- **Nav** — from each map's TOC (the authoritative DITA map), with route slugs derived from `prettyUrl`.
+
+## Rendering fidelity
+
+Tuned against the live FT portals; each item is regression-tested. Full story in
+[`docs-dev/fluidtopics-rest-importer.md`](../../docs-dev/fluidtopics-rest-importer.md).
+
+- **Internal xrefs** — FT renders them as hrefless `<span data-tocid data-mapid>`
+  (resolved by its client at runtime, zero `href`s in the static HTML). The
+  importer builds a `tocId → slug` index from the selected maps' TOCs and resolves
+  them to real routes, falling back to plain text (not a dead link) when out of set.
+- **Figures / inline images** — block `<img>` survive; base64 `data:` images are
+  extracted to real `content/_assets/…` files (filename from FT metadata).
+- **Lists & inline runs** — consecutive inline content is coalesced into one
+  paragraph, so xrefs inside list items resolve and prose doesn't fragment.
+- **Tables** — CALS → structured tables; cells with block content (lists,
+  paragraphs) are preserved (HTML tables per the Dogsbay-MD convention).
+- **Definition lists** — `<dl>/<dt>/<dd>` → a real deflist (`dt.inline` term + `dd`
+  block children), not literal `: ` text.
+
+## Verified (live, 2026-06)
+
+ServiceNow `www.servicenow.com/docs` (CRM, 24 topics), Johnson Controls
+`docs.johnsoncontrols.com/bas` (Metasys bulletin, 55), Fluid Topics
+`docs.fluidtopics.com` (13). Notably, REST succeeds on ServiceNow's CRM
+publication where the **Markdown export (Option A) failed** (its `index.md` TOC
+was stale: 1/24 targets existed) — the live khub TOC+content is authoritative.
+
+## Known gaps
+
+- Nav-card landing grids come through as a generic table (Option A special-cases
+  them into `:::cards`) — a `nav-card`-detection pass is future work.
+- **Cross-map** xrefs resolve only when the target map is in the import set
+  (single-`--map` runs leave them as text).
+- External image **URLs** are kept as-is (not downloaded); only inline `data:`
+  images are localized to `_assets`.
+- conref/keyref/profiling were already resolved/flattened upstream by FT's
+  DITA-OT run (not recoverable, and not needed for delivery).

package/dist/assets.d.ts

@@ -0,0 +1,13 @@
+export interface ParsedDataUri {
+    mime: string;
+    data: Buffer;
+}
+/** Parse a `data:` URI into its mime + decoded bytes. Returns null if not one. */
+export declare function parseDataUri(src: string): ParsedDataUri | null;
+export declare function sanitizeFilename(name: string): string;
+/**
+ * Compute the content-relative asset path (`_assets/<dir>/<file>`) for a
+ * decoded image, using the FT display-name as the filename.
+ */
+export declare function assetPath(resourceId: string | undefined, displayName: string | undefined, parsed: ParsedDataUri): string;
+//# sourceMappingURL=assets.d.ts.map

package/dist/assets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assets.d.ts","sourceRoot":"","sources":["../src/assets.ts"],"names":[],"mappings":"AAuBA,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,kFAAkF;AAClF,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAQ9D;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQrD;AAED;;;GAGG;AACH,wBAAgB,SAAS,CACvB,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,MAAM,EAAE,aAAa,GACpB,MAAM,CAOR"}

package/dist/assets.js

@@ -0,0 +1,53 @@
+/**
+ * Turn inline `data:` images (FT inlines figure PNGs / SVG icons as base64) into
+ * real content-rooted asset files, per the Dogsbay `_assets` convention:
+ * bytes written under `content/_assets/<rel>/<file>` and referenced as
+ * `/_assets/<rel>/<file>` (format-astro's copyAssets propagates them to
+ * astro/public on build).
+ *
+ * The human filename comes from FT metadata (`data-ft-asset-display-name`); the
+ * directory is an 8-char hash of the FT `data-ft-resource-id` (stable + dedups
+ * the same resource reused across topics) or, lacking that, of the bytes.
+ */
+import { createHash } from "node:crypto";
+const EXT_BY_MIME = {
+    "image/png": "png",
+    "image/jpeg": "jpg",
+    "image/jpg": "jpg",
+    "image/gif": "gif",
+    "image/svg+xml": "svg",
+    "image/webp": "webp",
+    "image/avif": "avif",
+};
+/** Parse a `data:` URI into its mime + decoded bytes. Returns null if not one. */
+export function parseDataUri(src) {
+    const m = /^data:([^;,]+)(;base64)?,([\s\S]*)$/.exec(src);
+    if (!m)
+        return null;
+    const mime = m[1];
+    const isBase64 = !!m[2];
+    const payload = m[3];
+    const data = isBase64 ? Buffer.from(payload, "base64") : Buffer.from(decodeURIComponent(payload), "utf-8");
+    return { mime, data };
+}
+export function sanitizeFilename(name) {
+    return (name
+        .trim()
+        .replace(/[^\w.\-]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^[-.]+|[-.]+$/g, "") || "image");
+}
+/**
+ * Compute the content-relative asset path (`_assets/<dir>/<file>`) for a
+ * decoded image, using the FT display-name as the filename.
+ */
+export function assetPath(resourceId, displayName, parsed) {
+    const ext = EXT_BY_MIME[parsed.mime] ?? "bin";
+    let file = displayName ? sanitizeFilename(displayName) : "";
+    if (!file || !/\.[a-z0-9]+$/i.test(file))
+        file = `${file || "image"}.${ext}`;
+    const key = resourceId || createHash("sha1").update(parsed.data).digest("hex");
+    const dir = createHash("sha1").update(key).digest("hex").slice(0, 8);
+    return `_assets/${dir}/${file}`;
+}
+//# sourceMappingURL=assets.js.map

package/dist/assets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assets.js","sourceRoot":"","sources":["../src/assets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,MAAM,WAAW,GAA2B;IAC1C,WAAW,EAAE,KAAK;IAClB,YAAY,EAAE,KAAK;IACnB,WAAW,EAAE,KAAK;IAClB,WAAW,EAAE,KAAK;IAClB,eAAe,EAAE,KAAK;IACtB,YAAY,EAAE,MAAM;IACpB,YAAY,EAAE,MAAM;CACrB,CAAC;AAOF,kFAAkF;AAClF,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,MAAM,CAAC,GAAG,qCAAqC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC1D,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAClB,MAAM,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACxB,MAAM,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACrB,MAAM,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC;IAC3G,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACxB,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,CACL,IAAI;SACD,IAAI,EAAE;SACN,OAAO,CAAC,YAAY,EAAE,GAAG,CAAC;SAC1B,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;SACnB,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC,IAAI,OAAO,CAC5C,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CACvB,UAA8B,EAC9B,WAA+B,EAC/B,MAAqB;IAErB,MAAM,GAAG,GAAG,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC;IAC9C,IAAI,IAAI,GAAG,WAAW,CAAC,CAAC,CAAC,gBAAgB,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5D,IAAI,CAAC,IAAI,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,IAAI,GAAG,GAAG,IAAI,IAAI,OAAO,IAAI,GAAG,EAAE,CAAC;IAC7E,MAAM,GAAG,GAAG,UAAU,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC/E,MAAM,GAAG,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACrE,OAAO,WAAW,GAAG,IAAI,IAAI,EAAE,CAAC;AAClC,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,9 @@
+import type { FormatPlugin } from "@dogsbay/types";
+/**
+ * Fluid Topics REST format plugin.
+ *
+ * Import-only; the "source" is a **portal URL** (not a local path), so it's
+ * driven by the `migrate-fluidtopics-rest` command rather than path auto-detect.
+ */
+export declare const plugin: FormatPlugin;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAuB,MAAM,gBAAgB,CAAC;AAGxE;;;;;GAKG;AACH,eAAO,MAAM,MAAM,EAAE,YAoBpB,CAAC"}

package/dist/cli.js

@@ -0,0 +1,28 @@
+import { importFluidTopicsRest } from "./importer.js";
+/**
+ * Fluid Topics REST format plugin.
+ *
+ * Import-only; the "source" is a **portal URL** (not a local path), so it's
+ * driven by the `migrate-fluidtopics-rest` command rather than path auto-detect.
+ */
+export const plugin = {
+    name: "fluidtopics-rest",
+    canImport: true,
+    canExport: false,
+    detectSource: () => false, // URL source — invoked explicitly
+    importOptions: [],
+    async import(source, opts) {
+        const { pages, nav } = await importFluidTopicsRest({
+            portalBase: source,
+            maps: Array.isArray(opts.maps) ? opts.maps : undefined,
+            titleFilter: typeof opts.titleFilter === "string" ? opts.titleFilter : undefined,
+            lang: typeof opts.lang === "string" ? opts.lang : undefined,
+            hrefPrefix: typeof opts.hrefPrefix === "string" ? opts.hrefPrefix : undefined,
+            throttleMs: typeof opts.throttleMs === "number" ? opts.throttleMs : undefined,
+            taxonomyNames: Array.isArray(opts.taxonomyNames) ? opts.taxonomyNames : undefined,
+        });
+        opts.siteName = opts.siteName || "Documentation";
+        return { pages, nav };
+    },
+};
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAEtD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,MAAM,GAAiB;IAClC,IAAI,EAAE,kBAAkB;IACxB,SAAS,EAAE,IAAI;IACf,SAAS,EAAE,KAAK;IAChB,YAAY,EAAE,GAAG,EAAE,CAAC,KAAK,EAAE,kCAAkC;IAC7D,aAAa,EAAE,EAAE;IAEjB,KAAK,CAAC,MAAM,CAAC,MAAc,EAAE,IAA6B;QACxD,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,MAAM,qBAAqB,CAAC;YACjD,UAAU,EAAE,MAAM;YAClB,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAE,IAAI,CAAC,IAAiB,CAAC,CAAC,CAAC,SAAS;YACpE,WAAW,EAAE,OAAO,IAAI,CAAC,WAAW,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS;YAChF,IAAI,EAAE,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;YAC3D,UAAU,EAAE,OAAO,IAAI,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS;YAC7E,UAAU,EAAE,OAAO,IAAI,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS;YAC7E,aAAa,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,CAAE,IAAI,CAAC,aAA0B,CAAC,CAAC,CAAC,SAAS;SAChG,CAAC,CAAC;QACH,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,eAAe,CAAC;QACjD,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;IACxB,CAAC;CACF,CAAC"}

package/dist/frontmatter.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Build Dogsbay frontmatter for a topic from the DITA-OT-derived topic type
+ * plus the map's khub metadata (locale, release/family).
+ */
+import type { KhubMap } from "./khub.js";
+type Meta = NonNullable<KhubMap["metadata"]>;
+export interface BuildFrontmatterArgs {
+    title: string;
+    /** concept | task | reference | glossentry | topic */
+    topicType: string;
+    mapMeta?: Meta;
+    /**
+     * Per-topic metadata (from `/maps/{id}/topics`). When present its values take
+     * precedence over `mapMeta` — topic-level facets are more specific than the
+     * map's. The DITA subjectScheme classification arrives here as the `PBS`
+     * ("Subject matter") facet.
+     */
+    topicMeta?: Meta;
+    /**
+     * Extra FT metadata keys to copy into frontmatter, kept **verbatim** (the
+     * `ft:` prefix is preserved to namespace them). Allowlist, not blocklist: the
+     * internal `ft:` keys never land unless explicitly named here.
+     */
+    metadataAllow?: readonly string[];
+    /**
+     * Emit the `ft:`-namespaced technical numerics (wordCount/contentSize/…).
+     * True for book/single-page pages (the map totals are correct there) and for
+     * per-topic pages only when full per-topic metadata was fetched. Off on the
+     * cheap per-topic path, where the only available values are misleading book
+     * totals.
+     */
+    technical?: boolean;
+}
+export declare function buildFrontmatter(args: BuildFrontmatterArgs): Record<string, unknown>;
+export {};
+//# sourceMappingURL=frontmatter.d.ts.map

package/dist/frontmatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../src/frontmatter.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,KAAK,IAAI,GAAG,WAAW,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC;AAmB7C,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,IAAI,CAAC;IACf;;;;;OAKG;IACH,SAAS,CAAC,EAAE,IAAI,CAAC;IACjB;;;;OAIG;IACH,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,oBAAoB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAkDpF"}

package/dist/frontmatter.js

@@ -0,0 +1,78 @@
+/**
+ * FT technical metadata kept verbatim under the `ft:` namespace (as numbers) so
+ * they sit apart from the semantic facets. `wordCount`/`outputSize` are
+ * per-topic; `contentSize`/`attachmentsSize` are map-level (so they repeat
+ * across a book's topics).
+ */
+const TECHNICAL_KEYS = ["ft:wordCount", "ft:contentSize", "ft:outputSize", "ft:attachmentsSize"];
+function metaValue(meta, ...keys) {
+    if (!meta)
+        return undefined;
+    for (const key of keys) {
+        const hit = meta.find((m) => m.key === key);
+        if (hit?.values?.length)
+            return hit.values[0];
+    }
+    return undefined;
+}
+export function buildFrontmatter(args) {
+    const fm = { title: args.title };
+    // Prefer the per-topic value, fall back to the map's.
+    const mv = (...keys) => metaValue(args.topicMeta, ...keys) ?? metaValue(args.mapMeta, ...keys);
+    // topic_type → type (skip the generic "topic")
+    if (args.topicType && args.topicType !== "topic")
+        fm.type = args.topicType;
+    const locale = mv("ft:locale", "locale");
+    if (locale)
+        fm.lang = locale;
+    const version = mv("family", "version", "ft:version", "Version_FT", "FT_Version");
+    if (version)
+        fm.version = version;
+    // Faceted metadata → search filters (Pagefind auto-discovers the
+    // `data-pagefind-filter` divs DocsLayout emits from these fields).
+    // `category` / `audience` are built-in facets (parseMeta reads them
+    // directly); `editorialType` / `version` / `subject` are custom taxonomies
+    // the importer's `taxonomyNames` picks up. See docs-dev/fluidtopics-rest-importer.md.
+    const category = mv("Category");
+    if (category)
+        fm.category = category;
+    const audience = mv("audience");
+    if (audience)
+        fm.audience = audience;
+    const editorialType = mv("ft:editorialType");
+    if (editorialType)
+        fm.editorialType = editorialType;
+    // DITA subjectScheme classification → "Subject matter" facet.
+    const subject = mv("PBS");
+    if (subject)
+        fm.subject = subject;
+    const product = mv("Product");
+    if (product)
+        fm.product = product;
+    const author = mv("author");
+    if (author)
+        fm.author = author;
+    const source = mv("ft:sourceName");
+    if (source)
+        fm.source = source;
+    // Last content change → DocsFooter "Last updated". Per-topic only: it lives
+    // solely in the full per-topic metadata, so it's absent on the cheap path
+    // (we deliberately don't fall back to the book-level ft:lastEdition).
+    const updated = metaValue(args.topicMeta, "ft:lastTechChange");
+    if (updated)
+        fm.updated = updated;
+    // Technical fields (only where the values are meaningful — see `technical`),
+    // plus any --metadata extras (always): kept under the `ft:` namespace,
+    // verbatim, coerced to number when numeric.
+    const keys = [...(args.technical ? TECHNICAL_KEYS : []), ...(args.metadataAllow ?? [])];
+    for (const key of keys) {
+        if (key in fm)
+            continue;
+        const v = mv(key);
+        if (v === undefined)
+            continue;
+        fm[key] = /^\d+$/.test(v) ? Number(v) : v;
+    }
+    return fm;
+}
+//# sourceMappingURL=frontmatter.js.map

package/dist/frontmatter.js.map

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

package/dist/headings.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Heading extraction + slug population.
+ *
+ * Walks the tree, computes a stable slug for each heading (de-duplicated),
+ * writes `slug`/`text` back onto the heading node's props (so the renderer
+ * can emit anchors), and returns the flat Heading[] for TOC generation.
+ */
+import type { TreeNode, Heading } from "@dogsbay/types";
+export declare function extractHeadings(tree: TreeNode[]): Heading[];
+/** Extract plain text from a node, preferring structured inline content. */
+export declare function extractText(node: TreeNode): string;
+export declare function slugify(text: string): string;
+//# sourceMappingURL=headings.d.ts.map

package/dist/headings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"headings.d.ts","sourceRoot":"","sources":["../src/headings.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAc,MAAM,gBAAgB,CAAC;AAEpE,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,OAAO,EAAE,CA6B3D;AAED,4EAA4E;AAC5E,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAWlD;AAyBD,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAU5C"}

package/dist/headings.js

@@ -0,0 +1,76 @@
+export function extractHeadings(tree) {
+    const headings = [];
+    const seen = new Map();
+    function walk(nodes) {
+        for (const node of nodes) {
+            if (node.type === "heading") {
+                const level = node.props?.level ?? 1;
+                const text = extractText(node);
+                let slug = node.props?.slug;
+                if (!slug) {
+                    const base = slugify(text);
+                    const count = seen.get(base) ?? 0;
+                    slug = count === 0 ? base : `${base}-${count}`;
+                    seen.set(base, count + 1);
+                }
+                if (!node.props)
+                    node.props = {};
+                node.props.slug = slug;
+                node.props.text = text;
+                headings.push({ depth: level, slug, text });
+            }
+            if (node.children)
+                walk(node.children);
+        }
+    }
+    walk(tree);
+    return headings;
+}
+/** Extract plain text from a node, preferring structured inline content. */
+export function extractText(node) {
+    const parts = [];
+    if (node.inline) {
+        parts.push(extractInlineText(node.inline));
+    }
+    else if (node.html) {
+        parts.push(node.html.replace(/<[^>]+>/g, ""));
+    }
+    if (node.children) {
+        for (const child of node.children)
+            parts.push(extractText(child));
+    }
+    return parts.filter(Boolean).join(" ").trim();
+}
+function extractInlineText(nodes) {
+    const parts = [];
+    for (const node of nodes) {
+        switch (node.type) {
+            case "text":
+            case "code":
+                parts.push(node.text);
+                break;
+            case "link":
+            case "highlight":
+                parts.push(extractInlineText(node.children));
+                break;
+            case "image":
+                if (node.alt)
+                    parts.push(node.alt);
+                break;
+            case "html-inline":
+                parts.push(node.html.replace(/<[^>]+>/g, ""));
+                break;
+        }
+    }
+    return parts.join("");
+}
+export function slugify(text) {
+    return (text
+        .toLowerCase()
+        .replace(/[^\w\s-]/g, "")
+        .replace(/\s+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .trim() || "section");
+}
+//# sourceMappingURL=headings.js.map

package/dist/headings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"headings.js","sourceRoot":"","sources":["../src/headings.ts"],"names":[],"mappings":"AASA,MAAM,UAAU,eAAe,CAAC,IAAgB;IAC9C,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,MAAM,IAAI,GAAG,IAAI,GAAG,EAAkB,CAAC;IAEvC,SAAS,IAAI,CAAC,KAAiB;QAC7B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;gBAC5B,MAAM,KAAK,GAAI,IAAI,CAAC,KAAK,EAAE,KAAgB,IAAI,CAAC,CAAC;gBACjD,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;gBAE/B,IAAI,IAAI,GAAG,IAAI,CAAC,KAAK,EAAE,IAA0B,CAAC;gBAClD,IAAI,CAAC,IAAI,EAAE,CAAC;oBACV,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;oBAC3B,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;oBAClC,IAAI,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,KAAK,EAAE,CAAC;oBAC/C,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;gBAC5B,CAAC;gBAED,IAAI,CAAC,IAAI,CAAC,KAAK;oBAAE,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;gBACjC,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC;gBACvB,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC;gBACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAC9C,CAAC;YACD,IAAI,IAAI,CAAC,QAAQ;gBAAE,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACzC,CAAC;IACH,CAAC;IAED,IAAI,CAAC,IAAI,CAAC,CAAC;IACX,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,WAAW,CAAC,IAAc;IACxC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QAChB,KAAK,CAAC,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IAC7C,CAAC;SAAM,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QACrB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,CAAC;IAChD,CAAC;IACD,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QAClB,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ;YAAE,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC;IACpE,CAAC;IACD,OAAO,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;AAChD,CAAC;AAED,SAAS,iBAAiB,CAAC,KAAmB;IAC5C,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;YAClB,KAAK,MAAM,CAAC;YACZ,KAAK,MAAM;gBACT,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACtB,MAAM;YACR,KAAK,MAAM,CAAC;YACZ,KAAK,WAAW;gBACd,KAAK,CAAC,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;gBAC7C,MAAM;YACR,KAAK,OAAO;gBACV,IAAI,IAAI,CAAC,GAAG;oBAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBACnC,MAAM;YACR,KAAK,aAAa;gBAChB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,CAAC;gBAC9C,MAAM;QACV,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACxB,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,IAAY;IAClC,OAAO,CACL,IAAI;SACD,WAAW,EAAE;SACb,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC;SACxB,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;SACpB,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;SACnB,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;SACvB,IAAI,EAAE,IAAI,SAAS,CACvB,CAAC;AACJ,CAAC"}

package/dist/html-to-tree.d.ts

@@ -0,0 +1,17 @@
+import type { TreeNode } from "@dogsbay/types";
+import { type InlineOptions } from "./inline-html.js";
+export interface HtmlToTreeResult {
+    tree: TreeNode[];
+    /** Topic title from h1.topictitle1, if present. */
+    title?: string;
+    /** Derived from the body class: concept | task | reference | topic. */
+    topicType: string;
+}
+export declare function htmlToTree(html: string, opts?: InlineOptions): HtmlToTreeResult;
+/**
+ * Extract a YouTube video id from an embed/watch/short URL, else undefined.
+ * Handles youtube.com/embed/<id>, youtube-nocookie.com/embed/<id>,
+ * youtu.be/<id>, and watch?v=<id>.
+ */
+export declare function youtubeIdFromUrl(url: string): string | undefined;
+//# sourceMappingURL=html-to-tree.d.ts.map

package/dist/html-to-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"html-to-tree.d.ts","sourceRoot":"","sources":["../src/html-to-tree.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAiD,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAErG,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,QAAQ,EAAE,CAAC;IACjB,mDAAmD;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,SAAS,EAAE,MAAM,CAAC;CACnB;AAWD,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,aAAkB,GAAG,gBAAgB,CAYnF;AAyBD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAKhE"}