pattern-dump 0.1.0-alpha.0 → 0.1.0-alpha.2

package/dist/types/config/index.d.ts

@@ -1,7 +1,9 @@
 import type { ShellBrandConfig, SwatchSlots, ThemeSwitch } from "../contracts/index.js";
 export type { ShellBrandConfig, SwatchSlots, ThemeSwitch };
+export { ConfigError, configProblems, validateConfig } from "./validate.js";
 export interface AssetsConfig {
-    /** 'central' (default) serves the central assets dir; 'component-relative' resolves from component folder. */
+    /** Where assets live. Only 'central' (the default: one assets dir, served at /assets/) is supported
+     *  so far; 'component-relative' is reserved, and the config check rejects it as not supported yet. */
     strategy?: "central" | "component-relative";
     /**
      * Asset directory (relative to project root), served at /assets/. Accepts an ARRAY of roots —
@@ -11,12 +13,14 @@ export interface AssetsConfig {
      * normalized to `/assets/…` by matching a root basename — depth-independent.
      */
     dir?: string | string[];
-    /** CSS files (relative to assets dir) to link in every preview document, before component CSS. */
+    /** Stylesheets to link in every preview document, before component CSS: a path relative to the
+     *  assets dir, or a full URL (e.g. a web-font stylesheet), which is linked as it is. */
     css?: string[];
 }
 export interface StylesConfig {
-    /** 'parallel' (default, hTWOo-native) or 'co-located' (framework-oriented). */
-    strategy: "parallel" | "co-located";
+    /** Where styles live. Only 'parallel' (the default: a separate tree mirroring the patterns) is
+     *  supported so far; 'co-located' is reserved, and the config check rejects it as not supported yet. */
+    strategy?: "parallel" | "co-located";
     /** Source tree root; also the home for global/base/theme styles. */
     dir: string;
     /**
@@ -102,15 +106,18 @@ export interface PatternDumpConfig {
     helpers?: string;
     /**
      * The always-injected document-base layer (M5-CSS-EXTERNAL §2.2: a preview links
-     * closure + base + active theme). Names the base-origin path(s) — e.g.
-     * ['base/reset', 'base/root', 'base/font.base'] — relative to `styles.dir`.
+     * closure + base + active theme). Names file or folder paths — e.g.
+     * ['base/reset', 'base/root', 'base/font.base'] — relative to `styles.dir`; `"."` is the whole tree.
      *
-     * When present and non-empty, PD links the compiled base layer (`/_pd/base.css`, the
-     * origin-unattributed shared rules — resets, `:root`, `@font-face`, and family-level classes
-     * with no single owning component) into every preview, BENEATH the component closure so it
-     * never overrides it. Absent → not linked (current behaviour; a project whose classes all
-     * attribute to components needs no shared layer). The `__base__` layer must still carry no
-     * MIS-attributed rules — anything with a genuine owner attributes to that owner.
+     * When present and non-empty, PD links the compiled base layer (`/_pd/base.css`) into every
+     * preview, BENEATH the component closure so it never overrides it. The layer holds:
+     *  - every rule from a LISTED path, even one whose file belongs to a component (a component's
+     *    `body` rule needed on every page, or a whole PatternLab stylesheet with `"."`);
+     *  - the origin-unattributed rules — `:root`, `@font-face`, family-level classes with no single
+     *    owning component — listed or not, so shared partials stay available.
+     * Entries that match no file are reported at startup. Absent → not linked (a project whose classes
+     * all attribute to components needs no shared layer). Class ownership is unchanged by listing: a
+     * class still belongs to the component whose file authored it.
      */
     documentBase?: string[];
     /**

package/dist/types/config/validate.d.ts

@@ -0,0 +1,10 @@
+import type { PatternDumpConfig } from "./index.js";
+/** A config that cannot be used, with a message written for the person editing it. The CLI prints
+ *  its message alone, without a stack trace. */
+export declare class ConfigError extends Error {
+    name: string;
+}
+/** The problems with a loaded config, one line each; empty when it is valid. */
+export declare function configProblems(raw: unknown): string[];
+/** Check a loaded config and return it typed, or throw one error listing every problem. */
+export declare function validateConfig(raw: unknown, source: string): PatternDumpConfig;

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

@@ -4,12 +4,13 @@ export type ComponentId = string;
 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)
+ * Preview layout mode (M4.2). How the component sits in the stage. The preview document is the same
+ * in both — the markup directly in <body>, no wrapper — only the frame around it differs:
+ *  - "centered": the frame is sized to what the content needs (pd-width, measured at the full width
+ *                available) and to its height (pd-height), and the stage centres it (atoms/molecules/organisms)
+ *  - "full":     the frame 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).
+ * so the shell renders directly without re-deriving precedence.
  */
 export type LayoutMode = "centered" | "full";
 /** A named data set applied over defaults — a state or a documentation example. */
@@ -164,10 +165,22 @@ export interface DiagnosticsGraph {
     /** 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\".";
+/** One line of the audit scope: a named area and what it means. */
+export interface AuditScopeItem {
+    name: string;
+    detail: string;
+}
+/** What the corpus audit checks and what it deliberately leaves out. Carried with every audit result
+ *  (every `pd audit` format and the workbench's Audit tab), because a defect count is only meaningful
+ *  next to its limits. Data, not formatted text: each renderer (Markdown, plain text, JSON, the
+ *  workbench's DOM) formats it for its own medium. */
+export interface AuditScope {
+    covered: AuditScopeItem[];
+    notCovered: AuditScopeItem[];
+    /** The closing statement on what zero findings means. */
+    note: string;
+}
+export declare const AUDIT_SCOPE: AuditScope;
 /** Per-rule roll-up: blast radius (distinct components) primary, occurrences secondary. */
 export interface AuditRuleRollup {
     engine: string;
@@ -190,8 +203,8 @@ export interface AuditComponentRollup {
 /** 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. */
+ *  never independent string builders. A CI consumer reading the `json` gets `scope` (what the audit covers)
+ *  and `headline` alongside the count, never a bare number. */
 export interface AuditRollup {
     subjectSha?: string;
     /** The headline sentence, plain (no markdown emphasis); renderers wrap/position it. */
@@ -209,8 +222,8 @@ export interface AuditRollup {
     };
     rulesByBlast: AuditRuleRollup[];
     perComponent: AuditComponentRollup[];
-    /** The §0 scope boundary, verbatim (SCOPE_BOUNDARY). Carried in every format. */
-    scope: string;
+    /** What the audit covers and leaves out (AUDIT_SCOPE). Carried in every format. */
+    scope: AuditScope;
 }
 /** 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pattern-dump",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.2",
   "description": "A workbench for HTML and CSS design systems: live component previews, docs, checks and static publishing.",
   "keywords": [
     "design-system",
@@ -50,7 +50,8 @@
     "dist",
     "templates",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "engines": {
     "node": ">=20.10"