sh3-core 0.13.1 → 0.13.3

package/dist/primitives/widgets/Select.svelte.test.js

@@ -0,0 +1,37 @@
+import { describe, it, expect, vi } from 'vitest';
+import { render, fireEvent } from '@testing-library/svelte';
+import Select from './Select.svelte';
+vi.mock('../../shellRuntime.svelte', () => ({
+    shell: { popup: { show: () => ({ close: () => { } }) } },
+}));
+describe('Select event contract', () => {
+    const options = [
+        { value: 'a', label: 'Apple' },
+        { value: 'b', label: 'Banana' },
+        { value: 'c', label: 'Cherry' },
+    ];
+    it('fires onchange via native select in single mode', async () => {
+        const onchange = vi.fn();
+        const { container } = render(Select, { props: { options, value: 'a', onchange } });
+        const native = container.querySelector('select');
+        native.value = 'c';
+        await fireEvent.change(native);
+        expect(onchange).toHaveBeenCalledTimes(1);
+        expect(onchange).toHaveBeenCalledWith('c');
+    });
+    it('defaults to empty array in multi mode', () => {
+        const { container } = render(Select, { props: { options, multiple: true } });
+        const native = container.querySelector('select');
+        // No <option> should carry a `selected` attribute when value defaults to [].
+        // (happy-dom may surface a selectedOptions item for the first option in a
+        // multi-select that has no explicit selection — assert the attribute the
+        // template controls instead.)
+        const optionsEls = Array.from(native.querySelectorAll('option'));
+        expect(optionsEls.every((o) => !o.hasAttribute('selected'))).toBe(true);
+    });
+    it('defaults to empty string in single mode', () => {
+        const { container } = render(Select, { props: { options } });
+        const trigger = container.querySelector('.sh3-select__display');
+        expect(trigger === null || trigger === void 0 ? void 0 : trigger.classList.contains('sh3-select__display--placeholder')).toBe(true);
+    });
+});

package/dist/primitives/widgets/Slider.svelte

@@ -1,4 +1,5 @@
 <script lang="ts">
+  import type { LiveInputEvents } from './_contract';
   import { valueToPercent } from './Slider';
 
   let {
@@ -12,6 +13,7 @@
     invalid = false,
     size = 'md',
     orientation = 'horizontal',
+    oninput,
     onchange,
   }: {
     value?: number;
@@ -24,8 +26,7 @@
     invalid?: boolean;
     size?: 'sm' | 'md';
     orientation?: 'horizontal' | 'vertical';
-    onchange?: (next: number) => void;
-  } = $props();
+  } & LiveInputEvents<number> = $props();
 
   const pct = $derived(valueToPercent(value, min, max));
 </script>
@@ -50,6 +51,7 @@
     {disabled}
     aria-invalid={invalid || undefined}
     bind:value
+    oninput={() => oninput?.(value)}
     onchange={() => onchange?.(value)}
   />
   {#if showValue}

package/dist/primitives/widgets/Slider.svelte.d.ts

@@ -1,3 +1,4 @@
+import type { LiveInputEvents } from './_contract';
 type $$ComponentProps = {
     value?: number;
     min?: number;
@@ -9,8 +10,7 @@ type $$ComponentProps = {
     invalid?: boolean;
     size?: 'sm' | 'md';
     orientation?: 'horizontal' | 'vertical';
-    onchange?: (next: number) => void;
-};
+} & LiveInputEvents<number>;
 declare const Slider: import("svelte").Component<$$ComponentProps, {}, "value">;
 type Slider = ReturnType<typeof Slider>;
 export default Slider;

package/dist/primitives/widgets/Slider.svelte.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/primitives/widgets/Slider.svelte.test.js

@@ -0,0 +1,22 @@
+import { describe, it, expect, vi } from 'vitest';
+import { render, fireEvent } from '@testing-library/svelte';
+import Slider from './Slider.svelte';
+describe('Slider event contract', () => {
+    it('fires oninput on native input event', async () => {
+        const oninput = vi.fn();
+        const { container } = render(Slider, { props: { value: 0, min: 0, max: 100, oninput } });
+        const range = container.querySelector('input[type=range]');
+        await fireEvent.input(range, { target: { value: '42' } });
+        expect(oninput).toHaveBeenCalledTimes(1);
+        expect(oninput).toHaveBeenCalledWith(42);
+    });
+    it('fires onchange on native change event', async () => {
+        const onchange = vi.fn();
+        const { container } = render(Slider, { props: { value: 0, min: 0, max: 100, onchange } });
+        const range = container.querySelector('input[type=range]');
+        await fireEvent.input(range, { target: { value: '70' } });
+        await fireEvent.change(range, { target: { value: '70' } });
+        expect(onchange).toHaveBeenCalledTimes(1);
+        expect(onchange).toHaveBeenCalledWith(70);
+    });
+});

package/dist/primitives/widgets/SliderGroup.svelte

@@ -1,4 +1,5 @@
 <script lang="ts">
+  import type { LiveInputEvents } from './_contract';
   import Slider from './Slider.svelte';
 
   type Channel = { id: string; label: string; min?: number; max?: number; step?: number };
@@ -10,6 +11,7 @@
     showValues = false,
     disabled = false,
     size = 'md',
+    oninput,
     onchange,
   }: {
     orientation?: 'horizontal' | 'vertical';
@@ -18,8 +20,7 @@
     showValues?: boolean;
     disabled?: boolean;
     size?: 'sm' | 'md';
-    onchange?: (next: Record<string, number>) => void;
-  } = $props();
+  } & LiveInputEvents<Record<string, number>> = $props();
 </script>
 
 <div class="sh3-sg sh3-sg--{orientation}">
@@ -38,6 +39,7 @@
           () => values[ch.id] ?? 0,
           (n: number) => values = { ...values, [ch.id]: n }
         }
+        oninput={() => oninput?.(values)}
         onchange={() => onchange?.(values)}
       />
     </div>

package/dist/primitives/widgets/SliderGroup.svelte.d.ts

@@ -1,3 +1,4 @@
+import type { LiveInputEvents } from './_contract';
 type Channel = {
     id: string;
     label: string;
@@ -12,8 +13,7 @@ type $$ComponentProps = {
     showValues?: boolean;
     disabled?: boolean;
     size?: 'sm' | 'md';
-    onchange?: (next: Record<string, number>) => void;
-};
+} & LiveInputEvents<Record<string, number>>;
 declare const SliderGroup: import("svelte").Component<$$ComponentProps, {}, "values">;
 type SliderGroup = ReturnType<typeof SliderGroup>;
 export default SliderGroup;

package/dist/primitives/widgets/SliderGroup.svelte.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/primitives/widgets/SliderGroup.svelte.test.js

@@ -0,0 +1,34 @@
+import { describe, it, expect, vi } from 'vitest';
+import { render, fireEvent } from '@testing-library/svelte';
+import SliderGroup from './SliderGroup.svelte';
+describe('SliderGroup event contract', () => {
+    const channels = [
+        { id: 'r', label: 'R' },
+        { id: 'g', label: 'G' },
+        { id: 'b', label: 'B' },
+    ];
+    it('emits oninput with full record when a child slider moves', async () => {
+        const oninput = vi.fn();
+        const { container } = render(SliderGroup, {
+            props: { channels, values: { r: 0, g: 0, b: 0 }, oninput },
+        });
+        const ranges = container.querySelectorAll('input[type=range]');
+        const gSlider = ranges[1];
+        await fireEvent.input(gSlider, { target: { value: '50' } });
+        expect(oninput).toHaveBeenCalled();
+        const lastCall = oninput.mock.calls[oninput.mock.calls.length - 1][0];
+        expect(lastCall).toEqual({ r: 0, g: 50, b: 0 });
+    });
+    it('emits onchange with full record on commit', async () => {
+        const onchange = vi.fn();
+        const { container } = render(SliderGroup, {
+            props: { channels, values: { r: 0, g: 0, b: 0 }, onchange },
+        });
+        const bSlider = container.querySelectorAll('input[type=range]')[2];
+        await fireEvent.input(bSlider, { target: { value: '75' } });
+        await fireEvent.change(bSlider, { target: { value: '75' } });
+        expect(onchange).toHaveBeenCalled();
+        const lastCall = onchange.mock.calls[onchange.mock.calls.length - 1][0];
+        expect(lastCall).toEqual({ r: 0, g: 0, b: 75 });
+    });
+});

package/dist/primitives/widgets/Textarea.svelte

@@ -1,4 +1,6 @@
 <script lang="ts">
+  import type { LiveInputEvents } from './_contract';
+
   let {
     value = $bindable(''),
     label,
@@ -11,6 +13,7 @@
     required = false,
     rows = 3,
     resize = 'vertical',
+    oninput,
     onchange,
   }: {
     value?: string;
@@ -24,8 +27,7 @@
     required?: boolean;
     rows?: number;
     resize?: 'none' | 'vertical' | 'both';
-    onchange?: (next: string) => void;
-  } = $props();
+  } & LiveInputEvents<string> = $props();
 
   const showError = $derived(invalid && !!error);
   const helperText = $derived(showError ? error : helper);
@@ -42,6 +44,7 @@
     {rows}
     aria-invalid={invalid || undefined}
     bind:value
+    oninput={() => oninput?.(value)}
     onblur={() => onchange?.(value)}
   ></textarea>
   {#if helperText}<span class="sh3-textarea__helper" class:sh3-textarea__helper--error={showError}>{helperText}</span>{/if}

package/dist/primitives/widgets/Textarea.svelte.d.ts

@@ -1,3 +1,4 @@
+import type { LiveInputEvents } from './_contract';
 type $$ComponentProps = {
     value?: string;
     label?: string;
@@ -10,8 +11,7 @@ type $$ComponentProps = {
     required?: boolean;
     rows?: number;
     resize?: 'none' | 'vertical' | 'both';
-    onchange?: (next: string) => void;
-};
+} & LiveInputEvents<string>;
 declare const Textarea: import("svelte").Component<$$ComponentProps, {}, "value">;
 type Textarea = ReturnType<typeof Textarea>;
 export default Textarea;

package/dist/primitives/widgets/Textarea.svelte.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/primitives/widgets/Textarea.svelte.test.js

@@ -0,0 +1,29 @@
+import { describe, it, expect, vi } from 'vitest';
+import { render, fireEvent } from '@testing-library/svelte';
+import Textarea from './Textarea.svelte';
+describe('Textarea event contract', () => {
+    it('fires oninput on every keystroke', async () => {
+        const oninput = vi.fn();
+        const { container } = render(Textarea, { props: { value: '', oninput } });
+        const ta = container.querySelector('textarea');
+        await fireEvent.input(ta, { target: { value: 'a' } });
+        await fireEvent.input(ta, { target: { value: 'ab' } });
+        expect(oninput).toHaveBeenCalledTimes(2);
+        expect(oninput).toHaveBeenNthCalledWith(2, 'ab');
+    });
+    it('fires onchange once on blur with final value', async () => {
+        const onchange = vi.fn();
+        const { container } = render(Textarea, { props: { value: '', onchange } });
+        const ta = container.querySelector('textarea');
+        await fireEvent.input(ta, { target: { value: 'done' } });
+        await fireEvent.blur(ta);
+        expect(onchange).toHaveBeenCalledTimes(1);
+        expect(onchange).toHaveBeenCalledWith('done');
+    });
+    it('propagates rows and resize props', () => {
+        const { container } = render(Textarea, { props: { value: '', rows: 5, resize: 'none' } });
+        const ta = container.querySelector('textarea');
+        expect(ta.getAttribute('rows')).toBe('5');
+        expect(ta.style.resize).toBe('none');
+    });
+});

package/dist/primitives/widgets/UserPicker.svelte

@@ -0,0 +1,53 @@
+<script lang="ts">
+  import type { CommitOnlyEvents } from './_contract';
+  import PickerList from './PickerList.svelte';
+  import type { PickerItem } from './PickerList';
+  import { usersAdminState, refreshAdminUsers } from '../../auth/admin-users.svelte';
+
+  let {
+    value = $bindable<string[]>([]),
+    onchange,
+    disabled = false,
+    size = 'md',
+  }: {
+    value?: string[];
+    disabled?: boolean;
+    size?: 'sm' | 'md';
+  } & CommitOnlyEvents<string[]> = $props();
+
+  // Kick a fetch if the cache is empty. The store dedupes concurrent calls,
+  // so multiple UserPicker mounts share one request. After completion
+  // subsequent mounts see the cached state.
+  if (
+    usersAdminState.users.length === 0 &&
+    !usersAdminState.loading &&
+    !usersAdminState.error
+  ) {
+    void refreshAdminUsers();
+  }
+
+  const items = $derived<PickerItem[]>(
+    usersAdminState.users.map((u) => ({
+      id: u.id,
+      label: u.displayName || u.username,
+      sublabel: u.username,
+    })),
+  );
+
+  function handleChange(next: string[]) {
+    value = next;
+    onchange?.(next);
+  }
+</script>
+
+<PickerList
+  {items}
+  {value}
+  onchange={handleChange}
+  loading={usersAdminState.loading}
+  error={usersAdminState.error}
+  onRetry={() => void refreshAdminUsers()}
+  emptyText="No users found."
+  {disabled}
+  {size}
+/>

package/dist/primitives/widgets/UserPicker.svelte.d.ts

@@ -0,0 +1,9 @@
+import type { CommitOnlyEvents } from './_contract';
+type $$ComponentProps = {
+    value?: string[];
+    disabled?: boolean;
+    size?: 'sm' | 'md';
+} & CommitOnlyEvents<string[]>;
+declare const UserPicker: import("svelte").Component<$$ComponentProps, {}, "value">;
+type UserPicker = ReturnType<typeof UserPicker>;
+export default UserPicker;

package/dist/primitives/widgets/UserPicker.svelte.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/primitives/widgets/UserPicker.svelte.test.js

@@ -0,0 +1,30 @@
+import { describe, it, expect, vi } from 'vitest';
+import { render, fireEvent } from '@testing-library/svelte';
+import UserPicker from './UserPicker.svelte';
+const refresh = vi.fn();
+vi.mock('../../auth/admin-users.svelte', () => ({
+    usersAdminState: {
+        users: [
+            { id: 'u1', displayName: 'Alice', username: 'alice' },
+            { id: 'u2', displayName: '', username: 'bob' },
+        ],
+        loading: false,
+        error: null,
+    },
+    refreshAdminUsers: () => refresh(),
+}));
+describe('UserPicker event contract', () => {
+    it('renders cached users with displayName fallback to username', () => {
+        const { container } = render(UserPicker, { props: { value: [] } });
+        const labels = Array.from(container.querySelectorAll('.sh3-picker__row-label')).map((el) => el.textContent);
+        expect(labels).toEqual(['Alice', 'bob']);
+    });
+    it('fires onchange with id array on toggle', async () => {
+        const onchange = vi.fn();
+        const { container } = render(UserPicker, { props: { value: [], onchange } });
+        const checkboxes = container.querySelectorAll('input[type=checkbox]');
+        await fireEvent.click(checkboxes[0]);
+        expect(onchange).toHaveBeenCalledTimes(1);
+        expect(onchange).toHaveBeenCalledWith(['u1']);
+    });
+});

package/dist/primitives/widgets/UserPicker.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/primitives/widgets/UserPicker.test.js

@@ -0,0 +1,115 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { mount, unmount, tick } from 'svelte';
+import UserPicker from './UserPicker.svelte';
+import { usersAdminState, __resetAdminUsersForTest, } from '../../auth/admin-users.svelte';
+let host;
+let cmp = null;
+beforeEach(() => {
+    host = document.createElement('div');
+    document.body.appendChild(host);
+    __resetAdminUsersForTest();
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
+        ok: true,
+        json: async () => [
+            { id: 'u-1', username: 'alice', displayName: 'Alice', role: 'user', createdAt: '', updatedAt: '' },
+            { id: 'u-2', username: 'bob', displayName: 'Bob', role: 'admin', createdAt: '', updatedAt: '' },
+        ],
+    }));
+});
+afterEach(() => {
+    if (cmp) {
+        unmount(cmp);
+        cmp = null;
+    }
+    host.remove();
+    __resetAdminUsersForTest();
+});
+describe('UserPicker', () => {
+    it('triggers a fetch on first mount and renders rows once loaded', async () => {
+        cmp = mount(UserPicker, { target: host, props: { value: [] } });
+        expect(globalThis.fetch).toHaveBeenCalledTimes(1);
+        await new Promise((r) => setTimeout(r, 0));
+        await tick();
+        const rows = host.querySelectorAll('.sh3-picker__row');
+        expect(rows.length).toBe(2);
+    });
+    it('reflects selected user ids as checked rows', async () => {
+        // Pre-populate the cache so the mount can render synchronously.
+        usersAdminState.users = [
+            { id: 'u-1', username: 'alice', displayName: 'Alice', role: 'user', createdAt: '', updatedAt: '' },
+            { id: 'u-2', username: 'bob', displayName: 'Bob', role: 'admin', createdAt: '', updatedAt: '' },
+        ];
+        cmp = mount(UserPicker, { target: host, props: { value: ['u-2'] } });
+        await tick();
+        const checks = host.querySelectorAll('input[type="checkbox"]');
+        const aliceChecked = Array.from(checks).find((c) => { var _a, _b; return (_b = (_a = c.closest('.sh3-picker__row')) === null || _a === void 0 ? void 0 : _a.textContent) === null || _b === void 0 ? void 0 : _b.includes('alice'); }).checked;
+        const bobChecked = Array.from(checks).find((c) => { var _a, _b; return (_b = (_a = c.closest('.sh3-picker__row')) === null || _a === void 0 ? void 0 : _a.textContent) === null || _b === void 0 ? void 0 : _b.includes('bob'); }).checked;
+        expect(aliceChecked).toBe(false);
+        expect(bobChecked).toBe(true);
+    });
+    it('subsequent mounts reuse the cached state and skip the fetch', async () => {
+        cmp = mount(UserPicker, { target: host, props: { value: [] } });
+        await new Promise((r) => setTimeout(r, 0));
+        await tick();
+        expect(globalThis.fetch).toHaveBeenCalledTimes(1);
+        const host2 = document.createElement('div');
+        document.body.appendChild(host2);
+        const cmp2 = mount(UserPicker, { target: host2, props: { value: [] } });
+        await tick();
+        expect(globalThis.fetch).toHaveBeenCalledTimes(1);
+        unmount(cmp2);
+        host2.remove();
+    });
+    it('uses displayName for label and username for sublabel', async () => {
+        usersAdminState.users = [
+            { id: 'u-1', username: 'alice', displayName: 'Alice', role: 'user', createdAt: '', updatedAt: '' },
+            { id: 'u-2', username: 'bob', displayName: 'Bob', role: 'admin', createdAt: '', updatedAt: '' },
+        ];
+        cmp = mount(UserPicker, { target: host, props: { value: [] } });
+        await tick();
+        const labels = host.querySelectorAll('.sh3-picker__row-label');
+        const subs = host.querySelectorAll('.sh3-picker__row-sub');
+        const labelTexts = Array.from(labels).map((l) => l.textContent).sort();
+        const subTexts = Array.from(subs).map((l) => l.textContent).sort();
+        expect(labelTexts).toEqual(['Alice', 'Bob']);
+        expect(subTexts).toEqual(['alice', 'bob']);
+    });
+    it('fires onchange with the new value array on row click', async () => {
+        usersAdminState.users = [
+            { id: 'u-1', username: 'alice', displayName: 'Alice', role: 'user', createdAt: '', updatedAt: '' },
+            { id: 'u-2', username: 'bob', displayName: 'Bob', role: 'admin', createdAt: '', updatedAt: '' },
+        ];
+        let received = null;
+        cmp = mount(UserPicker, {
+            target: host,
+            props: {
+                value: [],
+                onchange: (next) => { received = next; },
+            },
+        });
+        await tick();
+        const aliceRow = Array.from(host.querySelectorAll('.sh3-picker__row'))
+            .find((r) => { var _a; return (_a = r.textContent) === null || _a === void 0 ? void 0 : _a.includes('alice'); });
+        aliceRow.querySelector('input[type="checkbox"]').click();
+        await tick();
+        expect(received).toEqual(['u-1']);
+    });
+    it('shows the loading state before the first response', async () => {
+        let resolveFetch = null;
+        globalThis.fetch.mockReset();
+        globalThis.fetch.mockImplementationOnce(() => new Promise((res) => { resolveFetch = res; }));
+        cmp = mount(UserPicker, { target: host, props: { value: [] } });
+        await tick();
+        expect(host.textContent).toContain('Loading');
+        resolveFetch({ ok: true, json: async () => [] });
+    });
+    it('shows an error and a Retry button on fetch failure', async () => {
+        globalThis.fetch.mockReset();
+        globalThis.fetch.mockResolvedValueOnce({ ok: false, status: 500 });
+        cmp = mount(UserPicker, { target: host, props: { value: [] } });
+        await new Promise((r) => setTimeout(r, 0));
+        await tick();
+        expect(host.textContent).toMatch(/500/);
+        expect(host.querySelector('.sh3-picker__retry')).not.toBeNull();
+    });
+});

package/dist/primitives/widgets/_contract.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Widget event-contract types — codifies which widgets expose `oninput`
+ * (live, during-interaction) vs `onchange`-only (commit-only).
+ *
+ * Each widget under `widgets/` MUST compose one of these into its prop
+ * type. Adding a third bucket requires a new ADR-022 amendment.
+ *
+ * Internal — not exported from `api.ts`.
+ */
+/**
+ * Widgets with a continuous interaction phase (typing, dragging).
+ * - oninput fires on every internal value change (keystroke, drag tick).
+ * - onchange fires once at commit (blur for text inputs, mouseup / native
+ *   change for sliders).
+ * Mirrors HTML <input>'s input vs change distinction.
+ */
+export type LiveInputEvents<T> = {
+    oninput?: (next: T) => void;
+    onchange?: (next: T) => void;
+};
+/**
+ * Widgets whose interaction is a single discrete commit (click, pick).
+ * - onchange fires once when the value changes. No oninput.
+ */
+export type CommitOnlyEvents<T> = {
+    onchange?: (next: T) => void;
+};

package/dist/primitives/widgets/_contract.js

@@ -0,0 +1,10 @@
+/**
+ * Widget event-contract types — codifies which widgets expose `oninput`
+ * (live, during-interaction) vs `onchange`-only (commit-only).
+ *
+ * Each widget under `widgets/` MUST compose one of these into its prop
+ * type. Adding a third bucket requires a new ADR-022 amendment.
+ *
+ * Internal — not exported from `api.ts`.
+ */
+export {};

package/dist/projects/session-state.svelte.d.ts

@@ -0,0 +1,17 @@
+export declare const sessionState: {
+    activeProjectId: string | null;
+};
+/**
+ * Set the active project id. Side-effects when the value actually changes:
+ *   - the active app (if any) is unloaded — its document handles and zone
+ *     state are bound to the previous scope and cannot follow.
+ *   - the breadcrumb pointer is cleared so re-entering an app cannot point
+ *     at the wrong namespace.
+ *
+ * Setting the same value is a no-op (no app unload, no breadcrumb clear).
+ *
+ * The unloadApp call is deferred to a dynamic import so this module stays
+ * importable from circular-dependency hot-paths (lifecycle imports
+ * sessionState; sessionState here would otherwise import lifecycle eagerly).
+ */
+export declare function setActiveProjectId(id: string | null): void;

package/dist/projects/session-state.svelte.js

@@ -0,0 +1,39 @@
+/*
+ * Session-zone state for the active project scope.
+ *
+ * `null` means the user is in their personal scope. Otherwise it carries
+ * the active project's id. Read at app launch by `launchApp` to bind
+ * `ctx.scopeId`, and read by ShellHome / BrandSlot for UX rendering.
+ *
+ * Setting the slot through `setActiveProjectId` is the only supported
+ * mutation path: it clears the breadcrumb pointer (so resuming an app
+ * after a scope change can't open a stale doc handle) and unloads any
+ * active app (whose scopeId is bound to the old scope).
+ */
+import { activeApp, breadcrumbApp } from '../apps/registry.svelte';
+export const sessionState = $state({
+    activeProjectId: null,
+});
+/**
+ * Set the active project id. Side-effects when the value actually changes:
+ *   - the active app (if any) is unloaded — its document handles and zone
+ *     state are bound to the previous scope and cannot follow.
+ *   - the breadcrumb pointer is cleared so re-entering an app cannot point
+ *     at the wrong namespace.
+ *
+ * Setting the same value is a no-op (no app unload, no breadcrumb clear).
+ *
+ * The unloadApp call is deferred to a dynamic import so this module stays
+ * importable from circular-dependency hot-paths (lifecycle imports
+ * sessionState; sessionState here would otherwise import lifecycle eagerly).
+ */
+export function setActiveProjectId(id) {
+    if (sessionState.activeProjectId === id)
+        return;
+    const previousActive = activeApp.id;
+    sessionState.activeProjectId = id;
+    breadcrumbApp.id = null;
+    if (previousActive) {
+        void import('../apps/lifecycle').then((m) => m.unloadApp(previousActive));
+    }
+}

package/dist/projects/session-state.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/projects/session-state.test.js

@@ -0,0 +1,55 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { sessionState, setActiveProjectId } from './session-state.svelte';
+import { breadcrumbApp, activeApp } from '../apps/registry.svelte';
+vi.mock('../apps/lifecycle', () => ({
+    unloadApp: vi.fn(),
+}));
+describe('sessionState.activeProjectId', () => {
+    beforeEach(async () => {
+        sessionState.activeProjectId = null;
+        breadcrumbApp.id = null;
+        activeApp.id = null;
+        const lifecycle = await import('../apps/lifecycle');
+        lifecycle.unloadApp.mockClear();
+    });
+    it('starts as null', () => {
+        expect(sessionState.activeProjectId).toBeNull();
+    });
+    it('setActiveProjectId updates the slot', () => {
+        setActiveProjectId('acme-abcd');
+        expect(sessionState.activeProjectId).toBe('acme-abcd');
+    });
+    it('setActiveProjectId clears breadcrumbApp.id when the value actually changes', () => {
+        breadcrumbApp.id = 'notes';
+        setActiveProjectId('acme-abcd');
+        expect(breadcrumbApp.id).toBeNull();
+    });
+    it('setActiveProjectId(null) also clears breadcrumb', () => {
+        sessionState.activeProjectId = 'acme-abcd';
+        breadcrumbApp.id = 'notes';
+        setActiveProjectId(null);
+        expect(breadcrumbApp.id).toBeNull();
+        expect(sessionState.activeProjectId).toBeNull();
+    });
+    it('setting the same value is a no-op (does not clear breadcrumb)', () => {
+        setActiveProjectId('acme-abcd');
+        breadcrumbApp.id = 'notes';
+        setActiveProjectId('acme-abcd');
+        expect(breadcrumbApp.id).toBe('notes');
+    });
+    it('unloads the active app on scope change (its doc handle is scope-bound)', async () => {
+        const lifecycle = await import('../apps/lifecycle');
+        activeApp.id = 'notes';
+        setActiveProjectId('acme-abcd');
+        // unloadApp is called via a dynamic import — wait for it to resolve.
+        await new Promise((r) => setTimeout(r, 0));
+        expect(lifecycle.unloadApp).toHaveBeenCalledWith('notes');
+    });
+    it('does not call unloadApp when no app is active', async () => {
+        const lifecycle = await import('../apps/lifecycle');
+        activeApp.id = null;
+        setActiveProjectId('acme-abcd');
+        await Promise.resolve();
+        expect(lifecycle.unloadApp).not.toHaveBeenCalled();
+    });
+});