@promptctl/cc-candybar 1.31.0 → 1.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/cc-candybar",
-  "version": "1.31.0",
+  "version": "1.32.0",
   "description": "Statusline renderer for Claude Code — a JSON5-configurable DSL with daemon-cached data sources, byte-clean palette-aware composition, and OSC8 click verbs.",
   "type": "module",
   "main": "./dist/index.mjs",
@@ -91,9 +91,9 @@
     "mobx": "^6.15.0"
   },
   "optionalDependencies": {
-    "@promptctl/cc-candybar-darwin-arm64": "1.31.0",
-    "@promptctl/cc-candybar-darwin-x64": "1.31.0",
-    "@promptctl/cc-candybar-linux-x64": "1.31.0",
-    "@promptctl/cc-candybar-linux-arm64": "1.31.0"
+    "@promptctl/cc-candybar-darwin-arm64": "1.32.0",
+    "@promptctl/cc-candybar-darwin-x64": "1.32.0",
+    "@promptctl/cc-candybar-linux-x64": "1.32.0",
+    "@promptctl/cc-candybar-linux-arm64": "1.32.0"
   }
 }

package/schema/cc-candybar.schema.json

@@ -1364,6 +1364,47 @@
             ],
             "additionalProperties": false
           },
+          {
+            "type": "object",
+            "properties": {
+              "persist": {
+                "type": "string"
+              },
+              "insertSegmentFrom": {
+                "anyOf": [
+                  {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  {
+                    "type": "array",
+                    "items": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "minItems": 1,
+                    "uniqueItems": true
+                  }
+                ]
+              },
+              "anchor": {
+                "type": "string"
+              },
+              "relation": {
+                "enum": [
+                  "before",
+                  "after"
+                ]
+              }
+            },
+            "required": [
+              "persist",
+              "insertSegmentFrom",
+              "anchor",
+              "relation"
+            ],
+            "additionalProperties": false
+          },
           {
             "type": "object",
             "properties": {

package/src/config/action.ts

@@ -108,6 +108,13 @@ export type ActionKey = (typeof ACTION_KEYS)[number];
 //     anchor + relation  — (persist only) insert a named segment before/after
 //                         an existing one, same key shape -> allow-list {one
 //                         op token}
+//   insertSegmentFrom +
+//     anchor + relation  — (persist only) insertSegment's domain-sourced
+//                         sibling (brandon-layout-edit-2gc.3): the segment
+//                         name is picked from an option domain at render
+//                         (a `{{ menu }}`'s bound option) rather than fixed
+//                         at author time -> allow-list {one op token per
+//                         domain member}
 //
 // [LAW:one-source-of-truth] `set` writes SessionState and `persist` writes
 // the config-overrides layer, so only those two derive a validator (through
@@ -156,6 +163,24 @@ export type ActionDecl =
       readonly anchor: string;
       readonly relation: "before" | "after";
     }
+  // [LAW:one-source-of-truth] brandon-layout-edit-2gc.3's DOMAIN-SOURCED
+  // sibling of `insertSegment`: the same tree op, but the segment name comes
+  // from the template's bound option (a picker/menu cell) instead of being
+  // fixed at config-author time — exactly the `to`-vs-`from` split `set`/
+  // `persist` already draw, one arm over. `anchor`/`relation` stay literal
+  // (the POSITION is still author-time data; only WHICH segment lands there
+  // is picked at render). This is what makes a `{{ menu "insertHere" }}`
+  // legal over a structural edit: `requireOptionKind` (render/picker.ts)
+  // admits it alongside set-option/persist-option, and the click writes
+  // `encodeLayoutOp({ op: "insert", segment: <picked>, anchor, relation })` —
+  // the SAME wire shape a literal `insertSegment` action emits, so undo/redo
+  // and the daemon's apply-layout-op handler need no changes at all.
+  | {
+      readonly persist: string;
+      readonly insertSegmentFrom: OptionDomain;
+      readonly anchor: string;
+      readonly relation: "before" | "after";
+    }
   | { readonly copy: string }
   | { readonly open: string }
   | { readonly reset: string }

package/src/config/dsl-loader.ts

@@ -48,6 +48,8 @@ import { validateVariables } from "./loader/variables.js";
 import { validateSegments } from "./loader/segments.js";
 import { synthesizeGroupDecls, validateRoot } from "./loader/layout.js";
 import { synthesizeMenuDecls } from "./loader/menu-synth.js";
+import { synthesizeEditModeToggle } from "./loader/edit-mode.js";
+import { synthesizeEditChrome } from "./edit-chrome.js";
 import { validateActions } from "./loader/actions.js";
 import { validateLooks } from "./loader/looks.js";
 import { validatePresets } from "./loader/presets.js";
@@ -143,7 +145,15 @@ export function validateConfig(
   if (issues.length > 0) {
     throw new ConfigError(filePath, issues);
   }
-  return config as ValidatedConfig;
+  // [LAW:one-source-of-truth] Edit-mode's CHROME half (brandon-layout-edit-
+  // 2gc.3), synthesized HERE — not in parseDslConfig alongside the toggle —
+  // because it needs the fully merged, preset-resolved, rootOps-replayed
+  // tree cross-ref/cycles just proved sound. Its own output (segment refs
+  // into freshly-synthesized segments, actions into freshly-synthesized
+  // actions) is correct by construction and does not re-enter cross-ref/
+  // cycle checking, exactly as group/menu synthesis's output doesn't either.
+  const withChrome = synthesizeEditChrome(config);
+  return withChrome as ValidatedConfig;
 }
 
 /**
@@ -278,6 +288,13 @@ function validateTopLevel(
   // through deriveActionValidators, and collide loudly with any user name under
   // the reserved namespace.
   synthesizeMenuDecls(ctx, out);
+  // [LAW:one-source-of-truth] Edit-mode's TOGGLE half (brandon-layout-edit-
+  // 2gc.3) — unconditional, like the reservation above, so `edit.mode`/
+  // `edit.toggle` exist in EVERY parsed file and a hand-authored trigger
+  // segment cross-ref-checks normally. The CHROME half (the per-position +/-
+  // affordances) runs later, in validateConfig, once the merged/preset-
+  // resolved/rootOps-replayed tree exists to derive it from.
+  synthesizeEditModeToggle(ctx, out);
   return out;
 }
 

package/src/config/edit-chrome.ts

@@ -0,0 +1,329 @@
+// [LAW:one-source-of-truth] brandon-layout-edit-2gc.3's CHROME half — the
+// LOWERING that turns "edit mode is a session toggle" into "each row's
+// segments render interleaved with +/- affordances" without a render-walk
+// branch [LAW:dataflow-not-control-flow]. Follows the SAME move `kind:
+// "group"` sugar makes (src/config/loader/layout.ts): one pass produces a NEW
+// tree with synthesized nodes spliced in, each gated by an ordinary `when` —
+// the walk that renders it learns nothing new. The difference from group
+// sugar is WHEN this can run: a group is authored data, lowered per file
+// before merge; edit chrome is DERIVED from which segments are actually in
+// the tree, which is only known after merge, preset-root resolution, and
+// rootOps replay. So this runs from validateConfig, on the fully resolved
+// config each declared preset stages — see synthesizeEditChrome below.
+//
+// [LAW:single-enforcer] The +/- affordances reuse EXISTING primitives
+// wholesale rather than inventing parallel ones: `-` is an ordinary
+// `{ persist, removeSegment }` action behind `{{ action }}` (2gc.1); `+` is an
+// ordinary `{ persist, insertSegmentFrom }` action behind `{{ menu }}`
+// (2gc.3's new arm — see action.ts), synthesized by calling the SAME pure
+// functions `{{ menu }}`'s own load-time synthesis calls
+// (menu-keys.ts/disclosure.ts) so a synthesized menu and a hand-authored one
+// are indistinguishable at render. Nothing here is a new render concept.
+
+import type { ActionDecl as ActionDeclType, OptionDomain } from "./action.js";
+import type {
+  ContainerNode,
+  DslConfig,
+  LayoutNode,
+  PresetDecl,
+  SegmentDecl,
+  SegmentNode,
+  VariableDecl,
+} from "./dsl-types.js";
+import { collectSegmentNames } from "./layout-ops.js";
+import { presetByName, presetNames, presetRoot } from "./presets.js";
+import {
+  EDIT_MODE_GATE,
+  EDIT_NS,
+  EDIT_TOGGLE_ACTION,
+} from "./loader/edit-mode.js";
+import { GROUP_NS } from "./loader/layout.js";
+import {
+  menuActionName,
+  menuMember,
+  menuPageKey,
+  menuStateKey,
+  MENU_NS,
+} from "./menu-keys.js";
+import {
+  DISCLOSURE_CLOSED,
+  disclosureCycleAction,
+  disclosureStateVar,
+} from "./disclosure.js";
+
+// [LAW:one-source-of-truth] group/menu-synthesized segments (`groups.`/
+// `menus.`) and edit mode's own trigger/chrome (`edit.`) are structural —
+// removing one via `-` would strand its sibling artifacts (a toggle segment
+// with no body, a menu with no host), and offering one back via `+` would
+// insert a bare ref with none of the synthesis that made it work. Ordinary
+// content segments only.
+function isChromeExempt(name: string): boolean {
+  return (
+    name.startsWith(EDIT_NS) ||
+    name.startsWith(MENU_NS) ||
+    name.startsWith(GROUP_NS)
+  );
+}
+
+// [LAW:types-are-the-program] Collapse an arbitrary name to a template-
+// identifier-safe fragment — the SAME shape menu-keys.ts's `ident` enforces,
+// reimplemented here rather than imported (menu-keys.ts's copy is
+// module-private) since both need only the one rule: alphanumerics survive,
+// everything else collapses to `_`.
+function ident(name: string): string {
+  return name.replace(/[^A-Za-z0-9]+/g, "_");
+}
+
+// [LAW:one-source-of-truth] Every synthesized decl this pass produces, keyed
+// by its final name — one accumulator threaded through every preset's splice
+// so cross-preset names (disambiguated by `presetIdent`) can never collide.
+interface ChromeArtifacts {
+  readonly variables: Record<string, VariableDecl>;
+  readonly actions: Record<string, ActionDeclType>;
+  readonly segments: Record<string, SegmentDecl>;
+}
+
+// [LAW:one-source-of-truth] The domain name a preset's `+` pickers range —
+// computed once per preset (declared segments minus the ones already present
+// in ITS current tree) and consumed two ways: here (by name, for every
+// insertSegmentFrom action this preset's splice synthesizes) and by
+// registerDslConfig/deriveConfigActionValidators (which call
+// `addableSegmentDomains` directly to populate `perConfigDomains` before
+// resolving `from`). Both read the SAME string shape so a synthesized
+// action's domain name always resolves.
+export function addableDomainName(presetName: string): string {
+  return `${EDIT_NS}addable.${presetName}`;
+}
+
+// [LAW:one-source-of-truth] THE per-preset "what can `+` offer here" set:
+// every declared, non-exempt segment name minus the ones already present
+// anywhere in that preset's CURRENT (merged, rootOps-replayed) tree. Exported
+// so render.ts's registerDslConfig and config-validators.ts's
+// deriveConfigActionValidators — the two sites that resolve `from` domains —
+// merge this into `perConfigDomainsFor`'s map without each re-deriving it
+// [LAW:locality-or-seam]; option-domain.ts itself stays untouched (its
+// `perConfigDomainsFor` deliberately never imports dsl-types.ts — see that
+// file's own header — so a third per-preset domain merges at the two call
+// sites instead of inside it).
+export function addableSegmentDomains(
+  config: DslConfig,
+): ReadonlyMap<string, readonly string[]> {
+  const declared = Object.keys(config.segments).filter(
+    (n) => !isChromeExempt(n),
+  );
+  const domains = new Map<string, readonly string[]>();
+  for (const name of presetNames(config.presets)) {
+    const { node } = presetRoot(config, name);
+    const present = collectSegmentNames(node);
+    domains.set(
+      addableDomainName(name),
+      declared.filter((n) => !present.has(n)),
+    );
+  }
+  return domains;
+}
+
+// Synthesize the `-` affordance for one segment instance: a literal
+// `removeSegment` action plus the segment that hosts its `{{ action }}`.
+function removeChrome(
+  presetIdent: string,
+  rootOpsKey: string,
+  segName: string,
+  artifacts: ChromeArtifacts,
+): SegmentNode {
+  const actionName = `${EDIT_NS}${presetIdent}.remove.${ident(segName)}`;
+  const chromeSegName = `${EDIT_NS}${presetIdent}.removeSeg.${ident(segName)}`;
+  artifacts.actions[actionName] = {
+    persist: rootOpsKey,
+    removeSegment: segName,
+  };
+  artifacts.segments[chromeSegName] = {
+    template: `{{ action "${actionName}" "-" }}`,
+    when: EDIT_MODE_GATE,
+  };
+  return { kind: "segment", name: chromeSegName };
+}
+
+// Synthesize the `+` affordance for one gap: an `insertSegmentFrom` action
+// over this preset's addable domain, plus a segment hosting `{{ menu }}` over
+// it. The menu's own disclosure (open state, page cursor, toggle action) is
+// synthesized here by calling the SAME pure functions menu-synth.ts's
+// file-parse-time pass calls — this pass runs too late to piggyback on that
+// pass directly (it needs post-merge/post-rootOps data menu-synth.ts's
+// per-file timing does not have), so parity is achieved by sharing the
+// functions, not by re-deriving the shape.
+function insertChrome(
+  presetIdent: string,
+  rootOpsKey: string,
+  posIdent: string,
+  domainName: OptionDomain,
+  anchor: string,
+  relation: "before" | "after",
+  artifacts: ChromeArtifacts,
+): SegmentNode {
+  const applyName = `${EDIT_NS}${presetIdent}.insert.${posIdent}`;
+  const chromeSegName = `${EDIT_NS}${presetIdent}.insertSeg.${posIdent}`;
+  artifacts.actions[applyName] = {
+    persist: rootOpsKey,
+    insertSegmentFrom: domainName,
+    anchor,
+    relation,
+  };
+
+  const member = menuMember(applyName);
+  const stateKey = menuStateKey(chromeSegName, applyName, undefined);
+  const pageKey = menuPageKey(stateKey);
+  const identity = menuActionName(stateKey, member);
+  artifacts.variables[stateKey] = disclosureStateVar(
+    stateKey,
+    DISCLOSURE_CLOSED,
+  );
+  artifacts.variables[pageKey] = { kind: "state", key: pageKey, default: "0" };
+  artifacts.actions[identity] = disclosureCycleAction(stateKey, member);
+  artifacts.actions[pageKey] = { set: pageKey, int: true };
+
+  artifacts.segments[chromeSegName] = {
+    template: `+{{ menu "${applyName}" }}`,
+    when: EDIT_MODE_GATE,
+  };
+  return { kind: "segment", name: chromeSegName };
+}
+
+// [LAW:dataflow-not-control-flow] One recursive splice: a container's
+// non-exempt segment children get a `+` before and a `-` after (so N
+// consecutive segments read `+ [seg1 -] + [seg2 -] + [seg3 -] +` — N+1 insert
+// points, N remove points); a container child recurses; an exempt segment
+// (a group toggle, a menu host, edit mode's own chrome) passes through
+// untouched. `posCounter` is threaded by reference so position identifiers
+// stay unique across the WHOLE preset tree, not just one container.
+function spliceContainer(
+  node: ContainerNode,
+  presetIdent: string,
+  rootOpsKey: string,
+  domainName: OptionDomain,
+  artifacts: ChromeArtifacts,
+  posCounter: { n: number },
+): ContainerNode {
+  const children: LayoutNode[] = [];
+  for (const child of node.children) {
+    if (child.kind === "container") {
+      children.push(
+        spliceContainer(
+          child,
+          presetIdent,
+          rootOpsKey,
+          domainName,
+          artifacts,
+          posCounter,
+        ),
+      );
+      continue;
+    }
+    if (isChromeExempt(child.name)) {
+      children.push(child);
+      continue;
+    }
+    children.push(
+      insertChrome(
+        presetIdent,
+        rootOpsKey,
+        String(posCounter.n++),
+        domainName,
+        child.name,
+        "before",
+        artifacts,
+      ),
+    );
+    children.push(child);
+    children.push(removeChrome(presetIdent, rootOpsKey, child.name, artifacts));
+  }
+  const last = node.children[node.children.length - 1];
+  if (
+    last !== undefined &&
+    last.kind === "segment" &&
+    !isChromeExempt(last.name)
+  ) {
+    children.push(
+      insertChrome(
+        presetIdent,
+        rootOpsKey,
+        String(posCounter.n++),
+        domainName,
+        last.name,
+        "after",
+        artifacts,
+      ),
+    );
+  }
+  return { ...node, children };
+}
+
+// One preset's chrome-spliced root. A bare-segment root (the A-grammar
+// collapses a single top-level segment ref to `{ kind: "segment", name }`
+// with no enclosing container) is wrapped in a synthetic horizontal
+// container for splicing purposes — the wrap becomes the real returned root,
+// which is exactly right: a lone segment needs a `+` on each side too.
+function spliceEditChromeForPreset(
+  config: DslConfig,
+  presetName: string,
+  artifacts: ChromeArtifacts,
+): LayoutNode {
+  const { node } = presetRoot(config, presetName);
+  const rootOpsKey = `presets.${presetName}.rootOps`;
+  const domainName = addableDomainName(presetName);
+  const presetIdent = ident(presetName);
+  const posCounter = { n: 0 };
+  const container: ContainerNode =
+    node.kind === "container"
+      ? node
+      : { kind: "container", direction: "horizontal", children: [node] };
+  return spliceContainer(
+    container,
+    presetIdent,
+    rootOpsKey,
+    domainName,
+    artifacts,
+    posCounter,
+  );
+}
+
+// [LAW:single-enforcer] THE synthesis entry point, called once from
+// validateConfig after cross-ref/cycle checks pass. Every declared preset
+// (the floor "default" included — presetNames/presetByName/presetRoot
+// already treat it uniformly) gets an explicit `presets[name].root` carrying
+// its spliced tree; `config.root` itself is left untouched (presetRoot falls
+// back to it only when a preset declares no root of its own, and every name
+// now does). The synthesized variables/actions/segments merge additively —
+// nothing here can collide with user data, since every name it mints lives
+// under the `edit.`/`menus.` namespaces `synthesizeEditModeToggle` and
+// `synthesizeMenuDecls` already reserve unconditionally at parse time.
+export function synthesizeEditChrome(config: DslConfig): DslConfig {
+  // [LAW:carrying-cost] Demand-driven, mirroring synthesizeEditModeToggle's
+  // own gate: `edit.toggle` exists in the merged config iff SOME file's
+  // Phase A synthesis fired (iff some segment referenced it), which iff some
+  // author actually placed an edit-mode trigger. A config that never opted
+  // in gets back the identical config, untouched — no extra segments,
+  // actions, or variables, and critically no NEW `set`/`state` surface that
+  // would force session.id onto an otherwise fully static bar.
+  if (!(EDIT_TOGGLE_ACTION in config.actions)) return config;
+  const artifacts: ChromeArtifacts = {
+    variables: {},
+    actions: {},
+    segments: {},
+  };
+  const presets: Record<string, PresetDecl> = { ...config.presets };
+  for (const name of presetNames(config.presets)) {
+    const splicedRoot = spliceEditChromeForPreset(config, name, artifacts);
+    presets[name] = {
+      ...presetByName(config.presets, name),
+      root: splicedRoot,
+    };
+  }
+  return {
+    ...config,
+    variables: { ...config.variables, ...artifacts.variables },
+    actions: { ...config.actions, ...artifacts.actions },
+    segments: { ...config.segments, ...artifacts.segments },
+    presets,
+  };
+}

package/src/config/layout-ops.ts

@@ -79,6 +79,27 @@ export function decodeLayoutOp(token: string): LayoutOp | null {
   return null;
 }
 
+// [LAW:single-enforcer] THE one collector of "which segment names does this
+// tree contain" — brandon-layout-edit-2gc.3's edit-chrome synthesis
+// (src/config/edit-chrome.ts) uses it to compute both halves of the +/-
+// affordances: which segments are PRESENT (get a `-`) and, by set difference
+// against every declared segment, which are ADDABLE (populate the `+`
+// picker's domain). A name appearing more than once collapses to one entry —
+// callers that care about occurrence COUNT (none currently do) need a
+// different walk.
+export function collectSegmentNames(root: LayoutNode): ReadonlySet<string> {
+  const out = new Set<string>();
+  const walk = (node: LayoutNode): void => {
+    if (node.kind === "segment") {
+      out.add(node.name);
+      return;
+    }
+    for (const child of node.children) walk(child);
+  };
+  walk(root);
+  return out;
+}
+
 // [LAW:dataflow-not-control-flow] Ops are DATA folded over the tree in
 // order — replaying zero ops is the identity fold, replaying N is the same
 // reduce for every N. No branch on "are there ops to apply."

package/src/config/loader/actions.ts

@@ -388,6 +388,20 @@ const INSERT_SEGMENT_FIELDS: FieldSpecMap<{
   anchor: layoutNameSpec("anchor"),
   relation: relationSpec(),
 };
+// [LAW:one-type-per-behavior] `insertSegmentFrom`'s payload mirrors
+// `insertSegment`'s verbatim except the segment name is a `from`-shaped
+// OptionDomain (fromSpec, the SAME field `set`/`persist … from` already
+// validate) instead of a literal layout name — the "to" vs "from" split every
+// other value source already draws, one arm over.
+const INSERT_SEGMENT_FROM_FIELDS: FieldSpecMap<{
+  insertSegmentFrom: OptionDomain;
+  anchor: string;
+  relation: "before" | "after";
+}> = {
+  insertSegmentFrom: fromSpec("persist"),
+  anchor: layoutNameSpec("anchor"),
+  relation: relationSpec(),
+};
 
 // [LAW:types-are-the-program] A bounded step is fully described by an integer
 // domain (min < max) and a non-zero integer increment (`by`; negative for a
@@ -440,12 +454,25 @@ interface ValueSourceArm {
   readonly parse: ArmParse<Partial<ActionDecl>>;
 }
 
+// [LAW:no-mode-explosion] `detectKeys` narrows WHICH of an arm's fields the
+// present-count dispatch keys off, independent of `allowed`/`label` (still
+// the full field set — what the arm PERMITS and is NAMED by never changes).
+// Every arm before insertSegmentFrom had a field set disjoint from every
+// other arm's, so `Object.keys(fieldMap)` was a safe default for both jobs
+// at once. insertSegmentFrom breaks that: it shares `anchor`/`relation` with
+// insertSegment (same POSITION shape, different segment-name SOURCE), so
+// dispatching on the full set would make an ordinary `insertSegment` action
+// spuriously match both arms via those shared keys. Pass the true
+// discriminator (the field no sibling arm carries) here; omit it when the
+// field set already is disjoint from every sibling, as it is everywhere else.
 function valueSourceArm<P extends object>(
   discriminator: "set" | "persist",
   fieldMap: FieldSpecMap<P>,
-  ...checks: ReadonlyArray<Refinement<P>>
+  checks: ReadonlyArray<Refinement<P>> = [],
+  detectKeys?: readonly string[],
 ): ValueSourceArm {
-  const detect = Object.keys(fieldMap);
+  const fullKeys = Object.keys(fieldMap);
+  const detect = detectKeys ?? fullKeys;
   const inner: ArmParse<P> = (ctx, path, raw) =>
     fields(ctx, fieldMap, path, raw);
   const source = objectJson(fieldMap) as {
@@ -454,8 +481,8 @@ function valueSourceArm<P extends object>(
   };
   return {
     detect,
-    allowed: [discriminator, ...detect],
-    label: detect.join("/"),
+    allowed: [discriminator, ...fullKeys],
+    label: fullKeys.join("/"),
     json: {
       type: "object",
       properties: { [discriminator]: { type: "string" }, ...source.properties },
@@ -475,7 +502,7 @@ function valueSourceArm<P extends object>(
 const SET_ARMS: readonly ValueSourceArm[] = [
   valueSourceArm("set", TO_FIELDS_SET),
   valueSourceArm("set", FROM_FIELDS_SET),
-  valueSourceArm("set", BOUNDED_FIELDS, minLessThanMax, byNonZero),
+  valueSourceArm("set", BOUNDED_FIELDS, [minLessThanMax, byNonZero]),
   valueSourceArm("set", INT_FIELDS),
   valueSourceArm("set", CYCLE_FIELDS_SET),
 ];
@@ -487,10 +514,21 @@ const SET_ARMS: readonly ValueSourceArm[] = [
 const PERSIST_ARMS: readonly ValueSourceArm[] = [
   valueSourceArm("persist", TO_FIELDS_PERSIST),
   valueSourceArm("persist", FROM_FIELDS_PERSIST),
-  valueSourceArm("persist", BOUNDED_FIELDS, minLessThanMax, byNonZero),
+  valueSourceArm("persist", BOUNDED_FIELDS, [minLessThanMax, byNonZero]),
   valueSourceArm("persist", CYCLE_FIELDS_PERSIST),
   valueSourceArm("persist", REMOVE_SEGMENT_FIELDS),
-  valueSourceArm("persist", INSERT_SEGMENT_FIELDS),
+  // [LAW:no-mode-explosion] Both insertSegment arms narrow detectKeys to
+  // their own discriminating field — see valueSourceArm's own comment. They
+  // share "anchor"/"relation" (same position shape, different segment-name
+  // source), so dispatching on the full field set would make EITHER arm
+  // spuriously match an action declaring the other.
+  valueSourceArm("persist", INSERT_SEGMENT_FIELDS, [], ["insertSegment"]),
+  valueSourceArm(
+    "persist",
+    INSERT_SEGMENT_FROM_FIELDS,
+    [],
+    ["insertSegmentFrom"],
+  ),
 ];
 
 // [LAW:one-source-of-truth] The clause list, not the joined string, is the
@@ -511,6 +549,7 @@ function valueSourceClauses(discriminator: "set" | "persist"): string[] {
     clauses.push(
       `"removeSegment" (remove a named segment from the layout)`,
       `"insertSegment"/"anchor"/"relation" (insert a named segment before/after an existing one)`,
+      `"insertSegmentFrom"/"anchor"/"relation" (insert a segment PICKED from an option domain before/after an existing one)`,
     );
   }
   return clauses;
@@ -635,7 +674,7 @@ function fromSpec(discriminator: "set" | "persist"): FieldSpec<OptionDomain> {
       const at = `${path}.${field}`;
       if (typeof from === "string") {
         if (from === "") {
-          issue(ctx, at, `from must be a non-empty domain name`);
+          issue(ctx, at, `${field} must be a non-empty domain name`);
           return undefined;
         }
         return from;
@@ -646,7 +685,7 @@ function fromSpec(discriminator: "set" | "persist"): FieldSpec<OptionDomain> {
           issue(
             ctx,
             at,
-            `from must name a domain (a non-empty string) or declare an inline domain (a non-empty array of values)`,
+            `${field} must name a domain (a non-empty string) or declare an inline domain (a non-empty array of values)`,
           );
           return undefined;
         }
@@ -654,7 +693,7 @@ function fromSpec(discriminator: "set" | "persist"): FieldSpec<OptionDomain> {
           issue(
             ctx,
             at,
-            `from array members must be non-empty — an empty value cannot be delivered on the ${wire} wire`,
+            `${field} array members must be non-empty — an empty value cannot be delivered on the ${wire} wire`,
           );
           return undefined;
         }
@@ -663,7 +702,7 @@ function fromSpec(discriminator: "set" | "persist"): FieldSpec<OptionDomain> {
           issue(
             ctx,
             at,
-            `from array member(s) ${slashed.map((m) => `"${m}"`).join(", ")} contain "/" — ${discriminator} values must be slash-free`,
+            `${field} array member(s) ${slashed.map((m) => `"${m}"`).join(", ")} contain "/" — ${discriminator} values must be slash-free`,
           );
           return undefined;
         }
@@ -671,7 +710,7 @@ function fromSpec(discriminator: "set" | "persist"): FieldSpec<OptionDomain> {
           issue(
             ctx,
             at,
-            `from array members must be unique — a duplicated value would render the same picker option twice`,
+            `${field} array members must be unique — a duplicated value would render the same picker option twice`,
           );
           return undefined;
         }
@@ -680,7 +719,7 @@ function fromSpec(discriminator: "set" | "persist"): FieldSpec<OptionDomain> {
       issue(
         ctx,
         at,
-        `from must be a domain name (a string) or an inline domain (an array of strings), got ${describeValue(from)}`,
+        `${field} must be a domain name (a string) or an inline domain (an array of strings), got ${describeValue(from)}`,
       );
       return undefined;
     },