@promptctl/cc-candybar 1.26.0 → 1.27.0

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

@@ -10,9 +10,20 @@ import {
   hasCacheField,
   walkNodes,
   type DslConfig,
+  type LayoutNode,
   type VariableDecl,
 } from "../dsl-types.js";
-import { actionBindsSet } from "../action.js";
+import {
+  actionBindsPersist,
+  actionBindsReset,
+  actionBindsSet,
+} from "../action.js";
+import {
+  knownOptionDomainNames,
+  perConfigDomainsFor,
+} from "../option-domain.js";
+import { listGlobalsFieldNames } from "./globals.js";
+import { parsePersistTarget } from "./persist-target.js";
 import { findKeyLine } from "./diagnostics.js";
 import { isPlainObject, type ValidateCtx } from "./validate-core.js";
 import {
@@ -50,6 +61,89 @@ export function validateCrossReferences(
       line: findKeyLine(ctx.source, ["globals", "look"]),
     });
   }
+  // [LAW:one-type-per-behavior] globals.preset is globals.look one dimension
+  // over — the same post-merge membership check against the same kind of
+  // per-config block, for the same reason (a user's default may name a
+  // bundled preset). A typo'd DEFAULT is a load error even though a stale
+  // SESSION pick collapses silently to the floor: the config file is authored
+  // and re-readable, so naming a preset that does not exist is a mistake we can
+  // point at; a session pick is a click made against a config that has since
+  // changed, which is not [LAW:no-silent-failure].
+  if (
+    cfg.globals.preset !== undefined &&
+    !Object.prototype.hasOwnProperty.call(cfg.presets, cfg.globals.preset)
+  ) {
+    ctx.issues.push({
+      path: "globals.preset",
+      message: `globals.preset "${cfg.globals.preset}" does not match any declared preset (have: ${Object.keys(cfg.presets).join(", ")})`,
+      line: findKeyLine(ctx.source, ["globals", "preset"]),
+    });
+  }
+  // [LAW:one-source-of-truth] A `set … from` NAME must resolve — checked
+  // against this config's per-config domains ("looks", the merged looks:
+  // block) plus the global registry (themes/styles, and any future
+  // registration), the SAME set resolveOptionDomain consults at render and
+  // gate-derivation time. An inline array `from` is its own domain — nothing
+  // to resolve. Runs post-merge for the same reason globals.look does above:
+  // "looks" isn't fully known until the user's looks: block has merged onto
+  // the bundled stdlib.
+  const optionDomains = perConfigDomainsFor(cfg);
+  for (const [name, a] of Object.entries(cfg.actions)) {
+    if (!("set" in a) || !("from" in a) || typeof a.from !== "string") continue;
+    if (!knownOptionDomainNames(optionDomains).includes(a.from)) {
+      ctx.issues.push({
+        path: `actions.${name}.from`,
+        message: `actions.${name} from: references unknown option domain "${a.from}" (have: ${knownOptionDomainNames(optionDomains).join(", ")})`,
+        line: findKeyLine(ctx.source, ["actions", name, "from"]),
+      });
+    }
+  }
+  // [LAW:no-silent-failure] A `persist`/`reset` target must name a REAL
+  // Globals field OR a declared segment's `palette` (candybar-config-engine-
+  // 71o.6 — `segments.<name>.palette`, parsed by the one shared authority in
+  // persist-target.ts) — the loader's structural pass (loader/actions.ts)
+  // only proves the key is non-empty/slash-free, the same shape a `set` key
+  // needs for the wire, but a persist/reset key additionally has to land
+  // somewhere real. Catching a typo (`persist: "pallete"`) or a dangling
+  // segment name here turns a confusing click-time "registration invariant
+  // broken" error into a clear load-time one naming the actual allowed
+  // targets — the same species of fix as the `from` domain check just above.
+  for (const [name, a] of Object.entries(cfg.actions)) {
+    const key = "persist" in a ? a.persist : "reset" in a ? a.reset : null;
+    if (key === null) continue;
+    const discriminator = "persist" in a ? "persist" : "reset";
+    const target = parsePersistTarget(key);
+    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`,
+        line: findKeyLine(ctx.source, ["actions", name, discriminator]),
+      });
+      continue;
+    }
+    if (target.scope !== "segment-palette") continue;
+    if (!Object.prototype.hasOwnProperty.call(cfg.segments, target.segment)) {
+      ctx.issues.push({
+        path: `actions.${name}.${discriminator}`,
+        message: `actions.${name}: "${key}" names segment "${target.segment}" which is not declared (have segments: ${Object.keys(cfg.segments).join(", ")})`,
+        line: findKeyLine(ctx.source, ["actions", name, discriminator]),
+      });
+      continue;
+    }
+    // [LAW:types-are-the-program] A palette is a NAME, not a number — a
+    // bounded stepper (`min`/`max`/`by`) has no meaning over it, unlike a
+    // Globals field where nothing today enforces value/field-kind agreement
+    // either way. Rejecting it here (rather than tolerating a numeric-string
+    // palette name that only fails later at `paletteForThemeName`) keeps
+    // the failure at load time, next to the typo it actually is.
+    if ("min" in a) {
+      ctx.issues.push({
+        path: `actions.${name}.${discriminator}`,
+        message: `actions.${name}: "${key}" is a segment palette target and cannot use a bounded stepper (min/max/by) — use "to", "from", or "cycle" instead`,
+        line: findKeyLine(ctx.source, ["actions", name, discriminator]),
+      });
+    }
+  }
   // [LAW:one-source-of-truth] THE set of resolvable variable names — a
   // faithful mirror of the runtime store's key set (declareOne in
   // src/dsl/render.ts registers globals under their bare names and segment
@@ -80,30 +174,51 @@ export function validateCrossReferences(
   // field) — would fool a raw `findKeyLine` search and misclassify the config.
   // Validation is cold-path, so reading the source's top-level keys is exact.
   // The reported path/message then point at the surface the user wrote.
-  const layoutKey = authoredLayoutKey(ctx.source);
-  const layoutLine = findKeyLine(ctx.source, [layoutKey]);
-  for (const node of walkNodes(cfg.root)) {
-    // [LAW:locality-or-seam] A node's `when` reads the global scope (bare
-    // globals + namespaced segment vars) — the same existence-check shape as a
-    // segment template, surfaced at load time.
-    if (node.when !== undefined) {
-      checkTemplateRefs(ctx, `${layoutKey}.when`, node.when, templateScope, {
-        line: layoutLine,
-      });
-    }
-    if (node.kind !== "segment") continue;
-    if (!Object.prototype.hasOwnProperty.call(cfg.segments, node.name)) {
-      const renamed = RENAMED_SEGMENTS[node.name];
-      const hint =
-        renamed !== undefined
-          ? ` (the built-in segment "${node.name}" was renamed to "${renamed}" — update this reference)`
-          : "";
-      ctx.issues.push({
-        path: layoutKey,
-        message: `${layoutKey} entry "${node.name}" does not match any declared segment${hint}`,
-        line: layoutLine,
-      });
+  //
+  // [LAW:one-type-per-behavior] A PRESET's `root` is a root: it gets this exact
+  // walk, not a reduced copy. The only thing that varies between the config's
+  // own tree and a preset's is the diagnostic key + line — data threaded in,
+  // never a second traversal that could learn a different idea of what a valid
+  // layout is. This is what makes `cc-candybar check` catch a preset staging a
+  // segment nobody declared.
+  const checkLayoutTree = (
+    root: LayoutNode,
+    layoutKey: string,
+    layoutLine: number | undefined,
+  ): void => {
+    for (const node of walkNodes(root)) {
+      // [LAW:locality-or-seam] A node's `when` reads the global scope (bare
+      // globals + namespaced segment vars) — the same existence-check shape as a
+      // segment template, surfaced at load time.
+      if (node.when !== undefined) {
+        checkTemplateRefs(ctx, `${layoutKey}.when`, node.when, templateScope, {
+          line: layoutLine,
+        });
+      }
+      if (node.kind !== "segment") continue;
+      if (!Object.prototype.hasOwnProperty.call(cfg.segments, node.name)) {
+        const renamed = RENAMED_SEGMENTS[node.name];
+        const hint =
+          renamed !== undefined
+            ? ` (the built-in segment "${node.name}" was renamed to "${renamed}" — update this reference)`
+            : "";
+        ctx.issues.push({
+          path: layoutKey,
+          message: `${layoutKey} entry "${node.name}" does not match any declared segment${hint}`,
+          line: layoutLine,
+        });
+      }
     }
+  };
+  const layoutKey = authoredLayoutKey(ctx.source);
+  checkLayoutTree(cfg.root, layoutKey, findKeyLine(ctx.source, [layoutKey]));
+  for (const [name, preset] of Object.entries(cfg.presets)) {
+    if (preset.root === undefined) continue;
+    checkLayoutTree(
+      preset.root,
+      `presets.${name}.root`,
+      findKeyLine(ctx.source, ["presets", name, "root"]),
+    );
   }
 
   // For each variable's template/cache.key, every dotted ref must exist
@@ -243,11 +358,16 @@ function hasStateKind(cfg: DslConfig): boolean {
   return false;
 }
 
-// [LAW:dataflow-not-control-flow] A config emits a set-state click — and so needs
-// session.id — when any declared action is a `set` (literal, option, or bounded).
-// copy/open actions write nothing, so they embed no session.id.
+// [LAW:dataflow-not-control-flow] A config emits a set-state, set-config, OR
+// reset-config click — and so needs session.id — when any declared action is
+// a `set` (literal/option/bounded/cycle), a `persist` (its config-overrides
+// twin), or a `reset` (persist's gated undo) — all three carry session.id on
+// the wire for click-error surfacing. copy/open actions write nothing, so
+// they embed no session.id.
 function hasActionSetAction(cfg: DslConfig): boolean {
-  return Object.values(cfg.actions).some(actionBindsSet);
+  return Object.values(cfg.actions).some(
+    (a) => actionBindsSet(a) || actionBindsPersist(a) || actionBindsReset(a),
+  );
 }
 
 function checkVarRefs(

package/src/config/loader/emit-schema.ts

@@ -17,6 +17,7 @@ import { variablesMapJson } from "./variables.js";
 import { segmentsJson } from "./segments.js";
 import { actionsJson } from "./actions.js";
 import { looksJson } from "./looks.js";
+import { presetsJson } from "./presets.js";
 import {
   layoutNodeJson,
   LAYOUT_NODE_DEF_NAME,
@@ -48,6 +49,7 @@ export function emitConfigSchema(): JsonNode {
       root: { $ref: LAYOUT_NODE_REF },
       actions: actionsJson(),
       looks: looksJson(),
+      presets: presetsJson(),
       helpers: { type: "object", additionalProperties: { type: "string" } },
     },
     definitions: {

package/src/config/loader/globals.ts

@@ -20,6 +20,7 @@ import {
   record,
   recordJson,
   type FieldSpec,
+  type FieldSpecMap,
   type JsonNode,
   type RecordSchema,
   type ValidateCtx,
@@ -53,46 +54,110 @@ const colorCompatibilitySpec: FieldSpec<ColorCompatibility> = {
   },
 };
 
+// [LAW:one-source-of-truth] THE globals field table, declared once. Both the
+// top-level `globals:` schema and the preset-scoped one below are built from
+// this map, so a field added here is automatically settable from a preset —
+// there is no second list to remember to grow.
+const GLOBALS_FIELDS: FieldSpecMap<Globals> = {
+  default_bg: optionalStringSpec(),
+  default_fg: optionalStringSpec(),
+  default_empty_value: optionalStringSpec(),
+  default_separator: optionalStringSpec(),
+  default_truncate_marker: optionalStringSpec(),
+  palette: paletteSpec(),
+  // [LAW:types-are-the-program] The config-default LOOK name. Unlike the
+  // registry-static palette set, the look domain is per-config (the merged
+  // `looks` block), so membership is a cross-ref check on the MERGED config —
+  // a user's globals.look may name a default-provided look. Shape-only here,
+  // exactly the shape/meaning split paletteSpec's schema facet keeps.
+  look: optionalStringSpec(),
+  // [LAW:types-are-the-program] The config-default PRESET name — same
+  // per-config-domain shape as `look` (membership is a post-merge cross-ref
+  // check, since a user's globals.preset may name a default-provided preset).
+  preset: optionalStringSpec(),
+  // [LAW:types-are-the-program] The strip style is a CLOSED enum (the powerline
+  // shapes the joiner can render), unlike the open-ended palette NAME — so it
+  // validates by membership and emits a JSON-Schema `enum`.
+  style: optionalEnumSpec(STRIP_STYLES),
+  autoWrap: optionalBooleanSpec(),
+  // Intra-cell spaces per side. Bounded above so a config value can never
+  // drive an unbounded `" ".repeat` allocation in the daemon
+  // [LAW:no-silent-failure] — an absurd value is a loud load error, not a
+  // silently-huge render.
+  padding: optionalIntSpec({ min: 0, max: 16 }),
+  // [LAW:types-are-the-program] Closed enum like `style`: the joiner glyph
+  // vocabularies pickJoiner can render — validates by membership, emits a
+  // JSON-Schema `enum` from the same CHARSETS literal.
+  charset: optionalEnumSpec(CHARSETS),
+  // Closed enum with a bespoke "auto" rejection — see colorCompatibilitySpec.
+  colorCompatibility: colorCompatibilitySpec,
+};
+
 const GLOBALS_SCHEMA: RecordSchema<Globals> = {
   noun: "globals key",
-  fields: {
-    default_bg: optionalStringSpec(),
-    default_fg: optionalStringSpec(),
-    default_empty_value: optionalStringSpec(),
-    default_separator: optionalStringSpec(),
-    default_truncate_marker: optionalStringSpec(),
-    palette: paletteSpec(),
-    // [LAW:types-are-the-program] The config-default LOOK name. Unlike the
-    // registry-static palette set, the look domain is per-config (the merged
-    // `looks` block), so membership is a cross-ref check on the MERGED config —
-    // a user's globals.look may name a default-provided look. Shape-only here,
-    // exactly the shape/meaning split paletteSpec's schema facet keeps.
-    look: optionalStringSpec(),
-    // [LAW:types-are-the-program] The strip style is a CLOSED enum (the powerline
-    // shapes the joiner can render), unlike the open-ended palette NAME — so it
-    // validates by membership and emits a JSON-Schema `enum`.
-    style: optionalEnumSpec(STRIP_STYLES),
-    autoWrap: optionalBooleanSpec(),
-    // Intra-cell spaces per side. Bounded above so a config value can never
-    // drive an unbounded `" ".repeat` allocation in the daemon
-    // [LAW:no-silent-failure] — an absurd value is a loud load error, not a
-    // silently-huge render.
-    padding: optionalIntSpec({ min: 0, max: 16 }),
-    // [LAW:types-are-the-program] Closed enum like `style`: the joiner glyph
-    // vocabularies pickJoiner can render — validates by membership, emits a
-    // JSON-Schema `enum` from the same CHARSETS literal.
-    charset: optionalEnumSpec(CHARSETS),
-    // Closed enum with a bespoke "auto" rejection — see colorCompatibilitySpec.
-    colorCompatibility: colorCompatibilitySpec,
+  fields: GLOBALS_FIELDS,
+};
+
+// [LAW:one-source-of-truth] A preset's `globals` may not carry `preset`: which
+// preset is active has exactly one authority (session pick over globals.preset
+// over the floor), and a preset re-selecting a preset would be a second one —
+// a cyclic second one. Same species of bespoke, migration-pointing rejection as
+// colorCompatibility's "auto" above, and for the same reason: an author who
+// writes it deserves to be told WHY, not handed a bare unknown-key message.
+const nestedPresetSpec: FieldSpec<string> = {
+  required: false,
+  // Always-fail: JSON Schema's `not: {}` matches nothing, so an editor flags
+  // the key at the same moment the validator does.
+  json: {
+    not: {},
+    description:
+      "not allowed inside a preset — a preset cannot select a preset",
   },
+  parse: (ctx, path, field, raw) => {
+    if (raw[field] !== undefined) {
+      ctx.issues.push({
+        path: `${path}.${field}`,
+        message:
+          `${path}.${field}: a preset cannot select a preset. Which preset is active is ` +
+          `resolved once, as session pick over globals.preset over "default"; a preset ` +
+          `naming another would be a second authority over that, and a cyclic one. ` +
+          `Set the default arrangement in the top-level globals.preset instead.`,
+        line: findKeyLine(ctx.source, [...path.split("."), field]),
+      });
+    }
+    return undefined;
+  },
+};
+
+// [LAW:one-source-of-truth] The preset-scoped globals schema is the SAME field
+// table with exactly one field swapped for its rejection — not a hand-listed
+// subset that a future globals field could be forgotten from.
+const PRESET_GLOBALS_SCHEMA: RecordSchema<Globals> = {
+  noun: "preset globals key",
+  fields: { ...GLOBALS_FIELDS, preset: nestedPresetSpec },
 };
 
 // An absent globals block is the empty default (no issue); a non-object is a
 // reported error that recovers to the empty default, since parseDslConfig throws
 // once any issue exists so the recovery value never renders [LAW:no-silent-failure].
-export function validateGlobals(ctx: ValidateCtx, raw: unknown): Globals {
+// `path` is explicit because the same schema validates the top-level `globals:`
+// block and a preset's nested one, and a diagnostic must name where it actually is.
+export function validateGlobals(
+  ctx: ValidateCtx,
+  path: string,
+  raw: unknown,
+): Globals {
   if (raw === undefined) return {};
-  return record(ctx, GLOBALS_SCHEMA, "globals", raw) ?? {};
+  return record(ctx, GLOBALS_SCHEMA, path, raw) ?? {};
+}
+
+// The preset-scoped twin: same interpreter, the schema that rejects `preset`.
+export function validatePresetGlobals(
+  ctx: ValidateCtx,
+  path: string,
+  raw: unknown,
+): Globals {
+  return record(ctx, PRESET_GLOBALS_SCHEMA, path, raw) ?? {};
 }
 
 // [LAW:one-source-of-truth] The schema emitter derives from the SAME declaration
@@ -101,3 +166,25 @@ export function validateGlobals(ctx: ValidateCtx, raw: unknown): Globals {
 export function globalsJson(): JsonNode {
   return recordJson(GLOBALS_SCHEMA);
 }
+
+export function presetGlobalsJson(): JsonNode {
+  return recordJson(PRESET_GLOBALS_SCHEMA);
+}
+
+// [LAW:one-source-of-truth] THE membership check for "is this a real Globals
+// field" — derived from GLOBALS_SCHEMA.fields, the same declaration
+// validateGlobals/globalsJson interpret, so a `persist`/`reset` action's
+// target key is checked against exactly the field set a hand-authored
+// `globals: {...}` block would be. Used by cross-ref.ts (candybar-config-
+// engine-71o.2) to catch a typo'd persist target at config-load time instead
+// of a confusing click-time "invariant broken" error.
+const GLOBALS_FIELD_NAMES: ReadonlySet<string> = new Set(
+  Object.keys(GLOBALS_SCHEMA.fields),
+);
+export function isGlobalsField(key: string): key is keyof Globals {
+  return GLOBALS_FIELD_NAMES.has(key);
+}
+
+export function listGlobalsFieldNames(): readonly string[] {
+  return [...GLOBALS_FIELD_NAMES];
+}

package/src/config/loader/merge.ts

@@ -13,7 +13,11 @@
 // specific consumer, a cycle. Callers who want "the bundled default" import
 // DEFAULT_DSL_CONFIG from default-dsl-config.ts and pass it explicitly.
 
-import { type DslConfig, type RawDslConfig } from "../dsl-types.js";
+import {
+  type DslConfig,
+  type RawDslConfig,
+  type SegmentDecl,
+} from "../dsl-types.js";
 
 /**
  * Merge a RawDslConfig on top of a default DslConfig. Pure function.
@@ -44,9 +48,62 @@ export function mergeWithDefault(
     // overrides one adaptation by re-declaring its name; the bundled stdlib
     // (incl. the "none" identity floor) survives every merge by construction.
     looks: { ...dflt.looks, ...(raw.looks ?? {}) },
+    // [LAW:one-source-of-truth] presets merge by name, same cascade — a user
+    // overrides one arrangement by re-declaring its name; the bundled stdlib
+    // (incl. the "default" empty-fragment floor effectivePresetName collapses
+    // to) survives every merge by construction, exactly as looks' "none" does.
+    presets: { ...dflt.presets, ...(raw.presets ?? {}) },
     // [LAW:one-source-of-truth] helpers merge by name, same cascade — a user
     // overrides one formatter helper by re-declaring its name; the rest inherit
     // from the bundled default.
     helpers: { ...dflt.helpers, ...(raw.helpers ?? {}) },
   };
 }
+
+// [LAW:one-source-of-truth] The segment-scoped half of the config-overrides
+// layer's merge (candybar-config-engine-71o.6) — the SAME "changes the
+// DEFAULT, never the hand-authored file" precedence mergeWithDefault's
+// `globals` cascade already applies, but patches ONE field (`palette`)
+// inside an already-merged segment rather than replacing the segment
+// wholesale. mergeWithDefault's `segments` cascade is deliberately per-name
+// WHOLESALE replacement (a user overriding a segment restates it in full,
+// same as any other by-name merge in this file) — routing a one-field
+// override through that cascade would silently drop every other field the
+// segment declares (template, bg, fg, when, vars...). This runs AFTER
+// mergeWithDefault, directly against the already-merged config, so it never
+// fights that cascade; it is its own, later, narrower merge step.
+//
+// [LAW:no-silent-failure] exception: a stale override naming a segment the
+// config no longer declares is not a load-time error — the CONFIG, not the
+// override, is the source of truth for which segments exist. Skipping it is
+// a no-op, not a swallowed failure: a fresh `persist` write can only ever
+// name a segment the config declares (cross-ref checks that at load time),
+// so a dangling entry here only happens after a later config edit removed
+// the segment, and there is nothing left for the override to apply to.
+//
+// [LAW:no-defensive-null-guards] exception: `Object.assign(Object.create(null),
+// ...)` instead of `{ ...config.segments }` — the SAME null-prototype hygiene
+// as the config-overrides-store.ts accumulators above (segment names come
+// from user config and this loop WRITES via bracket assignment, `segments[name]
+// = ...`, not a pure spread). Pure object spread never risks this (it defines
+// every key directly, never invoking an inherited setter), but a stale
+// override naming a since-removed segment `__proto__` hits exactly the
+// "no own property yet, so the read returns the inherited accessor and the
+// write invokes its setter" case a plain accumulator does not guard against.
+export function applySegmentPaletteOverrides(
+  config: DslConfig,
+  overrides: Readonly<Record<string, string>>,
+): DslConfig {
+  const entries = Object.entries(overrides);
+  if (entries.length === 0) return config;
+  const segments: Record<string, SegmentDecl> = Object.assign(
+    Object.create(null) as Record<string, SegmentDecl>,
+    config.segments,
+  );
+  for (const [name, palette] of entries) {
+    const seg = segments[name];
+    if (seg === undefined) continue;
+    segments[name] = { ...seg, palette };
+  }
+  return { ...config, segments };
+}

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

@@ -0,0 +1,32 @@
+// [LAW:one-source-of-truth] THE parser for what a `persist`/`reset` action's
+// key STRING may legally name — the single place a key is classified as a
+// Globals field (candybar-config-engine-71o.3's scope) or a per-segment
+// palette override (candybar-config-engine-71o.6's scope), so cross-ref
+// validation (load time), the config-overrides store (write/read), and the
+// daemon's write-gate all classify a key through ONE authority instead of
+// three independently-drifting `isGlobalsField` checks.
+//
+// [LAW:types-are-the-program] A discriminated union, not a bag of optional
+// fields: every legal key shape is representable, every illegal one
+// collapses to `null` at exactly this one boundary — no downstream consumer
+// re-parses the string itself.
+
+import type { Globals } from "../dsl-types.js";
+import { isGlobalsField } from "./globals.js";
+
+export type PersistTarget =
+  | { readonly scope: "globals"; readonly field: keyof Globals }
+  | { readonly scope: "segment-palette"; readonly segment: 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.
+const SEGMENT_PALETTE_KEY = /^segments\.([^.]+)\.palette$/;
+
+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;
+}

package/src/config/loader/presets.ts

@@ -0,0 +1,107 @@
+// [LAW:types-are-the-program] The `presets` schema: each preset is a named
+// config FRAGMENT — an alternative arrangement of the bar the user switches to
+// — capped at exactly the two sections a render RESOLVES (`root`, `globals`)
+// and closed to the sections the daemon REGISTERS once per process
+// (`variables`, `segments`, `actions`, `helpers`). The reasoning for that cap
+// lives on PresetDecl in dsl-types.ts; enforcing it is this file's job, and the
+// record engine enforces it for free — `rejectUnknownKeys` reports any other
+// section as a "preset key" error naming the two that are legal.
+//
+// This file is the structural pass only. Whether a preset's root names a
+// segment that exists, and whether globals.preset names a declared preset, are
+// CROSS-REFERENCE concerns (loader/cross-ref.ts), because both run on the
+// MERGED config — a preset may stage segments the bundled default provides.
+
+import {
+  describeType,
+  isPlainObject,
+  record,
+  recordJson,
+  type FieldSpec,
+  type JsonNode,
+  type RecordSchema,
+  type ValidateCtx,
+} from "./validate-core.js";
+import { findKeyLine } from "./diagnostics.js";
+import { presetGlobalsJson, validatePresetGlobals } from "./globals.js";
+import { LAYOUT_NODE_REF, validateRoot } from "./layout.js";
+import type { PresetDecl } from "../dsl-types.js";
+
+// [LAW:one-source-of-truth] A preset's `root` runs through THE layout validator
+// — the same `validateRoot` the top-level `root:` uses, not a reduced copy — so
+// the A-grammar, the group sugar, and every migration error read identically
+// wherever a layout is authored. Group sugar declared inside a preset therefore
+// also lands in `ctx.groups` and synthesizes its state var / cycle action /
+// toggle segment into the shared sections, exactly as a top-level group does:
+// the synthesized artifacts are process-lifetime (see PresetDecl's cap), the
+// preset only chooses whether to stage them.
+const presetRootSpec: FieldSpec<NonNullable<PresetDecl["root"]>> = {
+  required: false,
+  json: { $ref: LAYOUT_NODE_REF },
+  parse: (ctx, path, field, raw) =>
+    raw[field] === undefined
+      ? undefined
+      : validateRoot(ctx, `${path}.${field}`, raw[field]),
+};
+
+// [LAW:one-source-of-truth] A preset's `globals` runs through the globals field
+// table, minus `preset` itself (a preset cannot select a preset — see
+// validatePresetGlobals). A field added to Globals is preset-settable the same
+// day, with no edit here.
+const presetGlobalsSpec: FieldSpec<NonNullable<PresetDecl["globals"]>> = {
+  required: false,
+  json: presetGlobalsJson(),
+  parse: (ctx, path, field, raw) =>
+    raw[field] === undefined
+      ? undefined
+      : validatePresetGlobals(ctx, `${path}.${field}`, raw[field]),
+};
+
+const PRESET_SCHEMA: RecordSchema<PresetDecl> = {
+  noun: "preset key",
+  fields: { root: presetRootSpec, globals: presetGlobalsSpec },
+};
+
+// An absent presets block is handled by the caller (absence survives the parse);
+// a non-object is a reported error recovering to empty — parseDslConfig throws
+// once any issue exists, so the recovery value never renders.
+export function validatePresets(
+  ctx: ValidateCtx,
+  raw: unknown,
+): Readonly<Record<string, PresetDecl>> {
+  if (!isPlainObject(raw)) {
+    ctx.issues.push({
+      path: "presets",
+      message: `presets must be an object mapping preset names to config fragments, got ${describeType(raw)}`,
+      line: findKeyLine(ctx.source, ["presets"]),
+    });
+    return {};
+  }
+  const out: Record<string, PresetDecl> = {};
+  for (const [name, value] of Object.entries(raw)) {
+    // [LAW:no-silent-failure] A preset name is a deliverable set-state value —
+    // a preset picker writes it on the wire, which rejects empty values and
+    // splits on "/". Rejecting the shape HERE surfaces the error on every
+    // config load, not only once an action ranges the "presets" domain (the
+    // identical guard looks.ts applies to look names, for the identical
+    // reason).
+    if (name === "" || name.includes("/")) {
+      ctx.issues.push({
+        path: `presets.${name}`,
+        message: `preset name ${JSON.stringify(name)} must be non-empty and slash-free — a preset picker writes the name on the set-state wire, which rejects empty values and splits on "/"`,
+        line: findKeyLine(ctx.source, ["presets", name]),
+      });
+      continue;
+    }
+    const parsed = record(ctx, PRESET_SCHEMA, `presets.${name}`, value);
+    if (parsed !== null) out[name] = parsed;
+  }
+  return out;
+}
+
+// [LAW:one-source-of-truth] The schema emitter derives from the SAME declaration
+// the validator interprets — a map of preset names to the closed two-section
+// fragment object.
+export function presetsJson(): JsonNode {
+  return { type: "object", additionalProperties: recordJson(PRESET_SCHEMA) };
+}