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

package/dist/storage/namespace.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 declare function sanitizeWorkspaceProfile(raw: string): string | 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 declare function storageKey(base: string, profile?: string | null): string;

package/dist/storage/namespace.js

@@ -0,0 +1,32 @@
+/**
+ * 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) {
+    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, profile) {
+    return profile ? `${base}_${profile}` : base;
+}

package/dist/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;
+}

package/dist/theming/ThemeToggle.svelte

@@ -0,0 +1,170 @@
+<script lang="ts">
+	/**
+	 * ThemeToggle — the generic three-state lamp mount (ADR-0063 D2).
+	 * The MECHANISM lives in theming/theme-prefs.svelte.ts; this component
+	 * carries NO words and NO skin: every label comes in as a prop, every
+	 * icon as a snippet, every color as a token var (boundary suite).
+	 * Structure follows the DSI footer lamp: one trigger whose icon is the
+	 * current choice, a popup with the three states, check on the active
+	 * one, click-outside closes, dropUp for rail-bottom mounts.
+	 */
+	import type { Component, Snippet } from 'svelte';
+
+	export type ThemeChoice = 'system' | 'light' | 'dark';
+
+	let {
+		/** The consumer's ThemePrefs instance (createThemePrefs). */
+		prefs,
+		/** aria-label / title for the trigger (consumer's words). */
+		triggerLabel,
+		/** Per-state words (consumer's dictionary). */
+		optionLabels,
+		/** Per-state icon components (consumer's icon set). */
+		icons,
+		/** Open the list upward (rail-bottom mounts). */
+		dropUp = false
+	}: {
+		prefs: {
+			readonly choice: ThemeChoice;
+			set: (c: ThemeChoice) => void;
+		};
+		triggerLabel: string;
+		optionLabels: Record<ThemeChoice, string>;
+		icons: Record<ThemeChoice, Component<{ size?: number; 'aria-hidden'?: boolean | 'true' | 'false' }>>;
+		dropUp?: boolean;
+	} = $props();
+
+	let open = $state(false);
+	let rootEl = $state<HTMLElement | null>(null);
+
+	const CHOICES: ThemeChoice[] = ['system', 'light', 'dark'];
+
+	const TriggerIcon = $derived(icons[prefs.choice]);
+
+	function choose(c: ThemeChoice): void {
+		open = false;
+		prefs.set(c);
+	}
+
+	// outside click closes — one window listener while open (removed on close)
+	$effect(() => {
+		if (!open) return;
+		const onDocClick = (ev: MouseEvent) => {
+			if (rootEl && !rootEl.contains(ev.target as Node)) open = false;
+		};
+		document.addEventListener('click', onDocClick);
+		return () => document.removeEventListener('click', onDocClick);
+	});
+</script>
+
+<div
+	class="cb-theme-toggle"
+	data-testid="cb-theme-toggle"
+	bind:this={rootEl}
+>
+	<button
+		type="button"
+		class="cb-theme-toggle-trigger"
+		title={triggerLabel}
+		aria-label={triggerLabel}
+		aria-expanded={open}
+		data-testid="cb-theme-toggle-trigger"
+		onclick={() => (open = !open)}
+	>
+		<TriggerIcon size={16} />
+	</button>
+	{#if open}
+		<div
+			class="cb-theme-toggle-list"
+			class:cb-drop-up={dropUp}
+			data-testid="cb-theme-toggle-list"
+			role="menu"
+		>
+			{#each CHOICES as c (c)}
+				{@const Icon = icons[c]}
+				<button
+					type="button"
+					class="cb-theme-option"
+					class:cb-option-active={prefs.choice === c}
+					data-testid={'cb-theme-option-' + c}
+					data-active={prefs.choice === c ? 'true' : 'false'}
+					role="menuitem"
+					onclick={() => choose(c)}
+				>
+					<span class="cb-theme-option-row">
+						<Icon size={13} aria-hidden="true" />
+						{optionLabels[c]}
+					</span>
+					{#if prefs.choice === c}<span aria-hidden="true">✓</span>{/if}
+				</button>
+			{/each}
+		</div>
+	{/if}
+</div>
+
+<style>
+	/* Structure only — every color crosses through tokens (ground rule).
+	 * The outside-click close effect lives with the consumer host for now
+	 * (see tests); the component itself holds no globals. */
+	.cb-theme-toggle {
+		position: relative;
+		display: inline-block;
+	}
+	.cb-theme-toggle-trigger {
+		display: flex;
+		align-items: center;
+		gap: 0.25rem;
+		border: none;
+		background: transparent;
+		color: var(--color-text-secondary);
+		border-radius: 0.25rem;
+		padding: 0.25rem;
+		cursor: pointer;
+	}
+	.cb-theme-toggle-trigger:hover {
+		color: var(--color-text-primary);
+	}
+	.cb-theme-toggle-list {
+		position: absolute;
+		right: 0;
+		z-index: 50;
+		width: 9rem;
+		overflow: hidden;
+		margin-top: 0.25rem;
+		border-radius: 0.375rem;
+		border: 1px solid var(--color-surface-border);
+		background: var(--color-surface-elevated);
+		color: var(--color-text-primary);
+		box-shadow: 0 4px 6px -1px var(--color-surface-border);
+	}
+	.cb-theme-toggle-list.cb-drop-up {
+		bottom: 100%;
+		margin-top: 0;
+		margin-bottom: 0.25rem;
+	}
+	.cb-theme-option {
+		display: flex;
+		width: 100%;
+		align-items: center;
+		justify-content: space-between;
+		padding: 0.375rem 0.75rem;
+		text-align: left;
+		font-size: 0.75rem;
+		border: none;
+		background: transparent;
+		color: inherit;
+		cursor: pointer;
+	}
+	.cb-theme-option:hover {
+		background: var(--color-surface-secondary);
+	}
+	.cb-theme-option.cb-option-active {
+		color: var(--color-accent-purple);
+		font-weight: 600;
+	}
+	.cb-theme-option-row {
+		display: flex;
+		align-items: center;
+		gap: 0.375rem;
+	}
+</style>

package/dist/theming/ThemeToggle.svelte.d.ts

@@ -0,0 +1,27 @@
+/**
+     * ThemeToggle — the generic three-state lamp mount (ADR-0063 D2).
+     * The MECHANISM lives in theming/theme-prefs.svelte.ts; this component
+     * carries NO words and NO skin: every label comes in as a prop, every
+     * icon as a snippet, every color as a token var (boundary suite).
+     * Structure follows the DSI footer lamp: one trigger whose icon is the
+     * current choice, a popup with the three states, check on the active
+     * one, click-outside closes, dropUp for rail-bottom mounts.
+     */
+import type { Component } from 'svelte';
+export type ThemeChoice = 'system' | 'light' | 'dark';
+type $$ComponentProps = {
+    prefs: {
+        readonly choice: ThemeChoice;
+        set: (c: ThemeChoice) => void;
+    };
+    triggerLabel: string;
+    optionLabels: Record<ThemeChoice, string>;
+    icons: Record<ThemeChoice, Component<{
+        size?: number;
+        'aria-hidden'?: boolean | 'true' | 'false';
+    }>>;
+    dropUp?: boolean;
+};
+declare const ThemeToggle: Component<$$ComponentProps, {}, "">;
+type ThemeToggle = ReturnType<typeof ThemeToggle>;
+export default ThemeToggle;

package/dist/theming/applier.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The pre-paint theme applier — an inline SCRIPT SOURCE STRING the consumer
+ * embeds in its HTML template (ADR-0063 D2). It re-derives the storage key
+ * with the SAME grammar as theming/theme-prefs.svelte.ts (namespace.ts:
+ * <baseKey> + '_' + sanitized ?profile=), reads the choice, resolves system
+ * against the OS, and sets html[data-theme] BEFORE first paint — no flash.
+ *
+ * It cannot import modules (it runs before the bundle), so the derivation is
+ * generated from this one function: consumers never hand-copy it.
+ *
+ * Pure string generation — no runes — so plain node (strip-types) can import
+ * it for HTML template generation (scripts/sync-theme-applier.mjs).
+ */
+/** Generate the inline script source for a consumer's theme base key. */
+export declare function themeApplierScript(baseKey: string): string;

package/dist/theming/applier.js

@@ -0,0 +1,29 @@
+/**
+ * The pre-paint theme applier — an inline SCRIPT SOURCE STRING the consumer
+ * embeds in its HTML template (ADR-0063 D2). It re-derives the storage key
+ * with the SAME grammar as theming/theme-prefs.svelte.ts (namespace.ts:
+ * <baseKey> + '_' + sanitized ?profile=), reads the choice, resolves system
+ * against the OS, and sets html[data-theme] BEFORE first paint — no flash.
+ *
+ * It cannot import modules (it runs before the bundle), so the derivation is
+ * generated from this one function: consumers never hand-copy it.
+ *
+ * Pure string generation — no runes — so plain node (strip-types) can import
+ * it for HTML template generation (scripts/sync-theme-applier.mjs).
+ */
+/** Generate the inline script source for a consumer's theme base key. */
+export function themeApplierScript(baseKey) {
+    return `try {
+	var m = location.search.match(/[?&]profile=([^&]*)/);
+	var prof = m ? m[1].replace(/[^A-Za-z0-9_-]/g, '').slice(0, 40) : '';
+	var k = '${baseKey}' + (prof ? '_' + prof : '');
+	var t = localStorage.getItem(k);
+	if (t !== 'light' && t !== 'dark' && t !== 'system') t = 'system';
+	document.documentElement.dataset.theme =
+		t === 'dark' || (t === 'system' && window.matchMedia && matchMedia('(prefers-color-scheme: dark)').matches)
+			? 'dark'
+			: 'light';
+} catch (e) {
+	document.documentElement.dataset.theme = 'light';
+}`;
+}

package/dist/theming/theme-prefs.svelte.d.ts

@@ -0,0 +1,21 @@
+export type ThemeChoice = 'system' | 'light' | 'dark';
+export type ResolvedTheme = 'light' | 'dark';
+export interface ThemePrefsOptions {
+    /** The un-suffixed localStorage key (e.g. 'dsi-theme', 'pg-theme'). */
+    baseKey: string;
+}
+export interface ThemePrefs {
+    readonly choice: ThemeChoice;
+    readonly resolved: ResolvedTheme;
+    /** Mount-time adoption: the pre-paint applier already resolved and set
+     * the attribute before the bundle ran — ADOPT it (flash-free),
+     * re-deriving the choice from storage. Paints only when the attribute
+     * was somehow missing. */
+    adopt(): void;
+    /** Persist the CHOICE (never the resolved value — system keeps following
+     * the OS), then paint. */
+    set(next: ThemeChoice): void;
+    /** Live OS following, only while the choice is system. */
+    listen(): void;
+}
+export declare function createThemePrefs(options: ThemePrefsOptions): ThemePrefs;

package/dist/theming/theme-prefs.svelte.js

@@ -0,0 +1,91 @@
+// The base Three-State Lamp — the switch MECHANISM (ADR-0063 D2, moved out
+// of DSI's hand-rolled twin). Owns a three-state choice (system / light /
+// dark), persists it under localStorage[<baseKey>], resolves it against the
+// OS, and sets html[data-theme] — the single hinge the token layer reads.
+// The ONLY other place that derives the storage key is the inline pre-paint
+// applier (theming/applier.ts) the consumer inlines in its HTML template;
+// key grammar flows through storage/namespace so the two cannot drift.
+// Key grammar: EVERY <baseKey> is profile-scoped (?profile= param), so each
+// desk remembers its own lamp.
+import { storageKey, sanitizeWorkspaceProfile } from '../storage/namespace';
+export function createThemePrefs(options) {
+    const baseKey = options.baseKey;
+    /** The active workspace profile — the sticky ?profile= param, sanitized
+     * once here (mirror of the pre-paint derivation in the applier). */
+    const currentProfile = () => typeof location === 'undefined'
+        ? null
+        : sanitizeWorkspaceProfile(new URLSearchParams(location.search).get('profile') ?? '');
+    const storageKeyFor = () => storageKey(baseKey, currentProfile());
+    const osPrefersDark = () => typeof window !== 'undefined' &&
+        !!window.matchMedia?.('(prefers-color-scheme: dark)').matches;
+    /** Defensive read — SSR-safe, junk -> system. */
+    const readStoredChoice = () => {
+        if (typeof localStorage === 'undefined')
+            return 'system';
+        try {
+            const raw = localStorage.getItem(storageKeyFor());
+            return raw === 'light' || raw === 'dark' || raw === 'system' ? raw : 'system';
+        }
+        catch {
+            return 'system';
+        }
+    };
+    const resolve = (choice) => choice === 'system' ? (osPrefersDark() ? 'dark' : 'light') : choice;
+    let choice = $state('system');
+    let resolved = $state('light');
+    let listeningMq = null;
+    const apply = () => {
+        if (typeof document !== 'undefined')
+            document.documentElement.dataset.theme = resolved;
+    };
+    const persist = () => {
+        if (typeof localStorage === 'undefined')
+            return;
+        try {
+            localStorage.setItem(storageKeyFor(), choice);
+        }
+        catch {
+            /* blocked storage — the attribute still flips for this session */
+        }
+    };
+    return {
+        get choice() {
+            return choice;
+        },
+        get resolved() {
+            return resolved;
+        },
+        adopt() {
+            choice = readStoredChoice();
+            const attr = typeof document !== 'undefined' ? document.documentElement.dataset.theme : undefined;
+            if (attr === 'dark' || attr === 'light') {
+                resolved = attr;
+            }
+            else {
+                resolved = resolve(choice);
+                apply();
+            }
+            this.listen();
+        },
+        set(next) {
+            choice = next;
+            resolved = resolve(next);
+            persist();
+            apply();
+        },
+        listen() {
+            if (typeof window === 'undefined' || !window.matchMedia)
+                return;
+            const mq = window.matchMedia('(prefers-color-scheme: dark)');
+            if (listeningMq === mq)
+                return; // one listener per media-query object
+            listeningMq = mq;
+            mq.addEventListener('change', (e) => {
+                if (choice !== 'system')
+                    return; // pinned ignores the OS
+                resolved = e.matches ? 'dark' : 'light';
+                apply();
+            });
+        }
+    };
+}

package/package.json

@@ -1,6 +1,35 @@
 {
-  "name": "@deepseek-insight/container-base",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@deepseek-insight/container-base",
+	"version": "0.1.0",
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"svelte": "./dist/index.js",
+			"default": "./dist/index.js"
+		},
+		"./theme/tokens.css": "./src/theme/tokens.css"
+	},
+	"files": [
+		"dist",
+		"src",
+		"README.md"
+	],
+	"peerDependencies": {
+		"svelte": "^5.0.0"
+	},
+	"peerDependenciesMeta": {
+		"svelte": {
+			"required": true
+		}
+	},
+	"scripts": {
+		"build:package": "svelte-package -i src -o dist",
+		"lint:package": "publint",
+		"test": "vitest run --root ../.. --project dom packages/container-base/tests"
+	},
+	"devDependencies": {
+		"@sveltejs/package": "^3.0.2",
+		"publint": "^0.3.25"
+	}
+}

package/src/components/ChordPaletteOverlay.svelte

@@ -0,0 +1,99 @@
+<script lang="ts">
+	/**
+	 * ChordPaletteOverlay — the armed chord's face (ADR-0006a amendment
+	 * D16/D18 port; container-base W4, ADR-0062 D8): a centered overlay
+	 * with the live option rows and a decay ticker. The consumer passes
+	 * its OWN labels (rows carry label text; title/ariaLabel arrive as
+	 * props — the package never learns a translation system) and its
+	 * action-window length (windowMs). The overlay holds NO armed state:
+	 * open/since come in, onexpire fires out.
+	 *
+	 * While open it fills a footer progress bar 0→100% across
+	 * idleCloseMs — inside windowMs the bar reads in-action, past it
+	 * idle — and at 100% fires onexpire once. The clock is THIS
+	 * component's visibility lifecycle (D18: view-lifecycle, not
+	 * reducer state).
+	 */
+
+	let {
+		open,
+		rows,
+		since,
+		windowMs,
+		idleCloseMs = 10_000,
+		title,
+		ariaLabel,
+		onexpire
+	}: {
+		/** True between the arming chord and the fire / disarm / decay. */
+		open: boolean;
+		/** The live options, already filtered by the consumer's reducer. */
+		rows: { key: string; label: string }[];
+		/** Date.now() of the arming — the decay clock's zero. */
+		since: number;
+		/** The consumer's action-window length (ms) — inside it the bar
+		 *  reads in-action; the consumer owns the semantics (ADR-0052). */
+		windowMs: number;
+		/** The idle window before the overlay closes itself (default 10s). */
+		idleCloseMs?: number;
+		/** The strip title (consumer-localized, names the armed prefix). */
+		title: string;
+		/** Accessible name for the overlay (consumer-localized). */
+		ariaLabel: string;
+		/** Fired once at 100% — the host resets the chord. */
+		onexpire?: () => void;
+	} = $props();
+
+	// The decay clock: the ticker runs ONLY while open — the host's timer
+	// discipline counts every persistent client interval, and an overlay
+	// that lives for seconds must not add a permanent one.
+	let now = $state(Date.now());
+	const elapsed = $derived(open ? Math.max(0, Math.min(now - (since || Date.now()), idleCloseMs)) : 0);
+	const expired = $derived(open && elapsed >= idleCloseMs);
+
+	$effect(() => {
+		if (!open) return;
+		const ticker = setInterval(() => (now = Date.now()), 100);
+		return () => clearInterval(ticker);
+	});
+	$effect(() => {
+		if (expired) onexpire?.();
+	});
+	const pct = $derived(Math.round((elapsed / idleCloseMs) * 100));
+	const inActionWindow = $derived(elapsed < windowMs);
+	// Ground rule: the ticker colors cross through tokens — no palette classes (W6).
+	const barColor = $derived(inActionWindow ? 'bg-[var(--color-chord-armed)]' : 'bg-[var(--color-chord-idle)]');
+</script>
+
+{#if open}
+	<div
+		class="fixed top-1/2 left-1/2 z-50 w-72 -translate-x-1/2 -translate-y-1/2 rounded-lg border border-[var(--color-surface-border)] bg-[var(--color-surface-elevated)] px-3 py-2 shadow-lg backdrop-blur"
+		data-testid="chord-palette"
+		data-chord-elapsed={elapsed}
+		aria-live="polite"
+		aria-label={ariaLabel}
+	>
+		<div class="mb-1 text-[10px] font-semibold tracking-wide text-[var(--color-text-secondary)] uppercase">
+			{title}
+		</div>
+		<ul class="m-0 list-none space-y-0.5 p-0">
+			{#each rows as row (row.key)}
+				<li class="flex items-center gap-2 text-xs" data-testid="chord-palette-row" data-chord-key={row.key}>
+					<kbd class="min-w-5 rounded border border-[var(--color-surface-border)] bg-[var(--color-surface-secondary)] px-1 text-center font-mono text-[11px]">
+						{row.key}
+					</kbd>
+					<span class="text-[var(--color-text-primary)]">{row.label}</span>
+				</li>
+			{/each}
+		</ul>
+		<!-- The idle clock: in-action while the consumer's window is open, idle after -->
+		<div class="mt-2 h-1 w-full overflow-hidden rounded bg-[var(--color-surface-secondary)]" data-testid="chord-palette-decay">
+			<div
+				class="h-full {barColor} transition-[width] duration-100 ease-linear"
+				style="width: {pct}%"
+				data-testid="chord-palette-progress"
+				data-chord-phase={inActionWindow ? 'action' : 'idle'}
+			></div>
+		</div>
+	</div>
+{/if}