sdtk-design-kit 0.3.2 → 0.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 `sdtk-design-kit` is the public CLI package for SDTK-DESIGN.
 
-Package version in this source snapshot: `0.3.1`
+Package version in this source snapshot: `0.4.0`
 CLI command: `sdtk-design`
 
 SDTK-DESIGN is a local-first MVP design planner and reviewer. It turns either a rough MVP idea or explicit SDTK-SPEC design artifacts into reviewable design docs, a static prototype, visual review evidence, and an SDTK-CODE handoff.
@@ -60,20 +60,33 @@ sdtk-design screens
 sdtk-design wireframe --screen landing
 sdtk-design system --style minimal-saas
 sdtk-design prototype
+sdtk-design preview
+sdtk-design styles
 sdtk-design review --artifact docs/design/prototype/index.html
 sdtk-design handoff
 sdtk-design status
 ```
 
+`preview` starts a local Preview Studio (browser): it renders the prototype screens, lets you click/shift-click elements to annotate them with a note, and (via the **Tokens** panel) live-preview design-token tweaks on the `:root` CSS variables a screen declares. On "Send to agent" it shows a confirm summary, writes `docs/design/feedback/DESIGN_FEEDBACK_<timestamp>.md` (schema `sdtk.design.feedback.v1`), then a copy-ready instruction to apply it. Run the `design-prototype` skill afterward to apply that scoped feedback. The studio serves the prototype read-only, writes only under `docs/design/feedback/`, and never runs the agent itself.
+
+`styles` opens the same studio focused on the **Style Gallery** — a visual menu of the category-oriented style presets (swatches + type sample + summary). Click a card to copy its `start --style <preset>` command. It needs no prototype (pick a style before generating) and is choose-only: it copies a command, it writes nothing.
+
 Visual style presets:
 
 ```text
-minimal-saas
-premium-dashboard
-bold-founder
-warm-editorial
+minimal-saas        SaaS & Productivity
+premium-dashboard   Dashboard & Data
+bold-founder        Marketing & Launch
+warm-editorial      Editorial & Content
+ecommerce-retail    E-Commerce & Retail
+fintech-trust       Fintech & Data
+editorial-content   Editorial & Content
 ```
 
+Presets are category-oriented: pick the one closest to the product you are
+designing (for example `ecommerce-retail` for a storefront). They are
+unbranded SDTK-original style directions, not copies of any third-party brand.
+
 ## Outputs
 
 Human-facing artifacts are written under `docs/design/`, including:
@@ -85,6 +98,7 @@ DESIGN_SYSTEM.md
 DESIGN_HANDOFF.md
 prototype/index.html
 reviews/DESIGN_REVIEW_YYYYMMDD.md
+feedback/DESIGN_FEEDBACK_YYYYMMDDThhmmss.md
 wireframes/
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdtk-design-kit",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Local-first MVP design planner and reviewer for SDTK workspaces.",
   "bin": {
     "sdtk-design": "bin/sdtk-design.js"

package/skills/design-prototype/SKILL.md

@@ -1,6 +1,17 @@
 ---
 name: design-prototype
 description: Generate high-fidelity standalone HTML prototypes from an SDTK-DESIGN generation manifest, design system, design tokens, and per-screen briefs.
+sdtk:
+  preview:
+    entry: sdtk-design preview
+  parameters:
+    - { name: --accent, type: color }
+    - { name: --primary, type: color }
+    - { name: --surface, type: color }
+    - { name: --text, type: color }
+    - { name: --radius-card, type: spacing, min: 0, max: 24 }
+    - { name: --space-section, type: spacing, min: 8, max: 96 }
+  capabilities_required: [surgical_edit]
 ---
 
 # Design Prototype
@@ -265,6 +276,17 @@ For each screen with multiple `<nav>` elements, verify before output:
 
 If any check fails, fix the CSS before emitting the HTML file.
 
+## Consume design feedback (BK-275)
+
+Use this when the user asks you to apply Preview Studio feedback (the `sdtk-design preview` annotate→send loop).
+
+1. Read the **newest** `docs/design/feedback/DESIGN_FEEDBACK_*.md` (sort by filename timestamp; the name is `DESIGN_FEEDBACK_<YYYYMMDDThhmmss>.md`). Its front-matter is `schema: sdtk.design.feedback.v1`.
+2. Parse the `<attached-preview-comments>` block. Each numbered entry names a `targetKind` (`element`, `pod`, or `token`), and — for element/pod — a `screen` (with its `file:` path), a `selector`, a `stable-id`, a `position`, and a `comment`. Pod entries list `member.N` sub-targets. **Token entries** instead name a `token` (a CSS custom property such as `--accent`), an `oldValue`, a `newValue`, a `scope: global`, and a `comment`.
+3. **Hard scope — obey it literally.** For `element`/`pod` marks, change ONLY the elements named by selector / stable-id / position, in ONLY the named screen file(s) under `docs/design/prototype/screens/`. Do NOT modify sibling screens, parent layout, global CSS, `DESIGN_SYSTEM.md`, or `DESIGN_TOKENS.json` — even if you notice issues there. Surface any out-of-scope observation as a short note in your reply instead of editing it. If a request cannot be satisfied without touching outside the scope, ask the user first.
+   - **`token` marks are the one deliberate exception** to "do not touch tokens": apply the named `token` change globally to its source of truth — update the value in `docs/design/DESIGN_TOKENS.json` if the token maps to a token field there, and/or the `:root { --token: … }` declaration shared by the screens. Change ONLY the named token(s) to the given `newValue`; do not retune other tokens, palettes, or unmarked screens. If a token has no clear source of truth, ask before editing.
+4. When you (re)write a screen, **stamp `data-sdtk-id="<stable id>"` on the stable structural elements you touch** (headers, cards, sections, nav, primary CTAs). This is best-effort and never required, but it lets future Preview Studio marks re-anchor by id instead of by DOM-path.
+5. After editing, keep each screen a complete standalone `<!doctype html>` document under ~1000 lines, exactly as elsewhere in this skill. Do not delete the feedback file.
+
 ## Boundaries
 
 - Brand, palette, typography, spacing, mood, and component direction come only from `docs/design/DESIGN_SYSTEM.md` and `docs/design/DESIGN_TOKENS.json`.

package/src/commands/help.js

@@ -14,6 +14,8 @@ Usage:
   sdtk-design wireframe --screen landing
   sdtk-design system --style minimal-saas
   sdtk-design prototype
+  sdtk-design preview
+  sdtk-design styles
   sdtk-design review --artifact docs/design/prototype/index.html
   sdtk-design handoff
   sdtk-design status
@@ -57,6 +59,8 @@ Command status:
   wireframe             Available.
   system                Available.
   prototype             Available SPEC-driven prototype manifest launcher.
+  preview               Available local Preview Studio (render screens + element-level annotate to feedback).
+  styles                Available visual Style Gallery (browse + copy a "start --style" command).
   handoff               Available.
   review                Available for local markdown and static HTML artifacts.
   start                 Available beginner facade.

package/src/commands/preview.js

@@ -0,0 +1,195 @@
+"use strict";
+
+// BK-275 — `sdtk-design preview`: serve the Preview Studio (rendered prototype
+// screens + element-level annotate→feedback loop) from a local server. Reuses
+// the sdtk-wiki viewer rail pattern; writes nothing except via the studio's
+// /api/feedback endpoint (which lands in docs/design/feedback/).
+
+const fs = require("fs");
+const path = require("path");
+const { spawn } = require("child_process");
+const { parseFlags } = require("../lib/args");
+const { describeDesignPaths, resolveProjectPath } = require("../lib/design-paths");
+const { ValidationError } = require("../lib/errors");
+const { DEFAULT_STYLE, styleCatalog } = require("../lib/style-presets");
+const {
+  startDesignServer,
+  findFreePort,
+  waitForServer,
+} = require("../lib/design-server");
+
+const PREVIEW_FLAG_DEFS = {
+  help: { type: "boolean" },
+  "project-path": { type: "string" },
+  port: { type: "string" },
+  "no-open": { type: "boolean" },
+};
+
+const DEFAULT_HOST = "127.0.0.1";
+const DEFAULT_PORT = 3210;
+const STUDIO_BOOTSTRAP_MARKER = "/*__SDTK_STUDIO_BOOTSTRAP__*/";
+
+function cmdPreviewHelp() {
+  console.log(`SDTK-DESIGN Preview Studio
+
+Usage:
+  sdtk-design preview [--project-path <path>] [--port <n>] [--no-open]
+
+Example:
+  sdtk-design preview
+  sdtk-design preview --port 3210 --no-open
+
+Reads:
+  docs/design/prototype/.manifest.json (run sdtk-design prototype first)
+  docs/design/prototype/screens/*.html (skill-owned screen HTML)
+
+In the studio:
+  Annotate — click/shift-click elements to mark them with a note.
+  Tokens — live-preview design-token tweaks on the :root CSS variables a screen
+    declares (no file is written); "Add changes to queue" turns them into marks.
+  Send to agent — shows a confirm summary, writes the feedback file, then a
+    copy-ready instruction to apply it (the studio never runs the agent itself).
+
+Creates (only via the in-browser "Send to agent" action):
+  docs/design/feedback/DESIGN_FEEDBACK_<timestamp>.md (schema sdtk.design.feedback.v1)
+
+Safety:
+  Local server on 127.0.0.1 only; no external network.
+  Serves the prototype directory read-only; writes only under docs/design/feedback.
+  Never shells out to an agent; token live-preview is in-browser only (no file write).
+  Does not generate or modify screen HTML, the design system, tokens, .sdtk/atlas, or SDTK-WIKI output.
+  In WSL2/Docker, use --no-open and tunnel the printed URL (e.g. cloudflared).`);
+  return 0;
+}
+
+function loadStudioHtml(manifest) {
+  const assetPath = path.join(__dirname, "..", "..", "assets", "design-studio.html");
+  const template = fs.readFileSync(assetPath, "utf-8");
+  // Escape "<" so a screen title containing "</script>" (or "<!--") cannot break
+  // out of the inline <script> the bootstrap is injected into.
+  const json = JSON.stringify({
+    schema: "sdtk.design.feedback.v1",
+    manifest: { screens: (manifest.screens || []).map((s) => ({ screenId: s.screenId, title: s.title || s.screenId, role: s.role || "" })) },
+  }).replace(/</g, "\\u003c");
+  const bootstrap = `window.__SDTK_STUDIO__ = ${json};`;
+  // Use a function replacer so "$" sequences in the JSON are inserted literally
+  // (String.replace honors $& / $` / $' patterns in a string replacement).
+  if (template.includes(STUDIO_BOOTSTRAP_MARKER)) {
+    return template.replace(STUDIO_BOOTSTRAP_MARKER, () => bootstrap);
+  }
+  // Defensive: if the marker is missing, inject before </head> so the studio still boots.
+  return template.replace("</head>", () => `<script>${bootstrap}</script>\n</head>`);
+}
+
+function tryOpenBrowser(url) {
+  const platform = process.platform;
+  const cmd = platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
+  const args = platform === "win32" ? ["/c", "start", "", url] : [url];
+  try {
+    const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+    child.on("error", () => {});
+    child.unref();
+  } catch (_) {
+    // Best-effort only; non-fatal (WSL2/Docker has no browser — use the printed URL).
+  }
+}
+
+async function runDesignPreview({ projectPath, port, noOpen = false }) {
+  const resolvedProjectPath = resolveProjectPath(projectPath || process.cwd());
+  if (!fs.existsSync(resolvedProjectPath) || !fs.statSync(resolvedProjectPath).isDirectory()) {
+    throw new ValidationError(`--project-path is not a valid directory: ${resolvedProjectPath}. No server started.`);
+  }
+  const paths = describeDesignPaths(resolvedProjectPath);
+  if (!fs.existsSync(paths.prototypeManifestPath)) {
+    throw new ValidationError(
+      "Missing docs/design/prototype/.manifest.json. Run sdtk-design prototype first. No server started."
+    );
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(paths.prototypeManifestPath, "utf-8"));
+  } catch (err) {
+    throw new ValidationError(`Could not read prototype manifest: ${err.message}. No server started.`);
+  }
+  const screenCount = Array.isArray(manifest.screens) ? manifest.screens.length : 0;
+
+  const studioHtml = loadStudioHtml(manifest);
+
+  let chosenPort = DEFAULT_PORT;
+  if (port !== undefined && port !== "") {
+    const parsed = Number.parseInt(port, 10);
+    if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535) {
+      throw new ValidationError(`Invalid --port: ${port}. No server started.`);
+    }
+    chosenPort = parsed;
+  } else {
+    chosenPort = await findFreePort(DEFAULT_HOST, DEFAULT_PORT);
+  }
+
+  // The studio reads the design-prototype skill's optional `sdtk:` front-matter
+  // (preview parameters) to filter which token sliders to show. Best-effort:
+  // the kit-bundled SKILL.md if present, else the endpoint returns {}.
+  const skillMetaPath = path.join(
+    __dirname, "..", "..", "skills", "design-prototype", "SKILL.md"
+  );
+
+  const { server, url } = await startDesignServer({
+    host: DEFAULT_HOST,
+    port: chosenPort,
+    projectPath: resolvedProjectPath,
+    studioHtml,
+    skillMetaPath: fs.existsSync(skillMetaPath) ? skillMetaPath : undefined,
+    styles: styleCatalog(),
+    defaultStyle: DEFAULT_STYLE,
+  });
+  await waitForServer(DEFAULT_HOST, chosenPort);
+
+  return { server, url, screenCount, projectPath: resolvedProjectPath, noOpen };
+}
+
+async function cmdPreview(args) {
+  const { flags, positionals } = parseFlags(args || [], PREVIEW_FLAG_DEFS);
+  if (flags.help) return cmdPreviewHelp();
+  if (positionals.length > 0) {
+    throw new ValidationError(
+      `Unsupported preview argument: ${positionals.join(" ")}. Use sdtk-design preview [--project-path <path>] [--port <n>] [--no-open]. No server started.`
+    );
+  }
+
+  const result = await runDesignPreview({
+    projectPath: flags["project-path"],
+    port: flags.port,
+    noOpen: Boolean(flags["no-open"]),
+  });
+
+  console.log(`[design] Preview Studio: ${result.url}`);
+  console.log(`[design] Serving ${result.screenCount} screen(s) from docs/design/prototype/`);
+  console.log("[design] Annotate elements, then \"Send to agent\" writes docs/design/feedback/DESIGN_FEEDBACK_<timestamp>.md");
+  console.log("[design] Then run the design-prototype skill to apply the scoped feedback.");
+  if (result.noOpen) {
+    console.log("[design] --no-open: not launching a browser. Open the URL above (tunnel it on WSL2/Docker).");
+  } else {
+    tryOpenBrowser(result.url);
+  }
+  console.log("[design] Press Ctrl+C to stop the preview server.");
+
+  return new Promise((resolve) => {
+    const shutdown = () => {
+      try { result.server.close(); } catch (_) {}
+      resolve(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+  });
+}
+
+module.exports = {
+  DEFAULT_HOST,
+  DEFAULT_PORT,
+  STUDIO_BOOTSTRAP_MARKER,
+  cmdPreview,
+  cmdPreviewHelp,
+  loadStudioHtml,
+  runDesignPreview,
+  tryOpenBrowser,
+};

package/src/commands/styles.js

@@ -0,0 +1,140 @@
+"use strict";
+
+// BK-277 P-B — `sdtk-design styles`: open the Preview Studio focused on the
+// visual Style Gallery so the user can browse style directions and copy the
+// `start --style <preset>` command BEFORE generating. Unlike `preview`, it does
+// NOT require a prototype manifest (you pick a style first). Read-only / choose-
+// only: it never generates or mutates anything — the gallery just copies a
+// command to the clipboard.
+
+const fs = require("fs");
+const path = require("path");
+const { parseFlags } = require("../lib/args");
+const { describeDesignPaths, resolveProjectPath } = require("../lib/design-paths");
+const { ValidationError } = require("../lib/errors");
+const { DEFAULT_STYLE, styleCatalog } = require("../lib/style-presets");
+const { startDesignServer, findFreePort, waitForServer } = require("../lib/design-server");
+const { DEFAULT_HOST, DEFAULT_PORT, loadStudioHtml, tryOpenBrowser } = require("./preview");
+
+const STYLES_FLAG_DEFS = {
+  help: { type: "boolean" },
+  "project-path": { type: "string" },
+  port: { type: "string" },
+  "no-open": { type: "boolean" },
+};
+
+function cmdStylesHelp() {
+  console.log(`SDTK-DESIGN Style Gallery
+
+Usage:
+  sdtk-design styles [--project-path <path>] [--port <n>] [--no-open]
+
+Example:
+  sdtk-design styles
+  sdtk-design styles --no-open
+
+What it does:
+  Opens the Preview Studio focused on the visual Style Gallery. Browse the
+  category-oriented style presets (e.g. ecommerce-retail) as cards — swatches,
+  a type sample, and a summary — and click one to copy its
+  "sdtk-design start --idea ... --style <preset>" command. Does NOT require a
+  prototype; pick a style before you generate.
+
+Reads:
+  Nothing required. If docs/design/prototype/.manifest.json exists, its screens
+  are also previewable; otherwise only the gallery is shown.
+
+Creates:
+  Nothing. The gallery is choose-only — it copies a command, it does not write.
+
+Safety:
+  Local server on 127.0.0.1 only; no external network. Never shells out.
+  In WSL2/Docker, use --no-open and tunnel the printed URL (e.g. cloudflared).`);
+  return 0;
+}
+
+async function runDesignStyles({ projectPath, port, noOpen = false }) {
+  const resolvedProjectPath = resolveProjectPath(projectPath || process.cwd());
+  if (!fs.existsSync(resolvedProjectPath) || !fs.statSync(resolvedProjectPath).isDirectory()) {
+    throw new ValidationError(`--project-path is not a valid directory: ${resolvedProjectPath}. No server started.`);
+  }
+  const paths = describeDesignPaths(resolvedProjectPath);
+
+  // The gallery works without a prototype; load screens only if a manifest exists.
+  let manifest = { screens: [] };
+  if (fs.existsSync(paths.prototypeManifestPath)) {
+    try {
+      manifest = JSON.parse(fs.readFileSync(paths.prototypeManifestPath, "utf-8"));
+    } catch (_) {
+      manifest = { screens: [] }; // a malformed manifest must not block the gallery
+    }
+  }
+  const studioHtml = loadStudioHtml(manifest);
+
+  let chosenPort = DEFAULT_PORT;
+  if (port !== undefined && port !== "") {
+    const parsed = Number.parseInt(port, 10);
+    if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535) {
+      throw new ValidationError(`Invalid --port: ${port}. No server started.`);
+    }
+    chosenPort = parsed;
+  } else {
+    chosenPort = await findFreePort(DEFAULT_HOST, DEFAULT_PORT);
+  }
+
+  const skillMetaPath = path.join(__dirname, "..", "..", "skills", "design-prototype", "SKILL.md");
+
+  const { server, url } = await startDesignServer({
+    host: DEFAULT_HOST,
+    port: chosenPort,
+    projectPath: resolvedProjectPath,
+    studioHtml,
+    skillMetaPath: fs.existsSync(skillMetaPath) ? skillMetaPath : undefined,
+    styles: styleCatalog(),
+    defaultStyle: DEFAULT_STYLE,
+  });
+  await waitForServer(DEFAULT_HOST, chosenPort);
+
+  const galleryUrl = `${url}#styles`;
+  return { server, url: galleryUrl, styleCount: styleCatalog().length, projectPath: resolvedProjectPath, noOpen };
+}
+
+async function cmdStyles(args) {
+  const { flags, positionals } = parseFlags(args || [], STYLES_FLAG_DEFS);
+  if (flags.help) return cmdStylesHelp();
+  if (positionals.length > 0) {
+    throw new ValidationError(
+      `Unsupported styles argument: ${positionals.join(" ")}. Use sdtk-design styles [--project-path <path>] [--port <n>] [--no-open]. No server started.`
+    );
+  }
+
+  const result = await runDesignStyles({
+    projectPath: flags["project-path"],
+    port: flags.port,
+    noOpen: Boolean(flags["no-open"]),
+  });
+
+  console.log(`[design] Style Gallery: ${result.url}`);
+  console.log(`[design] ${result.styleCount} style preset(s). Click a card to copy its start command.`);
+  if (result.noOpen) {
+    console.log("[design] --no-open: not launching a browser. Open the URL above (tunnel it on WSL2/Docker).");
+  } else {
+    tryOpenBrowser(result.url);
+  }
+  console.log("[design] Press Ctrl+C to stop the server.");
+
+  return new Promise((resolve) => {
+    const shutdown = () => {
+      try { result.server.close(); } catch (_) {}
+      resolve(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+  });
+}
+
+module.exports = {
+  cmdStyles,
+  cmdStylesHelp,
+  runDesignStyles,
+};

package/src/commands/system.js

@@ -118,6 +118,9 @@ function systemContent(briefContent, screenMapContent, style) {
     "- Avoid nested cards and decorative gradient backgrounds.",
     `- Preset density rule: ${preset.density}`,
     "",
+    ...(preset.elevation
+      ? ["## Depth & Elevation", "", `- ${preset.elevation}`, ""]
+      : []),
     "## Table / Dashboard Density",
     "",
     `- ${preset.dashboard}`,
@@ -134,6 +137,9 @@ function systemContent(briefContent, screenMapContent, style) {
     "",
     ...linesForBullets(preset.components),
     "",
+    ...(preset.dosAndDonts && preset.dosAndDonts.length
+      ? ["## Do's and Don'ts", "", ...linesForBullets(preset.dosAndDonts), ""]
+      : []),
     "## Mobile Layout Rules",
     "",
     `- ${preset.mobile}`,

package/src/index.js

@@ -4,6 +4,8 @@ const { cmdBrief } = require("./commands/brief");
 const { cmdHandoff } = require("./commands/handoff");
 const { cmdHelp } = require("./commands/help");
 const { cmdInit } = require("./commands/init");
+const { cmdPreview } = require("./commands/preview");
+const { cmdStyles } = require("./commands/styles");
 const { cmdPrototype } = require("./commands/prototype");
 const { cmdReview } = require("./commands/review");
 const { cmdScreens } = require("./commands/screens");
@@ -71,6 +73,12 @@ async function run(argv) {
   if (command === "prototype") {
     return cmdPrototype(args);
   }
+  if (command === "preview") {
+    return cmdPreview(args);
+  }
+  if (command === "styles") {
+    return cmdStyles(args);
+  }
   if (command === "start") {
     return cmdStart(args);
   }

package/src/lib/design-server.js

@@ -0,0 +1,437 @@
+"use strict";
+
+// BK-275 — SDTK-DESIGN Preview Studio local server.
+// Fork-minimal, dependency-free static server (Node stdlib only). Modeled on the
+// sdtk-wiki viewer runner pattern but stripped to: static-serve the prototype
+// directory, serve the single-file studio at "/" and "/studio", and accept ONE
+// POST endpoint (/api/feedback) that writes a scoped feedback artifact to a
+// local file. It NEVER shells out to an agent (manual-apply boundary, BK-275 D3).
+
+const fs = require("fs");
+const http = require("http");
+const net = require("net");
+const path = require("path");
+const { describeDesignPaths, isPathInsideOrEqual } = require("./design-paths");
+
+const JSON_HEADERS = {
+  "Content-Type": "application/json; charset=utf-8",
+  "Cache-Control": "no-cache",
+};
+
+const MIME_TYPES = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "application/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".ico": "image/x-icon",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".md": "text/plain; charset=utf-8",
+  ".txt": "text/plain; charset=utf-8",
+};
+
+const MAX_BODY_BYTES = 2 * 1024 * 1024; // 2 MB cap for a feedback batch.
+const HEALTH_CHECK_RETRIES = 20;
+const HEALTH_CHECK_INTERVAL_MS = 150;
+
+const HARD_SCOPE_PREAMBLE =
+  "Hard scope: change ONLY the elements identified below by screen / selector / stable-id / position. " +
+  "Do NOT modify sibling screens, parent layout, global CSS, design tokens, or unrelated rules even if you " +
+  "notice issues there — surface those as a follow-up note instead of editing them. If a request cannot be " +
+  "satisfied without touching outside this scope, ask the user before proceeding.";
+
+function isPortOpen(host, port) {
+  return new Promise((resolve) => {
+    const socket = net.createConnection({ host, port, timeout: 500 });
+    socket.once("connect", () => {
+      socket.destroy();
+      resolve(true);
+    });
+    socket.once("error", () => resolve(false));
+    socket.once("timeout", () => {
+      socket.destroy();
+      resolve(false);
+    });
+  });
+}
+
+async function findFreePort(host, startPort) {
+  for (let p = startPort; p < startPort + 20; p += 1) {
+    const busy = await isPortOpen(host, p);
+    if (!busy) return p;
+  }
+  throw new Error(
+    `Could not find a free port in range ${startPort}-${startPort + 19}. ` +
+      "Stop unused preview servers or pass a different --port."
+  );
+}
+
+async function waitForServer(host, port) {
+  for (let i = 0; i < HEALTH_CHECK_RETRIES; i += 1) {
+    const ok = await isPortOpen(host, port);
+    if (ok) return;
+    await new Promise((r) => setTimeout(r, HEALTH_CHECK_INTERVAL_MS));
+  }
+  throw new Error(`SDTK-DESIGN preview server did not start on http://${host}:${port}`);
+}
+
+function feedbackStamp(date = new Date()) {
+  const pad = (n) => String(n).padStart(2, "0");
+  return (
+    `${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}` +
+    `T${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`
+  );
+}
+
+function trimText(value, max) {
+  const text = String(value == null ? "" : value).replace(/\s+/g, " ").trim();
+  return text.length > max ? `${text.slice(0, max - 3)}...` : text;
+}
+
+function normalizePosition(input) {
+  const finite = (v) => (Number.isFinite(v) ? Math.round(v) : 0);
+  const pos = input || {};
+  return { x: finite(pos.x), y: finite(pos.y), width: finite(pos.width), height: finite(pos.height) };
+}
+
+function formatComputedStyle(style) {
+  if (!style || typeof style !== "object") return "";
+  return Object.keys(style)
+    .map((key) => {
+      const value = style[key];
+      return value ? `${key}: ${trimText(value, 80)}` : null;
+    })
+    .filter(Boolean)
+    .join("; ");
+}
+
+function renderTargetLines(target, indent = "") {
+  const t = target || {};
+  const pos = normalizePosition(t.position);
+  const lines = [
+    `${indent}selector: ${trimText(t.selector, 200) || "(none)"}`,
+    `${indent}label: ${trimText(t.label, 120) || "(unlabeled)"}`,
+    `${indent}position: x${pos.x} y${pos.y} ${pos.width}x${pos.height}`,
+    `${indent}currentText: ${trimText(t.currentText, 160) || "(empty)"}`,
+    `${indent}htmlHint: ${trimText(t.htmlHint, 200) || "(none)"}`,
+    `${indent}computedStyle: ${formatComputedStyle(t.computedStyle) || "(none)"}`,
+  ];
+  return lines;
+}
+
+// Pure, exported — the unit-test target. Ports the shape of Open Design's
+// comments.ts#renderCommentAttachmentContext into SDTK screen/file vocabulary.
+function compileFeedbackMarkdown(marks, options = {}) {
+  const list = Array.isArray(marks) ? marks : [];
+  const generatedAt = options.generatedAt || new Date().toISOString();
+  const manifestRelPath = options.manifestRelPath || "docs/design/prototype/.manifest.json";
+
+  const out = [];
+  out.push("---");
+  out.push("schema: sdtk.design.feedback.v1");
+  out.push(`generatedAt: ${generatedAt}`);
+  out.push(`prototypeManifest: ${manifestRelPath}`);
+  out.push(`markCount: ${list.length}`);
+  out.push("---");
+  out.push("");
+  out.push("<attached-preview-comments>");
+  out.push(HARD_SCOPE_PREAMBLE);
+
+  list.forEach((mark, index) => {
+    const rawKind = mark && mark.kind;
+    const kind = rawKind === "pod" ? "pod" : rawKind === "token" ? "token" : "element";
+
+    // Token marks are GLOBAL design-token changes (not anchored to one screen):
+    // render the token name/old/new + scope instead of an element descriptor.
+    if (kind === "token") {
+      const tokenName = trimText(mark && mark.token, 120) || `token-${index + 1}`;
+      out.push("");
+      out.push(`${index + 1}. ${tokenName}`);
+      out.push(`   targetKind: token`);
+      out.push(`   scope: ${trimText(mark && mark.scope, 40) || "global"}`);
+      out.push(`   token: ${tokenName}`);
+      out.push(`   oldValue: ${trimText(mark && mark.oldValue, 120) || "(unknown)"}`);
+      out.push(`   newValue: ${trimText(mark && mark.newValue, 120) || "(unset)"}`);
+      const tNote = trimText(mark && mark.note, 600);
+      out.push(`   comment: ${tNote || "(no note — apply the token change above)"}`);
+      return;
+    }
+
+    const screenId = trimText(mark && mark.screenId, 120) || "(unknown-screen)";
+    const stableId = trimText(mark && (mark.target && mark.target.stableId), 200) ||
+      trimText(mark && mark.stableId, 200) || `mark-${index + 1}`;
+    out.push("");
+    out.push(`${index + 1}. ${stableId}`);
+    out.push(`   targetKind: ${kind}`);
+    out.push(`   screen: ${screenId}  (file: docs/design/prototype/screens/${screenId}.html)`);
+    if (kind === "pod") {
+      const members = Array.isArray(mark.members) ? mark.members : [];
+      out.push(`   memberCount: ${members.length}`);
+      members.slice(0, 12).forEach((member, mi) => {
+        const mStable = trimText(member && member.stableId, 200) || `member-${mi + 1}`;
+        out.push(`   member.${mi + 1}: ${mStable}`);
+        renderTargetLines(member, "     ").forEach((line) => out.push(line));
+      });
+    } else {
+      renderTargetLines(mark && mark.target, "   ").forEach((line) => out.push(line));
+    }
+    const note = trimText(mark && mark.note, 600);
+    out.push(`   comment: ${note || "(no note — see target)"}`);
+  });
+
+  out.push("</attached-preview-comments>");
+  out.push("");
+  return out.join("\n");
+}
+
+// Parse the optional `sdtk:` block from a SKILL.md YAML front-matter. Tolerant
+// by contract: returns {} on anything unexpected (never throws). Supports the
+// documented shape only — preview.entry, parameters (inline-object list items),
+// capabilities_required (inline [list]). A full YAML parser is intentionally
+// NOT a dependency.
+function parseInlineObject(line) {
+  // "- { name: accent, type: color, min: 0, max: 24 }" -> { name, type, min, max }
+  // Strips from the last "}" so a trailing YAML comment ("} # note") is ignored.
+  // NOTE: values must be comma-free scalars (the schema only uses name/type/min/max).
+  const body = line.replace(/^\s*-\s*\{/, "").replace(/\}[^}]*$/, "");
+  const obj = {};
+  body.split(",").forEach((pair) => {
+    const idx = pair.indexOf(":");
+    if (idx === -1) return;
+    const key = pair.slice(0, idx).trim();
+    let value = pair.slice(idx + 1).trim().replace(/^['"]|['"]$/g, "");
+    if (!key) return;
+    if ((key === "min" || key === "max") && value !== "" && Number.isFinite(Number(value))) {
+      value = Number(value);
+    }
+    obj[key] = value;
+  });
+  return obj;
+}
+
+function parseSkillMeta(skillMdText) {
+  try {
+    // Strip a leading UTF-8 BOM (editors add it; fs 'utf-8' does not remove it).
+    const text = String(skillMdText || "").replace(/^\uFEFF/, "");
+    const fm = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+    if (!fm) return {};
+    const lines = fm[1].split(/\r?\n/);
+    const startIdx = lines.findIndex((l) => /^sdtk:\s*$/.test(l));
+    if (startIdx === -1) return {};
+    const block = [];
+    for (let i = startIdx + 1; i < lines.length; i += 1) {
+      const line = lines[i];
+      if (line.trim() === "") continue;
+      if (/^\s/.test(line)) block.push(line);
+      else break; // dedented back to top level → end of sdtk block
+    }
+    const meta = {};
+    const parameters = [];
+    let inParameters = false;
+    for (const line of block) {
+      const trimmed = line.trim();
+      const indent = line.length - line.replace(/^\s+/, "").length;
+      if (/^preview:\s*$/.test(trimmed)) { inParameters = false; continue; }
+      const entryMatch = /^entry:\s*(.+)$/.exec(trimmed);
+      if (entryMatch) {
+        meta.preview = meta.preview || {};
+        meta.preview.entry = entryMatch[1].trim().replace(/^['"]|['"]$/g, "");
+        continue;
+      }
+      if (/^parameters:\s*$/.test(trimmed)) { inParameters = true; continue; }
+      const capsMatch = /^capabilities_required:\s*\[(.*)\]\s*$/.exec(trimmed);
+      if (capsMatch) {
+        meta.capabilitiesRequired = capsMatch[1]
+          .split(",").map((c) => c.trim().replace(/^['"]|['"]$/g, "")).filter(Boolean);
+        inParameters = false;
+        continue;
+      }
+      if (inParameters && /^-\s*\{.*\}\s*(#.*)?$/.test(trimmed) && indent >= 4) {
+        const obj = parseInlineObject(line);
+        if (obj.name) parameters.push(obj);
+        continue;
+      }
+      if (trimmed && !/^-/.test(trimmed) && indent <= 2) inParameters = false;
+    }
+    if (parameters.length) meta.parameters = parameters;
+    return meta;
+  } catch (_) {
+    return {};
+  }
+}
+
+function serveStatic(req, res, paths) {
+  let urlPath;
+  try {
+    urlPath = decodeURIComponent((req.url || "/").split("?")[0]);
+  } catch (_) {
+    // Malformed percent-encoding must not crash the server.
+    res.writeHead(400, { "Content-Type": "text/plain; charset=utf-8" });
+    res.end("Bad request");
+    return;
+  }
+  const rel = urlPath.replace(/^\/+/, "");
+  const candidate = path.join(paths.prototypePath, rel);
+  if (!isPathInsideOrEqual(candidate, paths.prototypePath)) {
+    res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+    res.end("Not found");
+    return;
+  }
+  fs.stat(candidate, (err, stat) => {
+    if (err || !stat.isFile()) {
+      res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+      res.end("Not found");
+      return;
+    }
+    const ext = path.extname(candidate).toLowerCase();
+    res.writeHead(200, { "Content-Type": MIME_TYPES[ext] || "application/octet-stream", "Cache-Control": "no-cache" });
+    fs.createReadStream(candidate).pipe(res);
+  });
+}
+
+function handleFeedbackPost(req, res, paths) {
+  let body = "";
+  let aborted = false;
+  req.on("data", (chunk) => {
+    if (aborted) return;
+    body += chunk;
+    if (body.length > MAX_BODY_BYTES) {
+      aborted = true;
+      res.writeHead(413, JSON_HEADERS);
+      res.end(JSON.stringify({ ok: false, error: "Feedback body too large." }));
+      req.destroy();
+    }
+  });
+  req.on("end", () => {
+    if (aborted) return;
+    let payload;
+    try {
+      payload = body ? JSON.parse(body) : {};
+    } catch (_) {
+      res.writeHead(400, JSON_HEADERS);
+      res.end(JSON.stringify({ ok: false, error: "Invalid JSON body." }));
+      return;
+    }
+    const marks = Array.isArray(payload.marks) ? payload.marks : [];
+    if (marks.length === 0) {
+      res.writeHead(400, JSON_HEADERS);
+      res.end(JSON.stringify({ ok: false, error: "No marks to send." }));
+      return;
+    }
+    const generatedAt = new Date();
+    const markdown = compileFeedbackMarkdown(marks, {
+      generatedAt: generatedAt.toISOString(),
+      manifestRelPath: "docs/design/prototype/.manifest.json",
+    });
+    const feedbackDir = path.join(paths.designDocsPath, "feedback");
+    const relPath = `docs/design/feedback/DESIGN_FEEDBACK_${feedbackStamp(generatedAt)}.md`;
+    const outPath = path.join(paths.projectPath, relPath);
+    if (!isPathInsideOrEqual(outPath, paths.designDocsPath)) {
+      res.writeHead(400, JSON_HEADERS);
+      res.end(JSON.stringify({ ok: false, error: "Refusing to write outside docs/design." }));
+      return;
+    }
+    try {
+      fs.mkdirSync(feedbackDir, { recursive: true });
+      fs.writeFileSync(outPath, `${markdown}`, "utf-8");
+    } catch (err) {
+      res.writeHead(500, JSON_HEADERS);
+      res.end(JSON.stringify({ ok: false, error: `Could not write feedback: ${err.message}` }));
+      return;
+    }
+    res.writeHead(200, JSON_HEADERS);
+    res.end(JSON.stringify({ ok: true, path: relPath }));
+  });
+}
+
+function loadSkillMeta(skillMetaPath) {
+  if (!skillMetaPath) return {};
+  try {
+    return parseSkillMeta(fs.readFileSync(skillMetaPath, "utf-8"));
+  } catch (_) {
+    // Missing/unreadable SKILL.md must not break the studio — fall back to {}.
+    return {};
+  }
+}
+
+function startDesignServer({ host = "127.0.0.1", port, projectPath, studioHtml, skillMetaPath, styles, defaultStyle }) {
+  const paths = describeDesignPaths(projectPath);
+  const styleCatalog = Array.isArray(styles) ? styles : [];
+  return new Promise((resolve, reject) => {
+    const server = http.createServer((req, res) => {
+      const method = (req.method || "GET").toUpperCase();
+      const pathOnly = (req.url || "/").split("?")[0];
+
+      if (pathOnly === "/" || pathOnly === "/studio" || pathOnly === "/studio/") {
+        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-cache" });
+        res.end(studioHtml);
+        return;
+      }
+      if (pathOnly === "/api/health") {
+        res.writeHead(200, JSON_HEADERS);
+        res.end(JSON.stringify({ ok: true, projectPath: paths.projectPath }));
+        return;
+      }
+      if (pathOnly === "/api/styles") {
+        if (method !== "GET") {
+          res.writeHead(405, JSON_HEADERS);
+          res.end(JSON.stringify({ ok: false, error: "Method not allowed." }));
+          return;
+        }
+        // Read-only style catalog for the visual gallery (display-safe fields only).
+        res.writeHead(200, JSON_HEADERS);
+        res.end(JSON.stringify({
+          ok: true,
+          defaultStyle: defaultStyle || (styleCatalog.length ? styleCatalog[0].name : null),
+          styles: styleCatalog,
+        }));
+        return;
+      }
+      if (pathOnly === "/api/skill-meta") {
+        if (method !== "GET") {
+          res.writeHead(405, JSON_HEADERS);
+          res.end(JSON.stringify({ ok: false, error: "Method not allowed." }));
+          return;
+        }
+        // Read-only; tolerant — never 500 on a malformed/absent SKILL.md.
+        res.writeHead(200, JSON_HEADERS);
+        res.end(JSON.stringify({ ok: true, sdtk: loadSkillMeta(skillMetaPath) }));
+        return;
+      }
+      if (pathOnly === "/api/feedback") {
+        if (method !== "POST") {
+          res.writeHead(405, JSON_HEADERS);
+          res.end(JSON.stringify({ ok: false, error: "Method not allowed." }));
+          return;
+        }
+        handleFeedbackPost(req, res, paths);
+        return;
+      }
+      serveStatic(req, res, paths);
+    });
+
+    server.on("error", reject);
+    server.listen(port, host, () => {
+      resolve({ server, port, url: `http://${host}:${port}/` });
+    });
+  });
+}
+
+module.exports = {
+  HARD_SCOPE_PREAMBLE,
+  MAX_BODY_BYTES,
+  compileFeedbackMarkdown,
+  feedbackStamp,
+  findFreePort,
+  isPortOpen,
+  parseSkillMeta,
+  startDesignServer,
+  waitForServer,
+};

package/src/lib/style-presets.js

@@ -7,6 +7,7 @@ const DEFAULT_STYLE = "minimal-saas";
 const STYLE_PRESETS = {
   "minimal-saas": {
     label: "Minimal SaaS",
+    category: "SaaS & Productivity",
     summary: "Clean solo-founder SaaS default with practical hierarchy, quiet surfaces, and low-decoration components.",
     typography: [
       "Use system UI, Segoe UI, Roboto, Helvetica, Arial, sans-serif.",
@@ -36,6 +37,7 @@ const STYLE_PRESETS = {
   },
   "premium-dashboard": {
     label: "Premium Dashboard",
+    category: "Dashboard & Data",
     summary: "Dashboard-first MVP style with stronger density, metrics, cards, tables, and command surfaces.",
     typography: [
       "Use Inter-like system sans with tabular numerals for metrics.",
@@ -65,6 +67,7 @@ const STYLE_PRESETS = {
   },
   "bold-founder": {
     label: "Bold Founder",
+    category: "Marketing & Launch",
     summary: "High-contrast launch style for marketing-heavy MVPs with decisive type and CTA hierarchy.",
     typography: [
       "Use a heavy display face fallback stack: Impact, Arial Black, Inter, system-ui.",
@@ -94,6 +97,7 @@ const STYLE_PRESETS = {
   },
   "warm-editorial": {
     label: "Warm Editorial",
+    category: "Editorial & Content",
     summary: "Softer consultant/service-product style with restrained serif-led hierarchy and warm surfaces.",
     typography: [
       "Use Georgia, Charter, or Times New Roman for display; use system sans for UI labels and forms.",
@@ -121,6 +125,122 @@ const STYLE_PRESETS = {
       "Tag row: forest-accent labels with readable text.",
     ],
   },
+  "ecommerce-retail": {
+    label: "E-Commerce Retail",
+    category: "E-Commerce & Retail",
+    summary: "Product-forward storefront style with photography-led cards, a single confident accent for CTA and price, and a sticky cart/checkout rail.",
+    typography: [
+      "Use a clean geometric/grotesque system sans: system-ui, Segoe UI, Roboto, Helvetica, Arial, sans-serif.",
+      "Use a 36/26/20/15/13px hierarchy; keep product names at 15-16px medium weight and prices at 18-20px bold.",
+      "Use tabular numerals for prices and quantities; keep letter spacing at 0 except optional 0.06em uppercase micro-labels for badges (SALE, NEW).",
+    ],
+    colors: [
+      "`color-bg`: #FFFFFF for the product canvas; let photography carry the visual weight.",
+      "`color-surface`: #FFFFFF for product cards on a #F6F7F9 alternating page tint.",
+      "`color-text`: #1A1D21 for product names, prices, and primary copy.",
+      "`color-muted`: #6B7280 for secondary metadata, shipping notes, and review counts.",
+      "`color-primary`: #4338CA indigo for the add-to-cart / checkout CTA and active filters.",
+      "`color-accent`: #E8590C pumpkin for price emphasis, sale tags, and the wishlist heart.",
+      "`color-success`: #1B873F in-stock, `color-warning`: #B7791F low-stock, `color-danger`: #C2330E out-of-stock or error.",
+      "`color-border`: #E6E8EB for quiet card edges, dividers, and input outlines.",
+    ],
+    surface: "Use white product cards with 14-20px corner radius on a soft page tint; let product imagery sit edge-to-edge with gentle rounding. Prefer hairline borders over heavy shadows; reserve a soft lift only for the sticky cart panel.",
+    density: "Use a responsive product grid (2-4 columns) with 16-20px gutters and generous whitespace around hero and category bands; keep cart/line-item rows compact at 12-14px.",
+    cta: "One dominant filled primary CTA per surface (Add to cart / Checkout); secondary actions (wishlist, compare) stay outlined or icon-only. Keep price and CTA visually paired.",
+    dashboard: "For seller/order views, use order-status pills with text, a compact line-item table, and clear fulfillment states; do not borrow heavy analytics chrome onto the storefront.",
+    mobile: "Collapse the grid to two then one column under 760px; pin the add-to-cart / total bar to the bottom on product and cart screens; keep tap targets at least 44px.",
+    accessibility: "Never signal stock or price state by color alone — pair with text and icons; maintain 4.5:1 contrast on price and CTA text; keep focus rings visible on cards, filters, and quantity steppers.",
+    elevation: "Keep most surfaces flat with hairline borders; use a single soft shadow (0 8px 24px rgba(16,24,40,0.10)) only for the sticky cart/checkout rail and modal overlays; product cards lift only on hover, not at rest.",
+    dosAndDonts: [
+      "Do let product photography be the hero; keep chrome quiet around it.",
+      "Do pair price and the add-to-cart CTA so the buying decision is one glance.",
+      "Don't use more than one accent color; reserve the accent for price and sale signals.",
+      "Don't stack nested cards or decorative gradients that compete with product imagery.",
+    ],
+    components: [
+      "Product card: image, name, price, rating/review count, add-to-cart.",
+      "Cart line item: thumbnail, name, variant, quantity stepper, line total, remove.",
+      "Sticky order summary: subtotal, shipping, total, primary checkout CTA.",
+      "Filter rail: category, price range, in-stock toggle with applied-filter chips.",
+    ],
+  },
+  "fintech-trust": {
+    label: "Fintech Trust",
+    category: "Fintech & Data",
+    summary: "Trust-forward financial style with dense data surfaces, tabular numerals, a restrained palette, and strong status semantics.",
+    typography: [
+      "Use a precise system sans with tabular numerals enabled everywhere numbers appear: system-ui, Inter, Segoe UI, Roboto, sans-serif.",
+      "Use a 30/22/18/14/12px hierarchy with heavier labels and compact metadata; align figures on the decimal.",
+      "Reserve monospace for account IDs, reference numbers, and timestamps only.",
+    ],
+    colors: [
+      "`color-bg`: #F4F6FB for the application background.",
+      "`color-surface`: #FFFFFF for balance cards, statements, and tables.",
+      "`color-text`: #0F172A for balances, labels, and primary copy.",
+      "`color-muted`: #5A6678 for secondary metadata and helper text.",
+      "`color-primary`: #1E3A8A deep navy for primary actions and active states.",
+      "`color-accent`: #0E7C66 teal for positive balance highlights and one chart series.",
+      "`color-success`: #1B873F credit/up, `color-warning`: #B7791F pending/review, `color-danger`: #C2330E debit/down or error.",
+      "`color-border`: #DCE2EC for table rules, card edges, and input outlines.",
+    ],
+    surface: "Use structured white cards and tables with crisp 8-10px radius on a cool page tint; keep rules and dividers hairline. Money and status must read instantly; avoid decorative surfaces that obscure figures.",
+    density: "Use high density: 10-12px table row gaps, aligned numeric columns with right-aligned figures, and scannable statement rows; keep summary cards calm with one headline figure each.",
+    cta: "Primary CTA should be compact, explicit, and reassuring (Transfer, Confirm payment); destructive or irreversible actions require a clear confirm step.",
+    dashboard: "Lead with 3-4 balance/KPI cards (tabular figures + trend), then a transactions table with status pills; keep gains/losses signed and color-paired with text.",
+    mobile: "Stack balance cards to one column; keep transaction rows readable without horizontal scroll; pin the primary action for the active account.",
+    accessibility: "Never signal up/down or credit/debit by color alone — pair with sign, arrow, and text; maintain 4.5:1 contrast on figures; keep focus rings visible on dense controls and table actions.",
+    elevation: "Keep surfaces flat and trustworthy with hairline borders; use a single restrained shadow (0 1px 2px rgba(15,23,42,0.08)) for cards and a slightly stronger lift only for modals/confirm dialogs; avoid playful depth.",
+    dosAndDonts: [
+      "Do use tabular numerals and align figures so balances are scannable.",
+      "Do pair every up/down or credit/debit signal with a sign, arrow, and text.",
+      "Don't decorate money surfaces with gradients or imagery that reduce legibility.",
+      "Don't hide the active account's primary action below the fold on mobile.",
+    ],
+    components: [
+      "Balance card: account label, balance (tabular), signed trend, last-updated.",
+      "Transaction row: date, payee, category, signed amount, status pill.",
+      "Confirm dialog: amount, recipient, fee, irreversible-action confirm.",
+      "Status pill: text label plus color (cleared, pending, failed).",
+    ],
+  },
+  "editorial-content": {
+    label: "Editorial Content",
+    category: "Editorial & Content",
+    summary: "Reading-first content style with a narrow measure, serif-led hierarchy, warm surfaces, and minimal chrome for articles, blogs, and marketplace listings.",
+    typography: [
+      "Use a readable serif for headings and long-form body (Georgia, Charter, 'Iowan Old Style', Times New Roman, serif); use system sans for UI labels, nav, and forms.",
+      "Use a 44/30/22/18/14px hierarchy with generous line-height (1.6-1.7) for body and a comfortable 66-72ch reading measure.",
+      "Use serif for narrative and pull quotes; keep captions, bylines, and metadata in small sans at 13-14px.",
+    ],
+    colors: [
+      "`color-bg`: #FBF9F5 warm paper background.",
+      "`color-surface`: #FFFFFF for elevated cards and media frames.",
+      "`color-text`: #201C17 near-black ink for body and headings.",
+      "`color-muted`: #857D72 for bylines, dates, and secondary metadata.",
+      "`color-primary`: #9A3412 burnt-sienna for primary links, CTAs, and active nav.",
+      "`color-accent`: #2F5B4F forest for tags, section markers, and dividers.",
+      "`color-border`: rgba(32,28,23,0.12) for restrained rules and card edges.",
+    ],
+    surface: "Use warm paper backgrounds with a single centered reading column; frame media edge-to-edge with gentle rounding. Prefer rules and whitespace over cards; reserve cards for related-content and listing grids.",
+    density: "Use generous vertical rhythm for article body (paragraph spacing ~1em, section spacing ~2.5em); use a calm 2-3 column grid with 24px gutters for listing/related content.",
+    cta: "Primary CTA (Subscribe, Read more, Contact seller) uses the sienna link/fill; keep it understated and inline with the reading flow rather than dominant.",
+    dashboard: "For author/listing management, use readable rows and notes-first cards rather than heavy analytics chrome; surface publish status and last-edit clearly.",
+    mobile: "Keep the reading measure narrow and centered; stack listing cards to one column; reduce section spacing by about one third while preserving body line-height.",
+    accessibility: "Warm palettes still need contrast checks — keep body text at 4.5:1 on paper; never rely on sienna/forest color alone for links or tags, underline or label them; keep focus visible.",
+    elevation: "Stay almost flat: use hairline rules and whitespace for structure; reserve a soft shadow (0 6px 20px rgba(32,28,23,0.08)) only for related-content cards and image lightboxes.",
+    dosAndDonts: [
+      "Do hold a 66-72ch measure and generous line-height for long-form readability.",
+      "Do use serif for narrative and sans for UI labels and forms.",
+      "Don't widen body text to full-bleed or crowd paragraphs together.",
+      "Don't signal links by color alone on warm surfaces — underline or label them.",
+    ],
+    components: [
+      "Article hero: serif headline, byline, date, lead image with caption.",
+      "Reading body: 66-72ch measure, pull quotes, inline media with captions.",
+      "Listing card: media, title, short excerpt, tag row, price or read-time.",
+      "Tag row: forest-accent labels with readable text and clear focus.",
+    ],
+  },
 };
 
 function availableStyleNames() {
@@ -141,10 +261,50 @@ function getStylePreset(style) {
   return STYLE_PRESETS[resolveStyleName(style)];
 }
 
+// Extract the 6-digit hex swatches a preset declares, in author order, so a
+// visual gallery can render a color row without re-parsing the prose. Captures
+// every hex token across all `colors[]` lines (a single line may declare more
+// than one role, e.g. success/warning/danger), skips rgba()/named values, and
+// de-duplicates while preserving first-seen order.
+function paletteSwatches(preset) {
+  const swatches = [];
+  const seen = new Set();
+  for (const line of preset.colors || []) {
+    const matches = line.match(/#[0-9a-fA-F]{6}\b/g) || [];
+    for (const hex of matches) {
+      const value = hex.toUpperCase();
+      if (!seen.has(value)) {
+        seen.add(value);
+        swatches.push(value);
+      }
+    }
+  }
+  return swatches;
+}
+
+// Read-only serialization of the preset catalog for the (future) Style Gallery
+// endpoint. Carries only display-safe fields — no file paths, no secrets.
+function styleCatalog() {
+  return availableStyleNames().map((name) => {
+    const preset = STYLE_PRESETS[name];
+    return {
+      name,
+      label: preset.label,
+      category: preset.category || "General",
+      summary: preset.summary,
+      swatches: paletteSwatches(preset),
+      typographySample: (preset.typography && preset.typography[0]) || "",
+      component: (preset.components && preset.components[0]) || "",
+    };
+  });
+}
+
 module.exports = {
   DEFAULT_STYLE,
   STYLE_PRESETS,
   availableStyleNames,
   getStylePreset,
   resolveStyleName,
+  paletteSwatches,
+  styleCatalog,
 };