@promptctl/cc-candybar 1.34.1 → 1.36.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/cc-candybar",
-  "version": "1.34.1",
+  "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.34.1",
-    "@promptctl/cc-candybar-darwin-x64": "1.34.1",
-    "@promptctl/cc-candybar-linux-x64": "1.34.1",
-    "@promptctl/cc-candybar-linux-arm64": "1.34.1"
+    "@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/check.ts

@@ -119,6 +119,11 @@ export function checkPayload(
     weekly: { percentage: 21, resetsAt: nowSec + 5 * 86400 },
     cache: { expiresAt: nowSec + 15 * 60 },
     tmux: { session: "work" },
+    // `ssh: true` for the same reason `tmux.session` is populated: this
+    // fixture deliberately satisfies every gate so a when-gated segment
+    // RENDERS and its template gets checked. A local-looking fixture would
+    // gate the host segment off and let a typo inside it ship.
+    host: { name: "tester-box", user: "tester", ssh: true },
     theme: { effective: effective.theme },
     look: { effective: effective.look },
     // [LAW:one-source-of-truth] Was missing here even though EffectiveGlobals

package/src/config/default-dsl-config.ts

@@ -465,6 +465,31 @@ export const RAW_DEFAULT_DSL_CONFIG = {
     // gates the input variant so unused segments cost nothing.
     "tmux.session": { kind: "input", path: "tmux.session", default: "" },
 
+    // Host identity — which machine this session is on, and whether the user
+    // arrived over SSH. All three come through the augmented payload rather
+    // than `kind: "env"` / `kind: "shell"`, and that is not a style choice:
+    //
+    //   • `host.ssh` CANNOT be an env var here. Variables are evaluated in the
+    //     DAEMON, which is detached and serves every session for this user at
+    //     once — its `SSH_*` env describes whichever shell happened to spawn
+    //     it. The fact is captured by the live client and carried as a wire
+    //     hint (the `termCols` pattern); the payload is the only honest source.
+    //   • `host.name`/`host.user` are machine facts the daemon reads directly,
+    //     so they cost two syscalls instead of a per-render subprocess.
+    //
+    // Defaults are the "unknown" values, and for `ssh` that is `false`: an
+    // absent field (a client too old to send the hint) renders as local, which
+    // is the pre-feature behavior, while the input-fallback chain records a
+    // `last_error` so `cc-candybar debug vars` can still tell the two apart.
+    "host.name": { kind: "input", path: "host.name", default: "" },
+    "host.user": { kind: "input", path: "host.user", default: "" },
+    "host.ssh": {
+      kind: "input",
+      path: "host.ssh",
+      type: "boolean",
+      default: false,
+    },
+
     // Git — every field flows from the daemon's projected GitInfo payload.
     // The DSL's native `kind: "git"` source covers a 6-field subset
     // (branch/sha/dirty/ahead/behind/stash); using `input` here gives the
@@ -803,6 +828,34 @@ export const RAW_DEFAULT_DSL_CONFIG = {
       fg: "foreground",
       when: '{{ ne .tmux.session "" }}',
     },
+    // "You are not on your own machine." Modelled on the git-taculous zsh
+    // theme, which prepends `(%n@%m)` to the prompt under SSH and shows
+    // nothing locally — you already know your own hostname.
+    //
+    // [LAW:dataflow-not-control-flow] Presence IS the signal. There is no SSH
+    // "mode" and no force-on flag (git-taculous's GITTACULOUS_ENABLE_SSH_THEME
+    // would be a flag with no deletion date, [LAW:no-mode-explosion]); the cell
+    // exists exactly when the value says so, like tmux/block/weekly. A user who
+    // wants it always-on overrides this one segment's `when` to `"true"`.
+    //
+    // `bg: "warning"` is load-bearing, not decoration: warning is one of the
+    // hue-ANCHORED palette roots, so it survives every theme, look, and
+    // per-segment hue transposition still reading as an alert. Any other slot
+    // would drift with the hue stepper and could land camouflaged against its
+    // neighbours — exactly what a "wrong machine" warning must never do.
+    // `contrastOn (bgOf)` then derives a readable foreground from whatever that
+    // resolves to, rather than betting a fixed `foreground` stays legible.
+    //
+    // Each half falls back to "?" so a failed hostname/username read renders
+    // `⇄ ?@?` — still unmistakably "remote", and legibly missing its identity
+    // rather than a blank that reads as a rendering bug ([LAW:no-silent-failure]).
+    host: {
+      template:
+        '⇄ {{ .host.user | default "?" }}@{{ .host.name | default "?" }}',
+      bg: "warning",
+      fg: "{{ contrastOn (bgOf) }}",
+      when: "{{ .host.ssh }}",
+    },
     git: {
       template: GIT_TEMPLATE,
       bg: "surface-active",
@@ -1268,6 +1321,12 @@ export const RAW_DEFAULT_DSL_CONFIG = {
         kind: "container",
         direction: "horizontal",
         children: [
+          // Leads the identity row: the first thing to read is WHICH MACHINE,
+          // because it reframes every path and branch to its right. Same
+          // placement git-taculous gives `(%n@%m)` — ahead of the directory.
+          // Gated off entirely on a local session, so the row still opens with
+          // `directory` where it always has.
+          { kind: "segment", name: "host" },
           { kind: "segment", name: "directory" },
           { kind: "segment", name: "gitaculous" },
           { kind: "segment", name: "toolbar" },

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";