@promptctl/cc-candybar 1.18.1 → 1.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/cc-candybar",
-  "version": "1.18.1",
+  "version": "1.20.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",
@@ -89,16 +89,16 @@
     "typescript": "^5.0.0"
   },
   "dependencies": {
-    "@promptctl/go-template-js": "^0.6.0",
+    "@promptctl/go-template-js": "^0.7.0",
     "@promptctl/rich-js": "^0.6.0",
     "json5": "^2.2.3",
     "mobx": "^6.15.0"
   },
   "optionalDependencies": {
-    "@promptctl/cc-candybar-darwin-arm64": "1.18.1",
-    "@promptctl/cc-candybar-darwin-x64": "1.18.1",
-    "@promptctl/cc-candybar-linux-x64": "1.18.1",
-    "@promptctl/cc-candybar-linux-arm64": "1.18.1"
+    "@promptctl/cc-candybar-darwin-arm64": "1.20.0",
+    "@promptctl/cc-candybar-darwin-x64": "1.20.0",
+    "@promptctl/cc-candybar-linux-x64": "1.20.0",
+    "@promptctl/cc-candybar-linux-arm64": "1.20.0"
   },
   "pnpm": {
     "supportedArchitectures": {

package/src/check.ts

@@ -0,0 +1,359 @@
+// [LAW:verifiable-goals] `cc-candybar check [path]` — the authoring agent's eyes.
+// Config diagnostics otherwise surface VISUALLY (composeWithDiagnostics renders
+// error/warning icons into the bar), a channel a blind config author never sees.
+// This command runs the production pipeline and projects its verdict onto a
+// text + exit-code contract a script can close its own loop on:
+//   0 — config loads and renders (warnings, if any, on stderr)
+//   1 — config is invalid (parse / validate / register / render failure)
+//   2 — usage error or a named file could not be read
+//
+// [LAW:single-enforcer] No parallel validation path: the verdict is reached
+// through the exact functions the daemon runs (RenderCache.reloadInto →
+// buildState, then the per-request render in server.ts) — resolveDslConfigPath →
+// detectConfigCollisions → loadConfig → validateConfig → registerDslConfig →
+// deriveActionValidators → renderDsl. "check passes" and "the daemon renders"
+// cannot diverge, because they are one code path.
+
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import {
+  loadConfig,
+  validateConfig,
+  resolveDslConfigPath,
+  detectConfigCollisions,
+  ConfigError,
+} from "./config/dsl-loader.js";
+import { expandHome } from "./config/loader/discovery.js";
+import { VariableStore } from "./var-system/store.js";
+import { SourceRegistry } from "./var-system/sources.js";
+import { SessionState } from "./daemon/session-state.js";
+import { registerDslConfig, renderDsl } from "./dsl/render.js";
+import { deriveActionValidators } from "./daemon/verbs/state-validators.js";
+import { effectiveThemeName, effectiveStripStyle } from "./themes/policy.js";
+import { resolverForThemeName } from "./themes/palette-resolvers.js";
+import {
+  DEFAULT_CHARSET,
+  DEFAULT_COLOR_COMPATIBILITY,
+  DEFAULT_PADDING,
+  DEFAULT_WRAP,
+} from "./render/strip.js";
+
+// [LAW:no-ambient-temporal-coupling] A fixed width keeps the verdict a function
+// of the config alone, not of whichever terminal invoked the check. Templates
+// evaluate in full before any width-driven wrap/pagination, so width shapes
+// layout, never diagnostics.
+const CHECK_WIDTH = 200;
+
+// One faked Claude Code hook event, shaped like the daemon's augmented payload
+// (see src/daemon/render-payload.ts) — the `input` vars read out of it by their
+// dotted `path`. [LAW:verifiable-goals] It is deliberately RICH (dirty git with
+// every worktree count, an upstream, a stash, a recent commit; home set; live
+// session/today/context/metrics/rate-limit data) so gated segments actually
+// RENDER their content instead of gating off. A minimal payload would let a
+// field-name typo in the git/directory/metrics/budget branches slip through —
+// those branches only run when their data is present.
+//
+// `effectiveTheme` is threaded in exactly as the daemon threads it (server.ts
+// resolves effectiveThemeName once and feeds BOTH the payload's
+// `theme.effective` field and the basePalette below) [LAW:one-source-of-truth].
+//
+// test/example-configs.test.ts asserts rendered content against these literal
+// values (780s → "◷ 13m", cost $0.39, version 1.15.0, …); changing one here
+// fails that suite loudly rather than drifting silently.
+export function checkPayload(effectiveTheme: string): Record<string, unknown> {
+  const home = "/home/tester";
+  const nowSec = Math.floor(Date.now() / 1000);
+  return {
+    hook_event_name: "Status",
+    session_id: "test0a1b-2c3d-4e5f-6a7b-8c9d0e1f2a3b",
+    version: "1.15.0",
+    home,
+    cwd: `${home}/code/cc-candybar/src`,
+    transcript_path: `${home}/.claude/projects/x/test.jsonl`,
+    model: { id: "claude-opus-4-8", display_name: "Opus 4.8" },
+    workspace: {
+      current_dir: `${home}/code/cc-candybar/src`,
+      project_dir: `${home}/code/cc-candybar`,
+    },
+    git: {
+      repoName: "cc-candybar",
+      branch: "main",
+      sha: "abc1234",
+      ahead: 2,
+      behind: 1,
+      staged: 3,
+      unstaged: 2,
+      untracked: 1,
+      conflicts: 0,
+      upstream: "origin/main",
+      stash: 1,
+      status: "dirty",
+      operation: "rebase",
+      timeSinceCommit: 780,
+    },
+    session: { cost: 0.39, tokens: 241400 },
+    today: { cost: 12.5, tokens: 3_400_000 },
+    context: { totalTokens: 48487, contextLeft: 24 },
+    metrics: {
+      lastResponseTime: 8.2,
+      responseTime: 4.2,
+      sessionDuration: 930,
+      messageCount: 8,
+      linesAdded: 512,
+      linesRemoved: 88,
+    },
+    block: { nativeUtilization: 63, resetsAt: nowSec + 2 * 3600 },
+    weekly: { percentage: 21, resetsAt: nowSec + 5 * 86400 },
+    cache: { expiresAt: nowSec + 15 * 60 },
+    tmux: { session: "work" },
+    theme: { effective: effectiveTheme },
+  };
+}
+
+// [LAW:dataflow-not-control-flow] The check result is DATA — a pure function of
+// the target file's contents — discriminated into the three outcomes the exit-
+// code contract projects. `checkConfig` carries the decision; `runCheck` only
+// maps it to (streams, exit), so the contract is testable without spawning a
+// process or stubbing process.exit.
+//
+// `configPath` null means the bundled default was checked (no config file
+// found — the daemon renders the same default in that state).
+export type CheckOutcome =
+  | {
+      readonly kind: "clean";
+      readonly configPath: string | null;
+      readonly warnings: readonly string[];
+      readonly rendered: string;
+    }
+  | {
+      readonly kind: "fatal";
+      readonly configPath: string | null;
+      readonly message: string;
+      readonly warnings: readonly string[];
+    }
+  | {
+      readonly kind: "unreadable";
+      readonly path: string;
+      readonly message: string;
+    };
+
+// Run the daemon's load-and-render pipeline against one config target.
+//
+// With no target, the path resolves exactly as the daemon resolves it
+// (resolveDslConfigPath: $CC_CANDYBAR_CONFIG → project/cwd → XDG), so the file
+// this checks IS the file the daemon would load from this directory.
+//
+// [LAW:no-silent-failure] With an explicit target, the named file must exist
+// and be readable — a missing file is `unreadable`, never a fall-through to the
+// bundled default. (The daemon's --config-to-missing-file behavior — render the
+// default, watch for the file to appear — is liveness for a long-running
+// renderer; a verdict command must not report "clean" about a file it never
+// read.)
+export function checkConfig(
+  target: string | undefined,
+  cwd: string = process.cwd(),
+): CheckOutcome {
+  // [LAW:one-source-of-truth] No pre-read: the ONE content read of the config
+  // file is the readFileSync inside loadConfig. Readability is established by
+  // the same read that parses (no double I/O); the catch below classifies its
+  // errno failure as `unreadable`. The explicit-target statSync is a metadata
+  // probe at the argv trust boundary, not a second read: a directory target
+  // (`check .`) fails read() with a path-less EISDIR the catch could not
+  // attribute, so the not-a-file usage error is decided here.
+  const configPath =
+    target !== undefined
+      ? path.resolve(expandHome(target))
+      : resolveDslConfigPath(cwd, cwd);
+  if (target !== undefined && configPath !== null) {
+    // throwIfNoEntry suppresses only ENOENT (left for the content read to
+    // classify); EACCES/EPERM on the probe itself is equally "could not read
+    // the named file" — same outcome, not an uncaught stack.
+    let st: fs.Stats | undefined;
+    try {
+      st = fs.statSync(configPath, { throwIfNoEntry: false });
+    } catch (e) {
+      return {
+        kind: "unreadable",
+        path: configPath,
+        message: e instanceof Error ? e.message : String(e),
+      };
+    }
+    if (st !== undefined && !st.isFile()) {
+      return {
+        kind: "unreadable",
+        path: configPath,
+        message: "not a file",
+      };
+    }
+  }
+
+  // [LAW:dataflow-not-control-flow] Collision detection runs independent of
+  // load success — mirror of RenderCache.reloadInto: even if the .json5 fails
+  // to parse, the author still wants to know a shadowed .json sibling exists.
+  const warnings: string[] = [];
+  const collision = detectConfigCollisions(cwd, cwd);
+  if (collision !== null) warnings.push(collision);
+
+  try {
+    const rendered = loadRegisterRender(configPath, cwd, warnings);
+    return { kind: "clean", configPath, warnings, rendered };
+  } catch (e) {
+    // A filesystem error on the config file itself (ENOENT/EACCES from
+    // loadConfig's read — errno errors carry the failing `.path`, which is the
+    // discriminator against deeper fs failures) is the `unreadable` outcome:
+    // the named file could not be read at all, distinct from a file that read
+    // but is invalid. [LAW:no-silent-failure] — never a fall-through to the
+    // bundled default. Duck-typed, not `instanceof Error`: fs errors can cross
+    // a realm boundary (jest/graceful-fs), where instanceof lies.
+    const errno = e as Partial<NodeJS.ErrnoException> | null;
+    if (
+      configPath !== null &&
+      typeof errno === "object" &&
+      errno !== null &&
+      typeof errno.code === "string" &&
+      errno.path === configPath &&
+      typeof errno.message === "string"
+    ) {
+      return { kind: "unreadable", path: configPath, message: errno.message };
+    }
+    // Same classification RenderCache.reloadInto applies: ConfigError and
+    // register/render throws (template parse, MissingFieldError, action arity)
+    // are all author-facing diagnostics — the daemon would surface each via
+    // composeWithDiagnostics, so check surfaces each as fatal text.
+    const message =
+      e instanceof ConfigError
+        ? e.message
+        : e instanceof Error
+          ? e.message
+          : String(e);
+    return { kind: "fatal", configPath, message, warnings };
+  }
+}
+
+// The buildState + per-request-render mirror: every call below is the function
+// the daemon calls, in the daemon's order [LAW:single-enforcer]. Returns the
+// rendered line; appends the register pass's advisory `loadWarnings` (partial
+// declaration failures) to `warnings` — the same channel RenderCache merges
+// them into.
+function loadRegisterRender(
+  configPath: string | null,
+  cwd: string,
+  warnings: string[],
+): string {
+  const { config: merged, source } = loadConfig(configPath);
+  const config = validateConfig(merged, configPath ?? "<default>", source);
+
+  const store = new VariableStore();
+  const registry = new SourceRegistry(
+    store,
+    config.globals.default_empty_value ?? "",
+    undefined,
+    new SessionState(),
+  );
+  try {
+    const compiled = registerDslConfig(config, registry, { cwd });
+    // Registered before the validator pass so a derive throw (a key-kind
+    // clash) still carries the partial-load warnings into the fatal outcome.
+    warnings.push(...compiled.loadWarnings);
+    // Derivation only (the throw-on-clash coherence pass over the action
+    // table); the daemon additionally registers the results in its global
+    // validator registry, which a one-shot check has no wire to serve.
+    deriveActionValidators(config);
+
+    // Fresh session (no clicked theme/style), so the session half of each
+    // resolution is null — the config default over the floor, exactly what the
+    // daemon renders for a session that has never clicked.
+    const effectiveTheme = effectiveThemeName(null, config.globals.palette);
+    return renderDsl(
+      config,
+      compiled,
+      store,
+      registry,
+      checkPayload(effectiveTheme),
+      resolverForThemeName(effectiveTheme),
+      {
+        style: effectiveStripStyle(null, config.globals.style),
+        width: CHECK_WIDTH,
+        colorCompatibility:
+          config.globals.colorCompatibility ?? DEFAULT_COLOR_COMPATIBILITY,
+        wrap: config.globals.autoWrap ?? DEFAULT_WRAP,
+        padding: config.globals.padding ?? DEFAULT_PADDING,
+        charset: config.globals.charset ?? DEFAULT_CHARSET,
+      },
+    );
+  } finally {
+    // [LAW:single-enforcer] The registry owns every async handle the config
+    // declared (timers, fs watchers, git subscriptions); a one-shot check must
+    // not leak them past the verdict.
+    registry.dispose();
+  }
+}
+
+const EXIT_CLEAN = 0;
+const EXIT_FATAL = 1;
+const EXIT_USAGE = 2;
+
+// [LAW:dataflow-not-control-flow] The outcome → (streams, exit-code) mapping is
+// DATA: a total fold over CheckOutcome returning one descriptor; runCheck runs
+// the two unconditional writes + exit against it. Verdict on stdout, every
+// diagnostic (warnings included) on stderr — so `check` in a pipeline yields a
+// parseable verdict while a human still sees the advisories.
+export interface CheckPlan {
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly code: number;
+}
+
+function warningLines(warnings: readonly string[]): string {
+  return warnings.map((w) => `warning: ${w}\n`).join("");
+}
+
+export function checkPlan(o: CheckOutcome): CheckPlan {
+  switch (o.kind) {
+    case "clean": {
+      const where = o.configPath ?? "bundled default (no config file found)";
+      const count =
+        o.warnings.length > 0
+          ? ` (${o.warnings.length} warning${o.warnings.length === 1 ? "" : "s"})`
+          : "";
+      return {
+        stdout: `✓ ${where}: config OK${count}\n`,
+        stderr: warningLines(o.warnings),
+        code: EXIT_CLEAN,
+      };
+    }
+    case "fatal":
+      return {
+        stdout: "",
+        stderr:
+          warningLines(o.warnings) +
+          `✗ ${o.configPath ?? "<default>"}\n${o.message}\n`,
+        code: EXIT_FATAL,
+      };
+    case "unreadable":
+      return {
+        stdout: "",
+        stderr: `check: cannot read ${o.path}: ${o.message}\n`,
+        code: EXIT_USAGE,
+      };
+  }
+}
+
+// `cc-candybar check [path]` — the argv binding. Extra arguments and an empty
+// path argument are usage errors (loud, not silently ignored — the likeliest
+// cause is an unquoted or mis-expanded shell variable). An empty string is not
+// "no argument": `checkConfig(undefined)` means "resolve like the daemon",
+// while `""` is a malformed target that would otherwise EISDIR on the cwd.
+export function runCheck(args: readonly string[]): never {
+  if (args.length > 1 || args[0] === "") {
+    process.stderr.write(
+      "check: expected at most one non-empty path\nUsage: cc-candybar check [config-file]\n",
+    );
+    process.exit(EXIT_USAGE);
+  }
+  const plan = checkPlan(checkConfig(args[0]));
+  process.stdout.write(plan.stdout);
+  process.stderr.write(plan.stderr);
+  process.exit(plan.code);
+}

package/src/config/cli.ts

@@ -1,128 +1,17 @@
-// [LAW:single-enforcer] Config-tooling CLI entry points. `lint` and `schema`
-// share one module because they share one change-reason: the config grammar.
-// Neither carries validation or schema LOGIC — `lint` is a second entry point
-// into the loader (the single config-validation enforcer the daemon also uses),
-// and `schema` serves the build-generated artifact (derived from the config
-// types). Both are bindings, not reimplementations [LAW:one-source-of-truth].
+// [LAW:single-enforcer] Config-tooling CLI entry point for `schema`. It carries
+// no schema LOGIC — it serves the build-generated artifact (derived from the
+// loader's declarations), so it is a binding, not a reimplementation
+// [LAW:one-source-of-truth]. Config *validation* lives in `cc-candybar check`
+// (src/check.ts) — the full-pipeline verdict command; the old `lint` is its
+// alias.
 
 import fs from "node:fs";
 import path from "node:path";
 import process from "node:process";
-import { loadConfig, validateConfig } from "./dsl-loader.js";
-import { ConfigError } from "./loader/diagnostics.js";
 
-// Exit codes are a contract (the CLI guideline: not just 0/1), so scripts and
-// editors can distinguish "your config is wrong" from "I couldn't run":
-//   0 — config is valid
-//   1 — config is invalid (ConfigError: structural, cross-ref, or cycle)
-//   2 — usage error or the file could not be read
 const EXIT_VALID = 0;
-const EXIT_INVALID = 1;
 const EXIT_USAGE = 2;
 
-// [LAW:dataflow-not-control-flow] The lint result is DATA — a pure function of
-// the target file's contents — discriminated into the three outcomes the exit-
-// code contract projects. `lintConfig` carries the decision; `runLint` only maps
-// it to (stream, exit). The decision is unit-testable without spawning a process
-// or stubbing process.exit, which is what makes the exit-code goal verifiable.
-export type LintOutcome =
-  | { readonly kind: "valid"; readonly path: string }
-  | { readonly kind: "invalid"; readonly message: string }
-  | {
-      readonly kind: "unreadable";
-      readonly path: string;
-      readonly message: string;
-    };
-
-// Run the real loader (parse → merge-with-default → cross-ref + cycle validation)
-// against an arbitrary file. No daemon: the loader imports only fs, JSON5, and
-// pure validators, so the same errors the daemon would surface at render time are
-// surfaced here ahead of time.
-//
-// [LAW:single-enforcer] loadConfig + validateConfig is the identical pipeline
-// RenderCache.reloadInto runs in the daemon — the validation authority is one
-// function, so lint cannot drift from production. The source we read is passed to
-// validateConfig only to sharpen line numbers (semantic issues map to lines).
-export function lintConfig(target: string): LintOutcome {
-  const resolved = path.resolve(target);
-
-  let source: string;
-  try {
-    source = fs.readFileSync(resolved, "utf-8");
-  } catch (e) {
-    return {
-      kind: "unreadable",
-      path: target,
-      message: e instanceof Error ? e.message : String(e),
-    };
-  }
-
-  try {
-    const { config } = loadConfig(resolved);
-    validateConfig(config, resolved, source);
-  } catch (e) {
-    if (e instanceof ConfigError)
-      return { kind: "invalid", message: e.message };
-    throw e;
-  }
-
-  return { kind: "valid", path: target };
-}
-
-// `cc-candybar lint <path>` — the argv binding. Missing-arg is a usage concern
-// (not a lint outcome), handled here; everything else is the projection of
-// lintConfig's outcome onto the stream + exit-code contract.
-export function runLint(args: readonly string[]): void {
-  const target = args[0];
-  if (target === undefined || target === "") {
-    process.stderr.write(
-      "lint: missing <path>\nUsage: cc-candybar lint <config-file>\n",
-    );
-    process.exit(EXIT_USAGE);
-  }
-  applyLintOutcome(lintConfig(target));
-}
-
-// [LAW:dataflow-not-control-flow] The outcome → (stream, text, exit-code) mapping
-// is DATA. `lintPlan` is a total fold returning that descriptor (a non-returning
-// arm fails the typecheck, so the projection stays exhaustive over LintOutcome);
-// `applyLintOutcome` runs the single write + exit against it. The side effects
-// are unconditional; the data decides their content.
-interface LintPlan {
-  readonly stream: NodeJS.WriteStream;
-  readonly text: string;
-  readonly code: number;
-}
-
-function lintPlan(o: LintOutcome): LintPlan {
-  switch (o.kind) {
-    case "valid":
-      return {
-        stream: process.stdout,
-        text: `✓ ${o.path}: config valid\n`,
-        code: EXIT_VALID,
-      };
-    case "invalid":
-      return {
-        stream: process.stderr,
-        text: o.message + "\n",
-        code: EXIT_INVALID,
-      };
-    case "unreadable":
-      return {
-        stream: process.stderr,
-        text: `lint: cannot read ${o.path}: ${o.message}\n`,
-        code: EXIT_USAGE,
-      };
-  }
-}
-
-function applyLintOutcome(o: LintOutcome): never {
-  const plan = lintPlan(o);
-  plan.stream.write(plan.text);
-  process.exit(plan.code);
-}
-
 // Read the build-generated JSON Schema for the config file shape (RawDslConfig),
 // or null when the artifact is absent. Pure read — `runSchema` owns the side
 // effects, so the locate-and-read path is testable.
@@ -137,7 +26,19 @@ export function loadSchemaText(): string | null {
 // time (scripts/gen-schema.ts → emitConfigSchema); served verbatim here (the
 // emitter runs at build, not ship time).
 export function runSchema(): void {
-  const text = loadSchemaText();
+  // [LAW:no-silent-failure] A schema that exists but cannot be read (EACCES, a
+  // deletion racing the existsSync in locateSchema) is a distinct failure from
+  // schema-not-found — report it as what it is, not a misleading top-level
+  // render error.
+  let text: string | null;
+  try {
+    text = loadSchemaText();
+  } catch (e) {
+    process.stderr.write(
+      `schema: cannot read bundled schema: ${e instanceof Error ? e.message : String(e)}\n`,
+    );
+    process.exit(EXIT_USAGE);
+  }
   if (text === null) {
     process.stderr.write(
       "schema: bundled schema not found (expected schema/cc-candybar.schema.json). " +

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

@@ -528,12 +528,9 @@ export const DEFAULT_DSL_CONFIG = {
     // and the render's read are one value. Empty default ⇒ the daemon's
     // "powerline" floor is in effect and styleControl shows "(default)".
     activeStyle: { kind: "state", key: "style", default: "" },
-    // The style picker's page index. Open/closed is the synthesized menus.* key
-    // the styleControl's {{ menu }} owns — NOT this var, which is purely the page
-    // the picker paginates by (default page 0; the disclosure resets it to 0 on
-    // every toggle, so a reopened menu never lands on a stale page). The stylePage
-    // action below declares the int gate this var reads back.
-    stylePage: { kind: "state", key: "style-page", default: "0" },
+    // No page-cursor var: the styleControl {{ menu }} synthesizes its own page
+    // cursor (state var + int action, named by menuPageKey) under the reserved
+    // menus.* namespace, alongside its open-state.
   },
 
   // ─── Segments ──────────────────────────────────────────────────────────────
@@ -794,15 +791,16 @@ export const DEFAULT_DSL_CONFIG = {
     // onto the line below this row when open. [LAW:one-type-per-behavior] "a menu
     // that opens and closes" is one behavior the substrate already expresses — no
     // bespoke open-action + page-cursor-as-open-state + when-gated reveal row.
-    // paged omitted ⇒ false ⇒ one full-width page (the 3 powerline shapes are a
-    // small domain; FlexStrip soft-wraps if needed). closeOnPick omitted ⇒ false
-    // ⇒ stay-open, so shapes can be tried in a row; the ▾ collapses.
+    // The apply name is the whole declaration: the page cursor (state var + int
+    // gate) is synthesized from the menu's identity, and the defaults are the
+    // canonical path — paged (the 3 powerline shapes fit one page, so no arrows
+    // render) and stay-open, so shapes can be tried in a row; ▾/✕ collapse.
     // [LAW:dataflow-not-control-flow] No display state from the provider — the
     // label is the one "style" value the click writes and the render reads.
     styleControl: {
       template:
         "✦ {{ if .activeStyle }}{{ .activeStyle }}{{ else }}(default){{ end }} " +
-        '{{ menu "applyStyle" "stylePage" }}',
+        '{{ menu "applyStyle" }}',
       bg: "surface",
       fg: "foreground",
     },
@@ -876,18 +874,17 @@ export const DEFAULT_DSL_CONFIG = {
     openProject: { open: "{{ .project_dir }}" },
     openTranscript: { open: "{{ .transcript_path }}" },
 
-    // [LAW:locality-or-seam] The style menu's behaviors, decoupled by NAME from the
-    // styleControl {{ menu }} above. The disclosure's open-state toggle + its
-    // backing state var are SYNTHESIZED by the menu pass (under the reserved
-    // menus.* namespace) — no hand-authored open/close action. These two are the
-    // picker body's effects, both gated by derivation (deriveActionValidators):
-    // applyStyle writes the chosen shape, gated to the STRIP_STYLES allow-list
-    // because its value source is `from: "styles"`; stylePage is the page cursor's
-    // unbounded int gate (←/→ navigation + the disclosure's page-0 reset). The
+    // [LAW:locality-or-seam] The style menu's behavior, decoupled by NAME from the
+    // styleControl {{ menu }} above. The disclosure's open-state toggle, its
+    // backing state var, AND the picker body's page cursor (state var + int
+    // action) are all SYNTHESIZED by the menu pass (under the reserved menus.*
+    // namespace) — no hand-authored open/close or page plumbing. This one action
+    // is the picker body's apply effect, gated by derivation
+    // (deriveActionValidators): it writes the chosen shape, gated to the
+    // STRIP_STYLES allow-list because its value source is `from: "styles"`. The
     // rendered click and the wire gate share that one source — a template cannot
     // smuggle an un-gated style write.
     applyStyle: { set: "style", from: "styles" },
-    stylePage: { set: "style-page", int: true },
   },
 
   // [LAW:single-enforcer] / [LAW:one-source-of-truth] Display-formatting policy

package/src/config/disclosure.ts

@@ -0,0 +1,55 @@
+// [LAW:one-source-of-truth] THE disclosure primitive: the one toggle machinery
+// that both group sugar (`kind: "group"`, src/config/loader/layout.ts) and the
+// `{{ menu }}` helper (src/config/loader/menu-synth.ts + src/render/menu.ts) are
+// built on. A disclosure is a binary toggle over a SessionState key: the key
+// holds either the CLOSED sentinel or a single MEMBER name; a `cycle` action
+// flips between the two; a ▸/▾ glyph shows which state it is in; sibling
+// disclosures sharing one key become mutually exclusive (an accordion) because
+// one key holds one open member. Group and menu differ ONLY in their BODY (group
+// reveals an arbitrary layout container gated by a `when`; menu drops a picker
+// grid below the row) and in where the trigger lives (group synthesizes a toggle
+// segment; the menu helper IS the trigger). The toggle itself — sentinel, glyphs,
+// the `state` var, the `cycle` action — is single-sourced HERE so the two
+// body-kinds cannot drift [LAW:one-type-per-behavior][LAW:decomposition].
+//
+// [LAW:one-way-deps] This module is intentionally PURE — it imports only decl
+// TYPES (erased at build) and holds no loader (`ValidateCtx`, diagnostics) nor
+// render (rich-js) dependency, so both the loader synthesis passes and the render
+// helper can share it without dragging one layer into the other. The loader-side
+// reserved-namespace collision check — the other half of the shared machinery,
+// which needs the validation context — lives in
+// `src/config/loader/reserved-namespace.ts`.
+
+import type { ActionDecl } from "./action.js";
+import type { VariableDecl } from "./dsl-types.js";
+
+// The "nothing open" sentinel a disclosure's key starts from and returns to on
+// close. A disclosure's MEMBER (a group name / a menu apply-action name) may
+// never equal this — an equal member would make the cycle `[closed, "closed"]`
+// (two identical members, never openable), which both synthesis passes reject.
+export const DISCLOSURE_CLOSED = "closed";
+
+// [LAW:representation] The disclosure glyph vocabulary — one pair for the whole
+// bar so every disclosure reads the same (trailing the label/content it gates,
+// per pdu.8): collapsed ▸, expanded ▾.
+export const DISCLOSURE_GLYPH_CLOSED = "▸";
+export const DISCLOSURE_GLYPH_OPEN = "▾";
+
+// [LAW:single-enforcer] THE backing `state` variable a disclosure key implies:
+// it holds the open member's name and defaults to `def` (the CLOSED sentinel for
+// an independent disclosure, or an initially-open member for a group's
+// `open: true`). One shape, so a group var and a menu var declared on one key
+// cannot disagree on kind or key.
+export function disclosureStateVar(key: string, def: string): VariableDecl {
+  return { kind: "state", key, default: def };
+}
+
+// [LAW:single-enforcer] THE toggle action a disclosure realizes: a binary `cycle`
+// between the CLOSED sentinel and the member (ordered closed-first, so an unset or
+// sibling-held key counts as the first member — the toggle renders ▸ and a click
+// writes the member, opening it and auto-closing any accordion sibling). The
+// derived click gate (`deriveActionValidators`) reads this like every other
+// `set`, so a disclosure toggle needs no parallel verb [LAW:single-enforcer].
+export function disclosureCycleAction(key: string, member: string): ActionDecl {
+  return { set: key, cycle: [DISCLOSURE_CLOSED, member] };
+}