@promptctl/cc-candybar 1.0.0

package/src/template-engine/cells.ts

@@ -0,0 +1,90 @@
+// [LAW:dataflow-not-control-flow] The fragment walk is unconditional: every
+// fragment is visited; style.link (a value on the fragment) decides whether
+// it becomes its own cell or coalesces with neighbours. No branching on
+// "are there any cells" — variability lives entirely in the data.
+//
+// [LAW:one-type-per-behavior] Cells are RichText. There is no parallel
+// "cell" type with a single-bg invariant: rich-js's joiner protocol asks
+// each item only for its edge style, so the interior can vary freely.
+// What was previously expressed as "split this run into N cells at bg
+// boundaries" or "lift the modal style to cell-level so parts survive a
+// slice" is now structurally impossible to need — RichText carries per-
+// character styling via spans, and every layout op (truncate / align /
+// pad / slice) preserves spans by construction.
+
+import { RichText } from "@promptctl/rich-js";
+import type { Style } from "@promptctl/rich-js";
+
+/**
+ * Convert template-engine fragments (`RichText[]`) into Strip cells
+ * (`RichText[]`), splitting at OSC-8 link boundaries so each clickable
+ * region is its own cell. Non-link runs coalesce into one cell whose
+ * interior styling is carried as spans.
+ *
+ * `baseStyle` is the segment-level default (resolved bg + fg). It becomes
+ * the cell's wrapping style so segment-wide bg+fg cascade across every
+ * character, and per-fragment fg overlays land as spans on top.
+ *
+ * [LAW:single-enforcer] The only mapper from template fragments to Strip
+ * cells. Callers do not assemble cells by hand.
+ */
+export function fragmentsToCells(
+  fragments: RichText[],
+  baseStyle?: Style,
+): RichText[] {
+  const cells: RichText[] = [];
+  let group: RichText[] = [];
+
+  const flush = () => {
+    if (!group.length) return;
+    const cell = buildCell(group, baseStyle);
+    if (cell.plain.length > 0) cells.push(cell);
+    group = [];
+  };
+
+  for (const frag of fragments) {
+    if (frag.style.link) {
+      flush();
+      const cell = buildCell([frag], baseStyle);
+      if (cell.plain.length > 0) cells.push(cell);
+    } else {
+      group.push(frag);
+    }
+  }
+  flush();
+
+  return cells;
+}
+
+function buildCell(fragments: RichText[], baseStyle?: Style): RichText {
+  // [LAW:types-are-the-program] Each fragment carries its own style (and
+  // possibly spans). We merge baseStyle UNDER each fragment's style before
+  // assembling so the segment-wide default flows through every character,
+  // with the fragment's own style winning on overlap. That merged style
+  // then lands as a span on the assembled RichText, so per-fragment styles
+  // are addressable as overlays.
+  const layered =
+    baseStyle !== undefined && !baseStyle.isNull
+      ? fragments.map((f) => withBaseStyle(f, baseStyle))
+      : fragments;
+  const cell = RichText.fromFragments(layered);
+  cell.end = "";
+  cell.noWrap = true;
+  // [LAW:one-source-of-truth] For a single-fragment cell (a link cell, or a
+  // single-styled non-link fragment), the cell's wrapping style IS that
+  // fragment's effective style. This keeps the link / linked-region claim
+  // structurally at cell level (where joiners and click dispatch read it)
+  // and matches the old per-cell-style contract.
+  if (layered.length === 1) {
+    cell.style = layered[0]!.style;
+  } else if (baseStyle !== undefined && !baseStyle.isNull) {
+    cell.style = baseStyle;
+  }
+  return cell;
+}
+
+function withBaseStyle(f: RichText, base: Style): RichText {
+  const copy = f.copy();
+  copy.style = base.add(f.style);
+  return copy;
+}

package/src/template-engine/colors.ts

@@ -0,0 +1,102 @@
+// [LAW:single-enforcer] All per-segment bg/fg resolution flows through
+// resolveSegmentColors. No second path; a second path would silently drift
+// from the two-stage pipeline (bg first, fg with auto-contrast context second).
+//
+// [LAW:dataflow-not-control-flow] Steps execute unconditionally; the option
+// values (undefined template = no spec) are what decides the output, not
+// whether steps run. Absent bg or fg → Style fields are undefined → Style.isNull
+// → fragmentsToStripCells's baseStyle merge is a no-op, cells flow through
+// unchanged.
+
+import { Style, ColorSpec } from "@promptctl/rich-js";
+import type { ColorRgba, PaletteResolver } from "@promptctl/rich-js";
+import type { RichText } from "@promptctl/rich-js";
+import type { Template } from "@promptctl/go-template-js";
+
+export class ColorSpecError extends Error {
+  constructor(spec: string, role: "bg" | "fg") {
+    super(`Invalid ${role} color spec: ${JSON.stringify(spec)}`);
+    this.name = "ColorSpecError";
+  }
+}
+
+/**
+ * Resolve per-segment bg and fg template strings into a Style for baseStyle
+ * injection in fragmentsToStripCells().
+ *
+ * Pipeline:
+ *   1. Evaluate bgTemplate → plain text color-spec string.
+ *   2. resolver.resolve(bgSpec) → ColorRgba.
+ *   3. Evaluate fgTemplate → plain text color-spec string.
+ *   4. resolver.resolve(fgSpec, { against: bgColor }) → ColorRgba (auto-contrast).
+ *   5. Wrap as Style({ bgcolor, color }).
+ *
+ * Undefined template → that color is not set in the returned Style, so cells
+ * fall through to their own style (or no color if they have none).
+ *
+ * Throws ColorSpecError if a non-empty spec string resolves to null.
+ *
+ * Hue rotation is not this function's concern: per-segment hue lives upstream as
+ * WHICH palette `resolver` carries (a transposed palette), so bg and fg resolve
+ * from the same transposed palette and their theme-designed relationship is
+ * preserved. [LAW:dataflow-not-control-flow]
+ *
+ * [LAW:dataflow-not-control-flow] Steps are ordered data transformations, not
+ * guarded branches. The "no spec" case is represented as undefined, which flows
+ * through to produce an absent Style field — not a skipped step.
+ */
+export function resolveSegmentColors(
+  resolver: PaletteResolver,
+  bgTemplate: Template<RichText> | undefined,
+  fgTemplate: Template<RichText> | undefined,
+  scope: object,
+): Style {
+  const bgSpec = evalToPlainText(bgTemplate, scope);
+  const bgColor =
+    bgSpec !== undefined
+      ? resolveSpec(resolver, bgSpec, undefined, "bg")
+      : undefined;
+
+  const fgSpec = evalToPlainText(fgTemplate, scope);
+  const fgColor =
+    fgSpec !== undefined
+      ? resolveSpec(resolver, fgSpec, bgColor, "fg")
+      : undefined;
+
+  return new Style({
+    bgcolor: bgColor !== undefined ? ColorSpec.fromRgba(bgColor) : undefined,
+    color: fgColor !== undefined ? ColorSpec.fromRgba(fgColor) : undefined,
+  });
+}
+
+// Evaluate a template against scope and flatten all fragments to plain text.
+// Returns undefined when no template is configured (no bg/fg override).
+function evalToPlainText(
+  template: Template<RichText> | undefined,
+  scope: object,
+): string | undefined {
+  if (template === undefined) return undefined;
+  return template
+    .evaluate(scope)
+    .map((f) => f.plain)
+    .join("");
+}
+
+// Resolve a color spec string through the palette resolver.
+// Throws ColorSpecError (loud failure) if the spec is unknown or the required
+// `against` context is missing — never silently falls back to a default.
+// [LAW:no-defensive-null-guards] null from resolver.resolve signals broken
+// config; the fix is the config, not a silent fallback.
+function resolveSpec(
+  resolver: PaletteResolver,
+  spec: string,
+  against: ColorRgba | undefined,
+  role: "bg" | "fg",
+): ColorRgba {
+  const color = resolver.resolve(
+    spec.trim(),
+    against !== undefined ? { against } : undefined,
+  );
+  if (color === null) throw new ColorSpecError(spec, role);
+  return color;
+}

package/src/template-engine/engine.ts

@@ -0,0 +1,108 @@
+// [LAW:one-source-of-truth] One Engine instance covers all segment template
+// evaluation. Callers parse their template once (engine.parse(src)) and call
+// template.evaluate(scope) per render — the expensive parse step is not
+// repeated per render cycle.
+//
+// Function registry (closed set for cc-candybar):
+//  • Go builtins (always registered by the engine): printf, print, println,
+//    eq/ne/lt/gt/le/ge, and/or/not, len, index, slice, call.
+//  • sprigDefaults: default, empty, coalesce, ternary, fromJson, toJson.
+//  • sprigStrings: trunc, lower, upper, replace, trim/trimPrefix/trimSuffix,
+//    split/join, contains, hasPrefix, hasSuffix, and more string utils.
+//  • sprigLists: has (membership test: `has "v" $list`).
+//  • sprigMath: add, sub, mul, div, mod, floor, ceil, round, min, max,
+//    seq, until (round here is shadowed by formatterFuncs' Math.round below).
+//  • sprigDatetime(clock): now, date, ago, unixEpoch, dateInZone, dateModify,
+//    toDate, duration — all reading "now" through the injected clock seam.
+//  • sprigConversions: atoi, int, int64, float64, toString, toStrings
+//    (int here is shadowed by ccCandybarFuncs' var-system cast below).
+//  • sprigDicts: dict, get, set, keys, values, pick, omit, hasKey, merge —
+//    `dict` lets a helper take multiple named inputs through its one dot arg.
+//  • richTextFuncs: bold, italic, red, green, … (styling from rich-js).
+//  • paletteFuncs (when resolver provided): primary, accent, palette, paletteOver, auto.
+//  • ccCandybarFuncs: basename, dirname, int, string, bool, urlEncode.
+//  • formatterFuncs: minutesUntilReset (clock-reading numeric primitive),
+//    formatInteger, round, formatModelName, shortenModelName. (The cost/token/
+//    budget AND duration/time-remaining formatters moved to DSL helper templates
+//    — see DEFAULT_DSL_CONFIG.helpers.)
+
+import {
+  createEngine,
+  type Engine,
+  type FuncMap,
+  sprigDefaults,
+  sprigStrings,
+  sprigLists,
+  sprigMath,
+  sprigDatetime,
+  sprigConversions,
+  sprigDicts,
+} from "@promptctl/go-template-js";
+import type { PaletteResolver } from "@promptctl/rich-js";
+import { richTextFuncs, RichText } from "@promptctl/rich-js";
+import { paletteFuncs } from "@promptctl/rich-js/template-bindings";
+import { ccCandybarFuncs, formatterFuncs } from "./funcs.js";
+
+// [LAW:single-enforcer] fromString/toString are declared once here.
+// richTextFuncs() provides style functions (bold, red, link, …).
+// paletteFuncs(resolver) registers semantic palette functions when a theme
+// resolver is provided — same engine instance, no second parse path.
+// [LAW:one-way-deps] `extraFuncs` is an INJECTED FuncMap (e.g. the action +
+// picker feature funcs, built in render/action.ts + render/picker.ts). The
+// generic engine never imports a specific feature — the caller hands it the
+// capability as data, so the dependency runs caller → engine, never engine → feature.
+// [LAW:one-type-per-behavior] resolver?/extraFuncs? are values, not modes —
+// one factory, one engine shape; the data (their presence) governs what's
+// registered.
+// [LAW:single-enforcer] `clock` is the one time source. It feeds sprigDatetime
+// (the funcs that read "now") AND createEngine's clock option, so every
+// time-dependent evaluation in this engine reads from one seam. Defaulted here
+// so the default literal `() => new Date()` lives in exactly one place; callers
+// that omit it (and forwarders passing `undefined`) inherit it unchanged.
+export function createCcCandybarEngine(
+  resolver?: PaletteResolver,
+  extraFuncs?: FuncMap,
+  clock: () => Date = () => new Date(),
+): Engine<RichText> {
+  return createEngine<RichText>({
+    fromString: (s) => new RichText(s),
+    toString: (rt) => rt.plain,
+    clock,
+    // [LAW:no-defensive-null-guards] missing fields must throw at the boundary,
+    // not silently produce "<no value>". Callers (SourceRegistry, segments)
+    // depend on MissingFieldError to drive varDefault / defaultEmptyValue.
+    missingKey: "error",
+    funcs: {
+      ...sprigDefaults(),
+      ...sprigStrings(),
+      ...sprigLists(),
+      ...sprigMath(),
+      // [LAW:single-enforcer] one clock seam: the same source createEngine holds.
+      ...sprigDatetime(clock),
+      ...sprigConversions(),
+      // [LAW:types-are-the-program] `dict` is the substrate primitive a helper
+      // uses to receive more than one input through its single dot arg:
+      // `{{ template "budgetStatus" (dict "cost" .x "budget" .y "warn" .z) }}`.
+      // It makes a multi-input formatter's domain exactly {named scalars},
+      // decoupled from any payload's nesting — no per-payload helper variant.
+      ...sprigDicts(),
+      ...richTextFuncs(),
+      ...(resolver !== undefined ? paletteFuncs(resolver) : {}),
+      // Domain-specific overrides last (wins on collision with sprig aliases).
+      // [LAW:one-source-of-truth] ccCandybarFuncs' `int` is the var-system cast
+      // (toNumber over VarValue); it intentionally shadows sprigConversions' `int`
+      // so a template's `int` keeps one meaning. Position is the override policy.
+      ...ccCandybarFuncs(),
+      // [LAW:one-source-of-truth] formatter funcs delegate to
+      // src/utils/formatters.ts; minutesUntilReset reads the same `clock` seam.
+      // The only sprig collision is `round`: formatterFuncs' Math.round shadows
+      // sprigMath's precision-aware round, registered last so the domain meaning
+      // wins (revisited by the bdi cleanup ticket).
+      ...formatterFuncs(clock),
+      // [LAW:locality-or-seam] Injected feature funcs (the daemon's per-config
+      // engine supplies the `action` + `picker` funcs; resolver-less compile-only
+      // paths do not). Last so a feature can override on collision.
+      ...(extraFuncs ?? {}),
+    },
+  });
+}

package/src/template-engine/funcs.ts

@@ -0,0 +1,216 @@
+// [LAW:one-source-of-truth] Cast semantics live in var-system/types.ts.
+// This module wraps them as FuncMap entries — it does not duplicate logic.
+// [LAW:single-enforcer] The boundary gate (argTypes) lives at the engine
+// dispatch site; the bodies here trust the runtime types they declared.
+
+import { basename as pathBasename, dirname as pathDirname } from "path";
+import type { FuncMap } from "@promptctl/go-template-js";
+import {
+  toNumber,
+  toString,
+  toBool,
+  type VarValue,
+} from "../var-system/types.js";
+import {
+  formatInteger,
+  formatModelName,
+  shortenModelName,
+} from "../utils/formatters.js";
+import { listResolvablePaletteNames, STYLE_ORDER } from "../themes/policy.js";
+
+// [LAW:one-source-of-truth] The DSL `themes()` and `styles()` bindings
+// project the SAME canonical sources the set-state validator consults
+// (listResolvablePaletteNames / STYLE_ORDER). A picker (or a config that
+// `range`s over themes() to emit OSC-8 cells) iterates the allow-list the
+// validator will enforce on the resulting click — the list and the gate cannot
+// diverge because there is no second list.
+//
+// Module-init caching is correct by construction: rich-js THEMES is a
+// static import (no dynamic palette registration at runtime) and
+// STYLE_ORDER is a const array. The "reactivity" requirement from the
+// ticket is satisfied vacuously — the lists never change during a
+// daemon lifetime, so a cached snapshot IS the current truth.
+const THEMES_LIST: readonly string[] = listResolvablePaletteNames();
+const STYLES_LIST: readonly string[] = [...STYLE_ORDER];
+
+// Normalize an engine-supplied numeric argument. The "number" argType admits
+// both number and bigint (per @promptctl/go-template-js); the underlying
+// formatters take a JS number, so collapse bigint here. [LAW:single-enforcer]
+// every formatter wrapper goes through this — no per-wrapper bigint check.
+//
+// [LAW:no-silent-fallbacks] A bigint outside JS's safe-integer range cannot
+// round-trip through Number without silent precision loss (53-bit mantissa)
+// or overflow to ±Infinity. Either would feed a wrong value into a formatter
+// (e.g. formatDuration) and produce confidently-wrong output. Throw at the
+// conversion boundary so the failure surfaces where the conversion happens,
+// not deep inside a formatter doing math on a corrupted number.
+function num(v: number | bigint): number {
+  if (typeof v === "bigint") {
+    if (
+      v > BigInt(Number.MAX_SAFE_INTEGER) ||
+      v < BigInt(Number.MIN_SAFE_INTEGER)
+    ) {
+      throw new TypeError(
+        `Numeric argument ${v}n is outside JS safe-integer range ` +
+          `(|v| > Number.MAX_SAFE_INTEGER = ${Number.MAX_SAFE_INTEGER}); ` +
+          `Number(v) would lose precision or overflow. ` +
+          `Pass a value within ±Number.MAX_SAFE_INTEGER.`,
+      );
+    }
+    return Number(v);
+  }
+  return v;
+}
+
+// cc-candybar-specific functions not already covered by sprig or Go builtins.
+// The engine also includes sprigDefaults(), sprigStrings(), and sprigLists()
+// which cover: default, trunc, lower, upper, replace, trim/trimPrefix/trimSuffix,
+// split/join, contains/hasPrefix/hasSuffix, has.
+// Go builtins cover: printf, eq/ne/lt/gt/le/ge, and/or/not.
+export function ccCandybarFuncs(): FuncMap {
+  return {
+    // Path operations absent from sprig in this package.
+    basename: {
+      fn: (s: string) => pathBasename(s),
+      argTypes: ["string"],
+    },
+    dirname: {
+      fn: (s: string) => pathDirname(s),
+      argTypes: ["string"],
+    },
+
+    // [LAW:single-enforcer] Type casts delegate to var-system/types.ts.
+    // "value" argType: these funcs enforce their own constraints and emit
+    // a useful TypeError on ambiguous input — no need for the engine gate
+    // to pre-filter (it can't describe the partial-cast semantics anyway).
+    int: {
+      fn: (v: VarValue) => toNumber(v),
+      argTypes: ["value"],
+    },
+    string: {
+      fn: (v: VarValue) => toString(v),
+      argTypes: ["value"],
+    },
+    bool: {
+      fn: (v: VarValue) => toBool(v),
+      argTypes: ["value"],
+    },
+
+    // [LAW:single-enforcer] One URL-encoding function for click-verb URL
+    // construction in templates. encodeURIComponent matches the legacy
+    // src/segments/renderer.ts toolbar/tray renderers, so DSL-emitted
+    // cc-candybar://verb/<value> URLs are byte-identical to legacy ones.
+    // [LAW:types-are-the-program] Domain primitive surfaced by chunk-7/8
+    // migration (vhi.3) — the proposal explicitly budgets "may add one or
+    // two filters during migration." This is one of those.
+    urlEncode: {
+      fn: (s: string) => encodeURIComponent(s),
+      argTypes: ["string"],
+    },
+
+    // [LAW:one-source-of-truth] themes() and styles() are zero-arg
+    // projections of the daemon's canonical domain lists. A picker (or a
+    // hand-authored `range`) expresses "options come from list Y" by
+    // iterating these bindings; the same lists feed the set-state
+    // validator's allow-list checks, so the rendered options are exactly
+    // the values the next click will be allowed to write. No second
+    // enumeration in user config.
+    // [LAW:dataflow-not-control-flow] A range loop over a list IS the
+    // option primitive — `{{ range themes }}…{{ end }}` produces one
+    // rendered cell per allowed value. Adding a theme adds a cell;
+    // removing a theme removes a cell; no template branch on "how many
+    // themes are there."
+    themes: {
+      fn: () => THEMES_LIST,
+      argTypes: [],
+    },
+    styles: {
+      fn: () => STYLES_LIST,
+      argTypes: [],
+    },
+  };
+}
+
+// [LAW:one-source-of-truth] Domain value formatters. What remains after the
+// formatting-as-data epic (bdi) are primitives with NO template-native
+// expression — the bdi migration is complete. Do NOT migrate these to DSL
+// helpers; each one is retained for a load-bearing reason:
+//
+//   minutesUntilReset — returns a NUMBER for comparisons and arithmetic
+//     (`le (minutesUntilReset .x) 8`). A template helper writes to output
+//     and cannot return a value, so a helper form would duplicate the formula
+//     across every comparison site [LAW:one-source-of-truth].
+//
+//   formatInteger — locale-aware grouping via toLocaleString(). A regex
+//     helper would be locale-blind (always comma+3), a second divergent
+//     producer [LAW:one-source-of-truth]. The daemon inherits shell LANG/LC_*
+//     from the Rust spawner so grouping honors the user's locale at runtime.
+//
+//   round — Math.round (half-away-from-zero) consumed in `{{ round .pct }}%`
+//     segments. shadows sprigMath's precision-aware round intentionally:
+//     block/weekly/context need integer-rounding, not decimal rounding.
+//
+//   formatModelName / shortenModelName — regex parsing of external model IDs
+//     (named capture groups, version assembly, variant stripping). Trust-
+//     boundary normalization, not display policy. No regex primitive in DSL.
+//
+// The display-formatting families moved to DSL helpers in DEFAULT_DSL_CONFIG:
+// cost/token/budget (bdi.3), duration/time-remaining (bdi.4).
+//
+// [LAW:single-enforcer] minutesUntilReset reads "now" from the injected
+// `clock` — the SAME seam createCcCandybarEngine threads to sprigDatetime
+// (now/unixEpoch) and createEngine. One clock governs every time-dependent
+// evaluation; tests inject a frozen clock for determinism.
+export function formatterFuncs(clock: () => Date = () => new Date()): FuncMap {
+  return {
+    // Epoch-seconds → whole minutes until that instant, clamped at 0 for a past
+    // expiry: round(max(0, epoch*1000 − now)/60000). Consumed by the block/weekly
+    // segments (`formatLongTimeRemaining (minutesUntilReset .resetsAt)`) and the
+    // cacheTimer warmth countdown (numeric `le` thresholds).
+    minutesUntilReset: {
+      fn: (epochSeconds: number | bigint) =>
+        Math.round(
+          Math.max(0, num(epochSeconds) * 1000 - clock().getTime()) / 60000,
+        ),
+      argTypes: ["number"],
+    },
+
+    // ─── Locale-grouped integer (context's "50,000") ──────────────────
+    // [LAW:one-source-of-truth] bdi.5: deliberately RETAINED as a primitive
+    // (not migrated to a DSL helper). toLocaleString reads the host locale the
+    // daemon inherits, so grouping is locale-correct (en_US "50,000" /
+    // de_DE "50.000"). A regex helper would be a second, locale-blind producer
+    // of grouping policy — same parsing/formatting boundary that keeps
+    // formatModelName here.
+    formatInteger: {
+      fn: (n: number | bigint) => formatInteger(num(n)),
+      argTypes: ["number"],
+    },
+
+    // ─── Numeric helper (block/weekly's Math.round of pct) ────────────
+    // [LAW:one-source-of-truth] Math.round is a JS built-in shared between
+    // legacy and DSL — no wrapper indirection makes sense for it. The
+    // formatters.ts module documents domain-meaningful rules; rounding is
+    // not domain-meaningful, so it stays here.
+    round: {
+      fn: (n: number | bigint) => Math.round(num(n)),
+      argTypes: ["number"],
+    },
+
+    // ─── Model-name normalizers (chunk-7 model dsl-pending → dsl-parity) ─
+    // [LAW:one-source-of-truth] formatModelName / shortenModelName are regex-
+    // based normalizers; the DSL function set has no regex primitive, so the
+    // only honest way to express them is to wrap the canonical impls. The
+    // model binding can then move from "echo display_name verbatim" (only
+    // byte-parity for friendly names) to "echo normalized model name" (full
+    // behavioral parity, including raw IDs like "claude-sonnet-4-6").
+    formatModelName: {
+      fn: (raw: string) => formatModelName(raw),
+      argTypes: ["string"],
+    },
+    shortenModelName: {
+      fn: (formatted: string) => shortenModelName(formatted),
+      argTypes: ["string"],
+    },
+  };
+}

package/src/template-engine/index.ts

@@ -0,0 +1,11 @@
+export { createCcCandybarEngine } from "./engine.js";
+export { buildScope } from "./scope.js";
+export { ccCandybarFuncs } from "./funcs.js";
+export { fragmentsToCells } from "./cells.js";
+export { evaluateWhen, applySegmentLayout } from "./layout.js";
+export type {
+  SegmentLayoutOptions,
+  JustifyMode,
+  TruncateMode,
+} from "./layout.js";
+export { resolveSegmentColors, ColorSpecError } from "./colors.js";

package/src/template-engine/layout.ts

@@ -0,0 +1,112 @@
+// [LAW:single-enforcer] All per-segment width/justify/truncate enforcement
+// runs through applySegmentLayout. RichText owns the slice/pad/truncate
+// primitives; this function chooses which to call from the segment-level
+// options. No second path exists.
+//
+// [LAW:dataflow-not-control-flow] Every step is unconditional in shape;
+// option values (width, justify, truncate) decide what the output is, not
+// whether the step runs. "auto" width is not a branch that skips logic —
+// it is a value that selects "collapse only, no resize" over "collapse then
+// size to width".
+//
+// [LAW:types-are-the-program] With RichText as the cell type, every layout
+// operation is span-preserving by construction. There is no rebuild path,
+// no slice-then-restyle dance: `richText.truncate({width, mode, marker})`
+// and `richText.align(justify, width)` clip and shift spans through every
+// cut. The bzh.9 limitation (truncation drops per-part fg) cannot be
+// expressed in this shape — its preconditions don't exist.
+
+import { RichText } from "@promptctl/rich-js";
+import type { Style } from "@promptctl/rich-js";
+import type { Template } from "@promptctl/go-template-js";
+
+export type JustifyMode = "left" | "center" | "right";
+export type TruncateMode = "right" | "left" | "middle";
+
+export interface SegmentLayoutOptions {
+  /** "auto" → content-sized; a positive integer → fixed terminal-cell width. */
+  width: "auto" | number;
+  /** Alignment within a fixed-width segment. Ignored when width is "auto". */
+  justify: JustifyMode;
+  /** Overflow strategy when content exceeds a fixed width. Ignored when "auto". */
+  truncate: TruncateMode;
+  /** Glyph inserted at the overflow cut point. Default "…". */
+  truncateMarker?: string;
+  /**
+   * Style for synthesized whitespace — RichText pads using plain spaces.
+   * The padding inherits the cell's wrapping style at render time, so the
+   * segment bg/fg is continuous across padded gaps without a second style
+   * assignment here.
+   */
+  baseStyle?: Style;
+}
+
+/**
+ * Evaluate a `when` predicate template against `scope`.
+ * Returns false only when the evaluated text equals the string "false".
+ * A missing template means the segment is always visible.
+ *
+ * [LAW:dataflow-not-control-flow] Visibility is a value that flows out of the
+ * template engine. The engine always runs; the output value decides visibility.
+ */
+export function evaluateWhen(
+  template: Template<RichText> | undefined,
+  scope: object,
+): boolean {
+  if (template === undefined) return true;
+  const fragments = template.evaluate(scope);
+  return fragments.map((f) => f.plain).join("") !== "false";
+}
+
+/**
+ * Collapse a visual line's cells into the ONE strip item the unit contributes
+ * for that line. [LAW:single-enforcer] A unit (segment, or an inline leaf) is
+ * one strip item — the powerline joiner caps BETWEEN units, never inside one,
+ * so a unit's interior bg/fg variation is paint, not a structural seam the
+ * joiner reads. Each input cell's wrapping style becomes a span over its range
+ * and its interior spans (including OSC-8 links) carry through, so every
+ * clickable region survives as its own span — serialized as one OSC-8 region
+ * each. `baseStyle` is the wrapping default so synthesized padding and gaps
+ * inherit the unit's bg.
+ */
+function collapseToCell(
+  cells: readonly RichText[],
+  baseStyle?: Style,
+): RichText {
+  const merged = RichText.fromFragments(cells);
+  merged.end = "";
+  merged.noWrap = true;
+  if (baseStyle !== undefined && !baseStyle.isNull) merged.style = baseStyle;
+  return merged;
+}
+
+/**
+ * Lay out one segment visual line: collapse its cells into a single strip
+ * item, then size that item to the requested width. Returns `[]` for an empty
+ * line (a unit that rendered nothing contributes no strip item) or `[cell]`
+ * for one — never more, so the caller's branchless spread handles both.
+ *
+ * [LAW:dataflow-not-control-flow] `width` is the value that selects the sizing
+ * op: "auto" keeps the content-sized cell as-is; a fixed width truncates when
+ * over and pad-aligns when under. Truncation/align are span-preserving, so the
+ * collapsed link structure survives every cut.
+ */
+export function applySegmentLayout(
+  cells: readonly RichText[],
+  options: SegmentLayoutOptions,
+): RichText[] {
+  const { width, justify, truncate, truncateMarker = "…", baseStyle } = options;
+
+  if (cells.length === 0) return [];
+
+  const cell = collapseToCell(cells, baseStyle);
+  if (width === "auto") return [cell];
+
+  if (cell.cellLength > width) {
+    cell.truncate(width, { mode: truncate, marker: truncateMarker });
+  } else if (cell.cellLength < width) {
+    cell.align(justify, width);
+  }
+
+  return [cell];
+}