@bitmagic/cli 0.1.59-dev.1 → 0.1.59-dev.3

package/dist/theme/theme-color-math.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Hand-mirror of game/src/engine/hud/colorMath.ts — the WCAG arithmetic behind
+ * the derived HUD inks. The theme report computes its contrast pairings with
+ * EXACTLY the maths the engine will apply, so a SUBSTITUTED line in the report
+ * is a promise about what will render, not an estimate.
+ *
+ * Mirrored by hand because agent tools cannot import engine source (separate
+ * tsconfig include sets). Drift-checked BEHAVIOURALLY by scripts/
+ * check-hud-catalog.ts: the gate imports both copies under tsx and compares
+ * their outputs over every preset palette plus adversarial pairs, so a changed
+ * threshold or mix factor on either side goes red in CI.
+ */
+export declare function relLuminance(hex: string): number;
+export declare function contrastRatio(a: string, b: string): number;
+export declare function mixHex(from: string, to: string, amount: number): string;
+export declare function readableTextColor(hex: string): string;
+export declare const ON_SURFACE_MIN_CONTRAST = 3;
+export declare function inkOnSurface(surface: string, preferred: string): string;
+export declare const ACCENT_INK_MIN_CONTRAST = 4.5;
+export declare function accentInkOn(ground: string, accent: string): string | null;
+export declare function mutedInkOnSurface(surface: string, preferred: string): string;

package/dist/theme/theme-color-math.js

@@ -0,0 +1,99 @@
+/**
+ * Hand-mirror of game/src/engine/hud/colorMath.ts — the WCAG arithmetic behind
+ * the derived HUD inks. The theme report computes its contrast pairings with
+ * EXACTLY the maths the engine will apply, so a SUBSTITUTED line in the report
+ * is a promise about what will render, not an estimate.
+ *
+ * Mirrored by hand because agent tools cannot import engine source (separate
+ * tsconfig include sets). Drift-checked BEHAVIOURALLY by scripts/
+ * check-hud-catalog.ts: the gate imports both copies under tsx and compares
+ * their outputs over every preset palette plus adversarial pairs, so a changed
+ * threshold or mix factor on either side goes red in CI.
+ */
+export function relLuminance(hex) {
+    const lin = (v) => (v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4));
+    return 0.2126 * lin(parseInt(hex.slice(1, 3), 16) / 255)
+        + 0.7152 * lin(parseInt(hex.slice(3, 5), 16) / 255)
+        + 0.0722 * lin(parseInt(hex.slice(5, 7), 16) / 255);
+}
+export function contrastRatio(a, b) {
+    const la = relLuminance(a);
+    const lb = relLuminance(b);
+    return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+}
+export function mixHex(from, to, amount) {
+    const channel = (i) => {
+        const f = parseInt(from.slice(i, i + 2), 16);
+        const t = parseInt(to.slice(i, i + 2), 16);
+        return Math.round(f * amount + t * (1 - amount)).toString(16).padStart(2, '0');
+    };
+    return `#${channel(1)}${channel(3)}${channel(5)}`;
+}
+export function readableTextColor(hex) {
+    if (!/^#[0-9a-fA-F]{6}$/.test(hex))
+        return '#ffffff';
+    return relLuminance(hex) > 0.5 ? '#000000' : '#ffffff';
+}
+// The ink for anything painted ON `surface`, plus its muted companion.
+//
+// Same species as --hud-color-on-primary: the engine picks the readable pair so a
+// theme author does not have to hand-author contrast per element. It exists
+// because `text` carries TWO jobs that only agree on a uniformly dark theme. It is
+// the ink on the `background` canvas — a game's own dialogs paint themselves with
+// that pair — AND the ink on every counter, timer, toast, bubble and panel filled
+// with `surface`. A style whose big UI is a light canvas and whose HUD furniture is
+// darker cannot satisfy both from one value: with a single ink the furniture caps
+// out around #9E9276, which is 1.4:1 against a sunny world and so not furniture at
+// all. Village Keep spent three rounds oscillating between a washed-out HUD and a
+// uniformly dark one for exactly this reason.
+//
+// It PREFERS the theme's own ink, because a tinted parchment or a cold cyan is part
+// of a style's identity and must survive. It substitutes only where the declared
+// pairing is unusable — below 3:1, the WCAG floor for large text, and far below
+// every pairing in the catalog: the presets measure 9.6 to 17.8 for `text` and 5.7
+// to 9.3 for `textMuted`, so this cannot fire on a theme that was already coherent.
+export const ON_SURFACE_MIN_CONTRAST = 3;
+export function inkOnSurface(surface, preferred) {
+    if (!/^#[0-9a-fA-F]{6}$/.test(surface) || !/^#[0-9a-fA-F]{6}$/.test(preferred))
+        return preferred;
+    if (contrastRatio(preferred, surface) >= ON_SURFACE_MIN_CONTRAST)
+        return preferred;
+    return readableTextColor(surface);
+}
+// Target 4.5:1 rather than the 3:1 the on-surface inks use: this one paints
+// headings and status lines, which are body-scale on some surfaces, and the
+// margin is free — the lowest any shipped preset measures is 6.02:1, so raising
+// the bar cannot make the token fire on a theme that was already fine.
+export const ACCENT_INK_MIN_CONTRAST = 4.5;
+export function accentInkOn(ground, accent) {
+    if (!/^#[0-9a-fA-F]{6}$/.test(ground) || !/^#[0-9a-fA-F]{6}$/.test(accent))
+        return null;
+    if (contrastRatio(accent, ground) >= ACCENT_INK_MIN_CONTRAST)
+        return null;
+    // Walk the accent toward the ground's opposite pole and stop at the FIRST value
+    // that clears, so the result keeps as much of the accent as the ground allows.
+    // Mixing toward black or white preserves the HUE, which is the part that makes
+    // an accent an accent: village-keep's candy lime lands on a forest green rather
+    // than on brown, and a forest green on parchment is what the reference draws.
+    const pole = relLuminance(ground) > 0.5 ? '#000000' : '#ffffff';
+    for (let keep = 0.95; keep > 0.05; keep -= 0.05) {
+        const candidate = mixHex(accent, pole, keep);
+        if (contrastRatio(candidate, ground) >= ACCENT_INK_MIN_CONTRAST)
+            return candidate;
+    }
+    return readableTextColor(ground);
+}
+export function mutedInkOnSurface(surface, preferred) {
+    if (!/^#[0-9a-fA-F]{6}$/.test(surface) || !/^#[0-9a-fA-F]{6}$/.test(preferred))
+        return preferred;
+    if (contrastRatio(preferred, surface) >= ON_SURFACE_MIN_CONTRAST)
+        return preferred;
+    // A secondary label steps BACK toward its own backdrop rather than taking the
+    // full-strength ink — otherwise the substitution would make muted text the
+    // loudest thing on the element it was meant to sit quietly on. 0.78 is the
+    // point where it still clears AA on the lightest surface that can reach this
+    // branch at all (a mid-brown at 4.65:1) while reading as clearly quieter than
+    // the full ink beside it.
+    return mixHex(readableTextColor(surface), surface, 0.78);
+}
+//# sourceMappingURL=theme-color-math.js.map

package/dist/theme/theme-color-math.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme-color-math.js","sourceRoot":"","sources":["../../src/theme/theme-color-math.ts"],"names":[],"mappings":"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"}

package/dist/theme/theme-io.d.ts

@@ -0,0 +1,49 @@
+import type { JsonObject } from '../project/world-json.js';
+export interface StoredTheme {
+    kind: 'preset' | 'custom' | 'none' | 'unknown-preset';
+    stored: unknown;
+    /** The tokens the engine renders for this stored value. */
+    effective: Record<string, unknown>;
+    /** Human-readable description of where `effective` came from. */
+    label: string;
+}
+/** worldProfileData.hud.theme — the ONLY path the engine reads a theme from. */
+export declare function readStoredTheme(world: JsonObject): StoredTheme;
+/**
+ * Parse a `set`/`patch` argument: a preset name, inline JSON, `@file`, or (for
+ * `set`) the literal `null`. Files keep long inline themes off the shell line,
+ * where quoting mangles them.
+ */
+export declare function parseThemeArgument(raw: string, readFile: (path: string) => string): {
+    kind: 'preset';
+    name: string;
+} | {
+    kind: 'reset';
+} | {
+    kind: 'object';
+    value: Record<string, unknown>;
+};
+export interface PreparedWrite {
+    /** What to store at worldProfileData.hud.theme. */
+    value: unknown;
+    /** The tokens that value renders as (for the report). */
+    effective: Record<string, unknown>;
+    baseLabel: string;
+    warnings: Array<{
+        path: string;
+        message: string;
+        suggestion?: string;
+    }>;
+}
+/** `set`: full replace with a preset name, inline object, or null. */
+export declare function prepareSet(argument: ReturnType<typeof parseThemeArgument>, current: StoredTheme): PreparedWrite;
+/** `patch`: merge onto the current effective theme, validate the whole result. */
+export declare function preparePatch(patch: Record<string, unknown>, current: StoredTheme): PreparedWrite;
+/** The report both lanes print — identical text to the hosted tool's. */
+export declare function themeReport(prepared: PreparedWrite, before: StoredTheme): string;
+/** `check`/`show`: verdict + report for what is stored right now. */
+export declare function checkStoredTheme(current: StoredTheme): {
+    valid: boolean;
+    problems: string[];
+    report: string;
+};

package/dist/theme/theme-io.js

@@ -0,0 +1,190 @@
+/**
+ * The rules behind `bitmagic theme show | check | set | patch` — everything that
+ * is not flags and printing. Split from the command file the way `levels/`
+ * splits registry from command, so tests exercise the rules without a
+ * filesystem or a citty run.
+ *
+ * The vocabulary, validator, merge semantics and report come from `src/theme/`,
+ * a byte-identical mirror of game-play-agent's theme kit (the drift gate in
+ * game-play-agent/scripts/check-hud-catalog.ts enforces the byte identity
+ * against both the engine and this copy). Same inputs, same verdicts, same
+ * report text in both lanes.
+ */
+import { CliError } from '../errors.js';
+import { DEFAULT_THEME_TOKENS, HUD_PRESETS, isEngineFatalIssue, presetTheme, suggestClosest, validateThemeStrict, } from './hud-theme-catalog.js';
+import { resolveStoredTheme } from './theme-stored.js';
+import { applyMergePatch, deleteAtPath } from './theme-merge.js';
+import { buildThemeReport } from './theme-report.js';
+/** worldProfileData.hud.theme — the ONLY path the engine reads a theme from. */
+export function readStoredTheme(world) {
+    const profile = world.worldProfileData;
+    const hud = typeof profile === 'object' && profile !== null
+        ? profile.hud
+        : undefined;
+    const stored = typeof hud === 'object' && hud !== null ? hud.theme : undefined;
+    // The stored-value→tokens mapping lives in the gated kit (theme-stored.ts),
+    // shared with the hosted write tool — this wrapper only digs the value out
+    // of the world shape and keeps it for `show`.
+    const resolved = resolveStoredTheme(stored);
+    return {
+        kind: resolved.kind,
+        stored: stored === undefined ? null : stored,
+        effective: resolved.tokens,
+        label: resolved.label,
+    };
+}
+/**
+ * Parse a `set`/`patch` argument: a preset name, inline JSON, `@file`, or (for
+ * `set`) the literal `null`. Files keep long inline themes off the shell line,
+ * where quoting mangles them.
+ */
+export function parseThemeArgument(raw, readFile) {
+    if (raw === 'null' || raw === 'default')
+        return { kind: 'reset' };
+    const text = raw.startsWith('@') ? readFile(raw.slice(1)) : raw;
+    const trimmed = text.trim();
+    if (!trimmed.startsWith('{')) {
+        if (HUD_PRESETS.includes(trimmed)) {
+            return { kind: 'preset', name: trimmed };
+        }
+        const close = suggestClosest(trimmed, HUD_PRESETS);
+        throw new CliError(`"${trimmed}" is not a preset name, JSON object, @file, or null. `
+            + `Presets: ${HUD_PRESETS.join(', ')}.${close ? ` Closest match: "${close}".` : ''}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch (error) {
+        throw new CliError(`Not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new CliError('Expected a JSON object (the theme, or a merge patch in the theme\'s shape).');
+    }
+    return { kind: 'object', value: parsed };
+}
+/** Validation failure formatted the way every issue leaves this command. */
+function rejected(errors) {
+    const lines = errors.map(e => `  ${e.path}: ${e.message}${e.suggestion ? ` (${e.suggestion})` : ''}`);
+    return new CliError(`Theme rejected — nothing was written:\n${lines.join('\n')}`);
+}
+/** `set`: full replace with a preset name, inline object, or null. */
+export function prepareSet(argument, current) {
+    if (argument.kind === 'reset') {
+        // RESET writes the default tokens INLINE rather than clearing the key.
+        // `null` cannot be stored: the GameData schema types worldProfileData.hud.theme
+        // as anyOf [string, object] (shared/world-forger .../game-data-schema.ts), so the
+        // applier's post-write schema gate rejects it and nothing lands. Deleting the key
+        // is not available either — `remove` in both world.json editors filters ARRAY
+        // entries by predicate and cannot drop an object key. Writing the default tokens
+        // is schema-valid and renders the identical default look; the difference is that
+        // the values are now explicit, which also means an agent can read and patch them.
+        const tokens = structuredClone(DEFAULT_THEME_TOKENS);
+        return {
+            value: tokens,
+            effective: tokens,
+            baseLabel: 'the engine default look (reset)',
+            warnings: [],
+        };
+    }
+    if (argument.kind === 'preset') {
+        return {
+            value: argument.name,
+            effective: presetTheme(argument.name),
+            baseLabel: `preset ${argument.name}`,
+            warnings: [],
+        };
+    }
+    const theme = structuredClone(argument.value);
+    const result = validateThemeStrict(theme);
+    if (!result.ok) {
+        // The one mistake worth a dedicated redirect: a partial object passed to
+        // `set` where `patch` was meant.
+        const errors = result.errors.map(e => e.message.includes('required')
+            ? { ...e, suggestion: `${e.suggestion ? `${e.suggestion} ` : ''}If you meant to change just these fields, use \`bitmagic theme patch\` — set replaces the whole theme.` }
+            : e);
+        throw rejected(errors);
+    }
+    void current;
+    return { value: theme, effective: theme, baseLabel: 'inline theme', warnings: result.warnings };
+}
+/** `patch`: merge onto the current effective theme, validate the whole result. */
+export function preparePatch(patch, current) {
+    const base = structuredClone(current.effective);
+    // A stored custom base may carry pre-strict-era leaves the engine already
+    // ignores (unknown color tokens, bad per-element leaves). Left in place they
+    // would fail validation of the merged result at paths the patch never
+    // touched — prune them with a warning instead; they render as nothing today,
+    // so removing them changes no pixels. Same behaviour as the hosted tool.
+    const prunedWarnings = [];
+    if (current.kind === 'custom') {
+        const baseCheck = validateThemeStrict(structuredClone(base));
+        for (const issue of baseCheck.errors) {
+            if (deleteAtPath(base, issue.path)) {
+                prunedWarnings.push({
+                    path: issue.path,
+                    message: `pre-existing issue in the stored theme (${issue.message}) — the engine was already ignoring this leaf; it was removed so your patch could apply`,
+                });
+            }
+        }
+    }
+    const merged = applyMergePatch(base, patch);
+    const result = validateThemeStrict(merged);
+    if (!result.ok)
+        throw rejected(result.errors);
+    return {
+        value: merged,
+        effective: merged,
+        baseLabel: `${current.label} + patch`,
+        warnings: [...prunedWarnings, ...result.warnings],
+    };
+}
+/** The report both lanes print — identical text to the hosted tool's. */
+export function themeReport(prepared, before) {
+    return buildThemeReport(prepared.effective, {
+        before: before.effective,
+        baseLabel: prepared.baseLabel,
+    });
+}
+/** `check`/`show`: verdict + report for what is stored right now. */
+export function checkStoredTheme(current) {
+    if (current.kind === 'unknown-preset') {
+        const close = typeof current.stored === 'string'
+            ? suggestClosest(current.stored, HUD_PRESETS)
+            : undefined;
+        return {
+            valid: false,
+            problems: [
+                `hud.theme is "${String(current.stored)}", which is not a preset — the game silently renders the default look.`
+                    + `${close ? ` Closest match: "${close}".` : ''} Presets: ${HUD_PRESETS.join(', ')}.`,
+            ],
+            report: buildThemeReport(current.effective, { baseLabel: current.label }),
+        };
+    }
+    if (current.kind === 'custom') {
+        const probe = structuredClone(current.effective);
+        const result = validateThemeStrict(probe);
+        // Only ENGINE-FATAL errors mean the theme will not apply. The strict
+        // validator also errors on leaves the engine warn-and-drops (per-element
+        // colors/shape/font) or ignores outright (unknown color tokens) — the
+        // theme renders fine minus those, and failing `check` over them blocks a
+        // working theme in CI and misleads agents into repairing it.
+        const fatal = result.errors.filter(isEngineFatalIssue);
+        const droppable = result.errors.filter(e => !isEngineFatalIssue(e));
+        const format = (e) => `${e.path}: ${e.message}${e.suggestion ? ` (${e.suggestion})` : ''}`;
+        return {
+            valid: fatal.length === 0,
+            problems: [
+                ...fatal.map(format),
+                ...droppable.map(e => `${format(e)} [leaf issue — the engine drops this leaf and still renders the theme]`),
+            ],
+            report: buildThemeReport(current.effective, { baseLabel: current.label }),
+        };
+    }
+    return {
+        valid: true,
+        problems: [],
+        report: buildThemeReport(current.effective, { baseLabel: current.label }),
+    };
+}
+//# sourceMappingURL=theme-io.js.map

package/dist/theme/theme-io.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme-io.js","sourceRoot":"","sources":["../../src/theme/theme-io.ts"],"names":[],"mappings":"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"}

package/dist/theme/theme-merge.d.ts

@@ -0,0 +1,36 @@
+/**
+ * RFC 7386 JSON merge patch, for HUD theme edits.
+ *
+ * Why merge patch and not path-based `{path, value}` edits: a merge patch IS
+ * the theme's own shape — `{ colors: { primary: "#FF8800" } }` — so the model
+ * emits the one notation it already knows from reading themes, instead of
+ * inventing dotted path strings it can typo. Deletion is `null` at the key
+ * (RFC 7386), which is how "remove the outline" and "clear glowColor" are
+ * expressed without a second vocabulary.
+ *
+ * The patch applies to a base and the MERGED result is validated as a whole
+ * theme, so a patch can never sneak an invalid leaf past the checks that a
+ * full write would catch.
+ */
+export declare function applyMergePatch(base: unknown, patch: unknown): unknown;
+export interface ThemeDiffEntry {
+    path: string;
+    from: unknown;
+    to: unknown;
+}
+/**
+ * Leaf-level differences between two themes, as dotted paths. Feeds the
+ * report's `changed:` line — the model's confirmation of what its edit
+ * actually did (and, on a full replace, of everything it changed without
+ * meaning to).
+ */
+export declare function diffThemes(before: unknown, after: unknown, prefix?: string): ThemeDiffEntry[];
+/**
+ * Delete the leaf at a dotted validator path ("elements.healthBar.colors.background").
+ * Returns false when the path does not resolve — the caller then leaves the
+ * error in place rather than pretending it fixed something. Companion to the
+ * patch flows: a STORED base can carry pre-strict-era leaves the engine already
+ * ignores, and pruning them (with a warning) is what lets an unrelated patch
+ * apply instead of failing at paths it never touched.
+ */
+export declare function deleteAtPath(target: Record<string, unknown>, dottedPath: string): boolean;

package/dist/theme/theme-merge.js

@@ -0,0 +1,81 @@
+/**
+ * RFC 7386 JSON merge patch, for HUD theme edits.
+ *
+ * Why merge patch and not path-based `{path, value}` edits: a merge patch IS
+ * the theme's own shape — `{ colors: { primary: "#FF8800" } }` — so the model
+ * emits the one notation it already knows from reading themes, instead of
+ * inventing dotted path strings it can typo. Deletion is `null` at the key
+ * (RFC 7386), which is how "remove the outline" and "clear glowColor" are
+ * expressed without a second vocabulary.
+ *
+ * The patch applies to a base and the MERGED result is validated as a whole
+ * theme, so a patch can never sneak an invalid leaf past the checks that a
+ * full write would catch.
+ */
+export function applyMergePatch(base, patch) {
+    // Per RFC 7386: a non-object patch replaces the target outright.
+    if (typeof patch !== 'object' || patch === null || Array.isArray(patch))
+        return patch;
+    const target = typeof base === 'object' && base !== null && !Array.isArray(base)
+        ? { ...base }
+        : {};
+    for (const [key, value] of Object.entries(patch)) {
+        if (value === null) {
+            delete target[key];
+        }
+        else {
+            target[key] = applyMergePatch(target[key], value);
+        }
+    }
+    return target;
+}
+/**
+ * Leaf-level differences between two themes, as dotted paths. Feeds the
+ * report's `changed:` line — the model's confirmation of what its edit
+ * actually did (and, on a full replace, of everything it changed without
+ * meaning to).
+ */
+export function diffThemes(before, after, prefix = '') {
+    if (Object.is(before, after))
+        return [];
+    const bothObjects = typeof before === 'object' && before !== null && !Array.isArray(before)
+        && typeof after === 'object' && after !== null && !Array.isArray(after);
+    if (!bothObjects) {
+        // Arrays and scalars diff as one leaf; deep-equal arrays are not a change.
+        if (JSON.stringify(before) === JSON.stringify(after))
+            return [];
+        return [{ path: prefix || '(root)', from: before, to: after }];
+    }
+    const b = before;
+    const a = after;
+    const out = [];
+    for (const key of new Set([...Object.keys(b), ...Object.keys(a)])) {
+        const childPrefix = prefix ? `${prefix}.${key}` : key;
+        out.push(...diffThemes(b[key], a[key], childPrefix));
+    }
+    return out;
+}
+/**
+ * Delete the leaf at a dotted validator path ("elements.healthBar.colors.background").
+ * Returns false when the path does not resolve — the caller then leaves the
+ * error in place rather than pretending it fixed something. Companion to the
+ * patch flows: a STORED base can carry pre-strict-era leaves the engine already
+ * ignores, and pruning them (with a warning) is what lets an unrelated patch
+ * apply instead of failing at paths it never touched.
+ */
+export function deleteAtPath(target, dottedPath) {
+    const segments = dottedPath.split('.');
+    let node = target;
+    for (const segment of segments.slice(0, -1)) {
+        const next = node[segment];
+        if (typeof next !== 'object' || next === null || Array.isArray(next))
+            return false;
+        node = next;
+    }
+    const leaf = segments[segments.length - 1];
+    if (leaf === undefined || !(leaf in node))
+        return false;
+    delete node[leaf];
+    return true;
+}
+//# sourceMappingURL=theme-merge.js.map

package/dist/theme/theme-merge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme-merge.js","sourceRoot":"","sources":["../../src/theme/theme-merge.ts"],"names":[],"mappings":"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"}

package/dist/theme/theme-report.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The text report that rides every successful theme read/write — the model's
+ * eyes. An LLM cannot see the rendered HUD, so the one moment it can learn
+ * "your literal value will not render" or "your edit also changed X" is inside
+ * the tool response, in text, immediately.
+ *
+ * Two sections:
+ *   changed:  leaf-level diff of what the write actually did — the confirmation
+ *             of the intended edit AND of anything a full replace changed
+ *             without meaning to.
+ *   contrast: the derived-ink pairings computed with EXACTLY the engine's
+ *             arithmetic (theme-color-math mirrors engine colorMath, gate-
+ *             checked), so "SUBSTITUTED -> renders #X" is a promise about the
+ *             pixels, not an estimate.
+ *
+ * Deliberately report-only: the engine self-heals every pairing marked
+ * SUBSTITUTED, so nothing here blocks a write. The report exists so the agent
+ * can decide whether the substitute serves the user's ask — a lime accent that
+ * renders as forest green might be exactly right, or reason to pick a colour
+ * the ground can carry.
+ */
+export interface ThemeReportOptions {
+    /** The theme before this write, for the diff section. Omit for read-only reports. */
+    before?: unknown;
+    /** How the written theme was produced, e.g. `preset rift-raider + patch`. */
+    baseLabel: string;
+}
+export declare function buildThemeReport(after: unknown, options: ThemeReportOptions): string;