@deepseek-insight/container-base 0.0.0-stage → 0.1.0

package/src/interaction/chord-machine.ts

@@ -0,0 +1,208 @@
+/**
+ * chord-machine — the armed two-stroke keyboard chord reducer (ADR-0006a
+ * port; container-base W5, ADR-0062 D5: the MACHINE moves, the PREFIX
+ * TABLES stay consumer config).
+ *
+ * A PURE reducer: every transition is (state, event, facts) -> { state,
+ * action }. No DOM, no stores, no timers — the caller owns the clock
+ * (now) and the wiring (which element heard the key).
+ *
+ * Grammar: press-and-release the arming key within CHORD_WINDOW_MS; a
+ * digit fires { apply, n }; a verb letter fires { verb } through the
+ * consumer's table; any other key or the expiring window disarms.
+ *
+ * D5 (the consumer-table rule): the machine never learns WHICH letters
+ * are verbs or what a terminal prefix maps to — the consumer passes
+ * ChordTables. The arming prefixes (Alt+first / Alt+second) and the
+ * digit lanes are machine semantics; "the arming key names the prefix;
+ * the prefix owns the follow-up table" is the ADR-0052 D1 rule the
+ * tables express.
+ */
+
+export const CHORD_WINDOW_MS = 2_000;
+
+export type ChordPrefix = 's' | 't';
+
+export interface ChordState {
+	/** True between the arming release and the digit / disarm. */
+	armed: boolean;
+	/** Date.now() of the arming keyup — the window clock. */
+	since: number;
+	/** Which prefix owns this chord — the prefix names the follow-up table. */
+	prefix: ChordPrefix;
+}
+
+export const IDLE_CHORD: ChordState = { armed: false, since: 0, prefix: 's' };
+
+export interface ChordOptionRow {
+	key: string;
+	label: string;
+}
+
+export type ChordAction =
+	| { type: 'none' }
+	| { type: 'disarm' }
+	| { type: 'apply'; n: number }
+	| { type: 'verb'; verb: string; prefix: ChordPrefix };
+
+/** Minimal key shape the wiring feeds in (a real KeyboardEvent fits). */
+export interface ChordKey {
+	key: string;
+	/** PHYSICAL key identity — the layout-independent match site. Holding
+	 *  Alt remaps letters on macOS (Option+S types key='ß'), so e.key
+	 *  matching never arms on a real keyboard. Match e.code; key stays as
+	 *  the no-code fallback. */
+	code?: string;
+	altKey: boolean;
+	ctrlKey: boolean;
+	metaKey: boolean;
+	/** string, not the union — a real KeyboardEvent.type IS a string and
+	 *  the wiring passes the event whole (no lossy adapter). */
+	type: string;
+}
+
+/** The consumer's chord tables (D5): WHICH letters are verbs under the
+ *  plain prefix, and what the terminal prefix's letters map to. Absence
+ *  of a letter in the terminal map disarms; a letter outside `verbs`
+ *  disarms. An empty default table keeps the machine neutral — the
+ *  consumer's config module owns the real table. */
+export interface ChordTables {
+	/** Letters that fire `{ type: 'verb', verb: letter }` under the
+	 *  plain (first) prefix. */
+	verbs: string;
+	/** The terminal prefix's letter → verb-name map (a verb name the
+	 *  host dispatches; the machine never interprets it). */
+	terminal?: Record<string, string>;
+	/** Which prefix is the terminal one (default 't'). */
+	terminalPrefix?: ChordPrefix;
+}
+
+const NO_TABLES: ChordTables = { verbs: '' };
+
+/** True when the chord can arm at all — any preset slot on any lane. */
+export function hasAnyPreset(p: {
+	agent: Record<number, unknown>;
+	glass: Record<number, unknown>;
+	sidebar: Record<number, unknown>;
+	zoom?: Record<number, unknown>;
+}): boolean {
+	return (
+		Object.keys(p.agent).length > 0 ||
+		Object.keys(p.glass).length > 0 ||
+		Object.keys(p.sidebar).length > 0 ||
+		Object.keys(p.zoom ?? {}).length > 0
+	);
+}
+
+/** Is the event target an editable surface? The wiring calls this FIRST —
+ *  typing "1" in a composer must never fire a preset. */
+export function isEditableTarget(t: unknown): boolean {
+	const el = t as { closest?: (sel: string) => unknown } | null;
+	if (!el || typeof el.closest !== 'function') return false;
+	return el.closest('input, textarea, select, [contenteditable="true"], [contenteditable=""]') != null;
+}
+
+/** One key event through the machine. now is injectable for tests.
+ *
+ *  ARM ON KEYDOWN — keyup is unreachable through window keydown wiring,
+ *  and an arm-on-keyup rule would eat the chord it just armed: keyups
+ *  pass through untouched. */
+export function chordKey(
+	state: ChordState,
+	ev: ChordKey,
+	canArm: boolean,
+	now: number = Date.now(),
+	tables: ChordTables = NO_TABLES
+): { state: ChordState; action: ChordAction } {
+	const key = ev.key.toLowerCase();
+
+	if (ev.type === 'keyup') return { state, action: { type: 'none' } };
+
+	// PHYSICAL identity: code='KeyS'/'KeyT' survives the macOS Alt remap;
+	// key==='s'/'t' stays as the fallback for code-less events. The
+	// arming key NAMES the prefix; the prefix owns the follow-up table.
+	const terminalPrefix = tables.terminalPrefix ?? 't';
+	const prefix: ChordPrefix | null =
+		ev.code === 'KeyS' || (key === 's' && !ev.code)
+			? 's'
+			: ev.code === 'KeyT' || (key === 't' && !ev.code)
+				? 't'
+				: null;
+	// Digits: Digit1..9 first (matches even with Alt still held), key
+	// fallback. Digits are the FIRST prefix's lanes — under the terminal
+	// prefix they disarm (the table is truthful).
+	const digit =
+		state.prefix === 's'
+			? (/^Digit([1-9])$/.exec(ev.code ?? '')?.[1] ?? (/^[1-9]$/.test(ev.key) ? ev.key : null))
+			: null;
+
+	// Arming: a clean Alt+<prefix key> keydown (no ctrl/meta — browser verbs).
+	if (prefix && ev.altKey && !ev.ctrlKey && !ev.metaKey) {
+		if (!canArm) return { state, action: { type: 'none' } };
+		// last prefix wins — an armed chord re-arms cleanly.
+		return { state: { armed: true, since: now, prefix }, action: { type: 'none' } };
+	}
+
+	if (!state.armed) return { state, action: { type: 'none' } };
+
+	// The window expired on this keypress: disarm first, key never counts.
+	if (now - state.since > CHORD_WINDOW_MS) {
+		return { state: IDLE_CHORD, action: { type: 'disarm' } };
+	}
+
+	// A digit fires the preset (the operator taps; we don't grade the phase).
+	if (digit) {
+		return { state: IDLE_CHORD, action: { type: 'apply', n: Number(digit) } };
+	}
+
+	// A verb letter fires its table action — code first (the same
+	// physical-identity rule as arming), key fallback after. The LETTER
+	// SETS are the consumer's tables (D5), never this module's.
+	const letter =
+		(/^[a-z]$/.test(ev.key) ? ev.key : undefined) ??
+		(/^Key([A-Z])$/.exec(ev.code ?? '')?.[1]?.toLowerCase());
+	if (letter) {
+		if (state.prefix === terminalPrefix && tables.terminal) {
+			const verb = tables.terminal[letter];
+			if (verb === undefined) return { state: IDLE_CHORD, action: { type: 'disarm' } };
+			return { state: IDLE_CHORD, action: { type: 'verb', verb, prefix: state.prefix } };
+		}
+		if (tables.verbs.includes(letter)) {
+			return { state: IDLE_CHORD, action: { type: 'verb', verb: letter, prefix: state.prefix } };
+		}
+		return { state: IDLE_CHORD, action: { type: 'disarm' } };
+	}
+
+	// Any other key disarms.
+	return { state: IDLE_CHORD, action: { type: 'disarm' } };
+}
+
+/** The capture-first decision as a PURE function so the route adapter
+ *  stays three lines and the capture rules unit-test without DOM.
+ *  Ordering IS the contract: (1) a clean arming keydown captures
+ *  everywhere; (2) an armed chord captures the next keydown everywhere;
+ *  (3) anything else — including an un-armed digit on an editable
+ *  target — passes. preventDefault is the swallowing the composer must
+ *  never see. */
+export function decideChordKeydown(
+	state: ChordState,
+	ev: ChordKey,
+	canArm: boolean,
+	now: number = Date.now(),
+	tables: ChordTables = NO_TABLES
+): { state: ChordState; action: ChordAction; preventDefault: boolean } {
+	const k = ev.key.toLowerCase();
+	const isArm =
+		((ev.code === 'KeyS' || (k === 's' && !ev.code)) ||
+			(ev.code === 'KeyT' || (k === 't' && !ev.code))) &&
+		ev.altKey &&
+		!ev.ctrlKey &&
+		!ev.metaKey;
+	if (ev.type === 'keydown' && isArm) {
+		return { ...chordKey(state, ev, canArm, now, tables), preventDefault: true };
+	}
+	if (state.armed && ev.type === 'keydown') {
+		return { ...chordKey(state, ev, canArm, now, tables), preventDefault: true };
+	}
+	return { state, action: { type: 'none' }, preventDefault: false };
+}

package/src/interaction/gutter-resize.ts

@@ -0,0 +1,76 @@
+/**
+ * Gutter resize — the SINGLE sidebar-style drag machine (SSC#2 extraction,
+ * 2026-11-14): one width, snapshot on gutter mousedown, clamped delta per
+ * window mousemove, settle on window mouseup. Both consumers DSI has run
+ * byte-similar copies of this skeleton (route `startSidebarResize` +
+ * playground page drag vars); this module is now its only home.
+ *
+ * The machine OWNS: the window-listener lifecycle (attached on a
+ * successful start, released on settle), the delta arithmetic, the
+ * candidate width (snapshot + delta), and the clamp pass. The host OWNS:
+ * the bounds (clamp fn — DSI's are config-driven), the apply (write the
+ * width wherever it lives), and the settle (persistence, afterglow).
+ *
+ * A mousedown that returns null from `onStart` arms nothing — a host with
+ * collapsed/ignored states uses that instead of pre-gating the gutter.
+ */
+export interface GutterResizeMachine {
+	/** Gutter mousedown — arms the machine and attaches the window
+	 *  listeners when `onStart` returns a snapshot width (null = ignore). */
+	start: (e: MouseEvent) => void;
+	/** True while dragging (start succeeded, settle not yet fired). */
+	readonly active: boolean;
+	/** Release the window listeners without settling (page teardown). */
+	destroy: () => void;
+}
+
+export function createGutterResize(handlers: {
+	/** Gutter mousedown: return the SNAPSHOT width (the width the drag
+	 *  moves away from), or null to ignore this gesture. */
+	onStart: (e: MouseEvent) => number | null;
+	/** The host's bounds — a pure width -> width clamp. */
+	clamp: (width: number) => number;
+	/** Apply the clamped width — called per window mousemove while armed. */
+	onResize: (width: number, e: MouseEvent) => void;
+	/** Settle on window mouseup: persist, arm afterglow, etc. The final
+	 *  clamped width is the one the last resize produced. */
+	onSettle?: (width: number) => void;
+}): GutterResizeMachine {
+	let armed = false;
+	let snapshot = 0;
+	let lastWidth = 0;
+
+	function onMove(e: MouseEvent): void {
+		if (!armed) return;
+		lastWidth = handlers.clamp(snapshot + (e.clientX - lastStartX));
+		handlers.onResize(lastWidth, e);
+	}
+	function onUp(e: MouseEvent): void {
+		if (!armed) return;
+		armed = false;
+		window.removeEventListener('mousemove', onMove);
+		window.removeEventListener('mouseup', onUp);
+		handlers.onSettle?.(lastWidth);
+	}
+	let lastStartX = 0;
+	return {
+		start(e: MouseEvent): void {
+			const snap = handlers.onStart(e);
+			if (snap === null) return;
+			snapshot = snap;
+			lastStartX = e.clientX;
+			lastWidth = handlers.clamp(snap);
+			armed = true;
+			window.addEventListener('mousemove', onMove);
+			window.addEventListener('mouseup', onUp);
+		},
+		get active(): boolean {
+			return armed;
+		},
+		destroy(): void {
+			armed = false;
+			window.removeEventListener('mousemove', onMove);
+			window.removeEventListener('mouseup', onUp);
+		}
+	};
+}

package/src/layout/floor-math.ts

@@ -0,0 +1,94 @@
+/**
+ * floor-math — the drag/resize/order math of a one-row pane floor
+ * (generalized from DSI's floor-math.ts, ADR-0062 W3 / D8). PURE functions
+ * over plain structural inputs; no DOM, no stores, no consumer vocabulary.
+ *
+ * GENERIC over the pane type: a consumer's own pane interface (union,
+ * discriminated kinds, extra fields) flows through UNCHANGED — every
+ * function returns the same pane type it took. Only the structural core
+ * (id + width, optional kind) is required.
+ *
+ * The width bound is INJECTED (the clamp): the generic module cannot know
+ * a consumer's config-driven bounds, so every resize entry takes an
+ * optional clamp — the consumer's single bound site (DSI passes
+ * clampPanelWidth). Behavior is byte-identical to the pre-move DSI file
+ * when the consumer passes its clamp.
+ */
+
+/** The structural core every pane must expose (satisfied by any consumer
+ *  pane with an id and a width; the kind tag rides through opaquely). */
+export interface PaneCore {
+	id: string;
+	width: number;
+	/** Opaque kind tag — passed through to the injected clamp only. */
+	kind?: unknown;
+}
+
+/** A consumer's single width bound site (load-side sanitize AND drags). */
+export type WidthClamp = (width: number, kind?: string) => number;
+
+/** Move direction, named in the INVOKING surface's geometry: horizontal
+ *  header chevrons vs vertical rows. The floor owner maps both pairs onto
+ *  one array operation — left/up toward the start, right/down toward the
+ *  end. */
+export type PaneMoveDir = 'left' | 'right' | 'up' | 'down';
+
+const identityClamp: WidthClamp = (width) => width;
+
+/** Plain drag: ONLY the pane left of the dragged gutter changes — its
+ *  snapshot width plus delta, passed through the injected clamp. Other
+ *  panes keep their widths untouched (the row's total grows/shrinks; the
+ *  floor viewport scrolls when the widened row overflows it). */
+export function resizeOne<P extends PaneCore>(
+	panels: readonly P[],
+	snapshots: readonly number[],
+	index: number,
+	delta: number,
+	clamp: WidthClamp = identityClamp
+): P[] {
+	const target = clamp(snapshots[index] + delta, panels[index]?.kind as string | undefined);
+	return panels.map((p, i) => (i === index ? { ...p, width: target } : p));
+}
+
+/** Shift+drag: EVERY pane scales by its snapshot share of the row — ratios
+ *  are preserved (new_i/new_j = snap_i/snap_j) until a pane saturates at a
+ *  bound; an extreme drag clamps the row. A degenerate row (total <= 0)
+ *  returns the input order untouched. */
+export function scaleProportionally<P extends PaneCore>(
+	panels: readonly P[],
+	snapshots: readonly number[],
+	delta: number,
+	clamp: WidthClamp = identityClamp
+): P[] {
+	const total = snapshots.reduce((sum, w) => sum + w, 0);
+	if (total <= 0) return [...panels];
+	return panels.map((p, i) => ({
+		...p,
+		width: clamp(snapshots[i] + (snapshots[i] / total) * delta, panels[i]?.kind as string | undefined)
+	}));
+}
+
+/** Honest-slider check: a row is uniform when every width equals the
+ *  first (an empty row is not — nothing to sync the preset to). */
+export function isUniformRow<P extends PaneCore>(panels: readonly P[]): boolean {
+	if (panels.length === 0) return false;
+	const first = panels[0].width;
+	return panels.every((p) => p.width === first);
+}
+
+/** Move one pane one slot toward the direction's edge — left/up swap with
+ *  the predecessor, right/down with the successor. A no-op returning the
+ *  input order at either edge or for an unknown pane id. */
+export function movePanelWithin<P extends PaneCore>(
+	panels: readonly P[],
+	panelId: string,
+	dir: PaneMoveDir
+): P[] {
+	const idx = panels.findIndex((p) => p.id === panelId);
+	if (idx === -1) return [...panels];
+	const target = dir === 'left' || dir === 'up' ? idx - 1 : idx + 1;
+	if (target < 0 || target >= panels.length) return [...panels];
+	const next = [...panels];
+	[next[idx], next[target]] = [next[target], next[idx]];
+	return next;
+}

package/src/layout/placement.ts

@@ -0,0 +1,30 @@
+/**
+ * placement — the generic order/anchor math of a pane floor (ADR-0062 W3,
+ * D8: split from DSI's panel-placement; the kind-tagged request union and
+ * DSI-specific branches stay in the consumer). PURE, list-shaped only.
+ */
+
+/** The slot directly BELOW an anchor pane — anchor + 1 — or the caller's
+ *  fallback when no pane carries the anchor (anchorIndex < 0). The
+ *  fork-child / below-the-explorer slot rule. */
+export function slotAfter(anchorIndex: number, fallback: number): number {
+	return anchorIndex >= 0 ? anchorIndex + 1 : fallback;
+}
+
+/** Insert ONE item at an anchor index. Boundary anchors clamp: an empty
+ *  list (or an anchor past the end) appends; a negative anchor inserts at
+ *  the front. Ordering is stable — existing members never reorder. */
+export function insertAtAnchor<T>(list: readonly T[], anchorIndex: number, item: T): T[] {
+	const at = Math.max(0, Math.min(anchorIndex, list.length));
+	const next = [...list];
+	next.splice(at, 0, item);
+	return next;
+}
+
+/** The focused-slot rule: a fresh item lands at the FOCUSED index —
+ *  immediately before it. 0 when nothing is focused (negative or past the
+ *  end) — front-add stays the fallback; Math.max keeps splice's
+ *  negative-index semantics out of the no-selection case. */
+export function focusedSlot(selectedIndex: number, listLength: number): number {
+	return selectedIndex >= 0 && selectedIndex < listLength ? selectedIndex : 0;
+}

package/src/registry/action-registry.ts

@@ -0,0 +1,62 @@
+/**
+ * action-registry — the generic leaf-to-root action channel (ADR-0062 W3,
+ * D8: split from DSI's panel-registry; the payload unions stay in the
+ * consumer). Shape follows the OCI ControlRail precedent: register(name,
+ * fn | null) slots owned by the host's mount/destroy lifecycle, invoke
+ * returning boolean (false = no handler, graceful no-op — never a crash
+ * in a leaf). Payload-agnostic: actions are string-keyed, arguments
+ * variadic, the table never inspects a payload.
+ */
+
+type AnyHandler = (...args: never[]) => unknown;
+
+export interface ActionTable {
+	/** Set (or overwrite) an action's handler; null unregisters. */
+	register(action: string, handler: AnyHandler | null): void;
+	/** True when a handler is currently registered for the action. */
+	has(action: string): boolean;
+	/** Run the action's handler if registered.
+	 *  @returns true when a handler ran; false otherwise. */
+	invoke(action: string, ...args: unknown[]): boolean;
+	/** Like invoke, but returns the HANDLER'S OWN return value — undefined
+	 *  when no handler is registered. For result-carrying actions (e.g. a
+	 *  handler that reports a miss) where 'did it run' and 'what did it
+	 *  say' are different questions. */
+	invokeForResult(action: string, ...args: unknown[]): unknown;
+	/** True when ANY handler is registered (a host is mounted). */
+	isActive(): boolean;
+	/** Clear every slot (isolation between tests / host destroy). */
+	reset(): void;
+}
+
+export function createActionTable(): ActionTable {
+	const slots = new Map<string, AnyHandler>();
+	return {
+		register(action: string, handler: AnyHandler | null): void {
+			if (handler === null) slots.delete(action);
+			else slots.set(action, handler);
+		},
+		has(action: string): boolean {
+			return slots.has(action);
+		},
+		invoke(action: string, ...args: unknown[]): boolean {
+			const handler = slots.get(action);
+			if (handler === undefined) return false;
+			// The table is payload-agnostic by construction; the consumer's
+			// register-time types are the contract, invoke erases shape.
+			(handler as (...a: unknown[]) => unknown)(...args);
+			return true;
+		},
+		invokeForResult(action: string, ...args: unknown[]): unknown {
+			const handler = slots.get(action);
+			if (handler === undefined) return undefined;
+			return (handler as (...a: unknown[]) => unknown)(...args);
+		},
+		isActive(): boolean {
+			return slots.size > 0;
+		},
+		reset(): void {
+			slots.clear();
+		}
+	};
+}

package/src/storage/create-prefs-store.ts

@@ -0,0 +1,87 @@
+/**
+ * createPrefsStore — the survival-layer primitive (ADR-0062 D4).
+ *
+ * Nine consumer modules hand-rolled one pattern: SSR guard → revive with
+ * junk fallback → clamp → best-effort write. This is that pattern, once:
+ *
+ *   const store = createPrefsStore<MyPrefs>({
+ *     key: 'my-key',
+ *     defaults: () => ({ ... }),
+ *     revive: (raw) => sanitize(raw),   // return null ⇒ junk ⇒ defaults
+ *     clamp: (v) => bound(v)
+ *   });
+ *
+ * Semantics (pinned by tests/storage/create-prefs-store.test.ts):
+ * - SSR (`typeof localStorage === 'undefined'`): load → defaults, save → no-op.
+ * - junk / truncated / unparseable blob → defaults, never throws.
+ * - clamp runs AFTER revive, on every load.
+ * - writes are best-effort: a full or blocked store never throws.
+ * - blob shapes are consumer-owned: the stored text is exactly
+ *   JSON.stringify(prefs) unless the consumer opts into the `{v, data}`
+ *   envelope (new consumers only — existing blobs never migrate, D4).
+ */
+import { storageKey } from './namespace';
+
+export interface PrefsStoreOptions<T> {
+	/** The un-suffixed localStorage key (namespaced per profile). */
+	key: string;
+	/** Persisted defaults — a factory, so callers never share object state. */
+	defaults: () => T;
+	/** Parse a parsed-JSON value into prefs; return null to reject the blob
+	 *  as junk (load falls back to defaults). */
+	revive: (raw: unknown) => T | null;
+	/** Optional bound pass, applied to the revived value (after revive). */
+	clamp?: (prefs: T) => T;
+	/** Opt-in `{v, data}` envelope — new consumers only (D4); read-side
+	 *  still accepts a bare (legacy) blob so adoption is one-way safe. */
+	envelope?: { version: number };
+}
+
+export interface PrefsStore<T> {
+	/** Read from localStorage; defaults on SSR, absence, junk, or error. */
+	load(profile?: string | null): T;
+	/** Write to localStorage (best-effort; no-op under SSR). */
+	save(prefs: T, profile?: string | null): void;
+	/** The exact key this store reads/writes for a profile. */
+	key(profile?: string | null): string;
+}
+
+/** True when the parsed JSON carries the envelope wrapper. */
+function isEnvelope(raw: unknown): raw is { v: number; data: unknown } {
+	if (raw === null || typeof raw !== 'object') return false;
+	const rec = raw as Record<string, unknown>;
+	return 'v' in rec && 'data' in rec;
+}
+
+export function createPrefsStore<T>(options: PrefsStoreOptions<T>): PrefsStore<T> {
+	const { key, defaults, revive, clamp, envelope } = options;
+	const keyFor = (profile?: string | null) => storageKey(key, profile);
+	const finalize = (prefs: T): T => (clamp ? clamp(prefs) : prefs);
+
+	return {
+		key: keyFor,
+		load(profile?: string | null): T {
+			if (typeof localStorage === 'undefined') return defaults();
+			try {
+				const raw = localStorage.getItem(keyFor(profile));
+				if (!raw) return defaults();
+				const parsed: unknown = JSON.parse(raw);
+				const body = envelope !== undefined && isEnvelope(parsed) ? parsed.data : parsed;
+				const revived = revive(body);
+				if (revived === null) return defaults();
+				return finalize(revived);
+			} catch {
+				return defaults();
+			}
+		},
+		save(prefs: T, profile?: string | null): void {
+			if (typeof localStorage === 'undefined') return;
+			try {
+				const payload = envelope !== undefined ? { v: envelope.version, data: prefs } : prefs;
+				localStorage.setItem(keyFor(profile), JSON.stringify(payload));
+			} catch {
+				// Store full or blocked — persistence is lost, the app is not.
+			}
+		}
+	};
+}

package/src/storage/namespace.ts

@@ -0,0 +1,34 @@
+/**
+ * Storage namespace — the ONE home of the workspace-profile key convention
+ * (generalized from DSI's storage-profile.ts; ADR-0062 D4). Consumer keys
+ * keep their exact existing strings: the suffix rule is the only thing
+ * this module owns.
+ *
+ *   no profile   → my-key
+ *   ?profile=widi → my-key_widi
+ *
+ * The profile is sticky and sanitized here once — every prefs store routes
+ * its key through the namespace fn so no two call sites re-implement it.
+ */
+
+/**
+ * Sanitize a raw `?profile=` value into a storage-key-safe segment.
+ * Keeps `[A-Za-z0-9_-]` (case preserved — profiles are exact ids), caps at
+ * 40 chars; anything that sanitizes to nothing is not a profile.
+ * @returns the safe segment, or null when the value carries no usable
+ *          characters (the caller then behaves as if no profile were set).
+ */
+export function sanitizeWorkspaceProfile(raw: string): string | null {
+	const safe = raw.replace(/[^A-Za-z0-9_-]/g, '').slice(0, 40);
+	return safe.length > 0 ? safe : null;
+}
+
+/**
+ * The storage key for a workspace profile.
+ * @param base the un-suffixed storage key (e.g. 'dsi-panels').
+ * @param profile sanitized profile segment, or null/undefined for the
+ *                default desk (the base key unchanged).
+ */
+export function storageKey(base: string, profile?: string | null): string {
+	return profile ? `${base}_${profile}` : base;
+}

package/src/theme/tokens.css

@@ -0,0 +1,35 @@
+/*
+ * @deepseek-insight/container-base — default theme tokens (ADR-0062 W5,
+ * D7): a fresh consumer is styled out of the box; the host OVERRIDES every
+ * var (DSI's theme defines all of them, byte-identical visuals).
+ *
+ * --zoom is NOT a theme token: it is a per-frame runtime variable the
+ * PanelsZoom component writes itself.
+ *
+ * Ground rule (dev/article/2026-11/04.re-architect, 2026-11-14): styling
+ * crosses ONLY through tokens — components never carry a skin. W6 added
+ * the chord-palette tokens after the boundary audit found the overlay
+ * wearing Tailwind palette classes.
+ */
+:root {
+	/* Surfaces */
+	--color-surface-primary: #ffffff;
+	--color-surface-secondary: #f1f3f5;
+	--color-surface-elevated: #ffffff;
+	--color-surface-border: #dee2e6;
+	--color-header-wash: #fff8ec;
+
+	/* Text */
+	--color-text-primary: #212529;
+	--color-text-secondary: #6c757d;
+
+	/* Accents (the selection ring gradient stops) */
+	--color-accent-blue: #3b82f6;
+	--color-accent-purple: #a855f7;
+	--color-accent-rose: #f43f5e;
+
+	/* Chord palette (the armed overlay's decay ticker — W6 ground rule:
+	 * theming crosses only through tokens; the component ships no skin) */
+	--color-chord-armed: #86efac;
+	--color-chord-idle: #fef08a;
+}