@weatherboard/gyde-design 0.4.0 → 0.4.2

package/selfgate.mjs

@@ -0,0 +1,162 @@
+/**
+ * G-127 — Gyde runs its own gate over the scaffold Gyde emits.
+ *
+ * ===========================================================================
+ * WHY THIS FILE EXISTS
+ * ===========================================================================
+ *
+ * `emit.mjs` has carried this sentence since G-101:
+ *
+ *   "So this stays below the threshold until the templates earn it. The rule,
+ *    and `emit.test.mjs` enforces it: a fresh scaffold must pass the gate Gyde
+ *    would run against it."
+ *
+ * `emit.test.mjs` did not enforce it. It checked that no component declares a
+ * style-shaped prop and that none spreads `{...rest}` — both worth checking,
+ * neither of them the gate. Nothing anywhere ran `gyde-design gate` against the
+ * emitted tree, so the claim was true of nobody's code and read as true of all
+ * of it.
+ *
+ * What that cost, measured: the scaffold emitted on 2026-09-15 shipped **ten**
+ * `optional-prop` findings across five of its five components — Button 3,
+ * Checkbox 3, Select 2, Card 1, Text 1. The tool that fails a customer for an
+ * optional prop wrote ten of them into every repository it scaffolded, and the
+ * customer found out, not us.
+ *
+ * ===========================================================================
+ * IT MEASURES THROUGH THE FRONT DOOR
+ * ===========================================================================
+ *
+ * `init` and `gate` are run as SUBPROCESSES, through `cli.mjs`, exactly as a
+ * customer runs them. Importing `scan()` and calling it here would be shorter
+ * and would measure a different thing: the CLI is where `design.scope` is read,
+ * where `exportedComponents` narrows `componentRoots`, and where the ledger is
+ * consulted. A number taken around it is a real number about a repository that
+ * does not exist.
+ *
+ * ===========================================================================
+ * THE ASSERTION IS ON THE BASELINE, NOT ON THE EXIT CODE
+ * ===========================================================================
+ *
+ * `gate` on a tree with no ledger RECORDS one and exits 1 — deliberately, since
+ * recording debt is not a pass. So a green exit code cannot be the check here:
+ * the clean run's exit code is 1 by design, and the second run's exit code is 0
+ * whatever the first run recorded, because the first run wrote every finding
+ * into the allowance.
+ *
+ * Gate a scaffold with ten optional props and the second run passes. That is
+ * correct behaviour for a customer adopting Gyde and useless as a check on
+ * ourselves, which is why this reads `total` out of the recorded baseline.
+ * **A scaffold Gyde emits starts at zero, or it is not a scaffold Gyde may
+ * emit.** The exit code of the second run is checked as well, because a
+ * baseline of zero followed by a failing gate would mean something else is
+ * wrong.
+ */
+
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const CLI = join(HERE, "cli.mjs");
+
+/** The scope the probe repository declares. Arbitrary, but it must agree with itself (G-123). */
+const SCOPE = "@selfgate";
+
+function cli(args) {
+  try {
+    return { code: 0, out: execFileSync(process.execPath, [CLI, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }) };
+  } catch (error) {
+    /**
+     * A non-zero exit is an ORDINARY outcome here — `gate` exits 1 when it
+     * records a baseline — so it is returned rather than thrown. Throwing would
+     * make the clean path the exceptional one.
+     */
+    return { code: error.status ?? 1, out: `${error.stdout ?? ""}${error.stderr ?? ""}` };
+  }
+}
+
+/**
+ * Emit a scaffold into a fresh directory and gate it.
+ *
+ * `corrupt` receives the directory after `init` and before `gate`, so a caller
+ * can put a defect into the emitted source and prove the gate sees it. That is
+ * the negative fixture, and it is the only reason this parameter exists: a
+ * check that has never been watched to fail is a check nobody has evidence of.
+ */
+export function gateAScaffold({ corrupt = null, dir = null } = {}) {
+  const root = dir ?? mkdtempSync(join(tmpdir(), "gyde-selfgate-"));
+  mkdirSync(root, { recursive: true });
+
+  writeFileSync(join(root, "package.json"),
+    JSON.stringify({ name: "gyde-selfgate-probe", private: true, workspaces: ["packages/*", "apps/*"] }, null, 2) + "\n");
+  writeFileSync(join(root, "gyde.config.json"),
+    JSON.stringify({ version: 1, design: { scope: SCOPE } }, null, 2) + "\n");
+
+  const init = cli(["init", root]);
+  if (init.code !== 0) return { root, phase: "init", ok: false, total: null, init, baseline: null, judged: null };
+
+  if (corrupt) corrupt(root);
+
+  const baseline = cli(["gate", root]);
+  let total = null;
+  try { total = JSON.parse(readFileSync(join(root, "gyde-allowance.json"), "utf8")).total ?? null; } catch { /* reported as null */ }
+
+  const judged = cli(["gate", root]);
+
+  return {
+    root,
+    phase: "gate",
+    total,
+    baseline,
+    judged,
+    ok: total === 0 && judged.code === 0,
+  };
+}
+
+/**
+ * The findings the baseline recorded, as `file  rule  count` lines.
+ *
+ * Read back out of the written ledger rather than parsed from the gate's
+ * stdout: the prose changes, the file is the record.
+ */
+export function baselineFindings(root) {
+  let led;
+  try { led = JSON.parse(readFileSync(join(root, "gyde-allowance.json"), "utf8")); } catch { return []; }
+  const out = [];
+  for (const [file, rules] of Object.entries(led.allowed ?? {})) {
+    for (const [rule, count] of Object.entries(rules)) out.push({ file, rule, count });
+  }
+  return out.sort((a, b) => a.file.localeCompare(b.file) || a.rule.localeCompare(b.rule));
+}
+
+export function formatSelfGate(result) {
+  const L = [];
+  if (result.phase === "init") {
+    L.push("the scaffold could not be emitted at all:");
+    L.push(result.init.out.trim());
+    return L.join("\n");
+  }
+  const findings = baselineFindings(result.root);
+  if (result.ok) return `a fresh scaffold records a baseline of 0 finding(s) and passes \`gyde-design gate\``;
+
+  L.push(`Gyde emitted a scaffold its own gate rejects: ${result.total} finding(s).`);
+  L.push("");
+  for (const f of findings) L.push(`  ${f.file}  ${f.rule} x${f.count}`);
+  L.push("");
+  if (result.judged.code !== 0) L.push(`  the judged run also exited ${result.judged.code}`);
+  L.push("  Fix the TEMPLATES in packages/design/emit.mjs. Do not record a baseline for");
+  L.push("  this — a customer's ledger may carry pre-existing debt, but the scaffold we");
+  L.push("  hand them starts at zero or it is not one we may hand them.");
+  return L.join("\n");
+}
+
+/* Run directly (`node packages/design/selfgate.mjs`) — this is what `verify` calls. */
+if (process.argv[1] && process.argv[1].endsWith("selfgate.mjs")) {
+  const result = gateAScaffold();
+  console.log(formatSelfGate(result));
+  try { rmSync(result.root, { recursive: true, force: true }); } catch { /* a leftover temp dir is not a failure */ }
+  process.exitCode = result.ok ? 0 : 1;
+}

package/theme-choice.mjs

@@ -0,0 +1,111 @@
+/** Browser theme lifecycle emitted into each product's design system. */
+export function emitThemeChoice({ path = "packages/design-system", storageKey }) {
+  const key = JSON.stringify(storageKey);
+  const bootstrap = `/* GENERATED BY GYDE — then yours. Inline this script in <head> before styles. */
+(() => {
+  const key = ${key};
+  let choice = "system";
+  try {
+    const stored = localStorage.getItem(key);
+    if (stored === "light" || stored === "dark") choice = stored;
+  } catch { /* Storage can be unavailable; the system preference remains usable. */ }
+  if (choice === "system") document.documentElement.removeAttribute("data-theme");
+  else document.documentElement.setAttribute("data-theme", choice);
+})();
+`;
+  const controller = `/* GENERATED BY GYDE — then yours.
+ * The app owns its root and calls startThemeChoice() once after hydration.
+ * This module adds no provider or layout element.
+ */
+export const THEME_STORAGE_KEY = ${key};
+const valid = (value) => value === "light" || value === "dark" || value === "system";
+
+export function startThemeChoice({ doc = document, win = window } = {}) {
+  let choice = "system";
+  let root;
+  let rootObserver;
+  const listeners = new Set();
+  const media = win.matchMedia("(prefers-color-scheme: dark)");
+  const read = () => {
+    try {
+      const stored = win.localStorage.getItem(THEME_STORAGE_KEY);
+      choice = valid(stored) ? stored : "system";
+    } catch { /* Keep the in-memory choice when storage is unavailable. */ }
+  };
+  const resolvedTheme = () => choice === "system" ? (media.matches ? "dark" : "light") : choice;
+  const notify = () => { for (const listener of listeners) listener(choice, resolvedTheme()); };
+  const reconcile = () => {
+    if (root !== doc.documentElement) {
+      rootObserver?.disconnect();
+      root = doc.documentElement;
+      if (root) rootObserver?.observe(root, { attributes: true, attributeFilter: ["data-theme"] });
+    }
+    if (!root) return;
+    if (choice === "system") {
+      if (root.hasAttribute("data-theme")) root.removeAttribute("data-theme");
+    } else if (root.getAttribute("data-theme") !== choice) root.setAttribute("data-theme", choice);
+  };
+  rootObserver = new win.MutationObserver(reconcile);
+  const documentObserver = new win.MutationObserver(reconcile);
+  documentObserver.observe(doc, { childList: true });
+  read();
+  reconcile();
+  const onStorage = (event) => {
+    if (event.key !== THEME_STORAGE_KEY && event.key !== null) return;
+    try { if (event.storageArea && event.storageArea !== win.localStorage) return; }
+    catch { /* Storage access is blocked; read() retains the in-memory choice. */ }
+    read(); reconcile(); notify();
+  };
+  const onPageShow = () => { read(); reconcile(); notify(); };
+  const onNavigate = () => { reconcile(); notify(); };
+  const onMedia = () => { if (choice === "system") notify(); };
+  win.addEventListener("storage", onStorage);
+  win.addEventListener("pageshow", onPageShow);
+  win.addEventListener("popstate", onNavigate);
+  win.addEventListener("hashchange", onNavigate);
+  media.addEventListener("change", onMedia);
+  return {
+    getChoice: () => choice,
+    getResolvedTheme: resolvedTheme,
+    setChoice(next) {
+      if (!valid(next)) throw new TypeError("Theme choice must be light, dark, or system");
+      choice = next;
+      try { win.localStorage.setItem(THEME_STORAGE_KEY, next); } catch { /* Current tab still works. */ }
+      reconcile(); notify();
+    },
+    reconcile,
+    subscribe(listener) { listeners.add(listener); listener(choice, resolvedTheme()); return () => listeners.delete(listener); },
+    stop() {
+      rootObserver.disconnect();
+      documentObserver.disconnect();
+      win.removeEventListener("storage", onStorage);
+      win.removeEventListener("pageshow", onPageShow);
+      win.removeEventListener("popstate", onNavigate);
+      win.removeEventListener("hashchange", onNavigate);
+      media.removeEventListener("change", onMedia);
+      listeners.clear();
+    },
+  };
+}
+`;
+  return {
+    [`${path}/src/theme-bootstrap.js`]: bootstrap,
+    [`${path}/src/theme-choice.js`]: controller,
+    [`${path}/src/theme-choice.d.ts`]: `/* GENERATED BY GYDE — then yours.
+ * Gyde wrote this file once and will never overwrite it.
+ */
+export type ThemeChoice = "light" | "dark" | "system";
+export type ResolvedTheme = "light" | "dark";
+export declare const THEME_STORAGE_KEY: string;
+export interface ThemeChoiceController {
+  getChoice(): ThemeChoice;
+  getResolvedTheme(): ResolvedTheme;
+  setChoice(next: ThemeChoice): void;
+  reconcile(): void;
+  subscribe(listener: (choice: ThemeChoice, resolved: ResolvedTheme) => void): () => void;
+  stop(): void;
+}
+export declare function startThemeChoice(): ThemeChoiceController;
+`,
+  };
+}

package/tokens.mjs

@@ -252,10 +252,12 @@ export function generateCss(dict = SEED) {
     "/* An explicit choice, on any element — which is what makes both themes",
     "   renderable on one page, and what a portalled popup looks up. */",
     '[data-theme="dark"] {',
+    '  color-scheme: dark;',
     decls("dark"),
     "}",
     "",
     '[data-theme="light"] {',
+    '  color-scheme: light;',
     decls("light"),
     "}",
     "",

package/wiring.mjs

@@ -28,7 +28,24 @@ import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
 import { join, extname, relative, sep } from "node:path";
 
 const SKIP = new Set(["node_modules", "dist", "build", ".next", ".turbo", ".git", "coverage"]);
-const SOURCE = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".css", ".scss"]);
+/**
+ * G-126. `.astro`, `.vue` and `.svelte` are import sites too.
+ *
+ * Measured 2026-09-15 on a consumer repository: `apps/web` was
+ * reported as "renders design-system components but never imports the token
+ * stylesheet" while `src/layouts/Base.astro` imported the stylesheet on line 2
+ * and the `:root` block was inlined into all four built pages. The walk simply
+ * never opened the file, so the import could not be seen.
+ *
+ * It is the worst direction to be wrong in for the second time in this file: a
+ * check that fails a correctly-wired repository gets switched off, and then it
+ * is not protecting the ones that ARE broken. The single-file-component formats
+ * put their imports in a frontmatter or `<script>` block rather than at the top
+ * of a `.js`, and everything below reads file TEXT rather than a parse tree, so
+ * recognising the extension is the whole fix — the `import "...css"` line looks
+ * identical once the file is read.
+ */
+const SOURCE = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".css", ".scss", ".astro", ".vue", ".svelte"]);
 
 export const WIRING = {
   OK: "wired",
@@ -125,10 +142,48 @@ export function exportedComponents(root, systemPath) {
  * Depth is bounded and cycles are tracked, because a stylesheet importing
  * itself should be a finding somewhere else, not a hang here.
  */
-function reachesTokens(root, startFile, { packageDirs, tokensPackage, seen = new Set(), depth = 0 }) {
+function reachesTokens(root, startFile, { packageDirs, tokensPackage, seen = new Set(), depth = 0, viaPackageSpecifier = false }) {
   if (depth > 8 || seen.has(startFile)) return false;
   seen.add(startFile);
 
+  /**
+   * G-126. The file we have arrived at IS the token stylesheet.
+   *
+   * Without this, a consumer that imports the tokens DIRECTLY — the simplest
+   * correct arrangement — reports unwired whenever `tokensPackage` is unset,
+   * because every branch below looks for an import OF the tokens rather than
+   * for the tokens themselves. A repository with no `gyde.config.json` has
+   * `tokensPackage` null, which is most of them.
+   *
+   * `viaPackageSpecifier` is the whole safety of it, and the first version of
+   * this change did not have it. A bare basename test fires on any path that
+   * ENDS in `tokens.css`, and two of the three ways into this function arrive
+   * with a path nobody resolved: `checkPackage` passes each walked file itself,
+   * and it passes a relative `./tokens.css` target with no `existsSync` behind
+   * it. The test then returned before the `readFileSync` that had been doing
+   * the existence check by accident. Four arrangements reported `wired` that
+   * are not: a stray unimported `apps/web/src/tokens.css`; a file importing an
+   * unrelated local `./tokens.css`; a file importing a `./tokens.css` that does
+   * not exist at all; and the stray-file case with `tokensPackage` configured,
+   * which had nothing to do with frontmatter and would have been a plain
+   * regression.
+   *
+   * So the shortcut fires only when we got here by resolving a workspace
+   * package specifier to a file that exists — the two `packageDirs` sites,
+   * which are the only callers that check. `depth` cannot stand in for this:
+   * `checkPackage`'s package-specifier loop calls at depth 0.
+   *
+   * And it declines entirely when `tokensPackage` IS configured, because then
+   * it can only ever be wrong. The two branches above already answer the
+   * question exactly for a configured repository — they compare against the
+   * package the config names — so the shortcut adds no correct verdict and one
+   * incorrect one: `import "@x/charts/src/tokens.css"`, an unrelated workspace
+   * package that happens to ship a file of that name, resolved to a real path
+   * and reported as wiring. Narrowing by HOW we arrived was not enough; the
+   * basename is only evidence at all when nothing better is available.
+   */
+  if (viaPackageSpecifier && !tokensPackage && /(^|\/)tokens\.css$/.test(startFile)) return true;
+
   let text; try { text = readFileSync(join(root, startFile), "utf8"); } catch { return false; }
   if (tokensPackage && text.includes(`${tokensPackage}/`) && /tokens\.css/.test(text)) return true;
 
@@ -142,7 +197,7 @@ function reachesTokens(root, startFile, { packageDirs, tokensPackage, seen = new
       const sub = spec.slice(name.length + 1);
       for (const guess of [join(dir, sub), join(dir, "src", sub)]) {
         if (existsSync(join(root, guess))) {
-          if (reachesTokens(root, guess, { packageDirs, tokensPackage, seen, depth: depth + 1 })) return true;
+          if (reachesTokens(root, guess, { packageDirs, tokensPackage, seen, depth: depth + 1, viaPackageSpecifier: true })) return true;
         }
       }
     }
@@ -185,7 +240,7 @@ export function checkPackage(root, pkg, { systemPackage, tokensPackage, componen
               if (!spec.startsWith(name + "/")) continue;
               const sub = spec.slice(name.length + 1);
               for (const guess of [join(dir, sub), join(dir, "src", sub)]) {
-                if (existsSync(join(root, guess)) && reachesTokens(root, guess, { packageDirs, tokensPackage })) importsTokens = true;
+                if (existsSync(join(root, guess)) && reachesTokens(root, guess, { packageDirs, tokensPackage, viaPackageSpecifier: true })) importsTokens = true;
               }
             }
           }

package/workflow.mjs

@@ -127,7 +127,7 @@ export function emitWorkflow({
   // rewrote this to "System A/gyde@v1" and two tests caught it — an emitted
   // workflow pointing at an organisation that does not exist. The org and one
   // of the products genuinely share a name; only one of the two uses is data.
-  action = "Another-Iteration/gyde@v1",
+  action = "Weatherboard-Studio/gyde@v1",
   /**
    * Blocking by default.
    *