sdtk-design-kit 0.1.2 → 0.2.1

package/src/commands/prototype.js

@@ -6,6 +6,7 @@ const { parseFlags } = require("../lib/args");
 const { describeDesignPaths, resolveProjectPath } = require("../lib/design-paths");
 const { inferDomainProfile } = require("../lib/domain-profile");
 const { ValidationError } = require("../lib/errors");
+const { renderMultiPagePrototype, screenFileName } = require("../lib/prototype-renderer");
 const { DEFAULT_STYLE, availableStyleNames, resolveStyleName } = require("../lib/style-presets");
 
 const PROTOTYPE_FLAG_DEFS = {
@@ -101,16 +102,38 @@ Reads:
   .sdtk/design/START_INPUT_STATE.json (optional; enables explicit multi-screen rendering when ready)
 
 Creates:
-  docs/design/prototype/index.html
+  legacy/simple mode:
+    docs/design/prototype/index.html
+  from-spec multi-page mode:
+    docs/design/prototype/index.html
+    docs/design/prototype/screens/*.html
+    docs/design/prototype/assets/prototype.css
+    docs/design/prototype/assets/prototype.js
 
 Safety:
   Local files only.
   Existing prototype index is not overwritten unless --force is explicit.
   No production app code outside docs/design/prototype.
-  No JavaScript runtime, server, network call, .sdtk/atlas, or SDTK-WIKI output mutation.`);
+  No JavaScript app runtime, server, network call, .sdtk/atlas, or SDTK-WIKI output mutation.`);
   return 0;
 }
 
+function resolvePrototypeMode(canUseMultiScreen) {
+  if (!canUseMultiScreen) {
+    return "single";
+  }
+  const raw = String(process.env.SDTK_DESIGN_PROTOTYPE_MODE || "").trim().toLowerCase();
+  if (!raw) {
+    return "multi";
+  }
+  if (raw === "single" || raw === "multi") {
+    return raw;
+  }
+  throw new ValidationError(
+    `Unsupported SDTK_DESIGN_PROTOTYPE_MODE "${process.env.SDTK_DESIGN_PROTOTYPE_MODE}". Use "single" or "multi". No project files were changed.`
+  );
+}
+
 function wireframePath(paths, fileName) {
   return path.join(paths.wireframesPath, fileName);
 }
@@ -309,7 +332,192 @@ function renderPrimitiveChips(primitiveNames) {
 
 function renderStateChips(requiredStates) {
   if (!Array.isArray(requiredStates) || requiredStates.length === 0) return "";
-  return `<div class="chip-row">${requiredStates.slice(0, 3).map((item) => `<span class="chip chip-state">${escapeHtml(item)}</span>`).join("")}</div>`;
+  return `<div class="chip-row">${requiredStates
+    .slice(0, 3)
+    .map((item) => `<span class="chip" data-chip-type="state">${escapeHtml(item)}</span>`)
+    .join("")}</div>`;
+}
+
+function screenBriefPath(paths, screenId) {
+  return path.join(paths.screensPath, `${screenId}_DESIGN_BRIEF.md`);
+}
+
+function screenBriefSidecarPath(paths, screenId) {
+  return path.join(paths.designScreenBriefsStatePath, `${screenId}.json`);
+}
+
+function readJsonSafe(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+  } catch (_err) {
+    return null;
+  }
+}
+
+function loadHighFidelityContracts(paths, statePayload) {
+  const warnings = [];
+  if (!fs.existsSync(paths.componentPatternLibraryPath)) {
+    warnings.push("missing docs/design/COMPONENT_PATTERN_LIBRARY.md");
+  }
+  if (!fs.existsSync(paths.designTokensPath)) {
+    warnings.push("missing docs/design/DESIGN_TOKENS.json");
+  }
+  const missingBriefs = [];
+  const screenContracts = new Map();
+  for (const screen of statePayload.screenModel.screens) {
+    const briefPath = screenBriefPath(paths, screen.screenId);
+    if (!fs.existsSync(briefPath)) {
+      missingBriefs.push(screen.screenId);
+      continue;
+    }
+    const sidecarPath = screenBriefSidecarPath(paths, screen.screenId);
+    screenContracts.set(screen.screenId, {
+      briefPath,
+      briefContent: fs.readFileSync(briefPath, "utf-8"),
+      sidecar: fs.existsSync(sidecarPath) ? readJsonSafe(sidecarPath) : null,
+    });
+  }
+  if (missingBriefs.length > 0) {
+    warnings.push(`missing per-screen briefs for: ${missingBriefs.join(", ")}`);
+  }
+  if (warnings.length > 0) {
+    return { ready: false, warnings, screenContracts: new Map(), tokens: null };
+  }
+  const tokens = readJsonSafe(paths.designTokensPath);
+  if (!tokens || typeof tokens !== "object") {
+    return { ready: false, warnings: ["invalid docs/design/DESIGN_TOKENS.json"], screenContracts: new Map(), tokens: null };
+  }
+  return { ready: true, warnings: [], screenContracts, tokens };
+}
+
+function managedPrototypeTargets(paths, statePayload, mode) {
+  const targets = [{ relativePath: "docs/design/prototype/index.html", filePath: paths.prototypeIndexPath }];
+  if (
+    mode === "multi" &&
+    statePayload &&
+    statePayload.screenModel &&
+    Array.isArray(statePayload.screenModel.screens)
+  ) {
+    targets.push(
+      { relativePath: "docs/design/prototype/assets/prototype.css", filePath: paths.prototypeCssPath },
+      { relativePath: "docs/design/prototype/assets/prototype.js", filePath: paths.prototypeJsPath },
+      ...statePayload.screenModel.screens.map((screen) => ({
+        relativePath: `docs/design/prototype/screens/${screenFileName(screen)}`,
+        filePath: path.join(paths.prototypeScreensPath, screenFileName(screen)),
+      }))
+    );
+  }
+  return targets;
+}
+
+function tokenOrDefault(tokens, keyPath, fallback) {
+  const value = keyPath.reduce((obj, key) => (obj && Object.prototype.hasOwnProperty.call(obj, key) ? obj[key] : undefined), tokens);
+  return value == null ? fallback : value;
+}
+
+function renderHighFidelityScreen(screenRole, title) {
+  switch (screenRole) {
+    case "home":
+      return `
+      <section class="hf-hero panel"><h3>${escapeHtml(title)} hero</h3><p>Category-first commerce landing with featured products and guided CTA.</p><div class="button-row"><a class="btn btn-primary" href="#">Start purchase</a><a class="btn btn-secondary" href="#">Open configurator</a></div></section>
+      <section class="hf-feature-grid"><article class="panel">Category range</article><article class="panel">Featured products</article><article class="panel">Configurator quick start</article></section>`;
+    case "category":
+      return `<section class="hf-split"><aside class="panel">Filter sidebar</aside><div class="panel"><h3>Product grid</h3><div class="hf-card-grid"><article class="product-card">Card A</article><article class="product-card">Card B</article><article class="product-card">Card C</article></div></div></section>`;
+    case "product-detail":
+      return `<section class="hf-split"><div class="panel"><h3>Gallery and spec area</h3><table class="spec-table"><tr><th>Spec</th><th>Value</th></tr><tr><td>Voltage</td><td>High pressure</td></tr></table></div><aside class="panel"><h3>Price and quantity</h3><div class="qty-stepper"><button>-</button><span>1</span><button>+</button></div><a class="btn btn-primary" href="#">Add to cart</a></aside></section>`;
+    case "search":
+      return `<section class="panel"><h3>Search and result state</h3><div class="search-toolbar"><input aria-label="Search query" placeholder="Search product"><button class="btn btn-primary">Search</button></div><div class="hf-list"><article class="result-row">Result item</article><article class="result-row no-result">No-result state</article></div></section>`;
+    case "cart":
+      return `<section class="hf-split"><div class="panel"><h3>Cart table</h3><table class="cart-table"><tr><th>Item</th><th>Qty</th><th>Total</th></tr><tr><td>Product</td><td><div class="qty-stepper"><button>-</button><span>2</span><button>+</button></div></td><td>100000</td></tr></table></div><aside class="panel"><h3>Summary</h3><p>Subtotal, tax, total</p><a class="btn btn-primary" href="#">Checkout</a></aside></section>`;
+    case "checkout":
+      return `<section class="panel"><ol class="checkout-stepper"><li>Information</li><li>Confirmation</li><li>Complete</li></ol><div class="hf-split"><div class="panel"><h3>Checkout form</h3><div class="field-row">Recipient / Address / Phone</div></div><aside class="panel"><h3>Summary card</h3><a class="btn btn-primary" href="#">Place order</a></aside></div></section>`;
+    case "order-history":
+      return `<section class="panel"><h3>Order history list</h3><div class="hf-list"><article class="result-row">Order #001 / paid</article><article class="result-row">Order #002 / shipping</article></div></section>`;
+    case "order-detail":
+      return `<section class="hf-split"><div class="panel"><h3>Order timeline</h3><ul class="timeline"><li>Placed</li><li>Paid</li><li>Shipping</li></ul></div><aside class="panel"><h3>Detail summary</h3><p>Delivery and payment snapshot</p></aside></section>`;
+    case "account-info":
+      return `<section class="hf-split"><aside class="panel">Account sidebar</aside><div class="panel"><h3>View or edit form</h3><div class="field-row">Company / Contact / Email / Phone</div><a class="btn btn-primary" href="#">Save profile</a></div></section>`;
+    case "mode-b-configurator":
+      return `<section class="panel"><h3>Configurator wizard</h3><ol class="checkout-stepper"><li>Project</li><li>Assembly</li><li>Construction</li><li>Review</li></ol><div class="hf-split"><div class="panel"><h4>Preview panel</h4><p>Derived material preview</p></div><div class="panel"><h4>BOM table</h4><table class="cart-table"><tr><th>Material</th><th>Qty</th><th>Action</th></tr><tr><td>Cable</td><td>4</td><td><button>Exclude</button></td></tr></table><div class="button-row"><a class="btn btn-secondary" href="#">Recalculate</a><a class="btn btn-primary" href="#">Add BOM to cart</a></div></div></div></section>`;
+    default:
+      return `<section class="panel"><h3>Screen contract section</h3><p>Render screen-specific layout from brief + component contract.</p></section>`;
+  }
+}
+
+function highFidelityMultiScreenPrototypeContent({ style, statePayload, contractBundle }) {
+  const styleName = resolveStyleName(style);
+  const tokens = contractBundle.tokens || {};
+  const screens = statePayload.screenModel.screens;
+  const profileSelection = statePayload.profileSelection || null;
+  const mappedRefs = statePayload.referenceMap && typeof statePayload.referenceMap.mappedCount === "number" ? statePayload.referenceMap.mappedCount : 0;
+  const sections = screens
+    .map((screen) => {
+      const screenRole = normalizeScreenRole(screen);
+      const contract = contractBundle.screenContracts.get(screen.screenId);
+      const sidecar = contract && contract.sidecar ? contract.sidecar : null;
+      const stateChips = renderStateChips(sidecar && Array.isArray(sidecar.required_states) ? sidecar.required_states : screen.requiredStates);
+      return `
+      <section class="prototype-section screen-${escapeHtml(screen.screenId)}" id="screen-${escapeHtml(screen.screenId)}" aria-labelledby="title-${escapeHtml(screen.screenId)}">
+        <div class="section-inner">
+          <div class="section-header">
+            <p class="eyebrow">${escapeHtml(screenRole.replace(/-/g, " "))}</p>
+            <h2 id="title-${escapeHtml(screen.screenId)}">${escapeHtml(screen.title)}</h2>
+            ${screen.route ? `<p class="support">Route: <code>${escapeHtml(screen.route)}</code></p>` : ""}
+            <p class="support">Source brief: <code>${escapeHtml(path.basename(contract.briefPath))}</code></p>
+          </div>
+          ${stateChips}
+          ${renderHighFidelityScreen(screenRole, screen.title)}
+        </div>
+      </section>`;
+    })
+    .join("");
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>SDTK-DESIGN High-Fidelity Prototype</title>
+  <style>
+    :root { --bg:${tokenOrDefault(tokens, ["color", "surfaceAlt"], "#F5F7FB")}; --surface:${tokenOrDefault(tokens, ["color", "surface"], "#FFFFFF")}; --text:${tokenOrDefault(tokens, ["color", "textPrimary"], "#111827")}; --muted:${tokenOrDefault(tokens, ["color", "textMuted"], "#64748B")}; --primary:${tokenOrDefault(tokens, ["color", "accentPrimary"], "#0F766E")}; --accent:${tokenOrDefault(tokens, ["color", "accentSecondary"], "#2563EB")}; --border:${tokenOrDefault(tokens, ["color", "border"], "#D8E0EA")}; --shadow:0 18px 40px rgba(15,23,42,0.10); }
+    * { box-sizing:border-box; } body { margin:0; background:var(--bg); color:var(--text); font:15px/1.5 Inter, ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif; }
+    .shell { width:min(1240px, calc(100vw - 24px)); margin:0 auto; padding:24px 0 48px; }
+    .topbar { position:sticky; top:0; z-index:4; background:color-mix(in srgb, var(--bg) 92%, var(--surface)); border:1px solid var(--border); border-radius:8px; box-shadow:var(--shadow); padding:14px; margin-bottom:18px; }
+    .topline { display:flex; gap:10px; align-items:center; justify-content:space-between; flex-wrap:wrap; }
+    .meta { color:var(--muted); font-size:12px; font-weight:700; }
+    .nav { display:flex; gap:8px; overflow:auto; margin-top:10px; padding-bottom:4px; } .nav a { text-decoration:none; border:1px solid var(--border); border-radius:999px; padding:6px 10px; white-space:nowrap; color:var(--text); background:var(--surface); font-size:12px; font-weight:700; }
+    .prototype-section { background:var(--surface); border:1px solid var(--border); border-radius:8px; box-shadow:var(--shadow); margin:14px 0; } .section-inner { padding:20px; }
+    .eyebrow { margin:0 0 6px; color:var(--primary); font-size:12px; font-weight:800; text-transform:uppercase; } h2,h3,h4,p { margin-top:0; } h2 { margin-bottom:8px; font-size:28px; } .support { color:var(--muted); margin-bottom:10px; }
+    .chip-row { display:flex; gap:8px; flex-wrap:wrap; margin:10px 0 12px; } .chip { border:1px solid var(--border); border-radius:999px; padding:4px 10px; font-size:12px; background:color-mix(in srgb, var(--surface) 92%, var(--bg)); } .chip-state { color:var(--primary); border-color:color-mix(in srgb, var(--primary) 35%, var(--border)); }
+    .panel { border:1px solid var(--border); border-radius:8px; padding:14px; background:color-mix(in srgb, var(--surface) 95%, var(--bg)); }
+    .hf-split { display:grid; grid-template-columns:minmax(220px,0.35fr) minmax(0,1fr); gap:12px; }
+    .hf-feature-grid, .hf-card-grid { display:grid; gap:12px; grid-template-columns:repeat(3, minmax(0, 1fr)); }
+    .product-card, .result-row { border:1px solid var(--border); border-radius:8px; padding:10px; background:var(--surface); }
+    .search-toolbar { display:flex; gap:8px; flex-wrap:wrap; margin-bottom:10px; } input { min-height:40px; border:1px solid var(--border); border-radius:8px; padding:0 12px; min-width:220px; }
+    .button-row { display:flex; flex-wrap:wrap; gap:10px; margin-top:10px; } .btn { display:inline-flex; min-height:40px; align-items:center; justify-content:center; border-radius:8px; padding:0 14px; text-decoration:none; font-weight:800; border:1px solid transparent; } .btn-primary { background:var(--primary); color:#fff; } .btn-secondary { border-color:var(--border); color:var(--text); background:transparent; }
+    .spec-table, .cart-table { width:100%; border-collapse:collapse; font-size:13px; } .spec-table th, .spec-table td, .cart-table th, .cart-table td { border-bottom:1px solid var(--border); text-align:left; padding:8px 6px; }
+    .qty-stepper { display:inline-flex; align-items:center; gap:8px; border:1px solid var(--border); border-radius:8px; padding:4px 8px; }
+    .checkout-stepper { display:flex; gap:10px; list-style:none; padding:0; margin:0 0 12px; } .checkout-stepper li { border:1px solid var(--border); border-radius:999px; padding:4px 10px; font-size:12px; font-weight:700; }
+    .timeline { margin:0; padding-left:16px; } .field-row { border:1px dashed var(--border); border-radius:8px; padding:10px; color:var(--muted); }
+    @media (max-width: 920px) { .hf-split,.hf-feature-grid,.hf-card-grid { grid-template-columns:1fr; } h2 { font-size:24px; } }
+  </style>
+</head>
+<body>
+  <main class="shell style-${styleName}" data-style-preset="${styleName}">
+    <header class="topbar">
+      <div class="topline">
+        <strong>SDTK-DESIGN high-fidelity prototype</strong>
+        <span class="meta">screens=${screens.length} | profile=${escapeHtml(profileSelection || "none")} | mapped references=${mappedRefs}</span>
+      </div>
+      <nav class="nav" aria-label="Screen navigation">
+        ${screens.map((screen) => `<a href="#screen-${escapeHtml(screen.screenId)}">${escapeHtml(screen.title)}</a>`).join("")}
+      </nav>
+    </header>
+    ${sections}
+  </main>
+</body>
+</html>
+`;
 }
 
 function multiScreenPrototypeContent({ style, statePayload }) {
@@ -429,8 +637,16 @@ function runDesignPrototype({ projectPath, force = false, style }) {
     const list = missing.map((target) => target.relativePath).join(", ");
     throw new ValidationError(`Missing required design artifacts: ${list}. Run sdtk-design start --idea "<idea>" first. No project files were changed.`);
   }
-  if (fs.existsSync(paths.prototypeIndexPath) && !force) {
-    throw new ValidationError("docs/design/prototype/index.html already exists. Re-run with --force to replace this managed prototype.");
+  const prototypeMode = resolvePrototypeMode(canUseMultiScreen);
+  const existingManagedPrototype = managedPrototypeTargets(paths, inputContractState, prototypeMode).filter((target) =>
+    fs.existsSync(target.filePath)
+  );
+  if (existingManagedPrototype.length > 0 && !force) {
+    throw new ValidationError(
+      `docs/design/prototype/index.html already exists. Managed prototype output already exists: ${existingManagedPrototype
+        .map((target) => target.relativePath)
+        .join(", ")}. Re-run with --force to replace managed prototype outputs.`
+    );
   }
 
   const designSystemContent = fs.existsSync(paths.designSystemPath) ? fs.readFileSync(paths.designSystemPath, "utf-8") : "";
@@ -448,29 +664,61 @@ function runDesignPrototype({ projectPath, force = false, style }) {
                 : wireframePath(paths, "DASHBOARD.md");
           return fs.readFileSync(filePath, "utf-8");
         });
-  const content = canUseMultiScreen
-    ? multiScreenPrototypeContent({
+  let renderResult = null;
+  let content = null;
+  let bundle = null;
+  if (canUseMultiScreen) {
+    bundle = loadHighFidelityContracts(paths, inputContractState);
+    if (prototypeMode === "multi" && bundle.ready) {
+      renderResult = renderMultiPagePrototype({
+        paths,
+        statePayload: inputContractState,
+        contractBundle: bundle,
+        styleName,
+      });
+    } else if (bundle.ready) {
+      content = highFidelityMultiScreenPrototypeContent({
         style: styleName,
         statePayload: inputContractState,
-      })
-    : prototypeContent({
+        contractBundle: bundle,
+      });
+    } else {
+      content = multiScreenPrototypeContent({
         style: styleName,
-        briefContent: fs.readFileSync(paths.designBriefPath, "utf-8"),
-        screenMapContent: fs.readFileSync(paths.screenMapPath, "utf-8"),
-        designSystemContent,
-        wireframeContents,
+        statePayload: inputContractState,
       });
+    }
+  } else {
+    content = prototypeContent({
+      style: styleName,
+      briefContent: fs.readFileSync(paths.designBriefPath, "utf-8"),
+      screenMapContent: fs.readFileSync(paths.screenMapPath, "utf-8"),
+      designSystemContent,
+      wireframeContents,
+    });
+  }
 
-  fs.mkdirSync(path.dirname(paths.prototypeIndexPath), { recursive: true });
-  fs.writeFileSync(paths.prototypeIndexPath, content, "utf-8");
+  if (!renderResult) {
+    fs.mkdirSync(path.dirname(paths.prototypeIndexPath), { recursive: true });
+    fs.writeFileSync(paths.prototypeIndexPath, content, "utf-8");
+  }
 
   return {
     projectPath: resolvedProjectPath,
     relativePrototypePath: "docs/design/prototype/index.html",
     forced: Boolean(force),
     style: styleName,
-    mode: canUseMultiScreen ? "multi-screen" : "simple",
+    mode: renderResult
+      ? renderResult.mode
+      : canUseMultiScreen
+        ? bundle && bundle.ready
+          ? "high-fidelity-single-file"
+          : "multi-screen"
+        : "simple",
     screenCount: canUseMultiScreen ? inputContractState.screenModel.screens.length : 3,
+    warnings: canUseMultiScreen && bundle ? bundle.warnings : [],
+    generatedPages: renderResult ? renderResult.screenPages : [],
+    densityReport: renderResult ? renderResult.densityReport : null,
   };
 }
 
@@ -486,12 +734,37 @@ function cmdPrototype(args) {
 
   console.log(`[design] Wrote ${result.relativePrototypePath}: ${result.projectPath}`);
   console.log(`[design] Style: ${result.style}`);
-  console.log(`[design] Mode: ${result.mode} (${result.screenCount} screen section(s))`);
+  console.log(`[design] Mode: ${result.mode} (${result.screenCount} screen(s))`);
+  if (result.densityReport) {
+    if (result.densityReport.mode === "bytes") {
+      console.log("[design] Density mode: bytes (deprecated rollback; report shape only, no filler emission)");
+      console.log(
+        `[design] Density: ${result.densityReport.pass ? "PASS" : "FAIL"} total=${result.densityReport.totalBytes}/${result.densityReport.minTotalBytes} bytes`
+      );
+      for (const page of result.densityReport.pages) {
+        console.log(`[design] Density page: ${page.screenId} ${page.byteLength}/${page.minBytes} bytes ${page.pass ? "PASS" : "FAIL"}`);
+      }
+    } else {
+      const aggregate = result.densityReport.aggregate || {};
+      console.log(
+        `[design] Density: ${result.densityReport.pass ? "PASS" : "FAIL"} mode=semantic sections=${aggregate.sectionCount || 0} components=${aggregate.componentCount || 0} dataSlots=${aggregate.dataSlotCount || 0} states=${aggregate.stateCount || 0}`
+      );
+      for (const page of result.densityReport.pages) {
+        const missing = Array.isArray(page.findings) && page.findings.length > 0 ? ` (${page.findings.join("; ")})` : "";
+        console.log(
+          `[design] Density page: ${page.screenId} sections=${page.sectionCount} components=${page.componentCount} dataSlots=${page.dataSlotCount} states=${page.stateCount} ${page.pass ? "PASS" : "FAIL"}${missing}`
+        );
+      }
+    }
+  }
+  if (Array.isArray(result.warnings) && result.warnings.length > 0) {
+    console.log(`[design] Contract fallback: ${result.warnings.join("; ")}`);
+  }
   console.log(`[design] Overwrite: ${result.forced ? "enabled by --force" : "not needed"}`);
   console.log("[design] Prototype mode: static HTML/CSS preview only.");
   console.log("[design] No app code outside docs/design/prototype, server, network, .sdtk/atlas, or SDTK-WIKI output was modified.");
   console.log("[design] Next: sdtk-design review --artifact docs/design/prototype/index.html");
-  return 0;
+  return result.densityReport && result.densityReport.mode !== "bytes" && !result.densityReport.pass ? 1 : 0;
 }
 
 module.exports = {