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

package/CHANGELOG.md

@@ -1,8 +1,91 @@
 # Changelog
 
+## 0.2.0-alpha.0
+
+The storefront: a website written as markdown pages, dressed by a skin made of ordinary components, served by
+`pd dev` on a host of its own and built by `pd build` next to the workbench. With it come responsive images, link
+and image checks, and live examples of your components on the site's pages.
+
+Pattern Dump now needs Node.js 22.22 or later (it was 20.10).
+
+### Workbench
+
+- Pattern packages linked into a project (a `file:` dependency or a workspace) are watched like the project's own
+  files, and each is read from its real folder. Global data, assets and helper modules reload while `pd dev` runs.
+- A pattern package's TypeScript helpers are refused with a message naming them, and diagnostics name files by
+  project or package path, never by an absolute path.
+- Live reload is dependable: changes are handled one at a time, in the order they happen; a page or preview that
+  missed a change fetches it again and never shows an older one; a save the file watcher drops is still handled; a
+  folder added while `pd dev` runs (as `git checkout` or `git pull` does) is seen with every file in it.
+- A component added while `pd dev` runs gets its own stylesheet even when the stylesheet is saved before the
+  template.
+- A variant reached by its own id (`/preview/atoms/toggle-demo~alt`) is the same document as `?variant=alt`, with
+  its base's behaviour scripts, layout and CSS.
+- An overview tile picks up a stylesheet that was still empty when it rendered.
+- Behaviour scripts are stamped with their content hash, so a browser fetches a script again exactly when it
+  changed.
+- Every base-layer file whose rules no component owns and no `documentBase` entry lists is named in
+  `BASE-LAYER.generated.md`, with its rule count.
+
+### Storefront
+
+- Pages: every markdown file in `storefront.pagesDir` is a page, rendered with a layout from your patterns. Its
+  frontmatter is checked against the layout's schema, `storefront.site` against `partials/base`'s, and every
+  problem names its file and line. `pd dev` serves the site at `http://live.localhost:4000/`, `pd build` writes it
+  to `storefront.outDir`.
+- Live examples: a `pattern` fence shows a component's own preview in a frame, with links to its variants. A
+  component can declare the height its example starts at (`x-pd-example-height`), and `pd dev` warns when that
+  height is too tall.
+- Placing components with values: `<pd-…>` tags in a page's markdown, checked against the component's schema at
+  every level (`x-pd-component`, `x-pd-content`, `text/markdown` properties), with the file, line and column of any
+  problem.
+- What a page knows about itself, for layouts that ask for it: its headings (with GitHub's anchors), section,
+  breadcrumbs, previous and next pages, dates from git, and declared navigations.
+- Search engines and link previews: canonical URLs, Open Graph, the site's language, JSON-LD, `sitemap.xml`,
+  `robots.txt`, a 404 page, `redirectFrom` for old routes, `index: false`, and a link-preview image per page or site.
+- A skin can add to every page's `<head>` through a `partials/head` component, and can be a pattern package.
+- `pd init --storefront` starts a project with a website: pages, a plain skin, the workbench under `/workbench/`
+  on the same host, and a GitHub Pages workflow.
+- Every file a page references (stylesheets, scripts, fonts, images) carries the content hash of the file as
+  served, so a visitor's browser fetches it again exactly when it changed.
+
+### Images
+
+- Every raster image is served as WebP variants of the widths it is shown at, encoded with sharp on first use and
+  cached in `node_modules/.cache/pattern-dump/images/`. `images` (quality, effort) sets the encoding, and
+  `storefront.images` overrides it for the site.
+- Image slots: a component declares where an image goes and how wide it is shown (`x-pd-image`), and its template
+  writes it with `{{pd-image field alt=…}}`. Alt text is required; `alt=""` marks a decorative image.
+- Images in a page's markdown get their variants in the slot the page's layout declares (`x-pd-prose-images`),
+  with `sizes="auto"`, and the first ones can load at once (`eager`).
+- Every `<img>` carries its width and height, so the page doesn't shift as images load. Photos are turned upright
+  by their EXIF orientation.
+
+### Checks
+
+- `pd build` checks every link on every page of the site before it writes anything: pages, files, `#` anchors (a
+  heading's too), the site's own address and links into the workbench. A broken link stops the build; links to other
+  sites are listed in the build's notes. `pd dev` warns about a page's links to pages that don't exist.
+- `pd build` refuses a page with an `<img>` that has no width and height, or a raster image served without its WebP
+  variants, and names the fix; `pd dev` shows the same as warnings.
+- A schema field named like a registered helper is an error, and so is an unknown `x-pd-` key in a schema.
+- The shape check tells a list from an object (an array property was reported as a mismatch).
+
+### Fixes
+
+- `pd dev` answers only requests addressed to its own host names, accepts live-reload connections only from its own
+  pages, binds its live-reload socket to 127.0.0.1 like its HTTP server, and serves files only from inside each
+  route's folder.
+- The starter's body defaults no longer override a pattern package's document styles (hTWOo's dark themes showed
+  dark text on a white page).
+- Two config loads in the same millisecond no longer share a temporary file.
+- The audit reuses a cached result only when it was made by the same version of the check.
+- The live-reload socket reports the port it is actually bound to.
+- A code example on a page that quotes `<img src="/assets/…">` is shown as written, not with a cache stamp added.
+
 ## 0.1.0-alpha.4
 
-Fixes found while moving a third PatternLab styleguide (CTS) to Pattern Dump with hTWOo consumed only as
+Fixes found while moving a third PatternLab styleguide to Pattern Dump with hTWOo consumed only as
 pattern packages: its templates, data, scripts and CSS all come from `@n8d/htwoo-patterns` and
 `@n8d/htwoo-core`, and the project compiles only its own SCSS.
 

package/LICENSE

@@ -1,8 +1,21 @@
 MIT License
 
-Copyright (c) 2026 n8d and contributors
+Copyright (c) 2026 Stefan Bauer (N8D e.U.)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, subject to the conditions of the MIT License.
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -4,7 +4,7 @@ A workbench for HTML and CSS design systems, and a successor to PatternLab. Writ
 Handlebars templates with SCSS, data and Markdown docs; Pattern Dump shows them live, checks them, maps
 how they relate, and publishes the result as a static site.
 
-> **Alpha (0.1.0-alpha.4).** Published under the `alpha` tag. Options and file conventions can still change
+> **Alpha (0.2.0-alpha.0).** Published under the `alpha` tag. Options and file conventions can still change
 > between releases.
 
 ## Requirements
@@ -102,4 +102,4 @@ export default defineConfig({
 
 ## License
 
-[MIT](https://github.com/n8design/pattern-dump/blob/main/LICENSE) © 2026 [n8d](https://n8d.at) and contributors
+[MIT](https://github.com/n8design/pattern-dump/blob/main/LICENSE) © 2026 Stefan Bauer (N8D e.U.)

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,130 @@
+# Third-party notices
+
+Pattern Dump is MIT-licensed (see `LICENSE`). It includes code from the projects below, under their own
+licences.
+
+## github-slugger 2.0.0
+
+- **Source:** https://github.com/Flet/github-slugger
+- **Used in:** `packages/dev-server/src/storefront/slug.ts` (the slugger and its generated regex, ported
+  unchanged) and `packages/dev-server/test/fixtures/github-slugger-2.0.0.json` (its test fixtures, copied
+  unchanged).
+- **Licence:** ISC
+
+```
+Copyright (c) 2015, Dan Flettre <fletd01@yahoo.com>
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is
+hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE
+INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
+USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
+OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+```
+
+## Fonts in the repository
+
+- **Mr Bedfort**, Alejandro Paul (Sudtipos), version 1.000, with Reserved Font Name "Mr Bedfort".
+- **Used in:** `test-bench/assets/fonts/pd-test.woff2`, unmodified; its licence text is
+  `test-bench/licenses/pd-test-OFL.txt`, and `test-bench/README.md` says what the file is. Not part of the npm package.
+- **Licence:** SIL Open Font License 1.1.
+
+The experimental skin's fonts (Montserrat, Source Serif 4, IBM Plex Mono) are listed, with their sources and
+licences, in `skins/experimental/assets/skin-experimental/fonts/README.md`.
+
+## Images in the repository
+
+These files are in the git repository, in test fixtures and benches. They are not part of the npm package.
+
+### Photographs from Unsplash
+
+- **Space Shuttle Challenger**, NASA: https://unsplash.com/photos/dCgbRAQmTQA
+- **Used in:** `packages/build/test/fixtures/images/` (`photo.jpg`, `portrait-exif6.jpg` and `alpha.png`, cut from
+  it; how, in the README beside them).
+- **Licence:** [Unsplash License](https://unsplash.com/license). This is not the MIT licence and not an open-source
+  licence: it covers these images only, and the repository's MIT licence does not cover them.
+
+- **Cable cars**, Cody Hiscox: https://unsplash.com/photos/kzb0Mo0YQDw
+- **Used in:** `storefront-bench/src/assets/images/cable-cars.jpg` (cropped and scaled; how, in the README beside it).
+- **Licence:** [Unsplash License](https://unsplash.com/license), as above: not the MIT licence.
+
+## Phosphor Icons
+
+- **Phosphor Icons**: https://github.com/phosphor-icons/core
+- **Used in:** `apps/dev-ui/src/icons/index.ts`: twenty icons of the workbench (regular and fill weights, the
+  SVG paths unchanged), which are in the npm package as part of `dist/dev-ui/main.js`. The registry's two other
+  icons (the disclosure chevron and the open-in-new-window mark) are not Phosphor's.
+- **Also used in:** `test-bench/assets/images/symbols.svg`: the `star` and `check` icons (regular weight, paths
+  unchanged), for the sprite and `<use>` specs. Not part of the npm package.
+- **Licence:** MIT
+
+```
+MIT License
+
+Copyright (c) 2023 Phosphor Icons
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and
+to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of
+the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
+THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
+CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.
+```
+
+## Monokai Light
+
+- **Monokai Light**, Velichko Konstantin: https://github.com/zoxon/vscode-theme-monokai-light
+- **Used in:** `packages/renderer/src/themes/monokai-light.ts`: the syntax theme `pd-monokai-light` takes its
+  token colours from the theme's JSON, with two deliberate changes (listed in the file). It is part of the npm
+  package (`dist/pd.js`).
+- **Licence:** MIT
+
+```
+MIT License
+
+Copyright (c) 2017 Velichko Konstantin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and
+to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of
+the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
+THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
+CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.
+```
+
+## Colour vision deficiency matrices
+
+- **Machado, G. M., Oliveira, M. M., Fernandes, L. (2009).** "A Physiologically-based Model for Simulation of Color
+  Vision Deficiency". *IEEE Transactions on Visualization and Computer Graphics* 15(6), 1291-1298.
+  https://doi.org/10.1109/TVCG.2009.113
+- **Used in:** `apps/dev-ui/src/core/cvd-math.ts`: the matrices of the workbench's colour-vision simulation (protanopia,
+  deuteranopia, tritanopia, eleven severities each). They are numbers published in that paper: data, not code. The
+  achromatopsia table is not from the paper.
+- **Licence:** none applies to published data; the paper is cited as its source.
+
+## Dependencies with other licences
+
+The npm package declares its dependencies, and npm installs them with their own licence files; none is bundled into
+`dist/` or modified. Almost all are MIT, ISC, BSD or Apache-2.0. Two have terms worth naming:
+
+- **axe-core** (Deque Systems), **MPL-2.0**: https://github.com/dequelabs/axe-core. Used by the accessibility checks
+  (`packages/a11y`), as installed.
+- **libvips** binaries (`@img/sharp-libvips-*`), **LGPL-3.0-or-later**: https://github.com/lovell/sharp-libvips. Optional
+  dependencies of **sharp** (Apache-2.0), which encodes the storefront's images; installed as prebuilt binaries, not
+  linked into or copied into this package. An install with `--omit=optional` leaves them out.

package/dist/chunks/{chunk-NXGPZL5L.js → chunk-ESMZAOP2.js}

@@ -1,4 +1,6 @@
 // packages/config/src/validate.ts
+import { relative, resolve, sep } from "node:path";
+var IMAGES = { keys: { quality: "quality", effort: "effort" } };
 var SHAPE = {
   $schema: "string",
   sourceDir: "string",
@@ -39,9 +41,26 @@ var SHAPE = {
   },
   packages: "packages",
   exclude: "strings",
-  build: { keys: { outDir: "string", basePath: "string", audit: "boolean" } }
+  build: { keys: { outDir: "string", basePath: "string", audit: "boolean" } },
+  images: IMAGES,
+  storefront: {
+    keys: {
+      pagesDir: "string",
+      outDir: "string",
+      host: "host",
+      workbenchUrl: "workbench-url",
+      site: "plain-object",
+      url: "site-url",
+      lang: "lang",
+      index: "boolean",
+      image: "asset-path",
+      images: IMAGES
+    },
+    required: ["pagesDir", "outDir"]
+  }
 };
 var REQUIRED = ["sourceDir", "patternsDir", "outDir", "styles"];
+var WORKBENCH_PATH = /^\/(?:(?!\.{1,2}(?:\/|$))[a-z0-9._~-]+\/?)+$/i;
 var isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 var isStrings = (v) => Array.isArray(v) && v.every((x) => typeof x === "string");
 function distance(a, b) {
@@ -116,6 +135,63 @@ function checkValue(value, rule, at, problems) {
     if (!ok) fail(`a path or { light, dark }`);
     return;
   }
+  if (rule === "workbench-url") {
+    let ok = false;
+    if (typeof value === "string" && WORKBENCH_PATH.test(value)) ok = true;
+    else if (typeof value === "string") {
+      try {
+        const url = new URL(value);
+        ok = /^https?:$/.test(url.protocol) && url.search === "" && url.hash === "" && !/[?#]/.test(value);
+      } catch {
+        ok = false;
+      }
+    }
+    if (!ok) fail(`an absolute http(s) URL for a workbench on its own host, such as "https://workbench.example.com/", or a path for one on the storefront's host, such as "/workbench/"`);
+    return;
+  }
+  if (rule === "site-url") {
+    let ok = false;
+    if (typeof value === "string") {
+      try {
+        const url = new URL(value);
+        ok = /^https?:$/.test(url.protocol) && url.pathname === "/" && url.search === "" && url.hash === "" && !/[?#]/.test(value);
+      } catch {
+        ok = false;
+      }
+    }
+    if (!ok) fail(`the site's absolute http(s) address, with no path, query or fragment, such as "https://example.com/"`);
+    return;
+  }
+  if (rule === "lang") {
+    if (typeof value !== "string" || !/^[a-z]{2,3}(?:-[a-z]{4})?(?:-(?:[a-z]{2}|\d{3}))?(?:-(?:[a-z\d]{5,8}|\d[a-z\d]{3}))*$/i.test(value)) {
+      fail(`a language tag, such as "en", "de-AT" or "zh-Hant-TW"`);
+    }
+    return;
+  }
+  if (rule === "asset-path") {
+    if (typeof value !== "string" || !/^\/assets\/[^?#]+[^/?#]$/.test(value)) {
+      fail(`a path to a file in the assets, such as "/assets/images/share.png"`);
+    }
+    return;
+  }
+  if (rule === "quality") {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 1 || value > 100) fail("a whole number from 1 to 100 (WebP quality)");
+    return;
+  }
+  if (rule === "effort") {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0 || value > 6) fail("a whole number from 0 to 6 (WebP effort: 0 fastest, 6 smallest)");
+    return;
+  }
+  if (rule === "plain-object") {
+    if (!isObject(value)) fail(`an object of the site's values, such as { title: "My site" }`);
+    return;
+  }
+  if (rule === "host") {
+    if (typeof value !== "string" || !/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*$/i.test(value)) {
+      fail(`a host name with no scheme, port or path, such as "live.localhost"`);
+    }
+    return;
+  }
   if ("values" in rule) {
     if (typeof value === "string" && rule.unsupported?.includes(value)) {
       problems.push(`"${at}": "${value}" is not supported yet \u2014 use ${rule.values.map((v) => `"${v}"`).join(" or ")}, or leave it out`);
@@ -133,19 +209,64 @@ function checkValue(value, rule, at, problems) {
 var ConfigError = class extends Error {
   name = "ConfigError";
 };
+function checkRelations(raw, problems) {
+  const sf = raw.storefront;
+  if (!isObject(sf)) return;
+  const folders = [
+    ["storefront.pagesDir", sf.pagesDir],
+    ["patternsDir", raw.patternsDir],
+    ["storefront.outDir", sf.outDir]
+  ];
+  const root = resolve(sep, "pd-root");
+  const inside = (child, parent) => {
+    const rel = relative(parent, child);
+    return rel !== "" && !rel.startsWith("..") && !rel.startsWith(sep) && !/^[a-zA-Z]:/.test(rel);
+  };
+  for (let i = 0; i < folders.length; i++) {
+    for (let j = i + 1; j < folders.length; j++) {
+      const [a, va] = folders[i], [b, vb] = folders[j];
+      if (typeof va !== "string" || typeof vb !== "string") continue;
+      const pa = resolve(root, va), pb = resolve(root, vb);
+      const label = (name, value) => `"${name}" ("${value}")`;
+      if (pa === pb) problems.push(`${label(a, va)} and ${label(b, vb)} are the same folder \u2014 each needs a folder of its own`);
+      else if (inside(pa, pb)) problems.push(`${label(a, va)} is inside ${label(b, vb)} \u2014 each needs a folder of its own, outside the other`);
+      else if (inside(pb, pa)) problems.push(`${label(b, vb)} is inside ${label(a, va)} \u2014 each needs a folder of its own, outside the other`);
+    }
+  }
+}
 function configProblems(raw) {
   if (!isObject(raw)) return ["the config must be an object (a .ts config must `export default defineConfig({ \u2026 })`)"];
   const problems = [];
   checkObject(raw, SHAPE, REQUIRED, "", problems);
+  if (problems.length === 0) checkRelations(raw, problems);
   return problems;
 }
+var withOneTrailingSlash = (url) => `${url.replace(/\/+$/, "")}/`;
 function validateConfig(raw, source) {
   const problems = configProblems(raw);
   if (problems.length > 0) {
     throw new ConfigError(`${source}: invalid config
 ${problems.map((p) => `  - ${p}`).join("\n")}`);
   }
-  return raw;
+  const config = raw;
+  const sf = config.storefront;
+  if (!sf) return config;
+  const workbenchUrl = sf.workbenchUrl !== void 0 ? withOneTrailingSlash(sf.workbenchUrl) : void 0;
+  const url = sf.url !== void 0 ? `${new URL(sf.url).origin}/` : void 0;
+  if (workbenchUrl === sf.workbenchUrl && url === sf.url) return config;
+  return { ...config, storefront: {
+    ...sf,
+    ...workbenchUrl !== void 0 ? { workbenchUrl } : {},
+    ...url !== void 0 ? { url } : {}
+  } };
+}
+function sameHostWorkbenchPath(storefront) {
+  const w = storefront?.workbenchUrl;
+  if (w === void 0) return void 0;
+  if (w.startsWith("/")) return w;
+  if (storefront?.url === void 0) return void 0;
+  const u = new URL(w);
+  return `${u.origin}/` === storefront.url ? u.pathname : void 0;
 }
 
 // packages/config/src/index.ts
@@ -154,7 +275,9 @@ function defineConfig(config) {
 }
 
 export {
+  suggest,
   ConfigError,
   validateConfig,
+  sameHostWorkbenchPath,
   defineConfig
 };