@promptctl/cc-candybar 1.26.0 → 1.27.0

package/src/dsl/render.ts

@@ -11,7 +11,7 @@
 // the input values (kind discriminators, layout length, palette presence)
 // govern output, not whether operations run.
 
-import type { RichText, PaletteResolver, ThemeKey } from "@promptctl/rich-js";
+import type { RichText, Palette, ThemeKey } from "@promptctl/rich-js";
 import { ColorSpec, Style, lighten, IDENTITY } from "@promptctl/rich-js";
 import type { Engine, Template } from "@promptctl/go-template-js";
 import type {
@@ -21,6 +21,8 @@ import type {
   LayoutNode,
 } from "../config/dsl-types.js";
 import { HUE_STEP_VAR } from "../config/dsl-types.js";
+import { perConfigDomainsFor } from "../config/option-domain.js";
+import { PRESET_FLOOR, presetNames, presetRoot } from "../config/presets.js";
 import type { VariableStore } from "../var-system/store.js";
 import type { SourceRegistry } from "../var-system/sources.js";
 import {
@@ -30,11 +32,12 @@ import {
 } from "../var-system/sources.js";
 import type { BuildLineOptions } from "../render/strip.js";
 import { DEFAULT_PADDING, renderStripCells } from "../render/strip.js";
-import { resolverForThemeName } from "../themes/index.js";
+import { paletteForThemeName } from "../themes/index.js";
 import { buildScope } from "../template-engine/scope.js";
 import {
   createCcCandybarEngine,
   evaluateWhen,
+  resolveSegmentColors,
 } from "../template-engine/index.js";
 import {
   compileActions,
@@ -47,6 +50,11 @@ import {
   collectMenuDrops,
   type MenuRuntime,
 } from "../render/menu.js";
+import {
+  createActiveSegmentRef,
+  type ActiveSegmentRef,
+} from "../render/active-segment.js";
+import { segmentColorFuncs } from "../render/segment-color.js";
 // [LAW:one-way-deps] The node-type registry sits below this driver: it owns the
 // compiled node shapes + each kind's compile/render, dispatched via nodeType().
 // render.ts threads the recursion (compileChild/renderChild) + the hue counter in
@@ -71,14 +79,27 @@ import {
 // owns node behavior); this driver only assembles + walks them.
 export interface CompiledConfig {
   readonly segments: CompiledSegments;
-  readonly root: CompiledNode;
-  // [LAW:locality-or-seam] The menu runtime the engine's `menu` func closes over,
-  // surfaced here so renderDsl can publish each segment's placement into it before
-  // that segment's template evaluates. One instance per compiled config; its
-  // `current` is mutated synchronously within a single renderDsl walk (renders are
-  // sequential + synchronous, so no cross-render leak) — the spatial cousin of the
-  // hue cursor, one owner. [LAW:no-ambient-temporal-coupling]
+  // [LAW:dataflow-not-control-flow] EVERY preset's layout, compiled up front and
+  // keyed by preset name — the render selects one by name rather than compiling
+  // per session. This is the same move `looks` makes one level down (every
+  // look's ThemeKey is resolved at load; the render picks one), and it is what
+  // lets a per-SESSION preset pick ride a per-ENTRY compilation: one RenderCache
+  // entry serves many sessions, so nothing session-shaped may be compiled here.
+  // Total over `presetNames` — every selectable name, floor included — so the
+  // lookup needs no absent case. A preset declaring no `root` of its own maps
+  // to the config's own compiled root: the identity element, not a special
+  // case.
+  readonly roots: ReadonlyMap<string, CompiledNode>;
+  // [LAW:locality-or-seam] The menu runtime the engine's `menu` func closes over.
   readonly menuRuntime: MenuRuntime;
+  // [LAW:one-source-of-truth] The single "which segment is rendering" record
+  // every segment-scoped template function reads — the menu's identity, the
+  // `color` func's palette, the `bgOf` func's background. Surfaced here so the
+  // walk can publish into it. One instance per compiled config; mutated
+  // synchronously within a single renderDsl walk (renders are sequential +
+  // synchronous, so no cross-render leak) — the spatial cousin of the hue
+  // cursor, one owner. [LAW:no-ambient-temporal-coupling]
+  readonly activeSegment: ActiveSegmentRef;
   // [LAW:types-are-the-program] Variable declaration failures that did NOT
   // prevent the config from loading (type mismatches, bad defaults). The
   // affected variables are absent from the store; segments that reference them
@@ -296,31 +317,56 @@ export function registerDslConfig(
   // [LAW:single-enforcer] Forward the caller's clock (the daemon's `() => new
   // Date()`, a test's frozen clock) to the one engine. Omitted ⇒ undefined ⇒
   // createCcCandybarEngine applies its single default; no second default literal.
+  // [LAW:one-source-of-truth] ONE record for "which segment is rendering", read
+  // by every segment-scoped template function: `{{ menu }}` takes its identity
+  // from the name, `{{ color }}` its palette, `{{ bgOf }}` its background. A
+  // per-feature pointer would let two features disagree about which segment is
+  // current. Built before the engine so the funcs can close over it; `current`
+  // stays null until a render walk publishes one.
+  const activeSegment = createActiveSegmentRef();
   // [LAW:locality-or-seam] The menu runtime shares the action runtime (a menu's
-  // glyph + body resolve from the same compiled table + store) and carries the
-  // walk-published current placement. Built before the engine so the `menu` func
-  // can close over it; `current` stays null until a render walk publishes one.
+  // glyph + body resolve from the same compiled table + store) and reads the
+  // active segment through the shared record above.
   const menuRuntime: MenuRuntime = {
     action: actionRuntime,
-    current: null,
+    activeSegment,
   };
   // [LAW:one-source-of-truth] The config's look names — the one PER-CONFIG
-  // option domain. Computed once here and fed to BOTH consumers (the compiled
-  // set-option domains below and the `looks()` binding), so the rendered
-  // options, a hand-authored `range looks`, and the derived click gate (which
-  // reads the same config in deriveActionValidators) trace to one map.
+  // option domain. Fed to every consumer (the `looks()` binding below, and —
+  // via perConfigDomainsFor, the SAME construction cross-ref.ts and
+  // state-validators.ts use — the compiled set-option domains), so the
+  // rendered options, a hand-authored `range looks`, and the derived click
+  // gate (which reads the same config in deriveActionValidators) trace to
+  // one source.
   const lookNames = Object.keys(config.looks);
+  const presetOptions = presetNames(config.presets);
+  const perConfigDomains = perConfigDomainsFor(config);
   const engine = createCcCandybarEngine(
-    undefined,
     {
       ...actionFuncs(actionRuntime),
       ...pickerFuncs(actionRuntime),
       ...menuFuncs(menuRuntime),
+      // [LAW:one-source-of-truth] `{{ color }}` reads the palette of the
+      // segment currently rendering — the same palette its `bg:`/`fg:` resolve
+      // from, published by the walk. Binding it to a palette captured HERE
+      // (registration runs once per config load, renders happen per tick) was
+      // the two-clocks bug this seam exists to close: a session theme click, a
+      // look, or a per-segment hue rotation moved a segment's background while
+      // every in-body color stayed where it was, so one segment painted from
+      // two palettes at once. Reading live costs nothing structurally — FuncMap
+      // bodies run at evaluate time, so parse-once/evaluate-many is untouched.
+      // `{{ bgOf }}` rides the same record. [LAW:rich-js-owns-color-math]
+      ...segmentColorFuncs(activeSegment),
       // [LAW:one-type-per-behavior] The per-config sibling of the static
       // themes()/styles() bindings (template-engine/funcs.ts): zero-arg
       // projection of the "looks" option domain. Injected here — not in the
       // static FuncMap — because the domain is this config's looks block.
       looks: { fn: () => lookNames, argTypes: [] },
+      // The presets domain's twin of the binding above — same per-config
+      // reason, same shape. A hand-authored `range presets` and a
+      // `{{ menu "applyPreset" }}` therefore enumerate the same names the
+      // derived click gate admits.
+      presets: { fn: () => presetOptions, argTypes: [] },
     },
     opts?.clock,
   );
@@ -363,7 +409,7 @@ export function registerDslConfig(
     parse,
     config.actions,
     stateKeyToVar,
-    lookNames,
+    perConfigDomains,
   );
 
   // [LAW:dataflow-not-control-flow] One variable failing to declare does not
@@ -427,9 +473,9 @@ export function registerDslConfig(
       // per-render basePalette; folding globals.palette in here too would freeze
       // it per segment and the stale copy would shadow basePalette, so a session
       // theme change could never recolor the bar.
-      paletteResolver:
+      palette:
         seg.palette !== undefined
-          ? resolverForThemeName(seg.palette)
+          ? paletteForThemeName(seg.palette)
           : undefined,
     };
   }
@@ -463,9 +509,25 @@ export function registerDslConfig(
     return nodeType(node.kind).compile(node, cctx);
   };
 
+  // [LAW:one-source-of-truth] One compiled tree per declared preset, built
+  // through the SAME compileNode the config's own root goes through —
+  // `presetRoot` resolves the fragment's `root` or falls back to the config's,
+  // so the floor preset (the empty fragment) needs no arm and no absent case
+  // downstream.
+  // Keyed by the SAME domain the menu renders and the click gate admits, so
+  // every selectable name has a compiled tree [LAW:one-source-of-truth].
+  const roots = new Map<string, CompiledNode>();
+  for (const name of presetOptions) {
+    // The path travels WITH the tree, so a preset that stages the config's own
+    // root diagnoses under `root` — the place its author actually wrote it.
+    const { node, path } = presetRoot(config, name);
+    roots.set(name, compileNode(node, path));
+  }
+
   return {
     segments: compiled,
-    root: compileNode(config.root, "root"),
+    roots,
+    activeSegment,
     menuRuntime,
     loadWarnings,
   };
@@ -545,24 +607,44 @@ export interface RenderObservers {
   readonly onSegmentError?: (segName: string, message: string) => void;
 }
 
+// [LAW:locality-or-seam] The per-render RESOLUTION the caller performs and hands
+// down — the values that are neither config (compiled once) nor payload (input
+// data), but the session's live choices resolved against the config: which
+// theme-adaptation, which preset. Bundled as ONE named bag for exactly the
+// reason RenderObservers is: `look` arrived as a positional tail, `preset` would
+// have been a second one, and the next resolution a third — each a signature
+// every caller re-counts. A new per-render choice is now one field here.
+//
+// Both fields default to their domain's own identity element, so an omitting
+// caller (a compile-only test, the demo) renders the unadapted config — a true
+// default, not a fallback [LAW:no-silent-failure].
+export interface RenderSelection {
+  // The resolved look, as a ThemeKey: effectiveLookName over SessionState/
+  // globals, then lookKeyByName — resolved by the caller exactly how basePalette
+  // is. IDENTITY is the "none" look. Composed with each segment's hue shift into
+  // ONE transposition.
+  readonly look?: ThemeKey;
+  // The resolved preset NAME: effectivePresetName over SessionState/globals,
+  // collapsed to the floor if stale. Selects which of `compiled.roots` this
+  // render walks. The name (not the fragment) crosses this seam because the
+  // fragment's two halves land in two different places — the root here, the
+  // globals in `opts`/the payload — and one name keeps them from disagreeing.
+  readonly preset?: string;
+}
+
 export function renderDsl(
   config: ValidatedConfig,
   compiled: CompiledConfig,
   store: VariableStore,
   registry: SourceRegistry,
   payload: unknown,
-  basePalette: PaletteResolver,
+  basePalette: Palette,
   opts: BuildLineOptions,
   observers?: RenderObservers,
-  // [LAW:dataflow-not-control-flow] The render's look (the session's chosen
-  // theme-adaptation), resolved per render by the caller — effectiveLookName
-  // over SessionState/globals, then lookKeyByName — exactly how basePalette
-  // resolves. IDENTITY is the domain's own no-adaptation element (the "none"
-  // look), so an omitting caller renders unadapted — a true default, not a
-  // fallback. Composed with each segment's hue shift into ONE transposition.
-  look: ThemeKey = IDENTITY,
+  selection?: RenderSelection,
 ): string {
   const { perSegmentSink, onSegmentError } = observers ?? {};
+  const { look = IDENTITY, preset = PRESET_FLOOR } = selection ?? {};
   // [LAW:one-source-of-truth] Inject the usable width as `term.cols` from the
   // SAME opts.width the strip wraps to (below), so a width-paginated widget reads
   // the exact wrap width — never a cached or independently-measured copy. This is
@@ -626,19 +708,34 @@ export function renderDsl(
       : undefined;
   };
 
-  // [LAW:single-enforcer] The menu seam, owned here. `beginSegment` publishes the
-  // segment name a `{{ menu }}` needs to derive its identity; `collectDrops` reads
-  // the open bodies the menus carried as metadata on their evaluated fragments and
-  // clears the published placement. The runtime's `current` is set/cleared around
-  // each segment eval by the walk only — never ambient.
-  // [LAW:no-ambient-temporal-coupling]
-  const beginSegment = (segName: string): void => {
-    compiled.menuRuntime.current = { segName };
-  };
-  const collectDrops = (
-    fragments: readonly RichText[],
-  ): readonly RichText[] => {
-    compiled.menuRuntime.current = null;
+  // [LAW:single-enforcer] The segment seam, owned here as a symmetric pair.
+  // `enterSegment` establishes everything a segment's templates may ask about
+  // themselves — the name `{{ menu }}` derives its identity from, the palette
+  // `{{ color }}` resolves against, the background `{{ bgOf }}` returns — and
+  // returns the resolved base Style. `exitSegment` collects the menu bodies the
+  // fragments carried as metadata and tears the record back down.
+  //
+  // [LAW:no-ambient-temporal-coupling] The record is set and cleared around each
+  // segment's evaluation by the walk ONLY, so "which segment am I in" is owned
+  // state with one writer, never ambient context a reader has to hope is
+  // current. Enter/exit are a pair by construction: every path that publishes
+  // goes through the first, every path that finishes goes through the second.
+  const enterSegment = (
+    segName: string,
+    palette: Palette,
+    bgTemplate: Template<RichText> | undefined,
+    fgTemplate: Template<RichText> | undefined,
+  ): Style =>
+    resolveSegmentColors(
+      compiled.activeSegment,
+      segName,
+      palette,
+      bgTemplate,
+      fgTemplate,
+      scope,
+    );
+  const exitSegment = (fragments: readonly RichText[]): readonly RichText[] => {
+    compiled.activeSegment.current = null;
     return collectMenuDrops(fragments);
   };
 
@@ -662,8 +759,8 @@ export function renderDsl(
       nextHueShift,
       perSegmentSink,
       onSegmentError,
-      beginSegment,
-      collectDrops,
+      enterSegment,
+      exitSegment,
       focusTint,
       lookupSegment,
       renderChild: renderNode,
@@ -676,7 +773,22 @@ export function renderDsl(
   // emit a "\n"-bearing string (FlexStrip width-overflow wrap); joining the per-
   // line results with "\n" splices those in place — byte-identical to serializing
   // each leaf row independently, since the cells and their order are unchanged.
-  return renderNode(compiled.root, true)
+  // [LAW:no-defensive-null-guards] The active preset's compiled tree. By the
+  // time a name reaches here it must be a member: effectivePresetName collapses
+  // unknown names to the floor, and every merged config declares the floor — so
+  // the throw is the loud failure for a broken invariant (a hand-built config
+  // missing the bundled presets block), never a silent fall back to some other
+  // arrangement than the one the bar's own label claims is active.
+  const root = compiled.roots.get(preset);
+  if (root === undefined) {
+    throw new Error(
+      `Preset "${preset}" has no compiled layout — registerDslConfig compiles ` +
+        `one per declared preset and effectivePresetName collapses unknown ` +
+        `names to "${PRESET_FLOOR}"; a miss here is merge/policy drift ` +
+        `(have: ${[...compiled.roots.keys()].join(", ")})`,
+    );
+  }
+  return renderNode(root, true)
     .map((line) => renderStripCells(line, opts))
     .join("\n");
 }

package/src/help-text.ts

@@ -23,9 +23,9 @@ Configuration:
   to point at a specific file. See the default config for all available options:
     node dist/index.mjs debug --project-dir . --cwd .
 
-  The bundled default bar ships a clickable theme/look picker — no config
-  needed. Click 🎨 <theme> ${DISCLOSURE_GLYPH_CLOSED} or ◐ <look> ${DISCLOSURE_GLYPH_CLOSED} on the bar to
-  switch palettes.
+  The bundled default bar ships a settings drawer — no config needed. Click
+  ⚙ settings ${DISCLOSURE_GLYPH_CLOSED} on the bar to reveal a clickable theme/look picker and
+  other display options.
 
 Subcommands:
   install                  One-shot setup: stages the runtime (native render

package/src/install/index.ts

@@ -451,8 +451,8 @@ function installSuccessMessage(): string {
   return (
     `✓ install complete.\n` +
     `  Restart Claude Code to pick up the new statusline.\n` +
-    `  Tip: the default bar has a clickable theme/look picker — click\n` +
-    `  🎨 <theme> ${DISCLOSURE_GLYPH_CLOSED} or ◐ <look> ${DISCLOSURE_GLYPH_CLOSED} on the bar to switch palettes.\n`
+    `  Tip: the default bar has a settings drawer — click ⚙ settings\n` +
+    `  ${DISCLOSURE_GLYPH_CLOSED} to reveal a clickable theme/look picker and other display options.\n`
   );
 }
 

package/src/render/action.ts

@@ -25,17 +25,17 @@ import type { FuncMap, Template } from "@promptctl/go-template-js";
 import type { VariableStore } from "../var-system/store.js";
 import { toString as varToString } from "../var-system/types.js";
 import { buildScope } from "../template-engine/scope.js";
-import type { ActionDecl, OptionSource } from "../config/action.js";
-import {
-  listResolvablePaletteNames,
-  STRIP_STYLES,
-  type StripStyle,
-} from "../themes/policy.js";
+import type { ActionDecl } from "../config/action.js";
+import { resolveOptionDomain } from "../config/option-domain.js";
+import type { StripStyle } from "../themes/policy.js";
 import {
   effectsUrl,
   VERB_COPY,
   VERB_OPEN_VSCODE,
+  VERB_RESET_CONFIG,
+  VERB_SET_CONFIG,
   VERB_SET_STATE,
+  VERB_STEP_CONFIG,
   VERB_STEP_STATE,
   type Effect,
 } from "../click/wire.js";
@@ -102,24 +102,65 @@ export type CompiledActionDecl =
       readonly members: readonly string[];
     }
   | { readonly kind: "copy"; readonly text: Template<RichText> }
-  | { readonly kind: "open"; readonly target: Template<RichText> };
+  | { readonly kind: "open"; readonly target: Template<RichText> }
+  // [LAW:one-source-of-truth] `persist`'s twin of the set-* kinds above,
+  // MINUS set-int (a page cursor is never persisted — see action.ts). Carries
+  // the SAME shapes for the SAME reason: a persistent write is gated and
+  // realized exactly like a session write, only the wire verb (VERB_SET_CONFIG/
+  // VERB_STEP_CONFIG) and the write's durability differ.
+  | {
+      readonly kind: "persist-literal";
+      readonly key: string;
+      readonly value: string;
+      readonly stateVar: string;
+    }
+  | {
+      readonly kind: "persist-option";
+      readonly key: string;
+      readonly stateVar: string;
+      readonly options: readonly string[];
+    }
+  | {
+      readonly kind: "persist-bounded";
+      readonly key: string;
+      readonly by: number;
+    }
+  | {
+      readonly kind: "persist-cycle";
+      readonly key: string;
+      readonly stateVar: string;
+      readonly members: readonly string[];
+    }
+  // [LAW:one-source-of-truth] The gated undo for a persistent write: clears
+  // one config-overrides key. Carries only the key — there is no value to
+  // realize, so it shares copy/open's "no gate" shape at compile time (the
+  // GATE is the key-membership check the reset-config verb handler applies).
+  | { readonly kind: "reset"; readonly key: string };
 
 export type CompiledActions = ReadonlyMap<string, CompiledActionDecl>;
 
-// [LAW:one-source-of-truth] An option source resolves to the SAME canonical list
-// the `themes()`/`styles()`/`looks()` bindings and the derived gate consult —
-// rendered options and the gate cannot diverge. The render-side resolver (the
-// daemon's validator-derivation has its own that must agree — themes/styles from
-// themes/policy, looks from the config's merged look names, threaded in as data
-// because that one domain is per-config, not registry-static).
-export function optionDomain(
-  src: OptionSource,
-  lookNames: readonly string[],
-): readonly string[] {
-  if (src === "themes") return listResolvablePaletteNames();
-  if (src === "styles") return STRIP_STYLES;
-  return lookNames;
-}
+// [LAW:one-source-of-truth] Globals fields whose CURRENT resolved value is
+// exposed to templates under a different var name than the field itself (the
+// daemon publishes this resolution once per render — e.g. `theme.effective`
+// for `palette`, src/daemon/render-payload.ts). A `persist` action with no
+// entry here reads back through its own key name as an input var (mirrors
+// compileActions' stateKeyToVar fallback), so every persistable globals field
+// needs an entry unless its `.effective` projection happens to be named
+// exactly the bare field (none are — every projection carries the
+// `.effective` suffix). Every field with a projection is listed
+// (candybar-config-engine-71o.3 added style/charset/colorCompatibility/
+// autoWrap/padding to palette/look's original two); a field with no entry
+// here still writes correctly on `persist` — only its "current selection"
+// highlight is inert (readVar falls back to "" since no such var exists).
+const CONFIG_KEY_TO_EFFECTIVE_VAR: ReadonlyMap<string, string> = new Map([
+  ["palette", "theme.effective"],
+  ["look", "look.effective"],
+  ["style", "style.effective"],
+  ["charset", "charset.effective"],
+  ["colorCompatibility", "colorCompatibility.effective"],
+  ["autoWrap", "autoWrap.effective"],
+  ["padding", "padding.effective"],
+]);
 
 // [LAW:locality-or-seam] The runtime holder the `action` template function closes
 // over. Populated after the engine is constructed (the func references the
@@ -165,13 +206,17 @@ export function compileActions(
   parse: (src: string) => Template<RichText>,
   actions: Readonly<Record<string, ActionDecl>>,
   stateKeyToVar: ReadonlyMap<string, string>,
-  // The config's look names — the one per-config option domain optionDomain
-  // resolves from (themes/styles stay registry-static).
-  lookNames: readonly string[],
+  // This config's per-config option domains (currently just "looks" — the
+  // config's merged look names) — resolveOptionDomain checks these before
+  // falling back to the global registry (themes/styles).
+  perConfigDomains: ReadonlyMap<string, readonly string[]>,
 ): CompiledActions {
   const out = new Map<string, CompiledActionDecl>();
   for (const [name, action] of Object.entries(actions)) {
-    out.set(name, compileAction(parse, name, action, stateKeyToVar, lookNames));
+    out.set(
+      name,
+      compileAction(parse, name, action, stateKeyToVar, perConfigDomains),
+    );
   }
   return out;
 }
@@ -185,7 +230,7 @@ function compileAction(
   name: string,
   action: ActionDecl,
   stateKeyToVar: ReadonlyMap<string, string>,
-  lookNames: readonly string[],
+  perConfigDomains: ReadonlyMap<string, readonly string[]>,
 ): CompiledActionDecl {
   if ("set" in action) {
     const stateVar = stateKeyToVar.get(action.set) ?? action.set;
@@ -202,7 +247,7 @@ function compileAction(
         kind: "set-option",
         key: action.set,
         stateVar,
-        options: [...optionDomain(action.from, lookNames)],
+        options: [...resolveOptionDomain(action.from, perConfigDomains)],
       };
     }
     if ("int" in action) {
@@ -222,16 +267,52 @@ function compileAction(
       by: action.by,
     };
   }
+  if ("persist" in action) {
+    const stateVar =
+      CONFIG_KEY_TO_EFFECTIVE_VAR.get(action.persist) ?? action.persist;
+    if ("to" in action) {
+      return {
+        kind: "persist-literal",
+        key: action.persist,
+        value: action.to,
+        stateVar,
+      };
+    }
+    if ("from" in action) {
+      return {
+        kind: "persist-option",
+        key: action.persist,
+        stateVar,
+        options: [...resolveOptionDomain(action.from, perConfigDomains)],
+      };
+    }
+    if ("cycle" in action) {
+      return {
+        kind: "persist-cycle",
+        key: action.persist,
+        stateVar,
+        members: action.cycle,
+      };
+    }
+    return {
+      kind: "persist-bounded",
+      key: action.persist,
+      by: action.by,
+    };
+  }
   if ("copy" in action) {
     return {
       kind: "copy",
       text: parseActionTemplate(parse, action.copy, name),
     };
   }
-  return {
-    kind: "open",
-    target: parseActionTemplate(parse, action.open, name),
-  };
+  if ("open" in action) {
+    return {
+      kind: "open",
+      target: parseActionTemplate(parse, action.open, name),
+    };
+  }
+  return { kind: "reset", key: action.reset };
 }
 
 function parseActionTemplate(
@@ -292,7 +373,7 @@ export function linkFragment(
 // renders the first display and clicks to the second member (an accordion
 // sibling's path "counts as closed", a never-written toggle "counts as off").
 function cycleIndex(
-  c: Extract<CompiledActionDecl, { kind: "set-cycle" }>,
+  c: Extract<CompiledActionDecl, { kind: "set-cycle" | "persist-cycle" }>,
   store: VariableStore,
 ): number {
   return Math.max(c.members.indexOf(readVar(store, c.stateVar)), 0);
@@ -400,6 +481,47 @@ function realize(
         },
         active: false,
       };
+    // [LAW:one-source-of-truth] The persist-* arms mirror set-*'s realization
+    // verbatim (same literal/option/cycle/bounded semantics), only the wire
+    // verb differs (VERB_SET_CONFIG/VERB_STEP_CONFIG instead of
+    // VERB_SET_STATE/VERB_STEP_STATE) — the daemon-side handler is what makes
+    // the write durable, not the click itself.
+    case "persist-literal": {
+      const current = readVar(store, c.stateVar);
+      return {
+        effect: { verb: VERB_SET_CONFIG, args: [sessionId, c.key, c.value] },
+        active: current === c.value,
+      };
+    }
+    case "persist-option": {
+      const value = boundValue ?? display;
+      const current = readVar(store, c.stateVar);
+      return {
+        effect: { verb: VERB_SET_CONFIG, args: [sessionId, c.key, value] },
+        active: current === value,
+      };
+    }
+    case "persist-cycle": {
+      const next = c.members[(cycleIndex(c, store) + 1) % c.members.length]!;
+      return {
+        effect: { verb: VERB_SET_CONFIG, args: [sessionId, c.key, next] },
+        active: false,
+      };
+    }
+    case "persist-bounded": {
+      return {
+        effect: {
+          verb: VERB_STEP_CONFIG,
+          args: [sessionId, c.key, String(c.by)],
+        },
+        active: false,
+      };
+    }
+    case "reset":
+      return {
+        effect: { verb: VERB_RESET_CONFIG, args: [sessionId, c.key] },
+        active: false,
+      };
   }
 }
 
@@ -419,7 +541,7 @@ function selectDisplay(
   if (displays.length === 0) {
     throw new Error(`action "${name}" needs a display (the clickable text)`);
   }
-  if (action.kind === "set-cycle") {
+  if (action.kind === "set-cycle" || action.kind === "persist-cycle") {
     if (displays.length !== 1 && displays.length !== action.members.length) {
       throw new Error(
         `action "${name}" cycles ${action.members.length} members; bind one display per member (${action.members.length}) or one static display, got ${displays.length}`,