@promptctl/cc-candybar 1.31.0 → 1.32.0

package/src/config/loader/cross-ref.ts

@@ -396,10 +396,14 @@ function checkPresetRootOpsTarget(
   if (discriminator === "reset") return;
   const hasRemove = "removeSegment" in a;
   const hasInsert = "insertSegment" in a;
-  if (!hasRemove && !hasInsert) {
+  // [LAW:one-source-of-truth] brandon-layout-edit-2gc.3's domain-sourced
+  // sibling — the segment name is picked at render, so only `anchor` (still
+  // literal at author time) needs the declared-segment check below.
+  const hasInsertFrom = "insertSegmentFrom" in a;
+  if (!hasRemove && !hasInsert && !hasInsertFrom) {
     ctx.issues.push({
       path: at,
-      message: `actions.${name}: "${key}" is a "presets.<name>.rootOps" target and can only be paired with "removeSegment" or "insertSegment" (not "to"/"from"/"cycle"/bounded — those have no meaning as a tree op)`,
+      message: `actions.${name}: "${key}" is a "presets.<name>.rootOps" target and can only be paired with "removeSegment", "insertSegment", or "insertSegmentFrom" (not "to"/"from"/"cycle"/bounded — those have no meaning as a tree op)`,
       line,
     });
     return;
@@ -429,6 +433,13 @@ function checkPresetRootOpsTarget(
       });
     }
   }
+  if (hasInsertFrom && "insertSegmentFrom" in a && missing(a.anchor)) {
+    ctx.issues.push({
+      path: at,
+      message: `actions.${name}: anchor "${a.anchor}" is not a declared segment (have: ${Object.keys(cfg.segments).join(", ")})`,
+      line,
+    });
+  }
 }
 
 function hasStateKind(cfg: DslConfig): boolean {

package/src/config/loader/edit-mode.ts

@@ -0,0 +1,111 @@
+// [LAW:one-source-of-truth] brandon-layout-edit-2gc.3's TOGGLE half of edit
+// mode — the disclosure primitive's third body-kind, one register down from
+// group sugar and `{{ menu }}`: where those two synthesize a whole trigger +
+// body, edit mode synthesizes only the on/off state + toggle ACTION here
+// (`edit.mode` / `edit.toggle`), so a hand-authored `{{ action "edit.toggle"
+// "✎" }}` cross-ref-checks and compiles exactly like any other action — no
+// bespoke "this action always exists" carve-out anywhere downstream. The
+// per-segment +/- CHROME is a separate, LATER pass
+// (src/config/edit-chrome.ts) that runs on the fully merged, preset-resolved,
+// rootOps-replayed config (inside validateConfig, not here) because it needs
+// data — which segments are in which preset's CURRENT tree — that does not
+// exist yet at this per-file parse stage. Splitting the two halves across two
+// synthesis points is not incidental: the toggle is authorable/cross-ref-able
+// content (like a group's name or a menu's apply action), the chrome is
+// derived data (like a group's lowered body), and each belongs at the stage
+// that has what it needs.
+//
+// [LAW:carrying-cost] DEMAND-DRIVEN, not unconditional — this is the one place
+// this pass diverges from group/menu synthesis's OWN precedent of "reserve
+// unconditionally, synthesize on demand" and leans fully into the "on demand"
+// half: a config that references `{{ action "edit.toggle" … }}` nowhere gets
+// NEITHER the toggle var/action NOR (edit-chrome.ts checks for the SAME
+// action's presence) any per-segment chrome. This matters concretely, not just
+// as a purity concern — `edit.mode` is a `state` variable and `edit.toggle` is
+// a `set` action, and cross-ref.ts requires a global `session.id` variable the
+// instant ANY state var or set action exists anywhere in a config. Synthesizing
+// either unconditionally would force session.id onto every purely-static,
+// non-interactive bar in the corpus — exactly the regression an early version
+// of this pass caused. The reserved namespace stays reserved unconditionally
+// (mirroring reservedNamespaceCollisions' own contract); only the SYNTHESIS is
+// conditional.
+
+import { createEngine } from "@promptctl/go-template-js";
+import type { Mutable, ValidateCtx } from "./validate-core.js";
+import type { RawDslConfig, VariableDecl } from "../dsl-types.js";
+import type { ActionDecl } from "../action.js";
+import {
+  DISCLOSURE_CLOSED,
+  disclosureCycleAction,
+  disclosureStateVar,
+} from "../disclosure.js";
+import { reservedNamespaceCollisions } from "./reserved-namespace.js";
+
+// [LAW:one-source-of-truth] The reserved namespace every edit-mode artifact —
+// this toggle AND edit-chrome.ts's per-position +/- actions/segments — lives
+// under, mirroring `groups.`/`menus.`. Exported so edit-chrome.ts's LATER
+// synthesis (and its `isChromeExempt` exclusion of edit-mode's own chrome
+// from being treated as ordinary, removable/addable content) reads the same
+// string, never a second copy.
+export const EDIT_NS = "edit.";
+
+// [LAW:single-enforcer] The SessionState key edit mode's on/off state lives
+// at, and the toggle action's identity member. Both edit-chrome.ts (every
+// synthesized affordance's `when` gate) and a hand-authored trigger segment
+// read/write these same two names — one declaration, no drift.
+export const EDIT_MODE_KEY = "edit.mode";
+export const EDIT_TOGGLE_ACTION = "edit.toggle";
+export const EDIT_MODE_OPEN = "open";
+
+// [LAW:one-source-of-truth] The predicate every synthesized +/- chrome
+// segment gates on — spelled once here so edit-chrome.ts never hand-rolls
+// the template string a second time.
+export const EDIT_MODE_GATE = `{{ eq .${EDIT_MODE_KEY} "${EDIT_MODE_OPEN}" }}`;
+
+// [LAW:single-enforcer] The ONE detector for "does this file want edit mode":
+// a literal `{{ action "edit.toggle" … }}` call somewhere a segment's
+// template/bg/fg can reach — the SAME AST-based approach
+// menu-synth.ts's segmentReferencesMenu uses (robust against whitespace,
+// pipelines, and lookalike text a source-string scan would false-positive
+// or false-negative on), one function name over. A bare engine purely for
+// introspection: it never evaluates, so a malformed template simply yields
+// no match here (registerDslConfig re-parses and reports the real error;
+// [LAW:no-silent-failure] this pass just isn't the one that reports it).
+function referencesEditToggle(template: string): boolean {
+  const engine = createEngine<string>({ fromString: (s) => s });
+  try {
+    return engine
+      .parse(template)
+      .referencedCalls()
+      .some((c) => c.name === "action" && c.args[0] === EDIT_TOGGLE_ACTION);
+  } catch {
+    return false;
+  }
+}
+
+function fileWantsEditMode(out: Readonly<RawDslConfig>): boolean {
+  for (const seg of Object.values(out.segments ?? {})) {
+    for (const field of [seg.template, seg.bg, seg.fg] as const) {
+      if (typeof field === "string" && referencesEditToggle(field)) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+export function synthesizeEditModeToggle(
+  ctx: ValidateCtx,
+  out: Mutable<RawDslConfig>,
+): void {
+  reservedNamespaceCollisions(ctx, out, EDIT_NS, "edit mode");
+  if (!fileWantsEditMode(out)) return;
+  const variables: Record<string, VariableDecl> = {
+    [EDIT_MODE_KEY]: disclosureStateVar(EDIT_MODE_KEY, DISCLOSURE_CLOSED),
+  };
+  const actions: Record<string, ActionDecl> = {
+    [EDIT_TOGGLE_ACTION]: disclosureCycleAction(EDIT_MODE_KEY, EDIT_MODE_OPEN),
+  };
+  out.variables = { ...(out.variables ?? {}), ...variables };
+  out.actions = { ...(out.actions ?? {}), ...actions };
+}

package/src/daemon/verbs/config-validators.ts

@@ -15,6 +15,7 @@ import {
   perConfigDomainsFor,
   resolveOptionDomain,
 } from "../../config/option-domain";
+import { addableSegmentDomains } from "../../config/edit-chrome";
 import type { DslConfig } from "../../config/dsl-types";
 import { isGlobalsField } from "../config-overrides-store";
 import { encodeLayoutOp } from "../../config/layout-ops";
@@ -111,6 +112,34 @@ function actionKeySpecs(
       },
     ];
   }
+  // [LAW:one-source-of-truth] brandon-layout-edit-2gc.3's domain-sourced
+  // sibling: the allow-list is the ENCODED op token for every domain member,
+  // not the raw member — mirroring how a literal `insertSegment` contributes
+  // its own single encoded token above. A click carrying an option this
+  // domain never named — or naming a real segment but the wrong anchor/
+  // relation — cannot decode to a member of this list, so it is rejected the
+  // same loud way an unknown literal op token already is.
+  if ("insertSegmentFrom" in a) {
+    return [
+      {
+        key: a.persist,
+        spec: {
+          kind: "allow-list",
+          allowed: resolveOptionDomain(
+            a.insertSegmentFrom,
+            perConfigDomains,
+          ).map((segment) =>
+            encodeLayoutOp({
+              op: "insert",
+              segment,
+              anchor: a.anchor,
+              relation: a.relation,
+            }),
+          ),
+        },
+      },
+    ];
+  }
   return [
     {
       key: a.persist,
@@ -141,7 +170,16 @@ function configKeySeeds(config: DslConfig): ReadonlyMap<string, number> {
 
 function actionContributions(config: DslConfig): KeySpecContribution[] {
   const seeds = configKeySeeds(config);
-  const perConfigDomains = perConfigDomainsFor(config);
+  // [LAW:one-source-of-truth] The "addable segment" domains
+  // (edit-chrome.ts's `addableSegmentDomains`) merge in here alongside
+  // looks/presets — the same per-preset seam `insertSegmentFrom` resolves
+  // through at render (render.ts's registerDslConfig merges the identical
+  // map), so the rendered picker options and the derived click gate can
+  // never diverge over what's addable.
+  const perConfigDomains = new Map([
+    ...perConfigDomainsFor(config),
+    ...addableSegmentDomains(config),
+  ]);
   return Object.values(config.actions).flatMap((a) =>
     actionKeySpecs(a, seeds, perConfigDomains),
   );

package/src/dsl/render.ts

@@ -23,6 +23,7 @@ import type {
 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 { addableSegmentDomains } from "../config/edit-chrome.js";
 import type { VariableStore } from "../var-system/store.js";
 import type { SourceRegistry } from "../var-system/sources.js";
 import {
@@ -340,7 +341,15 @@ export function registerDslConfig(
   // one source.
   const lookNames = Object.keys(config.looks);
   const presetOptions = presetNames(config.presets);
-  const perConfigDomains = perConfigDomainsFor(config);
+  // [LAW:one-source-of-truth] The "addable segment" per-preset domains merge
+  // in here — the SAME map config-validators.ts's deriveConfigActionValidators
+  // merges — so a synthesized `insertSegmentFrom` action's rendered options
+  // and its derived click gate resolve from one source, never two
+  // independently-computed sets.
+  const perConfigDomains = new Map([
+    ...perConfigDomainsFor(config),
+    ...addableSegmentDomains(config),
+  ]);
   const engine = createCcCandybarEngine(
     {
       ...actionFuncs(actionRuntime),

package/src/render/action.ts

@@ -145,6 +145,22 @@ export type CompiledActionDecl =
   // template-bound option, unlike persist-option), so `op` is precomputed
   // here rather than reconstructed from raw fields at every realize() call.
   | { readonly kind: "layout-op"; readonly key: string; readonly op: LayoutOp }
+  // [LAW:one-source-of-truth] brandon-layout-edit-2gc.3's domain-sourced
+  // sibling of layout-op: `anchor`/`relation` are fixed at compile time (the
+  // POSITION is author-time data) but the segment name comes from the
+  // template's bound option — the option-picking shape `persist-option`
+  // already has, minus the value being written VERBATIM. `requireOptionKind`
+  // (render/picker.ts) admits this kind alongside set-option/persist-option
+  // so a `{{ menu }}`/`{{ picker }}` can drive it with zero picker changes;
+  // only the WRITE (realize(), below) differs — it encodes the picked option
+  // into a LayoutOp instead of persisting it as-is.
+  | {
+      readonly kind: "layout-op-option";
+      readonly key: string;
+      readonly anchor: string;
+      readonly relation: "before" | "after";
+      readonly options: readonly string[];
+    }
   // [LAW:one-source-of-truth] brandon-layout-edit-2gc.2's global history
   // step over the overrides layer — `reset`'s fine-grained sibling. No key:
   // there is nothing to carry, since the history stack (not this action) is
@@ -328,6 +344,17 @@ function compileAction(
         },
       };
     }
+    if ("insertSegmentFrom" in action) {
+      return {
+        kind: "layout-op-option",
+        key: action.persist,
+        anchor: action.anchor,
+        relation: action.relation,
+        options: [
+          ...resolveOptionDomain(action.insertSegmentFrom, perConfigDomains),
+        ],
+      };
+    }
     return {
       kind: "persist-bounded",
       key: action.persist,
@@ -587,6 +614,28 @@ function realize(
         },
         active: false,
       };
+    // [LAW:one-source-of-truth] The picked option (boundValue ?? display — the
+    // SAME resolution persist-option uses) becomes the op's `segment`; anchor/
+    // relation are the compiled literals. Same wire shape a literal layout-op
+    // emits, so the daemon's apply-layout-op handler and undo/redo need no
+    // knowledge of where the segment name came from. Never "active": a
+    // structural edit is a one-shot trigger, not a current-selection toggle.
+    case "layout-op-option": {
+      const segment = boundValue ?? display;
+      const op: LayoutOp = {
+        op: "insert",
+        segment,
+        anchor: c.anchor,
+        relation: c.relation,
+      };
+      return {
+        effect: {
+          verb: VERB_APPLY_LAYOUT_OP,
+          args: [sessionId, c.key, encodeLayoutOp(op)],
+        },
+        active: false,
+      };
+    }
   }
 }
 

package/src/render/picker.ts

@@ -28,7 +28,13 @@ import type { FuncMap } from "@promptctl/go-template-js";
 import { toNumber } from "../var-system/types.js";
 import { stripChromeCols } from "./strip.js";
 import { TERM_COLS_VAR } from "../config/dsl-types.js";
-import { effectsUrl, VERB_SET_CONFIG, VERB_SET_STATE } from "../click/wire.js";
+import {
+  effectsUrl,
+  VERB_APPLY_LAYOUT_OP,
+  VERB_SET_CONFIG,
+  VERB_SET_STATE,
+} from "../click/wire.js";
+import { encodeLayoutOp } from "../config/layout-ops.js";
 import {
   linkFragment,
   readVar,
@@ -136,26 +142,33 @@ function requireKind<K extends CompiledActionDecl["kind"]>(
   return action as Extract<CompiledActionDecl, { kind: K }>;
 }
 
-// [LAW:one-source-of-truth] The apply action a picker grid binds to is EITHER
-// of set-option's two durability twins (src/render/action.ts's persist-*
-// mirrors set-*'s shapes one for one) — a picker over `persist("charset",
-// from:"charsets")` is exactly as legal as one over `set("theme",
-// from:"themes")`, differing only in which wire verb the option click emits
-// (VERB_SET_CONFIG vs VERB_SET_STATE), never in shape (both carry key,
-// stateVar, options). Rejecting persist-option here would be an artificial
-// gap: the same option-domain gate (deriveActionValidators) covers both kinds
-// identically, so there is nothing about "picker" that's set-only.
+// [LAW:one-source-of-truth] The apply action a picker grid binds to is one of
+// THREE option-domain-driven kinds (src/render/action.ts): set-option/
+// persist-option (a picked value is WRITTEN VERBATIM — set-option's two
+// durability twins, differing only in wire verb VERB_SET_CONFIG vs
+// VERB_SET_STATE) or layout-op-option (a picked value is ENCODED into a
+// structural LayoutOp before writing — brandon-layout-edit-2gc.3's
+// `insertSegmentFrom`). All three share the same option-domain gate
+// (deriveActionValidators/deriveConfigActionValidators) and the same "pick a
+// cell, apply it" shape; only WHAT the click writes differs, which is
+// realize()'s job, not the picker's. Rejecting any of the three here would be
+// an artificial gap — there is nothing about "picker" that excludes one kind.
 function requireOptionKind(
   runtime: ActionRuntime,
   name: string,
-): Extract<CompiledActionDecl, { kind: "set-option" | "persist-option" }> {
+): Extract<
+  CompiledActionDecl,
+  { kind: "set-option" | "persist-option" | "layout-op-option" }
+> {
   const action = runtime.compiled.get(name);
   if (
     !action ||
-    (action.kind !== "set-option" && action.kind !== "persist-option")
+    (action.kind !== "set-option" &&
+      action.kind !== "persist-option" &&
+      action.kind !== "layout-op-option")
   ) {
     throw new Error(
-      `picker references action "${name}" which must be a set-option or persist-option action ({ set, from } or { persist, from }), got ${action ? `a ${action.kind} action` : "no such action"}`,
+      `picker references action "${name}" which must be a set-option, persist-option, or layout-op-option action ({ set, from }, { persist, from }, or { persist, insertSegmentFrom, anchor, relation }), got ${action ? `a ${action.kind} action` : "no such action"}`,
     );
   }
   return action;
@@ -183,7 +196,13 @@ export function renderPicker(
   const apply = requireOptionKind(runtime, applyName);
   const store = runtime.store;
   const sessionId = readVar(store, "session.id");
-  const current = readVar(store, apply.stateVar);
+  // [LAW:no-defensive-null-guards] layout-op-option carries no `stateVar` —
+  // a structural insert is a one-shot trigger, not a persisted single value,
+  // so there is no "current selection" to mark. `undefined` here (never a
+  // magic sentinel string) makes every option's `option === current` compare
+  // false below, structurally rather than by accident.
+  const current =
+    "stateVar" in apply ? readVar(store, apply.stateVar) : undefined;
   const widths = apply.options.map(cellWidth);
 
   // ✕ is always present; ←/→ appear only on a multi-page menu. Reserve arrow
@@ -243,30 +262,44 @@ export function renderPicker(
     { verb: VERB_SET_STATE, args: [sessionId, ...closeFlat] },
   ]);
   // [LAW:one-source-of-truth] A set-option apply folds its closeOnPick pairs
-  // into ONE set-state batch (setState is variadic — see daemon/verbs). A
-  // persist-option apply cannot: setConfig takes exactly one (key, value), so
-  // its close pairs (always SessionState — open/page live there regardless of
-  // the apply's durability) ride as a SECOND effect in the same dispatch,
-  // still one atomic click via effectsUrl's array.
-  const optionUrl = (option: string): string =>
-    apply.kind === "persist-option"
-      ? effectsUrl([
-          { verb: VERB_SET_CONFIG, args: [sessionId, apply.key, option] },
-          ...(closeOnPick
-            ? [{ verb: VERB_SET_STATE, args: [sessionId, ...closeFlat] }]
-            : []),
-        ])
-      : effectsUrl([
-          {
-            verb: VERB_SET_STATE,
-            args: [
-              sessionId,
-              apply.key,
-              option,
-              ...(closeOnPick ? closeFlat : []),
-            ],
-          },
-        ]);
+  // into ONE set-state batch (setState is variadic — see daemon/verbs).
+  // persist-option and layout-op-option cannot: setConfig/apply-layout-op
+  // each take exactly one (key, value) pair, so their close pairs (always
+  // SessionState — open/page live there regardless of the apply's
+  // durability) ride as a SECOND effect in the same dispatch, still one
+  // atomic click via effectsUrl's array. layout-op-option's "value" is the
+  // ENCODED op (segment=option, anchor/relation from the compiled action),
+  // not the option verbatim — the one place this kind's write differs from
+  // persist-option's.
+  const closeEffect = closeOnPick
+    ? [{ verb: VERB_SET_STATE, args: [sessionId, ...closeFlat] }]
+    : [];
+  const optionUrl = (option: string): string => {
+    if (apply.kind === "persist-option") {
+      return effectsUrl([
+        { verb: VERB_SET_CONFIG, args: [sessionId, apply.key, option] },
+        ...closeEffect,
+      ]);
+    }
+    if (apply.kind === "layout-op-option") {
+      const op = encodeLayoutOp({
+        op: "insert",
+        segment: option,
+        anchor: apply.anchor,
+        relation: apply.relation,
+      });
+      return effectsUrl([
+        { verb: VERB_APPLY_LAYOUT_OP, args: [sessionId, apply.key, op] },
+        ...closeEffect,
+      ]);
+    }
+    return effectsUrl([
+      {
+        verb: VERB_SET_STATE,
+        args: [sessionId, apply.key, option, ...(closeOnPick ? closeFlat : [])],
+      },
+    ]);
+  };
 
   const frags: RichText[] = [linkFragment(PICKER_CLOSE, closeUrl, false)];
   if (pageIdx > 0) {