pattern-dump 0.1.0-alpha.3 → 0.2.0-alpha.0

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

@@ -1,6 +1,6 @@
 import type { ShellBrandConfig, SwatchSlots, ThemeSwitch } from "../contracts/index.js";
 export type { ShellBrandConfig, SwatchSlots, ThemeSwitch };
-export { ConfigError, configProblems, validateConfig } from "./validate.js";
+export { ConfigError, configProblems, sameHostWorkbenchPath, suggest, validateConfig } from "./validate.js";
 export interface AssetsConfig {
     /** 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. */
@@ -37,9 +37,10 @@ export interface StylesConfig {
     entry?: string | string[];
 }
 export interface ThemesConfig {
-    /** Directory of theme files (custom-property value-sets). */
-    dir: string;
-    /** Default theme name applied via data-theme on the preview body. */
+    /** Directory of the project's own theme files (custom-property value-sets). Leave it out to use
+     *  only the themes pattern packages provide, with `default` naming one of them. */
+    dir?: string;
+    /** Default theme name applied via data-theme on the preview body: a project theme or a package's. */
     default: string;
     /** Switch wiring: attribute toggle (default) or per-theme stylesheet swap. */
     switch?: ThemeSwitch;
@@ -66,10 +67,17 @@ export interface ShellConfig {
  * invoking `cwd`. This holds even when the file is supplied via `--config` from outside the
  * root — which is what lets PD open a read-only project it does not own.
  */
-/** A pattern package named in the config: the npm name, or the name plus extra excludes. */
+/**
+ * A pattern package named in the config: the npm name, or the name plus options.
+ * - `exclude`: extra globs of the package's templates to hide.
+ * - `styles: false`: leave the package's stylesheets out (its templates, data, themes, scripts and
+ *   assets are still used), e.g. when the project compiles that CSS itself. A package reached only
+ *   as another package's peer can be named here just to carry this option.
+ */
 export type PackageReference = string | {
     name: string;
     exclude?: string[];
+    styles?: boolean;
 };
 export interface PatternDumpConfig {
     sourceDir: string;
@@ -148,5 +156,90 @@ export interface PatternDumpConfig {
         basePath?: string;
         audit?: boolean;
     };
+    /** How responsive image variants are encoded (WebP). Defaults: quality 75, effort 4. A site can override
+     *  either in `storefront.images`. */
+    images?: ImageSettings;
+    /** The storefront: a website of real HTML pages, written from markdown, beside the workbench. */
+    storefront?: StorefrontConfig;
+}
+/**
+ * The storefront. `pd dev` serves it on its own host (`live.localhost` unless `host` says otherwise),
+ * the workbench on `pd.localhost`, both from `/`. `pd build` writes it to its own folder, apart from
+ * the workbench snapshot. A page renders with the layout `layouts/<layout>` from the project's patterns.
+ */
+/** How responsive image variants are encoded. */
+export interface ImageSettings {
+    /** WebP quality, a whole number from 1 to 100. Default: 75. */
+    quality?: number;
+    /** WebP effort, 0 (fastest) to 6 (smallest files). Default: 4. */
+    effort?: number;
 }
+export interface StorefrontConfig {
+    /** Folder of the pages, relative to the root. `index.md` is `/`, `guides/setup.md` is `/guides/setup/`.
+     *  `pagesDir`, `patternsDir` and `outDir` are three separate folders: none is another, and none is inside
+     *  another. */
+    pagesDir: string;
+    /** Where `pd build` writes the storefront, relative to the root. Its own folder, apart from the workbench
+     *  snapshot, and separate from `pagesDir` and `patternsDir` (see `pagesDir`). */
+    outDir: string;
+    /** The host name `pd dev` serves the storefront on. Default: `live.localhost`. */
+    host?: string;
+    /**
+     * Where the built workbench will be hosted: an absolute http(s) URL with no query or fragment, e.g.
+     * `https://workbench.example.com/`, or, for a workbench on the storefront's own host, a path such as
+     * `/workbench/` (then built with that base path, and its previews kept out of the storefront's
+     * `robots.txt`; an absolute URL on `url`'s origin counts as the same host too). Loaded with exactly
+     * one trailing slash, whether written with one or not; links from storefront pages to the workbench are
+     * this value followed by a path. Used by `pd build` only: in `pd dev` those links always go to
+     * `http://pd.localhost:<port>`, the workbench of the same process.
+     */
+    workbenchUrl?: string;
+    /**
+     * The site's address, such as `https://example.com/`: an absolute http(s) URL with no path (the storefront
+     * is served from the root of its host), no query or fragment; loaded as its origin followed by `/`. With it,
+     * pages get a canonical URL, Open Graph and JSON-LD, and `pd build` writes a sitemap; without it they are
+     * left out, and `pd build` says so once.
+     */
+    url?: string;
+    /** The language of every page, as `<html lang>` takes it (a BCP 47 tag such as `de-AT`). Default: `en`. */
+    lang?: string;
+    /**
+     * `false` keeps the whole site out of search engines (a staging site): every page gets `noindex`,
+     * `robots.txt` disallows everything, and there is no sitemap. Default: `true`.
+     */
+    index?: boolean;
+    /** The image a page shows in link previews when it names none of its own: a raster image in the assets
+     *  (PNG, JPEG, GIF or WebP), such as `/assets/images/share.png`. */
+    image?: string;
+    /** This site's image encoding, over the project's `images`. */
+    images?: ImageSettings;
+    /**
+     * Values every page of the site shares, such as its title or the line in its footer. Every layout gets
+     * them as `site`; a page cannot set them. Which keys there are, and their types, is what the `site`
+     * property of `partials/base`'s schema declares: they are checked against it, not inferred.
+     *
+     * One key is Pattern Dump's: `navigations`, named lists of links (a footer's, a sidebar's), each entry a
+     * page, an external link or a group, nested to any depth. Their shape is fixed (StorefrontNavEntry) and
+     * checked by Pattern Dump; the skin's schema only lists the names it uses.
+     */
+    site?: Record<string, unknown> & {
+        navigations?: Record<string, StorefrontNavEntry[]>;
+    };
+}
+/**
+ * One entry of a declared navigation (`storefront.site.navigations.<name>`):
+ * - a page, by its path in the pages folder (`"guides/setup.md"`), labelled with its title unless `label`;
+ * - an external link: `href` is `https:`, `http:` or `mailto:`, or a path from the site's root (`/feed.xml`);
+ * - a group: a `label` and its `children`, entries of any of the three kinds.
+ */
+export type StorefrontNavEntry = {
+    page: string;
+    label?: string;
+} | {
+    href: string;
+    label: string;
+} | {
+    label: string;
+    children: StorefrontNavEntry[];
+};
 export declare function defineConfig(config: PatternDumpConfig): PatternDumpConfig;

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

@@ -1,4 +1,7 @@
 import type { PatternDumpConfig } from "./index.js";
+/** The closest of `known` to `key` when it is near enough to be a typo of it, else undefined. Used for
+ *  "did you mean" in config problems, and by other checks that name an unknown key. */
+export declare function suggest(key: string, known: string[]): string | undefined;
 /** 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 {
@@ -8,3 +11,12 @@ export declare class ConfigError extends Error {
 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;
+/**
+ * The path of a workbench published on the storefront's own host, or undefined when it has a host of its own.
+ * Same-host means a root-relative `workbenchUrl` ("/workbench/"), or an absolute one on the origin of
+ * `storefront.url`. Reads a validated config, so both are already normalised (one trailing slash).
+ */
+export declare function sameHostWorkbenchPath(storefront: {
+    workbenchUrl?: string;
+    url?: string;
+} | undefined): string | undefined;

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

@@ -70,7 +70,7 @@ export interface TreeNode {
     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";
+export type DiagnosticKind = "RENDER_ERROR" | "UNFILLED_REQUIRED" | "SHAPE_MISMATCH" | "HTML_INVALID" | "CASCADE_WARNING" | "A11Y" | "HIGHLIGHT_FALLBACK" | "HANDLE_COLLISION" | "DATA_INVALID" | "SCHEMA_INVALID";
 /** Fields every diagnostic carries, whichever engine produced it. */
 interface DiagnosticBase {
     severity: DiagnosticSeverity;
@@ -81,7 +81,10 @@ interface DiagnosticBase {
     ruleId?: string;
     /** JSON Schema / data pointer, e.g. "#/properties/label" — schema kinds only. */
     path?: string;
-    /** Source-file position — RENDER_ERROR, best-effort. */
+    /** Source-file position — RENDER_ERROR and DATA_INVALID, best-effort. `file` is never an absolute
+     *  path: relative to the project root for the project's own files (`src/patterns/atoms/x/x.json`),
+     *  `<package name>/<path in the package>` for a pattern package's (`@acme/ds/patterns/atoms/x/x.json`).
+     *  Output built anywhere names a file the same way, and names no folder of the machine it ran on. */
     location?: {
         file?: string;
         line?: number;
@@ -464,6 +467,14 @@ export declare const PD_ROUTES: {
     readonly version: "/api/version";
     /** GET → ShellClientConfig */
     readonly config: "/api/config";
+    /** GET → StorefrontPagesResponse, on the storefront host. What `pd build` crawls for storefront pages. */
+    readonly pages: "/api/pages";
+    /** GET → the storefront's sitemap (XML), on the storefront host; only when `storefront.url` is set. */
+    readonly sitemap: "/sitemap.xml";
+    /** GET → robots.txt (text): the storefront's on the storefront host, the workbench's on every other host. */
+    readonly robots: "/robots.txt";
+    /** GET → the storefront's 404 page (HTML, status 404), on the storefront host. `pd build` writes it as is. */
+    readonly notFound: "/404.html";
     /** The shell bundle, stylesheet and vendored assets. */
     readonly mainJs: "/_pd/main.js";
     readonly mainCss: "/_pd/main.css";
@@ -474,6 +485,16 @@ export declare const PD_ROUTES: {
     /** Document-base layer (reset + font-face). */
     readonly baseCss: "/_pd/base.css";
 };
+/**
+ * The two front ends of one `pd dev` process, told apart by the request's Host header. Both serve
+ * from `/`. Plain `localhost` and `127.0.0.1` also get the workbench. `storefront.host` in the config
+ * replaces the storefront default, which is a host of pd dev's only when there is a storefront. A request
+ * for any other host is refused (403).
+ */
+export declare const PD_HOSTS: {
+    readonly storefront: "live.localhost";
+    readonly workbench: "pd.localhost";
+};
 /** Prefixes of the parameterised routes. routes.ts matches with these; the builders emit them. */
 export declare const PD_ROUTE_PREFIX: {
     readonly component: "/api/component/";
@@ -484,6 +505,7 @@ export declare const PD_ROUTE_PREFIX: {
     readonly themeCss: "/_pd/themes/";
     readonly script: "/_pd/scripts/";
     readonly assets: "/assets/";
+    readonly images: "/_pd/images/";
 };
 /**
  * GET /api/component/:id[?variant=x] → ComponentDetailResponse (404 → ApiError).
@@ -496,6 +518,21 @@ export declare function componentCssUrl(id: ComponentId, version?: number | stri
 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;
+/**
+ * A responsive image variant, served immutable: WebP, `width` pixels wide, of the asset `name` (its path under the
+ * assets folder without its extension, e.g. "images/harbour"). `hash` is the variant's key, the first 10 hex
+ * digits of a SHA-256 over the source's bytes and what the variant is encoded with, so the URL changes whenever
+ * its bytes would. Each segment of `name` is encoded.
+ */
+export declare function imageUrl(name: string, hash: string, width: number): string;
+/** An image variant URL's parts (`name` decoded), or null when the path is not one: an empty, "." or ".."
+ *  segment, a segment that doesn't decode, a hash that isn't 10 hex digits, a width that isn't a whole number
+ *  from 1, written without leading zeros. */
+export declare function parseImageUrl(pathname: string): {
+    name: string;
+    hash: string;
+    width: number;
+} | null;
 /** 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";
@@ -509,6 +546,31 @@ export interface ShellClientConfig {
     /** The configured default theme — what an un-themed preview actually shows. "" when none. */
     defaultTheme: string;
 }
+/** One storefront page: a markdown file in `storefront.pagesDir`, at the route its path defines. */
+export interface StorefrontPage {
+    /** Root-relative and slash-wrapped: "/" for pages/index.md, "/guides/setup/" for pages/guides/setup.md. */
+    route: string;
+    /** The page's `title`, or its route when it has none. */
+    title: string;
+    /** The layout it renders with: the component `layouts/<layout>`. */
+    layout: string;
+    /** Old routes that forward to this page (frontmatter `redirectFrom`), each root-relative and slash-wrapped.
+     *  `pd build` writes a forwarding page at each. Absent when the page has none. */
+    redirectFrom?: string[];
+}
+/** A nav entry. Top-level pages and folders; a folder's pages are its children (one level only). */
+export interface StorefrontNavItem {
+    route: string;
+    title: string;
+    /** The page's `description` from its frontmatter; absent when it has none. */
+    description?: string;
+    children?: StorefrontNavItem[];
+}
+/** GET /api/pages — every storefront page and the nav, in nav order. */
+export interface StorefrontPagesResponse {
+    pages: StorefrontPage[];
+    nav: StorefrontNavItem[];
+}
 /** The body of every JSON error response. */
 export interface ApiError {
     error: string;
@@ -563,7 +625,9 @@ 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 —
+ * removed). Adding an optional field does not need a bump, and neither does adding an HMR arm: a shell
+ * bundled before the arm existed receives it, matches none of its handlers and does nothing. 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.
@@ -571,6 +635,20 @@ export declare function staticPathFor(liveUrl: string): string;
 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";
+/**
+ * The live-reload generation a `pd dev` response was rendered from: `<boot>.<n>`, where `<boot>` names the
+ * server process and `<n>` counts the reload messages it has sent. Sent by a live server on every response
+ * (this header), in `hello`, and on every reload message (content-swap, css-link-swap, tree-changed,
+ * page-changed), bumped when such a message is sent, after the change's state is in place. A request takes
+ * it before anything else, so a document rendered while a change landed carries the generation from before
+ * it. A client that later sees a newer one knows its document may predate a change it never heard about
+ * (sent while its socket was not open, or while its fetch was in flight) and fetches it again. Absent when
+ * the server has no live reload (`pd build`). Additive: no protocol bump.
+ */
+export declare const PD_GENERATION_HEADER = "X-PD-Generation";
+/** True when generation `a` is older than `b`: from an earlier server process, or a lower count. Either
+ *  absent compares as not behind (a server without live reload never makes a client refetch). */
+export declare function generationBehind(a: string | undefined | null, b: string | undefined | null): boolean;
 /**
  * HMR socket messages, discriminated on `type`:
  *  - hello         : sent once per connection — carries PD_PROTOCOL_VERSION.
@@ -579,6 +657,8 @@ export declare const PD_PROTOCOL_HEADER = "X-PD-Protocol";
  *  - 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.
+ *  - page-changed  : a storefront page (or the nav) changed → storefront pages reload. The
+ *                    workbench shell receives it too and ignores it.
  *
  * 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.
@@ -602,10 +682,20 @@ export interface CssLinkSwapMessage {
      * Only components with non-empty CSS output are included.
      */
     orderedHrefs?: string[];
+    /**
+     * Present (true) when the component's CSS was empty before this change and is not now. A component with
+     * no CSS gets no link (the link set holds linkable components only), so a document rendered while it
+     * was empty has no link for it to update.
+     */
+    cssBecameNonEmpty?: true;
+    /** The generation this message bumped the server to (PD_GENERATION_HEADER); set by the server. */
+    generation?: string;
 }
 /** Fired when a .hbs is added or removed — client re-fetches /api/tree to rebuild the nav. */
 export interface TreeChangedMessage {
     type: "tree-changed";
+    /** The generation this message bumped the server to (PD_GENERATION_HEADER); set by the server. */
+    generation?: string;
 }
 /** 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
@@ -616,15 +706,27 @@ export interface CollisionMessage {
     incumbentPath: string;
     quarantinedPath: string;
 }
-export type HmrMessage = HelloMessage | ContentSwapMessage | ErrorMessage | CssLinkSwapMessage | TreeChangedMessage | CollisionMessage;
+/** A storefront page changed. `route` names the page ("/guides/setup/"); null means a page was added
+ *  or removed, so the nav — and with it every page — changed. */
+export interface PageChangedMessage {
+    type: "page-changed";
+    route: string | null;
+    /** The generation this message bumped the server to (PD_GENERATION_HEADER); set by the server. */
+    generation?: string;
+}
+export type HmrMessage = HelloMessage | ContentSwapMessage | ErrorMessage | CssLinkSwapMessage | TreeChangedMessage | CollisionMessage | PageChangedMessage;
 /** First frame on every connection. Lets the shell detect a protocol mismatch with the server. */
 export interface HelloMessage {
     type: "hello";
     protocol: number;
+    /** The current live-reload generation (PD_GENERATION_HEADER). */
+    generation?: string;
 }
 export interface ContentSwapMessage {
     type: "content-swap";
     componentId: ComponentId;
+    /** The generation this message bumped the server to (PD_GENERATION_HEADER); set by the server. */
+    generation?: string;
 }
 export interface ErrorMessage {
     type: "error";

package/dist/types/contracts/iframe-fit.d.ts

@@ -0,0 +1,33 @@
+/** What the embedding page does with a decision. Only `write` is required. */
+export interface HeightFitAdapter {
+    /** Set the frame's height, in CSS px. */
+    write(frame: HTMLIFrameElement, height: number): void;
+    /** Whether this frame content-fits its height at all (a full-page preview does not). Default: yes. */
+    fits?(frame: HTMLIFrameElement): boolean;
+    /** Called once when a frame's height turns out to be circular, after it was set back to its steady height. */
+    onCircular?(frame: HTMLIFrameElement): void;
+    /** Called when a frame's history is forgotten (its document was replaced or restyled). */
+    onReset?(frame: HTMLIFrameElement): void;
+}
+/** Per frame: the height last applied, the last height that held still, and how many growing ticks followed in a row. */
+export interface HeightState {
+    last: number;
+    steady: number;
+    run: number;
+}
+export interface HeightFitter {
+    /** Apply a pd-height measured in `frame`'s document. Returns true when the frame's height was written. */
+    accept(frame: HTMLIFrameElement, height: number): boolean;
+    /** Forget a frame's height history: growth detection starts over. */
+    reset(frame: HTMLIFrameElement): void;
+    /** If `event` is a pd-height message from one of `frames`, that frame and its height; otherwise null. */
+    fromMessage(event: MessageEvent<unknown>, frames: Iterable<HTMLIFrameElement>): {
+        frame: HTMLIFrameElement;
+        height: number;
+    } | null;
+    /** Whether `measured` continues a run of growth against the heights we imposed — the loop's signature. */
+    isCircularGrowth(previous: HeightState | undefined, measured: number): boolean;
+}
+export declare function createHeightFitter(adapter: HeightFitAdapter): HeightFitter;
+/** The circular-growth rule, for callers without a fitter. The same function every fitter uses. */
+export declare function isCircularGrowth(previous: HeightState | undefined, measured: number): boolean;

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

@@ -16,7 +16,33 @@ export interface RenderInput {
     variant?: string;
     /** Live-control overrides; highest precedence in the cascade. */
     data?: Record<string, unknown>;
+    /** Which image settings the variant URLs this render writes are keyed with: "site" for a storefront page and the
+     *  previews its host serves (`storefront.images` over `images`), else the project's (`images`). */
+    images?: "site";
 }
+/**
+ * What an image in the assets is, for `{{pd-image}}`: looked up by its URL (`/assets/…`), synchronously, from an
+ * index built before rendering. Sizes are as the image is displayed (EXIF orientation applied).
+ *  - `variants`: a raster image, served as WebP variants; `variantUrl(width, settings)` is a variant's URL.
+ *  - `single`: one file, as it is (an SVG, or a raster image pd dev shows as it is when it can't encode).
+ *  - `unavailable`: a raster image that can't be served as variants; `reason` says why (the build fails the page).
+ */
+export type ImageSource = {
+    kind: "variants";
+    width: number;
+    height: number;
+    variantUrl(width: number, settings?: "site"): string;
+} | {
+    kind: "single";
+    url: string;
+    width: number;
+    height: number;
+} | {
+    kind: "unavailable";
+    reason: string;
+};
+/** Looks an asset up by its URL; undefined when the assets have no image there. */
+export type ImageLookup = (src: string) => ImageSource | undefined;
 export interface RenderMeta {
     componentId: string;
     variant?: string;
@@ -117,6 +143,8 @@ export type Render = (input: RenderInput) => Promise<RenderOutput>;
 export interface RendererOptions {
     /** Root containing the atomic pattern folders (atoms/, molecules/, ...). */
     patternsDir: string;
+    /** The images in the assets, for `{{pd-image}}`. Without it, `{{pd-image}}` fails the render. */
+    images?: ImageLookup;
     /** Every patterns folder, project first, when pattern packages are in use. Takes precedence over
      *  `patternsDir` for discovery. */
     patternRoots?: PatternRoot[];
@@ -158,6 +186,13 @@ export interface RendererOptions {
      * the real M6 file-as-component walk, never the old collectComponents folder-per-component walk.
      */
     discoveryMap?: DiscoveryMap;
+    /**
+     * How a diagnostic names a source file (`location.file`): project-relative, or prefixed with its
+     * package's name (see `Diagnostic` in dev-protocol). The dev-server supplies it, since only it knows
+     * the project root and each package's folder. Without it, or when it returns an absolute path, the
+     * renderer names the file relative to its pattern root. A diagnostic never carries an absolute path.
+     */
+    displayPath?: (absPath: string) => string;
 }
 /** Factory: a configured renderer closes over its source root, keeping `render()` pure. */
 export type CreateRenderer = (options: RendererOptions) => Render;
@@ -292,3 +327,4 @@ export interface ShellBrandConfig {
 /** Ordered list of CSS custom-property names used as swatch slots. */
 export type SwatchSlots = string[];
 export * from "./dev-protocol.js";
+export * from "./iframe-fit.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pattern-dump",
-  "version": "0.1.0-alpha.3",
+  "version": "0.2.0-alpha.0",
   "description": "A workbench for HTML and CSS design systems: live component previews, docs, checks and static publishing.",
   "keywords": [
     "design-system",
@@ -16,7 +16,11 @@
     "static-site",
     "htwoo"
   ],
-  "author": "Stefan Bauer <stefan.bauer@n8d.at> (https://n8d.at)",
+  "author": {
+    "name": "Stefan Bauer (N8D e.U.)",
+    "email": "stefan.bauer@n8d.at",
+    "url": "https://n8d.at"
+  },
   "license": "MIT",
   "homepage": "https://github.com/n8design/pattern-dump#readme",
   "repository": {
@@ -51,10 +55,11 @@
     "templates",
     "README.md",
     "LICENSE",
+    "THIRD-PARTY-NOTICES.md",
     "CHANGELOG.md"
   ],
   "engines": {
-    "node": ">=20.10"
+    "node": ">=22.22"
   },
   "dependencies": {
     "@shikijs/transformers": "^4.1.0",
@@ -69,7 +74,9 @@
     "markdown-it": "^14.2.0",
     "node-html-parser": "^7.1.0",
     "postcss": "^8.5.15",
+    "postcss-selector-parser": "^7.1.1",
     "sass": "^1.100.0",
+    "sharp": "0.35.5",
     "shiki": "^4.1.0",
     "source-map": "^0.6.1",
     "ws": "^8.21.0"

package/templates/base/README.md

@@ -8,6 +8,7 @@ npm run audit   # static defects across every component
 npm run typecheck      # type-check the behaviour scripts
 npm run build:scripts  # compile them to lib/scripts (JavaScript + type declarations)
 ```
+__PD_STOREFRONT_README__
 
 ## Layout
 

package/templates/base/_gitignore

@@ -1,3 +1,4 @@
 node_modules
 dist
 lib
+__PD_STOREFRONT_GITIGNORE__

package/templates/base/pattern-dump.config.ts

@@ -30,6 +30,7 @@ export default defineConfig({
   // Each package describes its patterns, styles and themes in its package.json ("patternDump").
   // packages: ["@n8d/htwoo-patterns"],
 
+__PD_STOREFRONT__
   shell: {
     brand: { title: __PD_BRAND_JSON__ },
   },

package/templates/base/src/styles/base/document.scss

@@ -2,6 +2,10 @@
 
 // The document defaults every preview sits on — the base layer named by `documentBase` in the config.
 // Fallbacks keep a preview readable before a theme is chosen.
+//
+// `:where(body)` has no specificity, so these are defaults only: a pattern package's own document
+// rules (hTWOo's body background and text colour, which follow its themes) override them even
+// though the project's base rules come later in the cascade.
 
 *,
 *::before,
@@ -9,7 +13,7 @@
   box-sizing: border-box;
 }
 
-body {
+:where(body) {
   margin: 0;
   font-family: tokens.$font-family;
   line-height: 1.5;

package/templates/storefront/.github/workflows/pages.yml

@@ -0,0 +1,53 @@
+# Builds the website and the workbench, and publishes both to GitHub Pages:
+# the website at the root of your domain, the workbench under /workbench/.
+# Before the first run: Settings → Pages → Source: "GitHub Actions", and your custom domain: see "Publish it" in the README.
+name: Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# One deploy at a time; a deploy that has started is never cancelled halfway.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          # The full history: a layout that shows page dates needs it, and pd build refuses a shallow clone then.
+          fetch-depth: 0
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24
+          cache: npm
+      - run: npm ci
+      - run: npm run build
+      # pd build writes the website (site/) and the workbench (dist/) side by side; Pages takes one folder.
+      - run: |
+          mkdir _site
+          cp -R site/. _site/
+          cp -R dist _site/workbench
+      - uses: actions/configure-pages@v6
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: _site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-24.04
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v5

package/templates/storefront/assets/icon.svg

@@ -0,0 +1,2 @@
+<!-- Drawn by Stefan Bauer, part of this repository, MIT. -->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><rect width="32" height="32" rx="6" fill="#0b5cad"/><path d="M9 9h14v4H9zm0 6h14v4H9zm0 6h9v4H9z" fill="#fff"/></svg>

package/templates/storefront/pages/about.md

@@ -0,0 +1,15 @@
+---
+title: About
+description: What is in this starter, and where it lives.
+order: 1
+---
+
+The pages are in `pages/`. What they look like is the skin, written as ordinary components so the
+workbench shows each part of it:
+
+- `src/patterns/layouts/page`: the layout every page renders with
+- `src/patterns/partials/base`: the frame around it, with the header, navigation and footer
+- `src/patterns/partials/head`: what the skin adds to every page's `<head>`
+- `src/patterns/components/note`: a component the pages show
+
+The site's name and footer are `storefront.site` in `pattern-dump.config.ts`.

package/templates/storefront/pages/index.md

@@ -0,0 +1,24 @@
+---
+title: Home
+description: A website written in markdown, next to the design system it shows.
+---
+
+This page is `pages/index.md`. Every markdown file in `pages/` is a page, at the address its path
+names: `pages/about.md` is [/about/](/about/).
+
+## A live example
+
+A `pattern` fence shows a component from the workbench, in a frame of its own, so its own styles
+render it and nothing on this page can restyle it:
+
+```pattern components/note
+```
+
+## A component with your values
+
+A `pd-` tag places a component with the values you give it. They are checked against the component's
+schema, `src/patterns/components/note/note.schema.json`, before the page is shown:
+
+<pd-components-note tone="tip" heading="Try breaking it">
+Change `tone="tip"` to `tone="tips"` and save. The page shows what is wrong, and where.
+</pd-components-note>

package/templates/storefront/src/patterns/components/note/note.hbs

@@ -0,0 +1,4 @@
+<aside class="note{{#if tone}} note-{{tone}}{{/if}}" role="note">
+  <p class="note-heading">{{heading}}</p>
+  <div class="note-text">{{{text}}}</div>
+</aside>

package/templates/storefront/src/patterns/components/note/note.json

@@ -0,0 +1,4 @@
+{
+  "heading": "A note",
+  "text": "<p>Something worth knowing, next to what it is about.</p>"
+}