@promptctl/cc-candybar 1.35.0 → 1.36.0

package/package.json

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

package/src/config/dsl-loader.ts

@@ -50,6 +50,8 @@ import { synthesizeGroupDecls, validateRoot } from "./loader/layout.js";
 import { synthesizeMenuDecls } from "./loader/menu-synth.js";
 import { synthesizeEditModeToggle } from "./loader/edit-mode.js";
 import { synthesizeEditChrome } from "./edit-chrome.js";
+import { SETTINGS_NS, synthesizeSettingsMenu } from "./settings-menu.js";
+import { reservedNamespaceCollisions } from "./loader/reserved-namespace.js";
 import { validateActions } from "./loader/actions.js";
 import { validateLooks } from "./loader/looks.js";
 import { validatePresets } from "./loader/presets.js";
@@ -152,7 +154,12 @@ export function validateConfig(
   // into freshly-synthesized segments, actions into freshly-synthesized
   // actions) is correct by construction and does not re-enter cross-ref/
   // cycle checking, exactly as group/menu synthesis's output doesn't either.
-  const withChrome = synthesizeEditChrome(config);
+  // [LAW:dataflow-not-control-flow] candybar-settings-ui-aok.1's global settings
+  // menu, spliced BEFORE edit chrome so edit chrome walks the final content tree
+  // and treats the menu's reserved `settings.` names as chrome-exempt — the
+  // full ordering argument lives in settings-menu.ts's header, beside the pass
+  // it governs.
+  const withChrome = synthesizeEditChrome(synthesizeSettingsMenu(config));
   return withChrome as ValidatedConfig;
 }
 
@@ -295,6 +302,18 @@ function validateTopLevel(
   // affordances) runs later, in validateConfig, once the merged/preset-
   // resolved/rootOps-replayed tree exists to derive it from.
   synthesizeEditModeToggle(ctx, out);
+  // [LAW:one-source-of-truth] The global settings menu reserves its namespace
+  // here and synthesizes NOTHING here: the tree it must be present in only
+  // exists after merge (a user `root` replaces the default's), so the artifacts
+  // are minted in validateConfig. The reservation is unconditional all the same,
+  // mirroring every other namespace above — "you never author settings.*" is a
+  // stable contract, not a rule that switches on when the pass happens to fire.
+  reservedNamespaceCollisions(
+    ctx,
+    out,
+    SETTINGS_NS,
+    "the global settings menu",
+  );
   return out;
 }
 

package/src/config/edit-chrome.ts

@@ -40,6 +40,7 @@ import {
   EDIT_TOGGLE_ACTION,
 } from "./loader/edit-mode.js";
 import { GROUP_NS } from "./loader/layout.js";
+import { SETTINGS_NS } from "./settings-menu.js";
 import {
   menuActionName,
   menuMember,
@@ -61,7 +62,11 @@ import {
 // knowledge, so the banner below is spliced UNCONDITIONALLY for every
 // preset — same shape, every reload — and this predicate is what decides
 // whether it's visible, never a branch in this synthesis pass.
-const PRESET_CUSTOMIZED_GATE = "{{ .preset.customized }}";
+// [LAW:one-source-of-truth] Exported: test/helpers/ambient-chrome.ts filters this
+// ensured name out of "what did the AUTHOR declare" assertions and must read the
+// same string, never a second copy that a rename here would leave behind.
+export const PRESET_CUSTOMIZED_VAR = "preset.customized";
+const PRESET_CUSTOMIZED_GATE = `{{ .${PRESET_CUSTOMIZED_VAR} }}`;
 
 // [LAW:one-source-of-truth] group/menu-synthesized segments (`groups.`/
 // `menus.`) and edit mode's own trigger/chrome (`edit.`) are structural —
@@ -73,7 +78,12 @@ function isChromeExempt(name: string): boolean {
   return (
     name.startsWith(EDIT_NS) ||
     name.startsWith(MENU_NS) ||
-    name.startsWith(GROUP_NS)
+    name.startsWith(GROUP_NS) ||
+    // The global settings menu is the entry point edit mode is REACHED from
+    // (candybar-settings-ui-aok.1) — offering a `-` beside it would let one
+    // click delete the door back in, the self-lockout the `toolbar` trigger's
+    // placement was chosen to avoid. Structural, like the three above it.
+    name.startsWith(SETTINGS_NS)
   );
 }
 
@@ -93,6 +103,11 @@ function escapeTemplateLiteral(s: string): string {
 // so cross-preset names (disambiguated by `presetIdent`) can never collide.
 interface ChromeArtifacts {
   readonly variables: Record<string, VariableDecl>;
+  // [LAW:no-silent-failure] Declarations this synthesis DEPENDS on rather than
+  // OWNS: merged UNDER the config so a user's own declaration of the same name
+  // wins, unlike `variables` above, which lives in a reserved namespace no user
+  // may write and therefore merges over.
+  readonly ensured: Record<string, VariableDecl>;
   readonly actions: Record<string, ActionDeclType>;
   readonly segments: Record<string, SegmentDecl>;
 }
@@ -219,7 +234,18 @@ function spliceContainer(
   posCounter: { n: number },
 ): ContainerNode {
   const children: LayoutNode[] = [];
-  for (const child of node.children) {
+  // [LAW:one-source-of-truth] The trailing `+`'s position is "after the last
+  // CONTENT segment", not "after the last child". Those coincided until a
+  // synthesis started appending exempt chrome (the global settings menu,
+  // candybar-settings-ui-aok.1) to a row's end, at which point reading the last
+  // child silently dropped the row's final insert point — N segments offering
+  // only N insert points instead of N+1.
+  const lastContent = node.children.reduce(
+    (idx, child, i) =>
+      child.kind === "segment" && !isChromeExempt(child.name) ? i : idx,
+    -1,
+  );
+  for (const [i, child] of node.children.entries()) {
     if (child.kind === "container") {
       children.push(
         spliceContainer(
@@ -250,24 +276,19 @@ function spliceContainer(
     );
     children.push(child);
     children.push(removeChrome(presetIdent, rootOpsKey, child.name, artifacts));
-  }
-  const last = node.children[node.children.length - 1];
-  if (
-    last !== undefined &&
-    last.kind === "segment" &&
-    !isChromeExempt(last.name)
-  ) {
-    children.push(
-      insertChrome(
-        presetIdent,
-        rootOpsKey,
-        String(posCounter.n++),
-        domainName,
-        last.name,
-        "after",
-        artifacts,
-      ),
-    );
+    if (i === lastContent) {
+      children.push(
+        insertChrome(
+          presetIdent,
+          rootOpsKey,
+          String(posCounter.n++),
+          domainName,
+          child.name,
+          "after",
+          artifacts,
+        ),
+      );
+    }
   }
   return { ...node, children };
 }
@@ -301,6 +322,20 @@ function prependCustomizedBanner(
   // edited down to zero non-exempt segments (no removeChrome/insertChrome
   // persist actions left to register it) doesn't orphan this exact click.
   artifacts.actions[actionName] = { reset: rootOpsKey };
+  // [LAW:one-source-of-truth] The banner reads `.preset.customized`, so THIS
+  // pass is what requires that variable — not whichever config happens to
+  // declare it. The bundled default does, which is why the dependency stayed
+  // invisible until the global settings menu made edit mode reachable from
+  // configs that never declared it, and the missing field surfaced as a ⚠ on
+  // the bar. Ensured, never overridden: a user declaration of the same name
+  // wins (see the merge in synthesizeEditChrome), so this only supplies the
+  // floor the synthesis itself depends on.
+  artifacts.ensured[PRESET_CUSTOMIZED_VAR] = {
+    kind: "input",
+    path: PRESET_CUSTOMIZED_VAR,
+    type: "boolean",
+    default: false,
+  };
   const label = escapeTemplateLiteral(presetName);
   artifacts.segments[chromeSegName] = {
     template: `{{ action "${actionName}" "↺ ${label} customized" }}`,
@@ -391,6 +426,7 @@ export function synthesizeEditChrome(config: DslConfig): DslConfig {
   if (!(EDIT_TOGGLE_ACTION in config.actions)) return config;
   const artifacts: ChromeArtifacts = {
     variables: {},
+    ensured: {},
     actions: {},
     segments: {},
   };
@@ -404,7 +440,11 @@ export function synthesizeEditChrome(config: DslConfig): DslConfig {
   }
   return {
     ...config,
-    variables: { ...config.variables, ...artifacts.variables },
+    variables: {
+      ...artifacts.ensured,
+      ...config.variables,
+      ...artifacts.variables,
+    },
     actions: { ...config.actions, ...artifacts.actions },
     segments: { ...config.segments, ...artifacts.segments },
     presets,

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

@@ -29,6 +29,13 @@ import {
 import { listGlobalsFieldNames } from "./globals.js";
 import { parsePersistTarget } from "./persist-target.js";
 import { presetNames } from "../presets.js";
+import {
+  canHostSessionState,
+  countAnchors,
+  isSettingsAnchor,
+  SESSION_ID_VAR,
+  SETTINGS_ANCHOR,
+} from "../settings-menu.js";
 import { ident } from "../ident.js";
 import { findKeyLine } from "./diagnostics.js";
 import { isPlainObject, type ValidateCtx } from "./validate-core.js";
@@ -248,11 +255,30 @@ export function validateCrossReferences(
   // 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.
+  //
+  // [LAW:single-enforcer] The menu precondition is asked once, of the same
+  // predicate synthesizeSettingsMenu gates on, and read by every tree walked.
+  const menuWillSynthesize = canHostSessionState(cfg);
   const checkLayoutTree = (
     root: LayoutNode,
     layoutKey: string,
     layoutLine: number | undefined,
   ): void => {
+    // [LAW:one-source-of-truth] The global settings menu's anchor is a POSITION
+    // an author may place and this walk must therefore accept, even though no
+    // config declares a segment by that name — synthesizeSettingsMenu provides
+    // it unconditionally, immediately after these checks pass. Two placements is
+    // the real error: one state key holds one open state, so a second anchor
+    // would be a second toggle writing one disclosure, with two bodies claiming
+    // to be it. Counted over the SAME census the synthesis reads, so "placed"
+    // means one thing [LAW:single-enforcer].
+    if (countAnchors(root) > 1) {
+      ctx.issues.push({
+        path: layoutKey,
+        message: `${layoutKey} places the global settings menu anchor "${SETTINGS_ANCHOR}" ${countAnchors(root)} times — it may appear at most once per layout (it is one disclosure, and one state key holds one open state). Remove all but the placement you want; removing every placement puts the menu at its default position.`,
+        line: layoutLine,
+      });
+    }
     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
@@ -263,6 +289,24 @@ export function validateCrossReferences(
         });
       }
       if (node.kind !== "segment") continue;
+      if (isSettingsAnchor(node.name)) {
+        // [LAW:one-source-of-truth] Accepting the anchor asserts that
+        // synthesizeSettingsMenu WILL declare a segment by this name, so the
+        // acceptance reads the very predicate that pass decides by rather than
+        // assuming its answer. When it is false the reference is genuinely
+        // dangling, and the error names the unmet precondition: the author
+        // placed a documented anchor, they did not typo a segment name, and the
+        // generic "does not match any declared segment" would teach the wrong
+        // lesson [LAW:no-silent-failure].
+        if (!menuWillSynthesize) {
+          ctx.issues.push({
+            path: layoutKey,
+            message: `${layoutKey} places the global settings menu anchor "${SETTINGS_ANCHOR}", but this config declares no "${SESSION_ID_VAR}" variable — the menu is a click surface and every click composes a URL from "${SESSION_ID_VAR}", so it is not synthesized for a config without it. Declare a "${SESSION_ID_VAR}" variable (any config merged onto the bundled default inherits one) or remove the anchor placement.`,
+            line: layoutLine,
+          });
+        }
+        continue;
+      }
       if (!Object.prototype.hasOwnProperty.call(cfg.segments, node.name)) {
         const renamed = RENAMED_SEGMENTS[node.name];
         const hint =

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

@@ -29,6 +29,20 @@
 // of this pass caused. The reserved namespace stays reserved unconditionally
 // (mirroring reservedNamespaceCollisions' own contract); only the SYNTHESIS is
 // conditional.
+//
+// WHAT candybar-settings-ui-aok.1 CHANGED, and what it did not: the gate above
+// is intact and still the only way edit mode is reached — but it now has a
+// PERMANENT DEMANDER. synthesizeSettingsMenu mints a `settings.edit` segment
+// referencing `edit.toggle` into every config it can host, so in practice the
+// demand is satisfied for essentially every config a user writes, and reading
+// this section as "most bars carry no edit mode" is no longer true. The
+// separation the gate protects still holds exactly where it always mattered:
+// the menu declines to synthesize for a config with no `session.id`
+// (canHostSessionState in settings-menu.ts), which is precisely the static,
+// non-interactive bar this comment was written to keep clean. Production blast
+// radius was nil either way — the bundled default's `toolbar` segment already
+// referenced `edit.toggle`, so every config merging it already demanded edit
+// mode before the menu existed.
 
 import { createEngine } from "@promptctl/go-template-js";
 import type { Mutable, ValidateCtx } from "./validate-core.js";