rastack 0.0.23 → 0.0.25

package/src/tokens/define.ts

@@ -0,0 +1,128 @@
+/**
+ * `rastack/tokens` — the TypeScript-first authoring DSL for design tokens.
+ *
+ * You author your design system in TypeScript; the compiler
+ * (`rastack tokens`) emits the canonical DTCG JSON plus ready-to-use CSS custom
+ * properties and a typed theme object. This mirrors the resource DSL
+ * (`rastack/define`): TypeScript is the single source of truth.
+ *
+ * ```ts
+ * import { defineTokens, t, ref } from "rastack/tokens";
+ *
+ * export default defineTokens({
+ *   tokens: {
+ *     color: {
+ *       brand: { 500: t.color("#4F6BFF"), 600: t.color("#3B54E8") },
+ *       text:  t.color(ref("color.brand.500")),   // alias
+ *     },
+ *     space: { sm: t.dimension(8), md: t.dimension(16) },
+ *     radius: { md: t.dimension(10) },
+ *     font: { sans: t.fontFamily(["Inter", "system-ui", "sans-serif"]) },
+ *   },
+ *   modes: {
+ *     light: { color: { bg: t.color("#FFFFFF") } },
+ *     dark:  { color: { bg: t.color("#06080F") } },
+ *   },
+ *   defaultMode: "light",
+ * });
+ * ```
+ *
+ * The builders are thin: each returns a plain `{ $type, $value }` DTCG token, so
+ * a token tree authored with `t.*` is byte-identical to one hand-written as
+ * JSON. You can freely mix the two.
+ */
+
+import {
+  DesignToken,
+  ShadowValue,
+  ThemedTokens,
+  TokenDocument,
+  TokenType,
+} from "./types";
+
+/** An alias reference to another token: `ref("color.brand.500")` → `"{color.brand.500}"`. */
+export function ref(path: string): string {
+  return `{${path}}`;
+}
+
+/** True when a string is a DTCG alias (`"{a.b.c}"`). */
+export function isAlias(value: unknown): value is string {
+  return typeof value === "string" && /^\{[^{}]+\}$/.test(value);
+}
+
+/** Strip the braces from an alias: `"{a.b}"` → `"a.b"`. */
+export function aliasTarget(value: string): string {
+  return value.slice(1, -1);
+}
+
+function token<T extends TokenType>(
+  type: T,
+  value: DesignToken["$value"],
+  description?: string,
+): DesignToken {
+  const out: DesignToken = { $type: type, $value: value };
+  if (description) out.$description = description;
+  return out;
+}
+
+/**
+ * Typed token builders. Each accepts a literal value or an alias produced by
+ * {@link ref}, plus an optional `$description`.
+ */
+export const t = {
+  /** A colour: any CSS colour string (or an alias). */
+  color: (value: string, description?: string): DesignToken =>
+    token("color", value, description),
+
+  /**
+   * A dimension — spacing, sizing, radius. A bare `number` is treated as `px`
+   * (the common case); pass a string for other units (`"1rem"`, `"50%"`).
+   */
+  dimension: (value: string | number, description?: string): DesignToken =>
+    token("dimension", typeof value === "number" ? `${value}px` : value, description),
+
+  /** A font-family stack. */
+  fontFamily: (value: string | string[], description?: string): DesignToken =>
+    token("fontFamily", value, description),
+
+  /** A font weight (numeric `700` or keyword `"bold"`). */
+  fontWeight: (value: number | string, description?: string): DesignToken =>
+    token("fontWeight", value, description),
+
+  /** A duration — `"200ms"`, or a bare `number` of milliseconds. */
+  duration: (value: string | number, description?: string): DesignToken =>
+    token("duration", typeof value === "number" ? `${value}ms` : value, description),
+
+  /** A cubic-bezier easing curve: `[x1, y1, x2, y2]`. */
+  cubicBezier: (
+    value: [number, number, number, number],
+    description?: string,
+  ): DesignToken => token("cubicBezier", value as unknown as string[], description),
+
+  /** A raw number token (line-height, z-index, opacity, …). */
+  number: (value: number, description?: string): DesignToken =>
+    token("number", value, description),
+
+  /** A shadow (or a stack of shadows) → a CSS `box-shadow`. */
+  shadow: (value: ShadowValue | ShadowValue[], description?: string): DesignToken =>
+    token("shadow", value, description),
+};
+
+/**
+ * Author a themeable token set. Accepts either a bare token tree or the full
+ * `{ tokens, modes, defaultMode }` shape, and always normalises to
+ * {@link ThemedTokens}.
+ */
+export function defineTokens(input: TokenDocument | ThemedTokens): ThemedTokens {
+  if (isThemed(input)) {
+    return { modes: {}, ...input };
+  }
+  return { tokens: input, modes: {} };
+}
+
+function isThemed(input: TokenDocument | ThemedTokens): input is ThemedTokens {
+  return (
+    typeof (input as ThemedTokens).tokens === "object" &&
+    (input as ThemedTokens).tokens !== null
+  );
+}

package/src/tokens/index.ts

@@ -0,0 +1,18 @@
+/**
+ * `rastack/tokens` core — the design-system framework.
+ *
+ * A TypeScript-first authoring DSL over the **W3C Design Tokens (DTCG)**
+ * standard, a resolver (alias + `$type` inheritance + cycle detection), and
+ * pure emitters (CSS custom properties, a typed theme). Everything here is
+ * filesystem- and React-free, so it builds for the browser and is what
+ * `rastack/theme` runs at runtime. The `rastack tokens` CLI adds file IO on top
+ * (see `tools/src/tokens/compile.ts`).
+ */
+
+export * from "./types";
+export * from "./define";
+export * from "./theme";
+export * from "./color";
+export * from "./resolve";
+export * from "./css";
+export * from "./ts";

package/src/tokens/resolve.ts

@@ -0,0 +1,170 @@
+/**
+ * Token resolution — the compiler's core pass.
+ *
+ * Given a DTCG token tree, produce a flat, ordered list of {@link ResolvedToken}
+ * with:
+ *   - **`$type` inheritance** — a token inherits the nearest ancestor group's
+ *     `$type` when it doesn't declare its own (a DTCG rule).
+ *   - **alias resolution** — a `"{a.b.c}"` value is followed to its source,
+ *     transitively, with cycle detection. The immediate alias target is kept
+ *     (`aliasOf`) so emitters can preserve the reference.
+ *   - **stable ordering** — depth-first in author order, so output diffs are
+ *     minimal.
+ */
+
+import { aliasTarget, isAlias } from "./define";
+import {
+  DesignToken,
+  isToken,
+  ResolvedToken,
+  ThemedTokens,
+  TokenDocument,
+  TokenType,
+  TokenValue,
+} from "./types";
+
+/** A flat map from dotted path to the raw token, plus its inherited type. */
+interface RawEntry {
+  path: string;
+  token: DesignToken;
+  /** Type after group inheritance but before alias type-borrowing. */
+  ownType: TokenType | undefined;
+}
+
+/** Metadata keys on a group that are not children. */
+const META_KEYS = new Set(["$type", "$description", "$value", "$extensions"]);
+
+/** Flatten a token tree to raw entries, applying group `$type` inheritance. */
+function flatten(doc: TokenDocument): RawEntry[] {
+  const entries: RawEntry[] = [];
+
+  const walk = (node: any, prefix: string[], inheritedType: TokenType | undefined) => {
+    const groupType = (node?.$type as TokenType | undefined) ?? inheritedType;
+    for (const key of Object.keys(node)) {
+      if (META_KEYS.has(key)) continue;
+      const child = node[key];
+      const path = [...prefix, key];
+      if (isToken(child)) {
+        entries.push({
+          path: path.join("."),
+          token: child,
+          ownType: child.$type ?? groupType,
+        });
+      } else if (child && typeof child === "object") {
+        walk(child, path, groupType);
+      }
+    }
+  };
+
+  walk(doc, [], undefined);
+  return entries;
+}
+
+/**
+ * Resolve a token document into ordered, alias-free {@link ResolvedToken}s.
+ * Throws on a dangling alias or an alias cycle — the token equivalent of the
+ * resource compiler's dangling-FK / circular-dependency checks.
+ */
+export function resolveTokens(doc: TokenDocument): ResolvedToken[] {
+  const raw = flatten(doc);
+  const byPath = new Map(raw.map((e) => [e.path, e]));
+
+  // Resolve one path to its literal value + effective type, following aliases.
+  const resolveValue = (
+    path: string,
+    seen: string[],
+  ): { value: TokenValue; type: TokenType | undefined } => {
+    const entry = byPath.get(path);
+    if (!entry) {
+      throw new Error(
+        `Token "${seen[seen.length - 1] ?? path}" aliases unknown token "${path}".`,
+      );
+    }
+    const value = entry.token.$value;
+    if (isAlias(value)) {
+      const target = aliasTarget(value);
+      if (seen.includes(target)) {
+        throw new Error(
+          `Alias cycle detected: ${[...seen, target].join(" → ")}.`,
+        );
+      }
+      const resolved = resolveValue(target, [...seen, target]);
+      // A pure alias borrows its target's type when it has none of its own.
+      return { value: resolved.value, type: entry.ownType ?? resolved.type };
+    }
+    return { value, type: entry.ownType };
+  };
+
+  return raw.map(({ path, token }) => {
+    const value = token.$value;
+    const resolved = resolveValue(path, [path]);
+    const out: ResolvedToken = {
+      path,
+      type: resolved.type,
+      value: resolved.value,
+    };
+    if (isAlias(value)) out.aliasOf = aliasTarget(value);
+    if (token.$description) out.$description = token.$description;
+    return out;
+  });
+}
+
+/** Deep-merge `override` onto `base`, returning a new document (base untouched). */
+export function mergeTokens(
+  base: TokenDocument,
+  override: TokenDocument,
+): TokenDocument {
+  const out: any = Array.isArray(base) ? [...base] : { ...base };
+  for (const key of Object.keys(override)) {
+    const o = (override as any)[key];
+    const b = (out as any)[key];
+    if (
+      o &&
+      b &&
+      typeof o === "object" &&
+      typeof b === "object" &&
+      !isToken(o) &&
+      !isToken(b)
+    ) {
+      out[key] = mergeTokens(b, o);
+    } else {
+      out[key] = o;
+    }
+  }
+  return out;
+}
+
+/** The resolved base plus, per mode, the resolved base-merged-with-that-mode. */
+export interface ResolvedTheme {
+  base: ResolvedToken[];
+  modes: Record<string, ResolvedToken[]>;
+  defaultMode?: string;
+}
+
+/**
+ * Resolve a themed token set: the base tree, and every mode as the base
+ * deep-merged with that mode's overrides. Callers diff a mode against the base
+ * to emit only what changed.
+ */
+export function resolveTheme(themed: ThemedTokens): ResolvedTheme {
+  const base = resolveTokens(themed.tokens);
+  const modes: Record<string, ResolvedToken[]> = {};
+  for (const [name, overrides] of Object.entries(themed.modes ?? {})) {
+    modes[name] = resolveTokens(mergeTokens(themed.tokens, overrides));
+  }
+  return { base, modes, defaultMode: themed.defaultMode };
+}
+
+/**
+ * The CSS custom-property name for a token path.
+ * `color.brand.500` → `--color-brand-500`. Segments are lower-cased and any
+ * non-word character becomes `-`, so numeric and camelCase keys stay valid.
+ */
+export function cssVarName(path: string, prefix = ""): string {
+  const body = path
+    .split(".")
+    .map((s) => s.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase())
+    .join("-")
+    .replace(/[^a-z0-9-]+/g, "-");
+  return `--${prefix ? `${prefix}-` : ""}${body}`;
+}

package/src/tokens/studio.ts

@@ -0,0 +1,357 @@
+/**
+ * The design studio page — a self-contained, dependency-free HTML app that
+ * `rastack design` serves. It **showcases** the design system (colour swatches,
+ * type ramp, spacing, radii, shadows, and live component previews built from the
+ * tokens themselves) and lets you **edit** token values in place — with a live
+ * preview — then save them back to the source, or export the DTCG JSON / CSS.
+ *
+ * Pure: given a themed doc it returns an HTML string, so it renders identically
+ * whether served by the CLI or snapshotted in a test. The page talks to the CLI
+ * server over two tiny endpoints: `POST /save` (persist) and it embeds
+ * everything else it needs inline.
+ */
+
+import { emitCss, formatCssValue } from "./css";
+import { cssVarName, resolveTheme } from "./resolve";
+import { ResolvedToken, ThemedTokens } from "./types";
+
+/** A per-token descriptor handed to the browser for rendering + editing. */
+interface TokenView {
+  path: string;
+  cssVar: string;
+  type: string | undefined;
+  /** CSS declaration value for preview: `var(--alias)` or a literal. */
+  decl: string;
+  /** The formatted literal value (what a swatch/sample shows). */
+  literal: string;
+  aliasOf?: string;
+  description?: string;
+}
+
+function toView(prefix: string, tok: ResolvedToken): TokenView {
+  return {
+    path: tok.path,
+    cssVar: cssVarName(tok.path, prefix),
+    type: tok.type,
+    decl: tok.aliasOf ? `var(${cssVarName(tok.aliasOf, prefix)})` : formatCssValue(tok),
+    literal: formatCssValue(tok),
+    aliasOf: tok.aliasOf,
+    description: tok.$description,
+  };
+}
+
+export interface StudioOptions {
+  prefix?: string;
+  /** Whether the running server accepts `POST /save` (false for module sources). */
+  editable?: boolean;
+  title?: string;
+}
+
+/** Render the full design-studio HTML document for a themed token set. */
+export function renderStudio(themed: ThemedTokens, options: StudioOptions = {}): string {
+  const prefix = options.prefix ?? "";
+  const editable = options.editable !== false;
+  const title = options.title ?? "Design System";
+  const resolved = resolveTheme(themed);
+
+  const layers: Record<string, TokenView[]> = {
+    base: resolved.base.map((t) => toView(prefix, t)),
+  };
+  for (const [name, toks] of Object.entries(resolved.modes)) {
+    layers[name] = toks.map((t) => toView(prefix, t));
+  }
+
+  const modeNames = Object.keys(resolved.modes);
+  const css = emitCss(themed, { prefix });
+
+  const payload = {
+    title,
+    prefix,
+    editable,
+    defaultMode: resolved.defaultMode ?? null,
+    modeNames,
+    layers,
+    raw: themed,
+  };
+
+  return page(title, css, payload);
+}
+
+function page(title: string, css: string, payload: unknown): string {
+  const data = JSON.stringify(payload).replace(/</g, "\\u003c");
+  return `<!doctype html>
+<html lang="en" data-theme="${(payload as any).defaultMode ?? ""}">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>${escapeHtml(title)} · rastack design</title>
+<style id="tokens-css">${css}</style>
+<style>${STUDIO_CSS}</style>
+</head>
+<body>
+<div id="app"></div>
+<script id="studio-data" type="application/json">${data}</script>
+<script>${STUDIO_JS}</script>
+</body>
+</html>
+`;
+}
+
+function escapeHtml(s: string): string {
+  return s.replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" }[c] as string));
+}
+
+/* -- The studio's own chrome. Deliberately neutral so it frames, not fights,
+      the design system it is displaying. --------------------------------- */
+const STUDIO_CSS = `
+* { box-sizing: border-box; }
+body { margin: 0; font-family: var(--font-sans, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif);
+  background: #0d1117; color: #e6edf3; -webkit-font-smoothing: antialiased; }
+.studio-header { position: sticky; top: 0; z-index: 10; display: flex; align-items: center; gap: 16px;
+  padding: 14px 24px; background: #161b22ee; backdrop-filter: blur(8px); border-bottom: 1px solid #30363d; }
+.studio-header h1 { font-size: 15px; font-weight: 650; margin: 0; letter-spacing: .2px; }
+.studio-header .spacer { flex: 1; }
+.pill { font: inherit; font-size: 12px; padding: 6px 12px; border-radius: 999px; border: 1px solid #30363d;
+  background: #21262d; color: #e6edf3; cursor: pointer; }
+.pill.active { background: #388bfd33; border-color: #388bfd; color: #cae3ff; }
+.pill:hover { border-color: #58a6ff; }
+.btn { font: inherit; font-size: 12px; font-weight: 600; padding: 6px 14px; border-radius: 6px; border: 1px solid #30363d;
+  background: #21262d; color: #e6edf3; cursor: pointer; }
+.btn.primary { background: #238636; border-color: #2ea043; }
+.btn:disabled { opacity: .5; cursor: default; }
+.layout { max-width: 1180px; margin: 0 auto; padding: 28px 24px 96px; }
+section { margin: 40px 0 0; }
+section > h2 { font-size: 12px; text-transform: uppercase; letter-spacing: .12em; color: #8b949e; margin: 0 0 16px;
+  padding-bottom: 8px; border-bottom: 1px solid #21262d; }
+.grid { display: grid; gap: 14px; grid-template-columns: repeat(auto-fill, minmax(210px, 1fr)); }
+.card { background: #161b22; border: 1px solid #21262d; border-radius: 12px; padding: 14px; }
+.swatch { height: 56px; border-radius: 8px; border: 1px solid #ffffff1a; margin-bottom: 10px; }
+.tok-name { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 11.5px; color: #7ee787; word-break: break-all; }
+.tok-meta { font-size: 11px; color: #8b949e; margin-top: 2px; }
+.tok-alias { color: #d2a8ff; }
+.row { display: flex; align-items: center; gap: 8px; margin-top: 10px; }
+.row input[type=text] { flex: 1; min-width: 0; font: inherit; font-family: ui-monospace, monospace; font-size: 12px;
+  padding: 6px 8px; border-radius: 6px; border: 1px solid #30363d; background: #0d1117; color: #e6edf3; }
+.row input[type=color] { width: 34px; height: 30px; padding: 0; border: 1px solid #30363d; border-radius: 6px; background: none; }
+.bar { height: 12px; max-width: 100%; background: var(--_v); border-radius: 4px; }
+.radius-box { height: 56px; background: #388bfd33; border: 1px solid #58a6ff88; }
+.shadow-box { height: 56px; background: #ffffff; border-radius: 8px; margin: 6px 4px 12px; }
+.type-sample { font-size: 20px; margin: 6px 0; color: #e6edf3; }
+.preview { display: flex; flex-wrap: wrap; gap: 16px; align-items: flex-start; }
+.saved-toast { position: fixed; bottom: 20px; left: 50%; transform: translateX(-50%); background: #238636;
+  padding: 10px 18px; border-radius: 8px; font-size: 13px; opacity: 0; transition: opacity .25s; pointer-events: none; }
+.saved-toast.show { opacity: 1; }
+.dim-note { font-size: 11px; color: #6e7681; margin-top: 16px; }
+`;
+
+/* -- The studio client. Renders sections from the embedded payload, applies
+      edits live to :root, and posts the mutated doc back to the server. ---- */
+const STUDIO_JS = `
+(function () {
+  var data = JSON.parse(document.getElementById("studio-data").textContent);
+  var root = document.documentElement;
+  var activeLayer = data.defaultMode || "base";
+  var app = document.getElementById("app");
+
+  // Deep clone the raw doc so edits are collected without touching the payload.
+  var draft = JSON.parse(JSON.stringify(data.raw));
+  var dirty = false;
+
+  function tokenType(views, path) {
+    for (var i = 0; i < views.length; i++) if (views[i].path === path) return views[i].type;
+  }
+  function setPath(tree, path, value, type) {
+    var segs = path.split(".");
+    var node = tree;
+    for (var i = 0; i < segs.length - 1; i++) { node[segs[i]] = node[segs[i]] || {}; node = node[segs[i]]; }
+    var leaf = node[segs[segs.length - 1]] || {};
+    leaf.$value = value; if (type && !leaf.$type) leaf.$type = type;
+    node[segs[segs.length - 1]] = leaf;
+  }
+  function layerTree(layer) {
+    if (layer === "base") return draft.tokens;
+    draft.modes = draft.modes || {};
+    draft.modes[layer] = draft.modes[layer] || {};
+    return draft.modes[layer];
+  }
+
+  // Apply a layer's declarations to :root so the preview reflects it exactly.
+  function applyLayer(layer) {
+    var views = data.layers[layer] || data.layers.base;
+    views.forEach(function (v) { root.style.setProperty(v.cssVar, v.decl); });
+    root.setAttribute("data-theme", layer === "base" ? "" : layer);
+  }
+
+  function onEdit(view, raw) {
+    root.style.setProperty(view.cssVar, raw);
+    setPath(layerTree(activeLayer), view.path, raw, view.type);
+    dirty = true;
+    var btn = document.getElementById("save-btn");
+    if (btn) btn.disabled = false;
+  }
+
+  function group(views, pred) { return views.filter(pred); }
+
+  function sectionEl(title, nodes) {
+    if (!nodes.length) return null;
+    var s = document.createElement("section");
+    var h = document.createElement("h2"); h.textContent = title; s.appendChild(h);
+    var g = document.createElement("div"); g.className = "grid";
+    nodes.forEach(function (n) { g.appendChild(n); }); s.appendChild(g);
+    return s;
+  }
+
+  function cardShell(view, preview) {
+    var c = document.createElement("div"); c.className = "card";
+    if (preview) c.appendChild(preview);
+    var name = document.createElement("div"); name.className = "tok-name"; name.textContent = view.path;
+    c.appendChild(name);
+    var meta = document.createElement("div"); meta.className = "tok-meta";
+    meta.innerHTML = view.aliasOf ? '→ <span class="tok-alias">' + view.aliasOf + "</span>" : escapeHtml(view.literal);
+    c.appendChild(meta);
+    if (view.description) { var d = document.createElement("div"); d.className = "tok-meta"; d.textContent = view.description; c.appendChild(d); }
+    return c;
+  }
+
+  function editorRow(view, isColor) {
+    if (!data.editable || view.aliasOf) return null;
+    var row = document.createElement("div"); row.className = "row";
+    var text = document.createElement("input"); text.type = "text"; text.value = view.literal;
+    if (isColor) {
+      var color = document.createElement("input"); color.type = "color";
+      try { color.value = toHex(view.literal); } catch (e) {}
+      color.oninput = function () { text.value = color.value; onEdit(view, color.value); };
+      row.appendChild(color);
+    }
+    text.oninput = function () { onEdit(view, text.value); };
+    row.appendChild(text);
+    return row;
+  }
+
+  function render() {
+    var views = data.layers[activeLayer] || data.layers.base;
+    app.innerHTML = "";
+    app.appendChild(header());
+    var wrap = document.createElement("div"); wrap.className = "layout";
+
+    var colors = group(views, function (v) { return v.type === "color"; }).map(function (v) {
+      var sw = document.createElement("div"); sw.className = "swatch"; sw.style.background = "var(" + v.cssVar + ")";
+      var c = cardShell(v, sw); var ed = editorRow(v, true); if (ed) c.appendChild(ed); return c;
+    });
+    add(wrap, sectionEl("Colours", colors));
+
+    var isRadius = function (v) { return /radius|radii|round/i.test(v.path); };
+    var dims = group(views, function (v) { return v.type === "dimension" && !isRadius(v); }).map(function (v) {
+      var bar = document.createElement("div"); bar.className = "bar"; bar.style.width = "var(" + v.cssVar + ")"; bar.style.setProperty("--_v", "var(" + v.cssVar + ")");
+      bar.style.background = "#58a6ff";
+      var c = cardShell(v, bar); var ed = editorRow(v, false); if (ed) c.appendChild(ed); return c;
+    });
+    add(wrap, sectionEl("Spacing & dimensions", dims));
+
+    var radii = group(views, function (v) { return isRadius(v) && v.type !== "color"; });
+    // radii tokens are dimensions too; show a rounded-box preview for the named ones
+    var radiiCards = radii.map(function (v) {
+      var box = document.createElement("div"); box.className = "radius-box"; box.style.borderRadius = "var(" + v.cssVar + ")";
+      return cardShell(v, box);
+    });
+    add(wrap, sectionEl("Radii", radiiCards));
+
+    var shadows = group(views, function (v) { return v.type === "shadow"; }).map(function (v) {
+      var box = document.createElement("div"); box.className = "shadow-box"; box.style.boxShadow = "var(" + v.cssVar + ")";
+      return cardShell(v, box);
+    });
+    add(wrap, sectionEl("Shadows", shadows));
+
+    var fonts = group(views, function (v) { return v.type === "fontFamily" || v.type === "fontWeight"; }).map(function (v) {
+      var s = document.createElement("div"); s.className = "type-sample";
+      if (v.type === "fontFamily") s.style.fontFamily = "var(" + v.cssVar + ")"; else s.style.fontWeight = "var(" + v.cssVar + ")";
+      s.textContent = "The quick brown fox";
+      var c = cardShell(v, s); var ed = editorRow(v, false); if (ed) c.appendChild(ed); return c;
+    });
+    add(wrap, sectionEl("Typography", fonts));
+
+    var known = { color: 1, dimension: 1, shadow: 1, fontFamily: 1, fontWeight: 1 };
+    var other = group(views, function (v) { return !known[v.type]; }).map(function (v) {
+      var c = cardShell(v, null); var ed = editorRow(v, false); if (ed) c.appendChild(ed); return c;
+    });
+    add(wrap, sectionEl("Other tokens", other));
+
+    add(wrap, componentPreview());
+
+    var note = document.createElement("div"); note.className = "dim-note";
+    note.textContent = data.editable
+      ? "Edits apply live. Aliased tokens (→) follow their source; edit the source to change them. Save writes back to the token source."
+      : "Read-only: this source is a module, not JSON. Export to capture edits.";
+    wrap.appendChild(note);
+    app.appendChild(wrap);
+    applyLayer(activeLayer);
+  }
+
+  function componentPreview() {
+    var s = document.createElement("section");
+    var h = document.createElement("h2"); h.textContent = "Components"; s.appendChild(h);
+    var box = document.createElement("div"); box.className = "preview";
+    box.innerHTML =
+      '<button style="font:inherit;font-weight:600;padding:10px 18px;border:none;border-radius:var(--radius-md,8px);' +
+        'background:var(--color-accent,#4F6BFF);color:var(--color-on-accent,#fff);cursor:pointer">Primary action</button>' +
+      '<button style="font:inherit;font-weight:600;padding:10px 18px;border:1px solid var(--color-border,#30363d);' +
+        'border-radius:var(--radius-md,8px);background:transparent;color:var(--color-text,#e6edf3);cursor:pointer">Secondary</button>' +
+      '<div style="padding:16px;border-radius:var(--radius-lg,12px);background:var(--color-surface,#161b22);' +
+        'border:1px solid var(--color-border,#30363d);box-shadow:var(--shadow-md,none);min-width:200px">' +
+        '<div style="font-weight:650;color:var(--color-text,#e6edf3)">Card title</div>' +
+        '<div style="color:var(--color-text-muted,#8b949e);font-size:13px;margin-top:4px">Body copy in the muted text tone.</div></div>';
+    s.appendChild(box);
+    return s;
+  }
+
+  function header() {
+    var h = document.createElement("div"); h.className = "studio-header";
+    var title = document.createElement("h1"); title.textContent = data.title; h.appendChild(title);
+    var layers = ["base"].concat(data.modeNames);
+    layers.forEach(function (layer) {
+      var b = document.createElement("button"); b.className = "pill" + (layer === activeLayer ? " active" : "");
+      b.textContent = layer; b.onclick = function () { activeLayer = layer; render(); };
+      h.appendChild(b);
+    });
+    var sp = document.createElement("div"); sp.className = "spacer"; h.appendChild(sp);
+    var exp = document.createElement("button"); exp.className = "btn"; exp.textContent = "Export JSON";
+    exp.onclick = exportJson; h.appendChild(exp);
+    if (data.editable) {
+      var save = document.createElement("button"); save.className = "btn primary"; save.id = "save-btn";
+      save.textContent = "Save"; save.disabled = !dirty; save.onclick = saveDoc; h.appendChild(save);
+    }
+    return h;
+  }
+
+  function saveDoc() {
+    var btn = document.getElementById("save-btn"); btn.disabled = true; btn.textContent = "Saving…";
+    fetch("/save", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(draft) })
+      .then(function (r) { if (!r.ok) throw new Error(); return r.json(); })
+      .then(function () { dirty = false; btn.textContent = "Save"; toast("Saved & recompiled"); })
+      .catch(function () { btn.disabled = false; btn.textContent = "Save"; toast("Save failed"); });
+  }
+
+  function exportJson() {
+    var blob = new Blob([JSON.stringify(draft, null, 2)], { type: "application/json" });
+    var a = document.createElement("a"); a.href = URL.createObjectURL(blob); a.download = "tokens.json"; a.click();
+  }
+
+  function toast(msg) {
+    var el = document.createElement("div"); el.className = "saved-toast show"; el.textContent = msg; document.body.appendChild(el);
+    setTimeout(function () { el.classList.remove("show"); setTimeout(function () { el.remove(); }, 300); }, 1600);
+  }
+
+  function add(parent, el) { if (el) parent.appendChild(el); }
+  function escapeHtml(s) { return String(s).replace(/[&<>"]/g, function (c) { return { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" }[c]; }); }
+  function toHex(v) {
+    v = (v || "").trim();
+    if (/^#([0-9a-f]{6})$/i.test(v)) return v;
+    if (/^#([0-9a-f]{3})$/i.test(v)) return "#" + v.slice(1).split("").map(function (c) { return c + c; }).join("");
+    var m = v.match(/rgba?\\(([^)]+)\\)/i);
+    if (m) { var p = m[1].split(",").map(function (x) { return parseInt(x, 10); }); return "#" + p.slice(0, 3).map(function (n) { return ("0" + n.toString(16)).slice(-2); }).join(""); }
+    return "#000000";
+  }
+
+  render();
+})();
+`;