sh3-core 0.19.3 → 0.19.5

package/dist/layout/compact/rootStore.svelte.test.js

@@ -0,0 +1,54 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { compactRootStore, resolveCompactBodyRoot, __resetCompactRootStoreForTest, } from './rootStore.svelte';
+import { __resetLayoutStoreForTest, layoutStore, } from '../store.svelte';
+function makeFloat(id, viewId = 'v') {
+    return {
+        id,
+        content: { type: 'slot', slotId: `slot-${id}`, viewId },
+        position: { x: 0, y: 0 },
+        size: { w: 200, h: 200 },
+    };
+}
+describe('compactRootStore', () => {
+    beforeEach(() => {
+        __resetLayoutStoreForTest();
+        __resetCompactRootStoreForTest();
+    });
+    it('starts at { kind: "docked" }', () => {
+        expect(compactRootStore.current).toEqual({ kind: 'docked' });
+    });
+    it('setRoot accepts a float id present in the active tree', () => {
+        const f = makeFloat('f-1');
+        layoutStore.tree.floats.push(f);
+        compactRootStore.setRoot({ kind: 'float', floatId: 'f-1' });
+        expect(compactRootStore.current).toEqual({ kind: 'float', floatId: 'f-1' });
+    });
+    it('setRoot throws when the float id is not in the active tree', () => {
+        expect(() => compactRootStore.setRoot({ kind: 'float', floatId: 'missing' })).toThrow(/missing/);
+    });
+    it('reset returns to docked', () => {
+        layoutStore.tree.floats.push(makeFloat('f-2'));
+        compactRootStore.setRoot({ kind: 'float', floatId: 'f-2' });
+        compactRootStore.reset();
+        expect(compactRootStore.current).toEqual({ kind: 'docked' });
+    });
+    it('resolveCompactBodyRoot returns docked content when current is docked', () => {
+        expect(resolveCompactBodyRoot()).toEqual(layoutStore.tree.docked);
+    });
+    it('resolveCompactBodyRoot returns the float content when current points at it', () => {
+        const f = makeFloat('f-3');
+        layoutStore.tree.floats.push(f);
+        compactRootStore.setRoot({ kind: 'float', floatId: 'f-3' });
+        // Workspace-zone reactivity proxies the pushed object, so identity
+        // (`toBe`) does not hold; the structural content is what we care about.
+        expect(resolveCompactBodyRoot()).toEqual(f.content);
+    });
+    it('resolveCompactBodyRoot self-heals on stale id (returns docked + resets)', () => {
+        const f = makeFloat('f-4');
+        layoutStore.tree.floats.push(f);
+        compactRootStore.setRoot({ kind: 'float', floatId: 'f-4' });
+        layoutStore.tree.floats.length = 0;
+        expect(resolveCompactBodyRoot()).toEqual(layoutStore.tree.docked);
+        expect(compactRootStore.current).toEqual({ kind: 'docked' });
+    });
+});

package/dist/layout/floats.d.ts

@@ -23,6 +23,33 @@ export declare function cascadePosition(existing: FloatEntry[], bounds: {
 };
 /** Stable, process-unique float id. Not cryptographic — just unique within a session. */
 export declare function generateFloatId(): string;
+/**
+ * Pull a float's rect into the supplied viewport bounds. Used at bind
+ * time so a float persisted from a larger viewport doesn't render past
+ * the overlay root — Firefox in particular grows the parent's painted
+ * area to fit an off-screen abspos child, which visibly bleeds the
+ * docked grid (footer ends up below the viewport).
+ *
+ * Size is shrunk to fit but never below `minSize`; if `minSize` itself
+ * exceeds bounds, position is pinned to (0,0) and size stays at min.
+ * Position is then clamped so the frame fits within bounds.
+ */
+export declare function clampFloatToViewport(rect: {
+    position: {
+        x: number;
+        y: number;
+    };
+    size: Size;
+}, minSize: Size, bounds: {
+    w: number;
+    h: number;
+}): {
+    position: {
+        x: number;
+        y: number;
+    };
+    size: Size;
+};
 /**
  * True if a LayoutNode subtree contains no leaf slot with a bound viewId.
  * Used by the drag-commit auto-close invariant: when the last bound leaf

package/dist/layout/floats.js

@@ -55,6 +55,26 @@ export function generateFloatId() {
     floatIdCounter += 1;
     return `float-${Date.now().toString(36)}-${floatIdCounter.toString(36)}`;
 }
+/**
+ * Pull a float's rect into the supplied viewport bounds. Used at bind
+ * time so a float persisted from a larger viewport doesn't render past
+ * the overlay root — Firefox in particular grows the parent's painted
+ * area to fit an off-screen abspos child, which visibly bleeds the
+ * docked grid (footer ends up below the viewport).
+ *
+ * Size is shrunk to fit but never below `minSize`; if `minSize` itself
+ * exceeds bounds, position is pinned to (0,0) and size stays at min.
+ * Position is then clamped so the frame fits within bounds.
+ */
+export function clampFloatToViewport(rect, minSize, bounds) {
+    const w = Math.max(minSize.w, Math.min(rect.size.w, bounds.w));
+    const h = Math.max(minSize.h, Math.min(rect.size.h, bounds.h));
+    const maxX = Math.max(0, bounds.w - w);
+    const maxY = Math.max(0, bounds.h - h);
+    const x = Math.max(0, Math.min(rect.position.x, maxX));
+    const y = Math.max(0, Math.min(rect.position.y, maxY));
+    return { position: { x, y }, size: { w, h } };
+}
 /**
  * True if a LayoutNode subtree contains no leaf slot with a bound viewId.
  * Used by the drag-commit auto-close invariant: when the last bound leaf

package/dist/layout/floats.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { computeMinSize, cascadePosition, isEmptyContent } from './floats';
+import { computeMinSize, cascadePosition, isEmptyContent, clampFloatToViewport } from './floats';
 const slot = (slotId, viewId = 'v') => ({
     type: 'slot',
     slotId,
@@ -72,6 +72,39 @@ describe('cascadePosition', () => {
         expect(cascadePosition(existing, bounds)).toEqual({ x: 48, y: 48 });
     });
 });
+describe('clampFloatToViewport', () => {
+    const min = { w: 120, h: 80 };
+    const bounds = { w: 1024, h: 768 };
+    it('returns the rect unchanged when fully inside bounds', () => {
+        const out = clampFloatToViewport({ position: { x: 100, y: 200 }, size: { w: 600, h: 400 } }, min, bounds);
+        expect(out).toEqual({ position: { x: 100, y: 200 }, size: { w: 600, h: 400 } });
+    });
+    it('pulls a float that extends past the right edge back inside', () => {
+        const out = clampFloatToViewport({ position: { x: 900, y: 50 }, size: { w: 600, h: 400 } }, min, bounds);
+        expect(out.position.x).toBe(bounds.w - 600);
+        expect(out.position.y).toBe(50);
+        expect(out.size).toEqual({ w: 600, h: 400 });
+    });
+    it('pulls a float that extends past the bottom edge back inside', () => {
+        const out = clampFloatToViewport({ position: { x: 50, y: 600 }, size: { w: 600, h: 400 } }, min, bounds);
+        expect(out.position.y).toBe(bounds.h - 400);
+    });
+    it('clamps negative position back to (0,0)', () => {
+        const out = clampFloatToViewport({ position: { x: -200, y: -50 }, size: { w: 600, h: 400 } }, min, bounds);
+        expect(out.position).toEqual({ x: 0, y: 0 });
+    });
+    it('shrinks size larger than bounds down to bounds (above min)', () => {
+        const out = clampFloatToViewport({ position: { x: 0, y: 0 }, size: { w: 4000, h: 3000 } }, min, bounds);
+        expect(out.size).toEqual({ w: bounds.w, h: bounds.h });
+        expect(out.position).toEqual({ x: 0, y: 0 });
+    });
+    it('never shrinks size below the supplied min, even when bounds < min', () => {
+        const tiny = { w: 80, h: 60 };
+        const out = clampFloatToViewport({ position: { x: 999, y: 999 }, size: { w: 600, h: 400 } }, min, tiny);
+        expect(out.size).toEqual(min);
+        expect(out.position).toEqual({ x: 0, y: 0 });
+    });
+});
 describe('isEmptyContent', () => {
     it('true for a slot with null viewId', () => {
         expect(isEmptyContent({ type: 'slot', slotId: 's', viewId: null })).toBe(true);

package/dist/layout/inspection.js

@@ -16,6 +16,24 @@ import { activeLayout, getActiveRoot } from './store.svelte';
 import { nodeAtPath, findTabBySlotId, removeTabBySlotId, cleanupTree, splitNodeAtPath, locateSlotIn, } from './ops';
 import { getSlotHandle } from './slotHostPool.svelte';
 import { floatManager } from '../overlays/float';
+import { viewportStore } from '../viewport/store.svelte';
+import { compactRootStore } from './compact/rootStore.svelte';
+/**
+ * In compact mode the user sees one root at a time. When focus lands on
+ * a slot in a float, swap the compact body root to that float before
+ * returning. When focus lands in the docked tree, snap back to docked.
+ * Desktop is unaffected.
+ */
+function maybeSwapForCompact(located) {
+    if (viewportStore.current.class !== 'compact')
+        return;
+    if (located.kind === 'float') {
+        compactRootStore.setRoot({ kind: 'float', floatId: located.floatId });
+    }
+    else {
+        compactRootStore.reset();
+    }
+}
 /**
  * Read-only snapshot of the currently-rendered layout tree. The return
  * value is the live object — callers MUST NOT mutate it directly;
@@ -48,8 +66,10 @@ export function spliceIntoActiveLayout(entry) {
  */
 export function focusTab(slotId) {
     const tree = activeLayout();
-    if (focusTabWhere(tree.docked, (entry) => entry.slotId === slotId))
+    if (focusTabWhere(tree.docked, (entry) => entry.slotId === slotId)) {
+        maybeSwapForCompact({ kind: 'docked' });
         return true;
+    }
     return focusTabInFloats(tree, (entry) => entry.slotId === slotId);
 }
 /**
@@ -58,8 +78,10 @@ export function focusTab(slotId) {
  */
 export function focusView(viewId) {
     const tree = activeLayout();
-    if (focusTabWhere(tree.docked, (entry) => entry.viewId === viewId))
+    if (focusTabWhere(tree.docked, (entry) => entry.viewId === viewId)) {
+        maybeSwapForCompact({ kind: 'docked' });
         return true;
+    }
     return focusTabInFloats(tree, (entry) => entry.viewId === viewId);
 }
 /** Walk the tree looking for a tab entry that satisfies `pred`, activate it. */
@@ -85,6 +107,7 @@ function focusTabInFloats(tree, pred) {
     for (const floatEntry of tree.floats) {
         if (focusTabWhere(floatEntry.content, pred)) {
             floatManager.focus(floatEntry.id);
+            maybeSwapForCompact({ kind: 'float', floatId: floatEntry.id });
             return true;
         }
     }

package/dist/layout/inspection.svelte.test.js

@@ -112,3 +112,52 @@ describe('dockIntoActiveLayout — body-role preference', () => {
         expect(right.tabs.map((t) => t.viewId)).toEqual(['view:r']);
     });
 });
+// ---------------------------------------------------------------------------
+// Compact body-root swap on focusView / focusTab
+// ---------------------------------------------------------------------------
+import { compactRootStore, __resetCompactRootStoreForTest, } from './compact/rootStore.svelte';
+import { viewportStore } from '../viewport/store.svelte';
+import { focusView } from './inspection';
+import { floatManager, __resetFloatManagerForTest, bindFloatStore, } from '../overlays/float';
+describe('focusView — compact body-root swap', () => {
+    beforeEach(() => {
+        __resetLayoutStoreForTest();
+        __resetCompactRootStoreForTest();
+        __resetFloatManagerForTest();
+        viewportStore.override(null);
+        bindFloatStore(layoutStore.floats, () => ({ w: 1024, h: 768 }));
+    });
+    it('compact: focusView in a float swaps body root before activating', () => {
+        viewportStore.override('compact');
+        const id = floatManager.open('view:in-float', { title: 'In Float' });
+        // open() in compact already auto-switches; reset so we can see the swap.
+        compactRootStore.reset();
+        expect(compactRootStore.current).toEqual({ kind: 'docked' });
+        const ok = focusView('view:in-float');
+        expect(ok).toBe(true);
+        expect(compactRootStore.current).toEqual({ kind: 'float', floatId: id });
+        viewportStore.override(null);
+    });
+    it('compact: focusView for a docked tab resets body root', () => {
+        viewportStore.override('compact');
+        layoutStore.tree.docked = {
+            type: 'tabs',
+            tabs: [{ slotId: 's-d', viewId: 'view:docked', label: 'Docked' }],
+            activeTab: 0,
+        };
+        floatManager.open('view:other');
+        expect(compactRootStore.current.kind).toBe('float');
+        const ok = focusView('view:docked');
+        expect(ok).toBe(true);
+        expect(compactRootStore.current).toEqual({ kind: 'docked' });
+        viewportStore.override(null);
+    });
+    it('desktop: focusView does not touch the compact body root', () => {
+        viewportStore.override('desktop');
+        floatManager.open('view:any');
+        const before = compactRootStore.current;
+        focusView('view:any');
+        expect(compactRootStore.current).toEqual(before);
+        viewportStore.override(null);
+    });
+});

package/dist/overlays/FloatLayer.svelte

@@ -7,14 +7,25 @@
 -->
 <script lang="ts">
   import { layoutStore } from '../layout/store.svelte';
+  import { viewportStore } from '../viewport/store.svelte';
   import FloatFrame from './FloatFrame.svelte';
 
   const floats = $derived(layoutStore.floats);
+  // In compact mode, non-dismissable floats are body-or-menu only — the
+  // compact-floats-menu design demotes them to the FloatsSheet so the
+  // user sees one root at a time. Dismissable pickers (anchored
+  // popovers) keep floating because they're transient.
+  const compact = $derived(viewportStore.current.class === 'compact');
+  function shouldRender(entry: { dismissable?: boolean }): boolean {
+    return !compact || entry.dismissable === true;
+  }
 </script>
 
 <div class="sh3-float-layer">
   {#each floats as entry, i (entry.id)}
-    <FloatFrame bind:entry={floats[i]} />
+    {#if shouldRender(entry)}
+      <FloatFrame bind:entry={floats[i]} />
+    {/if}
   {/each}
 </div>
 

package/dist/overlays/float.d.ts

@@ -74,6 +74,13 @@ export interface FloatManager {
  * Bind the manager to the active LayoutTree's `floats` array. Called
  * from Sh3.svelte during boot. `getBounds` returns the current
  * tree-allocated area for cascade-position wraparound.
+ *
+ * Persisted floats observed for the first time are pulled into the
+ * supplied viewport — without this, a float whose position/size came
+ * from a larger window renders past the overlay root, which Firefox
+ * paints by growing the parent and visibly shifts the docked grid.
+ * Ids already in `clampedIds` (re-bound on viewport-class swap, etc.)
+ * are left alone.
  */
 export declare function bindFloatStore(floats: FloatEntry[], getBounds: () => {
     w: number;

package/dist/overlays/float.js

@@ -26,21 +26,58 @@
  *   in-memory fallback array is used — this is both the test environment
  *   and the pre-boot state.
  */
-import { computeMinSize, cascadePosition, generateFloatId } from '../layout/floats';
+import { computeMinSize, cascadePosition, generateFloatId, clampFloatToViewport, } from '../layout/floats';
 import { findEnclosingOverlayHost } from './parentHost';
+import { compactRootStore } from '../layout/compact/rootStore.svelte';
+import { viewportStore } from '../viewport/store.svelte';
 import { setMaximizedReactive, readMaximizedReactive, __resetMaximizedReactiveForTest, } from './floatMaximized.svelte';
 // ----- storage binding ---------------------------------------------------
 let fallbackFloats = [];
 let boundFloats = null;
 let getTreeBounds = () => ({ w: 1600, h: 900 });
+/**
+ * Float ids that have already been pulled into the viewport — either at
+ * open() time, or on the bind that first observed them as persisted.
+ * Subsequent binds (viewport-class swap, preset switch back-and-forth)
+ * skip these so a user-positioned float isn't snapped on every re-bind.
+ *
+ * Ids are time+counter unique per session, so this set never confuses a
+ * recycled id; it grows for the lifetime of the session.
+ */
+const clampedIds = new Set();
+function clampFloatRect(entry, bounds) {
+    const minSize = computeMinSize(entry.content);
+    const clamped = clampFloatToViewport({ position: entry.position, size: entry.size }, minSize, bounds);
+    entry.position.x = clamped.position.x;
+    entry.position.y = clamped.position.y;
+    entry.size.w = clamped.size.w;
+    entry.size.h = clamped.size.h;
+}
 /**
  * Bind the manager to the active LayoutTree's `floats` array. Called
  * from Sh3.svelte during boot. `getBounds` returns the current
  * tree-allocated area for cascade-position wraparound.
+ *
+ * Persisted floats observed for the first time are pulled into the
+ * supplied viewport — without this, a float whose position/size came
+ * from a larger window renders past the overlay root, which Firefox
+ * paints by growing the parent and visibly shifts the docked grid.
+ * Ids already in `clampedIds` (re-bound on viewport-class swap, etc.)
+ * are left alone.
  */
 export function bindFloatStore(floats, getBounds) {
     boundFloats = floats;
     getTreeBounds = getBounds;
+    const bounds = getBounds();
+    for (const entry of floats) {
+        if (clampedIds.has(entry.id))
+            continue;
+        clampFloatRect(entry, bounds);
+        clampedIds.add(entry.id);
+    }
+    // Active tree changed (app/preset switch) — drop any compact body
+    // selection so the user lands on the new docked tree.
+    compactRootStore.reset();
 }
 export function unbindFloatStore() {
     boundFloats = null;
@@ -53,6 +90,7 @@ export function __resetFloatManagerForTest() {
     getTreeBounds = () => ({ w: 1600, h: 900 });
     parentHosts.clear();
     maximizedRects.clear();
+    clampedIds.clear();
     __resetMaximizedReactiveForTest();
 }
 function activeStore() {
@@ -80,8 +118,16 @@ function mintFloatSlotId(viewId) {
 }
 // ----- API ---------------------------------------------------------------
 const DEFAULT_SIZE = { w: 600, h: 400 };
-function maxSize(a, b) {
-    return { w: Math.max(a.w, b.w), h: Math.max(a.h, b.h) };
+/**
+ * The default opening size: prefer DEFAULT_SIZE, but cap each axis at
+ * the current viewport so phones don't get a 600×400 float on a 360×800
+ * screen. Never shrunk below the content's computed minimum.
+ */
+function defaultOpenSize(min, bounds) {
+    return {
+        w: Math.max(min.w, Math.min(DEFAULT_SIZE.w, bounds.w)),
+        h: Math.max(min.h, Math.min(DEFAULT_SIZE.h, bounds.h)),
+    };
 }
 function openFloat(viewId, options = {}) {
     var _a, _b, _c;
@@ -118,8 +164,9 @@ function openFloat(viewId, options = {}) {
         };
     }
     const computedMin = computeMinSize(content);
-    const size = (_b = options.size) !== null && _b !== void 0 ? _b : maxSize(DEFAULT_SIZE, computedMin);
-    const position = (_c = options.position) !== null && _c !== void 0 ? _c : cascadePosition(store, getTreeBounds());
+    const bounds = getTreeBounds();
+    const size = (_b = options.size) !== null && _b !== void 0 ? _b : defaultOpenSize(computedMin, bounds);
+    const position = (_c = options.position) !== null && _c !== void 0 ? _c : cascadePosition(store, bounds);
     const entry = {
         id,
         content,
@@ -134,14 +181,26 @@ function openFloat(viewId, options = {}) {
         if (host)
             parentHosts.set(id, host);
     }
+    // Pull the chosen rect into the current viewport (handles user-supplied
+    // off-screen positions and oversized user-supplied sizes).
+    clampFloatRect(entry, bounds);
+    // Mark already-clamped so the next bind doesn't snap it again.
+    clampedIds.add(id);
     store.push(entry);
+    // Compact mode demotes non-dismissable floats from overlays to body-or-menu;
+    // a fresh open auto-switches the body to the new float so the user actually
+    // sees what they just opened. Pickers stay floating per the design.
+    if (viewportStore.current.class === 'compact' && !options.dismissable) {
+        compactRootStore.setRoot({ kind: 'float', floatId: id });
+    }
     return id;
 }
 function openFloatWithContent(options) {
     var _a;
     const store = activeStore();
     const id = generateFloatId();
-    const position = (_a = options.position) !== null && _a !== void 0 ? _a : cascadePosition(store, getTreeBounds());
+    const bounds = getTreeBounds();
+    const position = (_a = options.position) !== null && _a !== void 0 ? _a : cascadePosition(store, bounds);
     const entry = {
         id,
         content: options.content,
@@ -149,7 +208,12 @@ function openFloatWithContent(options) {
         size: options.size,
         title: options.title,
     };
+    clampFloatRect(entry, bounds);
+    clampedIds.add(id);
     store.push(entry);
+    if (viewportStore.current.class === 'compact') {
+        compactRootStore.setRoot({ kind: 'float', floatId: id });
+    }
     return id;
 }
 function closeFloat(floatId) {
@@ -160,6 +224,12 @@ function closeFloat(floatId) {
     store.splice(idx, 1);
     parentHosts.delete(floatId);
     maximizedRects.delete(floatId);
+    // If this float was the compact body, snap back to docked.
+    const cur = compactRootStore.current;
+    if (cur.kind === 'float' && cur.floatId === floatId) {
+        compactRootStore.reset();
+    }
+    clampedIds.delete(floatId);
     setMaximizedReactive(floatId, false);
 }
 function listFloats() {

package/dist/overlays/float.test.js

@@ -80,6 +80,176 @@ describe('floatManager', () => {
         expect(f.content.type).toBe('tabs');
     });
 });
+describe('bindFloatStore — clamp persisted floats to viewport', () => {
+    beforeEach(() => {
+        __resetFloatManagerForTest();
+    });
+    it('pulls an off-screen persisted float back into the bound viewport', () => {
+        // Persisted state from a previous, larger viewport: x is past the
+        // current right edge, y is past the current bottom.
+        const floats = [
+            {
+                id: 'persisted-1',
+                content: {
+                    type: 'tabs',
+                    tabs: [{ slotId: 'float:v:1', viewId: 'v', label: 'V' }],
+                    activeTab: 0,
+                },
+                position: { x: 2400, y: 1800 },
+                size: { w: 600, h: 400 },
+            },
+        ];
+        bindFloatStore(floats, () => ({ w: 1024, h: 768 }));
+        expect(floats[0].position.x).toBe(1024 - 600);
+        expect(floats[0].position.y).toBe(768 - 400);
+        expect(floats[0].size).toEqual({ w: 600, h: 400 });
+    });
+    it('shrinks an oversized persisted float to fit the bound viewport', () => {
+        const floats = [
+            {
+                id: 'persisted-2',
+                content: {
+                    type: 'tabs',
+                    tabs: [{ slotId: 'float:v:2', viewId: 'v', label: 'V' }],
+                    activeTab: 0,
+                },
+                position: { x: 0, y: 0 },
+                size: { w: 4000, h: 3000 },
+            },
+        ];
+        bindFloatStore(floats, () => ({ w: 1024, h: 768 }));
+        expect(floats[0].size).toEqual({ w: 1024, h: 768 });
+    });
+    it('leaves a float that already fits unchanged', () => {
+        const floats = [
+            {
+                id: 'persisted-3',
+                content: {
+                    type: 'tabs',
+                    tabs: [{ slotId: 'float:v:3', viewId: 'v', label: 'V' }],
+                    activeTab: 0,
+                },
+                position: { x: 100, y: 200 },
+                size: { w: 600, h: 400 },
+            },
+        ];
+        bindFloatStore(floats, () => ({ w: 1024, h: 768 }));
+        expect(floats[0].position).toEqual({ x: 100, y: 200 });
+        expect(floats[0].size).toEqual({ w: 600, h: 400 });
+    });
+    it('does not re-clamp a float on subsequent binds (e.g. viewport-class swap)', () => {
+        // Simulate a user-positioned float that's outside a smaller viewport.
+        // First bind clamps it; the user then moves it back to (700, 200);
+        // a second bind (compact ↔ desktop) must not snap it again.
+        const floats = [
+            {
+                id: 'persisted-4',
+                content: {
+                    type: 'tabs',
+                    tabs: [{ slotId: 'float:v:4', viewId: 'v', label: 'V' }],
+                    activeTab: 0,
+                },
+                position: { x: 2400, y: 0 },
+                size: { w: 600, h: 400 },
+            },
+        ];
+        bindFloatStore(floats, () => ({ w: 1024, h: 768 }));
+        // User drags it back to an out-of-bounds spot (allowed mid-session).
+        floats[0].position.x = 2400;
+        floats[0].position.y = 1800;
+        bindFloatStore(floats, () => ({ w: 1024, h: 768 }));
+        expect(floats[0].position).toEqual({ x: 2400, y: 1800 });
+    });
+});
+describe('floatManager.open — default size respects viewport', () => {
+    beforeEach(() => {
+        __resetFloatManagerForTest();
+    });
+    it('caps the default size at viewport bounds (phone-sized window)', () => {
+        bindFloatStore(layoutStore.floats, () => ({ w: 360, h: 740 }));
+        const id = floatManager.open('test:view', { title: 'Phone' });
+        const f = floatManager.list().find((e) => e.id === id);
+        expect(f.size.w).toBeLessThanOrEqual(360);
+        expect(f.size.h).toBeLessThanOrEqual(740);
+        // And the float is fully on-screen.
+        expect(f.position.x + f.size.w).toBeLessThanOrEqual(360);
+        expect(f.position.y + f.size.h).toBeLessThanOrEqual(740);
+    });
+    it('uses DEFAULT_SIZE when the viewport is large enough', () => {
+        bindFloatStore(layoutStore.floats, () => ({ w: 1280, h: 800 }));
+        const id = floatManager.open('test:view', { title: 'Desktop' });
+        const f = floatManager.list().find((e) => e.id === id);
+        expect(f.size).toEqual({ w: 600, h: 400 });
+    });
+    it('clamps a user-supplied oversized size to viewport on open', () => {
+        bindFloatStore(layoutStore.floats, () => ({ w: 360, h: 740 }));
+        const id = floatManager.open('test:view', {
+            title: 'Phone',
+            size: { w: 2000, h: 2000 },
+        });
+        const f = floatManager.list().find((e) => e.id === id);
+        expect(f.size).toEqual({ w: 360, h: 740 });
+    });
+});
+// ---------------------------------------------------------------------------
+// Compact body-root integration: floatManager auto-switches in compact mode,
+// resets on close-of-current and on bind.
+// ---------------------------------------------------------------------------
+import { compactRootStore, __resetCompactRootStoreForTest, } from '../layout/compact/rootStore.svelte';
+import { viewportStore } from '../viewport/store.svelte';
+describe('floatManager — compact body root integration', () => {
+    beforeEach(() => {
+        __resetFloatManagerForTest();
+        __resetCompactRootStoreForTest();
+        viewportStore.override(null);
+    });
+    afterEach(() => {
+        viewportStore.override(null);
+    });
+    it('open() in compact mode switches the body to the new (non-dismissable) float', () => {
+        bindFloatStore(layoutStore.floats, () => ({ w: 360, h: 740 }));
+        viewportStore.override('compact');
+        const id = floatManager.open('test:view', { title: 'Notes' });
+        expect(compactRootStore.current).toEqual({ kind: 'float', floatId: id });
+    });
+    it('open() in compact mode does NOT switch the body for dismissable pickers', () => {
+        bindFloatStore(layoutStore.floats, () => ({ w: 360, h: 740 }));
+        viewportStore.override('compact');
+        floatManager.open('picker:view', { dismissable: true });
+        expect(compactRootStore.current).toEqual({ kind: 'docked' });
+    });
+    it('open() on desktop does not touch the compact body root', () => {
+        bindFloatStore(layoutStore.floats, () => ({ w: 1280, h: 800 }));
+        viewportStore.override('desktop');
+        floatManager.open('test:view');
+        expect(compactRootStore.current).toEqual({ kind: 'docked' });
+    });
+    it('close(id) resets when the closed float is the current body', () => {
+        bindFloatStore(layoutStore.floats, () => ({ w: 360, h: 740 }));
+        viewportStore.override('compact');
+        const id = floatManager.open('test:view');
+        floatManager.close(id);
+        expect(compactRootStore.current).toEqual({ kind: 'docked' });
+    });
+    it('close(id) leaves the body root alone when closing a different float', () => {
+        bindFloatStore(layoutStore.floats, () => ({ w: 360, h: 740 }));
+        viewportStore.override('compact');
+        floatManager.open('view:a');
+        const b = floatManager.open('view:b');
+        expect(compactRootStore.current).toEqual({ kind: 'float', floatId: b });
+        floatManager.close(layoutStore.floats[0].id);
+        expect(compactRootStore.current).toEqual({ kind: 'float', floatId: b });
+    });
+    it('bindFloatStore resets the body root (covers app/preset switch)', () => {
+        bindFloatStore(layoutStore.floats, () => ({ w: 360, h: 740 }));
+        viewportStore.override('compact');
+        const id = floatManager.open('test:view');
+        expect(compactRootStore.current).toEqual({ kind: 'float', floatId: id });
+        // Re-bind (e.g. preset switch).
+        bindFloatStore([], () => ({ w: 360, h: 740 }));
+        expect(compactRootStore.current).toEqual({ kind: 'docked' });
+    });
+});
 describe('floatManager — anchor-aware parent host', () => {
     beforeEach(() => {
         __resetFloatManagerForTest();

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

@@ -0,0 +1,25 @@
+import type { DocumentMeta } from '../../documents/types';
+export type DocEntry = DocumentMeta & {
+    shardId: string;
+};
+export type OpenerValue = Pick<DocEntry, 'shardId' | 'path'> | null;
+export type SaverValue = string | null;
+export type FileItem = {
+    kind: 'folder';
+    name: string;
+    fullPath: string;
+} | {
+    kind: 'file';
+    name: string;
+    doc: DocEntry;
+};
+export declare function buildTree(docs: DocEntry[], shardId: string | null, prefix: string): FileItem[];
+export declare function formatSize(bytes: number): string;
+export declare function formatDate(epochMs: number): string;
+export declare function iconForFile(name: string): string;
+export declare function breadcrumbSegments(shardId: string | null, prefix: string): {
+    label: string;
+    level: number;
+    targetShard: string | null;
+    targetPrefix: string;
+}[];