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

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.1.0-alpha.3
+
+Fixes found while moving a second PatternLab styleguide (n8d) to Pattern Dump.
+
+### Fixed
+
+- A numbered `templates` or `pages` folder now gets the `full` preview layout its category promises.
+  The category was matched with its ordering prefix still attached, so a PatternLab tree
+  (`04-templates`, `05-pages`) could never hit the documented default — only a per-folder
+  `preview: full` could. Folder *labels* still keep the number: `2-col` is a name and `04-templates`
+  a prefix, and nothing in the string tells them apart, so a numbered folder sets `title:` for a
+  clean label.
+- A `requireScript` or `globalScripts` id with no matching `<scriptsDir>/<id>.ts` is reported instead
+  of failing inside the preview. `pd dev` names every unresolvable id at startup — with the component
+  for a `requireScript` — and the script's URL answers 404 saying which file it expected and where,
+  rather than embedding a raw `ENOENT`. Scripts are TypeScript, so a `.js` file of the same name does
+  not satisfy an id; that is the common case this hid.
+
 ## 0.1.0-alpha.2
 
 Fixes found while moving a PatternLab styleguide to Pattern Dump, and the changes they needed.

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.2).** Published under the `alpha` tag. Options and file conventions can still change
+> **Alpha (0.1.0-alpha.3).** Published under the `alpha` tag. Options and file conventions can still change
 > between releases.
 
 ## Requirements

package/dist/pd.js

@@ -30,10 +30,12 @@ function collapseComponentId(relNoExt) {
   const parent = dirname(relNoExt);
   return stem === basename(parent) ? parent : relNoExt;
 }
+function stripOrderPrefixes(path) {
+  return path.split("/").map((seg) => seg.replace(/^\d+[-_]/, "")).join("/");
+}
 function deriveHandle(id) {
-  const parts = id.split("/");
-  const unnumbered = (seg) => seg.replace(/^\d+[-_]/, "");
-  return `${unnumbered(parts[0])}-${unnumbered(parts[parts.length - 1])}`;
+  const parts = stripOrderPrefixes(id).split("/");
+  return `${parts[0]}-${parts[parts.length - 1]}`;
 }
 async function buildDiscoveryMap(roots) {
   const rootList = typeof roots === "string" ? [{ dir: roots }] : roots;
@@ -1453,7 +1455,6 @@ function joinCssChunks(chunks) {
   }
   return [...charset.slice(0, 1), ...imports, ...rest].join("\n");
 }
-var stripOrderPrefixes = (path) => path.split("/").map((seg) => seg.replace(/^\d+[-_]/, "")).join("/");
 var strippedIdCache = /* @__PURE__ */ new WeakMap();
 function strippedIds(componentIds) {
   let map = strippedIdCache.get(componentIds);
@@ -2358,6 +2359,99 @@ async function buildStaticSite(config, root, opts) {
   return report;
 }
 
+// packages/dev-server/src/requires.ts
+import { readFile as readFile8 } from "node:fs/promises";
+import { existsSync as existsSync3 } from "node:fs";
+import { basename as basename3, join as join12, relative as relative5 } from "node:path";
+function normalizeScriptId(raw) {
+  let s = raw.trim().replace(/^\[(.+)\]$/, "$1").trim();
+  s = basename3(s);
+  s = s.replace(/\.(ts|js)$/, "");
+  return s;
+}
+function parseFrontmatterList(md, key) {
+  const values = [];
+  const re = new RegExp(`^${key}:\\s*(.+)$`, "mg");
+  for (const [, val] of md.matchAll(re)) {
+    values.push(val.trim());
+  }
+  return values;
+}
+async function aggregateRequires(componentId, patternsDir, flatNameToPath, discoveryMap, visited = /* @__PURE__ */ new Set()) {
+  if (visited.has(componentId)) return { scripts: [], assets: [] };
+  visited.add(componentId);
+  const entry = discoveryMap.get(componentId);
+  let ownScripts = [];
+  let ownAssets = [];
+  if (entry?.mdPath) {
+    try {
+      const md = await readFile8(entry.mdPath, "utf-8");
+      ownScripts = parseFrontmatterList(md, "requireScript").map(normalizeScriptId);
+      ownAssets = parseFrontmatterList(md, "requireAssets").map((v) => v.trim().replace(/^\[(.+)\]$/, "$1").trim());
+    } catch {
+    }
+  }
+  const allScripts = [...ownScripts];
+  const allAssets = [...ownAssets];
+  const hbsPath = entry?.hbsPath ?? "";
+  let hbs = "";
+  try {
+    hbs = hbsPath ? await readFile8(hbsPath, "utf-8") : "";
+  } catch {
+  }
+  for (const flatName of parsePartialsFromHbs(hbs)) {
+    const childPath = flatNameToPath.get(flatName);
+    if (childPath) {
+      const child = await aggregateRequires(childPath, patternsDir, flatNameToPath, discoveryMap, visited);
+      allScripts.push(...child.scripts);
+      allAssets.push(...child.assets);
+    }
+  }
+  return {
+    scripts: [...new Set(allScripts)],
+    assets: [...new Set(allAssets)]
+  };
+}
+async function loadSvgAssets(ids, assetsDir) {
+  const contents = [];
+  for (const id of ids) {
+    for (const candidate of [`${id}.svg`, `images/${id}.svg`]) {
+      try {
+        const raw = await readFile8(join12(assetsDir, candidate), "utf-8");
+        contents.push(hideSvg(raw));
+        break;
+      } catch {
+      }
+    }
+  }
+  return contents;
+}
+function hideSvg(svg) {
+  return svg.replace(/<svg(\s|>)/, '<svg$1style="display:none;position:absolute" aria-hidden="true" ');
+}
+async function reportUnresolvableScripts(discoveryMap, scriptsDirs, globalScripts, cwd) {
+  const resolves = (id) => scriptsDirs.some((d) => existsSync3(join12(d, `${id}.ts`)));
+  const where = scriptsDirs.length ? scriptsDirs.map((d) => relative5(cwd, d) || d).join(" or ") : "no scriptsDir configured";
+  for (const id of globalScripts) {
+    if (id.includes("://") || resolves(normalizeScriptId(id))) continue;
+    console.warn(`[dev-server] globalScripts "${id}": no ${normalizeScriptId(id)}.ts in ${where}`);
+  }
+  for (const [componentId, entry] of discoveryMap) {
+    if (!entry.mdPath) continue;
+    let md;
+    try {
+      md = await readFile8(entry.mdPath, "utf-8");
+    } catch {
+      continue;
+    }
+    for (const raw of parseFrontmatterList(md, "requireScript")) {
+      const id = normalizeScriptId(raw);
+      if (resolves(id)) continue;
+      console.warn(`[dev-server] requireScript "${raw}" on ${componentId}: no ${id}.ts in ${where}`);
+    }
+  }
+}
+
 // packages/dev-server/src/server-state.ts
 function createServerState() {
   return {
@@ -2399,25 +2493,25 @@ function applyStyleData(state, data) {
 }
 
 // packages/dev-server/src/routes.ts
-import { basename as basename4, extname as extname2, join as join18 } from "node:path";
+import { basename as basename4, extname as extname2, join as join18, relative as relative6 } from "node:path";
 import { readFile as readFile15, stat as stat4 } from "node:fs/promises";
-import { existsSync as existsSync4 } from "node:fs";
+import { existsSync as existsSync5 } from "node:fs";
 
 // packages/dev-server/src/component-tree.ts
+import { readFile as readFile11 } from "node:fs/promises";
+import { join as join15 } from "node:path";
+
+// packages/dev-server/src/layout-mode.ts
 import { readFile as readFile10 } from "node:fs/promises";
 import { join as join14 } from "node:path";
 
-// packages/dev-server/src/layout-mode.ts
+// packages/dev-server/src/pattern-dirs.ts
 import { readFile as readFile9 } from "node:fs/promises";
 import { join as join13 } from "node:path";
-
-// packages/dev-server/src/pattern-dirs.ts
-import { readFile as readFile8 } from "node:fs/promises";
-import { join as join12 } from "node:path";
 async function readFolderFile(dirs, rel) {
   for (const dir of typeof dirs === "string" ? [dirs] : dirs) {
     try {
-      return await readFile8(join12(dir, rel), "utf-8");
+      return await readFile9(join13(dir, rel), "utf-8");
     } catch {
     }
   }
@@ -2429,8 +2523,8 @@ var FULL_CATEGORIES = /* @__PURE__ */ new Set(["pages", "templates"]);
 async function resolveLayoutMode(componentId, patternsDir, discoveryMap) {
   const parts = componentId.split("/");
   const category = parts[0];
-  let layout = FULL_CATEGORIES.has(category) ? "full" : "centered";
-  const categoryIndex = await readFolderFile(patternsDir, join13(category, "index.md"));
+  let layout = FULL_CATEGORIES.has(stripOrderPrefixes(category)) ? "full" : "centered";
+  const categoryIndex = await readFolderFile(patternsDir, join14(category, "index.md"));
   if (categoryIndex !== null) {
     const m = categoryIndex.match(/^preview:\s*(centered|full)$/m);
     if (m) layout = m[1];
@@ -2438,7 +2532,7 @@ async function resolveLayoutMode(componentId, patternsDir, discoveryMap) {
   const mdPath = discoveryMap?.get(componentId)?.mdPath;
   if (mdPath) {
     try {
-      const md = await readFile9(mdPath, "utf-8");
+      const md = await readFile10(mdPath, "utf-8");
       const m = md.match(/^preview:\s*(centered|full)$/m);
       if (m) layout = m[1];
     } catch {
@@ -2531,7 +2625,7 @@ function folderTitle(segment) {
   const text = words.join(" ");
   return text.charAt(0).toUpperCase() + text.slice(1);
 }
-var readText = (path) => readFile10(path, "utf-8").catch(() => null);
+var readText = (path) => readFile11(path, "utf-8").catch(() => null);
 function orderOf(md) {
   return md === null ? void 0 : parseOrder(readFrontmatter(md)["order"]);
 }
@@ -2582,7 +2676,7 @@ async function buildTreeNodeFromMap(nodePath, idsUnderPath, patternsDir, overvie
       if (o && "weight" in o) weight = o.weight;
     }
   }
-  const indexMd = await readFolderFile(patternsDir, join14(nodePath, "index.md"));
+  const indexMd = await readFolderFile(patternsDir, join15(nodePath, "index.md"));
   const folderOrder = orderOf(indexMd);
   const built = [];
   for (const childPath of directChildPaths(nodePath, idsUnderPath)) {
@@ -2630,7 +2724,7 @@ async function buildTreeNodeFromMap(nodePath, idsUnderPath, patternsDir, overvie
 import { readFile as readFile14 } from "node:fs/promises";
 
 // packages/dev-server/src/markdown.ts
-import { readFile as readFile11 } from "node:fs/promises";
+import { readFile as readFile12 } from "node:fs/promises";
 import MarkdownIt from "markdown-it";
 var _md = new MarkdownIt({ html: false, linkify: false });
 _md.validateLink = (url) => {
@@ -2719,7 +2813,7 @@ async function _resolveFence(info, content, idx, renderComponent, out, discovery
       return;
     }
     try {
-      const src = await readFile11(entry.hbsPath, "utf-8");
+      const src = await readFile12(entry.hbsPath, "utf-8");
       out.set(idx, wrapWithCopyButton(highlight(src, "handlebars"), src));
     } catch (e) {
       console.warn(`[dev-server] src-template read error [${spec}]:`, e);
@@ -2744,8 +2838,8 @@ async function _resolveFence(info, content, idx, renderComponent, out, discovery
         }
         const baseJsonPath = discoveryMap.get(compId)?.jsonPath;
         const variantJsonPath = variantEntry.jsonPath;
-        const baseData = baseJsonPath ? JSON.parse(await readFile11(baseJsonPath, "utf-8")) : {};
-        const variantData = variantJsonPath ? JSON.parse(await readFile11(variantJsonPath, "utf-8")) : {};
+        const baseData = baseJsonPath ? JSON.parse(await readFile12(baseJsonPath, "utf-8")) : {};
+        const variantData = variantJsonPath ? JSON.parse(await readFile12(variantJsonPath, "utf-8")) : {};
         const merged = deepMerge(structuredClone(baseData), variantData);
         const src = JSON.stringify(merged, null, 2);
         out.set(idx, wrapWithCopyButton(highlight(src, "json"), src));
@@ -2755,7 +2849,7 @@ async function _resolveFence(info, content, idx, renderComponent, out, discovery
           out.set(idx, `<p class="doc-error">[src-data: ${escapeHtml(spec)} \u2014 no data file]</p>`);
           return;
         }
-        const src = await readFile11(jsonPath, "utf-8");
+        const src = await readFile12(jsonPath, "utf-8");
         out.set(idx, wrapWithCopyButton(highlight(src, "json"), src));
       }
     } catch (e) {
@@ -2785,7 +2879,7 @@ async function _resolveFence(info, content, idx, renderComponent, out, discovery
 }
 
 // packages/dev-server/src/css-closure.ts
-import { readFile as readFile12 } from "node:fs/promises";
+import { readFile as readFile13 } from "node:fs/promises";
 import { dirname as dirname5, resolve as resolve7 } from "node:path";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 import postcss4 from "postcss";
@@ -2825,7 +2919,7 @@ async function computeCssClosure(componentId, compReg, patternsDir, classOwnerIn
     const hbsPath = discoveryMap.get(id)?.hbsPath ?? "";
     let hbs = "";
     try {
-      hbs = hbsPath ? await readFile12(hbsPath, "utf-8") : "";
+      hbs = hbsPath ? await readFile13(hbsPath, "utf-8") : "";
     } catch {
     }
     const { styleUses } = deriveClassBorrowingFields(hbs, id, classOwnerIndex);
@@ -2881,76 +2975,6 @@ function linkableClosure(closureIds, perComponentCss) {
   return closureIds.filter((id) => !!perComponentCss.get(id));
 }
 
-// packages/dev-server/src/requires.ts
-import { readFile as readFile13 } from "node:fs/promises";
-import { join as join15, basename as basename3 } from "node:path";
-function normalizeScriptId(raw) {
-  let s = raw.trim().replace(/^\[(.+)\]$/, "$1").trim();
-  s = basename3(s);
-  s = s.replace(/\.(ts|js)$/, "");
-  return s;
-}
-function parseFrontmatterList(md, key) {
-  const values = [];
-  const re = new RegExp(`^${key}:\\s*(.+)$`, "mg");
-  for (const [, val] of md.matchAll(re)) {
-    values.push(val.trim());
-  }
-  return values;
-}
-async function aggregateRequires(componentId, patternsDir, flatNameToPath, discoveryMap, visited = /* @__PURE__ */ new Set()) {
-  if (visited.has(componentId)) return { scripts: [], assets: [] };
-  visited.add(componentId);
-  const entry = discoveryMap.get(componentId);
-  let ownScripts = [];
-  let ownAssets = [];
-  if (entry?.mdPath) {
-    try {
-      const md = await readFile13(entry.mdPath, "utf-8");
-      ownScripts = parseFrontmatterList(md, "requireScript").map(normalizeScriptId);
-      ownAssets = parseFrontmatterList(md, "requireAssets").map((v) => v.trim().replace(/^\[(.+)\]$/, "$1").trim());
-    } catch {
-    }
-  }
-  const allScripts = [...ownScripts];
-  const allAssets = [...ownAssets];
-  const hbsPath = entry?.hbsPath ?? "";
-  let hbs = "";
-  try {
-    hbs = hbsPath ? await readFile13(hbsPath, "utf-8") : "";
-  } catch {
-  }
-  for (const flatName of parsePartialsFromHbs(hbs)) {
-    const childPath = flatNameToPath.get(flatName);
-    if (childPath) {
-      const child = await aggregateRequires(childPath, patternsDir, flatNameToPath, discoveryMap, visited);
-      allScripts.push(...child.scripts);
-      allAssets.push(...child.assets);
-    }
-  }
-  return {
-    scripts: [...new Set(allScripts)],
-    assets: [...new Set(allAssets)]
-  };
-}
-async function loadSvgAssets(ids, assetsDir) {
-  const contents = [];
-  for (const id of ids) {
-    for (const candidate of [`${id}.svg`, `images/${id}.svg`]) {
-      try {
-        const raw = await readFile13(join15(assetsDir, candidate), "utf-8");
-        contents.push(hideSvg(raw));
-        break;
-      } catch {
-      }
-    }
-  }
-  return contents;
-}
-function hideSvg(svg) {
-  return svg.replace(/<svg(\s|>)/, '<svg$1style="display:none;position:absolute" aria-hidden="true" ');
-}
-
 // packages/dev-server/src/detail.ts
 async function buildComponentDetail(componentId, patternsDir, renderFn, tracker, defaultTheme, flatNameToPath, compositionReg, scssGraph, classOwnerIndex, discoveryMap, baseProvenance) {
   const parts = componentId.split("/");
@@ -3075,7 +3099,7 @@ async function buildComponentDetail(componentId, patternsDir, renderFn, tracker,
 import { join as join16 } from "node:path";
 async function buildFolderOverview(folderPath, patternsDir, renderFn, discoveryMap) {
   const category = folderPath.split("/")[0];
-  let folderLayout = FULL_CATEGORIES.has(category) ? "full" : "centered";
+  let folderLayout = FULL_CATEGORIES.has(stripOrderPrefixes(category)) ? "full" : "centered";
   let doc;
   try {
     const rawIndex = await readFolderFile(patternsDir, join16(folderPath, "index.md"));
@@ -3214,10 +3238,10 @@ function normalizeAssetRefs(text, rootNames) {
 }
 
 // packages/dev-server/src/assets.ts
-import { existsSync as existsSync3 } from "node:fs";
+import { existsSync as existsSync4 } from "node:fs";
 import { createRequire as createRequire2 } from "node:module";
 import { fileURLToPath as fileURLToPath4 } from "node:url";
-function resolveDevUiDist(moduleUrl, exists = existsSync3) {
+function resolveDevUiDist(moduleUrl, exists = existsSync4) {
   const packaged = fileURLToPath4(new URL("./dev-ui/", moduleUrl));
   if (exists(`${packaged}main.js`)) return packaged;
   return fileURLToPath4(new URL("../../../apps/dev-ui/dist/", moduleUrl));
@@ -3310,7 +3334,12 @@ async function handleRequest(req, res, ctx) {
       const scriptId = normalizeScriptId(decodeURIComponent(basename4(pathname, ".js")));
       try {
         if (!state.scriptCache.has(scriptId)) {
-          const entryPoint = scriptsDirs.map((d) => join18(d, `${scriptId}.ts`)).find((f) => existsSync4(f)) ?? join18(scriptsDirs[0], `${scriptId}.ts`);
+          const entryPoint = scriptsDirs.map((d) => join18(d, `${scriptId}.ts`)).find((f) => existsSync5(f));
+          if (entryPoint === void 0) {
+            res.writeHead(404, { "Content-Type": "text/plain" });
+            res.end(`No script "${scriptId}": scripts are TypeScript, so ${scriptId}.ts is expected in ` + scriptsDirs.map((d) => relative6(cwd, d) || d).join(" or "));
+            return;
+          }
           const js = await compileScriptFile(entryPoint);
           state.scriptCache.set(scriptId, js);
         }
@@ -3594,7 +3623,7 @@ function describeBindError(e, port2, role, ports) {
 }
 
 // packages/dev-server/src/watch.ts
-import { basename as basename5, extname as extname3, relative as relative5, resolve as resolve8 } from "node:path";
+import { basename as basename5, extname as extname3, relative as relative7, resolve as resolve8 } from "node:path";
 import chokidar from "chokidar";
 function startWatching(ctx) {
   const { cfg, state, render, tracker, hotreloader } = ctx;
@@ -3706,7 +3735,7 @@ function startWatching(ctx) {
       }
       return void 0;
     };
-    const rel = relative5(patternsDir, filePath);
+    const rel = relative7(patternsDir, filePath);
     if (event === "change") state.discoveryResult ??= await buildDiscoveryMap(patternRoots);
     let owner = ownerIn(state.discoveryResult);
     if (event === "change") {
@@ -3788,21 +3817,21 @@ function startWatching(ctx) {
     if (ext === ".scss" && !(themesDir && filePath.startsWith(themesDir))) {
       await handleComponentScss(filePath);
     } else if (ext === ".hbs" && filePath.startsWith(patternsDir)) {
-      await rebuildAndSignalTree(`Pattern added: ${relative5(patternsDir, filePath)}`);
+      await rebuildAndSignalTree(`Pattern added: ${relative7(patternsDir, filePath)}`);
     } else if (ext === ".md" && filePath.startsWith(patternsDir)) {
       await handleMarkdown(filePath, "add");
     }
   });
   watcher.on("unlink", async (filePath) => {
     if (extname3(filePath) === ".hbs" && filePath.startsWith(patternsDir)) {
-      await rebuildAndSignalTree(`Pattern removed: ${relative5(patternsDir, filePath)}`);
+      await rebuildAndSignalTree(`Pattern removed: ${relative7(patternsDir, filePath)}`);
     } else if (extname3(filePath) === ".md" && filePath.startsWith(patternsDir)) {
       await handleMarkdown(filePath, "unlink");
     }
   });
   watcher.on("unlinkDir", async (dirPath) => {
     if (dirPath.startsWith(patternsDir) && dirPath !== patternsDir) {
-      await rebuildAndSignalTree(`Pattern dir removed: ${relative5(patternsDir, dirPath)}`);
+      await rebuildAndSignalTree(`Pattern dir removed: ${relative7(patternsDir, dirPath)}`);
     }
   });
   return watcher;
@@ -3810,7 +3839,7 @@ function startWatching(ctx) {
 
 // packages/dev-server/src/export-io.ts
 import { readFile as readFile16, writeFile as writeFile4, mkdir as mkdir4 } from "node:fs/promises";
-import { dirname as dirname6, join as join19, relative as relative6, resolve as resolve9 } from "node:path";
+import { dirname as dirname6, join as join19, relative as relative8, resolve as resolve9 } from "node:path";
 
 // packages/dev-server/src/export.ts
 var escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -3960,7 +3989,7 @@ async function planExport(config, cwd) {
       const hbs = await readFile16(entry.hbsPath, "utf-8");
       inputs.push({ id, hbs });
       hbsById.set(id, hbs);
-      relPathById.set(id, relative6(patternsDir, entry.hbsPath).replace(/\.hbs$/, ""));
+      relPathById.set(id, relative8(patternsDir, entry.hbsPath).replace(/\.hbs$/, ""));
       if (entry.jsonPath) {
         try {
           dataJsonById.set(id, await readFile16(entry.jsonPath, "utf-8"));
@@ -4047,7 +4076,7 @@ async function writeThreadedIncluders(threaded, patternsDir, sink) {
     const res = rewriteIncludes(src, map);
     if (res.rewrites === 0) continue;
     rewrites += res.rewrites;
-    const rel = relative6(patternsDir, hbsPath);
+    const rel = relative8(patternsDir, hbsPath);
     const outPath = join19(sink, rel);
     await mkdir4(dirname6(outPath), { recursive: true });
     await writeFile4(outPath, res.hbs, "utf-8");
@@ -4231,6 +4260,7 @@ async function startDevServer(config, cwd, opts = {}) {
     const styleData = await buildAllStyleData(styleRoots, allComponentIds);
     applyStyleData(state, styleData);
     surfaceDocumentBase(styleRoots, styleData.baseOutsideList, cwd);
+    await reportUnresolvableScripts(dr.discoveryMap, cfg.scriptsDirs, cfg.globalScripts, cwd);
   }
   const boot = {
     startedAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -4271,9 +4301,9 @@ async function startDevServer(config, cwd, opts = {}) {
 
 // packages/core/src/index.ts
 import { build as esbuild } from "esbuild";
-import { existsSync as existsSync5 } from "node:fs";
+import { existsSync as existsSync6 } from "node:fs";
 import { readFile as readFile17, writeFile as writeFile5, unlink, mkdir as mkdir5 } from "node:fs/promises";
-import { join as join21, dirname as dirname7, resolve as resolve10, relative as relative7, isAbsolute } from "node:path";
+import { join as join21, dirname as dirname7, resolve as resolve10, relative as relative9, isAbsolute } from "node:path";
 import { tmpdir as tmpdir2 } from "node:os";
 import { createHash as createHash3 } from "node:crypto";
 import { pathToFileURL as pathToFileURL2 } from "node:url";
@@ -4316,7 +4346,7 @@ function defaultExportDir(root) {
   return join21(tmpdir2(), "pattern-dump", key, "export");
 }
 function assertOutsideRoot(outDir, root) {
-  const rel = relative7(resolve10(root), resolve10(outDir));
+  const rel = relative9(resolve10(root), resolve10(outDir));
   const inside = rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
   if (inside) {
     throw new Error(
@@ -4387,14 +4417,14 @@ async function runExport(root, configPath, outDir) {
 }
 async function loadConfig(root, configPath) {
   if (configPath) {
-    if (!existsSync5(configPath)) {
+    if (!existsSync6(configPath)) {
       throw new ConfigError(`--config file not found: ${configPath}`);
     }
     return validateConfig(await readConfigFile(configPath), configPath);
   }
   for (const name of ["pattern-dump.config.ts", "pattern-dump.config.json"]) {
     const path = join21(root, name);
-    if (existsSync5(path)) return validateConfig(await readConfigFile(path), name);
+    if (existsSync6(path)) return validateConfig(await readConfigFile(path), name);
   }
   throw new ConfigError(
     `No pattern-dump.config.ts or pattern-dump.config.json found in ${root} (and no --config given)`
@@ -4609,14 +4639,14 @@ var USAGE = `Usage: pd <command> [options]
   help [command]   Show this help`;
 
 // packages/cli/src/init/run.ts
-import { existsSync as existsSync6 } from "node:fs";
+import { existsSync as existsSync7 } from "node:fs";
 import { readFile as readFile19 } from "node:fs/promises";
-import { basename as basename6, dirname as dirname9, join as join23, relative as relative9, resolve as resolve12 } from "node:path";
+import { basename as basename6, dirname as dirname9, join as join23, relative as relative11, resolve as resolve12 } from "node:path";
 
 // packages/cli/package.json
 var package_default = {
   name: "@pattern-dump/cli",
-  version: "0.1.0-alpha.2",
+  version: "0.1.0-alpha.3",
   private: true,
   description: "The pd command and the published pattern-dump package.",
   type: "module",
@@ -4652,14 +4682,14 @@ var PD_VERSION = package_default.version;
 
 // packages/cli/src/init/files.ts
 import { mkdir as mkdir6, readdir as readdir5, readFile as readFile18, writeFile as writeFile6 } from "node:fs/promises";
-import { dirname as dirname8, join as join22, relative as relative8, sep as sep2 } from "node:path";
+import { dirname as dirname8, join as join22, relative as relative10, sep as sep2 } from "node:path";
 async function readTemplateDir(dir) {
   const out = [];
   async function walk(current) {
     for (const entry of await readdir5(current, { withFileTypes: true })) {
       const full = join22(current, entry.name);
       if (entry.isDirectory()) await walk(full);
-      else out.push({ path: relative8(dir, full).split(sep2).join("/"), content: await readFile18(full, "utf8") });
+      else out.push({ path: relative10(dir, full).split(sep2).join("/"), content: await readFile18(full, "utf8") });
     }
   }
   await walk(dir);
@@ -4759,12 +4789,12 @@ function mergePackageJson(current, answers, packageName) {
 function dependencySpec(pdSource, cwd) {
   if (pdSource === void 0) return `^${PD_VERSION}`;
   const asPath = resolve12(cwd, pdSource);
-  if (existsSync6(asPath)) return `file:${asPath}`;
+  if (existsSync7(asPath)) return `file:${asPath}`;
   return pdSource.startsWith(`${PD_PACKAGE_NAME}@`) ? pdSource.slice(PD_PACKAGE_NAME.length + 1) : pdSource;
 }
 async function insideGitRepo(target, io) {
   let dir = target;
-  while (!existsSync6(dir) && dirname9(dir) !== dir) dir = dirname9(dir);
+  while (!existsSync7(dir) && dirname9(dir) !== dir) dir = dirname9(dir);
   return await io.run("git", ["rev-parse", "--is-inside-work-tree"], dir) === 0;
 }
 async function runInit(cmd, io) {
@@ -4789,7 +4819,7 @@ async function runInit(cmd, io) {
   }
   const pkgPath = join23(target, "package.json");
   let packageJson = null;
-  if (existsSync6(pkgPath)) {
+  if (existsSync7(pkgPath)) {
     try {
       packageJson = JSON.parse(await readFile19(pkgPath, "utf8"));
     } catch (e) {
@@ -4807,14 +4837,14 @@ async function runInit(cmd, io) {
   const install = cmd.install ?? (prompt ? await io.confirm("Run npm install", true) : true);
   const answers = { name, brand, examples, dependency };
   const templates = await readTemplates(io.templatesDir);
-  const result = planInit(templates, answers, { packageJson, exists: (p) => existsSync6(join23(target, p)) }, PD_PACKAGE_NAME);
+  const result = planInit(templates, answers, { packageJson, exists: (p) => existsSync7(join23(target, p)) }, PD_PACKAGE_NAME);
   if (!result.ok) {
     io.log(`\u2717 ${result.reason}`);
     return 1;
   }
   const { plan } = result;
   await applyPlan(target, plan);
-  const where = relative9(io.cwd, target) || ".";
+  const where = relative11(io.cwd, target) || ".";
   io.log(`\u2713 ${plan.writes.length} files written to ${where}`);
   io.log(`\u2713 package.json ${plan.packageJson.created ? "created" : "updated"} \u2014 ${PD_PACKAGE_NAME} ${answers.dependency}`);
   for (const note of plan.packageJson.notes) io.log(`  \xB7 ${note}`);
@@ -4847,7 +4877,7 @@ async function runInit(cmd, io) {
 }
 
 // packages/cli/src/init/local-build.ts
-import { existsSync as existsSync7, statSync } from "node:fs";
+import { existsSync as existsSync8, statSync } from "node:fs";
 import { join as join24 } from "node:path";
 import { fileURLToPath as fileURLToPath6 } from "node:url";
 var BUILT = [
@@ -4866,9 +4896,9 @@ var mtime = (path) => {
 };
 function detectLocalBuild(moduleUrl, packageName, version) {
   const repo = fileURLToPath6(new URL("../../../", moduleUrl)).replace(/[\\/]$/, "");
-  if (!existsSync7(join24(repo, "packages/cli/src/distribution.ts"))) return null;
+  if (!existsSync8(join24(repo, "packages/cli/src/distribution.ts"))) return null;
   const tarball = join24(repo, ".pd-pack", `${packageName}-${version}.tgz`);
-  if (!existsSync7(tarball)) return { repo, tarball: null, stale: false };
+  if (!existsSync8(tarball)) return { repo, tarball: null, stale: false };
   const newestBuild = Math.max(...BUILT.map((p) => mtime(join24(repo, p))));
   return { repo, tarball, stale: newestBuild > mtime(tarball) };
 }

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

@@ -8,7 +8,8 @@ export type ComponentStatus = "draft" | "stable" | "deprecated";
  * 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)
+ *  - "full":     the frame fills the stage width AND height, top-aligned (pages/templates, with or
+ *                without an ordering prefix: `05-pages` counts)
  * This is the RESOLVED mode (category default ← category index.md frontmatter ← component override),
  * so the shell renders directly without re-deriving precedence.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pattern-dump",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.3",
   "description": "A workbench for HTML and CSS design systems: live component previews, docs, checks and static publishing.",
   "keywords": [
     "design-system",