@promptctl/cc-candybar 1.28.0 → 1.30.0

package/src/config/loader/actions.ts

@@ -324,6 +324,25 @@ const CYCLE_FIELDS_SET: FieldSpecMap<{ cycle: readonly string[] }> = {
 const CYCLE_FIELDS_PERSIST: FieldSpecMap<{ cycle: readonly string[] }> = {
   cycle: cycleSpec("persist"),
 };
+// [LAW:one-type-per-behavior] brandon-layout-edit-2gc.1's two structural-edit
+// arms — PERSIST-only (see action.ts's ActionDecl doc comment for why there
+// is no `set` twin). Each field reuses layoutNameSpec: a segment/anchor name
+// must be non-empty and free of both `/` (the click wire's own segment
+// delimiter) and `:` (layout-ops.ts's op-token delimiter) — the SAME
+// wire-safety diligence slashFreeString already applies to `to`/`cycle`
+// members, one forbidden character wider.
+const REMOVE_SEGMENT_FIELDS: FieldSpecMap<{ removeSegment: string }> = {
+  removeSegment: layoutNameSpec("removeSegment"),
+};
+const INSERT_SEGMENT_FIELDS: FieldSpecMap<{
+  insertSegment: string;
+  anchor: string;
+  relation: "before" | "after";
+}> = {
+  insertSegment: layoutNameSpec("insertSegment"),
+  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
@@ -418,16 +437,49 @@ const SET_ARMS: readonly ValueSourceArm[] = [
 
 // [LAW:one-type-per-behavior] `persist` mirrors `set` minus the `int` arm — a
 // page cursor is a UI-only paging concept with no meaning as a persisted
-// config default (see action.ts's ActionDecl comment).
+// config default (see action.ts's ActionDecl comment). `removeSegment`/
+// `insertSegment` are ADDITIONAL persist-only arms with no `set` counterpart.
 const PERSIST_ARMS: readonly ValueSourceArm[] = [
   valueSourceArm("persist", TO_FIELDS_PERSIST),
   valueSourceArm("persist", FROM_FIELDS_PERSIST),
   valueSourceArm("persist", BOUNDED_FIELDS, minLessThanMax, byNonZero),
   valueSourceArm("persist", CYCLE_FIELDS_PERSIST),
+  valueSourceArm("persist", REMOVE_SEGMENT_FIELDS),
+  valueSourceArm("persist", INSERT_SEGMENT_FIELDS),
 ];
 
-const VALUE_SOURCE_MESSAGE = (discriminator: "set" | "persist") =>
-  `a ${discriminator} action declares exactly one value source: "to" (a literal value), "from" (an option domain — a registered domain name like "themes"/"styles"/"looks", or an inline array of literal values), "min"/"max"/"by" (a bounded step)${discriminator === "set" ? `, "int" (an unbounded integer cursor)` : ""}, or "cycle" (an enumerated domain stepped in order)`;
+// [LAW:one-source-of-truth] The clause list, not the joined string, is the
+// data that varies per discriminator — the "or" belongs on the LAST clause
+// only, and which clause is last differs between `set` (ends at cycle) and
+// `persist` (ends at insertSegment), so building a list and joining it is
+// what keeps that placement correct without a second copy of the sentence.
+function valueSourceClauses(discriminator: "set" | "persist"): string[] {
+  const clauses = [
+    `"to" (a literal value)`,
+    `"from" (an option domain — a registered domain name like "themes"/"styles"/"looks", or an inline array of literal values)`,
+    `"min"/"max"/"by" (a bounded step)`,
+  ];
+  if (discriminator === "set")
+    clauses.push(`"int" (an unbounded integer cursor)`);
+  clauses.push(`"cycle" (an enumerated domain stepped in order)`);
+  if (discriminator === "persist") {
+    clauses.push(
+      `"removeSegment" (remove a named segment from the layout)`,
+      `"insertSegment"/"anchor"/"relation" (insert a named segment before/after an existing one)`,
+    );
+  }
+  return clauses;
+}
+
+function VALUE_SOURCE_MESSAGE(discriminator: "set" | "persist"): string {
+  const clauses = valueSourceClauses(discriminator);
+  const last = clauses[clauses.length - 1]!;
+  const list =
+    clauses.length === 1
+      ? last
+      : `${clauses.slice(0, -1).join(", ")}, or ${last}`;
+  return `a ${discriminator} action declares exactly one value source: ${list}`;
+}
 
 // [LAW:dataflow-not-control-flow] The set/persist sub-union eliminator:
 // validate the shared discriminator key, count which value sources are
@@ -681,6 +733,61 @@ function intMarkerSpec(): FieldSpec<true> {
   };
 }
 
+// [LAW:one-source-of-truth] A layout op's segment-name field (removeSegment /
+// insertSegment / anchor) is non-empty and free of BOTH wire-structural
+// characters: `/` (the click wire's own multi-arg segment delimiter, the
+// same restriction slashFreeString already enforces for `to`/`cycle`) and
+// `:` (layout-ops.ts's op-token delimiter — a name containing it would make
+// encodeLayoutOp's output ambiguous to decode). One spec, three callsites,
+// so the two-character restriction can't drift between them.
+function layoutNameSpec(field: string): FieldSpec<string> {
+  return {
+    required: true,
+    json: { type: "string" },
+    parse: (ctx, path, f, raw) => {
+      const v = requireString(ctx, path, raw, f);
+      if (v === null) return undefined;
+      const at = `${path}.${f}`;
+      if (v === "") {
+        issue(ctx, at, `${field} must be non-empty (a segment name)`);
+        return undefined;
+      }
+      if (v.includes("/") || v.includes(":")) {
+        issue(
+          ctx,
+          at,
+          `${field} "${v}" contains "/" or ":" — segment names in a layout op must be free of both (the click wire's own delimiter and layout-ops.ts's op-token delimiter)`,
+        );
+        return undefined;
+      }
+      return v;
+    },
+  };
+}
+
+// [LAW:types-are-the-program] `relation` is a closed two-value enum, not a
+// free string — a typo (`"befor"`) is a load error, never a click-time
+// surprise. Mirrors intMarkerSpec's "one legal literal" shape, widened to
+// two.
+function relationSpec(): FieldSpec<"before" | "after"> {
+  return {
+    required: true,
+    json: { enum: ["before", "after"] },
+    parse: (ctx, path, field, raw) => {
+      const v = raw[field];
+      if (v !== "before" && v !== "after") {
+        issue(
+          ctx,
+          `${path}.${field}`,
+          `relation must be "before" or "after", got ${describeValue(v)}`,
+        );
+        return undefined;
+      }
+      return v;
+    },
+  };
+}
+
 // [LAW:types-are-the-program] A required integer field — the field key (min / max
 // / by) comes from the map, the message names it. A non-integer or absent value
 // reports and fails the arm.

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

@@ -17,6 +17,7 @@ import {
   actionBindsPersist,
   actionBindsReset,
   actionBindsSet,
+  type ActionDecl,
 } from "../action.js";
 import {
   knownOptionDomainNames,
@@ -24,6 +25,7 @@ import {
 } from "../option-domain.js";
 import { listGlobalsFieldNames } from "./globals.js";
 import { parsePersistTarget } from "./persist-target.js";
+import { presetNames } from "../presets.js";
 import { findKeyLine } from "./diagnostics.js";
 import { isPlainObject, type ValidateCtx } from "./validate-core.js";
 import {
@@ -116,11 +118,23 @@ export function validateCrossReferences(
     if (target === null) {
       ctx.issues.push({
         path: `actions.${name}.${discriminator}`,
-        message: `actions.${name}: "${key}" is not a config globals field (have: ${listGlobalsFieldNames().join(", ")}) or a "segments.<name>.palette" target`,
+        message: `actions.${name}: "${key}" is not a config globals field (have: ${listGlobalsFieldNames().join(", ")}), a "segments.<name>.palette" target, or a "presets.<name>.rootOps" target`,
         line: findKeyLine(ctx.source, ["actions", name, discriminator]),
       });
       continue;
     }
+    if (target.scope === "preset-root-ops") {
+      checkPresetRootOpsTarget(
+        ctx,
+        cfg,
+        name,
+        discriminator,
+        key,
+        target.preset,
+        a,
+      );
+      continue;
+    }
     if (target.scope !== "segment-palette") continue;
     if (!Object.prototype.hasOwnProperty.call(cfg.segments, target.segment)) {
       ctx.issues.push({
@@ -345,6 +359,76 @@ export function validateCrossReferences(
   }
 }
 
+// [LAW:no-silent-failure] brandon-layout-edit-2gc.1's structural-edit target
+// check, one arm of the persist/reset key cross-ref above. Three things must
+// hold at load time, same spirit as the segment-palette check just above it:
+// the preset name must be real (mirrors globals.preset's check earlier in
+// this function), the arm pairing must make sense for this scope (only
+// removeSegment/insertSegment address a tree — a `to`/`from`/cycle/bounded
+// literal has no meaning as "the current op log"), and every segment name
+// the op names must be declared.
+function checkPresetRootOpsTarget(
+  ctx: ValidateCtx,
+  cfg: DslConfig,
+  name: string,
+  discriminator: "persist" | "reset",
+  key: string,
+  presetName: string,
+  a: ActionDecl,
+): void {
+  const at = `actions.${name}.${discriminator}`;
+  const line = findKeyLine(ctx.source, ["actions", name, discriminator]);
+  if (!presetNames(cfg.presets).includes(presetName)) {
+    ctx.issues.push({
+      path: at,
+      message: `actions.${name}: "${key}" names preset "${presetName}" which is not declared (have: ${presetNames(cfg.presets).join(", ")})`,
+      line,
+    });
+    return;
+  }
+  // [LAW:one-source-of-truth] `reset` has no value-source arm to check — its
+  // shape is a bare `{ reset: key }` — so the arm-pairing/segment checks
+  // below are `persist`-only, exactly as the "reset" action's clean-slate
+  // undo is meant to be: it clears the whole op log regardless of what wrote
+  // it.
+  if (discriminator === "reset") return;
+  const hasRemove = "removeSegment" in a;
+  const hasInsert = "insertSegment" in a;
+  if (!hasRemove && !hasInsert) {
+    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)`,
+      line,
+    });
+    return;
+  }
+  const missing = (segName: string): boolean =>
+    !Object.prototype.hasOwnProperty.call(cfg.segments, segName);
+  if (hasRemove && "removeSegment" in a && missing(a.removeSegment)) {
+    ctx.issues.push({
+      path: at,
+      message: `actions.${name}: removeSegment "${a.removeSegment}" is not a declared segment (have: ${Object.keys(cfg.segments).join(", ")})`,
+      line,
+    });
+  }
+  if (hasInsert && "insertSegment" in a) {
+    if (missing(a.insertSegment)) {
+      ctx.issues.push({
+        path: at,
+        message: `actions.${name}: insertSegment "${a.insertSegment}" is not a declared segment (have: ${Object.keys(cfg.segments).join(", ")})`,
+        line,
+      });
+    }
+    if (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 {
   for (const v of Object.values(cfg.variables)) {
     if (v.kind === "state") return true;

package/src/config/loader/persist-target.ts

@@ -16,17 +16,33 @@ import { isGlobalsField } from "./globals.js";
 
 export type PersistTarget =
   | { readonly scope: "globals"; readonly field: keyof Globals }
-  | { readonly scope: "segment-palette"; readonly segment: string };
+  | { readonly scope: "segment-palette"; readonly segment: string }
+  // [LAW:one-source-of-truth] brandon-layout-edit-2gc.1's structural-edit
+  // target — the accumulated op LOG for one preset's root (see
+  // src/config/layout-ops.ts), never the tree itself: a scalar-shaped value
+  // (a JSON-encoded string[] of op tokens) so it rides the SAME flat-dict
+  // overrides file with no shape change to that store's core writer.
+  | { readonly scope: "preset-root-ops"; readonly preset: string };
 
 // [LAW:locality-or-seam] `segments.<name>.palette` reuses the SAME dotted
 // namespacing SegmentDecl.vars already uses for segment-local variables
 // (`<segment>.<var>`, declared in src/dsl/render.ts) — one idiom for "a name
 // scoped under a segment", not a bespoke second syntax invented for persist
-// targets alone.
+// targets alone. `presets.<name>.rootOps` mirrors it one level up (a name
+// scoped under a preset) — deliberately spelled `rootOps`, not `root`, so it
+// never reads as the same string as presetRoot()'s load-time diagnostic path
+// `presets.<name>.root` (src/config/presets.ts), a different namespace this
+// key must never be confused with.
 const SEGMENT_PALETTE_KEY = /^segments\.([^.]+)\.palette$/;
+const PRESET_ROOT_OPS_KEY = /^presets\.([^.]+)\.rootOps$/;
 
 export function parsePersistTarget(key: string): PersistTarget | null {
   if (isGlobalsField(key)) return { scope: "globals", field: key };
-  const match = SEGMENT_PALETTE_KEY.exec(key);
-  return match ? { scope: "segment-palette", segment: match[1]! } : null;
+  const segmentMatch = SEGMENT_PALETTE_KEY.exec(key);
+  if (segmentMatch)
+    return { scope: "segment-palette", segment: segmentMatch[1]! };
+  const presetMatch = PRESET_ROOT_OPS_KEY.exec(key);
+  return presetMatch
+    ? { scope: "preset-root-ops", preset: presetMatch[1]! }
+    : null;
 }

package/src/config/presets.ts

@@ -37,6 +37,7 @@ import type {
   PresetDecl,
 } from "./dsl-types.js";
 import { effectiveMemberName } from "../themes/policy.js";
+import { applyLayoutOps, decodeLayoutOp } from "./layout-ops.js";
 
 // [LAW:one-source-of-truth] The floor preset's name, spelled once. `looks` has
 // `"none"` (the identity adaptation); presets have `"default"` (the identity
@@ -186,3 +187,44 @@ export function sanitizePersistedPresetOverride(
   delete rest.preset;
   return rest;
 }
+
+// [LAW:one-source-of-truth] brandon-layout-edit-2gc.1's replay step — the
+// SAME "patch an already-merged config" shape applySegmentPaletteOverrides
+// (src/config/loader/merge.ts) uses one field over, run at the SAME point in
+// RenderCache.buildState (after the globals/segment-palette overrides, before
+// validateConfig): for every preset with an accumulated op log, resolve its
+// CURRENT root the normal way (presetRoot — bundled/user root, or the
+// preset's own declared fragment) and replay the ops on top, writing the
+// result back as that preset's `root`. Every later reader (presetRoot,
+// registerDslConfig's per-preset compile, validateConfig's cross-ref walk)
+// sees the patched tree as if it had been authored that way — no second
+// resolution path [LAW:locality-or-seam].
+//
+// [LAW:no-silent-failure] exception: an op whose target/anchor names a
+// segment absent from the CURRENT tree is a no-op (layout-ops.ts's own
+// documented policy) — a validated action can only ever name a segment the
+// config declares at the time it was clicked, so a miss here only happens
+// after a LATER edit (a config change, or an earlier op in the same list)
+// already removed it. A malformed individual token (decodeLayoutOp -> null;
+// can only arise from hand-edited or previous-version state, never from this
+// process's own encodeLayoutOp) is filtered the same way, never applied.
+export function applyPresetRootOpsOverrides(
+  config: DslConfig,
+  presetRootOps: Readonly<Record<string, readonly string[]>>,
+): DslConfig {
+  const entries = Object.entries(presetRootOps).filter(
+    ([, tokens]) => tokens.length > 0,
+  );
+  if (entries.length === 0) return config;
+  const presets: Record<string, PresetDecl> = { ...config.presets };
+  for (const [name, tokens] of entries) {
+    const ops = tokens.map(decodeLayoutOp).filter((op) => op !== null);
+    if (ops.length === 0) continue;
+    const { node } = presetRoot(config, name);
+    presets[name] = {
+      ...presetByName(config.presets, name),
+      root: applyLayoutOps(node, ops),
+    };
+  }
+  return { ...config, presets };
+}

package/src/daemon/cache/render.ts

@@ -25,7 +25,10 @@ import {
 } from "../verbs/config-validators.js";
 import { loadOverrides } from "../config-overrides-store.js";
 import { configOverridesPath } from "../paths.js";
-import { sanitizePersistedPresetOverride } from "../../config/presets.js";
+import {
+  applyPresetRootOpsOverrides,
+  sanitizePersistedPresetOverride,
+} from "../../config/presets.js";
 import { VariableStore } from "../../var-system/store.js";
 import { SourceRegistry } from "../../var-system/sources.js";
 import type { GitDataProvider } from "./git.js";
@@ -324,8 +327,20 @@ export class RenderCache {
       withGlobalsOverrides,
       overrides.segmentPalette,
     );
-    const config = validateConfig(
+    // [LAW:one-source-of-truth] brandon-layout-edit-2gc.1's replay step —
+    // the SAME "patch an already-merged config" cascade as the segment-
+    // palette overlay above, one field over (a preset's `root` instead of a
+    // segment's `palette`). Runs last so validateConfig's cross-ref walk
+    // proves the OPS-PATCHED tree, not the pre-edit one — a structural edit
+    // that referenced a segment removed by a later config change is caught
+    // exactly like a hand-authored preset root naming the same segment would
+    // be.
+    const withPresetRootOps = applyPresetRootOpsOverrides(
       withOverrides,
+      overrides.presetRootOps,
+    );
+    const config = validateConfig(
+      withPresetRootOps,
       resolvedPath ?? "<default>",
       source,
     );

package/src/daemon/config-overrides-store.ts

@@ -100,7 +100,17 @@ export function coercePersistValue(
       `coercePersistValue: "${key}" is not a valid persist target`,
     );
   }
-  if (target.scope === "segment-palette") return raw;
+  // [LAW:one-type-per-behavior] Both non-globals scopes are always a NAME/
+  // TOKEN string — segment-palette's value is a palette name, preset-root-ops'
+  // is one op token appended by the daemon's apply-layout-op verb handler
+  // (never a bare `persist` write — see verbs/index.ts). Neither has a
+  // GLOBALS_FIELD_KIND row because neither is a Globals field.
+  if (
+    target.scope === "segment-palette" ||
+    target.scope === "preset-root-ops"
+  ) {
+    return raw;
+  }
   const kind = GLOBALS_FIELD_KIND[target.field];
   if (kind === "string") return raw;
   if (kind === "number") {
@@ -136,9 +146,7 @@ function isValidOverrides(
     const target = parsePersistTarget(key);
     if (target === null) return false;
     const kind =
-      target.scope === "segment-palette"
-        ? "string"
-        : GLOBALS_FIELD_KIND[target.field];
+      target.scope === "globals" ? GLOBALS_FIELD_KIND[target.field] : "string";
     if (kind === "number" && typeof v !== "number") return false;
     if (kind === "boolean" && typeof v !== "boolean") return false;
     if (kind === "string" && typeof v !== "string") return false;
@@ -237,6 +245,46 @@ function projectSegmentPaletteOverrides(
   return out;
 }
 
+// [LAW:one-source-of-truth] The preset-root-ops-scoped VIEW of the SAME raw
+// dict — preset name -> the accumulated op-token LIST (brandon-layout-edit-
+// 2gc.1's structural-edit log; see src/config/layout-ops.ts). This is a
+// SHAPE check only (well-formed JSON array of strings) — decoding each
+// token into a typed LayoutOp, and applying the ops to a tree, is presets.ts's
+// job, not this storage-layer module's [LAW:decomposition]. A stored value
+// that isn't a JSON array of strings drops for THAT preset only (a warn log,
+// never a crash of the whole overrides file) — the identical "the world
+// moved on since this was written" recovery projectSegmentPaletteOverrides
+// already gets, one level narrower.
+function projectPresetRootOpsOverrides(
+  raw: Readonly<Record<string, string | number | boolean>>,
+  logger: DaemonLogger,
+): Readonly<Record<string, readonly string[]>> {
+  const out: Record<string, readonly string[]> = Object.create(null) as Record<
+    string,
+    readonly string[]
+  >;
+  for (const [key, value] of Object.entries(raw)) {
+    const target = parsePersistTarget(key);
+    if (target?.scope !== "preset-root-ops" || typeof value !== "string") {
+      continue;
+    }
+    try {
+      const parsed: unknown = JSON.parse(value);
+      if (Array.isArray(parsed) && parsed.every((t) => typeof t === "string")) {
+        out[target.preset] = parsed;
+        continue;
+      }
+    } catch {
+      // fall through to the warn below
+    }
+    logger(
+      "warn",
+      `config-overrides: "${key}" is not a valid op-token list, dropping`,
+    );
+  }
+  return out;
+}
+
 export function loadConfigOverrides(
   filePath: string,
   logger: DaemonLogger = quietLogger,
@@ -251,14 +299,15 @@ export function loadSegmentPaletteOverrides(
   return projectSegmentPaletteOverrides(loadRawOverrides(filePath, logger));
 }
 
-// [LAW:carrying-cost] RenderCache wants BOTH views on every reload
-// (buildState merges globals overrides, then overlays segment-palette
-// overrides) — calling loadConfigOverrides + loadSegmentPaletteOverrides
-// back to back would read, parse, and shape-validate the same tiny file
-// twice per reload for no reason. One read, two projections.
+// [LAW:carrying-cost] RenderCache wants ALL THREE views on every reload
+// (buildState merges globals overrides, overlays segment-palette overrides,
+// then replays preset-root-ops overrides) — calling the scoped loaders back
+// to back would read, parse, and shape-validate the same tiny file three
+// times per reload for no reason. One read, three projections.
 export interface Overrides {
   readonly globals: Partial<Globals>;
   readonly segmentPalette: Readonly<Record<string, string>>;
+  readonly presetRootOps: Readonly<Record<string, readonly string[]>>;
 }
 
 export function loadOverrides(
@@ -269,6 +318,7 @@ export function loadOverrides(
   return {
     globals: projectGlobalsOverrides(raw),
     segmentPalette: projectSegmentPaletteOverrides(raw),
+    presetRootOps: projectPresetRootOpsOverrides(raw, logger),
   };
 }
 

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

@@ -17,6 +17,7 @@ import {
 } from "../../config/option-domain";
 import type { DslConfig } from "../../config/dsl-types";
 import { isGlobalsField } from "../config-overrides-store";
+import { encodeLayoutOp } from "../../config/layout-ops";
 import {
   clampSeed,
   createValidatorRegistry,
@@ -73,6 +74,43 @@ function actionKeySpecs(
   if ("cycle" in a) {
     return [{ key: a.persist, spec: { kind: "allow-list", allowed: a.cycle } }];
   }
+  // [LAW:single-enforcer] brandon-layout-edit-2gc.1's structural-edit arms:
+  // the op is fully literal at config-author time (removeSegment's target,
+  // insertSegment's segment/anchor/relation), so — exactly like a literal
+  // `to` — there is exactly ONE legal value this declared action can ever
+  // request: its own encoded op token. Multiple layout actions targeting the
+  // same "presets.<name>.rootOps" key each contribute one allow-list member,
+  // unioned by mergeContributions below, same as multiple `to` actions on
+  // one key already do.
+  if ("removeSegment" in a) {
+    return [
+      {
+        key: a.persist,
+        spec: {
+          kind: "allow-list",
+          allowed: [encodeLayoutOp({ op: "remove", target: a.removeSegment })],
+        },
+      },
+    ];
+  }
+  if ("insertSegment" in a) {
+    return [
+      {
+        key: a.persist,
+        spec: {
+          kind: "allow-list",
+          allowed: [
+            encodeLayoutOp({
+              op: "insert",
+              segment: a.insertSegment,
+              anchor: a.anchor,
+              relation: a.relation,
+            }),
+          ],
+        },
+      },
+    ];
+  }
   return [
     {
       key: a.persist,

package/src/daemon/verbs/index.ts

@@ -36,12 +36,15 @@ import {
   coercePersistValue,
   isGlobalsField,
   loadConfigOverrides,
+  loadOverrides,
   writeConfigOverride,
 } from "../config-overrides-store";
 import { configOverridesPath } from "../paths";
+import { parsePersistTarget } from "../../config/loader/persist-target";
 import {
   decodeSegments,
   parseEffects,
+  VERB_APPLY_LAYOUT_OP,
   VERB_COPY,
   VERB_DISPATCH,
   VERB_OPEN_VSCODE,
@@ -444,6 +447,48 @@ const resetConfig: VerbHandler = (value, ctx) => {
   ctx.dlog("info", `reset-config: ${key} (session=${sid})`);
 };
 
+// [LAW:one-source-of-truth] brandon-layout-edit-2gc.1's structural-edit
+// write: a THIRD config-overrides write shape beside setConfig's overwrite
+// and stepConfig's numeric read-modify-write — read the current op-token
+// list at `key`, append the validated op, write the whole list back. Gated
+// by the SAME allow-list machinery setConfig uses (validateConfigWrite,
+// derived from a config's declared removeSegment/insertSegment actions) —
+// an op token no action declares is a loud BAD_REQUEST, never silently
+// appended. `key` must resolve to the preset-root-ops scope specifically
+// (never a globals/segment-palette key smuggled in through this verb) —
+// checked here rather than trusted from the gate, since the gate only
+// proves the VALUE is allowed for that key, not that the key's SCOPE
+// matches this verb's read-modify-write shape.
+const applyLayoutOp: VerbHandler = (rawValue, ctx) => {
+  const [sessionId = "", key = "", opToken = ""] = decodeWire(() =>
+    decodeSegments(rawValue),
+  );
+  const sid = requireSessionId(sessionId);
+  if (!key) {
+    throw new BadVerbArgs(
+      `apply-layout-op: <key>/<op> is required (have: ${listConfigKeys().join(", ")})`,
+    );
+  }
+  const result = validateConfigWrite(key, opToken);
+  if (!result.ok) throw new BadVerbArgs(`apply-layout-op: ${result.reason}`);
+  const target = parsePersistTarget(key);
+  if (target === null || target.scope !== "preset-root-ops") {
+    throw new BadVerbArgs(
+      `apply-layout-op: "${key}" is not a "presets.<name>.rootOps" target`,
+    );
+  }
+  const existing =
+    loadOverrides(configOverridesPath(), ctx.dlog).presetRootOps[
+      target.preset
+    ] ?? [];
+  const next = JSON.stringify([...existing, result.value]);
+  writeConfigOverride(configOverridesPath(), key, next, ctx.dlog);
+  ctx.dlog(
+    "info",
+    `apply-layout-op: ${key} += ${result.value} (session=${sid})`,
+  );
+};
+
 // ─── Registry ───────────────────────────────────────────────────────────────
 
 // [LAW:one-source-of-truth] The LEAF verbs — every click effect that does real
@@ -505,6 +550,7 @@ const LEAF_VERBS = new Map<string, VerbHandler>([
   [VERB_SET_CONFIG, setConfig],
   [VERB_STEP_CONFIG, stepConfig],
   [VERB_RESET_CONFIG, resetConfig],
+  [VERB_APPLY_LAYOUT_OP, applyLayoutOp],
   [VERB_SHOW_CONFIG_ERROR, showConfigError],
   [VERB_SHOW_CONFIG_WARNING, showConfigWarning],
   [VERB_TOOLBAR_TOGGLE, toolbarToggle],
@@ -536,9 +582,9 @@ const dispatch: VerbHandler = (rawValue, ctx) => {
   let sessionId: string | null = null;
   for (const { verb, value } of parseEffects(rawValue)) {
     // Extract session ID from the first session-bearing effect for error display.
-    // set-state, step-state, set-config, step-config, reset-config, and
-    // toolbar-toggle all carry the session id as their first segment, so a
-    // failing step surfaces in the bar like any other.
+    // set-state, step-state, set-config, step-config, reset-config,
+    // apply-layout-op, and toolbar-toggle all carry the session id as their
+    // first segment, so a failing step surfaces in the bar like any other.
     if (
       !sessionId &&
       (verb === VERB_SET_STATE ||
@@ -546,6 +592,7 @@ const dispatch: VerbHandler = (rawValue, ctx) => {
         verb === VERB_SET_CONFIG ||
         verb === VERB_STEP_CONFIG ||
         verb === VERB_RESET_CONFIG ||
+        verb === VERB_APPLY_LAYOUT_OP ||
         verb === VERB_TOOLBAR_TOGGLE)
     ) {
       const parts = decodeSegments(value);