@weatherboard/gyde-design 0.4.1 → 0.4.3

package/agentdocs.mjs

@@ -122,6 +122,9 @@ export function agentDoc({
    * requirements rather than as facts about the implementation.
    */
   verified = true,
+  // An older Gyde-emitted set may predate the app theme controller. Its
+  // component metadata is verified, but this optional capability is absent.
+  themeChoice = verified,
 } = {}) {
   const closure = verified
     ? `**Never pass \`className\` or \`style\` to a design-system component.** They do not
@@ -191,7 +194,9 @@ brand — do **not** reach for inline styles. Spread \`themeVars(theme)\` onto a
 element you already own and set the component's tone to \`themed\`. It returns
 CSS custom properties only, which is why it is not an escape hatch.
 
-## App theme choice
+` : ""}
+
+${themeChoice ? `## App theme choice
 
 The design-system package supplies \`src/theme-bootstrap.js\` and exports
 \`${systemPackage}/theme-choice\`. The product must wire both into its app shell:
@@ -209,6 +214,17 @@ The design-system package supplies \`src/theme-bootstrap.js\` and exports
    replacement and repairs external attribute changes. Keep local route theme
    overrides on inner containers so they do not overwrite the global choice.
 
+Declare each browser host in \`gyde.config.json\` under \`design.themeHosts\`.
+For a standard HTML entry, use
+\`{ "appPath": "apps/web", "adapter": "html-inline", "html": "index.html", "entry": "src/main.js" }\`.
+The HTML head must contain the exact emitted bootstrap as a synchronous inline
+script before styles or external scripts, and load \`/src/main.js\` as a module.
+That module must import and call \`startThemeChoice\` from
+\`${systemPackage}/theme-choice\` immediately at module top level after that
+import. Gyde's gate checks these files and refuses
+an unsupported adapter; a framework-owned head needs its own adapter. Library
+packages without a browser host leave \`themeHosts\` absent or empty.
+
 The storage key is scoped to this design-system package. \`system\` is an
 explicit stored choice that removes \`data-theme\` from the document root and
 lets \`prefers-color-scheme\` decide. Unavailable storage keeps the current tab

package/cli.mjs

@@ -49,6 +49,7 @@ import { buildUsage, guidance, formatUsage } from "./usage.mjs";
 import { record, gate, formatGate, adopt, trim, formatTrim, LEDGER_NOTE } from "./ratchet.mjs";
 import { loadRules } from "./rules.mjs";
 import { validateScopeShape, checkScopeAgreement, formatScope } from "./scope.mjs";
+import { checkThemeHosts, formatThemeHosts } from "./themehost.mjs";
 
 /**
  * The single source of what would be written.
@@ -688,6 +689,16 @@ function cmdGate(root, config, { recordNewRules = false, trimLedger = false } =
     return 1;
   }
 
+  // Host wiring is a binary runtime contract, never an allowance entry. Check
+  // before the first-baseline path so recording debt cannot turn a missing
+  // pre-paint script into a passing gate.
+  const themeHosts = checkThemeHosts(root, design, { packages: ws.packages });
+  console.log(formatThemeHosts(themeHosts));
+  if (themeHosts.errors.length) {
+    writeEvidence(root, null, { ok: false, why: "declared theme host wiring is incomplete" });
+    return 1;
+  }
+
   const roots = exportedComponents(root, systemPath);
   const result = scan(root, { config: { ...design, componentRoots: roots ? new Set(roots) : null } });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weatherboard/gyde-design",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "private": false,
   "description": "Scaffolds a design system into a product repository, then keeps auditing it.",
   "type": "module",

package/theme-entry.mjs

@@ -0,0 +1,30 @@
+/** Parse the linked JavaScript module before accepting theme startup wiring. */
+import { parse } from "acorn";
+
+const directCall = (node, binding) => node?.type === "CallExpression" &&
+  node.callee.type === "Identifier" && node.callee.name === binding &&
+  node.arguments.length === 0 && !node.optional;
+
+/**
+ * Only an actual named import followed by a direct top-level call counts.
+ * Acorn's module AST excludes comments, strings, template literals, regex
+ * literals, branches and callbacks from this path. A syntax error is a failed
+ * static contract rather than a guess that source-looking text will execute.
+ */
+export function hasThemeStartup(source, systemPackage) {
+  let program;
+  try { program = parse(source, { ecmaVersion: "latest", sourceType: "module" }); }
+  catch { return false; }
+  for (const [index, node] of program.body.entries()) {
+    if (node.type !== "ImportDeclaration" ||
+        node.source.value !== `${systemPackage}/theme-choice`) continue;
+    const binding = node.specifiers.find((part) => part.type === "ImportSpecifier" &&
+      part.imported.type === "Identifier" && part.imported.name === "startThemeChoice")?.local.name;
+    if (!binding) continue;
+    const next = program.body[index + 1];
+    if (next?.type === "ExpressionStatement" && directCall(next.expression, binding)) return true;
+    if (next?.type === "VariableDeclaration" && next.kind === "const" &&
+        next.declarations.length === 1 && directCall(next.declarations[0].init, binding)) return true;
+  }
+  return false;
+}

package/themehost.mjs

@@ -0,0 +1,119 @@
+/** Static host contract for app shells Gyde knows how to inspect. */
+import { readFileSync, existsSync } from "node:fs";
+import { join, resolve, relative, sep } from "node:path";
+import { parse } from "parse5";
+import { hasThemeStartup } from "./theme-entry.mjs";
+
+const HTML_NAMESPACE = "http://www.w3.org/1999/xhtml";
+
+/**
+ * Read browser-parsed elements in a plain HTML entry. The parser handles
+ * raw text, RCDATA, and template contents as the browser does, so markup
+ * written inside them cannot masquerade as executable scripts.
+ */
+function htmlElements(html) {
+  const nodes = [];
+  const visit = (node, parent = null) => {
+    if (node.tagName && node.namespaceURI === HTML_NAMESPACE) {
+      if (node.tagName === "noscript") return;
+      // An implied head is not evidence that the source declares one.
+      if (node.sourceCodeLocation) {
+        nodes.push({
+          name: node.tagName,
+          attrs: new Map(node.attrs.map(({ name, value }) => [name, value])),
+          parent,
+          inert: false,
+          index: node.sourceCodeLocation.startOffset,
+          text: node.childNodes?.filter((child) => child.nodeName === "#text")
+            .map((child) => child.value).join("") ?? "",
+        });
+      }
+      parent = node.tagName;
+    }
+    // parse5 stores template children in `content`, separate from childNodes.
+    // Do not visit them: their scripts are inert in the host document.
+    for (const child of node.childNodes ?? []) visit(child, parent);
+  };
+  visit(parse(html, { sourceCodeLocationInfo: true, scriptingEnabled: true }));
+  return nodes;
+}
+
+function within(root, path) {
+  if (typeof path !== "string" || !path || path.startsWith("/")) return null;
+  const full = resolve(root, path);
+  const rel = relative(root, full);
+  return rel && rel !== ".." && !rel.startsWith(`..${sep}`) ? full : null;
+}
+
+function read(root, path) {
+  const full = within(root, path);
+  if (!full || !existsSync(full)) return null;
+  try { return readFileSync(full, "utf8"); } catch { return null; }
+}
+
+/**
+ * `html-inline` is intentionally narrow: it proves concrete wiring in a
+ * standard HTML entry and its directly linked module. Framework layouts need
+ * their own adapter; a text marker in config is never accepted as evidence.
+ */
+export function checkThemeHosts(root, design = {}, { packages = null } = {}) {
+  const declared = design.themeHosts;
+  if (declared === undefined) return { checked: 0, errors: [] };
+  if (!Array.isArray(declared)) return { checked: 0, errors: ["design.themeHosts must be an array"] };
+  const errors = [];
+  const systemPath = design.systemPath || "packages/design-system";
+  const systemPackage = design.systemPackage || `${design.scope}/design-system`;
+  const expected = read(root, `${systemPath}/src/theme-bootstrap.js`);
+  for (const [index, host] of declared.entries()) {
+    const label = `design.themeHosts[${index}]`;
+    if (!host || typeof host !== "object" || host.adapter !== "html-inline") {
+      errors.push(`${label}: unsupported adapter; this gate currently supports html-inline`);
+      continue;
+    }
+    const app = within(root, host.appPath);
+    if (!app || !existsSync(join(app, "package.json")) ||
+        (packages && !packages.some((p) => p.absolute === app))) {
+      errors.push(`${label}: appPath must name an existing workspace package`);
+      continue;
+    }
+    const html = read(app, host.html);
+    const entry = read(app, host.entry);
+    if (html === null) errors.push(`${label}: declared HTML file is missing or unreadable`);
+    if (entry === null) errors.push(`${label}: declared module entry is missing or unreadable`);
+    if (expected === null) errors.push(`${label}: emitted theme-bootstrap.js is missing or unreadable`);
+    if (html === null || entry === null || expected === null) continue;
+    const elements = htmlElements(html);
+    if (!elements.some((n) => n.name === "head" && !n.inert)) {
+      errors.push(`${label}: HTML has no head element`);
+      continue;
+    }
+    const headNodes = elements.filter((n) => n.parent === "head" && !n.inert);
+    const inline = headNodes.find((n) => n.name === "script" &&
+      !["src", "type", "defer", "async", "nomodule"].some((attr) => n.attrs.has(attr)) &&
+      n.text.trim() === expected.trim());
+    if (!inline) errors.push(`${label}: head must contain the exact emitted bootstrap as an inline script`);
+    else {
+      const earlyResource = headNodes.some((n) => n.index < inline.index &&
+        (n.name === "style" ||
+          (n.name === "link" && n.attrs.get("rel")?.toLowerCase().split(/\s+/).includes("stylesheet")) ||
+          (n.name === "script" && n.attrs.has("src"))));
+      if (earlyResource) {
+        errors.push(`${label}: bootstrap must precede styles and external scripts in head`);
+      }
+    }
+    const src = `/${host.entry?.replace(/^\/+/, "")}`;
+    const moduleTag = elements.some((n) => n.name === "script" && !n.inert &&
+      n.attrs.get("type")?.toLowerCase() === "module" && n.attrs.get("src") === src);
+    if (!moduleTag) errors.push(`${label}: HTML must load the declared entry as a module script`);
+    if (!hasThemeStartup(entry, systemPackage)) {
+      errors.push(`${label}: linked entry must import and immediately call startThemeChoice at module top level`);
+    }
+  }
+  return { checked: declared.length, errors };
+}
+
+export function formatThemeHosts(result) {
+  return result.errors.length
+    ? `theme hosts  ${result.checked} declared, ${result.errors.length} error(s):\n${result.errors.map((e) => `  ${e}`).join("\n")}`
+    : `theme hosts  ${result.checked} declared, checked`;
+}