@natjswenson/press 0.1.0

package/brand/laws.md

@@ -0,0 +1,105 @@
+# The PRESS laws
+
+PRESS is a **brand system, not a template**. Nothing here tells you what to
+build; it tells you what every thing you build must obey so that a morning
+brief, a city profile, a budget report, a résumé, a LinkedIn card and a dev-log
+cover read as one publication.
+
+The values live in `tokens.json` and are generated into consumers. These are the
+rules the numbers can't carry.
+
+## 1. The accent law
+
+There is **one** loud color. It is spent **once or twice in a document** — on
+the single most notable figure, and on the stamp. Never as decoration, never on
+a whole row of things, never to mean "good" or "bad".
+
+Adding more orange does not make it louder. It makes it quieter.
+
+Corollaries that have each already cost a real bug:
+
+- **No traffic lights.** Over-budget, failed, missed, at-risk — none of these get
+  a hue. They get a text mark and a label, which survive greyscale printing and
+  every form of color vision. `budget` carries over-budget on a `⚠︎` and a tick,
+  not on red.
+- **Emoji glyphs are a second loud color.** A bare `⚠` renders as a *colored*
+  emoji in Chromium. Always use the text-presentation form from
+  `tokens.marks.warn` (`⚠︎`, U+26A0 U+FE0E). The HTML looks fine and the PDF is
+  wrong, so nothing catches this but the lint.
+- **The one exception** is a two-subject comparison, where the subjects *are* the
+  document (city A vs city B). There the accent identifies one subject
+  throughout, because the alternative is asking the reader to match a hue from
+  memory. A legend is mandatory when this exception is taken.
+
+## 2. Structure is rules and whitespace
+
+**No rounded corners. No shadows. No gradients. No fills. No boxes inside
+boxes. No zebra striping.**
+
+That is not minimalism for its own sake, and it is not an oversight to be
+"fixed" later — it is the brand. Structure is carried by:
+
+- **ink rules** — 8px above a masthead, 2px between sections, 1px under a row;
+- **whitespace** — grouping is done by proximity, not by drawing a container;
+- **typographic weight** — 900 display sans against 400 serif italic.
+
+The single allowed radius is a circular avatar in the colophon, because a
+cropped photograph is not a container.
+
+## 3. Three voices, never mixed inside an element
+
+| Voice | Face | Carries |
+|---|---|---|
+| **Structure** | display sans, 800–900, tight tracking (`-0.02` to `-0.03em`) | names, headlines, section titles, numerals |
+| **Commentary** | serif italic, `dim` | standfirsts, captions, marginal notes, asides |
+| **Data** | mono, tracked caps at small sizes | labels, dates, URLs, tables, terminal output, provenance |
+
+Tones and verdicts are typographic — ink vs dim, roman vs italic — because that
+is what is left once the accent law has taken color away.
+
+## 4. Tracking has a hard ceiling
+
+`letter-spacing` above **0.10em** silently breaks PDF text extraction: pdf.js
+returns the string with spaces injected between characters, and poppler shows
+nothing wrong, so a résumé that looks perfect becomes unparseable to an ATS.
+`tokens.limits.max_letter_spacing_em` is the ceiling and `press lint` enforces
+it. Tracked caps get their emphasis from size and weight, not from more space.
+
+**The ceiling protects extraction, not taste**, so it binds only where a machine
+reads the text back — PDFs and HTML pages. A rasterised card is pixels by the
+time anyone sees it, and the card set runs its eyebrow at `.16em` deliberately.
+Lint those with `--raster` (or `textExtractable: false`).
+
+## 5. Every fill must be legible or labelled
+
+The ink ramp (`derived.fill_steps`) is **sequential** — monotonic in lightness —
+and encodes magnitude only, never identity. It is capped at three steps because
+the lighter extensions drop below 3:1 against cream, and a fill nobody can see
+is not worth the exception.
+
+It is deliberately **not** a categorical palette. Run through the `dataviz`
+skill's `validate_palette.js` it fails the chroma floor and the adjacent-pair
+floor, which is the correct result for a near-neutral ramp and exactly why
+identity here comes from direct labels rather than hue. Anything needing more
+categories uses ranked bars, which need no categorical encoding at all.
+
+## 6. A missing brand file must never break a render
+
+Every consumer's theme loader deep-merges an optional local override file over
+the defaults and **falls back silently on any error**. A report in the wrong
+colors beats a report that didn't generate. This is why the generated loader is
+part of the region rather than something each consumer reimplements.
+
+## 7. Identity marks
+
+- **Stamp** — a rotated (`-4deg`) square, accent border, accent initials from
+  `tokens.identity.stamp`. It appears once, in the masthead.
+- **Eyebrow** — tracked-caps mono: `{BRAND_LINE} · {DOCUMENT KIND} · {date}`.
+- **Byline** — right-aligned, dim, mono, from `tokens.identity.byline`.
+- **Colophon** — the closing line. What the document is for, or what happened.
+
+## What PRESS does not decide
+
+Layout, component choice, and composition are the medium's business. A poster
+card, a two-column report and a résumé share these laws and share nothing else.
+See `components.md` for the vocabulary they *do* share by name.

package/brand/tokens.json

@@ -0,0 +1,56 @@
+{
+  "$comment": "THE source of truth for the PRESS brand. Every color, stack and identity default in every artifact Nate produces is generated from this file. Do not hand-copy these values into a consumer — declare the consumer in targets.json and run `press emit` instead. See laws.md for what the values MEAN and why there are so few of them.",
+  "name": "press",
+  "schema": 1,
+  "colors": {
+    "paper": "#F5F0E6",
+    "paper_surface": "#ECE5D6",
+    "paper_elevated": "#E4DCCA",
+    "ink": "#181510",
+    "dim": "#6E675C",
+    "accent": "#E8501F",
+    "rule": "#181510",
+    "ink_mid": "#4A423A",
+    "ink_faint": "#8A8272"
+  },
+  "terminal": {
+    "$comment": "The dark panel is the ONE place the old dark palette survives, and only inside a .term element. This quartet never appears on paper.",
+    "term_bg": "#141A26",
+    "term_text": "#EFE9DC",
+    "term_dim": "#8A8478",
+    "term_hot": "#FF8A5C",
+    "term_prompt": "#1E2738"
+  },
+  "color_notes": {
+    "paper": "Warm cream. Flat — never gradiented, never textured.",
+    "paper_surface": "One step down from paper, for a panel that must separate from the page without a border. Still flat.",
+    "paper_elevated": "Two steps down. The deepest paper tone; below this, use an ink rule instead.",
+    "ink": "Near-black. Text, headlines, and every structural rule.",
+    "dim": "Muted secondary text; the serif commentary voice's color.",
+    "accent": "THE one loud color. Spent once or twice per document, never as decoration.",
+    "rule": "Rules are ink, named separately so an override can soften them without touching text color.",
+    "ink_mid": "Mid ink step: a second series, a stacked-bar segment, a bar track.",
+    "ink_faint": "Decorative only — a faint element inside an illustration. Never body text, never a headline."
+  },
+  "derived": {
+    "hair_alpha": 0.18,
+    "fill_steps": ["ink", "ink_mid", "dim"]
+  },
+  "fonts": {
+    "$comment": "The union of every consumer's stack. Fallbacks are additive, so the richest chain is the canonical one — the résumé's print-tuned stacks were the deepest and became these. Single quotes so the same string is valid CSS and needs no escaping in a Python literal.",
+    "display_stack": "-apple-system, BlinkMacSystemFont, 'Segoe UI', Inter, Roboto, 'Helvetica Neue', Arial, sans-serif",
+    "serif_stack": "'New York', ui-serif, Georgia, 'Iowan Old Style', 'Times New Roman', serif",
+    "mono_stack": "ui-monospace, 'SF Mono', 'Cascadia Code', Menlo, Consolas, monospace"
+  },
+  "identity": {
+    "stamp": "NS",
+    "byline": "linkedin.com/in/natejswenson"
+  },
+  "marks": {
+    "warn": "⚠︎"
+  },
+  "limits": {
+    "max_letter_spacing_em": 0.1,
+    "min_fill_contrast_on_paper": 3.0
+  }
+}

package/brand/voice-core.md

@@ -0,0 +1,44 @@
+## Voice — the universal core
+
+These rules hold for **every** artifact: a LinkedIn post, an X thread, a dev-log
+entry, a résumé bullet, a report caption, a card headline, a commit message.
+
+They are the floor, not the whole voice. A medium layers its own voice on top
+(ghostwriter's learned profile, devlog's release-note shape, the résumé's
+achievement grammar) and **the medium wins on conflict** — these rules are what
+survives when nothing more specific applies.
+
+### Truth
+
+- **Never fabricate.** No invented metrics, motivations, outcomes, quotes,
+  commands, or file hashes. If a detail isn't true to what actually happened,
+  cut it or ask for it.
+- **Real numbers only.** A number in a draft must be traceable to something you
+  actually read. A missing number is `—` or a question, never a plausible
+  placeholder.
+- **No drama for effect.** Authenticity beats a punchy-but-false image.
+
+### Construction
+
+- **No em dashes.** Use a comma, a semicolon, or two sentences.
+- **No hedge words.** "Arguably", "essentially", "quite possibly", "it could be
+  said" — cut them. State the thing or don't.
+- **No tacked-on punchy filler.** No closing one-liner that adds nothing, no
+  rhetorical fragment lists for rhythm, no clever-symmetry constructions
+  ("not X, but Y" as a tic).
+- **No throat-clearing.** Lead with the thesis; cut the runway before it.
+
+### Framing
+
+- **Write for the reader, not as a diary.** Prefer "here's what to do" over
+  "here's what I did". Lead with the change and its impact, not with "I".
+- **Argue the idea, never the person.** Tools, teams and vendors are criticised
+  by what they do, not by name-calling.
+- **Tighter is better.** If a sentence survives being cut, cut it.
+
+### Endings
+
+The ending is where AI writing gives itself away. An artifact ends on the last
+real thing it has to say. It does **not** end on a summary of itself, a
+rhetorical question to the reader, a call to "let me know what you think", or a
+restatement of the opening.

package/lib/check.mjs

@@ -0,0 +1,91 @@
+/**
+ * The drift gate.
+ *
+ * `check` re-derives what each region should contain and compares it to what is
+ * on disk. Three things must fail, not just the obvious one:
+ *
+ *   drift    — the region exists but its bytes differ (someone hand-edited it,
+ *              or the tokens moved and nobody re-emitted);
+ *   missing  — the file exists but has no region at all. A consumer that
+ *              silently dropped its marker would otherwise report "all clean"
+ *              while checking nothing;
+ *   absent   — a declared file isn't there.
+ *
+ * And a run that resolved *zero* targets is itself a failure. A glob that
+ * quietly matches nothing must go red — that is how a gate turns decorative.
+ */
+import { readFileSync } from 'node:fs';
+import { emitBody } from './emit.mjs';
+import { findRegion, RegionError } from './region.mjs';
+import { selectTargets, targetPath } from './targets.mjs';
+
+export function checkTarget(target, root, tokens, version) {
+  const path = targetPath(target, root);
+  let text;
+  try {
+    text = readFileSync(path, 'utf8');
+  } catch {
+    return { target, path, status: 'absent' };
+  }
+
+  let found;
+  try {
+    found = findRegion(text, target.region, target.syntax);
+  } catch (err) {
+    if (err instanceof RegionError) return { target, path, status: 'corrupt', detail: err.message };
+    throw err;
+  }
+  if (!found) return { target, path, status: 'missing' };
+
+  const expected = emitBody(tokens, target.emitter, target.params ?? {}).replace(/\s+$/, '');
+  const actual = found.body.replace(/\s+$/, '');
+  if (expected === actual) {
+    return { target, path, status: 'ok', writtenBy: found.version };
+  }
+  return { target, path, status: 'drift', diff: lineDiff(expected, actual), writtenBy: found.version };
+}
+
+export function checkAll({ tokens, targets, root, ids, version }) {
+  const selected = selectTargets(targets, { root, ids });
+  const results = selected.map((t) => checkTarget(t, root, tokens, version));
+  const failures = results.filter((r) => r.status !== 'ok');
+  return {
+    results,
+    failures,
+    empty: selected.length === 0,
+    ok: selected.length > 0 && failures.length === 0,
+  };
+}
+
+/**
+ * A compact diff: common prefix and suffix are elided, so a one-line token
+ * change reads as one line instead of the whole region.
+ */
+export function lineDiff(expected, actual) {
+  const a = expected.split('\n');
+  const b = actual.split('\n');
+  let head = 0;
+  while (head < a.length && head < b.length && a[head] === b[head]) head += 1;
+  let tail = 0;
+  while (
+    tail < a.length - head &&
+    tail < b.length - head &&
+    a[a.length - 1 - tail] === b[b.length - 1 - tail]
+  ) {
+    tail += 1;
+  }
+  const out = [];
+  if (head > 0) out.push(`  … ${head} identical line${head === 1 ? '' : 's'}`);
+  for (const line of b.slice(head, b.length - tail)) out.push(`- ${line}`);
+  for (const line of a.slice(head, a.length - tail)) out.push(`+ ${line}`);
+  if (tail > 0) out.push(`  … ${tail} identical line${tail === 1 ? '' : 's'}`);
+  return out.join('\n');
+}
+
+export const EXPLAIN = {
+  ok: 'in sync',
+  drift: 'region content differs from what the tokens produce',
+  missing: 'file has no press region — the generated block was removed',
+  absent: 'declared file does not exist at this path',
+  corrupt: 'region markers are malformed',
+};

package/lib/emit.mjs

@@ -0,0 +1,332 @@
+/**
+ * The emitters — one per shape a consumer needs the brand in.
+ *
+ * An emitter returns a region *body* (no markers); region.mjs wraps it. Every
+ * emitter is a pure function of (tokens, params), so the same inputs always
+ * produce the same bytes and `check` can re-derive what should be on disk.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { BRAND_DIR } from './tokens.mjs';
+
+export class EmitError extends Error {}
+
+/**
+ * Preferred order for colors in generated output — a *sort key*, never a
+ * filter. Anything not named here is appended rather than dropped, so a token
+ * added to tokens.json always reaches every consumer. Filtering here instead
+ * would mean a new brand value silently never shipped, with `check` still
+ * reporting green.
+ */
+const COLOR_ORDER = [
+  'paper', 'paper_surface', 'paper_elevated',
+  'ink', 'dim', 'accent', 'rule', 'ink_mid', 'ink_faint',
+];
+
+const orderedColors = (tokens) => {
+  const rank = (k) => (COLOR_ORDER.indexOf(k) === -1 ? COLOR_ORDER.length : COLOR_ORDER.indexOf(k));
+  return Object.keys(tokens.colors)
+    .sort((a, b) => rank(a) - rank(b))
+    .map((k) => [k, tokens.colors[k]]);
+};
+
+// --------------------------------------------------------------------------
+// python-theme
+// --------------------------------------------------------------------------
+
+/**
+ * The token dict plus the loader every Python consumer shares: a deep-merge
+ * over an optional local override file, falling back silently on any error
+ * because a report in the wrong colors beats a report that didn't generate
+ * (laws.md §6).
+ */
+function pythonTheme(tokens, params) {
+  const envVar = required(params, 'env_var', 'python-theme');
+  const extras = new Set(params.extras ?? []);
+  const useLogging = params.logging === true;
+  const stamp = params.stamp ?? tokens.identity.stamp;
+  const brandLine = required(params, 'brand_line', 'python-theme');
+  const byline = params.byline ?? tokens.identity.byline;
+  const docKind = params.document_kind ?? 'DOCUMENT';
+
+  const out = [];
+  out.push('import copy');
+  out.push('import json');
+  if (useLogging) out.push('import logging');
+  out.push('import os');
+  out.push('from pathlib import Path');
+  out.push('');
+  if (useLogging) {
+    out.push('_LOG = logging.getLogger(__name__)');
+    out.push('');
+  }
+  out.push(`_BRAND_FILE_ENV = ${py(envVar)}`);
+  out.push('');
+
+  if (extras.has('warn')) {
+    out.push('#: Forces U+26A0 to text presentation. A bare warning sign renders as a');
+    out.push('#: *colored emoji* glyph in Chromium, which would put a second loud color on');
+    out.push('#: the page and break the accent law silently — it looks right in the HTML');
+    out.push('#: and wrong in the PDF.');
+    out.push(`WARN = ${py(tokens.marks.warn)}`);
+    out.push('');
+  }
+
+  out.push('DEFAULT_THEME: dict = {');
+  out.push(`    "name": ${py(tokens.name)},`);
+  out.push('    "colors": {');
+  for (const [key, value] of orderedColors(tokens)) {
+    for (const line of wrapComment(tokens.notes[key], 8)) out.push(line);
+    out.push(`        ${py(key)}: ${py(value)},`);
+  }
+  if (extras.has('terminal')) {
+    out.push('        # The dark panel palette. Only ever inside a terminal element.');
+    for (const [key, value] of Object.entries(tokens.terminal)) {
+      out.push(`        ${py(key)}: ${py(value)},`);
+    }
+  }
+  out.push('    },');
+  out.push('    "fonts": {');
+  out.push('        # Display/structure voice, set 800-900 with tight tracking by the CSS.');
+  out.push(`        "display_stack": ${py(tokens.fonts.display_stack)},`);
+  out.push('        # Commentary voice: serif italics for standfirsts and captions.');
+  out.push(`        "serif_stack": ${py(tokens.fonts.serif_stack)},`);
+  out.push('        # Data voice: labels, dates, tables, provenance.');
+  out.push(`        "mono_stack": ${py(tokens.fonts.mono_stack)},`);
+  if (extras.has('mono_file')) {
+    out.push('        # Point at a real TTF to load an authentic mono face via @font-face.');
+    out.push('        "mono_file": None,');
+  }
+  out.push('    },');
+  out.push('    "identity": {');
+  out.push('        # Typographic stamp (rotated square, accent border + initials).');
+  out.push(`        "stamp": ${py(stamp)},`);
+  out.push(`        # Masthead eyebrow, tracked caps: "{brand_line} · ${docKind} · date".`);
+  out.push(`        "brand_line": ${py(brandLine)},`);
+  out.push('        # Right-aligned dim byline in the masthead.');
+  out.push(`        "byline": ${py(byline)},`);
+  out.push('    },');
+  out.push('}');
+
+  if (extras.has('fill_steps')) {
+    out.push('');
+    out.push('#: Sequential fill steps, dark to light. Capped at three because the lighter');
+    out.push('#: extensions of this ramp drop under 3:1 against paper. Encodes magnitude');
+    out.push('#: only, never identity — see the brand laws on fills.');
+    out.push(`FILL_STEPS = (${tokens.derived.fillSteps.map(py).join(', ')})`);
+  }
+
+  out.push('');
+  out.push('');
+  out.push('def _deep_merge(base: dict, override: dict) -> dict:');
+  out.push('    """Recursively merge ``override`` into a copy of ``base``.');
+  out.push('');
+  out.push('    Non-dict values replace; unknown keys are kept, so a brand file written');
+  out.push('    against a newer default still loads against an older one.');
+  out.push('    """');
+  out.push('    out = copy.deepcopy(base)');
+  out.push('    for key, value in override.items():');
+  out.push('        if isinstance(value, dict) and isinstance(out.get(key), dict):');
+  out.push('            out[key] = _deep_merge(out[key], value)');
+  out.push('        else:');
+  out.push('            out[key] = copy.deepcopy(value)');
+  out.push('    return out');
+  out.push('');
+  out.push('');
+  out.push('def load_theme() -> dict:');
+  out.push(`    """The active theme: \`\`DEFAULT_THEME\`\` merged with \`\`${envVar}\`\`.`);
+  out.push('');
+  out.push('    Read per render rather than cached, so editing the brand file takes effect');
+  out.push('    on the next render without restarting anything. A missing or broken brand');
+  out.push('    file must never break a render, so any load error falls back to the');
+  out.push('    default.');
+  out.push('    """');
+  out.push('    theme = copy.deepcopy(DEFAULT_THEME)');
+  out.push('    brand_file = os.environ.get(_BRAND_FILE_ENV)');
+  out.push('    if brand_file:');
+  out.push('        try:');
+  out.push('            override = json.loads(Path(brand_file).expanduser().read_text(encoding="utf-8"))');
+  out.push('            if isinstance(override, dict):');
+  out.push('                theme = _deep_merge(theme, override)');
+  if (useLogging) {
+    out.push('            else:');
+    out.push('                _LOG.warning(');
+    out.push('                    "brand file %s is not a JSON object — using default theme", brand_file)');
+    out.push('        except (OSError, ValueError):');
+    out.push('            _LOG.warning(');
+    out.push('                "could not load brand file %s — using default theme",');
+    out.push('                brand_file, exc_info=True)');
+  } else {
+    out.push('        except (OSError, ValueError):');
+    out.push('            pass');
+  }
+  if (extras.has('mono_file')) {
+    out.push('    mono_file = theme.get("fonts", {}).get("mono_file")');
+    out.push('    if mono_file:');
+    out.push('        theme["fonts"]["mono_file"] = str(Path(mono_file).expanduser())');
+  }
+  out.push('    return theme');
+
+  return out.join('\n');
+}
+
+// --------------------------------------------------------------------------
+// css-vars
+// --------------------------------------------------------------------------
+
+/**
+ * A custom-property block. `vars` names which tokens the medium wants and,
+ * crucially, what to *call* them: the résumé's `--sig` and the site's `--fg`
+ * stay medium-idiomatic while provably carrying one source's values. Forcing a
+ * global rename would be churn for no gain.
+ */
+function cssVars(tokens, params) {
+  const selector = params.selector ?? ':root';
+  const vars = params.vars ?? [];
+  if (vars.length === 0) throw new EmitError('css-vars needs a non-empty "vars" list');
+
+  const decls = vars.map((entry) => {
+    const spec = typeof entry === 'string' ? { token: entry } : entry;
+    // Custom properties are kebab-case; token keys are snake_case.
+    const name = (spec.name ?? spec.token).replace(/_/g, '-');
+    const raw = spec.token === 'stamp'
+      ? (params.stamp ?? tokens.identity.stamp)
+      : lookup(tokens, spec.token);
+    const value = spec.quote ? JSON.stringify(raw) : raw;
+    // `comments: "explicit"` keeps only hand-written hints; the token notes are
+    // written for a reader of tokens.json and are far too long for a CSS block.
+    const fallback = params.comments === 'explicit' ? null : tokens.notes[spec.token] ?? null;
+    return { name: `--${name}`, value, comment: spec.comment ?? fallback };
+  });
+
+  const pad = params.align ? Math.max(...decls.map((d) => d.name.length)) + 2 : 0;
+
+  const body = decls.map((d) => {
+    const line = `  ${`${d.name}:`.padEnd(pad)} ${d.value};`.replace(/ +;$/, ';');
+    return d.comment && params.comments !== false
+      ? `${line}${' '.repeat(Math.max(1, 48 - line.length))}/* ${d.comment} */`
+      : line;
+  });
+
+  for (const extra of params.trailing ?? []) body.push(`  ${extra}`);
+
+  return [`${selector} {`, ...body, '}'].join('\n');
+}
+
+// --------------------------------------------------------------------------
+// md-palette / markdown-block / json
+// --------------------------------------------------------------------------
+
+/** The palette as a prose bullet list, for a style guide an agent reads. */
+function mdPalette(tokens, params) {
+  const skip = new Set(params.omit ?? []);
+  const lines = orderedColors(tokens)
+    .filter(([key]) => !skip.has(key))
+    .map(([key, value]) => `- **${titleize(key)}** \`${value}\` — ${tokens.notes[key]}`);
+  if (params.terminal !== false) {
+    const keys = Object.keys(tokens.terminal);
+    const names = keys.map((k) => k.replace(/^term_/, '')).join(', ');
+    const values = keys.map((k) => `\`${tokens.terminal[k]}\``).join(', ');
+    lines.push(
+      `- **Terminal panel** (${names}) ${values} — the one place the dark palette`,
+      '  survives, and only inside a terminal element. Never on paper.',
+    );
+  }
+  return lines.join('\n');
+}
+
+/** Inline one of the brand contract documents verbatim. */
+function markdownBlock(tokens, params) {
+  const doc = required(params, 'doc', 'markdown-block');
+  if (!/^[a-z-]+$/.test(doc)) throw new EmitError(`illegal doc name "${doc}"`);
+  const text = readFileSync(join(BRAND_DIR, `${doc}.md`), 'utf8').replace(/\s+$/, '');
+  const shift = params.heading_shift ?? 0;
+  if (!shift) return text;
+  return text
+    .split('\n')
+    .map((l) => (/^#{1,5} /.test(l) ? '#'.repeat(shift) + l : l))
+    .join('\n');
+}
+
+/** Raw values, for anything that just wants the numbers. */
+function jsonTokens(tokens, params) {
+  const payload = {
+    colors: tokens.colors,
+    terminal: tokens.terminal,
+    fonts: tokens.fonts,
+    identity: { ...tokens.identity, ...(params.stamp ? { stamp: params.stamp } : {}) },
+    derived: { hair: tokens.derived.hair, fill_steps: tokens.derived.fillSteps },
+  };
+  for (const key of params.omit ?? []) delete payload[key];
+  return JSON.stringify(payload, null, 2);
+}
+
+// --------------------------------------------------------------------------
+
+export const EMITTERS = {
+  'python-theme': pythonTheme,
+  'css-vars': cssVars,
+  'md-palette': mdPalette,
+  'markdown-block': markdownBlock,
+  json: jsonTokens,
+};
+
+export function emitBody(tokens, emitter, params = {}) {
+  const fn = EMITTERS[emitter];
+  if (!fn) {
+    throw new EmitError(
+      `unknown emitter "${emitter}" (expected one of: ${Object.keys(EMITTERS).join(', ')})`,
+    );
+  }
+  return fn(tokens, params);
+}
+
+// --------------------------------------------------------------------------
+
+function required(params, key, emitter) {
+  const value = params[key];
+  if (value === undefined || value === null || value === '') {
+    throw new EmitError(`${emitter} requires params.${key}`);
+  }
+  return value;
+}
+
+function lookup(tokens, name) {
+  if (name === 'hair') return tokens.derived.hair;
+  for (const group of [tokens.colors, tokens.terminal, tokens.fonts, tokens.identity, tokens.marks]) {
+    if (name in group) return group[name];
+  }
+  throw new EmitError(`unknown token "${name}"`);
+}
+
+/** Python string literal. Double quotes, matching every existing consumer. */
+function py(value) {
+  if (value === null) return 'None';
+  return JSON.stringify(value);
+}
+
+function wrapComment(text, indent) {
+  if (!text) return [];
+  const pad = ' '.repeat(indent);
+  const words = text.split(' ');
+  const lines = [];
+  let current = '';
+  for (const word of words) {
+    const next = current ? `${current} ${word}` : word;
+    if (`${pad}# ${next}`.length > 79 && current) {
+      lines.push(`${pad}# ${current}`);
+      current = word;
+    } else {
+      current = next;
+    }
+  }
+  if (current) lines.push(`${pad}# ${current}`);
+  return lines;
+}
+
+function titleize(key) {
+  return key
+    .split('_')
+    .map((p) => p[0].toUpperCase() + p.slice(1))
+    .join(' ');
+}