@dogsbay/types 0.1.2

package/dist/format.d.ts

@@ -0,0 +1,350 @@
+import type { TreeNode } from "./tree.js";
+import type { PageMeta } from "./meta.js";
+/**
+ * A page for format conversion: slug → tree.
+ *
+ * This is the universal contract between importers and exporters.
+ * Importers produce ExportPage[], exporters consume them.
+ */
+export interface Heading {
+    depth: number;
+    slug: string;
+    text: string;
+    /** Symbol kind for API reference TOC entries (class, meth, attr, func, module) */
+    kind?: string;
+}
+export interface ExportPage {
+    /** File path relative to docs root, e.g. "getting-started" or "guides/install" */
+    slug: string;
+    /** Page title */
+    title: string;
+    /** Page content as TreeNode[] */
+    tree: TreeNode[];
+    /** Headings extracted during parsing (for TOC generation) */
+    headings: Heading[];
+    /** Target URL for redirect/navigation pages (no body content, just a link) */
+    redirect?: string;
+    /**
+     * Raw frontmatter data from the source page. Includes all YAML fields that
+     * were present in the original source (title, description, tags, custom
+     * fields like pcx_content_type, sidebar.*, etc.).
+     *
+     * Importers populate this with all frontmatter values; exporters can use
+     * specific keys or emit the whole object as frontmatter on output.
+     * Specific fields (title, redirect) are also lifted to named ExportPage
+     * fields for convenient access.
+     */
+    frontmatter?: Record<string, unknown>;
+    /**
+     * Parsed, validated, normalized metadata. Populated by importers
+     * via `parseMeta(frontmatter, options)`. Drives taxonomy emission,
+     * status badges, search facets, and Diátaxis-aware layouts.
+     *
+     * `frontmatter` stays opaque (preserves unknown keys for round-
+     * trip); `meta` is the typed slice the renderer consumes.
+     */
+    meta?: PageMeta;
+    /**
+     * Axis metadata for multi-source aggregation. Populated by the
+     * loader when ≥1 axis is active so downstream emitters (the
+     * version switcher data file, the per-page frontmatter that
+     * lets a page identify itself in the switcher) can reconstruct
+     * cross-axis equivalents.
+     *
+     * Undefined when no axis is active (single-source / single-
+     * version / single-namespace site). When set, `originalSlug`
+     * is always present (the slug as the importer produced it,
+     * before any axis prefixing); `namespace` / `version` /
+     * `locale` are present only when their axis is active.
+     *
+     * See plans/multi-source-content.md.
+     */
+    multiSource?: MultiSourceMeta;
+}
+/**
+ * Per-page axis metadata. Set by the loader's aggregator when
+ * multi-source axes are active; consumed by emitters that need
+ * to reconstruct cross-version / cross-locale / cross-namespace
+ * equivalents (switcherMap.json, hreflang tags, etc.).
+ */
+export interface MultiSourceMeta {
+    /** Namespace key (when namespace axis active). */
+    namespace?: string;
+    /** Version id (when version axis active). */
+    version?: string;
+    /** Locale code (when locale axis active; reserved for PR 5). */
+    locale?: string;
+    /**
+     * Slug as the importer produced it, BEFORE the loader applied
+     * any axis prefix. Lets emitters compute the logical key
+     * (`<namespace>/<originalSlug>`) that identifies "this same
+     * page across versions / locales".
+     */
+    originalSlug: string;
+}
+/**
+ * Navigation item for sidebar/TOC structures.
+ *
+ * Universal across formats — importers extract nav from source config
+ * (mkdocs.yml, sidebars.js, folder structure), exporters write it to
+ * the target format's nav mechanism.
+ */
+export interface NavItem {
+    label: string;
+    href?: string;
+    children?: NavItem[];
+}
+/**
+ * Standard interface for format plugins.
+ *
+ * Each format package (e.g. @dogsbay/format-mkdocs) exports a plugin
+ * conforming to this interface. The CLI discovers and composes them.
+ */
+export interface FormatPlugin {
+    /** Format identifier, e.g. "mkdocs", "obsidian", "astro" */
+    name: string;
+    /** Whether this format supports importing (source → tree) */
+    canImport: boolean;
+    /** Whether this format supports exporting (tree → target) */
+    canExport: boolean;
+    /** Auto-detect whether a path is this format */
+    detectSource: (path: string) => boolean;
+    /** Format-specific CLI options for import */
+    importOptions?: FormatOption[];
+    /** Format-specific CLI options for export */
+    exportOptions?: FormatOption[];
+    /** Import: read source format, produce pages + nav */
+    import?(source: string, opts: Record<string, unknown>): Promise<{
+        pages: ExportPage[];
+        nav: NavItem[];
+    }>;
+    /** Export: write pages + nav to target format */
+    export?(pages: ExportPage[], nav: NavItem[], output: string, opts: Record<string, unknown>): Promise<void>;
+}
+export interface FormatOption {
+    flags: string;
+    description: string;
+    default?: string;
+}
+/**
+ * Plausible analytics configuration.
+ *
+ * When present in `SiteConfig`, the docs layout emits a `<script>` tag
+ * loading Plausible's tracker. Cookie-less by default, no consent banner
+ * needed for EU.
+ */
+export interface PlausibleConfig {
+    /**
+     * Tracking domain — the value used as `data-domain` on the script tag.
+     * Typically matches the site's hostname, e.g. "docs.example.com".
+     */
+    domain: string;
+    /**
+     * Optional override for the Plausible script URL. Use this when
+     * self-hosting Plausible or proxying through your own subdomain.
+     * Default: "https://plausible.io/js/script.js".
+     */
+    scriptUrl?: string;
+}
+/**
+ * Runtime site configuration consumed by docs-layout and other runtime
+ * components. Written to `src/data/site.json` by `exportAstroProject`.
+ *
+ * Every field is optional except `siteName`, which has a sensible
+ * default ("Documentation") emitted by the project generator. Fields
+ * left undefined are omitted from the emitted JSON to keep output clean.
+ */
+export interface SiteConfig {
+    /** Site name shown in header, page title suffixes, copyright notices. */
+    siteName: string;
+    /**
+     * Canonical site URL. Required for `<link rel="canonical">`,
+     * sitemap.xml entries, and absolute OG meta tags. Without it, those
+     * features degrade to relative URLs.
+     */
+    siteUrl?: string;
+    /**
+     * Site-wide description used as the default `<meta name="description">`
+     * and fallback `og:description` when a page doesn't supply one.
+     */
+    description?: string;
+    /**
+     * Default OG image URL — used as `og:image` and `twitter:image`
+     * fallback when a page doesn't set `ogImage` in its frontmatter.
+     * Should be ~1200x630 PNG/JPG.
+     */
+    ogImage?: string;
+    /**
+     * Twitter / X handle including the leading "@". Emits as
+     * `<meta name="twitter:site">`.
+     */
+    twitterHandle?: string;
+    /**
+     * Theme color hint for browsers / iOS Safari status bar. Hex string
+     * e.g. "#0a0a0a".
+     */
+    themeColor?: string;
+    /**
+     * Source repo URL (for edit-on-GitHub links and similar). Combined
+     * with `editUri` to produce per-page edit URLs.
+     */
+    repoUrl?: string;
+    /**
+     * Path prefix appended to `repoUrl` for edit URLs, e.g.
+     * "blob/main/docs/". Resulting per-page link is
+     * `{repoUrl}/{editUri}/{slug}.md`.
+     */
+    editUri?: string;
+    /** Footer copyright text. */
+    copyright?: string;
+    /**
+     * Brand keywords for the site, used by the
+     * `seo/h1-brand-keyword` audit rule to verify that landing
+     * pages (home + `meta.type: landing` pages) include at least
+     * one of these strings in their H1 heading.
+     *
+     * Match is case-insensitive substring; ordering doesn't
+     * matter. Most sites set 1-3 entries (full name, short name,
+     * tagline). Sites that omit this config get no
+     * brand-keyword findings.
+     */
+    brandKeywords?: string[];
+    /**
+     * Plausible analytics configuration. When set, docs-layout emits the
+     * tracker script. When undefined, no analytics script is injected.
+     */
+    plausible?: PlausibleConfig;
+    /**
+     * Display config for hierarchical tag chips, sourced from
+     * `taxonomies.tags.prefixes` in `dogsbay.config.yml`. Keyed by
+     * the top-level prefix (`concept`, `difficulty`, etc.) — each
+     * entry supplies an optional human label and one of the closed
+     * palette colors. Consumed by `<TagList>` to render two-part
+     * chips with prefix-keyed colors. See plans/tag-display-config.md.
+     */
+    tagPrefixes?: Record<string, TagPrefixDisplay>;
+    /**
+     * Per-tag leaf-label overrides (slug → display string). URLs and
+     * taxonomy term-page paths still use the slug; only chip text
+     * changes. Sourced from `taxonomies.tags.labels`.
+     */
+    tagLabels?: Record<string, string>;
+    /**
+     * Map of taxonomy name → index path, sourced from declared
+     * `taxonomies` entries in `dogsbay.config.yml`. Lets renderer
+     * components (`TypeBadge`, `StatusBadge`, etc.) discover whether
+     * a built-in field has a browse destination AND what its path is.
+     *
+     * Example: `{ tags: "/tags", type: "/types", status: "/by-status" }`.
+     * A field absent from this map has no destination — the badge
+     * renders as a plain span; a field present in the map renders as
+     * a link to `<indexPath>/<value>/`.
+     *
+     * See plans/tag-display-config.md.
+     */
+    taxonomyIndexPaths?: Record<string, string>;
+    /**
+     * Per-taxonomy display config (prefixes + labels), keyed by
+     * taxonomy name. Powers the search-facet UI (`<SearchFacets>`)
+     * — facet checkboxes show "Concept: Accessibility" instead of
+     * `concept/a11y`, "How-to" instead of `how-to`, etc., reusing
+     * the same prefix/label mapping that drives `<TagList>` and
+     * the taxonomy term pages.
+     *
+     * `tagPrefixes` / `tagLabels` mirror `taxonomyDisplay.tags`
+     * for back-compat with the chip-rendering path. `<TagList>`
+     * still consumes those.
+     *
+     * See plans/search-facets.md.
+     */
+    taxonomyDisplay?: Record<string, TaxonomyDisplay>;
+    /**
+     * Per-page LLM action UI configuration ("Copy as markdown",
+     * "Open in Claude/ChatGPT/…"). When omitted, the action cluster
+     * is not rendered. See plans/llm-page-actions.md.
+     *
+     * The agent-readiness data layer (.md endpoints, llms.txt,
+     * Accept negotiation) is independent of this config — it always
+     * ships as long as `mdMirror` / `llmsTxt` are enabled in
+     * AstroProjectOptions. This config only controls the
+     * human-facing UI cluster.
+     */
+    llmActions?: LlmActionsConfig;
+}
+/**
+ * Closed list of LLM provider deep-link targets. Each one is a
+ * web app accepting `?q=` query strings to seed a new chat with
+ * the provided prompt text. Order in this union determines render
+ * order when no explicit list is configured.
+ */
+export type LlmProviderName = "claude" | "chatgpt" | "perplexity" | "gemini";
+/**
+ * Where the per-page LLM action cluster appears.
+ *   - `header` — top-right of the page header (sticky, always visible)
+ *   - `inline` — directly below the breadcrumb, above the H1
+ *   - `both`   — both placements; useful for sites that want the
+ *                cluster visible during long scrolls AND in line
+ *                with the content for first-glance discovery
+ */
+export type LlmActionsPlacement = "header" | "inline" | "both";
+/**
+ * Per-page LLM action UI configuration.
+ *
+ * Default behavior when this object is enabled but partial:
+ *   - `providers`        → all four providers, in this order:
+ *                          claude, chatgpt, perplexity, gemini.
+ *   - `placement`        → "header"
+ *   - `copyButton`       → true
+ *   - `promptTemplate`   → "Read this docs page: {url}"
+ *   - `footerLink`       → true (footer link to /llms.txt)
+ *
+ * Per-page opt-out is via frontmatter `llmActions: false` — see
+ * format-astro/src/project.ts.
+ */
+export interface LlmActionsConfig {
+    /**
+     * Master toggle. When `false`, no PageActions UI is rendered
+     * regardless of other fields. Default `true` when the parent
+     * `llmActions` object is present.
+     */
+    enabled?: boolean;
+    /** Provider list, in render order. */
+    providers?: LlmProviderName[];
+    /** Where to render the action cluster. */
+    placement?: LlmActionsPlacement;
+    /** Show the standalone "Copy markdown" button next to the dropdown. */
+    copyButton?: boolean;
+    /**
+     * Prompt template for "Open in {provider}" deep links. The
+     * placeholder `{url}` is replaced by the absolute `.md` URL of
+     * the current page; the result is URL-encoded into `?q=`.
+     */
+    promptTemplate?: string;
+    /** Add a footer link to `/llms.txt`. */
+    footerLink?: boolean;
+}
+/** Per-taxonomy display config — display labels for chip / facet UI. */
+export interface TaxonomyDisplay {
+    /** Per-prefix display config keyed by top-level segment. */
+    prefixes?: Record<string, TagPrefixDisplay>;
+    /** Per-slug label overrides; key = full slug, value = display string. */
+    labels?: Record<string, string>;
+}
+/**
+ * Display config for one taxonomy prefix. Color is one of the
+ * fixed palette names emitted into the runtime by `<TagList>`.
+ * Both fields are optional: with only `label`, the chip renders
+ * two-part text in the default palette slot; with only `color`,
+ * the slug stays as the chip label.
+ */
+export interface TagPrefixDisplay {
+    label?: string;
+    color?: TagPaletteName;
+}
+/**
+ * Closed palette of color names for tag chip backgrounds. Mirrored
+ * from `@dogsbay/cli`'s `PaletteName` so runtime consumers can
+ * type-narrow without importing CLI internals.
+ */
+export type TagPaletteName = "blue" | "amber" | "emerald" | "violet" | "rose" | "slate";
+//# sourceMappingURL=format.d.ts.map

package/dist/format.d.ts.map

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

package/dist/format.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=format.js.map

package/dist/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export type { TreeNode, InlineNode, InlineText, InlineLink, InlineImage, InlineCode, InlineFootnoteRef, InlineKbd, InlineIcon, InlineMath, InlineHtml, InlineBreak } from "./tree.js";
+export { treeToJson, chunkByHeadings, extractText } from "./json.js";
+export type { RagChunk } from "./json.js";
+export type { ExportPage, Heading, NavItem, FormatPlugin, FormatOption, SiteConfig, PlausibleConfig, TagPrefixDisplay, TagPaletteName, TaxonomyDisplay, LlmActionsConfig, LlmActionsPlacement, LlmProviderName } from "./format.js";
+export type { PageMeta, PageStatus, ParseMetaOptions } from "./meta.js";
+export { parseMeta } from "./meta.js";
+export type { DogsbayPlugin, DogsbayPluginContext, DogsbayPluginFactory, PluginVisibleConfig, PluginLogger, PluginRule, PluginIssue, PluginConfigEntry, EmitFilesHelpers, AstroIntegrationRef, } from "./plugin.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,iBAAiB,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACtL,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACrE,YAAY,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC1C,YAAY,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,gBAAgB,EAAE,cAAc,EAAE,eAAe,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACpO,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AACxE,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,YAAY,EACV,aAAa,EACb,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,YAAY,EACZ,UAAU,EACV,WAAW,EACX,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { treeToJson, chunkByHeadings, extractText } from "./json.js";
+export { parseMeta } from "./meta.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAIrE,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC"}

package/dist/json.d.ts

@@ -0,0 +1,26 @@
+import type { TreeNode } from "./tree.js";
+/**
+ * A chunk of content suitable for RAG retrieval.
+ * Each chunk corresponds to a heading section in the document.
+ */
+export interface RagChunk {
+    heading: string | null;
+    headingLevel: number;
+    path: string[];
+    content: string;
+    metadata: Record<string, unknown>;
+}
+/**
+ * Convert a TreeNode[] to structured JSON for LLM consumption.
+ */
+export declare function treeToJson(nodes: TreeNode[]): unknown;
+/**
+ * Split a TreeNode[] into chunks at heading boundaries.
+ * Each chunk contains the text content under a heading section.
+ */
+export declare function chunkByHeadings(nodes: TreeNode[], maxLevel?: number): RagChunk[];
+/**
+ * Extract plain text from a TreeNode, stripping any markup.
+ */
+export declare function extractText(node: TreeNode): string;
+//# sourceMappingURL=json.d.ts.map

package/dist/json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../src/json.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAE1C;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,OAAO,CAErD;AAkBD;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,QAAQ,EAAE,EACjB,QAAQ,GAAE,MAAU,GACnB,QAAQ,EAAE,CAoDZ;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAiBlD"}

package/dist/json.js

@@ -0,0 +1,88 @@
+/**
+ * Convert a TreeNode[] to structured JSON for LLM consumption.
+ */
+export function treeToJson(nodes) {
+    return nodes.map(nodeToJson);
+}
+function nodeToJson(node) {
+    const result = { type: node.type };
+    if (node.props && Object.keys(node.props).length > 0) {
+        result.props = node.props;
+    }
+    if (node.html) {
+        result.text = node.html;
+    }
+    if (node.children && node.children.length > 0) {
+        result.children = node.children.map(nodeToJson);
+    }
+    return result;
+}
+/**
+ * Split a TreeNode[] into chunks at heading boundaries.
+ * Each chunk contains the text content under a heading section.
+ */
+export function chunkByHeadings(nodes, maxLevel = 3) {
+    const chunks = [];
+    const headingStack = [];
+    let currentContent = [];
+    let currentHeading = null;
+    let currentLevel = 0;
+    function flush() {
+        const content = currentContent.join("\n").trim();
+        if (content || currentHeading) {
+            chunks.push({
+                heading: currentHeading,
+                headingLevel: currentLevel,
+                path: headingStack.map((h) => h.title),
+                content,
+                metadata: {},
+            });
+        }
+        currentContent = [];
+    }
+    function walkNodes(nodes) {
+        for (const node of nodes) {
+            if (node.type === "heading") {
+                const level = node.props?.level ?? 1;
+                if (level <= maxLevel) {
+                    flush();
+                    while (headingStack.length > 0 &&
+                        headingStack[headingStack.length - 1].level >= level) {
+                        headingStack.pop();
+                    }
+                    const title = extractText(node);
+                    headingStack.push({ title, level });
+                    currentHeading = title;
+                    currentLevel = level;
+                    continue;
+                }
+            }
+            currentContent.push(extractText(node));
+        }
+    }
+    walkNodes(nodes);
+    flush();
+    return chunks;
+}
+/**
+ * Extract plain text from a TreeNode, stripping any markup.
+ */
+export function extractText(node) {
+    const parts = [];
+    if (node.html) {
+        parts.push(stripHtml(node.html));
+    }
+    if (node.type === "code" && node.props?.code) {
+        parts.push(String(node.props.code).trim());
+    }
+    if (node.children) {
+        for (const child of node.children) {
+            parts.push(extractText(child));
+        }
+    }
+    return parts.filter(Boolean).join(" ").trim();
+}
+function stripHtml(html) {
+    return html.replace(/<[^>]+>/g, "").trim();
+}
+//# sourceMappingURL=json.js.map

package/dist/json.js.map

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

package/dist/meta.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Typed page metadata — the parsed, validated, normalized slice of
+ * frontmatter the renderer cares about.
+ *
+ * Importers populate `ExportPage.meta` by calling `parseMeta` on the
+ * source frontmatter. Free-form / format-specific keys stay in
+ * `ExportPage.frontmatter` (opaque, preserved for round-trip).
+ *
+ * See plans/metadata-and-taxonomies.md for the design rationale.
+ */
+/** Lifecycle states. Closed enum — fixed set with defined render semantics. */
+export type PageStatus = "draft" | "preview" | "stable" | "deprecated";
+export interface PageMeta {
+    /**
+     * Flat or slash-nested string tags. `tags: ["api/rest"]` means the
+     * page lives under `/tags/api/` AND `/tags/api/rest/` at emit
+     * time. Slash is the only nesting separator.
+     */
+    tags?: string[];
+    /**
+     * Broader grouping. Auto-derived from path when frontmatter
+     * doesn't supply a valid value (`content/guides/auth.md` →
+     * `["guides"]`). Override with `category: foo` or
+     * `category: [foo, bar]`.
+     *
+     * No first-class "belongs nowhere" sentinel in v1: `category: []`
+     * falls through to slug-derived default. See
+     * plans/metadata-and-taxonomies.md.
+     */
+    category?: string[];
+    /**
+     * Page type. Open string. Diátaxis values (`tutorial`, `how-to`,
+     * `reference`, `explanation`) are conventional; users can add
+     * `api-endpoint`, `release-notes`, etc.
+     */
+    type?: string;
+    /** Lifecycle. Drafts excluded from prod builds; deprecated gets a banner. */
+    status?: PageStatus;
+    /** Audience facets — `["developer"]`, `["admin", "end-user"]`, etc. */
+    audience?: string[];
+    /** ISO date strings. Consumers parse to Date when needed. */
+    updated?: string;
+    created?: string;
+    /** Sort hint for navigation/list pages. Lower weight first. */
+    weight?: number;
+    /**
+     * Free-form properties beyond well-known fields. Queryable from
+     * templates; doesn't get auto-generated index pages. Validate via
+     * `propSchema` in `dogsbay.config.yml`.
+     */
+    props?: Record<string, unknown>;
+    /**
+     * Custom taxonomies declared in config. Key is the taxonomy name
+     * (e.g. `audience`, `product`); value is the term list. Term
+     * strings may be slash-nested when the taxonomy is hierarchical.
+     */
+    taxonomies?: Record<string, string[]>;
+}
+/**
+ * Options for `parseMeta`. The slug enables path-based `category`
+ * auto-derivation; the `taxonomyNames` set tells the parser which
+ * frontmatter keys to lift into `meta.taxonomies`.
+ */
+export interface ParseMetaOptions {
+    /**
+     * Slug of the page being parsed (e.g. `"guides/auth"`). Used to
+     * auto-derive `category` when frontmatter doesn't set it. Pass
+     * `undefined` to skip path-based derivation.
+     */
+    slug?: string;
+    /**
+     * Names of user-declared taxonomies (from `dogsbay.config.yml`'s
+     * `taxonomies:` block). Frontmatter values for these keys are
+     * lifted into `meta.taxonomies[name]`. Without this, the parser
+     * doesn't know which extra keys to treat as taxonomies vs
+     * arbitrary frontmatter.
+     */
+    taxonomyNames?: readonly string[];
+}
+/**
+ * Parse and normalize frontmatter into `PageMeta`. Pure function;
+ * no I/O. Unknown frontmatter keys are not lifted — they stay in
+ * the caller's opaque frontmatter copy.
+ *
+ * Behavior:
+ * - `tags`, `audience` accept string[] or single string (coerced).
+ * - `category` accepts string[] or single string. When absent and
+ *   `slug` is provided, auto-derives from path segments (excluding
+ *   the leaf filename).
+ * - `type` accepts any string.
+ * - `status` accepts only the four enum values; others are dropped.
+ * - `weight` accepts numbers; non-numeric is dropped.
+ * - `updated` / `created` are stored as ISO strings; Date objects
+ *   are converted via `.toISOString()`.
+ * - `props` accepts an object; non-objects dropped.
+ * - Keys named in `options.taxonomyNames` are lifted into
+ *   `meta.taxonomies` as string arrays.
+ */
+export declare function parseMeta(frontmatter: Record<string, unknown> | undefined, options?: ParseMetaOptions): PageMeta;
+//# sourceMappingURL=meta.d.ts.map

package/dist/meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta.d.ts","sourceRoot":"","sources":["../src/meta.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,+EAA+E;AAC/E,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,SAAS,GAAG,QAAQ,GAAG,YAAY,CAAC;AAEvE,MAAM,WAAW,QAAQ;IACvB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAEhB;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IAEpB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,6EAA6E;IAC7E,MAAM,CAAC,EAAE,UAAU,CAAC;IAEpB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IAEpB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEhC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CACvC;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAUD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,SAAS,CACvB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAChD,OAAO,GAAE,gBAAqB,GAC7B,QAAQ,CAwCV"}

package/dist/meta.js

@@ -0,0 +1,130 @@
+/**
+ * Typed page metadata — the parsed, validated, normalized slice of
+ * frontmatter the renderer cares about.
+ *
+ * Importers populate `ExportPage.meta` by calling `parseMeta` on the
+ * source frontmatter. Free-form / format-specific keys stay in
+ * `ExportPage.frontmatter` (opaque, preserved for round-trip).
+ *
+ * See plans/metadata-and-taxonomies.md for the design rationale.
+ */
+/** Closed enum for status validation. */
+const STATUS_VALUES = [
+    "draft",
+    "preview",
+    "stable",
+    "deprecated",
+];
+/**
+ * Parse and normalize frontmatter into `PageMeta`. Pure function;
+ * no I/O. Unknown frontmatter keys are not lifted — they stay in
+ * the caller's opaque frontmatter copy.
+ *
+ * Behavior:
+ * - `tags`, `audience` accept string[] or single string (coerced).
+ * - `category` accepts string[] or single string. When absent and
+ *   `slug` is provided, auto-derives from path segments (excluding
+ *   the leaf filename).
+ * - `type` accepts any string.
+ * - `status` accepts only the four enum values; others are dropped.
+ * - `weight` accepts numbers; non-numeric is dropped.
+ * - `updated` / `created` are stored as ISO strings; Date objects
+ *   are converted via `.toISOString()`.
+ * - `props` accepts an object; non-objects dropped.
+ * - Keys named in `options.taxonomyNames` are lifted into
+ *   `meta.taxonomies` as string arrays.
+ */
+export function parseMeta(frontmatter, options = {}) {
+    const fm = frontmatter ?? {};
+    const meta = {};
+    const tags = coerceStringArray(fm.tags);
+    if (tags)
+        meta.tags = tags;
+    const category = coerceStringArray(fm.category) ?? deriveCategoryFromSlug(options.slug);
+    if (category)
+        meta.category = category;
+    if (typeof fm.type === "string" && fm.type.length > 0) {
+        meta.type = fm.type;
+    }
+    if (typeof fm.status === "string" && STATUS_VALUES.includes(fm.status)) {
+        meta.status = fm.status;
+    }
+    const audience = coerceStringArray(fm.audience);
+    if (audience)
+        meta.audience = audience;
+    const updated = coerceIsoDate(fm.updated);
+    if (updated)
+        meta.updated = updated;
+    const created = coerceIsoDate(fm.created);
+    if (created)
+        meta.created = created;
+    if (typeof fm.weight === "number" && Number.isFinite(fm.weight)) {
+        meta.weight = fm.weight;
+    }
+    if (isPlainObject(fm.props)) {
+        meta.props = { ...fm.props };
+    }
+    const taxonomies = collectTaxonomies(fm, options.taxonomyNames);
+    if (taxonomies)
+        meta.taxonomies = taxonomies;
+    return meta;
+}
+/**
+ * Auto-derive `category` from a slug. The leaf segment is treated
+ * as the page filename and dropped; remaining segments become the
+ * category path.
+ *
+ * - `"guides/auth"` → `["guides"]`
+ * - `"guides/oauth/setup"` → `["guides", "oauth"]`
+ * - `"intro"` → undefined (no parent path)
+ * - `""` / undefined → undefined
+ */
+function deriveCategoryFromSlug(slug) {
+    if (!slug)
+        return undefined;
+    const parts = slug.split("/").filter((p) => p.length > 0);
+    if (parts.length < 2)
+        return undefined;
+    return parts.slice(0, -1);
+}
+function coerceStringArray(value) {
+    if (typeof value === "string") {
+        return value.length > 0 ? [value] : undefined;
+    }
+    if (Array.isArray(value)) {
+        const out = value.filter((v) => typeof v === "string" && v.length > 0);
+        return out.length > 0 ? out : undefined;
+    }
+    return undefined;
+}
+function coerceIsoDate(value) {
+    if (value instanceof Date && !Number.isNaN(value.getTime())) {
+        return value.toISOString();
+    }
+    if (typeof value === "string" && value.length > 0) {
+        const parsed = new Date(value);
+        return Number.isNaN(parsed.getTime()) ? undefined : parsed.toISOString();
+    }
+    return undefined;
+}
+function isPlainObject(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        !(value instanceof Date));
+}
+function collectTaxonomies(fm, taxonomyNames) {
+    if (!taxonomyNames || taxonomyNames.length === 0)
+        return undefined;
+    const out = {};
+    for (const name of taxonomyNames) {
+        // Skip well-known names that have their own typed slot.
+        if (name === "tags" || name === "category" || name === "audience")
+            continue;
+        const value = coerceStringArray(fm[name]);
+        if (value)
+            out[name] = value;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+//# sourceMappingURL=meta.js.map

package/dist/meta.js.map

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

package/dist/plugin.d.ts

@@ -0,0 +1,269 @@
+/**
+ * Plugin types — the surface third-party plugins target.
+ *
+ * Design and rationale: plans/plugin-api.md.
+ *
+ * The interface is deliberately framework-agnostic. Plugins do NOT
+ * see the inner workings of the Astro build; they receive parsed
+ * pages as TreeNode-bearing `ExportPage[]` and contribute generated
+ * outputs (transformed pages, audit rules, client modules, styles,
+ * astro integrations) through named hooks.
+ *
+ * The runtime side (loader, codegen) lives in `packages/cli`. This
+ * file owns only the shapes — keeping `@dogsbay/types` light.
+ */
+import type { ExportPage, NavItem, SiteConfig } from "./format.js";
+/**
+ * Logger handed to plugin hooks. Output is automatically prefixed
+ * with the plugin's id so users can attribute messages.
+ */
+export interface PluginLogger {
+    info(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string): void;
+    debug(msg: string): void;
+}
+/**
+ * Read-only context passed to every plugin hook.
+ *
+ * Plugins MUST NOT mutate `config` directly — return a new config
+ * from `extendConfig` to change resolved configuration. The other
+ * fields are stable across the build.
+ */
+export interface DogsbayPluginContext {
+    /**
+     * Resolved site configuration — the same shape `dogsbay site
+     * build` works against, with defaults applied.
+     *
+     * Plugins receive this as a snapshot. To modify config, return
+     * a new value from `extendConfig`. Hooks fired AFTER
+     * `extendConfig` see the modified config.
+     */
+    readonly config: PluginVisibleConfig;
+    /** Absolute path of the directory containing `dogsbay.config.yml`. */
+    readonly siteRoot: string;
+    /**
+     * Absolute path of the generated Astro project. Usually
+     * `<siteRoot>/astro`; sometimes `<siteRoot>` when `output: "."`
+     * is configured.
+     */
+    readonly outputDir: string;
+    /** Logger prefixed with the plugin's id. */
+    readonly logger: PluginLogger;
+    /**
+     * Build command currently running. Lets plugins skip work that
+     * only matters in production builds, or run dev-only diagnostics.
+     */
+    readonly command: "build" | "dev" | "check";
+}
+/**
+ * Subset of the resolved config that plugins are allowed to read.
+ *
+ * The full `DogsbayConfig` lives in `@dogsbay/cli`; re-exposing it
+ * here would cause a circular dep. Plugins typically only need
+ * `site` (for name, basePath, etc.) plus the option pieces they
+ * declared themselves. Cast through `unknown` if you genuinely need
+ * deeper access — that's a deliberate friction point because the
+ * shape can change between minor versions.
+ */
+export interface PluginVisibleConfig {
+    site: SiteConfig;
+    /** Free-form access for everything the typed surface omits. */
+    [key: string]: unknown;
+}
+/**
+ * Audit rule contract — re-stated here to avoid a circular dep
+ * between `@dogsbay/types` and `@dogsbay/cli` (where the canonical
+ * audit module lives). The shape MUST stay in sync with
+ * `packages/cli/src/audit/types.ts` — adapted via a runtime
+ * pass-through in the loader.
+ */
+export interface PluginRule {
+    id: string;
+    category: string;
+    stage: "source" | "source-corpus" | "dist";
+    severity: "error" | "warning";
+    description: string;
+    /**
+     * The audit runner narrows this on the rule's declared `stage`.
+     * Plugins import the concrete context types from
+     * `@dogsbay/cli/audit` if they need typed access.
+     */
+    run(ctx: unknown): PluginIssue[];
+}
+export interface PluginIssue {
+    ruleId: string;
+    severity: "error" | "warning" | "info";
+    file: string;
+    line?: number;
+    message: string;
+    context?: string;
+}
+/**
+ * Helpers passed to `emitFiles` so plugins don't need to import
+ * `node:fs` directly. The runtime resolves all paths relative to
+ * `outputDir`.
+ */
+export interface EmitFilesHelpers {
+    /** Write a UTF-8 / Uint8Array file to `<outputDir>/<relPath>`. */
+    writeFile(relPath: string, contents: string | Uint8Array): void;
+    /** Recursively copy `srcAbs` (absolute) to `<outputDir>/<destRel>`. */
+    copyDir(srcAbs: string, destRel: string): void;
+}
+/**
+ * The plugin shape. All fields except `name` are optional; plugins
+ * implement only the hooks they need.
+ *
+ * Lifecycle order during `dogsbay site build`:
+ *
+ *   1. `extendConfig`            — modify resolved config
+ *   2. (content import runs)
+ *   3. `onContentImported`        — mutate pages + nav
+ *   4. `transformNav`             — sugar for nav-only patches
+ *   5. (format-astro emitters run)
+ *   6. `emitFiles`                — write extra files
+ *   7. (client-module / config / style codegen runs)
+ *   8. `auditRules`               — registered for `site check`
+ *   9. (astro.config.mjs codegen)
+ *
+ * `clientModules`, `styles`, `defineClientConfig`, `componentWrappers`,
+ * and `addAstroIntegrations` are queried before the corresponding
+ * codegen step; their return value is treated as data, not as a
+ * lifecycle hook with side-effect ordering.
+ */
+export interface DogsbayPlugin {
+    /**
+     * npm package name (or local synthetic name). Used in diagnostics
+     * and as the default `id` if `id` isn't set.
+     */
+    name: string;
+    /**
+     * Plugin instance id. Defaults to `name`. Provide explicitly when
+     * the same plugin is loaded twice (e.g. one OpenAPI instance per
+     * schema). The loader auto-suffixes (`#1`, `#2`) duplicates if
+     * no explicit id is supplied — that's a fallback, not a
+     * recommendation.
+     */
+    id?: string;
+    /** Plugin ids that MUST run after this one. */
+    before?: string[];
+    /** Plugin ids that MUST run before this one. */
+    after?: string[];
+    extendConfig?(ctx: DogsbayPluginContext): PluginVisibleConfig | Promise<PluginVisibleConfig>;
+    onContentImported?(pages: ExportPage[], nav: NavItem[], ctx: DogsbayPluginContext): {
+        pages: ExportPage[];
+        nav: NavItem[];
+    } | Promise<{
+        pages: ExportPage[];
+        nav: NavItem[];
+    }>;
+    transformNav?(nav: NavItem[], ctx: DogsbayPluginContext): NavItem[] | Promise<NavItem[]> | undefined;
+    emitFiles?(ctx: DogsbayPluginContext & {
+        pages: ExportPage[];
+        nav: NavItem[];
+    } & EmitFilesHelpers): void | Promise<void>;
+    /**
+     * Absolute paths of `.js` / `.ts` modules to import in the docs
+     * layout. Each module is loaded for its side effects and SHOULD
+     * listen for `astro:page-load` to handle view transitions.
+     */
+    clientModules?(ctx: DogsbayPluginContext): string[];
+    /**
+     * Absolute paths of `.css` files to inject into the layout. Each
+     * file is copied into `<outputDir>/src/styles/plugins/` and
+     * imported from the global stylesheet.
+     */
+    styles?(ctx: DogsbayPluginContext): string[];
+    /**
+     * Build-time → client-time config bridge. The returned value is
+     * exposed at `virtual:dogsbay-plugin-config/<plugin-id>` so the
+     * client modules can `import config from ".../<plugin-id>"`.
+     *
+     * The value is JSON-serialized into a TypeScript file at codegen
+     * time, so it must be JSON-safe (no functions, classes, or
+     * circular refs). Strings, numbers, booleans, arrays, and plain
+     * objects are fine.
+     */
+    defineClientConfig?(ctx: DogsbayPluginContext): unknown;
+    /**
+     * Wrap a built-in slot. Unlike Starlight (single-string-replaces-
+     * everything), wrappers compose: each plugin's wrapper sees the
+     * previous wrapper's output via `<slot />`. Order matches plugin
+     * declaration order — earlier-declared wrappers are outermost,
+     * later-declared wrappers are innermost.
+     *
+     * Each plugin's wrapper component MUST render a `<slot />` —
+     * that's where the inner content lands. The runtime emits a
+     * `<Slot>Stack.astro` codegen file that imports each wrapper and
+     * recursively nests them; per-page emission uses the stack
+     * around the article body.
+     *
+     * Available slots in v1:
+     *   - "MarkdownContent"  — wraps the page article body
+     *
+     * Future slots (DocsHeader, Sidebar, TOC, Footer, Pagination)
+     * land as plugin demand surfaces.
+     *
+     * @returns map of slot name → absolute path to the wrapper
+     *          `.astro` component shipped with the plugin
+     */
+    componentWrappers?(ctx: DogsbayPluginContext): Record<string, string>;
+    auditRules?(ctx: DogsbayPluginContext): PluginRule[];
+    /**
+     * Astro integrations to register on the generated project. Use
+     * for things no Dogsbay hook covers (sitemap, OG image generation,
+     * custom Vite plugins). The integrations are appended to the
+     * `integrations:` array in `astro.config.mjs` via codegen, so they
+     * must be importable from npm package paths — local-file
+     * integrations need the plugin to ship them as part of its package.
+     */
+    addAstroIntegrations?(ctx: DogsbayPluginContext): AstroIntegrationRef[];
+}
+/**
+ * Reference to an Astro integration as it should appear in the
+ * generated `astro.config.mjs`. Avoids a `@types/astro` dep here.
+ *
+ * Example:
+ *   { import: "@astrojs/sitemap", options: { customPages: [] } }
+ *   → import sitemap from "@astrojs/sitemap";
+ *     // ...
+ *     integrations: [..., sitemap({ customPages: [] })]
+ */
+export interface AstroIntegrationRef {
+    /** Module specifier for the integration's default export. */
+    import: string;
+    /**
+     * Options to pass to the integration factory. Must be JSON-safe;
+     * the codegen serializes via `JSON.stringify`. For options that
+     * can't be JSON-serialized (functions, etc.), use a thin wrapper
+     * package and pass options through `extendConfig` instead.
+     */
+    options?: unknown;
+    /**
+     * Optional factory call name. Defaults to the integration's
+     * default export. Use when the package's default export is the
+     * integration object itself rather than a factory.
+     */
+    callable?: boolean;
+}
+/**
+ * Plugin factory — the default export plugin authors ship.
+ *
+ * The factory pattern (rather than a plain object) gives plugin
+ * authors a place to validate options and stash per-instance state
+ * before returning the hook bag.
+ */
+export type DogsbayPluginFactory<O = unknown> = (options?: O) => DogsbayPlugin;
+/**
+ * Plugin entry as it appears in `dogsbay.config.yml`. Either a bare
+ * package name (no options) or a `{ name, id?, options? }` object.
+ */
+export type PluginConfigEntry = string | {
+    /** npm package name or local path. */
+    name: string;
+    /** Optional instance id; required when the same plugin appears more than once. */
+    id?: string;
+    /** Options forwarded to the plugin's factory. */
+    options?: unknown;
+};
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

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

package/dist/plugin.js

@@ -0,0 +1,16 @@
+/**
+ * Plugin types — the surface third-party plugins target.
+ *
+ * Design and rationale: plans/plugin-api.md.
+ *
+ * The interface is deliberately framework-agnostic. Plugins do NOT
+ * see the inner workings of the Astro build; they receive parsed
+ * pages as TreeNode-bearing `ExportPage[]` and contribute generated
+ * outputs (transformed pages, audit rules, client modules, styles,
+ * astro integrations) through named hooks.
+ *
+ * The runtime side (loader, codegen) lives in `packages/cli`. This
+ * file owns only the shapes — keeping `@dogsbay/types` light.
+ */
+export {};
+//# sourceMappingURL=plugin.js.map

package/dist/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG"}

package/dist/tree.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Universal document tree node.
+ *
+ * All format loaders (MkDocs, AsciiDoc, DITA, Dogsbay MD) produce TreeNode[].
+ * All renderers (ContentRenderer.astro) and exporters consume TreeNode[].
+ *
+ * This is a semantic model — it captures what content means, not how it was
+ * originally written. Format-specific syntax details do not belong here.
+ */
+export interface TreeNode {
+    /** Semantic node type: "callout", "tabs", "code", "heading", "paragraph", etc. */
+    type: string;
+    /** Semantic properties. Shape depends on type. */
+    props?: Record<string, unknown>;
+    /** Pre-rendered HTML content (for inline/prose nodes). */
+    html?: string;
+    /** Child nodes for container types. */
+    children?: TreeNode[];
+    /** Structured inline children (replaces html for portable rendering). */
+    inline?: InlineNode[];
+    /**
+     * Arbitrary metadata that travels with the node but does not affect
+     * rendering. Loaders can attach source-format hints, provenance info,
+     * or processing flags here. Renderers and exporters should ignore
+     * keys they do not recognise.
+     */
+    meta?: Record<string, unknown>;
+}
+/**
+ * Inline node — structured representation of inline/rich text content.
+ *
+ * Inspired by Notion's rich text model: formatting is flat annotations
+ * on spans, not nested elements. `{ bold: true, italic: true }` rather
+ * than `<strong><em>text</em></strong>`.
+ *
+ * Links use `children` because link text can contain formatted spans.
+ */
+export type InlineNode = InlineText | InlineLink | InlineImage | InlineCode | InlineHighlight | InlineFootnoteRef | InlineKbd | InlineIcon | InlineMath | InlineHtml | InlineBreak;
+/** Text span with flat formatting annotations. */
+export interface InlineText {
+    type: "text";
+    text: string;
+    bold?: boolean;
+    italic?: boolean;
+    strikethrough?: boolean;
+}
+/** Link wrapping inline children (link text can contain formatting). */
+export interface InlineLink {
+    type: "link";
+    href: string;
+    title?: string;
+    children: InlineNode[];
+}
+/** Image (block or inline depending on context). */
+export interface InlineImage {
+    type: "image";
+    src: string;
+    alt?: string;
+    title?: string;
+    width?: number;
+    height?: number;
+}
+/** Inline code span. */
+export interface InlineCode {
+    type: "code";
+    text: string;
+}
+/** Highlighted/marked text (==text== in Obsidian/pymdownx.mark). */
+export interface InlineHighlight {
+    type: "highlight";
+    children: InlineNode[];
+}
+/** Footnote reference. */
+export interface InlineFootnoteRef {
+    type: "footnote-ref";
+    label: string;
+    content?: string;
+}
+/** Keyboard shortcut keys. */
+export interface InlineKbd {
+    type: "kbd";
+    keys: string[];
+}
+/** Inline math: $E=mc^2$ — rendered by app-level math component. */
+export interface InlineMath {
+    type: "math";
+    latex: string;
+}
+/**
+ * Icon or emoji shortcode (e.g. :material-check:, :smile:).
+ * Resolved at render time by an IconRegistry.
+ */
+export interface InlineIcon {
+    type: "icon";
+    /** Full shortcode name as written (e.g. "material-check", "smile") */
+    name: string;
+    /** Icon library: "material" | "fontawesome" | "octicons" | "simple" | "emoji" | "custom" */
+    library?: string;
+    /** Sub-variant (e.g. "brands", "solid", "regular" for FontAwesome) */
+    variant?: string;
+    /** Size hint from shortcode (e.g. "16", "24" for Octicons) */
+    size?: string;
+    /** Attributes from attr_list syntax { .class style="..." } */
+    attrs?: Record<string, string>;
+}
+/** Raw HTML escape hatch for unsupported inline types. */
+export interface InlineHtml {
+    type: "html-inline";
+    html: string;
+}
+/** Line break. */
+export interface InlineBreak {
+    type: "break";
+}
+//# sourceMappingURL=tree.d.ts.map

package/dist/tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../src/tree.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,WAAW,QAAQ;IACvB,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAC;IAEb,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEhC,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,uCAAuC;IACvC,QAAQ,CAAC,EAAE,QAAQ,EAAE,CAAC;IAEtB,yEAAyE;IACzE,MAAM,CAAC,EAAE,UAAU,EAAE,CAAC;IAEtB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,UAAU,GAClB,UAAU,GACV,UAAU,GACV,WAAW,GACX,UAAU,GACV,eAAe,GACf,iBAAiB,GACjB,SAAS,GACT,UAAU,GACV,UAAU,GACV,UAAU,GACV,WAAW,CAAC;AAEhB,kDAAkD;AAClD,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,wEAAwE;AACxE,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,UAAU,EAAE,CAAC;CACxB;AAED,oDAAoD;AACpD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,OAAO,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAwB;AACxB,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,oEAAoE;AACpE,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,WAAW,CAAC;IAClB,QAAQ,EAAE,UAAU,EAAE,CAAC;CACxB;AAED,0BAA0B;AAC1B,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,cAAc,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,8BAA8B;AAC9B,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,KAAK,CAAC;IACZ,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,oEAAoE;AACpE,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,4FAA4F;IAC5F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED,0DAA0D;AAC1D,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,aAAa,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,kBAAkB;AAClB,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,OAAO,CAAC;CACf"}

package/dist/tree.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tree.js.map

package/dist/tree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.js","sourceRoot":"","sources":["../src/tree.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@dogsbay/types",
+  "version": "0.1.2",
+  "description": "Universal document tree model for Dogsbay format loaders and renderers",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "dogsbay",
+    "documentation",
+    "treenode",
+    "types"
+  ],
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dogsbay/dogsbay.git",
+    "directory": "packages/types"
+  },
+  "homepage": "https://github.com/dogsbay/dogsbay/tree/main/packages/types",
+  "bugs": {
+    "url": "https://github.com/dogsbay/dogsbay/issues"
+  }
+}