rastack 0.0.23 → 0.0.25

package/dist/tokens/types.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Design-token model — the **W3C Design Tokens (DTCG) format**.
+ *
+ * A design token is the smallest, named, platform-agnostic decision about how
+ * the UI looks: a colour, a spacing step, a radius, a font family. The DTCG
+ * community-group spec (https://tr.designtokens.org) is the industry standard
+ * serialization: a nested JSON tree of **groups** whose leaves are **tokens**,
+ * each carrying a `$value`, an optional `$type`, and an optional
+ * `$description`. Values may be literals or **aliases** — a `"{group.token}"`
+ * reference to another token.
+ *
+ * ```jsonc
+ * {
+ *   "color": {
+ *     "$type": "color",
+ *     "brand": { "500": { "$value": "#4F6BFF" } },
+ *     "text":  { "$value": "{color.brand.500}" }   // alias
+ *   }
+ * }
+ * ```
+ *
+ * This module is the pure data model shared by the compiler
+ * (`tools/src/tokens/{resolve,css,ts}.ts`) and the React runtime
+ * (`rastack/theme`). It has no filesystem or React dependency, so it builds for
+ * the browser exactly like `rastack/define`.
+ */
+/** The DTCG `$type`s this framework understands. */
+export type TokenType = "color" | "dimension" | "fontFamily" | "fontWeight" | "duration" | "cubicBezier" | "number" | "shadow" | "border" | "typography" | "transition";
+/** A shadow token value (single shadow or a stack of them). */
+export interface ShadowValue {
+    offsetX: string | number;
+    offsetY: string | number;
+    blur?: string | number;
+    spread?: string | number;
+    color: string;
+    inset?: boolean;
+}
+/** Anything that can appear as a token `$value` (including aliases as strings). */
+export type TokenValue = string | number | boolean | ShadowValue | ShadowValue[] | string[] | Record<string, unknown>;
+/** A single design token — a group leaf. Identified by the presence of `$value`. */
+export interface DesignToken {
+    $value: TokenValue;
+    $type?: TokenType;
+    $description?: string;
+    $extensions?: Record<string, unknown>;
+}
+/**
+ * A group node: named children (tokens or nested groups) plus optional group
+ * metadata. `$type` set on a group is **inherited** by descendant tokens that
+ * don't declare their own — the standard DTCG type-inheritance rule.
+ *
+ * Typed loosely (`any` children) on purpose: the tree is arbitrary-depth data,
+ * mirroring how the codebase types OpenAPI documents.
+ */
+export interface TokenGroup {
+    $type?: TokenType;
+    $description?: string;
+    [child: string]: DesignToken | TokenGroup | TokenType | string | undefined;
+}
+/** The root of a token tree. */
+export type TokenDocument = TokenGroup;
+/**
+ * A themeable token document: a base tree plus named **modes** (e.g. `light`,
+ * `dark`) that override a subset of tokens. Modes compile to CSS selector
+ * scopes, so a running app flips theme by toggling one attribute.
+ */
+export interface ThemedTokens {
+    /** Base tokens — the values that apply in every mode. */
+    tokens: TokenDocument;
+    /** Per-mode overrides, deep-merged over the base. */
+    modes?: Record<string, TokenDocument>;
+    /** Which mode is the default (emitted onto `:root`). */
+    defaultMode?: string;
+}
+/** A token after alias resolution and `$type` inheritance — ready to emit. */
+export interface ResolvedToken {
+    /** Dotted path, e.g. `color.brand.500`. */
+    path: string;
+    /** The token's `$type` (inherited or inferred). */
+    type: TokenType | undefined;
+    /** The literal value with every alias followed to its source. */
+    value: TokenValue;
+    /**
+     * If this token is a direct alias of another, the target's dotted path.
+     * Emitters use it to preserve the reference (CSS `var(--target)`), so theming
+     * cascades instead of being flattened away.
+     */
+    aliasOf?: string;
+    $description?: string;
+}
+/** True when a node is a token leaf (has `$value`) rather than a group. */
+export declare function isToken(node: unknown): node is DesignToken;

package/dist/tokens/types.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * Design-token model — the **W3C Design Tokens (DTCG) format**.
+ *
+ * A design token is the smallest, named, platform-agnostic decision about how
+ * the UI looks: a colour, a spacing step, a radius, a font family. The DTCG
+ * community-group spec (https://tr.designtokens.org) is the industry standard
+ * serialization: a nested JSON tree of **groups** whose leaves are **tokens**,
+ * each carrying a `$value`, an optional `$type`, and an optional
+ * `$description`. Values may be literals or **aliases** — a `"{group.token}"`
+ * reference to another token.
+ *
+ * ```jsonc
+ * {
+ *   "color": {
+ *     "$type": "color",
+ *     "brand": { "500": { "$value": "#4F6BFF" } },
+ *     "text":  { "$value": "{color.brand.500}" }   // alias
+ *   }
+ * }
+ * ```
+ *
+ * This module is the pure data model shared by the compiler
+ * (`tools/src/tokens/{resolve,css,ts}.ts`) and the React runtime
+ * (`rastack/theme`). It has no filesystem or React dependency, so it builds for
+ * the browser exactly like `rastack/define`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isToken = isToken;
+/** True when a node is a token leaf (has `$value`) rather than a group. */
+function isToken(node) {
+    return (typeof node === "object" &&
+        node !== null &&
+        Object.prototype.hasOwnProperty.call(node, "$value"));
+}

package/jest.config.cjs

@@ -3,4 +3,10 @@ module.exports = {
   testEnvironment: 'node',
   testMatch: ['**/test/**/*.spec.ts'],
   moduleFileExtensions: ['ts', 'js'],
+  // Let executed test fixtures import the package by its published subpath
+  // names, the same way a consumer would (the resource compiler resolves these
+  // via its own ts.Program; these mappings are for code jest actually runs).
+  moduleNameMapper: {
+    '^rastack/tokens$': '<rootDir>/tokens.ts',
+  },
 };

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "rastack",
-  "version": "0.0.23",
+  "version": "0.0.25",
   "description": "",
   "main": "runtime.ts",
   "types": "runtime.ts",
   "bin": {
-    "rastack": "dist/rastack.js"
+    "rastack": "dist/rastack.js",
+    "ras": "dist/rastack.js"
   },
   "publishConfig": {
     "access": "public"

package/src/rastack-design.ts

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+
+/**
+ * `rastack design` (aka `ras design`) — a live design-system studio.
+ *
+ *   rastack design [input] [--port <n>] [--prefix <p>]
+ *
+ * Boots a tiny, dependency-free HTTP server that serves an interactive page
+ * showcasing the design system — colour swatches, the type ramp, spacing,
+ * radii, shadows, and component previews built from the tokens themselves — and
+ * lets you edit token values in place with a live preview. Editing a `.json`
+ * source and hitting **Save** writes it back and recompiles `tokens.css` /
+ * `tokens.ts`, so the rest of the app picks the change up on reload.
+ *
+ * In keeping with the local-first ethos (the whole API runs in the browser via
+ * WASM), the studio needs no build step and no external dependencies.
+ */
+
+import * as http from "http";
+import * as path from "path";
+import { compileTokens, loadTokens } from "./tokens/compile";
+import { renderStudio } from "./tokens/studio";
+import { ThemedTokens } from "./tokens/types";
+
+const DEFAULT_INPUT = "tokens/theme.tokens.json";
+const DEFAULT_OUT = ".rastack";
+
+interface Args {
+  input: string;
+  port: number;
+  prefix: string;
+  outDir: string;
+}
+
+function parseArgs(argv: string[]): Args {
+  const positional: string[] = [];
+  let port = 4321;
+  let prefix = "";
+  let outDir = DEFAULT_OUT;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--port") port = Number(argv[++i]) || port;
+    else if (a === "--prefix") prefix = argv[++i] ?? "";
+    else if (a === "--out") outDir = argv[++i] ?? outDir;
+    else positional.push(a);
+  }
+  return { input: positional[0] || DEFAULT_INPUT, port, prefix, outDir };
+}
+
+function main(argv: string[]): void {
+  const args = parseArgs(argv);
+  const isJson = args.input.endsWith(".json");
+
+  let themed: ThemedTokens;
+  try {
+    themed = loadTokens(args.input);
+  } catch (err) {
+    console.error(`  ✗ ${(err as Error).message}`);
+    process.exit(1);
+    return;
+  }
+
+  const server = http.createServer((req, res) => {
+    // Only edits to a JSON source can be written back safely (a module source
+    // is code, not data).
+    if (req.method === "POST" && req.url === "/save") {
+      if (!isJson) {
+        res.writeHead(400).end("Editing is only supported for .json token sources.");
+        return;
+      }
+      let body = "";
+      req.on("data", (c) => (body += c));
+      req.on("end", () => {
+        try {
+          const next = JSON.parse(body) as ThemedTokens;
+          require("fs").writeFileSync(
+            path.resolve(args.input),
+            JSON.stringify(next, null, 2) + "\n",
+          );
+          themed = next;
+          // Recompile so tokens.css / tokens.ts reflect the save immediately.
+          compileTokens(args.input, args.outDir, { prefix: args.prefix });
+          res.writeHead(200, { "Content-Type": "application/json" }).end(`{"ok":true}`);
+          console.log(`  ↳ saved ${args.input} & recompiled`);
+        } catch (err) {
+          res.writeHead(500).end((err as Error).message);
+        }
+      });
+      return;
+    }
+
+    if (req.method === "GET" && (req.url === "/" || req.url === "/index.html")) {
+      const html = renderStudio(themed, {
+        prefix: args.prefix,
+        editable: isJson,
+        title: "Design System",
+      });
+      res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" }).end(html);
+      return;
+    }
+
+    res.writeHead(404).end("Not found");
+  });
+
+  server.listen(args.port, () => {
+    console.log(
+      `\n  rastack design — studio for ${args.input}\n` +
+        `  ▸ http://localhost:${args.port}\n` +
+        (isJson ? `  Edits Save back to ${args.input}.\n` : `  Read-only (module source).\n`) +
+        `\n  Press Ctrl+C to stop.\n`,
+    );
+  });
+}
+
+if (require.main === module) {
+  main(process.argv.slice(2));
+}

package/src/rastack-tokens.ts

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+/**
+ * `rastack tokens` — compile a design-token source into shippable artifacts.
+ *
+ *   rastack tokens [input] [outDir] [--prefix <p>]
+ *
+ * `input`  a DTCG `.json` file, or a compiled module that default-exports
+ *          `defineTokens(...)` (default: `tokens/theme.tokens.json`).
+ * `outDir` where to write `tokens.{rastack.json,css,ts}` (default: `.rastack`).
+ *
+ * Mirrors `rastack compile`: TypeScript-authored source → canonical JSON +
+ * ready-to-use outputs, with alias/cycle errors surfaced before anything is
+ * written.
+ */
+
+import { compileTokens } from "./tokens/compile";
+
+const DEFAULT_INPUT = "tokens/theme.tokens.json";
+const DEFAULT_OUT = ".rastack";
+
+function main(argv: string[]): void {
+  const positional: string[] = [];
+  let prefix = "";
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--prefix") prefix = argv[++i] ?? "";
+    else positional.push(argv[i]);
+  }
+  const input = positional[0] || DEFAULT_INPUT;
+  const outDir = positional[1] || DEFAULT_OUT;
+
+  try {
+    const { themed, files } = compileTokens(input, outDir, { prefix });
+    const modes = Object.keys(themed.modes ?? {});
+    console.log(
+      `✓ compiled design tokens${modes.length ? ` (${modes.length} mode${modes.length > 1 ? "s" : ""}: ${modes.join(", ")})` : ""} → ${files.join(", ")}`,
+    );
+  } catch (err) {
+    console.error(`  ✗ ${(err as Error).message}`);
+    process.exit(1);
+  }
+}
+
+if (require.main === module) {
+  main(process.argv.slice(2));
+}

package/src/rastack.ts

@@ -9,6 +9,8 @@
  *   rastack list    [resourcesDir]              Print resources, fields and relations
  *   rastack urls    [resourcesDir]              Print the generated /api/{app}/v1/{model}/ routes
  *   rastack generate [--schema-only]            Generate typed hooks from OpenAPI
+ *   rastack tokens  [input] [outDir]            Compile design tokens → CSS vars + typed theme
+ *   rastack design  [input] [--port n]          Live design-system studio (showcase + edit)
  *   rastack serve   [--warehouse dir]           Run the Rust API over an Iceberg warehouse
  *   rastack admin   [--warehouse dir]           Run the Rust admin (Django-admin-style DB browser)
  *   rastack wasm                                Compile the API to WebAssembly (in-browser local dev)
@@ -74,6 +76,14 @@ switch (command) {
     // Compile the API to WebAssembly for in-browser local dev.
     run("rastack-wasm-build.js", rest);
     break;
+  case "tokens":
+    // Design tokens → CSS custom properties + typed theme.
+    run("rastack-tokens.js", rest);
+    break;
+  case "design":
+    // Live design-system studio (showcase + inspect + edit).
+    run("rastack-design.js", rest);
+    break;
   case "scan":
     run("scan.js");
     break;
@@ -92,6 +102,8 @@ switch (command) {
         `  rastack compile [resourcesDir] [outDir]\n` +
         `  rastack check | list | urls [resourcesDir]\n` +
         `  rastack generate [--schema-only]\n` +
+        `  rastack tokens  [input] [outDir] [--prefix p]  Compile design tokens → CSS vars + typed theme\n` +
+        `  rastack design  [input] [--port n]             Live design-system studio (showcase + edit)\n` +
         `  rastack serve | admin [--warehouse dir]\n` +
         `  rastack wasm                                Compile the API to WebAssembly (browser local dev)\n` +
         `  rastack scan   [files...] [--fail-on-pii]\n` +

package/src/tokens/color.ts

@@ -0,0 +1,74 @@
+/**
+ * Tiny, dependency-free colour maths — just enough to turn one brand colour into
+ * a full tint/shade scale and to pick a readable on-colour. Used by
+ * {@link defineTheme} so a non-designer specifies a single hex and gets a
+ * complete, sensible palette.
+ */
+
+interface Rgb {
+  r: number;
+  g: number;
+  b: number;
+}
+
+/** Parse `#rgb` / `#rrggbb` (with or without `#`) into 0–255 channels. */
+export function parseHex(hex: string): Rgb {
+  let h = hex.trim().replace(/^#/, "");
+  if (h.length === 3) h = h.split("").map((c) => c + c).join("");
+  if (!/^[0-9a-fA-F]{6}$/.test(h)) {
+    throw new Error(`Not a hex colour: "${hex}" (use e.g. "#4F6BFF").`);
+  }
+  return {
+    r: parseInt(h.slice(0, 2), 16),
+    g: parseInt(h.slice(2, 4), 16),
+    b: parseInt(h.slice(4, 6), 16),
+  };
+}
+
+function toHex({ r, g, b }: Rgb): string {
+  const h = (n: number) =>
+    ("0" + Math.round(Math.max(0, Math.min(255, n))).toString(16)).slice(-2);
+  return `#${h(r)}${h(g)}${h(b)}`.toUpperCase();
+}
+
+/** Blend two colours; `amount` is how far from `a` toward `b` (0–1). */
+export function mix(a: string, b: string, amount: number): string {
+  const x = parseHex(a);
+  const y = parseHex(b);
+  return toHex({
+    r: x.r + (y.r - x.r) * amount,
+    g: x.g + (y.g - x.g) * amount,
+    b: x.b + (y.b - x.b) * amount,
+  });
+}
+
+/** Relative luminance (0 dark – 1 light), for contrast decisions. */
+export function luminance(hex: string): number {
+  const { r, g, b } = parseHex(hex);
+  const lin = (c: number) => {
+    const s = c / 255;
+    return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
+  };
+  return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+}
+
+/** Black or white — whichever is readable on `hex`. */
+export function readableOn(hex: string): string {
+  return luminance(hex) > 0.45 ? "#0B1020" : "#FFFFFF";
+}
+
+/**
+ * How much to mix a seed toward white (tints) or black (shades) at each step of
+ * a Tailwind-style 50–950 scale. `500` is the seed itself.
+ */
+const TINT: Record<number, number> = { 50: 0.95, 100: 0.9, 200: 0.78, 300: 0.62, 400: 0.34 };
+const SHADE: Record<number, number> = { 600: 0.12, 700: 0.28, 800: 0.44, 900: 0.6, 950: 0.74 };
+
+/** Build a `{ 50…950 }` colour scale from a single seed colour. */
+export function scale(seed: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [step, amt] of Object.entries(TINT)) out[step] = mix(seed, "#FFFFFF", amt);
+  out["500"] = toHex(parseHex(seed));
+  for (const [step, amt] of Object.entries(SHADE)) out[step] = mix(seed, "#000000", amt);
+  return out;
+}

package/src/tokens/compile.ts

@@ -0,0 +1,85 @@
+/**
+ * Token compilation with file IO — the engine behind `rastack tokens`.
+ *
+ * Loads a token source (canonical DTCG `.json`, or a `.js`/compiled module that
+ * default-exports a {@link ThemedTokens}), resolves it, and writes three
+ * artifacts:
+ *
+ *   - `tokens.rastack.json` — the canonical, resolved DTCG document (the manifest
+ *     analogue: one file that fully describes the design system).
+ *   - `tokens.css` — CSS custom properties with per-mode selector scopes.
+ *   - `tokens.ts` — the typed theme tree + `TokenPath` union.
+ *
+ * Kept separate from the pure core (`./index.ts`) so the browser runtime never
+ * pulls in `fs`.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import { defineTokens } from "./define";
+import { CssOptions, emitCss } from "./css";
+import { resolveTheme } from "./resolve";
+import { emitTs } from "./ts";
+import { ThemedTokens } from "./types";
+
+export interface TokenCompileOptions extends CssOptions {}
+
+export interface TokenCompileResult {
+  themed: ThemedTokens;
+  files: string[];
+}
+
+/**
+ * Load a token source into a normalised {@link ThemedTokens}. `.json` is parsed
+ * as DTCG; any other extension is `require`d and its default export (or the
+ * module itself) is taken — so a `defineTokens(...)` module works once compiled
+ * to JS (or when a `.ts` loader such as ts-node is registered).
+ */
+export function loadTokens(file: string): ThemedTokens {
+  const abs = path.resolve(file);
+  if (!fs.existsSync(abs)) throw new Error(`No such tokens file: ${file}`);
+
+  if (abs.endsWith(".json")) {
+    const raw = JSON.parse(fs.readFileSync(abs, "utf8"));
+    // Accept either the themed shape or a bare DTCG tree.
+    return defineTokens(raw);
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const mod = require(abs);
+  const exported = mod?.default ?? mod;
+  return defineTokens(exported);
+}
+
+/** The canonical, resolved DTCG document written to `tokens.rastack.json`. */
+export function canonicalDocument(themed: ThemedTokens): unknown {
+  return {
+    $description: "Compiled by `rastack tokens`. The resolved design system.",
+    ...themed.tokens,
+    ...(themed.modes && Object.keys(themed.modes).length
+      ? { $extensions: { "com.rastack.modes": themed.modes, "com.rastack.defaultMode": themed.defaultMode } }
+      : {}),
+  };
+}
+
+/** Compile a token source file to `tokens.{rastack.json,css,ts}` in `outDir`. */
+export function compileTokens(
+  file: string,
+  outDir: string,
+  options: TokenCompileOptions = {},
+): TokenCompileResult {
+  const themed = loadTokens(file);
+  // Resolve eagerly so alias/cycle errors surface here, before writing anything.
+  resolveTheme(themed);
+
+  fs.mkdirSync(outDir, { recursive: true });
+  const jsonPath = path.join(outDir, "tokens.rastack.json");
+  const cssPath = path.join(outDir, "tokens.css");
+  const tsPath = path.join(outDir, "tokens.ts");
+
+  fs.writeFileSync(jsonPath, JSON.stringify(canonicalDocument(themed), null, 2) + "\n");
+  fs.writeFileSync(cssPath, emitCss(themed, options));
+  fs.writeFileSync(tsPath, emitTs(resolveTheme(themed).base, options));
+
+  return { themed, files: [jsonPath, cssPath, tsPath] };
+}

package/src/tokens/css.ts

@@ -0,0 +1,138 @@
+/**
+ * CSS custom-property emitter — the primary, framework-agnostic output.
+ *
+ * Design tokens become CSS variables under `:root`, and each **mode** becomes a
+ * selector scope that overrides only the tokens it changes. A running app then
+ * switches theme by toggling one attribute (`<html data-theme="dark">`), and
+ * every `var(--…)` reference recascades for free. Aliases are preserved as
+ * `var(--target)` rather than inlined, so overriding a base token
+ * automatically flows through everything that references it.
+ */
+
+import { cssVarName, ResolvedTheme, resolveTheme } from "./resolve";
+import { ThemedTokens, ResolvedToken, ShadowValue, TokenValue } from "./types";
+
+export interface CssOptions {
+  /** Prefix every variable: `prefix: "rs"` → `--rs-color-brand-500`. */
+  prefix?: string;
+  /**
+   * How a mode maps to a selector. Given the mode name, return the selector
+   * whose block holds that mode's overrides. Default: `[data-theme="<mode>"]`,
+   * with the default mode also written to `:root`.
+   */
+  modeSelector?: (mode: string) => string;
+  /** Root selector for the base tokens. Default `:root`. */
+  rootSelector?: string;
+}
+
+/** Render one CSS number/length; bare numbers stay unitless. */
+function dim(v: string | number): string {
+  return typeof v === "number" ? `${v}px` : v;
+}
+
+/** Quote a font-family entry only when it contains whitespace. */
+function fontEntry(name: string): string {
+  return /\s/.test(name) && !/^["']/.test(name) ? `"${name}"` : name;
+}
+
+function shadow(s: ShadowValue): string {
+  const parts = [
+    s.inset ? "inset" : "",
+    dim(s.offsetX),
+    dim(s.offsetY),
+    s.blur != null ? dim(s.blur) : "",
+    s.spread != null ? dim(s.spread) : "",
+    s.color,
+  ];
+  return parts.filter(Boolean).join(" ");
+}
+
+/** Format a resolved token's literal value as a CSS declaration value. */
+export function formatCssValue(token: ResolvedToken): string {
+  const { type, value } = token;
+  switch (type) {
+    case "fontFamily":
+      return (Array.isArray(value) ? (value as string[]) : [value as string])
+        .map(fontEntry)
+        .join(", ");
+    case "cubicBezier":
+      return `cubic-bezier(${(value as unknown as number[]).join(", ")})`;
+    case "shadow":
+      return (Array.isArray(value) ? (value as ShadowValue[]) : [value as ShadowValue])
+        .map(shadow)
+        .join(", ");
+    case "dimension":
+      return dim(value as string | number);
+    case "number":
+    case "fontWeight":
+    case "color":
+    case "duration":
+      return String(value);
+    default:
+      return typeof value === "object" ? JSON.stringify(value) : String(value);
+  }
+}
+
+/** The right-hand side of a token's CSS declaration: `var(--alias)` or a literal. */
+function declValue(token: ResolvedToken, prefix: string): string {
+  if (token.aliasOf) return `var(${cssVarName(token.aliasOf, prefix)})`;
+  return formatCssValue(token);
+}
+
+function block(
+  selector: string,
+  tokens: ResolvedToken[],
+  prefix: string,
+  indent = "  ",
+): string {
+  const lines = tokens.map(
+    (tok) => `${indent}${cssVarName(tok.path, prefix)}: ${declValue(tok, prefix)};`,
+  );
+  return `${selector} {\n${lines.join("\n")}\n}`;
+}
+
+/** Only the tokens whose emitted declaration differs from the base. */
+function changed(
+  base: ResolvedToken[],
+  mode: ResolvedToken[],
+  prefix: string,
+): ResolvedToken[] {
+  const baseDecl = new Map(base.map((t) => [t.path, declValue(t, prefix)]));
+  return mode.filter((t) => baseDecl.get(t.path) !== declValue(t, prefix));
+}
+
+/** Emit CSS custom properties for a resolved theme (base + mode scopes). */
+export function emitCssFromResolved(
+  resolved: ResolvedTheme,
+  options: CssOptions = {},
+): string {
+  const prefix = options.prefix ?? "";
+  const root = options.rootSelector ?? ":root";
+  const modeSelector = options.modeSelector ?? ((m) => `[data-theme="${m}"]`);
+
+  const blocks: string[] = [
+    `/* Generated by \`rastack tokens\` — do not edit by hand. */`,
+  ];
+
+  // Base + the default mode both live on :root, so an app with no attribute set
+  // still gets a complete, sensible theme.
+  const defaultMode = resolved.defaultMode;
+  const rootTokens =
+    defaultMode && resolved.modes[defaultMode]
+      ? resolved.modes[defaultMode]
+      : resolved.base;
+  blocks.push(block(root, rootTokens, prefix));
+
+  for (const [name, tokens] of Object.entries(resolved.modes)) {
+    const diff = changed(resolved.base, tokens, prefix);
+    if (!diff.length) continue;
+    blocks.push(block(modeSelector(name), diff, prefix));
+  }
+
+  return blocks.join("\n\n") + "\n";
+}
+
+/** Emit CSS custom properties for a themed token document. */
+export function emitCss(themed: ThemedTokens, options: CssOptions = {}): string {
+  return emitCssFromResolved(resolveTheme(themed), options);
+}