pattern-dump 0.1.0-alpha.0

package/dist/types/contracts/dev-protocol.d.ts

@@ -0,0 +1,624 @@
+/** A component's canonical identity: its path relative to `patterns/`. e.g. "atoms/button". */
+export type ComponentId = string;
+/** Top-level atomic category — the first path segment. */
+export type Category = string;
+export type ComponentStatus = "draft" | "stable" | "deprecated";
+/**
+ * Preview layout mode (M4.2). How the component sits in the stage:
+ *  - "centered": inner <main> hugs content, height-fits, stage centers it (atoms/molecules/organisms)
+ *  - "full":     inner <main> fills the stage width AND height, top-aligned (pages/templates)
+ * This is the RESOLVED mode (category default ← category index.md frontmatter ← component override),
+ * so the shell renders directly without re-deriving precedence. Width is pure CSS; height is measured
+ * for centered mode only (full mode fills).
+ */
+export type LayoutMode = "centered" | "full";
+/** A named data set applied over defaults — a state or a documentation example. */
+export interface VariantRef {
+    /** The `~variant` token, e.g. "secondary", "disabled". Absent = component defaults. */
+    name: string;
+}
+/**
+ * GET /api/tree   (M4.3 — recursive)
+ * The sidebar navigation tree: a recursive hierarchy reflecting REAL folder depth
+ * (category → intermediate group folders → components), e.g. atoms/input/text-input.
+ *
+ * Sibling order, at every level including the roots — alphabetical unless the docs override it:
+ *  1. the parent folder's `index.md` `order:` LIST of child names (`patterns/index.md` for roots)
+ *     puts the listed children first, in list order; unknown names are ignored;
+ *  2. otherwise a child's own numeric `order:` WEIGHT (a component's `.md`, a group's `index.md`)
+ *     sorts ascending, weighted before unweighted;
+ *  3. then alphabetical by path segment, numeric-aware (`item2` before `item10`).
+ * Only the leading `---` frontmatter block is read. The client renders this order as served.
+ */
+export interface ComponentTree {
+    /** Top-level nodes (atoms, molecules, …), in the sibling order above. */
+    roots: TreeNode[];
+}
+/**
+ * One uniform node for every position in the tree. Three real cases fall out of one shape:
+ *  - group folder            — kind "group", has children, no component of its own (e.g. "atoms/input")
+ *  - leaf component          — kind "component", no children (e.g. "atoms/button")
+ *  - component with children — kind "component" + children (e.g. "molecules/field" owning "field/input")
+ * Depth is unrestricted; nesting is informational lineage, not an addressing boundary.
+ */
+export interface TreeNode {
+    /** Full path under patterns/ — folder or component:
+     *  "atoms" | "atoms/input" | "atoms/input/text-input". */
+    path: string;
+    /** Display title from frontmatter. Without one, a component falls back to its last path segment
+     *  as-is; a group folder to that segment made readable ("quick-links" → "Quick links"). */
+    title: string;
+    /** "group" = folder with no component of its own; "component" = renderable (may also have children). */
+    kind: "group" | "component";
+    /** Present when kind === "component". */
+    status?: ComponentStatus;
+    /** Resolved layout mode; present when kind === "component". */
+    layout?: LayoutMode;
+    /** Lineage marker. Private components are nested under their owner and hidden by default in the tree. */
+    visibility?: "public" | "private";
+    /** The pattern package (npm name) this component comes from; absent for the project's own. Present
+     *  only on component nodes — a group's source follows from its components. */
+    source?: string;
+    /** Has an overview page? TRUE for a group/category folder with ≥1 public component anywhere
+     *  beneath it — `index.md` is optional. Suppressed by `overviews: false` in config (all folders)
+     *  or `overview: false` in the folder's `index.md` (that folder). FALSE for component nodes
+     *  (M4.3) — a component's "all variants" gallery is M4.4, a separate concept. */
+    hasOverview: boolean;
+    /** Sub-folders / sub-components; absent or empty for a leaf. */
+    children?: TreeNode[];
+}
+export type DiagnosticSeverity = "error" | "warning" | "info";
+export type DiagnosticKind = "RENDER_ERROR" | "UNFILLED_REQUIRED" | "SHAPE_MISMATCH" | "HTML_INVALID" | "CASCADE_WARNING" | "A11Y" | "HIGHLIGHT_FALLBACK" | "HANDLE_COLLISION";
+/** Fields every diagnostic carries, whichever engine produced it. */
+interface DiagnosticBase {
+    severity: DiagnosticSeverity;
+    message: string;
+    /** Rule id within the engine (e.g. html-validate "element-permitted-content"). A11yDiagnostic
+     *  sets this to the axe rule id; html-validate sets it to the failing rule; absent for kinds that
+     *  have no finer rule than their `kind` (RENDER_ERROR, HANDLE_COLLISION, schema kinds). */
+    ruleId?: string;
+    /** JSON Schema / data pointer, e.g. "#/properties/label" — schema kinds only. */
+    path?: string;
+    /** Source-file position — RENDER_ERROR, best-effort. */
+    location?: {
+        file?: string;
+        line?: number;
+        column?: number;
+    };
+}
+/** A finding from any engine other than axe. */
+export interface GeneralDiagnostic extends DiagnosticBase {
+    kind: Exclude<DiagnosticKind, "A11Y">;
+    source: "render" | "schema" | "html" | "cascade" | "highlight" | "discovery";
+}
+/** Per-node axe-core finding. One diagnostic per failing DOM node. */
+export interface A11yDiagnostic extends DiagnosticBase {
+    kind: "A11Y";
+    source: "axe";
+    ruleId: string;
+    target: string;
+    nodeHtml: string;
+    help: string;
+    helpUrl: string;
+    /** Populated only when ruleId === "color-contrast". Source: nodes[n].any[0].data. */
+    contrast?: {
+        fg: string;
+        bg: string;
+        ratio: number;
+        expected: number;
+    };
+    /** True when sourced from axe's `incomplete` array — axe could not confirm pass/fail.
+     *  Absent/false = confirmed violation. Confirmed and needs-review are distinct certainty levels. */
+    needsReview?: boolean;
+}
+/**
+ * Any diagnostic — a union discriminated on `kind` (and equivalently `source`): checking
+ * `d.kind === "A11Y"` narrows to A11yDiagnostic, so consumers never cast to reach axe fields.
+ */
+export type Diagnostic = GeneralDiagnostic | A11yDiagnostic;
+/** The detection engine that produced a finding — a DISTINCT dimension from the rule id. Roll-up by
+ *  engine ("all axe", "all html-validation") is a field filter on this, never a string-prefix match. */
+export type DiagnosticEngine = "axe" | "html-validate" | "schema" | "render" | "discovery";
+/** Provenance tag. `SUBJECT-DEBT` = a real defect in the system under test (the common case; the
+ *  subject owns its templates). `PD-GAP` = PD's own detector/pipeline is at fault, not the subject.
+ *  Default is always SUBJECT-DEBT; PD-GAP is applied only via an explicit allowlist, never inferred
+ *  from a diagnostic kind (a RENDER_ERROR is the subject's template debt by default). */
+export type DiagnosticTag = "SUBJECT-DEBT" | "PD-GAP";
+/** A component's render outcome — metadata on the node, NEVER itself a defect occurrence. A component
+ *  that renders empty for want of project data (data-masked) or a base synthesized from variants is
+ *  legitimately `blank`; blank annotates findings (populated rules aren't over-claimed on empty
+ *  output) but is not counted as a defect. `error` = the template threw (a real defect, also emitted
+ *  as a RENDER_ERROR occurrence). */
+export type RenderOutcome = "ok" | "blank" | "error";
+/** A rule node. `engine` and `ruleId` are two DISTINCT dimensions, never concatenated into one id. */
+export interface RuleNode {
+    engine: DiagnosticEngine;
+    ruleId: string;
+    /** Optional composed label for display only (e.g. "axe:color-contrast"). Not an identity. */
+    displayKey?: string;
+}
+/** A component node — keyed on the discovery id (`collapseComponentId` form). */
+export interface DiagnosticComponentNode {
+    id: ComponentId;
+    render: RenderOutcome;
+}
+/** An occurrence edge: this rule fired on this component. References the rule by the (engine, ruleId)
+ *  pair — the same two distinct dimensions, not a concatenated node id. */
+export interface DiagnosticOccurrence {
+    engine: DiagnosticEngine;
+    ruleId: string;
+    component: ComponentId;
+    severity: DiagnosticSeverity;
+    message: string;
+    /** DOM path of the failing node, when the engine provides one (axe target / html-validate selector). */
+    domPath?: string;
+    tag: DiagnosticTag;
+}
+/** The project-wide diagnostics graph. Storage IS the graph; all tables are views over `occurrences`. */
+export interface DiagnosticsGraph {
+    rules: RuleNode[];
+    components: DiagnosticComponentNode[];
+    occurrences: DiagnosticOccurrence[];
+    /** ISO timestamp stamped by the caller after the pure build returns (build has no clock access). */
+    generatedAt?: string;
+    /** The subject's commit SHA when it has one (pinned in the report). */
+    subjectSha?: string;
+}
+/** The §0 scope boundary — embedded verbatim in every report/view so the artifact states its own
+ *  limits. Corrected for the sweep's real coverage: the rendered-contrast (needsRendering) axe tier
+ *  is a named exclusion (it needs browser layout the static jsdom sweep cannot produce). */
+export declare const SCOPE_BOUNDARY = "## Scope \u2014 the boundary is part of the artifact\n\n**Covers** \u2014 machine-detectable, static, single-render (no browser layout):\n- **HTML content-model** (html-validate) \u2014 nesting/permitted-content violations.\n- **Structural a11y** (axe, alwaysOn tier) \u2014 labels, names, ARIA, roles, image-alt.\n- **Schema** \u2014 required/shape violations against `component.schema.json`.\n- **Render outcome** \u2014 blank / error / ok (metadata, never itself a defect).\n\n**Deliberately NOT covered \u2014 named boundaries, not misses:**\n- **Rendered-contrast (axe needsRendering tier)** \u2014 contrast, aria-hidden-focus, duplicate-id-aria.\n  These require real browser layout/paint; the static jsdom sweep cannot produce them. The\n  per-component panel shows them (live iframe); this aggregate does not. Fewer rule types here is a\n  scope boundary, not a gap.\n- **Structural/graph findings** \u2014 dead subtrees, a shared-base \"component\", flattened variant families.\n  Those are the style graph's lens, not this one.\n- **PD reporting gaps** \u2014 PD under-claiming (e.g. missing provenance) is not a subject defect.\n- **Interactive / behavioural** \u2014 focus traps, keyboard flow, escape handling. Single static render only.\n- **Data-masked** \u2014 a component that renders empty for want of data won't throw the violations it would\n  when populated; findings are annotated with render outcome wherever it is blank.\n\nA component with zero findings is **not \"clean\" \u2014 it is \"clean of static machine-detectable defects.\"**\nThat is the honest claim; never \"clean\".";
+/** Per-rule roll-up: blast radius (distinct components) primary, occurrences secondary. */
+export interface AuditRuleRollup {
+    engine: string;
+    ruleId: string;
+    components: number;
+    occurrences: number;
+    tags: string[];
+}
+export interface AuditComponentRollup {
+    id: string;
+    render: RenderOutcome;
+    occurrences: Array<{
+        engine: string;
+        ruleId: string;
+        tag: DiagnosticTag;
+        message: string;
+        domPath?: string;
+    }>;
+}
+/** The `pd audit` report as structured data — the single rollup every output format serializes.
+ *  All roll-ups (headline numbers, rule blast-radius table, per-component list) are computed ONCE in
+ *  `buildAuditRollup`; `md`/`text`/`json` (and the workbench facet) are renderers over this object,
+ *  never independent string builders. A CI consumer reading the `json` gets `scope` (the §0 boundary)
+ *  + `headline` alongside the count, never a bare number. */
+export interface AuditRollup {
+    subjectSha?: string;
+    /** The headline sentence, plain (no markdown emphasis); renderers wrap/position it. */
+    headline: string;
+    totals: {
+        components: number;
+        affected: number;
+        cleanPct: number;
+        defects: number;
+    };
+    renderOutcomes: {
+        ok: number;
+        blank: number;
+        error: number;
+    };
+    rulesByBlast: AuditRuleRollup[];
+    perComponent: AuditComponentRollup[];
+    /** The §0 scope boundary, verbatim (SCOPE_BOUNDARY). Carried in every format. */
+    scope: string;
+}
+/** Build the structured rollup from the graph — the numbers exist as data here, not only as strings.
+ *  PURE: same graph → same rollup, no I/O or clock. The one builder both the CLI report renderers and
+ *  the workbench audit facet call. */
+export declare function buildAuditRollup(graph: DiagnosticsGraph, opts?: {
+    subjectSha?: string;
+}): AuditRollup;
+/**
+ * GET /api/version
+ * Build identity of the running dev server, so a human or script (scripts/check-server-fresh.mjs)
+ * can tell whether the process answering is behind the artifacts on disk. Frozen at boot.
+ */
+export interface VersionInfo {
+    /** Wall-clock start, ISO-8601. */
+    startedAt: string;
+    /** mtime (ms) of the dev-server bundle this process actually loaded, read at startup. */
+    serverBundleMtime: number | null;
+    /** PD_PROTOCOL_VERSION the server was built with. */
+    protocol: number;
+}
+/**
+ * GET /api/component/:id
+ * Everything the panel + preview need for one component. The shell never reads the
+ * filesystem — this is the whole picture.
+ */
+export interface ComponentDetail {
+    id: ComponentId;
+    title: string;
+    description: string;
+    category: Category;
+    status: ComponentStatus;
+    /** If status === "deprecated". */
+    deprecatedUse?: string;
+    /** Resolved preview layout mode (M4.2) — see LayoutMode. Always present (a default always applies). */
+    layout: LayoutMode;
+    /**
+     * Full preview HTML document for the default variant, ready to assign directly to
+     * `iframe.srcdoc`. Non-default variants are fetched on demand via `previewUrl()`.
+     * Root-relative asset links (`/_pd/*.css`, `/assets/...`) resolve because an unsandboxed
+     * srcdoc iframe inherits the parent origin; the static build will supply a `<base href>`
+     * via `buildPreviewDocument`'s `baseHref` parameter instead.
+     *
+     * Always present in live dev-server responses. Optional in the type because
+     * `buildComponentDetail` returns the rest of the detail without it — the HTTP handler
+     * computes and appends it before sending the JSON payload.
+     */
+    document?: string;
+    /** Switchable variants for the toolbar. The default (no variant) is always available implicitly. */
+    variants: VariantRef[];
+    /** Source files, for the source tab's HBS/HTML toggle and any future viewers. */
+    source: ComponentSource;
+    /** Rendered markdown documentation for the docs tab. Absent if no `.md`.
+     *  M4.1: fenced code blocks inside are Shiki-highlighted at render time (class-based HTML);
+     *  `pattern` embed blocks are NOT highlighted — they render the real component via render(). */
+    doc?: string;
+    /**
+     * Composition-aggregated behaviour script ids and CDN URLs from `requireScript` frontmatter.
+     * Bare ids are served at /_pd/scripts/<id>.js (ESbuild-compiled from scriptsDir).
+     * Absolute URLs (contain `://`) are CDN refs injected as-is.
+     * Deduped, preserving declaration order. Absent when none declared in the component tree.
+     */
+    requireScripts?: string[];
+    /**
+     * Composition-aggregated SVG symbol set ids from `requireAssets` frontmatter.
+     * Each id resolves to a symbol set SVG in the project assets dir, inlined hidden at the top
+     * of the preview body to enable same-document `<use href="#id">` with currentColor inheritance.
+     * Deduped. Absent when none declared.
+     */
+    requireAssets?: string[];
+    /** Composition + style relationships for this component (M5). Discriminated on `available`. */
+    relationships: Relationships;
+    /** Per-render diagnostics for the selected component + variant (M4.9). Empty = clean render. */
+    diagnostics: Diagnostic[];
+}
+export interface ComponentSource {
+    /** Raw Handlebars template text. Always present (`.hbs` is the only required file).
+     *  Raw is the copy source of truth — the copy button copies this, never the highlighted markup. */
+    hbs: string;
+    /** Render-time Shiki-highlighted HBS as class-based HTML (M4.1). For display in the source tab. */
+    hbsHighlighted: string;
+    /** Raw default-variant data, if a `component.json` exists (optional per M2).
+     *  Per-variant data comes via `dataSourceUrl` (not carried in the payload). */
+    json?: string;
+    /** Highlighted JSON, present whenever `json` is. */
+    jsonHighlighted?: string;
+    /** Raw `component.schema.json`, if the file exists. Component-level; does not vary with variant. */
+    schema?: string;
+    /** Shiki-highlighted schema JSON. Present whenever `schema` is. */
+    schemaHighlighted?: string;
+    /** Raw markdown source, if present. (Highlighted fenced blocks live in the RENDERED doc — the
+     *  `doc` field on ComponentDetail — not here; this is the raw `.md` for reference/copy.) */
+    md?: string;
+}
+/**
+ * The relationships facet payload (M5) — two layers of edges:
+ *   - composition (template): uses / usedBy — from the flat-partial registry.
+ * Three DISTINCT style relationships — kept separable in the graph, do not conflate:
+ *   - style (component class-borrowing): styleUses — components whose CSS classes appear in this
+ *       component's own markup (.hbs), attributed via a class→owner index built from compiled
+ *       CSS source maps. styleUsedBy is intentionally omitted (it's the transpose of every
+ *       component's styleUses; recompute on demand for impact analysis).
+ *   - style (@use dependency): styleUsesModules — shared base/token/mixin modules this component's
+ *       SCSS @use/@forward-imports. This is a SCSS dependency, not a worn class. Convention:
+ *       components must not @use another component's SCSS; if violated the target degrades to a
+ *       plain module path here (non-navigable).
+ *   - style (module class-borrowing): styleModules — shared/family modules that AUTHOR a class worn
+ *       by this component's markup but belong to no component (the module-level analog of styleUses).
+ *       These are the classes that would otherwise vanish into the base layer unattributed.
+ *   - style (leftovers): inlineStyles, utilityClasses, unattributedClasses — honest accounting
+ *       for classes that don't map to a known component or module.
+ *
+ * Determinism: arrays are sorted and deduplicated — byte-identical for an unchanged tree.
+ */
+/** A shared SCSS module that belongs to no component (e.g. "00-base/tokens"). Non-navigable. */
+export type StyleModuleId = string;
+export interface RelationshipsAvailable {
+    /** Always true. The "not yet computed" placeholder arm this once discriminated was never produced
+     *  and has been removed; the flag stays so existing payload readers keep working. */
+    available: true;
+    /** Components this one includes via template partials (composition). */
+    uses: ComponentId[];
+    /** Components that include this one (inverse composition). */
+    usedBy: ComponentId[];
+    /** Components whose CSS classes appear in this component's own markup (class-borrowing). */
+    styleUses: ComponentId[];
+    /** Shared SCSS modules this component's SCSS @use/@forward-imports — a dependency, not a worn
+     *  class (non-navigable). */
+    styleUsesModules: StyleModuleId[];
+    /** Shared/family modules that authored a class worn by this component's markup but belong to no
+     *  component — the module-level analog of styleUses (non-navigable). */
+    styleModules: StyleModuleId[];
+    /** True if markup contains style="" attributes or inline <style> blocks. */
+    inlineStyles: boolean;
+    /** True if any used class is owned by a registered utility source (e.g. Tailwind). */
+    utilityClasses: boolean;
+    /** CSS classes used in markup whose ownership is unrecognised (typos, dead, unregistered). */
+    unattributedClasses: string[];
+}
+export type Relationships = RelationshipsAvailable;
+/**
+ * GET /api/overview/:path   (M4.3 — was /api/category/:cat in M4.2)
+ * The overview page for a FOLDER — a top-level category ("atoms") or an intermediate group
+ * ("atoms/input"). The `index.md` (if any) plus the ordered list of the PUBLIC components in that
+ * folder's subtree, for the "show me all of these" gallery. Each item renders as its real component
+ * in its own isolated preview (via previewUrl), so the gallery is a list of <figure> illustrations.
+ *
+ * `index.md` is optional: with none, `doc` is absent and the gallery is auto-generated from
+ * `components` using the folder's default layout. Component nodes do NOT get a folder overview
+ * (their "all variants" gallery is M4.4); overviews belong to group/category folders.
+ */
+export interface FolderOverview {
+    /** Folder path — "atoms" or "atoms/input". */
+    path: string;
+    /** Rendered `index.md` body, if the folder has one (M4.1 highlighting applies to its fences). */
+    doc?: string;
+    /** Resolved layout mode for this folder's previews (component overrides still win per item). */
+    layout: LayoutMode;
+    /** The public components in this folder's subtree, in tree order (pre-order, siblings as in
+     *  ComponentTree) — the same order the Nav Rail shows. Each rendered live. */
+    components: FolderOverviewItem[];
+}
+export interface FolderOverviewItem {
+    id: ComponentId;
+    /** The pattern package this component comes from; absent for the project's own. */
+    source?: string;
+    title: string;
+    status: ComponentStatus;
+    /** Per-item resolved layout (usually the folder default; a component may override). */
+    layout: LayoutMode;
+}
+/**
+ * Returns the URL for a component's standalone preview document.
+ *
+ * Used for:
+ *   - On-demand fetch of non-default variant documents (`fetch(previewUrl(id, v)).then(r=>r.text())`)
+ *   - HMR content-swap re-fetch
+ *   - Open-in-new-tab links
+ *
+ * The single-preview iframe is driven by `srcdoc`, NOT `src` — this URL is never assigned
+ * to `iframe.src`. Keeping the route active for the use cases above.
+ *
+ * `theme` bakes `data-theme` into the served `<body>` pre-paint, fixing the one-frame flash
+ * on non-default themes. Pass the current user theme so the iframe renders correctly without
+ * waiting for the `iframe.load` handler. An empty string or absent value uses the config default.
+ *
+ * GET /preview/:id                       → default-data, config-default theme
+ * GET /preview/:id?variant=x             → variant document
+ * GET /preview/:id?theme=dark            → config-default variant, dark theme pre-baked
+ * GET /preview/:id?variant=x&theme=dark  → variant + theme
+ */
+export declare function previewUrl(id: ComponentId, variant?: string, theme?: string): string;
+/**
+ * The source tab's "rendered HTML" view (M4.1 — DECIDED).
+ *
+ * The rendered HTML is per-variant and HMR-volatile (it changes on every `content-swap`),
+ * so — unlike the static `.hbs`/`.json` source, which rides in ComponentSource — it is NOT
+ * carried in the once-fetched ComponentDetail. The shell fetches the Shiki-highlighted
+ * rendered fragment by URL, lazily, only when this view is selected, and re-fetches on a
+ * `content-swap` for the current variant. This mirrors the per-variant `previewUrl` model.
+ *
+ * GET /source/:id/rendered            → highlighted rendered HTML for default data
+ * GET /source/:id/rendered?variant=x  → highlighted rendered HTML for a variant
+ *
+ * Returns class-based highlighted HTML (same Shiki stylesheet as ComponentSource.*Highlighted).
+ * There is deliberately no `htmlHighlighted` field on ComponentSource.
+ */
+export declare function renderedSourceUrl(id: ComponentId, variant?: string): string;
+/**
+ * The data file for a component selection (JSON tab, M4.6).
+ *
+ * Per-variant data is HMR-volatile (it changes when the variant file changes), so it is NOT
+ * carried in the once-fetched ComponentDetail. The shell fetches the Shiki-highlighted data
+ * fragment lazily (only when the JSON tab is selected) and re-fetches on a `content-swap`.
+ * The default-variant data is also available via this route for consistency.
+ *
+ * GET /source/:id/data            → highlighted default data (component.json)
+ * GET /source/:id/data?variant=x  → highlighted variant data (component~x.json)
+ *
+ * Returns class-based highlighted HTML (same Shiki stylesheet as ComponentSource.*Highlighted).
+ */
+export declare function dataSourceUrl(id: ComponentId, variant?: string): string;
+/**
+ * Folder overview route (M4.3). Addressed by folder path, any depth.
+ * GET /api/overview/atoms          → top-level category overview
+ * GET /api/overview/atoms/input    → intermediate group overview
+ */
+export declare function overviewUrl(path: string): string;
+/** Fixed-path routes. */
+export declare const PD_ROUTES: {
+    /** GET → ComponentTree */
+    readonly tree: "/api/tree";
+    /** GET → AuditResponse (500 → ApiError) */
+    readonly audit: "/api/audit";
+    /** GET → ThemeSummary[] */
+    readonly themes: "/api/themes";
+    /** GET → VersionInfo */
+    readonly version: "/api/version";
+    /** GET → ShellClientConfig */
+    readonly config: "/api/config";
+    /** The shell bundle, stylesheet and vendored assets. */
+    readonly mainJs: "/_pd/main.js";
+    readonly mainCss: "/_pd/main.css";
+    readonly axeCore: "/_pd/axe-core.js";
+    /** GET → RuleTiers */
+    readonly ruleTiers: "/_pd/rule-tiers.json";
+    readonly shikiCss: "/_pd/shiki.css";
+    /** Document-base layer (reset + font-face). */
+    readonly baseCss: "/_pd/base.css";
+};
+/** Prefixes of the parameterised routes. routes.ts matches with these; the builders emit them. */
+export declare const PD_ROUTE_PREFIX: {
+    readonly component: "/api/component/";
+    readonly overview: "/api/overview/";
+    readonly preview: "/preview/";
+    readonly source: "/source/";
+    readonly componentCss: "/_pd/components/";
+    readonly themeCss: "/_pd/themes/";
+    readonly script: "/_pd/scripts/";
+    readonly assets: "/assets/";
+};
+/**
+ * GET /api/component/:id[?variant=x] → ComponentDetailResponse (404 → ApiError).
+ * A quarantined or failing component is still 200, carrying its diagnostic.
+ */
+export declare function componentUrl(id: ComponentId, variant?: string): string;
+/** Per-component own-origin CSS. `version` is a cache-buster (`?v=`), ignored by the server. */
+export declare function componentCssUrl(id: ComponentId, version?: number | string): string;
+/** Per-theme CSS. 404 when the theme is unknown or no themes dir is configured. */
+export declare function themeCssUrl(name: string): string;
+/** A compiled behaviour script (esbuild, from scriptsDir). `version` is a cache-buster. */
+export declare function scriptUrl(id: string, version?: number | string): string;
+/** How the shell switches component themes in the preview: toggle `data-theme` on one set of
+ *  linked theme stylesheets, or swap a single theme stylesheet (for bare-`:root` theme sets). */
+export type ThemeSwitch = "attribute" | "stylesheet";
+/** GET /api/config — the server-declared settings the shell reads once at startup. */
+export interface ShellClientConfig {
+    /** The project's `shell` config block, or null when it has none. */
+    shell: {
+        brand?: import("./index.js").ShellBrandConfig;
+    } | null;
+    themeSwitch: ThemeSwitch;
+    /** The configured default theme — what an un-themed preview actually shows. "" when none. */
+    defaultTheme: string;
+}
+/** The body of every JSON error response. */
+export interface ApiError {
+    error: string;
+}
+/** GET /api/audit — the diagnostics graph, stamped at response time. */
+export interface AuditResponse extends DiagnosticsGraph {
+    generatedAt: string;
+    /** Surgical HMR re-audits since startup — a debug instrument (rises by exactly 1 per .hbs edit,
+     *  0 per .scss edit). Not part of the graph; the leading underscore marks it as diagnostic. */
+    _liveReaudits: number;
+}
+/** GET /_pd/rule-tiers.json — the generated axe rule classification (packages/a11y classifier). */
+export interface RuleTiers {
+    /** Rules the static (jsdom) sweep runs. */
+    alwaysOn: string[];
+    /** Rules whose verdict needs real browser layout — run only in the live iframe. */
+    needsRendering: string[];
+    /** Rules not yet classified. */
+    investigate: string[];
+    /** Provenance written by the classifier. */
+    _note?: string;
+    generatedAt?: string;
+    axeVersion?: string;
+}
+/** GET /api/component/:id — the live server always includes the preview document. */
+export type ComponentDetailResponse = ComponentDetail & {
+    document: string;
+};
+/** How the shell document was served, inlined as `window.__pd` by whichever side produced it. */
+export type ShellRuntime = {
+    mode: "live";
+    wsPort: number;
+} | {
+    mode: "static";
+    /** Where the snapshot is hosted: "/" at a domain root, or "/sub/path/" (always slash-wrapped). */
+    basePath: string;
+    /** ISO timestamp of the build. */
+    builtAt: string;
+    /** The pattern-dump version that built it. */
+    pdVersion: string;
+    /** false when built without the corpus audit (`pd build --no-audit`): no api/audit.json exists
+     *  and the shell offers no Audit tab. Absent means included. */
+    audit?: boolean;
+};
+/** "/pd", "pd/", "pd" → "/pd/"; "" and "/" → "/". */
+export declare function normalizeBasePath(basePath: string | undefined): string;
+/** The snapshot file (relative, no leading slash) that holds the response for a live URL.
+ *  The result is a URL PATH, still percent-encoded where the live URL was (`brand%20blue.css`): the
+ *  shell requests it as-is, a static host decodes it, so the build writes the DECODED name to disk. */
+export declare function staticPathFor(liveUrl: string): string;
+/**
+ * Protocol version of this file's wire shapes — HTTP responses AND socket messages.
+ *
+ * Bump it whenever a shape changes incompatibly (a field removed, renamed or retyped; an HMR arm
+ * removed). Adding an optional field does not need a bump. The server announces it three ways —
+ * the `hello` socket message, the `X-PD-Protocol` response header, and `VersionInfo.protocol` —
+ * and the shell compares it against the value it was bundled with, so a stale shell talking to a
+ * newer server says so instead of misbehaving silently. Same idea as GRAPH_ARTIFACT_VERSION.
+ */
+export declare const PD_PROTOCOL_VERSION = 1;
+/** Response header carrying PD_PROTOCOL_VERSION on every dev-server response. */
+export declare const PD_PROTOCOL_HEADER = "X-PD-Protocol";
+/**
+ * HMR socket messages, discriminated on `type`:
+ *  - hello         : sent once per connection — carries PD_PROTOCOL_VERSION.
+ *  - content-swap  : template / data / `.ts` change → re-fetch and swap the preview document.
+ *  - css-link-swap : SCSS change → re-point the per-component `<link>` in the live iframe, no reload.
+ *  - error         : a render or build failure, surfaced on the Console.
+ *  - tree-changed  : a component was added or removed → re-fetch the tree.
+ *  - collision     : a handle collision quarantined a component → surfaced on the Console.
+ *
+ * NOTE: A11yResult / meta.a11y were removed in M4.11. Rendered a11y findings are produced
+ * client-side (axe in the live iframe) and do not flow through the HMR channel.
+ */
+/**
+ * A CSS-only change rebuilt the affected component's origin file.
+ * The client finds the matching `<link data-pd-comp>` in the iframe and
+ * updates its href to the cache-busted URL — no srcdoc rewrite, no state loss.
+ */
+export interface CssLinkSwapMessage {
+    type: "css-link-swap";
+    /** Component whose per-origin CSS file changed. */
+    componentId: ComponentId;
+    /** New URL, e.g. "/_pd/components/atoms/button.css?v=1717000000000". */
+    href: string;
+    /**
+     * Ordered closure hrefs for the currently-previewed component (`lastComponentId`).
+     * Absent when no preview is active. Each href is `/_pd/components/<id>.css?v=<timestamp>`,
+     * in DFS post-order (deepest dependency first). The client reconciles the preview head's
+     * pd-managed links against this list: add missing, remove dead, bump survivors.
+     * Only components with non-empty CSS output are included.
+     */
+    orderedHrefs?: string[];
+}
+/** Fired when a .hbs is added or removed — client re-fetches /api/tree to rebuild the nav. */
+export interface TreeChangedMessage {
+    type: "tree-changed";
+}
+/** M6: a handle collision was detected at discovery time. Both paths are named so the author
+ *  can resolve the conflict (rename or move a file). The tree remains operational; the
+ *  quarantined component is excluded until the collision is resolved. */
+export interface CollisionMessage {
+    type: "collision";
+    handle: string;
+    incumbentPath: string;
+    quarantinedPath: string;
+}
+export type HmrMessage = HelloMessage | ContentSwapMessage | ErrorMessage | CssLinkSwapMessage | TreeChangedMessage | CollisionMessage;
+/** First frame on every connection. Lets the shell detect a protocol mismatch with the server. */
+export interface HelloMessage {
+    type: "hello";
+    protocol: number;
+}
+export interface ContentSwapMessage {
+    type: "content-swap";
+    componentId: ComponentId;
+}
+export interface ErrorMessage {
+    type: "error";
+    /** Which pipeline failed — keeps build errors from masquerading as render errors. */
+    scope: "build" | "render";
+    /** Component-scoped where known (e.g. a missing partial in this component). */
+    componentId?: ComponentId;
+    /** A legible, already-formatted message (per M1: not a raw Handlebars stack trace). */
+    message: string;
+}
+export {};