@flashdsm/genome 0.2.0 → 0.3.0

package/dist/index.js

@@ -2,6 +2,7 @@
 import {
   GENOME_CONFIG_FILENAME,
   GenomeConfigSchema,
+  GenomeOutputsSchema,
   LEGACY_CONFIG_FILENAME,
   TokenCategorySchema,
   TokenSchema,
@@ -13,7 +14,7 @@ import {
   parseCategoryInput,
   parseFlashAtomicDocument,
   resolveTokenFilePath
-} from "./chunk-PHEWKKKF.js";
+} from "./chunk-YA26VZWF.js";
 
 // src/index.ts
 import { resolve as resolve13 } from "path";
@@ -24,7 +25,7 @@ import {
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z as z3 } from "zod";
 import { readFileSync, realpathSync } from "fs";
-import { readFile as readFile16 } from "fs/promises";
+import { readFile as readFile17 } from "fs/promises";
 
 // ../core/dist/change-plan.js
 import { z } from "zod";
@@ -509,7 +510,11 @@ function classify(name, value) {
   if (/^#[0-9a-fA-F]{3,8}$/.test(v))
     return { category: "colors", type: "color" };
   if (/^-?\d*\.?\d+(px|rem|em|%)$/.test(v)) {
-    return /radius/i.test(name) ? { category: "radius", type: "radius" } : { category: "spacing", type: "size" };
+    if (/radius/i.test(name))
+      return { category: "radius", type: "radius" };
+    if (/(?:^|-)(?:text|fs)-(?:\d?x+s|sm|md|base|lg|\d?x+l|\d{1,3}|display|hero|title|caption)$/i.test(name))
+      return { category: "typography", type: "font" };
+    return { category: "spacing", type: "size" };
   }
   return null;
 }
@@ -628,9 +633,29 @@ function projectNameFromPackageJson(text) {
     return null;
   }
 }
+async function pulledFiles(source) {
+  const clean2 = (p) => p.replace(/\\/g, "/").replace(/^\.\//, "");
+  const byPath = new Map(source.paths.map((p) => [clean2(p), p]));
+  const configPath = byPath.get(GENOME_CONFIG_FILENAME);
+  if (!configPath)
+    return () => false;
+  try {
+    const config = JSON.parse(await source.read(configPath) ?? "");
+    const { genomeDir } = GenomeOutputsSchema.parse(config?.outputs ?? {});
+    const lockPath = byPath.get(`${clean2(genomeDir).replace(/\/?$/, "/")}genome.lock`);
+    if (!lockPath)
+      return () => false;
+    const lock = JSON.parse(await source.read(lockPath) ?? "");
+    const files = new Set((Array.isArray(lock?.files) ? lock.files : []).filter((f) => typeof f === "string").map(clean2));
+    return (posix2) => files.has(clean2(posix2));
+  } catch {
+    return () => false;
+  }
+}
 async function buildWorkspaceScan(source) {
   const root = source.workspaceRoot;
-  const paths = source.paths;
+  const pulled = await pulledFiles(source);
+  const paths = source.paths.filter((p) => !pulled(p));
   const tokens = {};
   const files = [];
   const fileSources = [];
@@ -2680,7 +2705,7 @@ function tokenHashes(tokens) {
 }
 
 // ../codegen/dist/from-atomic-document.js
-function atomicTokenToDesign(t, value = t.value) {
+function atomicTokenToDesign(t, value = t.value, ref = t.referencedTokenId) {
   return {
     name: t.name,
     value,
@@ -2688,7 +2713,7 @@ function atomicTokenToDesign(t, value = t.value) {
     category: t.category,
     ...t.description ? { description: t.description } : {},
     ...t.layer ? { layer: t.layer } : {},
-    ...t.referencedTokenId ? { referencedTokenId: t.referencedTokenId } : {},
+    ...ref ? { referencedTokenId: ref } : {},
     ...t.colorGroup ? { colorGroup: t.colorGroup } : {},
     ...t.fallbackValue ? { fallbackValue: t.fallbackValue } : {},
     ...t.metadata ? { metadata: t.metadata } : {}
@@ -2702,6 +2727,10 @@ function atomicThemeValues(t) {
     return [t.value, t.value];
   return [dark ? String(dark) : null, light ? String(light) : null];
 }
+function atomicThemeRef(t, theme) {
+  const ref = t.metadata?.[`${theme}Ref`];
+  return typeof ref === "string" && ref ? ref : t.referencedTokenId;
+}
 function fromAtomicDocument(doc) {
   const f = doc.foundations;
   const colors = [];
@@ -2713,9 +2742,9 @@ function fromAtomicDocument(doc) {
   for (const t of palette) {
     const [dark, light] = atomicThemeValues(t);
     if (dark !== null)
-      colors.push(atomicTokenToDesign(t, dark));
+      colors.push(atomicTokenToDesign(t, dark, atomicThemeRef(t, "dark")));
     if (light !== null)
-      lightColors.push(atomicTokenToDesign(t, light));
+      lightColors.push(atomicTokenToDesign(t, light, atomicThemeRef(t, "light")));
   }
   return {
     colors,
@@ -2881,6 +2910,52 @@ ${FLASH_BLOCK_END}
 `;
 }
 
+// ../codegen/dist/shared/codeNames.js
+function keepInTheme(tokens, codeNames) {
+  let out = tokens;
+  for (const [code, role] of Object.entries(codeNames)) {
+    if (!code || !role || code === role)
+      continue;
+    const target = out.find((t) => t.name === role);
+    if (!target)
+      continue;
+    const held = out.find((t) => t.name === code);
+    const kept = {
+      ...held ?? { type: target.type, category: target.category },
+      name: code,
+      value: "",
+      layer: "alias",
+      referencedTokenId: role,
+      description: held?.description ?? `From your code: ${code}`
+    };
+    out = out.map((t) => {
+      if (t === held)
+        return kept;
+      if (t.referencedTokenId !== code)
+        return t;
+      return held?.referencedTokenId ? { ...t, referencedTokenId: held.referencedTokenId } : {
+        ...t,
+        layer: "primitive",
+        referencedTokenId: void 0,
+        value: held?.value ?? t.value
+      };
+    });
+    if (!held)
+      out = [...out, kept];
+  }
+  return out;
+}
+function keepCodeNames(tokens, codeNames, cssPrefix) {
+  if (!cssPrefix || !codeNames || Object.keys(codeNames).length === 0) {
+    return tokens;
+  }
+  return {
+    ...tokens,
+    colors: keepInTheme(tokens.colors, codeNames),
+    lightColors: keepInTheme(tokens.lightColors, codeNames)
+  };
+}
+
 // ../codegen/dist/shared/cssPrefix.js
 function normalizeCssPrefix(raw) {
   const cleaned = (raw ?? "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
@@ -3744,6 +3819,9 @@ function pruneUnusedMotionTokens(tokens, components = []) {
 }
 
 // ../codegen/dist/repo-token-diff.js
+function repoEditValue(edit) {
+  return edit.reference ? `var(--${tokensToCssVarName(edit.reference)})` : edit.after;
+}
 var GROUP_SECTIONS = {
   spacing: "spacing",
   typography: "typography",
@@ -3822,22 +3900,116 @@ function diffRepoTokens(doc, repoDtcg, responsive) {
     });
     return { edits, findings };
   }
-  const compare = (path, section, name, before, after, theme) => {
-    if (before === void 0 || after === void 0)
+  const palette = singleThemePalette(tokens);
+  const defaultTheme = palette === tokens.colors ? "dark" : "light";
+  const names = {
+    dark: new Map(tokens.colors.map((t) => [tokensToCssVarName(t.name), t])),
+    light: new Map(tokens.lightColors.map((t) => [tokensToCssVarName(t.name), t]))
+  };
+  const hasTheme = {
+    dark: tokens.colors.length > 0,
+    light: tokens.lightColors.length > 0
+  };
+  const addColour = (path, name, theme, value) => {
+    if (!hasTheme[theme]) {
+      findings.push({
+        path,
+        code: "missing-theme",
+        after: value,
+        reason: `The file gives a ${theme} value, and this design system has no ${theme} theme yet. Add the theme in Flash, then push again.`
+      });
       return;
-    if (same(before, after))
+    }
+    push({
+      path,
+      section: BUNDLE_SECTION[theme === "dark" ? "colors" : "lightColors"],
+      name,
+      theme,
+      kind: "add",
+      before: "",
+      after: value
+    });
+  };
+  const add = (group, key, entry) => {
+    if (!entry || typeof entry !== "object")
+      return false;
+    if (group === "color") {
+      const modes = modesOf(entry);
+      const given = ["dark", "light"].filter((theme) => typeof modes?.[theme] === "string");
+      if (given.length) {
+        for (const theme of given) {
+          addColour(`color.${key}`, key, theme, String(modes[theme]));
+        }
+        return true;
+      }
+      if (typeof entry.$value !== "string")
+        return false;
+      const themes = ["dark", "light"].filter((t) => hasTheme[t]);
+      for (const theme of themes.length ? themes : [defaultTheme]) {
+        addColour(`color.${key}`, key, theme, entry.$value);
+      }
+      return true;
+    }
+    const field = GROUP_SECTIONS[group];
+    if (!field || typeof entry.$value !== "string" || ladderOfEntry(entry)) {
+      return false;
+    }
+    push({
+      path: `${group}.${key}`,
+      section: BUNDLE_SECTION[field],
+      name: key,
+      kind: "add",
+      before: "",
+      after: entry.$value
+    });
+    return true;
+  };
+  const referenced = (value) => {
+    const inner = value.trim().slice(1, -1);
+    const dot = inner.indexOf(".");
+    if (dot < 0)
+      return void 0;
+    const group = inner.slice(0, dot);
+    const key = inner.slice(dot + 1);
+    if (group === "color") {
+      const held = names.dark.get(key) ?? names.light.get(key);
+      if (held)
+        return held.name;
+    } else if (GROUP_SECTIONS[group]) {
+      const held = tokens[GROUP_SECTIONS[group]].find((t) => groupKey(group, t.name) === key);
+      if (held)
+        return held.name;
+    } else {
+      return void 0;
+    }
+    return repo[group]?.[key] ? key : void 0;
+  };
+  const push = (edit) => {
+    if (!isReference(edit.after)) {
+      edits.push(edit);
       return;
-    if (isReference(before) || isReference(after)) {
+    }
+    const target = referenced(edit.after);
+    if (!target) {
+      if (findings.some((f) => f.path === edit.path && f.after === edit.after))
+        return;
       findings.push({
-        path,
+        path: edit.path,
         code: "alias",
-        before,
-        after,
-        reason: "This token is an alias, or became one. Re-point aliases in Flash; a push only carries literal values."
+        ...edit.before ? { before: edit.before } : {},
+        after: edit.after,
+        reason: "This points at a token that is neither in the design system nor in the file. Add that token, or point at one that exists."
       });
       return;
     }
-    edits.push({
+    edits.push({ ...edit, reference: target });
+  };
+  const compare = (path, section, name, before, after, theme) => {
+    if (before === void 0 || after === void 0)
+      return;
+    if (same(before, after))
+      return;
+    push({
       path,
       section,
       name,
@@ -3879,7 +4051,7 @@ function diffRepoTokens(doc, repoDtcg, responsive) {
           code: "alias",
           before: narrowest.value,
           after: repoNarrowest.value,
-          reason: "This token is an alias, or became one. Re-point aliases in Flash; a push only carries literal values."
+          reason: "This token changes with the viewport, and its narrowest size became an alias. Point it in Flash; a push carries one literal size here."
         });
       } else {
         edits.push({
@@ -3914,11 +4086,13 @@ function diffRepoTokens(doc, repoDtcg, responsive) {
     for (const key of Object.keys(repoGroup)) {
       if (key.startsWith("$") || key in webGroup)
         continue;
-      findings.push({
-        path: `${group}.${key}`,
-        code: "added-in-repo",
-        reason: "Not in the design system. Add it in Flash, then pull; a push does not create tokens."
-      });
+      if (!add(group, key, repoGroup[key])) {
+        findings.push({
+          path: `${group}.${key}`,
+          code: "added-in-repo",
+          reason: "Not in the design system, and not a single value a push can add. Add it in Flash, then pull."
+        });
+      }
     }
     for (const key of Object.keys(webGroup)) {
       if (key in repoGroup)
@@ -3932,20 +4106,20 @@ function diffRepoTokens(doc, repoDtcg, responsive) {
   };
   const webColors = web.color ?? {};
   presence("color", webColors);
-  const palette = singleThemePalette(tokens);
-  const defaultTheme = palette === tokens.colors ? "dark" : "light";
-  const names = {
-    dark: new Map(tokens.colors.map((t) => [tokensToCssVarName(t.name), t])),
-    light: new Map(tokens.lightColors.map((t) => [tokensToCssVarName(t.name), t]))
-  };
   for (const [key, webEntry] of Object.entries(webColors)) {
     const repoEntry = repo.color?.[key];
     if (!repoEntry)
       continue;
     for (const theme of ["dark", "light"]) {
       const token = names[theme].get(key);
-      if (!token)
+      if (!token) {
+        const own = modesOf(repoEntry)?.[theme];
+        if (typeof own === "string" && own.trim()) {
+          const other = names[theme === "dark" ? "light" : "dark"].get(key);
+          addColour(`color.${key}`, other.name, theme, own);
+        }
         continue;
+      }
       compare(`color.${key}`, BUNDLE_SECTION[theme === "dark" ? "colors" : "lightColors"], token.name, themeValue(webEntry, theme, defaultTheme), themeValue(repoEntry, theme, defaultTheme, webEntry), theme);
     }
   }
@@ -4004,7 +4178,7 @@ function documentToRepoBundle(doc, options = {}) {
     ...options.paths
   };
   const components = atomicComponentsToExportSpecs(doc);
-  const tokens = pruneUnusedMotionTokens(withResponsiveLayer(fromAtomicDocument(doc), options.responsive), components);
+  const tokens = pruneUnusedMotionTokens(keepCodeNames(withResponsiveLayer(fromAtomicDocument(doc), options.responsive), options.codeNames, options.cssPrefix), components);
   const projectName = options.projectName ?? doc.name;
   const files = [];
   if (paths.tokensDtcg) {
@@ -4197,10 +4371,20 @@ function responsiveOf(envelope) {
 function exportSettingsOf(envelope) {
   const raw = envelope.export_settings;
   if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
-  const { css_prefix: cssPrefix, css_selector: cssSelector } = raw;
+  const {
+    css_prefix: cssPrefix,
+    css_selector: cssSelector,
+    code_names: rawCodeNames
+  } = raw;
+  const codeNames = rawCodeNames && typeof rawCodeNames === "object" && !Array.isArray(rawCodeNames) ? Object.fromEntries(
+    Object.entries(rawCodeNames).filter(
+      (e) => typeof e[1] === "string"
+    )
+  ) : {};
   return {
     ...typeof cssPrefix === "string" ? { cssPrefix } : {},
-    ...typeof cssSelector === "string" ? { cssSelector } : {}
+    ...typeof cssSelector === "string" ? { cssSelector } : {},
+    ...Object.keys(codeNames).length ? { codeNames } : {}
   };
 }
 function editPath(edit) {
@@ -4662,19 +4846,43 @@ async function detectDrift(opts) {
   };
 }
 
-// src/tools/push-to-web.ts
-function findingEntry(finding) {
-  return {
-    action: "flag",
-    targetKind: "token",
-    path: finding.path,
-    before: finding.before ?? null,
-    after: finding.after ?? null,
-    code: finding.code,
-    reason: finding.reason
-  };
+// src/tools/scan-workspace.ts
+import { readFile as readFile6, readdir, stat } from "fs/promises";
+import { join as join5, resolve as resolve7 } from "path";
+async function walk(root, dir, out) {
+  const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+  for (const e of entries) {
+    const full = join5(dir, e.name);
+    if (e.isDirectory()) {
+      if (!isSkippedScanDir(e.name)) await walk(root, full, out);
+    } else if (e.isFile()) out.push(full.slice(root.length + 1));
+  }
 }
-async function pushToWeb(opts) {
+async function readSmallFile(path) {
+  const info = await stat(path).catch(() => null);
+  if (!info || !info.isFile() || info.size > MAX_SCAN_READ_BYTES) return null;
+  return readFile6(path, "utf8").catch(() => null);
+}
+async function scanWorkspace(workspaceRoot, opts = {}) {
+  const root = resolve7(workspaceRoot);
+  const paths = [];
+  await walk(root, root, paths);
+  return buildWorkspaceScan({
+    workspaceRoot: root,
+    paths: opts.skip ? paths.filter((p) => !opts.skip(p)) : paths,
+    read: (rel) => readSmallFile(join5(root, rel))
+  });
+}
+
+// src/tools/code-changes.ts
+function scanIsEmpty(scan) {
+  const tokens = Object.values(scan.tokens ?? {}).reduce(
+    (n, list2) => n + list2.length,
+    0
+  );
+  return tokens === 0 && (scan.files ?? []).length === 0;
+}
+async function collectCodeChanges(opts) {
   const state = await readRepoState(opts);
   const { envelope, lock } = state;
   if (!lock) {
@@ -4689,75 +4897,145 @@ async function pushToWeb(opts) {
       `Flash has published a new version since this repo pulled (published ${lock.publishedVersionId ?? "unknown"}, now ${envelope.published_version_id ?? "none"}). A push now could undo those changes. Keep a copy of your edits, pull, re-apply them, then push.`
     );
   }
-  if (state.tokensText === null) {
-    throw new SyncRefusal(
-      "missing-tokens-file",
-      `${state.tokensPath} is missing, so there is nothing to push. Pull again to restore it.`
-    );
-  }
-  const { edits, findings } = diffRepoTokens(
-    state.doc,
-    state.tokensText,
-    state.responsive
+  const { edits, findings } = state.tokensText === null ? {
+    edits: [],
+    findings: [
+      {
+        path: state.tokensPath,
+        code: "unreadable",
+        reason: `${state.tokensPath} is missing, so only the stylesheets were read. Pull again to restore it.`
+      }
+    ]
+  } : diffRepoTokens(state.doc, state.tokensText, state.responsive);
+  const pulled = new Set(
+    lock.files.map((f) => f.replace(/\\/g, "/").replace(/^\.\//, ""))
+  );
+  const scan = await scanWorkspace(opts.workspaceRoot, {
+    skip: (rel) => pulled.has(rel.replace(/\\/g, "/"))
+  });
+  return {
+    state,
+    scan,
+    edits,
+    findings,
+    request: {
+      scan,
+      changes: edits.map((edit) => ({
+        section: edit.section,
+        name: edit.name,
+        value: repoEditValue(edit)
+      })),
+      base_revision: envelope.revision
+    }
+  };
+}
+
+// src/tools/push-to-web.ts
+var NOT_TAKEN = /* @__PURE__ */ new Set(["unresolved", "unusable"]);
+var THEME_OF = {
+  "design-tokens-dark-colors": "dark",
+  "design-tokens-light-colors": "light"
+};
+function rowPath(section, name) {
+  const theme = section ? THEME_OF[section] : void 0;
+  return theme ? `${name} (${theme})` : name;
+}
+function findingEntry(finding) {
+  return {
+    action: "flag",
+    targetKind: "token",
+    path: finding.path,
+    before: finding.before ?? null,
+    after: finding.after ?? null,
+    code: finding.code,
+    reason: finding.reason
+  };
+}
+function planFrom(response, edits) {
+  const notes = response.notes ?? [];
+  const noteFor = (section, name) => notes.find(
+    (n) => !NOT_TAKEN.has(n.kind) && n.name === name && n.section === section
   );
-  const flagged = findings.map(findingEntry);
+  const rows = (response.diff ?? []).map((row) => {
+    const note = noteFor(row.section, row.name);
+    const edit = edits.find(
+      (e) => e.section === row.section && e.name === row.name
+    );
+    return {
+      ...tokenChangeToPlanEntry(row),
+      path: edit ? editPath(edit) : rowPath(row.section, row.name),
+      ...edit && edit.kind !== "add" ? { before: edit.before } : {},
+      ...edit && !edit.reference ? { after: edit.after } : {},
+      ...note ? { code: note.kind, reason: note.reason } : {}
+    };
+  });
+  const refused = notes.filter((n) => NOT_TAKEN.has(n.kind)).map((n) => ({
+    action: "flag",
+    targetKind: "token",
+    path: rowPath(n.section, n.name),
+    code: n.kind,
+    reason: n.reason
+  }));
+  return [...rows, ...refused];
+}
+async function pushToWeb(opts) {
+  const collected = await collectCodeChanges(opts);
+  const { envelope } = collected.state;
+  const flagged = collected.findings.map(findingEntry);
   const base = {
     genomeId: envelope.id,
     revision: envelope.revision,
-    findings
+    findings: collected.findings
   };
-  if (!edits.length) {
+  if (!collected.request.changes.length && scanIsEmpty(collected.scan)) {
     return {
       ...makeChangePlan(flagged, true),
       ...base,
       status: "no_changes",
       changeSetId: null,
-      message: findings.length ? "No token value changed. The flagged entries are things a push does not carry." : "No token value changed since the last pull."
+      message: collected.findings.length ? "Nothing in the code to send. The flagged entries are things a push does not carry." : "Nothing in the code to send: no stylesheet defines a token, and the tokens file matches the last pull."
     };
   }
-  const planned = edits.map((edit) => ({
-    action: "update",
-    targetKind: "token",
-    path: editPath(edit),
-    before: edit.before,
-    after: edit.after
-  }));
-  if (opts.confirm !== true) {
+  const dryRun = opts.confirm !== true;
+  const codebase = opts.config.codebase?.name ?? opts.config.name;
+  const response = await opts.client.callTool(
+    "propose_code_scan",
+    {
+      ...collected.request,
+      scan: {
+        ...collected.request.scan,
+        // The review card says where the code came from.
+        workspaceRoot: codebase
+      },
+      ...dryRun ? { dry_run: true } : {}
+    }
+  );
+  const entries = [...planFrom(response, collected.edits), ...flagged];
+  const changed = (response.diff ?? []).length;
+  if (response.no_changes) {
+    return {
+      ...makeChangePlan(entries, dryRun),
+      ...base,
+      status: "no_changes",
+      changeSetId: null,
+      message: "Flash already has what the code holds, or the same proposal is waiting for review."
+    };
+  }
+  if (dryRun) {
     return {
-      ...makeChangePlan([...planned, ...flagged], true),
+      ...makeChangePlan(entries, true),
       ...base,
       status: "dry_run",
       changeSetId: null,
-      message: `${edits.length} token value${edits.length === 1 ? "" : "s"} to propose for review. Run again with confirm to open the change set in Flash.`
+      message: `${changed} change${changed === 1 ? "" : "s"} to propose for review. Run again with confirm to open the change set in Flash.`
     };
   }
-  const codebase = opts.config.codebase?.name ?? opts.config.name;
-  const response = await opts.client.callTool(
-    "propose_change_set",
-    {
-      base_revision: envelope.revision,
-      source_label: `Genome \xB7 ${codebase}`,
-      changes: edits.map((edit) => ({
-        section: edit.section,
-        name: edit.name,
-        value: edit.after
-      }))
-    }
-  );
-  const skipped = (response.skipped ?? []).map((s) => ({
-    action: "flag",
-    targetKind: "token",
-    path: `${s.section}/${s.name}`,
-    code: "skipped-by-server",
-    reason: s.reason
-  }));
-  const proposed = (response.diff ?? []).map(tokenChangeToPlanEntry);
   return {
-    ...makeChangePlan([...proposed, ...skipped, ...flagged], false),
+    ...makeChangePlan(entries, false),
     ...base,
-    status: response.no_changes ? "no_changes" : "proposed",
+    status: "proposed",
     changeSetId: response.change_set_id ?? null,
-    message: response.message ?? (response.no_changes ? "Flash already has these values, or the same proposal is waiting for review." : "Proposed for review. Open Sync in Flash to apply or discard it.")
+    message: "Proposed for review. Open Sync in Flash to apply or discard it."
   };
 }
 
@@ -4861,8 +5139,8 @@ function ensureTrailingNewline(text) {
 }
 
 // src/workspace.ts
-import { readFile as readFile6 } from "fs/promises";
-import { resolve as resolve7 } from "path";
+import { readFile as readFile7 } from "fs/promises";
+import { resolve as resolve8 } from "path";
 
 // src/rpc.ts
 var TOOL_ERROR = -32e3;
@@ -4967,7 +5245,7 @@ function genomeToken(explicit) {
 async function readGenomeConfig(workspaceRoot, configPath) {
   let legacy = false;
   for (const path of configCandidates(configPath, workspaceRoot)) {
-    const raw = await readFile6(path, "utf8").catch(() => null);
+    const raw = await readFile7(path, "utf8").catch(() => null);
     if (!raw) continue;
     if (path.endsWith(LEGACY_CONFIG_FILENAME)) legacy = true;
     let parsed;
@@ -4990,7 +5268,7 @@ async function readGenomeConfig(workspaceRoot, configPath) {
   );
 }
 async function workspaceContext(opts) {
-  const workspaceRoot = resolve7(process.cwd(), opts.workspace ?? ".");
+  const workspaceRoot = resolve8(process.cwd(), opts.workspace ?? ".");
   const config = await readGenomeConfig(workspaceRoot, opts.configPath);
   const client = createRpcClient({
     // Already resolved by the caller in the documented order: the flag, then
@@ -5005,8 +5283,8 @@ async function workspaceContext(opts) {
 
 // src/tools/link.ts
 import { randomBytes } from "crypto";
-import { readFile as readFile7, writeFile as writeFile2 } from "fs/promises";
-import { basename, join as join5, resolve as resolve8 } from "path";
+import { readFile as readFile8, writeFile as writeFile2 } from "fs/promises";
+import { basename, join as join6, resolve as resolve9 } from "path";
 var DEFAULT_INPUTS = {
   tokens: ["design-tokens.json", "tokens.css"],
   components: []
@@ -5025,9 +5303,9 @@ async function linkGenome(opts) {
       "The server did not say which design system this token belongs to."
     );
   }
-  const root = resolve8(opts.workspaceRoot);
-  const path = join5(root, GENOME_CONFIG_FILENAME);
-  const before = await readFile7(path, "utf8").catch(() => null);
+  const root = resolve9(opts.workspaceRoot);
+  const path = join6(root, GENOME_CONFIG_FILENAME);
+  const before = await readFile8(path, "utf8").catch(() => null);
   let previous = null;
   let unreadable = false;
   if (before) {
@@ -5093,13 +5371,13 @@ function describeLink(result) {
 }
 
 // src/tools/apply-token-patch.ts
-import { readFile as readFile8, writeFile as writeFile3 } from "fs/promises";
+import { readFile as readFile9, writeFile as writeFile3 } from "fs/promises";
 function isRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 async function applyTokenPatch(tokenFile, patch, options = {}) {
   const confirm = options.confirm === true;
-  const text = await readFile8(tokenFile, "utf8");
+  const text = await readFile9(tokenFile, "utf8");
   const raw = JSON.parse(text);
   const { tokens, name } = normalizeTokenDocument(raw);
   const beforeCount = tokens.length;
@@ -5161,30 +5439,30 @@ async function applyTokenPatch(tokenFile, patch, options = {}) {
 }
 
 // src/tools/brand-dna.ts
-import { readFile as readFile9 } from "fs/promises";
-import { dirname as dirname3, resolve as resolve9 } from "path";
+import { readFile as readFile10 } from "fs/promises";
+import { dirname as dirname3, resolve as resolve10 } from "path";
 function isRecord3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 async function getBrandDna(options) {
   if (options.brandDnaFile) {
-    const text2 = await readFile9(options.brandDnaFile, "utf8");
+    const text2 = await readFile10(options.brandDnaFile, "utf8");
     const raw2 = JSON.parse(text2);
     if (!isRecord3(raw2)) {
       throw new Error("brand-dna file must be a JSON object");
     }
     return { source: options.brandDnaFile, brandDna: raw2 };
   }
-  const sibling = resolve9(dirname3(options.tokenFile), "brand-dna.json");
+  const sibling = resolve10(dirname3(options.tokenFile), "brand-dna.json");
   try {
-    const text2 = await readFile9(sibling, "utf8");
+    const text2 = await readFile10(sibling, "utf8");
     const raw2 = JSON.parse(text2);
     if (isRecord3(raw2)) {
       return { source: sibling, brandDna: raw2 };
     }
   } catch {
   }
-  const text = await readFile9(options.tokenFile, "utf8");
+  const text = await readFile10(options.tokenFile, "utf8");
   const raw = JSON.parse(text);
   if (!isRecord3(raw)) {
     throw new Error(
@@ -5259,7 +5537,7 @@ async function generateComponentPrompt(componentsFile, tokenFile, name) {
 }
 
 // src/tools/list-violations.ts
-import { readFile as readFile10 } from "fs/promises";
+import { readFile as readFile11 } from "fs/promises";
 var HEX_RE = /#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})\b/g;
 var ARBITRARY_TW_RE = /\b(?:bg|text|border|from|to|via|ring)-\[#[0-9a-fA-F]{3,8}\]/g;
 var ARBITRARY_PX_RE = /\b(?:p|px|py|pt|pb|pl|pr|m|mx|my|mt|mb|ml|mr|gap|space-[xy])-\[(\d+)px\]/g;
@@ -5300,7 +5578,7 @@ function lineCol(source, index) {
 }
 async function listViolations(tokenFile, filePath) {
   const loaded = await loadTokensFromFile(tokenFile);
-  const source = await readFile10(filePath, "utf8");
+  const source = await readFile11(filePath, "utf8");
   const colors = colorTokenSet(loaded.tokens);
   const spacing = spacingTokenSet(loaded.tokens);
   const violations = [];
@@ -5369,11 +5647,11 @@ import { spawn } from "child_process";
 import { createServer } from "http";
 
 // src/oauth/credentials.ts
-import { chmod, mkdir as mkdir2, readFile as readFile11, writeFile as writeFile4 } from "fs/promises";
+import { chmod, mkdir as mkdir2, readFile as readFile12, writeFile as writeFile4 } from "fs/promises";
 import { homedir } from "os";
-import { dirname as dirname4, join as join6 } from "path";
+import { dirname as dirname4, join as join7 } from "path";
 function credentialPath() {
-  return process.env.FLASH_GENOME_CREDENTIALS || join6(homedir(), ".config", "flash-dsm", "credentials.json");
+  return process.env.FLASH_GENOME_CREDENTIALS || join7(homedir(), ".config", "flash-dsm", "credentials.json");
 }
 async function writeCredential(cred) {
   const path = credentialPath();
@@ -5385,7 +5663,7 @@ async function writeCredential(cred) {
 async function readCredential() {
   try {
     const raw = JSON.parse(
-      await readFile11(credentialPath(), "utf8")
+      await readFile12(credentialPath(), "utf8")
     );
     if (!raw.accessToken || !raw.apiUrl) return null;
     if (raw.kind === "token") return raw;
@@ -5554,34 +5832,6 @@ async function loginWithOauth(opts) {
   return { path };
 }
 
-// src/tools/scan-workspace.ts
-import { readFile as readFile12, readdir, stat } from "fs/promises";
-import { join as join7, resolve as resolve10 } from "path";
-async function walk(root, dir, out) {
-  const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
-  for (const e of entries) {
-    const full = join7(dir, e.name);
-    if (e.isDirectory()) {
-      if (!isSkippedScanDir(e.name)) await walk(root, full, out);
-    } else if (e.isFile()) out.push(full.slice(root.length + 1));
-  }
-}
-async function readSmallFile(path) {
-  const info = await stat(path).catch(() => null);
-  if (!info || !info.isFile() || info.size > MAX_SCAN_READ_BYTES) return null;
-  return readFile12(path, "utf8").catch(() => null);
-}
-async function scanWorkspace(workspaceRoot) {
-  const root = resolve10(workspaceRoot);
-  const paths = [];
-  await walk(root, root, paths);
-  return buildWorkspaceScan({
-    workspaceRoot: root,
-    paths,
-    read: (rel) => readSmallFile(join7(root, rel))
-  });
-}
-
 // src/tools/init.ts
 import { readFile as readFile13 } from "fs/promises";
 import { join as join8 } from "path";
@@ -5711,8 +5961,8 @@ function describeInit(result) {
 
 // src/tools/connect.ts
 import { spawnSync } from "child_process";
-import { readFile as readFile14 } from "fs/promises";
-import { join as join9 } from "path";
+import { readFile as readFile15 } from "fs/promises";
+import { join as join10 } from "path";
 
 // src/cli-sync.ts
 import { resolve as resolve11 } from "path";
@@ -5916,6 +6166,475 @@ async function runSyncCommand(opts, deps = {}) {
   }
 }
 
+// src/tools/live-preview.ts
+import { spawn as spawn2 } from "child_process";
+import { mkdir as mkdir3, readFile as readFile14, rm, writeFile as writeFile5 } from "fs/promises";
+import http from "http";
+import net from "net";
+import { homedir as homedir2 } from "os";
+import { dirname as dirname5, join as join9 } from "path";
+var LIVE_PREVIEW_PORTS = [4747, 4748, 4749, 4750];
+var LIVE_PATH = "/__flash/";
+var COMMON_DEV_PORTS = [
+  5173,
+  5174,
+  3e3,
+  3001,
+  4321,
+  4200,
+  8080,
+  8e3,
+  5e3,
+  1234
+];
+function livePreviewStatePath() {
+  return process.env.FLASH_GENOME_PREVIEW_STATE || join9(homedir2(), ".config", "flash-dsm", "live-preview.json");
+}
+function httpOrigin(url) {
+  if (!url) return null;
+  try {
+    const parsed = new URL(url);
+    return parsed.protocol === "http:" || parsed.protocol === "https:" ? parsed.origin : null;
+  } catch {
+    return null;
+  }
+}
+async function lastLivePreviewOrigin(apiUrl) {
+  try {
+    const state = JSON.parse(
+      await readFile14(livePreviewStatePath(), "utf8")
+    );
+    if (typeof state.origin !== "string" || typeof state.apiOrigin !== "string")
+      return null;
+    if (state.apiOrigin !== httpOrigin(apiUrl)) return null;
+    return httpOrigin(state.origin) === state.origin ? state.origin : null;
+  } catch {
+    return null;
+  }
+}
+async function portsNamedByProject(root) {
+  const found = [];
+  const add = (raw) => {
+    const port = Number(raw);
+    if (Number.isInteger(port) && port > 0 && port < 65536 && !found.includes(port)) {
+      found.push(port);
+    }
+  };
+  try {
+    const pkg = JSON.parse(
+      await readFile14(join9(root, "package.json"), "utf8")
+    );
+    for (const script of Object.values(pkg.scripts ?? {})) {
+      for (const m of script.matchAll(/(?:--port|-p)[=\s]+(\d{2,5})/g))
+        add(m[1]);
+      for (const m of script.matchAll(/\bPORT=(\d{2,5})/g)) add(m[1]);
+    }
+  } catch {
+  }
+  for (const name of [
+    "vite.config.ts",
+    "vite.config.js",
+    "vite.config.mts",
+    "vite.config.mjs"
+  ]) {
+    try {
+      const text = await readFile14(join9(root, name), "utf8");
+      for (const m of text.matchAll(/\bport\s*:\s*(\d{2,5})/g)) add(m[1]);
+    } catch {
+    }
+  }
+  return found;
+}
+async function devServerCommand(root) {
+  let scripts = {};
+  try {
+    scripts = JSON.parse(await readFile14(join9(root, "package.json"), "utf8")).scripts ?? {};
+  } catch {
+    return null;
+  }
+  const script = ["dev", "start", "serve"].find((name) => scripts[name]);
+  if (!script) return null;
+  const has = async (name) => readFile14(join9(root, name)).then(
+    () => true,
+    () => false
+  );
+  const pm = await has("pnpm-lock.yaml") ? "pnpm" : await has("yarn.lock") ? "yarn" : await has("bun.lock") || await has("bun.lockb") ? "bun" : "npm";
+  if (pm === "pnpm" || pm === "yarn") return `${pm} ${script}`;
+  if (pm === "npm" && script === "start") return "npm start";
+  return `${pm} run ${script}`;
+}
+async function answersWithPage(url, fetchImpl) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 900);
+  try {
+    const res = await fetchImpl(url, {
+      signal: controller.signal,
+      headers: { accept: "text/html" },
+      redirect: "manual"
+    });
+    const type = res.headers.get("content-type") ?? "";
+    return type.includes("text/html") || res.status >= 300 && res.status < 400;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function findDevServer(root, fetchImpl = fetch) {
+  const ports = [
+    ...await portsNamedByProject(root),
+    ...COMMON_DEV_PORTS
+  ].filter(
+    (port, i, all) => all.indexOf(port) === i && !LIVE_PREVIEW_PORTS.includes(port)
+  );
+  for (const port of ports) {
+    const url = `http://localhost:${port}`;
+    if (await answersWithPage(`${url}/`, fetchImpl)) return url;
+  }
+  return null;
+}
+function liveCss(entries) {
+  return entries.map(([name, value]) => {
+    const inline = '[style*="' + name + ':"]';
+    return ":root, :host, *:not(" + inline + "):not(" + inline + " *) { " + name + ": " + value + " !important; }";
+  }).join("\n");
+}
+function liveScript(origin) {
+  return `(() => {
+  const ORIGIN = ${JSON.stringify(origin)};
+  const NAME = /^--[A-Za-z0-9_-]{1,80}$/;
+  const VALUE = /^[^;{}<>]{1,200}$/;
+  const liveCss = ${liveCss.toString()};
+  let css = "";
+  const roots = new Set([document]);
+  const sheetFor = (root) => {
+    const host = root === document ? document.head || document.documentElement : root;
+    let el = host.querySelector(":scope > style[data-flash-live]");
+    if (!el) {
+      el = document.createElement("style");
+      el.setAttribute("data-flash-live", "");
+      host.appendChild(el);
+    }
+    return el;
+  };
+  const collect = (node) => {
+    const walker = document.createTreeWalker(node, NodeFilter.SHOW_ELEMENT);
+    for (let el = walker.currentNode; el; el = walker.nextNode()) {
+      if (el.shadowRoot && !roots.has(el.shadowRoot)) {
+        roots.add(el.shadowRoot);
+        observe(el.shadowRoot);
+        collect(el.shadowRoot);
+      }
+    }
+  };
+  const paint = () => {
+    for (const root of roots) {
+      const el = sheetFor(root);
+      if (el.textContent !== css) el.textContent = css;
+    }
+  };
+  let queued = false;
+  const observer = new MutationObserver(() => {
+    if (queued) return;
+    queued = true;
+    requestAnimationFrame(() => {
+      queued = false;
+      collect(document.documentElement);
+      paint();
+    });
+  });
+  const observe = (root) =>
+    observer.observe(root, { childList: true, subtree: true });
+  window.addEventListener("message", (event) => {
+    if (event.origin !== ORIGIN || !event.data) return;
+    const { type, vars } = event.data;
+    if (type === "flash:reset") css = "";
+    else if (type === "flash:vars" && vars && typeof vars === "object") {
+      css = liveCss(
+        Object.entries(vars).filter(
+          ([name, value]) =>
+            NAME.test(name) && typeof value === "string" && VALUE.test(value),
+        ),
+      );
+    } else return;
+    collect(document.documentElement);
+    paint();
+  });
+  const start = () => {
+    observe(document.documentElement);
+    collect(document.documentElement);
+    paint();
+    if (window.parent !== window) {
+      window.parent.postMessage({ type: "flash:ready" }, ORIGIN);
+    }
+  };
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", start, { once: true });
+  } else start();
+})();
+`;
+}
+function cleanHeaders(headers, injected, origin) {
+  const out = {};
+  let csp = "";
+  for (const [key, value] of Object.entries(headers)) {
+    const name = key.toLowerCase();
+    if (name === "x-frame-options") continue;
+    if (name === "content-security-policy") {
+      csp = (Array.isArray(value) ? value.join(";") : String(value ?? "")).split(";").filter((part) => part.trim() && !/^\s*frame-ancestors\b/i.test(part)).join(";").trim();
+      continue;
+    }
+    if (injected && (name === "content-length" || name === "etag")) continue;
+    out[key] = value;
+  }
+  out["content-security-policy"] = [csp, `frame-ancestors ${origin}`].filter(Boolean).join("; ");
+  return out;
+}
+function injectScript(html) {
+  const tag = `<script src="${LIVE_PATH}live.js"></script>`;
+  if (html.includes(tag)) return html;
+  const head = html.match(/<head[^>]*>/i);
+  if (head?.index !== void 0) {
+    const at = head.index + head[0].length;
+    return html.slice(0, at) + tag + html.slice(at);
+  }
+  return tag + html;
+}
+async function serveLivePreview(opts) {
+  const target = new URL(opts.devUrl);
+  const targetPort = Number(target.port || 80);
+  const origin = opts.allowedOrigin.replace(/\/$/, "");
+  const script = liveScript(origin);
+  let info = null;
+  const cors = (res) => {
+    res.setHeader("Access-Control-Allow-Origin", origin);
+    res.setHeader("Access-Control-Allow-Methods", "GET, OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "*");
+    res.setHeader("Access-Control-Allow-Private-Network", "true");
+    res.setHeader("Vary", "Origin");
+  };
+  const own = (req, res) => {
+    const path = (req.url ?? "").split("?")[0];
+    if (req.method === "OPTIONS") {
+      cors(res);
+      res.writeHead(204).end();
+      return;
+    }
+    if (path === `${LIVE_PATH}hello`) {
+      cors(res);
+      res.writeHead(200, {
+        "content-type": "application/json",
+        "cache-control": "no-store"
+      });
+      res.end(JSON.stringify(info));
+      return;
+    }
+    if (path === `${LIVE_PATH}live.js`) {
+      res.writeHead(200, {
+        "content-type": "text/javascript; charset=utf-8",
+        "cache-control": "no-store"
+      });
+      res.end(script);
+      return;
+    }
+    res.writeHead(404).end();
+  };
+  const proxy = (req, res) => {
+    const headers = { ...req.headers, host: target.host };
+    headers["accept-encoding"] = "identity";
+    const upstream = http.request(
+      {
+        hostname: target.hostname,
+        port: targetPort,
+        path: req.url,
+        method: req.method,
+        headers
+      },
+      (up) => {
+        const type = String(up.headers["content-type"] ?? "");
+        const encoded = up.headers["content-encoding"];
+        if (type.includes("text/html") && (!encoded || encoded === "identity")) {
+          const chunks = [];
+          up.on("data", (c) => chunks.push(c));
+          up.on("end", () => {
+            const body = injectScript(Buffer.concat(chunks).toString("utf8"));
+            res.writeHead(
+              up.statusCode ?? 200,
+              cleanHeaders(up.headers, true, origin)
+            );
+            res.end(body);
+          });
+          return;
+        }
+        res.writeHead(
+          up.statusCode ?? 200,
+          cleanHeaders(up.headers, false, origin)
+        );
+        up.pipe(res);
+      }
+    );
+    upstream.on("error", () => {
+      if (res.headersSent) {
+        res.end();
+        return;
+      }
+      res.writeHead(502, { "content-type": "text/html; charset=utf-8" });
+      res.end(
+        `<!doctype html><meta charset="utf-8"><body style="font:14px system-ui;padding:32px;color:#555"><p>Your app isn't answering on ${target.host}.</p><p>Start its dev server and this page shows it.</p></body>`
+      );
+    });
+    req.pipe(upstream);
+  };
+  const fromThisMachine = (req) => {
+    const address = server.address();
+    const port = address && typeof address === "object" ? address.port : null;
+    const host = /^(\[[^\]]+\]|[^:]+)(?::(\d+))?$/.exec(
+      String(req.headers.host ?? "").toLowerCase()
+    );
+    return !!host && ["localhost", "127.0.0.1", "[::1]"].includes(host[1]) && (!host[2] || Number(host[2]) === port);
+  };
+  const server = http.createServer((req, res) => {
+    if (!fromThisMachine(req)) {
+      res.writeHead(403, { "content-type": "text/plain" }).end("Forbidden");
+      return;
+    }
+    if ((req.url ?? "").startsWith(LIVE_PATH) || req.method === "OPTIONS") {
+      own(req, res);
+    } else {
+      proxy(req, res);
+    }
+  });
+  server.on("upgrade", (req, socket, head) => {
+    if (!fromThisMachine(req)) {
+      socket.destroy();
+      return;
+    }
+    const upstream = net.connect(targetPort, target.hostname, () => {
+      const lines = [`${req.method} ${req.url} HTTP/${req.httpVersion}`];
+      for (let i = 0; i < req.rawHeaders.length; i += 2) {
+        const name = req.rawHeaders[i];
+        const value = name.toLowerCase() === "host" ? target.host : req.rawHeaders[i + 1];
+        lines.push(`${name}: ${value}`);
+      }
+      upstream.write(lines.join("\r\n") + "\r\n\r\n");
+      if (head.length) upstream.write(head);
+      socket.pipe(upstream).pipe(socket);
+    });
+    upstream.on("error", () => socket.destroy());
+    socket.on("error", () => upstream.destroy());
+  });
+  for (const port of opts.ports ?? LIVE_PREVIEW_PORTS) {
+    const ok = await new Promise((resolve14) => {
+      const onError = () => resolve14(false);
+      server.once("error", onError);
+      server.listen(port, "127.0.0.1", () => {
+        server.off("error", onError);
+        resolve14(true);
+      });
+    });
+    if (ok) {
+      info = {
+        designSystemId: opts.designSystemId,
+        devUrl: opts.devUrl,
+        project: opts.project ?? null,
+        port,
+        version: opts.version ?? "0.0.0",
+        pid: process.pid
+      };
+      return { server, info };
+    }
+  }
+  throw new Error(
+    `Ports ${(opts.ports ?? LIVE_PREVIEW_PORTS).join(", ")} are all taken; the live preview can't start.`
+  );
+}
+async function askLivePreview(port, fetchImpl = fetch) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 700);
+  try {
+    const res = await fetchImpl(`http://127.0.0.1:${port}${LIVE_PATH}hello`, {
+      signal: controller.signal
+    });
+    if (!res.ok) return null;
+    const body = await res.json();
+    return body && typeof body.designSystemId === "number" ? body : null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function stopLivePreview(fetchImpl = fetch) {
+  const path = livePreviewStatePath();
+  let state;
+  try {
+    state = JSON.parse(await readFile14(path, "utf8"));
+  } catch {
+    return false;
+  }
+  const { pid, origin, apiOrigin } = state;
+  if (origin && apiOrigin) {
+    await writeFile5(path, JSON.stringify({ origin, apiOrigin }), {
+      mode: 384
+    });
+  } else {
+    await rm(path, { force: true });
+  }
+  if (typeof pid !== "number") return false;
+  for (const port of LIVE_PREVIEW_PORTS) {
+    const info = await askLivePreview(port, fetchImpl);
+    if (info?.pid === pid) {
+      try {
+        process.kill(pid);
+      } catch {
+      }
+      return true;
+    }
+  }
+  return false;
+}
+async function startLivePreviewInBackground(opts) {
+  await stopLivePreview();
+  const child = spawn2(
+    process.execPath,
+    [
+      opts.bin,
+      "preview",
+      "--serve",
+      "--dev-url",
+      opts.devUrl,
+      "--system",
+      String(opts.designSystemId),
+      "--origin",
+      opts.allowedOrigin,
+      ...opts.project ? ["--name", opts.project] : []
+    ],
+    { detached: true, stdio: "ignore" }
+  );
+  child.unref();
+  const path = livePreviewStatePath();
+  await mkdir3(dirname5(path), { recursive: true });
+  await writeFile5(
+    path,
+    JSON.stringify({
+      pid: child.pid,
+      devUrl: opts.devUrl,
+      designSystemId: opts.designSystemId,
+      origin: opts.allowedOrigin.replace(/\/$/, ""),
+      apiOrigin: httpOrigin(opts.apiUrl)
+    }),
+    { mode: 384 }
+  );
+  for (let i = 0; i < 20; i++) {
+    await new Promise((r) => setTimeout(r, 150));
+    for (const port of LIVE_PREVIEW_PORTS) {
+      const info = await askLivePreview(port, opts.fetchImpl);
+      if (info?.designSystemId === opts.designSystemId) return info;
+    }
+  }
+  return null;
+}
+
 // src/tools/connect.ts
 var GENOME_SERVER_KEY = "flash-genome";
 var GENOME_LATEST = "@flashdsm/genome@latest";
@@ -5929,7 +6648,7 @@ var ConnectError = class extends Error {
 async function packageName2(root) {
   try {
     return projectNameFromPackageJson(
-      await readFile14(join9(root, "package.json"), "utf8")
+      await readFile15(join10(root, "package.json"), "utf8")
     );
   } catch {
     return null;
@@ -6080,6 +6799,30 @@ async function connectFromBrowser(opts) {
     token
   })))(collected.token) : 1;
   const mcp = (opts.addMcp ?? addMcpForClaudeCode)(scan.workspaceRoot);
+  let livePreview = null;
+  let noDevServer = false;
+  let livePreviewFailed;
+  let devCommand = null;
+  if (opts.livePreview !== false) {
+    const devUrl = await (opts.findDevServer ?? findDevServer)(scan.workspaceRoot);
+    if (devUrl) {
+      const start = opts.livePreview ?? ((args) => startLivePreviewInBackground({ ...args, bin: process.argv[1], apiUrl }));
+      try {
+        livePreview = await start({
+          devUrl,
+          designSystemId: collected.id,
+          allowedOrigin: httpOrigin(collected.editor_url) ?? new URL(apiUrl).origin,
+          project: collected.name
+        });
+      } catch {
+        livePreview = null;
+      }
+      if (!livePreview) livePreviewFailed = devUrl;
+    } else {
+      noDevServer = true;
+      devCommand = await devServerCommand(scan.workspaceRoot);
+    }
+  }
   return {
     system: {
       id: collected.id,
@@ -6091,7 +6834,11 @@ async function connectFromBrowser(opts) {
     link,
     linkError,
     pullExit,
-    mcp
+    mcp,
+    livePreview,
+    noDevServer,
+    livePreviewFailed,
+    devCommand
   };
 }
 function describeConnect(result) {
@@ -6118,6 +6865,20 @@ function describeConnect(result) {
       `So your editor reads the system while you work, add Genome as an MCP server. In Claude Code: ${result.mcp.command}`
     );
   }
+  if (result.livePreview) {
+    lines.push(
+      `Your app (${result.livePreview.devUrl}) shows live in Flash's preview and recolours as you edit. It runs in the background; stop it with \`npx ${GENOME_LATEST} preview --stop\`.`
+    );
+  } else if (result.noDevServer) {
+    const start = result.devCommand ? ` (\`${result.devCommand}\`)` : "";
+    lines.push(
+      `Your app's dev server isn't running, so Flash's preview shows a sample screen for now. To see your app there instead, start the dev server${start}, then run \`npx ${GENOME_LATEST} preview\` in this folder. The editor switches to your app by itself.`
+    );
+  } else if (result.livePreviewFailed) {
+    lines.push(
+      `Your app answers on ${result.livePreviewFailed}, but the live preview didn't start, so Flash's preview shows a sample screen. Run \`npx ${GENOME_LATEST} preview\` in this folder to try again.`
+    );
+  }
   lines.push(
     `Genome's sign-in is stored at ${result.credentialPath}. No token goes in any config.`
   );
@@ -6295,8 +7056,8 @@ async function captureProjectShell(opts) {
 }
 
 // src/tools/scan-usage.ts
-import { readFile as readFile15, readdir as readdir2 } from "fs/promises";
-import { basename as basename2, dirname as dirname5, join as join10, posix, resolve as resolve12 } from "path";
+import { readFile as readFile16, readdir as readdir2 } from "fs/promises";
+import { basename as basename2, dirname as dirname6, join as join11, posix, resolve as resolve12 } from "path";
 var PRODUCT_USAGE_VERSION = 1;
 var USAGE_LIMITS = {
   components: 400,
@@ -6320,11 +7081,11 @@ async function walk2(root, dir, out) {
   for (const entry of entries) {
     if (entry.isDirectory()) {
       if (!SKIP_DIR.test(entry.name)) {
-        await walk2(root, join10(dir, entry.name), out);
+        await walk2(root, join11(dir, entry.name), out);
       }
     } else {
       out.push(
-        join10(dir, entry.name).slice(root.length + 1).replace(/\\/g, "/")
+        join11(dir, entry.name).slice(root.length + 1).replace(/\\/g, "/")
       );
     }
   }
@@ -6388,7 +7149,7 @@ function tagUses(source, local) {
   return (source.match(new RegExp(`<${escapeRe(local)}(?=[\\s/>.])`, "g")) ?? []).length;
 }
 async function repositoryName(root) {
-  const gitConfig = await readFile15(join10(root, ".git", "config"), "utf8").catch(
+  const gitConfig = await readFile16(join11(root, ".git", "config"), "utf8").catch(
     () => ""
   );
   const remote = gitConfig.match(
@@ -6398,7 +7159,7 @@ async function repositoryName(root) {
   if (slug) return slug;
   try {
     const pkg = JSON.parse(
-      await readFile15(join10(root, "package.json"), "utf8")
+      await readFile16(join11(root, "package.json"), "utf8")
     );
     if (typeof pkg.name === "string" && pkg.name.trim()) return pkg.name.trim();
   } catch {
@@ -6421,7 +7182,7 @@ async function scanProductUsage(workspaceRoot, opts = {}) {
   for (const rel of paths) {
     if (basename2(rel) !== "package.json") continue;
     try {
-      const pkg = JSON.parse(await readFile15(join10(root, rel), "utf8"));
+      const pkg = JSON.parse(await readFile16(join11(root, rel), "utf8"));
       if (typeof pkg.name === "string") ownPackages.add(pkg.name);
     } catch {
     }
@@ -6431,13 +7192,13 @@ async function scanProductUsage(workspaceRoot, opts = {}) {
   );
   const found = /* @__PURE__ */ new Map();
   for (const rel of sources) {
-    const text = await readFile15(join10(root, rel), "utf8").catch(() => null);
+    const text = await readFile16(join11(root, rel), "utf8").catch(() => null);
     if (!text || !text.includes("import")) continue;
     for (const name of importedNames(text)) {
       if (!definedAt.has(name.imported)) continue;
       if (!isOwnSource(name.source, ownPackages)) continue;
       const home = definedAt.get(name.imported);
-      if (home && (home === rel || dirname5(home) === dirname5(rel) && /(^|\/)index\.[a-z]+$/i.test(rel))) {
+      if (home && (home === rel || dirname6(home) === dirname6(rel) && /(^|\/)index\.[a-z]+$/i.test(rel))) {
         continue;
       }
       const uses = tagUses(text, name.local);
@@ -6657,6 +7418,11 @@ function parseCliArgs(argv) {
   let confirm = false;
   let json = false;
   let noOpen = false;
+  let serve = false;
+  let stop = false;
+  let devUrl;
+  let system;
+  let origin;
   const VALUE_FLAGS = /* @__PURE__ */ new Set([
     "--tokens",
     "-t",
@@ -6668,7 +7434,10 @@ function parseCliArgs(argv) {
     "--token",
     "--cwd",
     "--code",
-    "--name"
+    "--name",
+    "--dev-url",
+    "--system",
+    "--origin"
   ]);
   let command;
   for (let i = 0; i < argv.length; i++) {
@@ -6732,6 +7501,27 @@ function parseCliArgs(argv) {
       noOpen = true;
       continue;
     }
+    if (arg === "--serve") {
+      serve = true;
+      continue;
+    }
+    if (arg === "--stop") {
+      stop = true;
+      continue;
+    }
+    if (arg === "--dev-url") {
+      devUrl = argv[++i];
+      continue;
+    }
+    if (arg === "--system") {
+      const n = Number(argv[++i]);
+      system = Number.isInteger(n) ? n : void 0;
+      continue;
+    }
+    if (arg === "--origin") {
+      origin = argv[++i];
+      continue;
+    }
     if (arg === "--help" || arg === "-h") {
       console.error(`Usage: flash-genome [command] [options]
 
@@ -6743,12 +7533,15 @@ Commands:
                      scans, opens Flash to confirm, then links the repo,
                      writes the system into it and (in Claude Code) adds
                      Genome as the project's MCP server
-  init --code CODE   Same, with a setup code instead of the browser:
+  preview            Show this app, running on its dev server, inside Flash
+                     and recolour it as you edit (connect starts it; this
+                     starts it again). --stop ends it
+  init --code CODE   Same as connect, with a setup code instead of the browser:
                      scans, creates it in Flash, stores the sign-in, links
                      the repo. CODE comes from Flash: Import > From your code
   link               Bind this repo to the design system you signed in to
   pull               Write the design system into this repo (dry run unless --confirm)
-  push               Propose this repo's token edits to Flash (dry run unless --confirm)
+  push               Propose what this repo's code changed to Flash (dry run unless --confirm)
   drift              Has the repo moved, has Flash, which tokens (read-only)
   login              Open Flash in the browser and store the sign-in locally
 
@@ -6795,7 +7588,12 @@ Exit codes (pull, push, drift):
     name,
     confirm,
     json,
-    noOpen
+    noOpen,
+    serve,
+    stop,
+    devUrl,
+    system,
+    origin
   };
 }
 function textResult(data, isError = false) {
@@ -7154,7 +7952,7 @@ async function createServer2(opts) {
   );
   server.tool(
     "push_to_web",
-    "Propose the token values this repo changed to Flash, as a change set a person reviews on the Sync page. Nothing is applied. Returns the plan; proposes only with confirm. Refused while Flash is ahead of the last pull.",
+    "Propose what this repo's code changed to Flash, as one change set a person reviews on the Sync page: the app's own stylesheets (new tokens, light or dark values Flash lacks, aliases re-pointed with var(--step)) and edits to the pulled design-tokens.json. Files the pull wrote are not read as code. Nothing is applied. Returns the plan; proposes only with confirm. Refused while Flash is ahead of the last pull.",
     workspaceArgs,
     async (args) => {
       try {
@@ -7253,7 +8051,7 @@ async function resolveApiUrl(cli, cwd) {
   const fromEnv = process.env.FLASH_GENOME_API_URL || process.env.FLASH_DS_API_URL;
   if (fromEnv) return fromEnv;
   for (const path of configCandidates(cli.configPath, cwd)) {
-    const raw = await readFile16(path, "utf8").catch(() => null);
+    const raw = await readFile17(path, "utf8").catch(() => null);
     if (!raw) continue;
     try {
       const parsed = GenomeConfigSchema.safeParse(JSON.parse(raw));
@@ -7320,6 +8118,64 @@ async function runConnect(cli, apiUrl) {
     process.exit(1);
   }
 }
+async function readLinkedSystem(root) {
+  try {
+    const config = await readGenomeConfig(root);
+    return { id: config.genomeId, name: config.name ?? null };
+  } catch {
+    return null;
+  }
+}
+async function runPreview(cli, apiUrl) {
+  if (cli.stop) {
+    const stopped = await stopLivePreview();
+    console.log(stopped ? "Stopped the live preview." : "No live preview was running.");
+    return;
+  }
+  const origin = (cli.origin ?? await lastLivePreviewOrigin(apiUrl) ?? new URL(apiUrl).origin).replace(/\/$/, "");
+  if (cli.serve) {
+    if (!cli.devUrl || cli.system === void 0) {
+      console.error("preview --serve needs --dev-url and --system.");
+      process.exit(2);
+    }
+    const { info: info2 } = await serveLivePreview({
+      devUrl: cli.devUrl,
+      designSystemId: cli.system,
+      allowedOrigin: origin,
+      project: cli.name ?? null,
+      version: packageVersion()
+    });
+    console.error(`[flash-genome] live preview on http://localhost:${info2.port} -> ${info2.devUrl}`);
+    return;
+  }
+  const root = resolve13(cli.cwd ?? process.cwd());
+  const linked = await readLinkedSystem(root);
+  if (!linked) {
+    console.error(
+      "This folder isn't linked to a Flash system yet. Run `npx @flashdsm/genome@latest connect` first."
+    );
+    process.exit(2);
+  }
+  const devUrl = cli.devUrl ?? await findDevServer(root);
+  if (!devUrl) {
+    const start = await devServerCommand(root) ?? "npm run dev";
+    console.error(
+      `Couldn't find your app's dev server on localhost, so Flash still shows its sample screen. Start it (${start}), then run this again, or pass --dev-url http://localhost:PORT.`
+    );
+    process.exit(1);
+  }
+  const info = await startLivePreviewInBackground({
+    bin: process.argv[1],
+    apiUrl,
+    devUrl,
+    designSystemId: linked.id,
+    allowedOrigin: origin,
+    project: linked.name
+  });
+  console.log(
+    info ? `Flash shows ${devUrl} live on its preview (through localhost:${info.port}). Stop it with \`npx @flashdsm/genome preview --stop\`.` : "The live preview didn't start. Run `npx @flashdsm/genome preview --serve --dev-url " + devUrl + " --system " + linked.id + "` to see why."
+  );
+}
 async function main() {
   const cli = parseCliArgs(process.argv.slice(2));
   const apiUrl = await resolveApiUrl(cli, resolve13(cli.cwd ?? process.cwd()));
@@ -7348,6 +8204,7 @@ async function main() {
   if (cli.command === "link") return runLink(cli);
   if (cli.command === "init") return runInit(cli, apiUrl);
   if (cli.command === "connect") return runConnect(cli, apiUrl);
+  if (cli.command === "preview") return runPreview(cli, apiUrl);
   if (cli.command) {
     console.error(
       `Unknown command "${cli.command}". Run flash-genome --help for the list.`