@promptctl/rich-js 0.18.0 → 0.19.0

package/dist/themes/terminalThemes.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Pre-built `TerminalTheme` constants — every theme in the registry has a
+ * matching `<NAME>` export here. There is no inline-only theme; the data
+ * file is the single source of truth for every theme's hex values.
+ *
+ * Editing `data/<name>.ts` updates both the registry's full ~150-var
+ * palette (via `getThemePalette(name)`) AND the matching `TerminalTheme`
+ * constant exported below (via `getThemeBaseColors(name)`, which pulls
+ * just the 8 substrate keys). The two views never drift because both
+ * derive from the same authored data.
+ *
+ * [LAW:one-source-of-truth] Hex values live in `data/<name>.ts`. This
+ * module is a derived view that builds a `TerminalTheme` from each
+ * theme's eight base colors via `buildPalette` for the substrate palette,
+ * and from the theme's own ANSI table for the sixteen named colours.
+ *
+ * [LAW:one-type-per-behavior] Every theme has the same shape — name,
+ * `dark` flag, full Palette in the registry, `TerminalTheme` constant
+ * here. Consumers can pick any theme by name without branching on which
+ * APIs work for it.
+ *
+ * [LAW:one-way-deps] `core/color → themes/palette` remains the only edge
+ * into themes/. This file imports only sibling theme modules and core
+ * color primitives; nothing in `core/` imports back.
+ */
+import { TerminalTheme } from "../core/color.js";
+export declare const DEFAULT_TERMINAL_THEME: TerminalTheme;
+export declare const SVG_EXPORT_THEME: TerminalTheme;
+export declare const MONOKAI: TerminalTheme;
+export declare const NORD: TerminalTheme;
+export declare const GRUVBOX: TerminalTheme;
+export declare const DRACULA: TerminalTheme;
+export declare const TOKYO_NIGHT: TerminalTheme;
+export declare const FLEXOKI: TerminalTheme;
+export declare const CYBERPUNK: TerminalTheme;
+export declare const CATPPUCCIN_MOCHA: TerminalTheme;
+export declare const CATPPUCCIN_LATTE: TerminalTheme;
+export declare const CATPPUCCIN_FRAPPE: TerminalTheme;
+export declare const CATPPUCCIN_MACCHIATO: TerminalTheme;
+export declare const SOLARIZED_DARK: TerminalTheme;
+export declare const SOLARIZED_LIGHT: TerminalTheme;
+export declare const ROSE_PINE: TerminalTheme;
+export declare const ROSE_PINE_MOON: TerminalTheme;
+export declare const ROSE_PINE_DAWN: TerminalTheme;
+export declare const ATOM_ONE_DARK: TerminalTheme;
+export declare const ATOM_ONE_LIGHT: TerminalTheme;
+export declare const TEXTUAL_DARK: TerminalTheme;
+export declare const TEXTUAL_LIGHT: TerminalTheme;
+export declare const TEXTUAL_ANSI: TerminalTheme;

package/dist/themes/terminalThemes.js

@@ -0,0 +1,63 @@
+/**
+ * Pre-built `TerminalTheme` constants — every theme in the registry has a
+ * matching `<NAME>` export here. There is no inline-only theme; the data
+ * file is the single source of truth for every theme's hex values.
+ *
+ * Editing `data/<name>.ts` updates both the registry's full ~150-var
+ * palette (via `getThemePalette(name)`) AND the matching `TerminalTheme`
+ * constant exported below (via `getThemeBaseColors(name)`, which pulls
+ * just the 8 substrate keys). The two views never drift because both
+ * derive from the same authored data.
+ *
+ * [LAW:one-source-of-truth] Hex values live in `data/<name>.ts`. This
+ * module is a derived view that builds a `TerminalTheme` from each
+ * theme's eight base colors via `buildPalette` for the substrate palette,
+ * and from the theme's own ANSI table for the sixteen named colours.
+ *
+ * [LAW:one-type-per-behavior] Every theme has the same shape — name,
+ * `dark` flag, full Palette in the registry, `TerminalTheme` constant
+ * here. Consumers can pick any theme by name without branching on which
+ * APIs work for it.
+ *
+ * [LAW:one-way-deps] `core/color → themes/palette` remains the only edge
+ * into themes/. This file imports only sibling theme modules and core
+ * color primitives; nothing in `core/` imports back.
+ */
+import { TerminalTheme } from "../core/color.js";
+import { buildPalette } from "./buildPalette.js";
+import { getThemeBaseColors } from "./registry.js";
+function defineTheme(d) {
+    return new TerminalTheme(d.bg, d.fg, d.ansi, buildPalette(d.name, d.dark, {
+        primary: d.primary,
+        secondary: d.secondary,
+        accent: d.accent,
+        success: d.success,
+        warning: d.warning,
+        error: d.error,
+        background: d.bg,
+        foreground: d.fg,
+    }));
+}
+export const DEFAULT_TERMINAL_THEME = defineTheme(getThemeBaseColors("default"));
+export const SVG_EXPORT_THEME = defineTheme(getThemeBaseColors("svg-export"));
+export const MONOKAI = defineTheme(getThemeBaseColors("monokai"));
+export const NORD = defineTheme(getThemeBaseColors("nord"));
+export const GRUVBOX = defineTheme(getThemeBaseColors("gruvbox"));
+export const DRACULA = defineTheme(getThemeBaseColors("dracula"));
+export const TOKYO_NIGHT = defineTheme(getThemeBaseColors("tokyo-night"));
+export const FLEXOKI = defineTheme(getThemeBaseColors("flexoki"));
+export const CYBERPUNK = defineTheme(getThemeBaseColors("cyberpunk"));
+export const CATPPUCCIN_MOCHA = defineTheme(getThemeBaseColors("catppuccin-mocha"));
+export const CATPPUCCIN_LATTE = defineTheme(getThemeBaseColors("catppuccin-latte"));
+export const CATPPUCCIN_FRAPPE = defineTheme(getThemeBaseColors("catppuccin-frappe"));
+export const CATPPUCCIN_MACCHIATO = defineTheme(getThemeBaseColors("catppuccin-macchiato"));
+export const SOLARIZED_DARK = defineTheme(getThemeBaseColors("solarized-dark"));
+export const SOLARIZED_LIGHT = defineTheme(getThemeBaseColors("solarized-light"));
+export const ROSE_PINE = defineTheme(getThemeBaseColors("rose-pine"));
+export const ROSE_PINE_MOON = defineTheme(getThemeBaseColors("rose-pine-moon"));
+export const ROSE_PINE_DAWN = defineTheme(getThemeBaseColors("rose-pine-dawn"));
+export const ATOM_ONE_DARK = defineTheme(getThemeBaseColors("atom-one-dark"));
+export const ATOM_ONE_LIGHT = defineTheme(getThemeBaseColors("atom-one-light"));
+export const TEXTUAL_DARK = defineTheme(getThemeBaseColors("textual-dark"));
+export const TEXTUAL_LIGHT = defineTheme(getThemeBaseColors("textual-light"));
+export const TEXTUAL_ANSI = defineTheme(getThemeBaseColors("textual-ansi"));

package/dist/themes/transpose.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Transpose a Palette to a new "key" — analogous to transposing a melody.
+ *
+ *   melody / chord progression  ::  Palette (relationships between colors)
+ *                key (signature) ::  ThemeKey (hue / chroma / lightness deltas)
+ *      "in C major" / "in D…"   ::  the resulting transposed Palette
+ *
+ * Because OKLCH is perceptually uniform, "+30° hue" looks like a
+ * consistent jump everywhere on the color wheel — the way a perfect-fifth
+ * interval sounds the same in every musical key. Transposition is closed
+ * under composition: `transpose(transpose(p, k1), k2)` produces the same
+ * colors as a single transpose with the combined deltas, modulo round-trip
+ * quantization.
+ *
+ * [LAW:dataflow-not-control-flow] A single uniform per-color transform
+ * runs for every var in the palette. Anchor protection selects *which*
+ * `ThemeKey` to apply (data), not *whether* to apply one (branch).
+ *
+ * [LAW:one-source-of-truth] Anchor classification lives only in
+ * `ANCHORED_ROOTS` below. The buildPalette derivation guarantees every
+ * variant of a semantic root shares the root as its hyphen prefix
+ * (`error`, `error-darken-1`, `error-lighten-2`, ...), so one set covers
+ * the whole family.
+ *
+ * [LAW:one-way-deps] Imports flow `core/oklch → themes/transpose`;
+ * nothing in core/ depends back on this file.
+ */
+import { type ThemeKey } from "../core/oklch.js";
+import { Palette } from "./palette.js";
+/**
+ * Semantic roots whose hue is locked under transposition. `error` must
+ * look red-ish, `success` green-ish, `warning` amber-ish — rotating the
+ * hue would make the UI lie about meaning. Lightness and chroma *still*
+ * transform for these roles, so they invert correctly during dark↔light
+ * flips and respond to chroma scaling alongside everything else.
+ */
+export declare const ANCHORED_ROOTS: ReadonlySet<string>;
+/**
+ * Whether a palette var's hue is locked under transposition. The single
+ * predicate used by `transposePalette`. Exported so callers building
+ * higher-level theme machinery can stay consistent with the locking rule.
+ */
+export declare function isAnchored(varName: string): boolean;
+/**
+ * Return a new `Palette` whose colors are the transposition of `palette`'s
+ * colors by `key`. Pure. Identity (`IDENTITY`) returns a Palette with byte-exact
+ * colors — fast-pathed so identity does not pay the sRGB↔OKLCH round-trip
+ * quantization cost.
+ *
+ * The `dark` flag of the result is derived from the actual lightness of
+ * the resulting `background` var (`Oklch.fromRgba(bg).l < 0.5`) — *not*
+ * from the key's coefficients. The strongest theorem: "dark iff
+ * background is dark." This is honest under every transform — pure
+ * lightness shifts, mirror-inversions, hue rotations that don't touch L,
+ * and combinations of all three. [LAW:types-are-the-program]
+ *
+ * The transposing path throws if the palette has no `background` var (the
+ * `dark`-flag derivation has nothing to read). Failing loudly is preferred
+ * over a silent fallback because the alternative — trusting the source
+ * `palette.dark` after an arbitrary L-transform — produces flags that lie.
+ * The identity fast-path is exempt: it preserves the source `dark` flag
+ * verbatim (no derivation), so it needs no `background` and never throws.
+ *
+ * @param name Optional override for the resulting palette name. Defaults
+ *   to the source palette's name. Callers building a family of transposed
+ *   palettes (e.g. "gruvbox +60°") supply their own.
+ */
+export declare function transposePalette(palette: Palette, key: ThemeKey, name?: string): Palette;
+/**
+ * Build the `ThemeKey` that rotates `palette` so its *tonic* var lands on
+ * `targetHueDeg`. The musical operation directly: a key is the set of
+ * intervals from the tonic, so "play this theme in the key of <hue>" means
+ * "shift every color by exactly the interval that carries the tonic's
+ * current hue to the target." Pick the tonic's pitch and the rest follows.
+ *
+ * Returns a hue-only key (chroma and lightness untouched). Callers that also
+ * want to scale chroma or shift lightness spread their own axes over the
+ * result — those are independent transposition dimensions, not part of
+ * choosing the key. [LAW:one-type-per-behavior] a degree-shift key and a
+ * root-note key are the *same* transform; this is just a second constructor
+ * for it, so `transposePalette` stays untouched.
+ *
+ * Throws if `tonicVar` is absent — the interval has no anchor to measure
+ * from, so there is no honest key to return. Failing loudly beats inventing
+ * a zero shift that would silently mean "no transposition."
+ */
+export declare function themeKeyForRoot(palette: Palette, tonicVar: string, targetHueDeg: number): ThemeKey;

package/dist/themes/transpose.js

@@ -0,0 +1,138 @@
+/**
+ * Transpose a Palette to a new "key" — analogous to transposing a melody.
+ *
+ *   melody / chord progression  ::  Palette (relationships between colors)
+ *                key (signature) ::  ThemeKey (hue / chroma / lightness deltas)
+ *      "in C major" / "in D…"   ::  the resulting transposed Palette
+ *
+ * Because OKLCH is perceptually uniform, "+30° hue" looks like a
+ * consistent jump everywhere on the color wheel — the way a perfect-fifth
+ * interval sounds the same in every musical key. Transposition is closed
+ * under composition: `transpose(transpose(p, k1), k2)` produces the same
+ * colors as a single transpose with the combined deltas, modulo round-trip
+ * quantization.
+ *
+ * [LAW:dataflow-not-control-flow] A single uniform per-color transform
+ * runs for every var in the palette. Anchor protection selects *which*
+ * `ThemeKey` to apply (data), not *whether* to apply one (branch).
+ *
+ * [LAW:one-source-of-truth] Anchor classification lives only in
+ * `ANCHORED_ROOTS` below. The buildPalette derivation guarantees every
+ * variant of a semantic root shares the root as its hyphen prefix
+ * (`error`, `error-darken-1`, `error-lighten-2`, ...), so one set covers
+ * the whole family.
+ *
+ * [LAW:one-way-deps] Imports flow `core/oklch → themes/transpose`;
+ * nothing in core/ depends back on this file.
+ */
+import { Oklch, isIdentityKey } from "../core/oklch.js";
+import { Palette } from "./palette.js";
+/**
+ * Semantic roots whose hue is locked under transposition. `error` must
+ * look red-ish, `success` green-ish, `warning` amber-ish — rotating the
+ * hue would make the UI lie about meaning. Lightness and chroma *still*
+ * transform for these roles, so they invert correctly during dark↔light
+ * flips and respond to chroma scaling alongside everything else.
+ */
+// [LAW:types-are-the-program] The `ReadonlySet` type is the immutability
+// enforcement — typed code cannot call `add`/`delete`. (`Object.freeze` is
+// not used here because it is a no-op on Set membership; relying on it would
+// imply a runtime guarantee it does not provide.)
+export const ANCHORED_ROOTS = new Set([
+    "error",
+    "success",
+    "warning",
+]);
+function rootOf(varName) {
+    const dash = varName.indexOf("-");
+    return dash === -1 ? varName : varName.slice(0, dash);
+}
+/**
+ * Whether a palette var's hue is locked under transposition. The single
+ * predicate used by `transposePalette`. Exported so callers building
+ * higher-level theme machinery can stay consistent with the locking rule.
+ */
+export function isAnchored(varName) {
+    return ANCHORED_ROOTS.has(rootOf(varName));
+}
+/**
+ * Return a new `Palette` whose colors are the transposition of `palette`'s
+ * colors by `key`. Pure. Identity (`IDENTITY`) returns a Palette with byte-exact
+ * colors — fast-pathed so identity does not pay the sRGB↔OKLCH round-trip
+ * quantization cost.
+ *
+ * The `dark` flag of the result is derived from the actual lightness of
+ * the resulting `background` var (`Oklch.fromRgba(bg).l < 0.5`) — *not*
+ * from the key's coefficients. The strongest theorem: "dark iff
+ * background is dark." This is honest under every transform — pure
+ * lightness shifts, mirror-inversions, hue rotations that don't touch L,
+ * and combinations of all three. [LAW:types-are-the-program]
+ *
+ * The transposing path throws if the palette has no `background` var (the
+ * `dark`-flag derivation has nothing to read). Failing loudly is preferred
+ * over a silent fallback because the alternative — trusting the source
+ * `palette.dark` after an arbitrary L-transform — produces flags that lie.
+ * The identity fast-path is exempt: it preserves the source `dark` flag
+ * verbatim (no derivation), so it needs no `background` and never throws.
+ *
+ * @param name Optional override for the resulting palette name. Defaults
+ *   to the source palette's name. Callers building a family of transposed
+ *   palettes (e.g. "gruvbox +60°") supply their own.
+ */
+export function transposePalette(palette, key, name) {
+    if (isIdentityKey(key)) {
+        return new Palette(name ?? palette.name, palette.dark, palette.vars);
+    }
+    // Anchors share *everything except* hue with the user's key. They still
+    // lightness-invert in a dark↔light flip; they still chroma-scale in a
+    // saturation sweep — only their hue is held.
+    const anchorKey = { ...key, hueShift: 0 };
+    const next = new Map();
+    for (const [varName, color] of palette.vars) {
+        const effective = isAnchored(varName) ? anchorKey : key;
+        next.set(varName, Oklch.fromRgba(color).applyKey(effective).toRgba());
+    }
+    const newBackground = next.get("background");
+    if (newBackground === undefined) {
+        throw new Error(`transposePalette: palette "${palette.name}" has no "background" ` +
+            `var; cannot derive the dark flag without a background color.`);
+    }
+    const newDark = Oklch.fromRgba(newBackground).l < 0.5;
+    return new Palette(name ?? palette.name, newDark, next);
+}
+/**
+ * Build the `ThemeKey` that rotates `palette` so its *tonic* var lands on
+ * `targetHueDeg`. The musical operation directly: a key is the set of
+ * intervals from the tonic, so "play this theme in the key of <hue>" means
+ * "shift every color by exactly the interval that carries the tonic's
+ * current hue to the target." Pick the tonic's pitch and the rest follows.
+ *
+ * Returns a hue-only key (chroma and lightness untouched). Callers that also
+ * want to scale chroma or shift lightness spread their own axes over the
+ * result — those are independent transposition dimensions, not part of
+ * choosing the key. [LAW:one-type-per-behavior] a degree-shift key and a
+ * root-note key are the *same* transform; this is just a second constructor
+ * for it, so `transposePalette` stays untouched.
+ *
+ * Throws if `tonicVar` is absent — the interval has no anchor to measure
+ * from, so there is no honest key to return. Failing loudly beats inventing
+ * a zero shift that would silently mean "no transposition."
+ */
+export function themeKeyForRoot(palette, tonicVar, targetHueDeg) {
+    // Validate the numeric input at the boundary: a non-finite target would
+    // propagate as NaN to Oklch's constructor several calls downstream, where
+    // the error is far less actionable.
+    if (!Number.isFinite(targetHueDeg)) {
+        throw new RangeError(`themeKeyForRoot: targetHueDeg must be a finite number; got ${targetHueDeg}`);
+    }
+    const tonic = palette.get(tonicVar);
+    if (tonic === undefined) {
+        throw new Error(`themeKeyForRoot: palette "${palette.name}" has no "${tonicVar}" var ` +
+            `to use as the tonic; cannot measure the transposition interval.`);
+    }
+    const tonicHue = Oklch.fromRgba(tonic).h;
+    let hueShift = (targetHueDeg - tonicHue) % 360;
+    if (hueShift < 0)
+        hueShift += 360;
+    return { hueShift, chromaScale: 1, lightnessScale: 1, lightnessShift: 0 };
+}

package/dist/widgets/button.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Button widget — labeled action trigger with variant styling.
+ * [LAW:dataflow-not-control-flow] rendering is a pure function of observable state.
+ * [LAW:one-type-per-behavior] shared widget infrastructure lives on WidgetBase.
+ *
+ * Four visual states:
+ *   normal  — variant colors from theme semantic palette (muted)
+ *   hover   — full variant accent bg + on-accent fg (WCAG contrast)
+ *   focus   — brackets [ label ] surrounding the button
+ *   active  — same color pair as hover, plus bold (pressed cue)
+ *
+ * States compose: active > focus > hover > normal. Active and hover
+ * deliberately share colors — active differentiates via bold rather
+ * than fg/bg inversion, because inversion produces mostly-accent text
+ * on bg-tinted surface, which is unreadable for accents whose contrast
+ * partner depends on luminance.
+ */
+import { Segment } from "../core/segment.js";
+import type { RenderOptions } from "../core/protocol.js";
+import type { TerminalTheme } from "../core/color.js";
+import { ThemedWidget } from "./themed-widget.js";
+import type { KeyEvent, WidgetMouseEvent } from "./types.js";
+export type ButtonVariant = "default" | "primary" | "success" | "warning" | "danger";
+export interface ButtonOptions {
+    label: string;
+    variant?: ButtonVariant;
+    id?: string;
+    disabled?: boolean;
+    theme?: TerminalTheme;
+}
+export declare class Button extends ThemedWidget {
+    readonly id: string;
+    readonly focusable = true;
+    accessor label: string;
+    accessor variant: ButtonVariant;
+    constructor(options: ButtonOptions);
+    handleKey(event: KeyEvent): void;
+    handleMouse(event: WidgetMouseEvent): void;
+    setActive(value: boolean): void;
+    protected draw(_options: RenderOptions): Iterable<Segment>;
+    measure(_options: RenderOptions): {
+        minimum: number;
+        maximum: number;
+    };
+}

package/dist/widgets/button.js

@@ -0,0 +1,177 @@
+/**
+ * Button widget — labeled action trigger with variant styling.
+ * [LAW:dataflow-not-control-flow] rendering is a pure function of observable state.
+ * [LAW:one-type-per-behavior] shared widget infrastructure lives on WidgetBase.
+ *
+ * Four visual states:
+ *   normal  — variant colors from theme semantic palette (muted)
+ *   hover   — full variant accent bg + on-accent fg (WCAG contrast)
+ *   focus   — brackets [ label ] surrounding the button
+ *   active  — same color pair as hover, plus bold (pressed cue)
+ *
+ * States compose: active > focus > hover > normal. Active and hover
+ * deliberately share colors — active differentiates via bold rather
+ * than fg/bg inversion, because inversion produces mostly-accent text
+ * on bg-tinted surface, which is unreadable for accents whose contrast
+ * partner depends on luminance.
+ */
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+import { observable, action, observableRef } from "mobx";
+import { Segment } from "../core/segment.js";
+import { Style } from "../core/style.js";
+import { cellLen } from "../core/cells.js";
+import { ThemedWidget } from "./themed-widget.js";
+import { ink } from "./ink.js";
+// Variant → palette key mapping. Per variant:
+//   bg / fg     — normal state. Muted accent bg + mostly-accent fg → readable.
+//   hover       — full accent bg; pair with hoverFg, NOT with `fg`. The
+//                 text-* keys are mostly-accent and would clash on a full
+//                 accent bg.
+//   hoverFg     — WCAG-correct contrast colour (on-${accent}) for full bg.
+const VARIANT_KEYS = {
+    default: { bg: "surface", fg: "foreground", hover: "primary", hoverFg: "on-primary" },
+    primary: { bg: "primary-muted", fg: "text-primary", hover: "primary", hoverFg: "on-primary" },
+    success: { bg: "success-muted", fg: "text-success", hover: "success", hoverFg: "on-success" },
+    warning: { bg: "warning-muted", fg: "text-warning", hover: "warning", hoverFg: "on-warning" },
+    danger: { bg: "error-muted", fg: "text-error", hover: "error", hoverFg: "on-error" },
+};
+let Button = (() => {
+    let _classSuper = ThemedWidget;
+    let _instanceExtraInitializers = [];
+    let _label_decorators;
+    let _label_initializers = [];
+    let _label_extraInitializers = [];
+    let _variant_decorators;
+    let _variant_initializers = [];
+    let _variant_extraInitializers = [];
+    let _handleKey_decorators;
+    let _handleMouse_decorators;
+    let _setActive_decorators;
+    return class Button extends _classSuper {
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+            _label_decorators = [observable];
+            _variant_decorators = [observableRef];
+            _handleKey_decorators = [action];
+            _handleMouse_decorators = [action];
+            _setActive_decorators = [action];
+            __esDecorate(this, null, _label_decorators, { kind: "accessor", name: "label", static: false, private: false, access: { has: obj => "label" in obj, get: obj => obj.label, set: (obj, value) => { obj.label = value; } }, metadata: _metadata }, _label_initializers, _label_extraInitializers);
+            __esDecorate(this, null, _variant_decorators, { kind: "accessor", name: "variant", static: false, private: false, access: { has: obj => "variant" in obj, get: obj => obj.variant, set: (obj, value) => { obj.variant = value; } }, metadata: _metadata }, _variant_initializers, _variant_extraInitializers);
+            __esDecorate(this, null, _handleKey_decorators, { kind: "method", name: "handleKey", static: false, private: false, access: { has: obj => "handleKey" in obj, get: obj => obj.handleKey }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _handleMouse_decorators, { kind: "method", name: "handleMouse", static: false, private: false, access: { has: obj => "handleMouse" in obj, get: obj => obj.handleMouse }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _setActive_decorators, { kind: "method", name: "setActive", static: false, private: false, access: { has: obj => "setActive" in obj, get: obj => obj.setActive }, metadata: _metadata }, null, _instanceExtraInitializers);
+            if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        }
+        id = __runInitializers(this, _instanceExtraInitializers);
+        focusable = true;
+        #label_accessor_storage = __runInitializers(this, _label_initializers, void 0);
+        get label() { return this.#label_accessor_storage; }
+        set label(value) { this.#label_accessor_storage = value; }
+        #variant_accessor_storage = (__runInitializers(this, _label_extraInitializers), __runInitializers(this, _variant_initializers, void 0));
+        get variant() { return this.#variant_accessor_storage; }
+        set variant(value) { this.#variant_accessor_storage = value; }
+        constructor(options) {
+            super(options.theme);
+            __runInitializers(this, _variant_extraInitializers);
+            this.id = options.id ?? `button-${options.label.toLowerCase().replace(/\s+/g, "-")}`;
+            this.label = options.label;
+            this.variant = options.variant ?? "default";
+            this.disabled = options.disabled ?? false;
+        }
+        // --- Event handlers ---
+        handleKey(event) {
+            if (this.disabled)
+                return;
+            if (event.key === "enter" || event.key === "space") {
+                this.active = true;
+                this.emitSubmit();
+                // [LAW:one-source-of-truth] Keyboard activation must leave the widget
+                // in the same end state as mouse activation: `active` cleared after
+                // the press. Mouse has a natural mouse_up to clear it; keyboard does
+                // not, so we schedule the clear on the next microtask. The single-
+                // frame `active=true` paint gives the user the visual "pressed" cue
+                // and is then cleared, matching mouse behaviour.
+                queueMicrotask(() => { if (this.active)
+                    this.setActive(false); });
+                event.stop();
+            }
+        }
+        handleMouse(event) {
+            if (this.disabled)
+                return;
+            if (event.type === "mouse_down") {
+                this.active = true;
+            }
+            // A release that dragged off the button cancels the press.
+            if (event.type === "mouse_up") {
+                if (this.active) {
+                    this.active = false;
+                    if (event.over)
+                        this.emitSubmit();
+                }
+            }
+        }
+        // --- Active mutator (the keyboard-activation microtask uses this) ---
+        setActive(value) { this.active = value; }
+        // --- Rendering ---
+        draw(_options) {
+            // [LAW:dataflow-not-control-flow] same segment count and width every state
+            const focused = this.focused;
+            const left = focused ? "[" : " ";
+            const right = focused ? "]" : " ";
+            const text = `${left} ${this.label} ${right}`;
+            if (this.disabled) {
+                return [new Segment(text, new Style(this.disabledInk))];
+            }
+            // Active and hover share the same colour pair (full accent bg + on-accent fg).
+            // Active is differentiated by bold, not by inverting fg/bg — inversion gives
+            // mostly-accent text on mostly-bg-tinted background, which is unreadable for
+            // accents whose contrast partner depends on luminance.
+            const keys = VARIANT_KEYS[this.variant];
+            if (this.active || this.hovered) {
+                return [new Segment(text, new Style({ ...ink(this.theme, keys.hoverFg, keys.hover), bold: this.active }))];
+            }
+            return [new Segment(text, new Style(ink(this.theme, keys.fg, keys.bg)))];
+        }
+        measure(_options) {
+            // [LAW:one-source-of-truth] cellLen is the cell-width authority; .length
+            // counts UTF-16 code units and miscounts wide / emoji characters.
+            const width = cellLen(this.label) + 4;
+            return { minimum: width, maximum: width };
+        }
+    };
+})();
+export { Button };

package/dist/widgets/checkbox.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Checkbox widget — boolean toggle with label.
+ * [LAW:dataflow-not-control-flow] one Segment of fixed width every render;
+ * the indicator character and style come from observable state.
+ * [LAW:one-type-per-behavior] shared widget infrastructure lives on WidgetBase.
+ *
+ * Visual states:
+ *   unchecked — "[ ] label"
+ *   checked   — "[✓] label"  (ASCII fallback "[x] label" when options.asciiOnly)
+ *   focused   — underline on the rendered segment (no width change)
+ *   disabled  — dimmed
+ */
+import { Segment } from "../core/segment.js";
+import { type RenderOptions } from "../core/protocol.js";
+import type { TerminalTheme } from "../core/color.js";
+import { ThemedWidget } from "./themed-widget.js";
+import type { KeyEvent, WidgetMouseEvent } from "./types.js";
+export interface CheckboxOptions {
+    label: string;
+    checked?: boolean;
+    id?: string;
+    disabled?: boolean;
+    theme?: TerminalTheme;
+}
+export declare class Checkbox extends ThemedWidget {
+    readonly id: string;
+    readonly focusable = true;
+    accessor label: string;
+    accessor checked: boolean;
+    constructor(options: CheckboxOptions);
+    handleKey(event: KeyEvent): void;
+    handleMouse(event: WidgetMouseEvent): void;
+    protected draw(options: RenderOptions): Iterable<Segment>;
+    measure(_options: RenderOptions): {
+        minimum: number;
+        maximum: number;
+    };
+}