sh3-core 0.17.0 → 0.17.2

package/dist/overlays/DrawerSurface.svelte

@@ -0,0 +1,141 @@
+<script lang="ts">
+  /*
+   * One drawer frame anchored to an edge. Renders nothing when closed.
+   * Open state slides the panel in over a backdrop. Tapping the backdrop
+   * fires onClose; tapping the close button does the same.
+   *
+   * Multi-slot drawers render a tab strip in the header. Single-slot
+   * drawers show the slot label only.
+   *
+   * Slot rendering goes through the standard SlotContainer path so the
+   * pooled host (and the mounted view) survives mount/unmount via the
+   * slot host pool — same mechanism as tab-drag re-parents.
+   */
+  import type { DrawerAnchor, DrawerSpec } from '../layout/compact/types';
+  import type { SlotNode } from '../layout/types';
+  import SlotContainer from '../layout/SlotContainer.svelte';
+
+  let {
+    anchor,
+    spec,
+    open,
+    activeSlotId,
+    onClose,
+    onActivate,
+  }: {
+    anchor: DrawerAnchor;
+    spec: DrawerSpec;
+    open: boolean;
+    activeSlotId: string | null;
+    onClose: () => void;
+    onActivate: (slotId: string) => void;
+  } = $props();
+
+  const activeSlot = $derived(
+    spec.slots.find((s) => s.slotId === activeSlotId) ?? spec.slots[0],
+  );
+
+  const slotNode: SlotNode = $derived({
+    type: 'slot',
+    slotId: activeSlot.slotId,
+    viewId: activeSlot.viewId,
+    role: activeSlot.role,
+  });
+</script>
+
+{#if open}
+  <div
+    class="drawer-backdrop"
+    onclick={onClose}
+    onkeydown={(e) => { if (e.key === 'Escape') onClose(); }}
+    role="presentation"
+  ></div>
+  <div
+    class="drawer drawer-{anchor}"
+    data-sh3-region="drawer"
+    data-sh3-anchor={anchor}
+  >
+    <header>
+      <span class="title">{activeSlot.label}</span>
+      <button
+        class="close"
+        onclick={onClose}
+        aria-label="Close drawer"
+      >×</button>
+    </header>
+    {#if spec.slots.length > 1}
+      <div class="tab-strip" role="tablist">
+        {#each spec.slots as s (s.slotId)}
+          <button
+            role="tab"
+            aria-selected={s.slotId === activeSlot.slotId}
+            class:active={s.slotId === activeSlot.slotId}
+            onclick={() => onActivate(s.slotId)}
+          >
+            {s.label}
+          </button>
+        {/each}
+      </div>
+    {/if}
+    <div class="body">
+      <SlotContainer node={slotNode} label={activeSlot.label} />
+    </div>
+  </div>
+{/if}
+
+<style>
+  .drawer-backdrop {
+    position: absolute;
+    inset: 0;
+    background: var(--sh3-overlay-backdrop, rgba(0, 0, 0, 0.35));
+    pointer-events: auto;
+  }
+  .drawer {
+    position: absolute;
+    background: var(--sh3-bg);
+    color: var(--sh3-fg);
+    box-shadow: var(--sh3-shadow-md, 0 0 16px rgba(0, 0, 0, 0.2));
+    display: flex;
+    flex-direction: column;
+    border: 1px solid var(--sh3-border);
+    pointer-events: auto;
+  }
+  .drawer-left  { top: 0; bottom: 0; left: 0;  width: min(360px, 80vw); }
+  .drawer-right { top: 0; bottom: 0; right: 0; width: min(360px, 80vw); }
+  .drawer-top   { left: 0; right: 0; top: 0;   height: min(50vh, 360px); }
+  header {
+    display: flex;
+    align-items: center;
+    padding: var(--sh3-pad-sm) var(--sh3-pad-md);
+    gap: var(--sh3-pad-md);
+    border-bottom: 1px solid var(--sh3-border);
+    background: var(--sh3-bg-elevated);
+  }
+  .title { font-weight: 600; }
+  .close {
+    margin-left: auto;
+    background: none;
+    border: none;
+    font-size: var(--sh3-font-lg);
+    cursor: pointer;
+    color: var(--sh3-fg-muted);
+    padding: 0 var(--sh3-pad-sm);
+  }
+  .close:hover { color: var(--sh3-fg); }
+  .tab-strip {
+    display: flex;
+    gap: 2px;
+    padding: var(--sh3-pad-xs) var(--sh3-pad-sm) 0;
+    background: var(--sh3-bg-sunken);
+  }
+  .tab-strip button {
+    padding: var(--sh3-pad-xs) var(--sh3-pad-sm);
+    border: 1px solid var(--sh3-border);
+    background: var(--sh3-bg-elevated);
+    border-bottom: none;
+    cursor: pointer;
+    color: var(--sh3-fg);
+  }
+  .tab-strip button.active { background: var(--sh3-bg); }
+  .body { flex: 1; min-height: 0; overflow: auto; }
+</style>

package/dist/overlays/DrawerSurface.svelte.d.ts

@@ -0,0 +1,12 @@
+import type { DrawerAnchor, DrawerSpec } from '../layout/compact/types';
+type $$ComponentProps = {
+    anchor: DrawerAnchor;
+    spec: DrawerSpec;
+    open: boolean;
+    activeSlotId: string | null;
+    onClose: () => void;
+    onActivate: (slotId: string) => void;
+};
+declare const DrawerSurface: import("svelte").Component<$$ComponentProps, {}, "">;
+type DrawerSurface = ReturnType<typeof DrawerSurface>;
+export default DrawerSurface;

package/dist/overlays/DrawerSurface.svelte.test.d.ts

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

package/dist/overlays/DrawerSurface.svelte.test.js

@@ -0,0 +1,67 @@
+/*
+ * DOM smoke test for DrawerSurface — when open with a single-slot spec,
+ * the drawer renders the slot's label in its header. When closed, it
+ * renders nothing.
+ *
+ * Re-parent contract testing (slot DOM container actually moves, doesn't
+ * remount) is handled by the browser-mode handheld-flip test.
+ */
+import { describe, it, expect, afterEach } from 'vitest';
+import { mount, unmount, flushSync } from 'svelte';
+import DrawerSurface from './DrawerSurface.svelte';
+const DrawerSurfaceAny = DrawerSurface;
+const spec = {
+    slots: [{ slotId: 'sb', viewId: 'v:sb', label: 'Files', role: 'sidebar' }],
+};
+const multiSpec = {
+    slots: [
+        { slotId: 'sb', viewId: 'v:sb', label: 'Files', role: 'sidebar' },
+        { slotId: 'pin', viewId: 'v:pin', label: 'Pinned', role: 'sidebar' },
+    ],
+};
+let mounted = null;
+let host = null;
+function renderHost(props) {
+    host = document.createElement('div');
+    host.style.position = 'relative';
+    document.body.appendChild(host);
+    mounted = mount(DrawerSurfaceAny, { target: host, props });
+    flushSync();
+    return host;
+}
+afterEach(() => {
+    if (mounted) {
+        unmount(mounted);
+        mounted = null;
+    }
+    if (host) {
+        host.remove();
+        host = null;
+    }
+});
+describe('DrawerSurface (dom)', () => {
+    it('renders nothing when closed', () => {
+        const el = renderHost({
+            anchor: 'left', spec, open: false, activeSlotId: null,
+            onClose: () => { }, onActivate: () => { },
+        });
+        expect(el.querySelector('[data-sh3-region="drawer"]')).toBeNull();
+    });
+    it('renders header with slot label when open', () => {
+        const el = renderHost({
+            anchor: 'left', spec, open: true, activeSlotId: 'sb',
+            onClose: () => { }, onActivate: () => { },
+        });
+        const header = el.querySelector('[data-sh3-region="drawer"] header');
+        expect(header === null || header === void 0 ? void 0 : header.textContent).toContain('Files');
+    });
+    it('multi-slot drawer renders a tab strip with one button per slot', () => {
+        const el = renderHost({
+            anchor: 'left', spec: multiSpec, open: true, activeSlotId: 'pin',
+            onClose: () => { }, onActivate: () => { },
+        });
+        const tabs = el.querySelectorAll('[data-sh3-region="drawer"] .tab-strip button');
+        expect(tabs.length).toBe(2);
+        expect(tabs[1].classList.contains('active')).toBe(true);
+    });
+});

package/dist/overlays/OverlayRoots.svelte

@@ -23,13 +23,16 @@
 
   // Layer metadata — order matches the stack in docs/design/layout.md.
   // Index 0 here is layer 1 (floating panels); layer 0 is the content area.
-  const overlayLayers: { layer: number; name: OverlayLayer }[] = [
-    { layer: 1, name: 'floating'     },
-    { layer: 2, name: 'drag-preview' },
-    { layer: 3, name: 'popup'        },
-    { layer: 4, name: 'modal'        },
-    { layer: 5, name: 'toast'        },
-    { layer: 6, name: 'command'      },
+  // The 'drawers' layer (compact-mode side panels) sits between docked (0)
+  // and floating (1); its z-index comes from --sh3-z-layer-drawers.
+  const overlayLayers: { layer: number | string; name: OverlayLayer; zToken: string }[] = [
+    { layer: 'drawers',     name: 'drawers',      zToken: '--sh3-z-layer-drawers' },
+    { layer: 1, name: 'floating',     zToken: '--sh3-z-layer-1' },
+    { layer: 2, name: 'drag-preview', zToken: '--sh3-z-layer-2' },
+    { layer: 3, name: 'popup',        zToken: '--sh3-z-layer-3' },
+    { layer: 4, name: 'modal',        zToken: '--sh3-z-layer-4' },
+    { layer: 5, name: 'toast',        zToken: '--sh3-z-layer-5' },
+    { layer: 6, name: 'command',      zToken: '--sh3-z-layer-6' },
   ];
 
   const overlayRoots: Partial<Record<OverlayLayer, HTMLDivElement>> = $state({});
@@ -55,12 +58,12 @@
 </script>
 
 <div class="sh3-overlays" aria-hidden="true">
-  {#each overlayLayers as { layer, name } (layer)}
+  {#each overlayLayers as { layer, name, zToken } (layer)}
     <div
       class="sh3-overlay-root"
       data-sh3-overlay={name}
       data-sh3-layer={layer}
-      style="z-index: var(--sh3-z-layer-{layer});"
+      style="z-index: var({zToken});"
       bind:this={overlayRoots[name]}
     >
       {#if name === 'floating'}

package/dist/overlays/types.d.ts

@@ -1,4 +1,4 @@
-export type OverlayLayer = 'floating' | 'drag-preview' | 'popup' | 'modal' | 'toast' | 'command';
+export type OverlayLayer = 'drawers' | 'floating' | 'drag-preview' | 'popup' | 'modal' | 'toast' | 'command';
 /** A handle returned by every overlay opener. Calling close() is idempotent. */
 export interface OverlayHandle {
     close(): void;

package/dist/sh3Api/headless.js

@@ -300,7 +300,15 @@ export function makeSh3Api(opts) {
         },
         listActions(actionOpts) {
             const all = listActionsFromEntries(listActionEntriesFromRegistry(), getLiveDispatcherState());
-            return (actionOpts === null || actionOpts === void 0 ? void 0 : actionOpts.activeOnly) ? all.filter((a) => a.active) : all;
+            let out = all;
+            if ((actionOpts === null || actionOpts === void 0 ? void 0 : actionOpts.submenuOf) !== undefined) {
+                const parent = actionOpts.submenuOf;
+                out = out.filter((a) => a.submenuOf === parent);
+            }
+            if (actionOpts === null || actionOpts === void 0 ? void 0 : actionOpts.activeOnly) {
+                out = out.filter((a) => a.active);
+            }
+            return out;
         },
         runAction(id, runOpts) {
             return dispatchActionProgrammatic(id, runOpts);

package/dist/sh3Api/headless.svelte.test.js

@@ -1,5 +1,8 @@
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, beforeEach } from 'vitest';
 import { makeSh3Api } from './headless';
+import { registerAction, __resetActionsRegistryForTest, } from '../actions/registry';
+import { __resetContributionsForTest } from '../contributions/registry';
+import { __resetDispatcherStateForTest } from '../actions/state.svelte';
 function makeMockZoneManager() {
     const data = {
         ephemeral: {},
@@ -57,3 +60,44 @@ describe('sh3Api readZone', () => {
         expect(api.readZone('not-a-shard', 'workspace')).toBe(null);
     });
 });
+describe('sh3Api listActions submenu filter', () => {
+    beforeEach(() => {
+        __resetContributionsForTest();
+        __resetActionsRegistryForTest();
+        __resetDispatcherStateForTest();
+    });
+    it('returns only children of the named parent when { submenuOf } is set', () => {
+        registerAction({ id: 'theme.set', label: 'Theme', scope: 'home', submenu: true }, 'shard.x');
+        registerAction({
+            id: 'theme.set:dark', label: 'Dark', scope: 'home',
+            submenuOf: 'theme.set', run: () => { },
+        }, 'shard.x');
+        registerAction({
+            id: 'theme.set:light', label: 'Light', scope: 'home',
+            submenuOf: 'theme.set', run: () => { },
+        }, 'shard.x');
+        registerAction({ id: 'unrelated', label: 'U', scope: 'home', run: () => { } }, 'shard.x');
+        const api = makeSh3Api({ callerKind: 'verb' });
+        const ids = api.listActions({ submenuOf: 'theme.set' }).map((d) => d.id);
+        expect(ids.sort()).toEqual(['theme.set:dark', 'theme.set:light']);
+    });
+    it('returns [] when no children match the parent id', () => {
+        registerAction({ id: 'home.go', label: 'Go', scope: 'home', run: () => { } }, 'shard.x');
+        const api = makeSh3Api({ callerKind: 'verb' });
+        expect(api.listActions({ submenuOf: 'nope' })).toEqual([]);
+    });
+    it('combines with { activeOnly } — both predicates must hold', () => {
+        registerAction({ id: 'p', label: 'P', scope: 'home', submenu: true }, 'shard.x');
+        // active child (home is active by default in the test state)
+        registerAction({ id: 'p:a', label: 'A', scope: 'home',
+            submenuOf: 'p', run: () => { } }, 'shard.x');
+        // inactive child (app scope, no active app)
+        registerAction({ id: 'p:b', label: 'B', scope: 'app',
+            submenuOf: 'p', run: () => { } }, 'shard.x');
+        const api = makeSh3Api({ callerKind: 'verb' });
+        const ids = api
+            .listActions({ submenuOf: 'p', activeOnly: true })
+            .map((d) => d.id);
+        expect(ids).toEqual(['p:a']);
+    });
+});

package/dist/sh3Runtime.svelte.d.ts

@@ -10,6 +10,8 @@ import type { ColorApi } from './color/api';
 import { type OpenContextMenuOpts, type OpenPaletteOpts } from './actions/listeners';
 import type { ActiveActionDescriptor } from './actions/types';
 import { type DispatchToTerminalResult } from './shell-shard/dispatch-to-terminal';
+import type { ViewportInfo, ViewportClass } from './viewport/types';
+import type { DrawerAnchor, DrawerStateMap } from './layout/compact/types';
 /**
  * The process-wide sh3 singleton exposed to shards and the sh3's own
  * internal code. Provides state zone creation and overlay managers.
@@ -39,6 +41,17 @@ export interface Sh3 {
     color: ColorApi;
     /** Actions facade — rebind keys, query bindings, open menus/palette. */
     actions: Sh3ActionsApi;
+    /**
+     * Reactive viewport classification. Subscribers fire on class change
+     * (desktop ↔ compact). Use `override(cls)` to pin a class for
+     * playgrounds and debug; pass null to restore auto-derivation.
+     */
+    readonly viewport: Sh3Viewport;
+    /**
+     * Compact-mode drawer surface controls. Inert on desktop — mutating
+     * methods throw rather than silently no-op so misuse is caught early.
+     */
+    readonly drawers: Sh3Drawers;
     /**
      * Dispatch `line` through a Terminal view's normal submit path. Used by
      * views outside a verb context (floating pickers, dialogs) to drive a
@@ -51,6 +64,29 @@ export interface Sh3 {
      */
     dispatchToTerminal(line: string): DispatchToTerminalResult;
 }
+/**
+ * Compact-mode drawer surface controls. Mutating methods throw on desktop
+ * so misuse surfaces as a loud error instead of a silent no-op.
+ */
+export interface Sh3Drawers {
+    readonly state: DrawerStateMap;
+    open(anchor: DrawerAnchor): void;
+    close(anchor: DrawerAnchor): void;
+    toggle(anchor: DrawerAnchor): void;
+    activate(anchor: DrawerAnchor, slotId: string): void;
+}
+/**
+ * Reactive viewport classification surface. See viewport/store.svelte.ts.
+ */
+export interface Sh3Viewport {
+    /** Reactive — read directly inside an effect, or use `subscribe()`. */
+    readonly current: ViewportInfo;
+    subscribe(cb: (i: ViewportInfo) => void): () => void;
+    /** Pin the class. Pass null to restore auto. Debug/playground only. */
+    override(cls: ViewportClass | null): void;
+    /** Currently-pinned override (null = auto). */
+    readonly pinned: ViewportClass | null;
+}
 /**
  * API for managing action bindings and triggering menus/palette
  * programmatically (e.g. from a future settings UI shard).

package/dist/sh3Runtime.svelte.js

@@ -28,6 +28,8 @@ import { setUserBindings, getLiveDispatcherState, onActiveChange as onActiveChan
 import { listActions, onActionsChange } from './actions/registry';
 import { listActiveFromEntries } from './actions/listActive';
 import { makeDispatchToTerminal } from './shell-shard/dispatch-to-terminal';
+import { viewportStore } from './viewport/store.svelte';
+import { drawerStore } from './layout/compact/drawerStore.svelte';
 const sh3Actions = {
     async rebind(appId, actionId, shortcut) {
         await saveUserBinding(appId, actionId, shortcut);
@@ -77,4 +79,35 @@ export const sh3 = {
     color: colorApi,
     actions: sh3Actions,
     dispatchToTerminal: makeDispatchToTerminal({ headless: false }),
+    viewport: {
+        get current() { return viewportStore.current; },
+        subscribe: (cb) => viewportStore.subscribe(cb),
+        override: (cls) => viewportStore.override(cls),
+        get pinned() { return viewportStore.pinned; },
+    },
+    drawers: {
+        get state() { return drawerStore.state; },
+        open: (anchor) => {
+            assertCompact('open');
+            drawerStore.open(anchor);
+        },
+        close: (anchor) => {
+            assertCompact('close');
+            drawerStore.close(anchor);
+        },
+        toggle: (anchor) => {
+            assertCompact('toggle');
+            drawerStore.toggle(anchor);
+        },
+        activate: (anchor, slotId) => {
+            assertCompact('activate');
+            drawerStore.activate(anchor, slotId);
+        },
+    },
 };
+function assertCompact(method) {
+    const cls = viewportStore.current.class;
+    if (cls !== 'compact') {
+        throw new Error(`Sh3.drawers.${method}: viewport class is "${cls}"; drawers exist only on compact`);
+    }
+}

package/dist/shards/types.d.ts

@@ -8,7 +8,7 @@ import type { Sh3Api } from '../verbs/types';
 import type { ShardContextKeys } from '../keys/types';
 import type { ContributionsApi } from '../contributions/types';
 import type { ActionsApi } from '../actions/types';
-import type { TreeRootRef } from '../layout/types';
+import type { TreeRootRef, SlotRole } from '../layout/types';
 export { PERMISSION_KEYS_MINT, type ShardContextKeys, type ApiKeyPublic, type MintOpts, ScopeEscalationError, ConsentDeniedError } from '../keys/types';
 /**
  * The object returned by `ViewFactory.mount`. The framework calls
@@ -38,6 +38,14 @@ export interface ViewHandle {
     closable?: boolean | {
         canClose(): Promise<boolean>;
     };
+    /**
+     * View-level slot-role default. The compact renderer reads this when
+     * the containing slot's `role` is unset; slot-level always wins.
+     *
+     * Lets a view declare "I'm a sidebar by nature" without forcing the
+     * app author to know. See `layout/compact/resolveRole.ts`.
+     */
+    defaultRole?: SlotRole;
 }
 /**
  * Context passed to `ViewFactory.mount` so the view knows which layout

package/dist/tokens.css

@@ -79,8 +79,9 @@
    * source of truth for the layer stack. No component outside the overlay
    * layer managers is permitted to write a z-index.
    */
-  --sh3-z-layer-0: 0;   /* docked layout (content area) */
-  --sh3-z-layer-1: 100; /* floating panels (deferred)   */
+  --sh3-z-layer-0: 0;   /* docked layout (content area)         */
+  --sh3-z-layer-drawers: 50; /* compact-mode drawer surfaces     */
+  --sh3-z-layer-1: 100; /* floating panels (deferred)           */
   --sh3-z-layer-2: 200; /* drag preview                 */
   --sh3-z-layer-3: 300; /* popups, context menus        */
   --sh3-z-layer-4: 400; /* modals                       */

package/dist/verbs/types.d.ts

@@ -128,11 +128,14 @@ export interface Sh3Api {
         scrollback: ScrollbackEntry[];
     }>;
     /**
-     * Read-only snapshot of every action registered across every shard. Pass
-     * { activeOnly: true } to filter to currently-dispatchable actions.
+     * Read-only snapshot of every action registered across every shard.
+     * - `activeOnly`: filter to currently-dispatchable actions.
+     * - `submenuOf`: restrict to children of the named parent action id
+     *   (mirrors the palette sub-drill filter).
      */
     listActions(opts?: {
         activeOnly?: boolean;
+        submenuOf?: string;
     }): ActionDescriptor[];
     /**
      * Programmatically dispatch a registered action by id. Same semantics as

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** Auto-generated from package.json — do not edit manually. */
-export declare const VERSION = "0.17.0";
+export declare const VERSION = "0.17.2";

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Auto-generated from package.json — do not edit manually. */
-export const VERSION = '0.17.0';
+export const VERSION = '0.17.2';

package/dist/viewport/classify.d.ts

@@ -0,0 +1,8 @@
+import type { ViewportClass } from './types';
+export interface ClassifyInput {
+    width: number;
+    coarsePointer: boolean;
+    noHover: boolean;
+    dpr: number;
+}
+export declare function classify(i: ClassifyInput): ViewportClass;

package/dist/viewport/classify.js

@@ -0,0 +1,20 @@
+/*
+ * classify — derives the viewport class from multi-signal input.
+ *
+ * Why multi-signal: a 6.7" phone reports ~393 CSS px wide *with* coarse
+ * pointer + high DPR; a narrow desktop window reports the same width
+ * *with* fine pointer + DPR 1-2. CSS pixels alone undercount physical
+ * compactness on high-DPI mobile, so width is one signal among three.
+ *
+ * The thresholds (720, 1100) are not load-bearing — they're tunable in
+ * a single place. Adjust with a corresponding test row.
+ */
+export function classify(i) {
+    if (i.coarsePointer && i.noHover)
+        return 'compact';
+    if (i.width < 720)
+        return 'compact';
+    if (i.coarsePointer && i.dpr >= 2 && i.width < 1100)
+        return 'compact';
+    return 'desktop';
+}

package/dist/viewport/classify.test.d.ts

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

package/dist/viewport/classify.test.js

@@ -0,0 +1,32 @@
+/*
+ * Table-driven tests for the viewport classifier. Each row is a real
+ * device (or a deliberately-chosen edge case) with the signal tuple
+ * expected from a real browser/matchMedia in that device's typical
+ * orientation.
+ */
+import { describe, it, expect } from 'vitest';
+import { classify } from './classify';
+const ROWS = [
+    { name: 'phone portrait', width: 393, coarsePointer: true, noHover: true, dpr: 3, expected: 'compact' },
+    { name: 'phone landscape', width: 852, coarsePointer: true, noHover: true, dpr: 3, expected: 'compact' },
+    { name: 'tablet portrait', width: 768, coarsePointer: true, noHover: true, dpr: 2, expected: 'compact' },
+    { name: 'tablet landscape', width: 1024, coarsePointer: true, noHover: true, dpr: 2, expected: 'compact' },
+    { name: 'desktop wide', width: 1920, coarsePointer: false, noHover: false, dpr: 1, expected: 'desktop' },
+    { name: 'desktop narrow window', width: 700, coarsePointer: false, noHover: false, dpr: 1, expected: 'compact' },
+    { name: 'iPad with mouse attached', width: 1024, coarsePointer: false, noHover: false, dpr: 2, expected: 'desktop' },
+    { name: 'small laptop', width: 1366, coarsePointer: false, noHover: false, dpr: 1, expected: 'desktop' },
+    { name: 'phone with stylus (hover ok)', width: 412, coarsePointer: true, noHover: false, dpr: 3, expected: 'compact' },
+];
+describe('classify', () => {
+    for (const row of ROWS) {
+        it(`${row.name} → ${row.expected}`, () => {
+            const result = classify({
+                width: row.width,
+                coarsePointer: row.coarsePointer,
+                noHover: row.noHover,
+                dpr: row.dpr,
+            });
+            expect(result).toBe(row.expected);
+        });
+    }
+});

package/dist/viewport/store.browser.test.d.ts

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

package/dist/viewport/store.browser.test.js

@@ -0,0 +1,33 @@
+/*
+ * Real-signal viewport classification — boots the viewport store under
+ * Chromium and asserts initial class + override behavior. happy-dom's
+ * matchMedia stub is shallow, so this is the contract pin against a
+ * real browser engine.
+ */
+import { describe, it, expect, beforeEach } from 'vitest';
+import { viewportStore } from './store.svelte';
+beforeEach(() => {
+    viewportStore.__reset();
+});
+describe('viewport store under real browser', () => {
+    it('returns a viewport class consistent with the test runner window', () => {
+        const info = viewportStore.current;
+        expect(info.class).toMatch(/desktop|compact/);
+        expect(info.width).toBeGreaterThan(0);
+        expect(info.height).toBeGreaterThan(0);
+    });
+    it('override(compact) immediately flips class', () => {
+        const fires = [];
+        const unsub = viewportStore.subscribe((i) => fires.push(i.class));
+        viewportStore.override('compact');
+        expect(viewportStore.current.class).toBe('compact');
+        expect(fires).toContain('compact');
+        unsub();
+    });
+    it('override(null) restores auto-derived class', () => {
+        viewportStore.override('compact');
+        expect(viewportStore.pinned).toBe('compact');
+        viewportStore.override(null);
+        expect(viewportStore.pinned).toBeNull();
+    });
+});

package/dist/viewport/store.svelte.d.ts

@@ -0,0 +1,9 @@
+import type { ViewportClass, ViewportInfo } from './types';
+export declare const viewportStore: {
+    readonly current: ViewportInfo;
+    subscribe(cb: (i: ViewportInfo) => void): () => void;
+    override(cls: ViewportClass | null): void;
+    readonly pinned: ViewportClass | null;
+    /** Test-only reset hook. Not exported from index.ts. */
+    __reset(): void;
+};