@promptctl/rich-js 0.1.0 → 0.3.0

package/dist/template-bindings/index.js

@@ -1,16 +1,21 @@
 /**
  * rich-js template bindings — public entry point.
  *
- * [LAW:one-source-of-truth] This module is the single place where rich-js's
- * styling vocabulary is exposed as `@promptctl/go-template-js` template
- * functions. The current registration set covers foreground colour
- * (named, palette index, hex, RGB), background (`on`), and text
- * attributes (canonical names, short aliases, `not_*` negations) — all
- * registered via `richTextStyleFuncs`. `link`, palette / theme /
- * auto-contrast helpers, and per-position hue rotation ship in follow-up
- * epics on the same `template-bindings` topic and merge into this same
- * map. Consumers compose templates against the Engine returned here;
- * nesting is plain function composition (`{{ red (bold "x") }}`), not a
+ * [LAW:one-source-of-truth] This module is the public entry point for
+ * rich-js's styling vocabulary as `@promptctl/go-template-js` template
+ * functions. Two complementary registrations are exported:
+ *
+ * - `richTextFuncs()` — foreground colours, background, text attributes, and
+ *   `link`. Does not require configuration; safe to register unconditionally.
+ * - `paletteFuncs(resolver)` — semantic palette, auto-contrast, and extended
+ *   spec forms. Requires a `PaletteResolver` argument bound to the active
+ *   theme; consumers merge it alongside `richTextFuncs()`.
+ *
+ * `createRichTextEngine()` is convenience sugar that wires up `richTextFuncs()`
+ * only — it does not include `paletteFuncs`, because palette functions require
+ * a resolver the factory cannot supply. Consumers that need palette access
+ * call `paletteFuncs(resolver)` and merge it into their own engine config.
+ * Nesting is plain function composition (`{{ red (bold "x") }}`), not a
  * second markup grammar.
  *
  * Fragment type: `RichText`. Chosen because it is the library's primary
@@ -23,16 +28,17 @@
  */
 import { createEngine } from "@promptctl/go-template-js";
 import { RichText } from "../core/text.js";
+import { Style } from "../core/style.js";
+import { Segment } from "../core/segment.js";
 import { richTextStyleFuncs } from "./style-funcs.js";
+export { paletteFuncs } from "./palette-funcs.js";
 /**
- * Funcs registered by the rich-js binding. Style functions
- * (foreground / attribute / background) are populated by
- * `richTextStyleFuncs`; subsequent epics on the `template-bindings`
- * topic merge `link`, palette/theme/auto-contrast, and per-position
- * hue rotation into the same map. Exposed as a factory (not a const)
- * so future registrations that need configuration (e.g. a palette
- * resolver bound at construction time) have a place to receive
- * arguments without breaking the public shape.
+ * Funcs registered by the rich-js binding — style functions (foreground,
+ * background, attributes) and the `link` cell-splitter. Exposed as a factory
+ * so future registrations that need configuration have a place to receive
+ * arguments. Palette/theme/auto-contrast functions ship separately via
+ * `paletteFuncs(resolver)` and are merged at consumer side — they require a
+ * `PaletteResolver` argument and so cannot be included in this generic call.
  *
  * `FuncMap` is not parameterised over `T` in `@promptctl/go-template-js` — the engine's
  * `T` lives on the `Engine`/`EngineConfig`, and per-function input/output
@@ -67,4 +73,63 @@ export function createRichTextEngine() {
         funcs: richTextFuncs(),
     });
 }
+/**
+ * Compile a template source against `engine` and render the result to a
+ * flat `Segment[]`. The 90%-case convenience over chaining `engine.compile`,
+ * `RichText.fromFragments`, and `.render` by hand:
+ *
+ * - Runs `engine.compile(source)(scope)` to get the engine's `RichText[]`.
+ * - Flattens that fragment list into a single styled `RichText` via
+ *   `RichText.fromFragments` so every fragment's wrapping style survives.
+ * - Renders to a `Segment[]` at the requested `maxWidth`.
+ * - Wraps the whole flow in a try/catch — on parse/evaluate failure,
+ *   emits a single dim styled `[error: <message>]` segment the caller can
+ *   drop into their layout. No bespoke fallback wiring required at every
+ *   call site.
+ *
+ * [LAW:single-enforcer] One place owns "render a template to segments,
+ * degrade gracefully on errors" — every consumer that wants this exact
+ * shape reads from here rather than re-implementing the same try/catch +
+ * error-formatting glue.
+ *
+ * For the 10% — custom error UX, intermediate access to the `RichText`,
+ * pre-compiled templates re-used many times — call the engine directly
+ * and use `RichText.fromFragments` to flatten. This helper is sugar for
+ * the live-render case (e.g. a preview pane), not a replacement for the
+ * compile-once-evaluate-many pattern.
+ *
+ * @param maxWidth defaults to 400 — large enough that downstream `splitLines`
+ * / `adjustLineLength` clipping decides actual width, matching the typical
+ * "render wide, fit on output" pipeline.
+ * @param errorStyle is a `Style.parse` spec (default `"red dim"`).
+ */
+export function renderTemplate(engine, source, scope = {}, options) {
+    try {
+        const frags = engine.compile(source)(scope);
+        const rt = RichText.fromFragments(frags);
+        return Array.from(rt.render({
+            maxWidth: options?.maxWidth ?? 400,
+            isTerminal: true,
+            encoding: "utf-8",
+        }));
+    }
+    catch (e) {
+        return [new Segment(`[error: ${String(e).slice(0, 80)}]`, safeErrorStyle(options?.errorStyle))];
+    }
+}
+// [LAW:single-enforcer] The error-path Style must not itself throw, or
+// the whole "degrade gracefully" promise of renderTemplate is broken. A
+// bogus user-supplied `errorStyle` spec falls back to a hard-coded safe
+// Style — never propagates the parse failure to the caller.
+const FALLBACK_ERROR_STYLE = new Style({ color: "red", dim: true });
+function safeErrorStyle(spec) {
+    if (spec === undefined)
+        return FALLBACK_ERROR_STYLE;
+    try {
+        return Style.parse(spec);
+    }
+    catch {
+        return FALLBACK_ERROR_STYLE;
+    }
+}
 //# sourceMappingURL=index.js.map

package/dist/template-bindings/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/template-bindings/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,YAAY,EAA6B,MAAM,2BAA2B,CAAC;AACpF,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,aAAa;IAC3B,OAAO,kBAAkB,EAAE,CAAC;AAC9B,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO,YAAY,CAAW;QAC5B,UAAU,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC;QAClC,QAAQ,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,KAAK;QAC1B,KAAK,EAAE,aAAa,EAAE;KACvB,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/template-bindings/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,YAAY,EAA6B,MAAM,2BAA2B,CAAC;AACpF,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAEtD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,aAAa;IAC3B,OAAO,kBAAkB,EAAE,CAAC;AAC9B,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO,YAAY,CAAW;QAC5B,UAAU,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC;QAClC,QAAQ,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,KAAK;QAC1B,KAAK,EAAE,aAAa,EAAE;KACvB,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,cAAc,CAC5B,MAAwB,EACxB,MAAc,EACd,QAAiB,EAAE,EACnB,OAAoD;IAEpD,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC;QAC5C,MAAM,EAAE,GAAG,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QACzC,OAAO,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC;YAC1B,QAAQ,EAAE,OAAO,EAAE,QAAQ,IAAI,GAAG;YAClC,UAAU,EAAE,IAAI;YAChB,QAAQ,EAAE,OAAO;SAClB,CAAC,CAAC,CAAC;IACN,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,CAAC,IAAI,OAAO,CAAC,WAAW,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,cAAc,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;IAClG,CAAC;AACH,CAAC;AAED,uEAAuE;AACvE,wEAAwE;AACxE,wEAAwE;AACxE,4DAA4D;AAC5D,MAAM,oBAAoB,GAAG,IAAI,KAAK,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC;AACpE,SAAS,cAAc,CAAC,IAAwB;IAC9C,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,oBAAoB,CAAC;IACpD,IAAI,CAAC;QACH,OAAO,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,oBAAoB,CAAC;IAC9B,CAAC;AACH,CAAC"}

package/dist/template-bindings/palette-funcs.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Palette / theme / auto-contrast function registrations for the rich-js
+ * template binding.
+ *
+ * [LAW:one-source-of-truth] All palette resolution flows through the existing
+ * `PaletteResolver.resolve(spec, ctx)` API — this module adds no resolution
+ * logic of its own. The template functions here are thin adaptors that translate
+ * function call arguments into a `(spec, ctx)` call and wrap the resulting
+ * `ColorRgba` as a `Style` applied to the child fragment.
+ *
+ * [LAW:dataflow-not-control-flow] Every function follows the same shape:
+ * resolve spec → apply as foreground color → return styled fragment. The
+ * variability is in the spec string and the optional against context; the
+ * operation is fixed.
+ *
+ * ### Surface design rationale
+ *
+ * Four layers of ergonomics:
+ *
+ * 1. **Semantic-name functions** — one function per palette variable whose
+ *    name is a valid Go template identifier (no hyphens). `{{ primary child }}`,
+ *    `{{ accent child }}`, etc. The happy path: common semantic names read
+ *    cleanly in templates. Hyphenated names (`primary-muted`, `text-primary`)
+ *    cannot be Go template identifiers and are accessed via `palette`.
+ *
+ * 2. **`palette "spec" child`** — the general-purpose function for any spec
+ *    that does not need a background context (bare names and darken/lighten
+ *    modifiers). Covers hyphenated names and modifier chains.
+ *
+ * 3. **`paletteOver "spec" "#bgHex" child`** — for specs that require a
+ *    background context: alpha compositing (`"primary 50%"`) and auto-contrast
+ *    (`"auto"`, `"auto 33%"`). The bg color is threaded as an explicit hex
+ *    argument rather than via a scope side-channel — no mutable state, no
+ *    closure magic; the data flows through the function call.
+ *
+ * 4. **`auto "#bgHex" child`** — syntactic sugar for
+ *    `{{ paletteOver "auto" "#bgHex" child }}`, the common auto-contrast case.
+ *
+ * ### Theme switching
+ *
+ * `paletteFuncs(resolver)` captures `resolver` at construction time. Consumers
+ * that need runtime theme switching create a new `paletteFuncs()` from the new
+ * theme's resolver and rebuild their engine (or merge into a fresh `FuncMap`).
+ * The same template *source* produces different colors because the functions in
+ * the engine changed — the template text is the same, the resolver differs.
+ */
+import type { FuncMap } from "@promptctl/go-template-js";
+import { PaletteResolver } from "../themes/paletteResolver.js";
+/**
+ * Build a `FuncMap` exposing the semantic palette of `resolver` as template
+ * functions. Merge into `richTextFuncs()` (or pass to `createEngine`) to make
+ * palette colors available in templates.
+ *
+ * Registered functions:
+ * - One function per palette variable whose name is a valid Go template
+ *   identifier: `{{ primary child }}`, `{{ accent child }}`, etc.
+ * - `palette "spec" child` — any spec without background context.
+ * - `paletteOver "spec" "#bgHex" child` — any spec needing a background (alpha,
+ *   auto-contrast).
+ * - `auto "#bgHex" child` — sugar for `paletteOver "auto" bgHex child`.
+ *
+ * @example
+ * ```ts
+ * import { createEngine } from "@promptctl/go-template-js";
+ * import { GRUVBOX, PaletteResolver, RichText } from "rich-js";
+ * import { richTextFuncs, paletteFuncs } from "rich-js/template-bindings";
+ *
+ * const engine = createEngine({
+ *   fromString: (s) => new RichText(s),
+ *   toString: (rt) => rt.plain,
+ *   funcs: { ...richTextFuncs(), ...paletteFuncs(new PaletteResolver(GRUVBOX.palette)) },
+ * });
+ * ```
+ */
+export declare function paletteFuncs(resolver: PaletteResolver): FuncMap;
+//# sourceMappingURL=palette-funcs.d.ts.map

package/dist/template-bindings/palette-funcs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"palette-funcs.d.ts","sourceRoot":"","sources":["../../src/template-bindings/palette-funcs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAgB,MAAM,2BAA2B,CAAC;AAIvE,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAiG/D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAO/D"}

package/dist/template-bindings/palette-funcs.js

@@ -0,0 +1,157 @@
+/**
+ * Palette / theme / auto-contrast function registrations for the rich-js
+ * template binding.
+ *
+ * [LAW:one-source-of-truth] All palette resolution flows through the existing
+ * `PaletteResolver.resolve(spec, ctx)` API — this module adds no resolution
+ * logic of its own. The template functions here are thin adaptors that translate
+ * function call arguments into a `(spec, ctx)` call and wrap the resulting
+ * `ColorRgba` as a `Style` applied to the child fragment.
+ *
+ * [LAW:dataflow-not-control-flow] Every function follows the same shape:
+ * resolve spec → apply as foreground color → return styled fragment. The
+ * variability is in the spec string and the optional against context; the
+ * operation is fixed.
+ *
+ * ### Surface design rationale
+ *
+ * Four layers of ergonomics:
+ *
+ * 1. **Semantic-name functions** — one function per palette variable whose
+ *    name is a valid Go template identifier (no hyphens). `{{ primary child }}`,
+ *    `{{ accent child }}`, etc. The happy path: common semantic names read
+ *    cleanly in templates. Hyphenated names (`primary-muted`, `text-primary`)
+ *    cannot be Go template identifiers and are accessed via `palette`.
+ *
+ * 2. **`palette "spec" child`** — the general-purpose function for any spec
+ *    that does not need a background context (bare names and darken/lighten
+ *    modifiers). Covers hyphenated names and modifier chains.
+ *
+ * 3. **`paletteOver "spec" "#bgHex" child`** — for specs that require a
+ *    background context: alpha compositing (`"primary 50%"`) and auto-contrast
+ *    (`"auto"`, `"auto 33%"`). The bg color is threaded as an explicit hex
+ *    argument rather than via a scope side-channel — no mutable state, no
+ *    closure magic; the data flows through the function call.
+ *
+ * 4. **`auto "#bgHex" child`** — syntactic sugar for
+ *    `{{ paletteOver "auto" "#bgHex" child }}`, the common auto-contrast case.
+ *
+ * ### Theme switching
+ *
+ * `paletteFuncs(resolver)` captures `resolver` at construction time. Consumers
+ * that need runtime theme switching create a new `paletteFuncs()` from the new
+ * theme's resolver and rebuild their engine (or merge into a fresh `FuncMap`).
+ * The same template *source* produces different colors because the functions in
+ * the engine changed — the template text is the same, the resolver differs.
+ */
+import { ColorSpec } from "../core/color.js";
+import { Style } from "../core/style.js";
+import { applyStyleToFragment } from "./helpers.js";
+// Regex for validating hex bg strings accepted by `paletteOver` and `auto`.
+// Accepts #RRGGBB and #RRGGBBAA — same gate as the `hex` style function.
+const HEX_BG_RE = /^#[0-9a-fA-F]{6}([0-9a-fA-F]{2})?$/;
+/**
+ * Convert a hex string to `ColorRgba`. Only #RRGGBB / #RRGGBBAA accepted.
+ * Throws `RangeError` on invalid input — surfaces as an `EvalError` in the
+ * template engine, giving the author a precise failure message.
+ */
+function hexToColorRgba(hex) {
+    if (!HEX_BG_RE.test(hex)) {
+        throw new RangeError(`palette background expected #RRGGBB or #RRGGBBAA, got ${JSON.stringify(hex)}`);
+    }
+    // ColorSpec.parse("#RRGGBB") → TRUECOLOR spec; getTruecolor() returns value directly.
+    return ColorSpec.parse(hex).getTruecolor();
+}
+/**
+ * Resolve `spec` against the resolver (with optional background context) and
+ * apply the resulting color as a foreground `Style` on `child`.
+ *
+ * Throws on resolution failure with a contextual message — including a hint to
+ * use `paletteOver` when the spec needs a background but none was provided.
+ */
+function resolveAndApply(resolver, spec, against, child) {
+    const color = resolver.resolve(spec, against !== undefined ? { against } : undefined);
+    if (color === null) {
+        const hint = against === undefined
+            ? "; for specs with alpha or auto-contrast, use paletteOver"
+            : "";
+        throw new Error(`palette spec ${JSON.stringify(spec)} did not resolve — check the spec string is valid and the variable exists${hint}`);
+    }
+    return applyStyleToFragment(child, new Style({ color: ColorSpec.fromRgba(color) }));
+}
+// [LAW:types-are-the-program] Only palette var names that are valid Go template
+// identifiers (letter/underscore start, alphanumeric/underscore body) get
+// individual functions. Hyphenated names like "primary-muted" parse as subtraction
+// in Go template syntax and cannot be function names.
+const IDENTIFIER_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function semanticNameFuncs(resolver) {
+    const out = {};
+    for (const name of resolver.palette.vars.keys()) {
+        if (!IDENTIFIER_RE.test(name))
+            continue;
+        // [LAW:dataflow-not-control-flow] Capture name; same fn shape for every entry.
+        const captured = name;
+        out[captured] = {
+            fn: ((child) => resolveAndApply(resolver, captured, undefined, child)),
+            argTypes: ["liftable"],
+            returnType: "T",
+        };
+    }
+    return out;
+}
+function makePaletteFunc(resolver) {
+    return {
+        fn: ((spec, child) => resolveAndApply(resolver, spec, undefined, child)),
+        argTypes: ["string", "liftable"],
+        returnType: "T",
+    };
+}
+function makePaletteOverFunc(resolver) {
+    return {
+        fn: ((spec, bgHex, child) => resolveAndApply(resolver, spec, hexToColorRgba(bgHex), child)),
+        argTypes: ["string", "string", "liftable"],
+        returnType: "T",
+    };
+}
+function makeAutoFunc(resolver) {
+    return {
+        fn: ((bgHex, child) => resolveAndApply(resolver, "auto", hexToColorRgba(bgHex), child)),
+        argTypes: ["string", "liftable"],
+        returnType: "T",
+    };
+}
+/**
+ * Build a `FuncMap` exposing the semantic palette of `resolver` as template
+ * functions. Merge into `richTextFuncs()` (or pass to `createEngine`) to make
+ * palette colors available in templates.
+ *
+ * Registered functions:
+ * - One function per palette variable whose name is a valid Go template
+ *   identifier: `{{ primary child }}`, `{{ accent child }}`, etc.
+ * - `palette "spec" child` — any spec without background context.
+ * - `paletteOver "spec" "#bgHex" child` — any spec needing a background (alpha,
+ *   auto-contrast).
+ * - `auto "#bgHex" child` — sugar for `paletteOver "auto" bgHex child`.
+ *
+ * @example
+ * ```ts
+ * import { createEngine } from "@promptctl/go-template-js";
+ * import { GRUVBOX, PaletteResolver, RichText } from "rich-js";
+ * import { richTextFuncs, paletteFuncs } from "rich-js/template-bindings";
+ *
+ * const engine = createEngine({
+ *   fromString: (s) => new RichText(s),
+ *   toString: (rt) => rt.plain,
+ *   funcs: { ...richTextFuncs(), ...paletteFuncs(new PaletteResolver(GRUVBOX.palette)) },
+ * });
+ * ```
+ */
+export function paletteFuncs(resolver) {
+    return {
+        ...semanticNameFuncs(resolver),
+        palette: makePaletteFunc(resolver),
+        paletteOver: makePaletteOverFunc(resolver),
+        auto: makeAutoFunc(resolver),
+    };
+}
+//# sourceMappingURL=palette-funcs.js.map

package/dist/template-bindings/palette-funcs.js.map

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

package/dist/template-bindings/style-funcs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"style-funcs.d.ts","sourceRoot":"","sources":["../../src/template-bindings/style-funcs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAgB,MAAM,2BAA2B,CAAC;AAkKvE;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAU5C"}
+{"version":3,"file":"style-funcs.d.ts","sourceRoot":"","sources":["../../src/template-bindings/style-funcs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAgB,MAAM,2BAA2B,CAAC;AAqKvE;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAW5C"}

package/dist/template-bindings/style-funcs.js

@@ -18,33 +18,7 @@
  */
 import { Style, ATTRIBUTE_NAMES, ATTRIBUTE_SHORT_ALIASES, } from "../core/style.js";
 import { ColorSpec, ANSI_COLOR_NAMES } from "../core/color.js";
-import { RichText } from "../core/text.js";
-// --- Helpers ---
-/**
- * Apply a style on top of an already-styled RichText fragment.
- *
- * The engine's `"liftable"` arg type lifts string literals to
- * `RichText` via the binding's `fromString` *before* the body runs,
- * so by the time we get here, `child` is always a `RichText`. The
- * defensive instanceof check exists because `"liftable"` admits any
- * non-primitive value — the engine cannot prove the object is the
- * binding's own `T`. A misuse (`{{ red someMap }}`) lands here and
- * fails loudly rather than producing a malformed fragment.
- *
- * Conflict resolution follows `Style.add`: the outer (newly applied)
- * style wins. `red (bold "x")` → bold + red; `red (red "x")` → red.
- * Spans inside the inner fragment are preserved as-is — their styles
- * compose with the new wrapper at render time via the segment
- * pipeline's existing additive semantics.
- */
-function applyStyleToFragment(child, style) {
-    if (!(child instanceof RichText)) {
-        throw new TypeError(`style function expected a RichText fragment, got ${typeof child === "object" ? Object.prototype.toString.call(child) : typeof child}`);
-    }
-    const result = child.copy();
-    result.style = child.style.add(style);
-    return result;
-}
+import { applyStyleToFragment } from "./helpers.js";
 function fgFunc(style) {
     return {
         fn: ((child) => applyStyleToFragment(child, style)),
@@ -123,6 +97,37 @@ function attributeFuncs() {
     }
     return out;
 }
+// --- Style spec (multi-attribute one-shot) ---
+//
+// [LAW:one-source-of-truth] `style` accepts the same space-separated grammar
+// `Style.parse` consults — i.e. the inside of `[...]` markup. There is no
+// second parser: a spec that `Style.parse` accepts produces a fragment
+// byte-equivalent to the same spec inside markup, and one that `Style.parse`
+// rejects raises the same `StyleSyntaxError` surface.
+//
+// Motivation: the per-attribute functions (`bold`, `underline`, `hex`, …)
+// compose by nesting. For "apply a fixed set of styles to this child" or
+// "apply this named style set everywhere", nesting is awkward and the
+// style description is fragmented across multiple call sites. `style`
+// collapses that to a single call, and because the spec is a string it
+// flows through Go-template `$vars` and through scope without further
+// machinery:
+//
+//   {{ $alert := "bold underline #ff6b6b" }}
+//   {{ style $alert "alarm!" }}
+//   {{ style $alert .otherField }}
+//
+// [LAW:dataflow-not-control-flow] Same shape as every other style function:
+// a `Style` value (here built by `Style.parse(spec)`) plus a child, in,
+// styled child out. The variability is the spec string; the operation is
+// fixed.
+const styleSpecFunc = {
+    fn: ((spec, child) => {
+        return applyStyleToFragment(child, Style.parse(spec));
+    }),
+    argTypes: ["string", "liftable"],
+    returnType: "T",
+};
 // --- Hyperlink ---
 //
 // `link` is the cell-splitter for the multi-cell consumer contract.
@@ -167,6 +172,7 @@ export function richTextStyleFuncs() {
         on: onFunc,
         ...attributeFuncs(),
         link: linkFunc,
+        style: styleSpecFunc,
     };
 }
 //# sourceMappingURL=style-funcs.js.map

package/dist/template-bindings/style-funcs.js.map

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

package/dist/themes/colorMath.d.ts

@@ -20,4 +20,44 @@ export declare function alphaBlend(fg: ColorRgba, bg: ColorRgba, alpha: number):
  * where black and white are equally readable).
  */
 export declare function contrastFor(bg: ColorRgba): ColorRgba;
+/**
+ * WCAG 2.x relative luminance (0..1) of an opaque color. The single
+ * luminance function in the codebase — `contrastFor`, `contrastRatio`, and
+ * any caller that needs to reason about readability all funnel through it.
+ * [LAW:one-source-of-truth]
+ */
+export declare function relativeLuminance(c: ColorRgba): number;
+/**
+ * WCAG 2.x contrast ratio between two colors, in [1, 21]. Symmetric — the
+ * order of arguments does not matter. 4.5 is the AA threshold for normal
+ * text, 3.0 for large text.
+ *
+ * Assumes opaque inputs: alpha is ignored, since the displayed contrast of a
+ * translucent color depends on what it composites over. For a translucent
+ * foreground, flatten it first (or use `ensureContrast`, which does).
+ */
+export declare function contrastRatio(a: ColorRgba, b: ColorRgba): number;
+/**
+ * Return a foreground guaranteed to clear `minRatio` against `bg`, keeping the
+ * color *recognizably itself*. If the themed `fg` already passes it is returned
+ * untouched. Otherwise its OKLCH lightness is slid toward the pole that raises
+ * contrast — holding hue, and chroma where it stays in gamut (near the poles
+ * gamut clamping may reduce chroma, but hue is preserved) — until the ratio is
+ * met, so a blue on a dark-blue background becomes a lighter blue, not white.
+ * Only when no lightness of that hue can meet the ratio (a mid-toned
+ * background where even pure black-or-white tops out below the target) does it
+ * fall back to `contrastFor`'s black/white — the true maximum-contrast pick.
+ *
+ * A translucent `fg` is flattened over `bg` first (the displayed color is
+ * `fg` composited over `bg`), so the ratio is measured on what the eye
+ * actually sees and the returned color is opaque. `bg` is treated as the
+ * opaque substrate.
+ *
+ * [LAW:single-enforcer] The one place "is this text readable, and if not fix
+ * it" is decided. Callers route every fg/bg pair through here and the
+ * unreadable state never reaches output. [LAW:dataflow-not-control-flow] the
+ * function always runs; the measured ratio (data) decides how far the
+ * lightness moves — there is no caller-side "should I check contrast" branch.
+ */
+export declare function ensureContrast(fg: ColorRgba, bg: ColorRgba, minRatio?: number): ColorRgba;
 //# sourceMappingURL=colorMath.d.ts.map

package/dist/themes/colorMath.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"colorMath.d.ts","sourceRoot":"","sources":["../../src/themes/colorMath.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAY,MAAM,kBAAkB,CAAC;AAmEvD;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,CAIlE;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,CAEnE;AAED;;;GAGG;AACH,wBAAgB,UAAU,CACxB,EAAE,EAAE,SAAS,EACb,EAAE,EAAE,SAAS,EACb,KAAK,EAAE,MAAM,GACZ,SAAS,CAEX;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,SAAS,GAAG,SAAS,CAKpD"}
+{"version":3,"file":"colorMath.d.ts","sourceRoot":"","sources":["../../src/themes/colorMath.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAY,MAAM,kBAAkB,CAAC;AAoEvD;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,CAIlE;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,CAEnE;AAED;;;GAGG;AACH,wBAAgB,UAAU,CACxB,EAAE,EAAE,SAAS,EACb,EAAE,EAAE,SAAS,EACb,KAAK,EAAE,MAAM,GACZ,SAAS,CAEX;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,SAAS,GAAG,SAAS,CAKpD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,SAAS,GAAG,MAAM,CAMtD;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,GAAG,MAAM,CAMhE;AAMD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAC5B,EAAE,EAAE,SAAS,EACb,EAAE,EAAE,SAAS,EACb,QAAQ,SAAM,GACb,SAAS,CA+BX"}

package/dist/themes/colorMath.js

@@ -1,4 +1,5 @@
 import { ColorRgba, blendRgb } from "../core/color.js";
+import { Oklch } from "../core/oklch.js";
 const LEVEL_STEP = 0.1;
 function rgbToHsl(c) {
     const r = c.red / 255;
@@ -89,11 +90,91 @@ export function contrastFor(bg) {
         ? new ColorRgba(0, 0, 0)
         : new ColorRgba(255, 255, 255);
 }
-function relativeLuminance(c) {
+/**
+ * WCAG 2.x relative luminance (0..1) of an opaque color. The single
+ * luminance function in the codebase — `contrastFor`, `contrastRatio`, and
+ * any caller that needs to reason about readability all funnel through it.
+ * [LAW:one-source-of-truth]
+ */
+export function relativeLuminance(c) {
     const ch = (v) => {
         const x = v / 255;
         return x <= 0.03928 ? x / 12.92 : Math.pow((x + 0.055) / 1.055, 2.4);
     };
     return 0.2126 * ch(c.red) + 0.7152 * ch(c.green) + 0.0722 * ch(c.blue);
 }
+/**
+ * WCAG 2.x contrast ratio between two colors, in [1, 21]. Symmetric — the
+ * order of arguments does not matter. 4.5 is the AA threshold for normal
+ * text, 3.0 for large text.
+ *
+ * Assumes opaque inputs: alpha is ignored, since the displayed contrast of a
+ * translucent color depends on what it composites over. For a translucent
+ * foreground, flatten it first (or use `ensureContrast`, which does).
+ */
+export function contrastRatio(a, b) {
+    const la = relativeLuminance(a);
+    const lb = relativeLuminance(b);
+    const hi = la > lb ? la : lb;
+    const lo = la > lb ? lb : la;
+    return (hi + 0.05) / (lo + 0.05);
+}
+// Iterations for the lightness bisection below. 20 resolves L to ~1e-6 — far
+// finer than 8-bit quantization or the eye.
+const CONTRAST_ITERS = 20;
+/**
+ * Return a foreground guaranteed to clear `minRatio` against `bg`, keeping the
+ * color *recognizably itself*. If the themed `fg` already passes it is returned
+ * untouched. Otherwise its OKLCH lightness is slid toward the pole that raises
+ * contrast — holding hue, and chroma where it stays in gamut (near the poles
+ * gamut clamping may reduce chroma, but hue is preserved) — until the ratio is
+ * met, so a blue on a dark-blue background becomes a lighter blue, not white.
+ * Only when no lightness of that hue can meet the ratio (a mid-toned
+ * background where even pure black-or-white tops out below the target) does it
+ * fall back to `contrastFor`'s black/white — the true maximum-contrast pick.
+ *
+ * A translucent `fg` is flattened over `bg` first (the displayed color is
+ * `fg` composited over `bg`), so the ratio is measured on what the eye
+ * actually sees and the returned color is opaque. `bg` is treated as the
+ * opaque substrate.
+ *
+ * [LAW:single-enforcer] The one place "is this text readable, and if not fix
+ * it" is decided. Callers route every fg/bg pair through here and the
+ * unreadable state never reaches output. [LAW:dataflow-not-control-flow] the
+ * function always runs; the measured ratio (data) decides how far the
+ * lightness moves — there is no caller-side "should I check contrast" branch.
+ */
+export function ensureContrast(fg, bg, minRatio = 4.5) {
+    // Flatten translucency so the guarantee holds for the displayed color, not
+    // the raw bytes (e.g. a "#FFFFFF60" text-disabled over a light surface).
+    const opaqueFg = fg.compositeOver(bg);
+    if (contrastRatio(opaqueFg, bg) >= minRatio)
+        return opaqueFg;
+    const lab = Oklch.fromRgba(opaqueFg);
+    // The pole that increases contrast: lighten toward white on a dark bg, darken
+    // toward black on a light one. `contrastFor`'s 0.179 cutoff names it.
+    const poleL = relativeLuminance(bg) > 0.179 ? 0 : 1;
+    // If even the pole of this hue can't reach the ratio, the hue physically
+    // can't — return the true maximum-contrast pick (pure black/white from
+    // contrastFor). The gamut-clamped OKLCH pole is only *near* b/w, so
+    // contrastFor is at least as strong and is the honest maximum.
+    const pole = new Oklch(poleL, lab.c, lab.h, lab.alpha).toRgba();
+    if (contrastRatio(pole, bg) < minRatio)
+        return contrastFor(bg);
+    // Bisect for the lightness nearest the original that still clears the ratio:
+    // the smallest perceptual change that achieves accessibility. Contrast is
+    // monotone in L over [lab.l, poleL] (everything below the crossing fails),
+    // so the search is well-posed.
+    let fail = lab.l;
+    let pass = poleL;
+    for (let i = 0; i < CONTRAST_ITERS; i++) {
+        const mid = (fail + pass) / 2;
+        const candidate = new Oklch(mid, lab.c, lab.h, lab.alpha).toRgba();
+        if (contrastRatio(candidate, bg) >= minRatio)
+            pass = mid;
+        else
+            fail = mid;
+    }
+    return new Oklch(pass, lab.c, lab.h, lab.alpha).toRgba();
+}
 //# sourceMappingURL=colorMath.js.map