@promptctl/rich-js 0.6.0 → 0.7.0

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

@@ -1,76 +1,83 @@
 /**
- * Palette / theme / auto-contrast function registrations for the rich-js
- * template binding.
+ * The one palette-dependent template function: `color`.
  *
- * [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.
+ * ### Why exactly one
  *
- * [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.
+ * This module used to register four kinds of thing: one function per
+ * identifier-safe palette variable (`{{ primary child }}`, `{{ accent child }}`,
+ * …), a general `palette "spec" child`, a `paletteOver "spec" "#bg" child` for
+ * specs needing a background, and an `auto "#bg" child` sugar. That surface had
+ * two defects worth recording, because both are easy to reintroduce.
  *
- * ### Surface design rationale
+ * **The name family could not cover its own domain.** A themed palette carries
+ * ~150 variables; roughly 14 of them are legal Go-template identifiers. So the
+ * generated functions reached under a tenth of the palette, and the other nine
+ * tenths needed `palette "text-primary" child` — a *different expression shape*
+ * for the same intent. An author who learned `{{ primary x }}` and reasonably
+ * tried `{{ text_primary x }}` got a FuncNotFound. [LAW:composability] — the
+ * `filterByStatus`/`filterByOwner` shape: names cannot enumerate a domain, and
+ * the N+1 case always needs a form you have to learn separately.
  *
- * Four layers of ergonomics:
+ * **Resolution and application were fused.** Every one of those functions
+ * consumed its color instantly into a styled fragment, so a color could never
+ * be held or passed. Composition therefore had to happen inside the spec
+ * *string* — hence the old `name-darken-N alpha%` grammar. See
+ * `color-funcs.ts` for the full argument; the short version is that a string
+ * grammar is function application with the function calls spelled as
+ * punctuation, and it grows a new production for every operation.
  *
- * 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`.
+ * What replaces all of it: `color "name-or-hex"` produces a color value, the
+ * functions in `color-funcs.ts` transform colors, and `fg`/`bg` in
+ * `style-funcs.ts` paint them. One shape, total over the palette, open to
+ * arbitrary composition. [LAW:one-type-per-behavior]
  *
- * 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.
+ * ### Why a getter, not a palette
  *
- * 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.
+ * `paletteFuncs` takes `() => Palette` rather than a `Palette`. A consumer
+ * whose theme can change at runtime (a live preview, a theme picker, a
+ * status-line that recolors on click) would otherwise be frozen to whichever
+ * palette happened to be current when the engine was constructed — and since
+ * templates are parsed once and evaluated many times, that freeze outlives
+ * every subsequent theme change while the *rest* of the consumer's colors move
+ * on. Two palettes, one render: [LAW:one-source-of-truth] violated by a
+ * captured reference.
  *
- * 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.
+ * The getter costs nothing structurally. `FuncMap` entries are data in the
+ * engine and their bodies run at *evaluate* time, so reading the palette
+ * through a getter leaves parse-once/evaluate-many completely intact. What the
+ * getter must not change is *which functions exist* — and it cannot, because
+ * there is now exactly one, whose name does not depend on the palette's
+ * contents. That was not true of the generated per-variable functions, which
+ * is the second reason they are gone.
  */
 import type { FuncMap } from "@promptctl/go-template-js";
-import { PaletteResolver } from "../themes/paletteResolver.js";
+import type { Palette } from "../themes/palette.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.
+ * Register `color "name-or-hex"` against a live palette.
  *
- * 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`.
+ * `color` resolves a palette variable name to a `#RRGGBB` string, and passes
+ * an already-literal color through unchanged. That second half is not a
+ * convenience — it makes `color` **idempotent**, which is what lets consumers
+ * apply it unconditionally to any author-written color string without first
+ * asking whether it is a name or already a color. [LAW:dataflow-not-control-flow]
+ *
+ * An unknown name throws, carrying near-miss suggestions from the live
+ * palette. In a template that surfaces as an evaluation error at the exact
+ * call site, which is the signal an author (or an agent editing a config) needs
+ * to fix it. [LAW:no-silent-failure]
  *
  * @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)) },
+ *   funcs: {
+ *     ...richTextFuncs(),
+ *     ...colorFuncs(),
+ *     ...paletteFuncs(() => currentTheme.palette),
+ *   },
  * });
  * ```
  */
-export declare function paletteFuncs(resolver: PaletteResolver): FuncMap;
+export declare function paletteFuncs(getPalette: () => Palette): FuncMap;
 //# sourceMappingURL=palette-funcs.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"palette-funcs.d.ts","sourceRoot":"","sources":["../../src/template-bindings/palette-funcs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAgB,MAAM,2BAA2B,CAAC;AACvE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAGpD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,OAAO,GAAG,OAAO,CAO/D"}

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

@@ -1,157 +1,89 @@
 /**
- * Palette / theme / auto-contrast function registrations for the rich-js
- * template binding.
+ * The one palette-dependent template function: `color`.
  *
- * [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.
+ * ### Why exactly one
  *
- * [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.
+ * This module used to register four kinds of thing: one function per
+ * identifier-safe palette variable (`{{ primary child }}`, `{{ accent child }}`,
+ * …), a general `palette "spec" child`, a `paletteOver "spec" "#bg" child` for
+ * specs needing a background, and an `auto "#bg" child` sugar. That surface had
+ * two defects worth recording, because both are easy to reintroduce.
  *
- * ### Surface design rationale
+ * **The name family could not cover its own domain.** A themed palette carries
+ * ~150 variables; roughly 14 of them are legal Go-template identifiers. So the
+ * generated functions reached under a tenth of the palette, and the other nine
+ * tenths needed `palette "text-primary" child` — a *different expression shape*
+ * for the same intent. An author who learned `{{ primary x }}` and reasonably
+ * tried `{{ text_primary x }}` got a FuncNotFound. [LAW:composability] — the
+ * `filterByStatus`/`filterByOwner` shape: names cannot enumerate a domain, and
+ * the N+1 case always needs a form you have to learn separately.
  *
- * Four layers of ergonomics:
+ * **Resolution and application were fused.** Every one of those functions
+ * consumed its color instantly into a styled fragment, so a color could never
+ * be held or passed. Composition therefore had to happen inside the spec
+ * *string* — hence the old `name-darken-N alpha%` grammar. See
+ * `color-funcs.ts` for the full argument; the short version is that a string
+ * grammar is function application with the function calls spelled as
+ * punctuation, and it grows a new production for every operation.
  *
- * 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`.
+ * What replaces all of it: `color "name-or-hex"` produces a color value, the
+ * functions in `color-funcs.ts` transform colors, and `fg`/`bg` in
+ * `style-funcs.ts` paint them. One shape, total over the palette, open to
+ * arbitrary composition. [LAW:one-type-per-behavior]
  *
- * 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.
+ * ### Why a getter, not a palette
  *
- * 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.
+ * `paletteFuncs` takes `() => Palette` rather than a `Palette`. A consumer
+ * whose theme can change at runtime (a live preview, a theme picker, a
+ * status-line that recolors on click) would otherwise be frozen to whichever
+ * palette happened to be current when the engine was constructed — and since
+ * templates are parsed once and evaluated many times, that freeze outlives
+ * every subsequent theme change while the *rest* of the consumer's colors move
+ * on. Two palettes, one render: [LAW:one-source-of-truth] violated by a
+ * captured reference.
  *
- * 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.
+ * The getter costs nothing structurally. `FuncMap` entries are data in the
+ * engine and their bodies run at *evaluate* time, so reading the palette
+ * through a getter leaves parse-once/evaluate-many completely intact. What the
+ * getter must not change is *which functions exist* — and it cannot, because
+ * there is now exactly one, whose name does not depend on the palette's
+ * contents. That was not true of the generated per-variable functions, which
+ * is the second reason they are gone.
  */
-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();
-}
+import { resolveColorRef } from "../themes/colorRef.js";
 /**
- * Resolve `spec` against the resolver (with optional background context) and
- * apply the resulting color as a foreground `Style` on `child`.
+ * Register `color "name-or-hex"` against a live palette.
  *
- * 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.
+ * `color` resolves a palette variable name to a `#RRGGBB` string, and passes
+ * an already-literal color through unchanged. That second half is not a
+ * convenience — it makes `color` **idempotent**, which is what lets consumers
+ * apply it unconditionally to any author-written color string without first
+ * asking whether it is a name or already a color. [LAW:dataflow-not-control-flow]
  *
- * 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`.
+ * An unknown name throws, carrying near-miss suggestions from the live
+ * palette. In a template that surfaces as an evaluation error at the exact
+ * call site, which is the signal an author (or an agent editing a config) needs
+ * to fix it. [LAW:no-silent-failure]
  *
  * @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)) },
+ *   funcs: {
+ *     ...richTextFuncs(),
+ *     ...colorFuncs(),
+ *     ...paletteFuncs(() => currentTheme.palette),
+ *   },
  * });
  * ```
  */
-export function paletteFuncs(resolver) {
-    return {
-        ...semanticNameFuncs(resolver),
-        palette: makePaletteFunc(resolver),
-        paletteOver: makePaletteOverFunc(resolver),
-        auto: makeAutoFunc(resolver),
+export function paletteFuncs(getPalette) {
+    const colorFunc = {
+        fn: ((ref) => resolveColorRef(getPalette(), ref).hex),
+        argTypes: ["string"],
+        returnType: "string",
     };
+    return { color: colorFunc };
 }
 //# sourceMappingURL=palette-funcs.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"palette-funcs.js","sourceRoot":"","sources":["../../src/template-bindings/palette-funcs.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"palette-funcs.js","sourceRoot":"","sources":["../../src/template-bindings/palette-funcs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAIH,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,YAAY,CAAC,UAAyB;IACpD,MAAM,SAAS,GAAiB;QAC9B,EAAE,EAAE,CAAC,CAAC,GAAW,EAAE,EAAE,CAAC,eAAe,CAAC,UAAU,EAAE,EAAE,GAAG,CAAC,CAAC,GAAG,CAAuB;QACnF,QAAQ,EAAE,CAAC,QAAQ,CAAC;QACpB,UAAU,EAAE,QAAQ;KACrB,CAAC;IACF,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;AAC9B,CAAC"}

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

@@ -2,12 +2,11 @@
  * Style-function registrations for the rich-js template binding.
  *
  * [LAW:one-source-of-truth] The function inventory below mirrors the
- * string-syntax style vocabulary documented in `spec/style.md` —
- * foreground colours (named, palette index, hex, RGB), background
- * (`on`), text attributes (positive + negated), and short aliases.
- * Each registration is a templating-time analogue of a piece of
- * `Style.parse`, so a template fragment composed by these functions
- * round-trips through `Style` without semantic drift.
+ * string-syntax style vocabulary documented in `spec/style.md` — the two
+ * colour slots (`fg`/`bg`), text attributes (positive + negated), short
+ * aliases, and the hyperlink. Each registration is a templating-time analogue
+ * of a piece of `Style.parse`, so a template fragment composed by these
+ * functions round-trips through `Style` without semantic drift.
  *
  * [LAW:dataflow-not-control-flow] Every function follows the same
  * shape: child `RichText` in, `RichText` out. The styling difference
@@ -18,13 +17,13 @@
  */
 import type { FuncMap } from "@promptctl/go-template-js";
 /**
- * The full binding registration set populated by the template-bindings
- * style epics — foreground colours (named + generic forms), background
- * (`on`), text attributes (canonical names, short aliases, and `not_*`
- * negations), and the hyperlink cell-splitter (`link`).
+ * Text-styling registrations: the two colour sinks (`fg`, `bg`), text
+ * attributes (canonical names, short aliases, and `not_*` negations), the
+ * hyperlink cell-splitter (`link`), and the multi-attribute `style` spec.
  *
- * Palette/theme/auto-contrast and per-position hue rotation are
- * deliberately absent — they ship in `rich-template-bindings-83q`.
+ * Colours themselves come from elsewhere: `colorFuncs()` for the palette-free
+ * math, `paletteFuncs()` for naming a theme colour. This module only paints.
+ * [LAW:one-way-deps] — nothing here imports a palette.
  */
 export declare function richTextStyleFuncs(): FuncMap;
 //# sourceMappingURL=style-funcs.d.ts.map

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;AAqKvE;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAW5C"}
+{"version":3,"file":"style-funcs.d.ts","sourceRoot":"","sources":["../../src/template-bindings/style-funcs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAgB,MAAM,2BAA2B,CAAC;AA0IvE;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAQ5C"}

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

@@ -2,12 +2,11 @@
  * Style-function registrations for the rich-js template binding.
  *
  * [LAW:one-source-of-truth] The function inventory below mirrors the
- * string-syntax style vocabulary documented in `spec/style.md` —
- * foreground colours (named, palette index, hex, RGB), background
- * (`on`), text attributes (positive + negated), and short aliases.
- * Each registration is a templating-time analogue of a piece of
- * `Style.parse`, so a template fragment composed by these functions
- * round-trips through `Style` without semantic drift.
+ * string-syntax style vocabulary documented in `spec/style.md` — the two
+ * colour slots (`fg`/`bg`), text attributes (positive + negated), short
+ * aliases, and the hyperlink. Each registration is a templating-time analogue
+ * of a piece of `Style.parse`, so a template fragment composed by these
+ * functions round-trips through `Style` without semantic drift.
  *
  * [LAW:dataflow-not-control-flow] Every function follows the same
  * shape: child `RichText` in, `RichText` out. The styling difference
@@ -17,66 +16,44 @@
  * variability; the operation is fixed.
  */
 import { Style, ATTRIBUTE_NAMES, ATTRIBUTE_SHORT_ALIASES, } from "../core/style.js";
-import { ColorSpec, ANSI_COLOR_NAMES } from "../core/color.js";
+import { ColorSpec } from "../core/color.js";
 import { applyStyleToFragment } from "./helpers.js";
-function fgFunc(style) {
+function attrFunc(style) {
     return {
         fn: ((child) => applyStyleToFragment(child, style)),
         argTypes: ["liftable"],
         returnType: "T",
     };
 }
-// --- Foreground colours: named ---
-function namedColorFuncs() {
-    const out = {};
-    for (const name of Object.keys(ANSI_COLOR_NAMES)) {
-        const colorSpec = ColorSpec.parse(name);
-        out[name] = fgFunc(new Style({ color: colorSpec }));
-    }
-    return out;
+// --- Colour sinks ---
+//
+// `fg` and `bg` are the only two colour-applying functions, and they are the
+// terminal step of the colour pipeline: `color` names a colour, the functions
+// in `color-funcs.ts` transform it, these paint it onto text.
+//
+// [LAW:composability] They replace five separate families — one function per
+// ANSI colour name (`red`, `bright_blue`, …), `hex`, `rgb`, `color` (256-index),
+// and `on` (background). Every one of those encoded *which colour* in the
+// function's identity, so the vocabulary could only grow by adding names, and
+// a colour computed at render time could not be applied at all. Here the colour
+// is an argument, so the sink admits every colour that exists and every colour
+// that will ever exist. Two functions, unbounded reach.
+//
+// [LAW:types-are-the-program] The slot accepts the full `ColorSpec.parse`
+// vocabulary, which is wider than the hex the colour math produces — and that
+// width is deliberate, not laxity. `#7aa2f7` is a *concrete* colour; `"red"`
+// and `"color(42)"` are *symbolic* ones the terminal resolves against its own
+// theme. Only concrete colours can be darkened or blended, which is why the
+// colour-math functions take hex alone; but both kinds can be painted, so the
+// sink takes the union. The type of each slot is exactly the set of values that
+// slot can mean something for.
+function colorSinkFunc(slot) {
+    return {
+        fn: ((spec, child) => applyStyleToFragment(child, new Style({ [slot]: ColorSpec.parse(spec) }))),
+        argTypes: ["string", "liftable"],
+        returnType: "T",
+    };
 }
-// --- Foreground colours: generic forms ---
-const colorPaletteFunc = {
-    fn: ((index, child) => {
-        if (!Number.isInteger(index) || index < 0 || index > 255) {
-            throw new RangeError(`color index ${index} is out of range (0-255)`);
-        }
-        return applyStyleToFragment(child, new Style({ color: ColorSpec.fromAnsi(index) }));
-    }),
-    argTypes: ["int", "liftable"],
-    returnType: "T",
-};
-// [LAW:types-are-the-program] `hex` advertises a narrower domain than the
-// general colour-spec parser — only `#RRGGBB` / `#RRGGBBAA` is admitted.
-// Without this gate, `ColorSpec.parse` would silently accept any colour-spec
-// string (named colours, `rgb(...)`, `color(N)`), letting `hex "red"` succeed
-// and masking author mistakes.
-const HEX_INPUT_RE = /^#[0-9a-fA-F]{6}([0-9a-fA-F]{2})?$/;
-const colorHexFunc = {
-    fn: ((hex, child) => {
-        if (!HEX_INPUT_RE.test(hex)) {
-            throw new RangeError(`hex expected #RRGGBB or #RRGGBBAA, got ${JSON.stringify(hex)}`);
-        }
-        return applyStyleToFragment(child, new Style({ color: ColorSpec.parse(hex) }));
-    }),
-    argTypes: ["string", "liftable"],
-    returnType: "T",
-};
-const colorRgbFunc = {
-    fn: ((r, g, b, child) => {
-        return applyStyleToFragment(child, new Style({ color: ColorSpec.fromRgb(r, g, b) }));
-    }),
-    argTypes: ["int", "int", "int", "liftable"],
-    returnType: "T",
-};
-// --- Background ---
-const onFunc = {
-    fn: ((spec, child) => {
-        return applyStyleToFragment(child, new Style({ bgcolor: ColorSpec.parse(spec) }));
-    }),
-    argTypes: ["string", "liftable"],
-    returnType: "T",
-};
 // --- Text attributes ---
 //
 // [LAW:one-source-of-truth] The attribute and short-alias inventories
@@ -89,11 +66,11 @@ function attrStyle(name, value) {
 function attributeFuncs() {
     const out = {};
     for (const name of ATTRIBUTE_NAMES) {
-        out[name] = fgFunc(attrStyle(name, true));
-        out[`not_${name}`] = fgFunc(attrStyle(name, false));
+        out[name] = attrFunc(attrStyle(name, true));
+        out[`not_${name}`] = attrFunc(attrStyle(name, false));
     }
     for (const [alias, canonical] of Object.entries(ATTRIBUTE_SHORT_ALIASES)) {
-        out[alias] = fgFunc(attrStyle(canonical, true));
+        out[alias] = attrFunc(attrStyle(canonical, true));
     }
     return out;
 }
@@ -105,7 +82,7 @@ function attributeFuncs() {
 // 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`, …)
+// Motivation: the per-attribute functions (`bold`, `underline`, `fg`, …)
 // 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`
@@ -138,7 +115,7 @@ const styleSpecFunc = {
 //
 // The cell-boundary signal that consumers (cc-candybar et al.) walk is
 // `fragment.style.link` being truthy. `Style.add` propagates `link`
-// through any outer wrapping call, so `{{ red (link "u" "x") }}` and
+// through any outer wrapping call, so `{{ fg "red" (link "u" "x") }}` and
 // `{{ link "u" "x" }}` produce shapes that both qualify as cells from
 // the consumer's perspective. Outer-wins on nested links comes for free
 // from `Style.add`'s right-wins-on-conflict rule.
@@ -155,21 +132,18 @@ const linkFunc = {
 };
 // --- Public assembly ---
 /**
- * The full binding registration set populated by the template-bindings
- * style epics — foreground colours (named + generic forms), background
- * (`on`), text attributes (canonical names, short aliases, and `not_*`
- * negations), and the hyperlink cell-splitter (`link`).
+ * Text-styling registrations: the two colour sinks (`fg`, `bg`), text
+ * attributes (canonical names, short aliases, and `not_*` negations), the
+ * hyperlink cell-splitter (`link`), and the multi-attribute `style` spec.
  *
- * Palette/theme/auto-contrast and per-position hue rotation are
- * deliberately absent — they ship in `rich-template-bindings-83q`.
+ * Colours themselves come from elsewhere: `colorFuncs()` for the palette-free
+ * math, `paletteFuncs()` for naming a theme colour. This module only paints.
+ * [LAW:one-way-deps] — nothing here imports a palette.
  */
 export function richTextStyleFuncs() {
     return {
-        ...namedColorFuncs(),
-        color: colorPaletteFunc,
-        hex: colorHexFunc,
-        rgb: colorRgbFunc,
-        on: onFunc,
+        fg: colorSinkFunc("color"),
+        bg: colorSinkFunc("bgcolor"),
         ...attributeFuncs(),
         link: linkFunc,
         style: styleSpecFunc,