@promptctl/cc-candybar 1.36.0 → 1.37.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@promptctl/cc-candybar",
-  "version": "1.36.0",
+  "version": "1.37.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.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"
+    "@promptctl/cc-candybar-darwin-arm64": "1.37.0",
+    "@promptctl/cc-candybar-darwin-x64": "1.37.0",
+    "@promptctl/cc-candybar-linux-x64": "1.37.0",
+    "@promptctl/cc-candybar-linux-arm64": "1.37.0"
   }
 }

package/src/check.ts

@@ -36,14 +36,14 @@ import {
   effectiveLookName,
   lookKeyByName,
   effectiveStripStyle,
+  effectiveAutoWrap,
+  effectivePadding,
 } from "./themes/policy.js";
 import { paletteForThemeName } from "./themes/palette-resolvers.js";
 import { effectivePresetName, presetGlobals } from "./config/presets.js";
 import {
   DEFAULT_CHARSET,
   DEFAULT_COLOR_COMPATIBILITY,
-  DEFAULT_PADDING,
-  DEFAULT_WRAP,
 } from "./render/strip.js";
 import type { EffectiveGlobals } from "./daemon/render-payload.js";
 
@@ -321,8 +321,8 @@ function loadRegisterRender(
       theme: effectiveThemeName(null, globals.palette),
       look: effectiveLookName(null, globals.look, config.looks),
       style: effectiveStripStyle(null, globals.style),
-      autoWrap: globals.autoWrap ?? DEFAULT_WRAP,
-      padding: globals.padding ?? DEFAULT_PADDING,
+      autoWrap: effectiveAutoWrap(null, globals.autoWrap),
+      padding: effectivePadding(null, globals.padding),
       charset: globals.charset ?? DEFAULT_CHARSET,
       colorCompatibility:
         globals.colorCompatibility ?? DEFAULT_COLOR_COMPATIBILITY,

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

@@ -28,6 +28,7 @@
 
 import type { DslConfig, LayoutNode, SegmentDecl } from "./dsl-types.js";
 import { parseDslConfig } from "./dsl-loader.js";
+import { BOOLEAN_MEMBERS, PADDING_RANGE } from "../themes/policy.js";
 import { mergeWithDefault } from "./loader/merge.js";
 
 // ─── Shared template fragments ───────────────────────────────────────────────
@@ -250,7 +251,11 @@ function etaHeatFg(etaRef: string, warnRef: string): string {
 // theme/style/look/preset (session `set` for a per-conversation preview, PLUS
 // a persist-forever twin — candybar-config-engine-71o.5, brandon-presets-0yk.3
 // — for pinning the choice as everyone's default), the four .3 globals
-// steppers (persist-only, no SessionState half at all), and one .6
+// steppers (persist-only HERE — `autoWrap`/`padding` have gained a session
+// half since, but the drawer's own controls stay durable-by-default until
+// candybar-settings-ui-aok.3 gives the panel one `persist?` toggle instead of
+// a spelling per row; `charset`/`colorCompatibility` have no session half at
+// all, by design), and one .6
 // segment-scoped persist control (directoryPaletteControl, persist-only like
 // the four steppers — a per-segment palette pin, not a whole-bar default).
 // Placed as a sibling in row 1's horizontal container, toggled from beside the
@@ -1222,8 +1227,11 @@ export const RAW_DEFAULT_DSL_CONFIG = {
     // ── The four .3 globals steppers, folded into the settingsDrawer group
     // (candybar-config-engine-71o.4) alongside theme/style/look above. Each
     // pairs a `persist` control with a `↺` reset (docs' persist/reset
-    // convention) — these four have no SessionState half at all, so persist
-    // is their only seam, unlike theme/style/look's session `set`. Labels
+    // convention) — `charset`/`colorCompatibility` have no SessionState half
+    // at all, so persist is genuinely their only seam, while
+    // `autoWrap`/`padding` do have one and are simply spelled durable here
+    // (candybar-settings-ui-aok.3 owns whether the panel offers the choice).
+    // Labels
     // read `.field.effective` (the daemon-resolved value BuildLineOptions
     // actually rendered with), never a restated literal.
     charsetControl: {
@@ -1421,8 +1429,11 @@ export const RAW_DEFAULT_DSL_CONFIG = {
     // (candybar-config-engine-71o.4), decoupled by NAME from
     // charsetControl/colorCompatControl/wrapToggleControl/paddingControl
     // below. Unlike theme/style/look (a per-session experiment via `set`),
-    // these four have no SessionState half at all — .3's handoff established
-    // `persist` as their ONLY seam — so every one of these writes the
+    // these four are spelled durable: `charset`/`colorCompatibility` have no
+    // SessionState half at all, and `autoWrap`/`padding` have one
+    // (candybar-settings-ui-aok.2) but keep persist as the DRAWER's spelling
+    // until .3 collapses the twins behind one `persist?`. So every one of
+    // these writes the
     // config-file DEFAULT through the daemon-owned overrides layer (never the
     // hand-authored file itself), gated by the SAME deriveActionValidators
     // pass as a `set` (persist mirrors set's value-source shapes one for
@@ -1435,10 +1446,14 @@ export const RAW_DEFAULT_DSL_CONFIG = {
       from: "colorCompatibilities",
     },
     resetColorCompat: { reset: "colorCompatibility" },
-    toggleWrapForever: { persist: "autoWrap", cycle: ["true", "false"] },
+    // [LAW:one-source-of-truth] The toggle's members and the stepper's bounds
+    // are the SAME literals the resolvers parse a session pick with
+    // (BOOLEAN_MEMBERS / PADDING_RANGE in themes/policy.ts) — a click cannot
+    // write a value the render's own resolution would then refuse.
+    toggleWrapForever: { persist: "autoWrap", cycle: [...BOOLEAN_MEMBERS] },
     resetAutoWrap: { reset: "autoWrap" },
-    paddingDownForever: { persist: "padding", min: 0, max: 16, by: -1 },
-    paddingUpForever: { persist: "padding", min: 0, max: 16, by: 1 },
+    paddingDownForever: { persist: "padding", ...PADDING_RANGE, by: -1 },
+    paddingUpForever: { persist: "padding", ...PADDING_RANGE, by: 1 },
     resetPadding: { reset: "padding" },
 
     // [LAW:locality-or-seam] The segment-palette control's behavior

package/src/config/loader/globals.ts

@@ -7,6 +7,7 @@ import { type Globals } from "../dsl-types.js";
 import {
   CHARSETS,
   COLOR_COMPATIBILITIES,
+  PADDING_RANGE,
   STRIP_STYLES,
   type ColorCompatibility,
 } from "../../themes/policy.js";
@@ -84,7 +85,11 @@ const GLOBALS_FIELDS: FieldSpecMap<Globals> = {
   // 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:one-source-of-truth] The bound comes from PADDING_RANGE, the same
+  // literal the bundled default's stepper actions bound clicks by and the
+  // session-half parse admits values from — so the file, the click, and the
+  // session pick cannot end up honouring three different ranges.
+  padding: optionalIntSpec(PADDING_RANGE),
   // [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.

package/src/config/presets.ts

@@ -168,9 +168,14 @@ export function presetGlobals(config: DslConfig, name: string): Globals {
 // that is a typo in a file the author can see and fix — but a value that
 // only exists because the overrides layer supplied it gets the SAME
 // treatment a stale SessionState pick already gets from effectivePresetName:
-// collapse to the floor, visibly, never throw. Dropping the field here (so
-// it never reaches validateConfig) is what makes that collapse happen for
-// this layer too, instead of a fatal error replacing the whole bar.
+// an undeclared name is not a pick at all, so the resolution moves on to the
+// next rung of the precedence chain — visibly, never a throw. (For a stale
+// SESSION pick that next rung is the config's own `globals.preset`, and only
+// then the floor; for the field dropped here it is whatever the config file
+// itself declares. Same rule, different starting rung —
+// see effectiveGlobal in themes/policy.ts.) Dropping the field here (so it
+// never reaches validateConfig) is what applies that rule to this layer too,
+// instead of a fatal error replacing the whole bar.
 export function sanitizePersistedPresetOverride(
   globalsOverride: Partial<Globals>,
   declaredPresets: Readonly<Record<string, PresetDecl>>,

package/src/daemon/render-payload.ts

@@ -48,11 +48,13 @@ import type {
 // BuildLineOptions), so the value a trigger label displays and the value
 // that actually shaped the render can never disagree — the same reasoning
 // theme/look already followed, generalized to every globals field a menu or
-// stepper can persist. `theme`/`look`/`style` compose SessionState over the
-// config default (a session pick can diverge from the persisted default for
-// its own session); `charset`/`colorCompatibility`/`autoWrap`/`padding` have
-// no SessionState half today, so their "effective" value is just the
-// resolved config global over its floor constant.
+// stepper can persist. `theme`/`look`/`style`/`autoWrap`/`padding` compose
+// SessionState over the config default (a session pick can diverge from the
+// persisted default for its own session); `charset` and `colorCompatibility`
+// have no SessionState half — they describe the terminal (glyph coverage,
+// colour depth) rather than a per-session taste, so the resolved config global
+// over its floor constant is their whole resolution. See CHARSETS in
+// themes/policy.ts for why that is a decision rather than a gap.
 export interface EffectiveGlobals {
   readonly theme: string;
   readonly look: string;

package/src/daemon/server.ts

@@ -65,6 +65,8 @@ import { expandHome } from "../config/dsl-loader.js";
 import { renderDsl } from "../dsl/render.js";
 import {
   effectiveStripStyle,
+  effectiveAutoWrap,
+  effectivePadding,
   effectiveThemeName,
   effectiveLookName,
   lookKeyByName,
@@ -867,11 +869,12 @@ async function handleRequest(req: Request): Promise<HandledRequest> {
         //
         // [LAW:one-source-of-truth] Every globals field a menu/stepper can
         // persist (candybar-config-engine-71o.3), resolved ONCE into one
-        // struct: theme/look/style compose the session's click (SessionState)
-        // over the config default over a floor — a click recolors/reshapes the
-        // whole bar on the next render; charset/colorCompatibility/autoWrap/
-        // padding have no SessionState half today, so their "effective" value
-        // is just the config global over its floor constant. This struct feeds
+        // struct: theme/look/style/autoWrap/padding compose the session's click
+        // (SessionState) over the config default over a floor — a click
+        // recolors/reshapes the whole bar on the next render; charset and
+        // colorCompatibility describe the TERMINAL rather than a taste and so
+        // have no SessionState half at all, making the config global over its
+        // floor constant their whole resolution. This struct feeds
         // BOTH the payload's `*.effective` fields (trigger labels) AND
         // renderOpts below (the actual render) — one resolution, two readers,
         // so a label can never disagree with what was rendered.
@@ -918,8 +921,18 @@ async function handleRequest(req: Request): Promise<HandledRequest> {
             sessionState.get(req.hookData.session_id, "style"),
             globals.style,
           ),
-          autoWrap: globals.autoWrap ?? DEFAULT_WRAP,
-          padding: globals.padding ?? DEFAULT_PADDING,
+          autoWrap: effectiveAutoWrap(
+            sessionState.get(req.hookData.session_id, "autoWrap"),
+            globals.autoWrap,
+          ),
+          padding: effectivePadding(
+            sessionState.get(req.hookData.session_id, "padding"),
+            globals.padding,
+          ),
+          // charset and colorCompatibility have no session half by design —
+          // they describe the terminal, not a taste (see CHARSETS in
+          // themes/policy.ts) — so the config global over its floor is their
+          // whole resolution.
           charset: globals.charset ?? DEFAULT_CHARSET,
           colorCompatibility:
             globals.colorCompatibility ?? DEFAULT_COLOR_COMPATIBILITY,

package/src/demo/dsl.ts

@@ -33,6 +33,8 @@ import { listResolvablePaletteNames } from "../themes/policy.js";
 import {
   effectiveThemeName,
   effectiveLookName,
+  effectiveAutoWrap,
+  effectivePadding,
   lookKeyByName,
   paletteForThemeName,
 } from "../themes/index.js";
@@ -41,9 +43,7 @@ import { registerDslConfig, renderDsl } from "../dsl/render.js";
 import {
   DEFAULT_CHARSET,
   DEFAULT_COLOR_COMPATIBILITY,
-  DEFAULT_PADDING,
   DEFAULT_TERMINAL_WIDTH,
-  DEFAULT_WRAP,
 } from "../render/strip.js";
 import { applyClaudeCodeReserve } from "../utils/terminal-width.js";
 
@@ -139,10 +139,11 @@ try {
         width: applyClaudeCodeReserve(
           process.stdout.columns ?? DEFAULT_TERMINAL_WIDTH,
         ),
-        // Same resolution the daemon applies: the config global over the
-        // default-on floor.
-        wrap: globals.autoWrap ?? DEFAULT_WRAP,
-        padding: globals.padding ?? DEFAULT_PADDING,
+        // Same resolvers the daemon applies, with a null session pick — the
+        // demo has no SessionState, so both land on the config default over
+        // their floor.
+        wrap: effectiveAutoWrap(null, globals.autoWrap),
+        padding: effectivePadding(null, globals.padding),
         charset: globals.charset ?? DEFAULT_CHARSET,
       },
       undefined,

package/src/render/strip.ts

@@ -37,16 +37,12 @@ export type { Charset, ColorCompatibility, StripStyle };
 // applyClaudeCodeReserve from src/utils/terminal-width).
 export const DEFAULT_TERMINAL_WIDTH = 120;
 
-// [LAW:one-source-of-truth] The one statement of the globals.autoWrap
-// default (on — current behavior). Every resolver of the config global
-// (`globals.autoWrap ?? DEFAULT_WRAP`) derives from this constant.
-export const DEFAULT_WRAP = true;
-
-// [LAW:one-source-of-truth] The one statement of the globals.padding
-// default (one space per side inside each segment cell — current behavior,
-// matching the legacy display.padding). Every resolver of the config global
-// (`globals.padding ?? DEFAULT_PADDING`) derives from this constant.
-export const DEFAULT_PADDING = 1;
+// [LAW:one-source-of-truth] autoWrap's and padding's defaults live in
+// themes/policy.ts beside their resolvers and padding's range, because the
+// config loader needs them too and config must not import render
+// [LAW:one-way-deps]. Re-exported here on the same terms as the types above, so
+// render-layer consumers keep importing them from the strip module.
+export { DEFAULT_WRAP, DEFAULT_PADDING } from "../themes/policy.js";
 
 // [LAW:one-source-of-truth] The one statement of the globals.charset default
 // (powerline unicode glyphs — current behavior, matching the legacy

package/src/themes/index.ts

@@ -9,6 +9,8 @@ export {
   effectiveLookName,
   lookKeyByName,
   effectiveStripStyle,
+  effectiveAutoWrap,
+  effectivePadding,
   isStripStyle,
   listResolvablePaletteNames,
   STRIP_STYLES,

package/src/themes/policy.ts

@@ -1,9 +1,17 @@
-// [LAW:single-enforcer] The slim name/string policy layered on top of rich-js's
-// theme registry. cc-candybar selects theme NAMES and style IDENTIFIERS here;
-// every color *value* operation (hydrate hex, resolve specs, darken/contrast,
-// hue/transpose) lives in rich-js. This module only moves strings — no
-// Palette, no ColorRgba, no hex. The semantic/anchor knowledge
-// (which tokens keep their hue) stays in rich-js (ANCHORED_ROOTS), not here.
+// [LAW:single-enforcer] The vocabulary and the resolution for every `globals`
+// field a config can set or a click can pick: what values each field admits,
+// what its floor is, and the one function that turns a session pick, a config
+// default and that floor into the value a render actually uses.
+//
+// It sits in the themes module because theme/look/style were the first three
+// fields to need it, and it is a LEAF: the config loader (validation, JSON
+// schema) and the render layer both import it, which is what keeps a
+// config↔render cycle from forming [LAW:one-way-deps].
+//
+// No color arithmetic lives here. cc-candybar selects theme NAMES and style
+// IDENTIFIERS; every color *value* operation (hydrate hex, resolve specs,
+// darken/contrast, hue/transpose) lives in rich-js, as does the semantic/anchor
+// knowledge of which tokens keep their hue (ANCHORED_ROOTS).
 
 import {
   listThemePalettes,
@@ -22,19 +30,55 @@ export function resolvePaletteName(name: string): string {
   return THEME_ALIASES[name] ?? name;
 }
 
-// The theme name a render should use, as data. [LAW:dataflow-not-control-flow]
-// The `??` chain is the precedence — session choice over config default over the
-// built-in — with no "if the session has a theme" branch. The session value is
-// the user's live per-session pick (null when unset); globals.palette is the
-// config default; "textual-dark" is the always-present floor.
+// --- The one globals resolution ---
+
+// [LAW:one-type-per-behavior] THE resolution every globals field a click can
+// pick shares: the session's own value, over the config default, over a floor.
+// Written once because the fields differ only in DATA — which floor, and how a
+// raw SessionState string becomes a value of that field's type. Theme, look,
+// preset, style, autoWrap and padding are all this function with different
+// arguments, so the precedence order cannot land on one field and miss another.
+//
+// [LAW:dataflow-not-control-flow] The `??` chain IS the precedence; there is no
+// "does this session have one" branch. A session that has never clicked passes
+// null and lands on the config default by the same code path a session that
+// clicked lands on its pick.
+//
+// [LAW:parse-dont-validate] `parseSession` is the boundary between an untyped
+// SessionState string and this field's domain: it returns the typed value or
+// null, and null means "no session pick" — indistinguishable, on purpose, from
+// never having clicked. That is what makes a stale entry from a prior config's
+// vocabulary (or a value a since-narrowed gate would now refuse) resolve to the
+// default rather than throw or render something the label disagrees with
+// [LAW:no-silent-failure] — the caller publishes what this returns as
+// `<field>.effective`, so bar and label always trace to one value.
+export function effectiveGlobal<T>(
+  sessionPick: string | null,
+  configDefault: T | null | undefined,
+  floor: T,
+  parseSession: (raw: string) => T | null,
+): T {
+  const picked = sessionPick === null ? null : parseSession(sessionPick);
+  return picked ?? configDefault ?? floor;
+}
+
+// The theme name a render should use, as data.
 // [LAW:one-source-of-truth] The single definition of "which theme is effective";
 // every render derives basePalette through this, so the rendered palette can
-// never disagree with the chosen theme.
+// never disagree with the chosen theme. The theme domain is OPEN — registry
+// names, aliases, and per-session sentinels all resolve downstream — so its
+// parse is identity: there is no membership to check here, and pretending
+// otherwise would collapse names `paletteForThemeName` handles fine.
 export function effectiveThemeName(
   sessionTheme: string | null,
   globalsPalette: string | undefined,
 ): string {
-  return sessionTheme ?? globalsPalette ?? "textual-dark";
+  return effectiveGlobal(
+    sessionTheme,
+    globalsPalette,
+    "textual-dark",
+    (raw) => raw,
+  );
 }
 
 function listThemeAliases(): readonly string[] {
@@ -53,20 +97,16 @@ export function listResolvablePaletteNames(): readonly string[] {
 
 // --- Per-config member selection ---
 
-// [LAW:one-type-per-behavior] THE resolution shape shared by every selection
-// whose domain is PER-CONFIG (declared in the config, not a registry-static
-// list): session choice over config default over a floor, then collapse to the
-// floor if the chosen name is not a declared member. `looks` and `presets` are
-// both exactly this — what differs between them is only the floor name and
-// which map holds the members, i.e. DATA. Written once here rather than twice,
-// so a change to the collapse rule cannot land on one and miss the other.
+// The `effectiveGlobal` instance for every selection whose domain is PER-CONFIG
+// (declared in the config, not a registry-static list). `looks` and `presets`
+// are both exactly this — what differs between them is only the floor name and
+// which map holds the members, i.e. DATA.
 //
-// [LAW:dataflow-not-control-flow] The `??` chain IS the precedence — no "if the
-// session has one" branch anywhere. [LAW:no-silent-failure] the collapse is the
-// visible floor, not a throw: a stale SessionState entry from a prior config's
-// vocabulary (config edits can orphan a name the per-config gate once admitted)
-// must render the floor, and the caller publishes the RESOLVED name onto the
-// payload so a menu label can never claim a member the render did not use.
+// The config default runs through the SAME membership parse the session pick
+// does, one layer down: a `look:`/`preset:` naming a member the config no longer
+// declares is no default at all, and collapses to the floor exactly as a stale
+// session pick does. The loader cannot catch that for a per-config domain, so
+// this resolution is where it is caught.
 //
 // The floor's membership is a load-time guarantee, not a runtime hope: the
 // bundled stdlib ships it and merge-by-name cannot remove it.
@@ -76,10 +116,14 @@ export function effectiveMemberName(
   floor: string,
   declared: Readonly<Record<string, unknown>>,
 ): string {
-  const chosen = sessionPick ?? configDefault ?? floor;
-  return Object.prototype.hasOwnProperty.call(declared, chosen)
-    ? chosen
-    : floor;
+  const member = (raw: string): string | null =>
+    Object.prototype.hasOwnProperty.call(declared, raw) ? raw : null;
+  return effectiveGlobal(
+    sessionPick,
+    member(configDefault ?? floor),
+    floor,
+    member,
+  );
 }
 
 // --- Look (theme-adaptation) identifiers ---
@@ -136,19 +180,28 @@ export function isStripStyle(value: string): value is StripStyle {
   return (STRIP_STYLES as readonly string[]).includes(value);
 }
 
-// The strip style a render should use, as data. [LAW:dataflow-not-control-flow]
-// [LAW:one-type-per-behavior] The exact shape of `effectiveThemeName`, one
-// dimension over: session choice over config default over the "powerline" floor,
-// no "if the session has a style" branch. A value outside the domain (a stale
-// SessionState entry from a prior option vocabulary) collapses to the floor —
-// `pickJoiner` would render it as powerline anyway, so the floor keeps the
-// returned type honest rather than silently widening.
+// The strip style a render should use, as data.
+// [LAW:one-type-per-behavior] `effectiveGlobal` over a closed registry-static
+// vocabulary: the narrowing guard IS the parse. `pickJoiner` would render an
+// unknown style as powerline anyway; parsing here keeps the returned TYPE
+// honest rather than silently widening it.
+//
+// A stale SessionState entry (a member of a prior option vocabulary) is an
+// ABSENT session pick, not a pick of the floor: it falls through to the config
+// default, and only reaches "powerline" when the config declares no style
+// either. That is a deliberate change from the pre-`effectiveGlobal` spelling,
+// which collapsed straight to the floor and skipped the user's own declared
+// default — a config saying `style: "capsule"` deserves capsule when a session
+// entry goes stale, not powerline. Every field here now shares that one rule
+// [LAW:one-source-of-truth]; test/session-globals.test.ts pins it with a stale
+// pick over a valid non-floor default, the case the old tests never exercised.
 export function effectiveStripStyle(
   sessionStyle: string | null,
   globalsStyle: StripStyle | undefined,
 ): StripStyle {
-  const chosen = sessionStyle ?? globalsStyle ?? "powerline";
-  return isStripStyle(chosen) ? chosen : "powerline";
+  return effectiveGlobal(sessionStyle, globalsStyle, "powerline", (raw) =>
+    isStripStyle(raw) ? raw : null,
+  );
 }
 
 // --- Joiner charset identifiers ---
@@ -164,7 +217,11 @@ export function effectiveStripStyle(
 // joiner SHAPE, charset picks the glyph VALUES fed to it.
 // [config-only] Unlike STRIP_STYLES there is no SessionState/click half, so no
 // narrowing guard or effective* resolver — the config global over the default
-// is the whole resolution.
+// is the whole resolution. That is a decision, not a gap: charset describes the
+// TERMINAL (does its font carry the powerline private-use glyphs), not a taste.
+// It does not vary session-to-session on one machine, so a per-session override
+// would be a knob whose only honest setting is the one already in the config.
+// Same for COLOR_COMPATIBILITIES below.
 export const CHARSETS = ["unicode", "ascii"] as const;
 export type Charset = (typeof CHARSETS)[number];
 
@@ -192,3 +249,88 @@ export const COLOR_COMPATIBILITIES = [
   "none",
 ] as const satisfies readonly ColorSystemSpec[];
 export type ColorCompatibility = (typeof COLOR_COMPATIBILITIES)[number];
+
+// --- Layout globals (autoWrap, padding) ---
+//
+// These two DO have a session half, unlike charset/colorCompatibility above:
+// wrapping and cell padding are how much bar you want on your screen right now
+// — a taste that legitimately differs between one session in a wide terminal
+// and another in a split pane. Their floors and domains live here, beside the
+// other globals vocabularies, because both the config loader (range validation,
+// JSON-schema emit) and the render layer need them and config must not import
+// render [LAW:one-way-deps]. src/render/strip.ts re-exports them so render-layer
+// callers keep their existing import site.
+
+// [LAW:one-source-of-truth] The one statement of the globals.autoWrap default
+// (on — current behavior).
+export const DEFAULT_WRAP = true;
+
+// [LAW:one-source-of-truth] The spelling of a boolean as a SessionState string.
+// SessionState holds strings, so "true"/"false" is the wire vocabulary for every
+// boolean globals field — the same two members the bundled default's
+// `cycle: [...]` toggle writes and the parse below reads. Spelled once so a
+// toggle cannot write a member the resolver refuses to parse.
+export const BOOLEAN_MEMBERS = ["true", "false"] as const;
+
+// [LAW:one-source-of-truth] The one statement of the globals.padding default
+// (one space per side inside each segment cell — current behavior, matching the
+// legacy display.padding).
+export const DEFAULT_PADDING = 1;
+
+// [LAW:one-source-of-truth] THE padding domain: an integer, inclusive both ends.
+// Read by the loader's `padding` int spec (config-file values), by the bundled
+// default's stepper actions (`min`/`max`, which bound what a click may persist),
+// and by the session parse below. When those were three copies of `0`/`16`, a
+// widened range could land on the file and miss the clicks.
+export const PADDING_RANGE = { min: 0, max: 16 } as const;
+
+// [LAW:parse-dont-validate] A SessionState string to a boolean, or null for
+// anything else. `??` in effectiveGlobal (never `||`) is what keeps a parsed
+// `false` a real answer rather than falling through to the default.
+function parseBoolean(raw: string): boolean | null {
+  return raw === "true" ? true : raw === "false" ? false : null;
+}
+
+// [LAW:parse-dont-validate] A SessionState string to a padding value inside the
+// one declared range. The digits test comes first because `Number("")` is 0 and
+// `Number(" 3 ")` is 3 — an empty or padded entry would otherwise parse to a
+// value nobody wrote.
+function parsePadding(raw: string): number | null {
+  if (!/^\d+$/.test(raw)) return null;
+  const value = Number(raw);
+  return value >= PADDING_RANGE.min && value <= PADDING_RANGE.max
+    ? value
+    : null;
+}
+
+// Whether a render wraps over-wide rows, as data. The session's pick over the
+// config default over the on floor — `effectiveGlobal` with a boolean domain.
+export function effectiveAutoWrap(
+  sessionAutoWrap: string | null,
+  globalsAutoWrap: boolean | undefined,
+): boolean {
+  return effectiveGlobal(
+    sessionAutoWrap,
+    globalsAutoWrap,
+    DEFAULT_WRAP,
+    parseBoolean,
+  );
+}
+
+// The intra-cell padding a render uses, as data. A session value outside
+// PADDING_RANGE falls through to the config default, the same rule every other
+// field here follows: the gate already refuses out-of-range clicks, so a value
+// that gets here is a stale entry from a narrower-since range, and the user's
+// own default is the honest answer rather than a render at a width nobody
+// chose.
+export function effectivePadding(
+  sessionPadding: string | null,
+  globalsPadding: number | undefined,
+): number {
+  return effectiveGlobal(
+    sessionPadding,
+    globalsPadding,
+    DEFAULT_PADDING,
+    parsePadding,
+  );
+}