@promptctl/cc-candybar 1.39.0 → 1.41.0

package/src/config/help.ts

@@ -0,0 +1,151 @@
+// [LAW:one-type-per-behavior] candybar-settings-ui-aok.6 — the `(?)` affordance.
+// It is NOT a fourth kind of disclosure. A `(?)` is the SAME binary toggle
+// `kind: "group"`, `{{ menu }}`, edit mode's trigger and the global settings menu
+// all are; it differs from a group in exactly two VALUES — the text its trigger
+// binds (`(?)`/`✕` rather than `label ▸`/`label ▾`) and what its body contains
+// (help lines rather than arbitrary layout). So every artifact below comes out
+// of `disclosure.ts`, and this module contributes no state, no gate, and no
+// glyph rule of its own — only the two values and the shape they fill.
+//
+// The ticket that asked for this predicted the alternative: "if it arrives as
+// another hand-rolled set of four artifacts, the finding to report is that the
+// disclosure itself wants to be one thing". It did. `disclosure.ts` had
+// single-sourced only the two artifacts that are DATA (the state var, the cycle
+// action) and left the two that are STRINGS — the trigger template and the body
+// gate — hand-written at five sites, which is where the `+▸` double-glyph bug of
+// .4 lived. `disclosureTrigger`/`disclosureGate` finish that extraction, and
+// this file is the first caller that never had a copy to begin with.
+//
+// [LAW:one-way-deps] Content is a PARAMETER, never an import: this module knows
+// how to mint a help disclosure and nothing about what any particular one says.
+// The bundled sentences live in `src/help-text.ts` — the corpus `--help` prints
+// — and the two synthesis passes that place a `(?)` pass them in. That is what
+// keeps the bar's help and the CLI's help one set of strings rather than two
+// hand-maintained copies [LAW:one-source-of-truth].
+
+import type { ActionDecl } from "./action.js";
+import type { LayoutNode, SegmentDecl, VariableDecl } from "./dsl-types.js";
+import {
+  DISCLOSURE_CLOSED,
+  DISCLOSURE_GLYPH_CLOSE,
+  disclosureCycleAction,
+  disclosureGate,
+  disclosureStateVar,
+  disclosureTrigger,
+  type DisclosureRef,
+} from "./disclosure.js";
+
+// [LAW:one-source-of-truth] The trigger's closed text, one spelling for the
+// whole bar so a reader learns the affordance once. Its OPEN text is the shared
+// `DISCLOSURE_GLYPH_CLOSE` — the same ✕ a picker's close cell and edit mode's
+// opened `+` wear, because it is the same meaning: click to close what this
+// opened.
+//
+// [LAW:no-silent-failure] Deliberately per-state rather than one static `(?)`.
+// Several `(?)` triggers can be visible at once (edit mode's and the config
+// menu's, whenever both surfaces are open), and the tint that distinguishes
+// other open disclosures — node-registry's `drops.length > 0` — recolours a
+// segment's RESOLVED BACKGROUND, so it is a no-op on any segment declaring no
+// bg. .5 gave edit mode a look at the GLOBALS level only, which left its insert
+// chrome without one; the trigger's own text is therefore the only place the
+// open state can be read, exactly as it is for the `+` beside it.
+export const HELP_GLYPH_CLOSED = "(?)";
+
+// The open member of a help disclosure's binary key: it holds this or the shared
+// CLOSED sentinel, like every other binary disclosure in the bar.
+const HELP_OPEN = "open";
+
+// [LAW:one-source-of-truth] The declarations a `(?)` contributes, keyed by final
+// name — the same accumulator shape `ChromeArtifacts`/`MenuArtifacts` already
+// thread through their synthesis passes, so a caller merges one more set of
+// artifacts the way it already merges its own.
+export interface HelpArtifacts {
+  readonly variables: Record<string, VariableDecl>;
+  readonly actions: Record<string, ActionDecl>;
+  readonly segments: Record<string, SegmentDecl>;
+}
+
+// [LAW:types-are-the-program] The two nodes a caller must place, returned
+// separately because they belong in different rows and only the caller knows
+// which: the trigger is a CELL that joins a row the caller already has (so
+// opening help never widens the bar and closed help costs no row), and the body
+// is a ROW of its own that exists only while the disclosure is open.
+export interface HelpDisclosure {
+  readonly trigger: LayoutNode;
+  readonly body: LayoutNode;
+}
+
+// Mint one `(?)` and its body.
+//
+// `name` is the reserved-namespace base every artifact derives from — the
+// trigger segment, the state variable and the cycle action all take it
+// verbatim, the same one-name-four-artifacts convention `groups.<name>` and
+// `settings.menu` already use, so the toggle's click and the body's gate cannot
+// address different keys [LAW:one-source-of-truth].
+//
+// `within` names the disclosures this help sits INSIDE (edit mode, the settings
+// menu). Both nodes inherit those gates, so a `(?)` opened inside a surface that
+// is then closed cannot leave its body stranded on the bar — the body's gate is
+// its own ref AND every enclosing one, which is what "open" actually means for a
+// nested disclosure [LAW:dataflow-not-control-flow].
+export function declareHelp(
+  name: string,
+  lines: readonly string[],
+  within: readonly DisclosureRef[],
+  out: HelpArtifacts,
+  surface?: { readonly bg: string; readonly fg: string },
+): HelpDisclosure {
+  const self: DisclosureRef = { variable: name, member: HELP_OPEN };
+  out.variables[name] = disclosureStateVar(name, DISCLOSURE_CLOSED);
+  out.actions[name] = disclosureCycleAction(name, HELP_OPEN);
+  out.segments[name] = {
+    template: disclosureTrigger(
+      name,
+      HELP_GLYPH_CLOSED,
+      DISCLOSURE_GLYPH_CLOSE,
+    ),
+    ...surface,
+    // The trigger is visible wherever its host surface is. An unnested `(?)`
+    // (`within` empty) is always visible, and declares no `when` at all.
+    ...gateOf(within),
+  };
+
+  // [LAW:one-source-of-truth] One line is one SEGMENT whose template is that
+  // line VERBATIM — no wrapper text, no joining, no reformatting, and no
+  // escaping. A `template` IS template source, so its static runs reach the bar
+  // unchanged; escaping belongs to text spliced INSIDE a quoted `{{ }}` argument
+  // (what `disclosureTrigger` above does, and this is not), and applying it here
+  // would put backslashes on the bar the moment a sentence used a quote. That is
+  // what makes "the bar's help IS the corpus" checkable as identity rather than
+  // as string similarity: the declaration a test reads and the sentence
+  // `src/help-text.ts` exports are one value, byte for byte.
+  const bodyGate = disclosureGate(self, ...within);
+  const children = lines.map((line, i): LayoutNode => {
+    const lineName = `${name}.${i}`;
+    // [LAW:single-enforcer] The gate lives on the body container below and
+    // nowhere else — the render walk ANDs an ancestor's `when` into every
+    // descendant (src/dsl/render.ts:764), so a copy here would be a second
+    // enforcer of one predicate with nothing keeping the two equal.
+    out.segments[lineName] = { template: line, ...surface };
+    return { kind: "segment", name: lineName };
+  });
+
+  return {
+    trigger: { kind: "segment", name },
+    body: {
+      kind: "container",
+      direction: "horizontal",
+      children,
+      when: bodyGate,
+    },
+  };
+}
+
+// The enclosing gate as an optional `when` field — the codebase's standard
+// spelling for "this field exists only when there is something to put in it",
+// keeping `disclosureGate`'s first argument required so a gate over nothing
+// stays unrepresentable.
+function gateOf(within: readonly DisclosureRef[]): { when?: string } {
+  const [first, ...rest] = within;
+  return first === undefined ? {} : { when: disclosureGate(first, ...rest) };
+}

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

@@ -51,7 +51,9 @@ import type { ActionDecl } from "../action.js";
 import {
   DISCLOSURE_CLOSED,
   disclosureCycleAction,
+  disclosureGate,
   disclosureStateVar,
+  type DisclosureRef,
 } from "../disclosure.js";
 import { reservedNamespaceCollisions } from "./reserved-namespace.js";
 
@@ -71,10 +73,20 @@ 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] Edit mode AS a disclosure, which is what it has
+// always been: a binary toggle over one SessionState key. Naming it as a ref
+// lets anything nested inside edit mode (a `(?)` and its body) derive its own
+// gate by conjunction with this one, instead of concatenating gate strings.
+export const EDIT_MODE_REF: DisclosureRef = {
+  variable: EDIT_MODE_KEY,
+  member: EDIT_MODE_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}" }}`;
+// segment gates on — derived from the ref above through the same function
+// every other disclosure's gate comes from, so edit-mode chrome and a group
+// body are gated by one rule rather than by two spellings that agree today.
+export const EDIT_MODE_GATE = disclosureGate(EDIT_MODE_REF);
 
 // [LAW:single-enforcer] The ONE detector for "does this file want edit mode":
 // a literal `{{ action "edit.toggle" … }}` call somewhere a segment's

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

@@ -12,7 +12,7 @@
 // cycles. Those stay SEMANTIC checks the loader carries — schema = shape, lint =
 // meaning, the same complementary boundary `config-schema.test.ts` pins.
 
-import { globalsJson } from "./globals.js";
+import { editGlobalsJson, globalsJson } from "./globals.js";
 import { variablesMapJson } from "./variables.js";
 import { segmentsJson } from "./segments.js";
 import { actionsJson } from "./actions.js";
@@ -50,6 +50,7 @@ export function emitConfigSchema(): JsonNode {
       actions: actionsJson(),
       looks: looksJson(),
       presets: presetsJson(),
+      editGlobals: editGlobalsJson(),
       helpers: { type: "object", additionalProperties: { type: "string" } },
     },
     definitions: {

package/src/config/loader/globals.ts

@@ -104,43 +104,63 @@ const GLOBALS_SCHEMA: RecordSchema<Globals> = {
   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
+// [LAW:one-source-of-truth] A globals FRAGMENT — a delta layered over the
+// config's own globals at render time — may not carry `preset`: which preset is
+// active has exactly one authority (session pick over globals.preset over the
+// floor), and a fragment re-selecting a preset would be a second one. For a
+// preset's own fragment that second authority is also cyclic; for edit mode's
+// it would let a look-only fragment restage the whole layout, which edit chrome
+// already owns. 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-type-per-behavior] Both fragments reject the field identically and
+// differ only in the SUBJECT a diagnostic names, so this is one spec taking
+// that noun as data — never two specs that could drift in what they reject.
+function nestedPresetSpec(subject: string): FieldSpec<string> {
+  return {
+    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 here — ${subject} cannot select a preset`,
+    },
+    parse: (ctx, path, field, raw) => {
+      if (raw[field] !== undefined) {
+        ctx.issues.push({
+          path: `${path}.${field}`,
+          message:
+            `${path}.${field}: ${subject} cannot select a preset. Which preset is active is ` +
+            `resolved once, as session pick over globals.preset over "default"; a fragment ` +
+            `naming another would be a second authority over that. ` +
+            `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.
+// [LAW:one-source-of-truth] Each fragment-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 },
+  fields: { ...GLOBALS_FIELDS, preset: nestedPresetSpec("a preset") },
+};
+
+// [LAW:one-type-per-behavior] Edit mode's staged globals are the same shape one
+// rung later in the precedence chain, so they reuse the same table rather than
+// declaring which fields edit mode "supports" — a field added to Globals is
+// edit-settable the same day, with no edit here.
+const EDIT_GLOBALS_SCHEMA: RecordSchema<Globals> = {
+  noun: "editGlobals key",
+  fields: {
+    ...GLOBALS_FIELDS,
+    preset: nestedPresetSpec("the editGlobals fragment"),
+  },
 };
 
 // An absent globals block is the empty default (no issue); a non-object is a
@@ -177,6 +197,20 @@ export function presetGlobalsJson(): JsonNode {
   return recordJson(PRESET_GLOBALS_SCHEMA);
 }
 
+// Edit mode's twin of the two above: same interpreter, same field table, the
+// schema whose `preset` rejection names the editGlobals fragment.
+export function validateEditGlobals(
+  ctx: ValidateCtx,
+  path: string,
+  raw: unknown,
+): Globals {
+  return record(ctx, EDIT_GLOBALS_SCHEMA, path, raw) ?? {};
+}
+
+export function editGlobalsJson(): JsonNode {
+  return recordJson(EDIT_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

package/src/config/loader/layout.ts

@@ -35,7 +35,9 @@ import {
   DISCLOSURE_GLYPH_CLOSED,
   DISCLOSURE_GLYPH_OPEN,
   disclosureCycleAction,
+  disclosureGate,
   disclosureStateVar,
+  disclosureTrigger,
 } from "../disclosure.js";
 import { findKeyLine } from "./diagnostics.js";
 import { reservedNamespaceCollisions } from "./reserved-namespace.js";
@@ -535,20 +537,13 @@ function lowerGroup(g: GroupNodeInput): LayoutNode {
         kind: "container",
         direction: g.direction ?? "vertical",
         children: g.children,
-        when: `{{ eq .${ref} "${g.name}" }}`,
+        when: disclosureGate({ variable: ref, member: g.name }),
       },
     ],
     ...(g.when !== undefined && { when: g.when }),
   };
 }
 
-// Go-template string-literal escaping for the synthesized toggle template — the
-// label is a plain display string (dynamic labels are raw-grammar territory),
-// so backslashes and quotes are the only characters that could break the splice.
-function escapeTemplateLiteral(s: string): string {
-  return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
-}
-
 function groupIssue(ctx: ValidateCtx, path: string, message: string): void {
   ctx.issues.push({
     path,
@@ -641,7 +636,6 @@ export function synthesizeGroupDecls(
   for (const g of groups) {
     const name = GROUP_NS + g.name;
     const key = groupStateKey(g);
-    const label = escapeTemplateLiteral(g.label);
     // [LAW:dataflow-not-control-flow] Depth is a value derivable from the paths
     // already in ctx.groups — no extra threading. Strict-prefix count gives
     // nesting depth; the indent embeds as a string constant in the template.
@@ -662,7 +656,11 @@ export function synthesizeGroupDecls(
     // structural left-margin (nesting depth) and stays leading; the glyph is a
     // trailing affordance on the label, never a prefix.
     segments[name] = {
-      template: `{{ action "${name}" "${indent}${label} ${DISCLOSURE_GLYPH_CLOSED}" "${indent}${label} ${DISCLOSURE_GLYPH_OPEN}" }}`,
+      template: disclosureTrigger(
+        name,
+        `${indent}${g.label} ${DISCLOSURE_GLYPH_CLOSED}`,
+        `${indent}${g.label} ${DISCLOSURE_GLYPH_OPEN}`,
+      ),
       ...(g.bg !== undefined && { bg: g.bg }),
       ...(g.fg !== undefined && { fg: g.fg }),
     };

package/src/config/loader/merge.ts

@@ -53,6 +53,12 @@ export function mergeWithDefault(
     // (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] editGlobals merges FIELD by field — the
+    // `globals` cascade above, not the by-name cascades around it, because it
+    // IS a globals fragment: a user retuning edit mode's separator says nothing
+    // about its `style`, exactly as a user setting `globals.padding` says
+    // nothing about `globals.charset`.
+    editGlobals: { ...dflt.editGlobals, ...(raw.editGlobals ?? {}) },
     // [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.

package/src/config/presets.ts

@@ -15,7 +15,7 @@
 // place it is written down:
 //
 //   bundled default  <  user config file  <  persisted overrides
-//                    <  ACTIVE PRESET  <  session pick
+//                    <  ACTIVE PRESET  <  session pick  <  EDIT MODE
 //
 // The preset's position is forced by its lifetime, not chosen. Everything to
 // its left is resolved once per RenderCache entry (an entry serves many
@@ -26,6 +26,18 @@
 // "compact" arrangement must actually change padding, even for a user who once
 // persisted a padding they liked) while a session's own click still wins over
 // the preset (a click is later still).
+//
+// The same rule places the last rung (candybar-settings-ui-aok.5): edit mode's
+// `editGlobals` fragment is decided later than ANY session pick — a user picks
+// a style, and only afterwards enters edit mode — so it is the new rightmost
+// layer, and a session pick of "capsule" cannot survive into a mode whose whole
+// job is to stop segments reading as one continuous strip. It differs from
+// every rung to its left in LIFETIME rather than in kind: nothing writes it to
+// SessionState or the overrides layer, so leaving edit mode restores the
+// previous look with no save/restore path — the session's own pick was never
+// overwritten, only out-ranked [LAW:dataflow-not-control-flow]. The rung itself
+// is the `staged` parameter of effectiveGlobal (themes/policy.ts); this comment
+// is the ONE place the order is written down.
 
 // [LAW:one-way-deps] Type-only, so nothing is emitted and option-domain.ts (a
 // leaf that deliberately never imports dsl-types.ts) can import PRESET_NAMES
@@ -87,7 +99,14 @@ export function effectivePresetName(
   globalsPreset: string | undefined,
   declaredPresets: Readonly<Record<string, PresetDecl>>,
 ): string {
+  // [LAW:types-are-the-program] No staged rung, and the absence is enforced
+  // rather than assumed: every globals fragment that could stage one — a
+  // preset's own `globals`, edit mode's `editGlobals` — has `preset` swapped for
+  // a rejection in its schema (loader/globals.ts), so "a fragment selected a
+  // preset" is unrepresentable and there is nothing here to resolve against.
+  // Which preset is active keeps exactly one authority.
   return effectiveMemberName(
+    undefined,
     sessionPreset,
     globalsPreset,
     PRESET_FLOOR,