sh3-core 0.21.2 → 0.22.1

package/dist/apps/lifecycle.js

@@ -13,8 +13,9 @@
  */
 import { createStateZones } from '../state/zones.svelte';
 import { createGestureRegistry } from '../gestures';
-import { activateShard, deactivateShard, getShardContext, registeredShards, } from '../shards/activate.svelte';
-import { attachApp, acquireAppSlotHolds, detachApp, switchToApp, switchToHome, } from '../layout/store.svelte';
+import { registeredShards, } from '../shards/lifecycle.svelte';
+import { shardEntries, runAppActivate, runAppDeactivate, registerAllShards, erroredShards } from '../shards/lifecycle.svelte';
+import { attachApp, acquireAppSlotHolds, detachApp, switchToApp, switchToHome, getActiveAppTree, } from '../layout/store.svelte';
 import { activeApp, breadcrumbApp, getRegisteredApp, registeredApps } from './registry.svelte';
 import { createZoneManager } from '../state/manage';
 import { PERMISSION_STATE_MANAGE } from '../state/types';
@@ -25,6 +26,7 @@ import { toastManager } from '../overlays/toast';
 import { clearAppNavEntries } from '../navigation/back-stack';
 import { getActiveScopeId } from '../documents/config';
 import { sessionState } from '../projects/session-state.svelte';
+import { collectRestoredSlots } from '../layout/tree-walk';
 // ---------- last-active-app user zone ------------------------------------
 /**
  * Framework-reserved user-zone slot storing which app to boot into on
@@ -95,7 +97,7 @@ function getOrCreateAppContext(appId, scopeId, args) {
  * @throws If the app is not registered or a required shard is not registered.
  */
 export async function launchApp(id, opts = {}) {
-    var _a, _b, _c, _d, _e, _f, _g, _h;
+    var _a, _b, _c, _d, _e, _f, _g;
     const app = getRegisteredApp(id);
     if (!app) {
         throw new Error(`Cannot launch app "${id}": not registered`);
@@ -110,18 +112,17 @@ export async function launchApp(id, opts = {}) {
     else if (activeApp.id === id) {
         // Re-entering the same app from Home — fire resume hooks.
         for (const shardId of app.manifest.requiredShards) {
-            const shard = registeredShards.get(shardId);
-            const shardCtx = getShardContext(shardId);
-            if (shard && shardCtx)
-                void ((_a = shard.resume) === null || _a === void 0 ? void 0 : _a.call(shard, shardCtx));
+            const entry = shardEntries.get(shardId);
+            if ((entry === null || entry === void 0 ? void 0 : entry.shard.resume) && entry.ctx)
+                void entry.shard.resume(entry.ctx);
         }
-        void ((_b = app.resume) === null || _b === void 0 ? void 0 : _b.call(app, getOrCreateAppContext(id)));
+        void ((_a = app.resume) === null || _a === void 0 ? void 0 : _a.call(app, getOrCreateAppContext(id)));
         switchToApp();
-        void ((_c = app.onAppReady) === null || _c === void 0 ? void 0 : _c.call(app, getOrCreateAppContext(id)));
+        void ((_b = app.onAppReady) === null || _b === void 0 ? void 0 : _b.call(app, getOrCreateAppContext(id)));
         if (!opts.skipLastApp)
             writeLastApp(id);
         breadcrumbApp.id = id;
-        setActiveApp(id, new Set((_d = app.manifest.requiredShards) !== null && _d !== void 0 ? _d : []));
+        setActiveApp(id, new Set((_c = app.manifest.requiredShards) !== null && _c !== void 0 ? _c : []));
         void loadUserBindings(id).then(setUserBindings);
         return;
     }
@@ -141,14 +142,34 @@ export async function launchApp(id, opts = {}) {
     // detach to keep the preset manager state consistent.
     attachApp(app);
     try {
+        // v3: ensure every registered shard has been run through register().
+        // In production, host.bootstrap calls registerAllShards once at boot.
+        // In tests that skip bootstrap, this catch-up makes launchApp self-sufficient.
+        await registerAllShards();
+        // Surface register-time failures for required shards as a launch error
+        // (mirrors v2 activate failure semantics for missing factories / thrown register).
         for (const shardId of app.manifest.requiredShards) {
-            await activateShard(shardId, { phase: 'launch' });
+            const err = erroredShards.get(shardId);
+            if (err)
+                throw err.error;
+        }
+        // runAppActivate rotates the doc namespace binding AND fires
+        // onAppActivate. No per-shard activate() pass, no separate binding.
+        for (const shardId of app.manifest.requiredShards) {
+            await runAppActivate(shardId, id);
         }
     }
     catch (err) {
+        // Roll back any partial onAppActivate calls.
+        for (const shardId of app.manifest.requiredShards) {
+            try {
+                await runAppDeactivate(shardId, id);
+            }
+            catch ( /* swallow */_h) { /* swallow */ }
+        }
         detachApp();
         try {
-            toastManager.notify(`Couldn't launch "${(_e = app.manifest.label) !== null && _e !== void 0 ? _e : id}": ${err instanceof Error ? err.message : String(err)}`, { level: 'error', duration: 6000 });
+            toastManager.notify(`Couldn't launch "${(_d = app.manifest.label) !== null && _d !== void 0 ? _d : id}": ${err instanceof Error ? err.message : String(err)}`, { level: 'error', duration: 6000 });
         }
         catch (_j) {
             // Toast layer not mounted (e.g. early boot, tests without Sh3).
@@ -156,16 +177,33 @@ export async function launchApp(id, opts = {}) {
         }
         throw err;
     }
+    // Collect the layout's restored slots for the restore hooks.
+    const tree = getActiveAppTree();
+    const restoredSlots = tree ? collectRestoredSlots(tree) : [];
+    // Await onLayoutWillRestore so async slot-contribution registrations
+    // complete before acquireAppSlotHolds triggers view factory mount.
+    for (const shardId of app.manifest.requiredShards) {
+        const entry = shardEntries.get(shardId);
+        if ((entry === null || entry === void 0 ? void 0 : entry.shard.onLayoutWillRestore) && entry.ctx) {
+            await entry.shard.onLayoutWillRestore(entry.ctx, restoredSlots);
+        }
+    }
     // Shards have registered their view factories — safe to take the
     // refcount holds on the app's slots now (pool's factory lookup
     // happens in a microtask from this call).
     acquireAppSlotHolds();
-    void ((_f = app.activate) === null || _f === void 0 ? void 0 : _f.call(app, getOrCreateAppContext(id, undefined, opts.args)));
+    void ((_e = app.activate) === null || _e === void 0 ? void 0 : _e.call(app, getOrCreateAppContext(id, undefined, opts.args)));
     activeApp.id = id;
-    setActiveApp(id, new Set((_g = app.manifest.requiredShards) !== null && _g !== void 0 ? _g : []));
+    setActiveApp(id, new Set((_f = app.manifest.requiredShards) !== null && _f !== void 0 ? _f : []));
     void loadUserBindings(id).then(setUserBindings);
     switchToApp();
-    void ((_h = app.onAppReady) === null || _h === void 0 ? void 0 : _h.call(app, getOrCreateAppContext(id)));
+    for (const shardId of app.manifest.requiredShards) {
+        const entry = shardEntries.get(shardId);
+        if ((entry === null || entry === void 0 ? void 0 : entry.shard.onLayoutRestored) && entry.ctx) {
+            entry.shard.onLayoutRestored(entry.ctx, restoredSlots);
+        }
+    }
+    void ((_g = app.onAppReady) === null || _g === void 0 ? void 0 : _g.call(app, getOrCreateAppContext(id)));
     if (!opts.skipLastApp)
         writeLastApp(id);
     breadcrumbApp.id = id;
@@ -189,6 +227,12 @@ export function unloadApp(id, skipSwitchToHome = false) {
     if (!app)
         return;
     void ((_a = app.deactivate) === null || _a === void 0 ? void 0 : _a.call(app));
+    // v3: call runAppDeactivate for every required shard. The shard stays
+    // active (its register() output is intact); only its per-app bindings
+    // and per-app contribution registrations are torn down.
+    for (const shardId of app.manifest.requiredShards) {
+        void runAppDeactivate(shardId, id);
+    }
     // Detach layout (releases the refcount holds; pool cleanup runs on
     // the next microtask for any slots that no longer have a renderer).
     // Switch to home first so LayoutRenderer stops reading the app's
@@ -196,21 +240,6 @@ export function unloadApp(id, skipSwitchToHome = false) {
     if (!skipSwitchToHome)
         switchToHome();
     detachApp();
-    // Deactivate this app's required shards IF no other consumer needs
-    // them. Phase 8 has at most one app active at a time, so "no other
-    // consumer" reduces to "not self-starting AND not required by any
-    // other registered app that happens to already be active" — but we
-    // don't run multiple apps, so the only survivors are self-starters.
-    // The simple rule: deactivate a required shard unless it was
-    // self-starting (has an `autostart` field defined).
-    for (const shardId of app.manifest.requiredShards) {
-        const shard = registeredShards.get(shardId);
-        if (!shard)
-            continue;
-        if (shard.autostart)
-            continue; // self-starter stays running
-        deactivateShard(shardId);
-    }
     activeApp.id = null;
     setActiveApp(null, new Set());
     clearSelectionUnconditional();
@@ -257,9 +286,12 @@ export async function returnToHome() {
     const app = activeApp.id ? getRegisteredApp(activeApp.id) : null;
     if (app) {
         for (const shardId of app.manifest.requiredShards) {
-            const shard = registeredShards.get(shardId);
-            if ((shard === null || shard === void 0 ? void 0 : shard.suspend) && (await shard.suspend()) === false)
-                return false;
+            const entry = shardEntries.get(shardId);
+            if ((entry === null || entry === void 0 ? void 0 : entry.shard.suspend) && entry.ctx) {
+                const result = await entry.shard.suspend(entry.ctx);
+                if (result === false)
+                    return false;
+            }
         }
         if (app.suspend && (await app.suspend()) === false)
             return false;

package/dist/apps/lifecycle.test.js

@@ -3,7 +3,7 @@ import { resetFramework } from '../__test__/reset';
 import { makeApp, makeShard, makeAppManifest, makeShardManifest, makeTabsNode, makeTabEntry, makeSlotNode, makeTree, } from '../__test__/fixtures';
 import { launchApp, returnToHome, unregisterApp } from './lifecycle';
 import { registerApp } from './registry.svelte';
-import { registerShard } from '../shards/activate.svelte';
+import { registerShard } from '../shards/lifecycle.svelte';
 import { presetManager } from '../overlays/presets';
 import { layoutStore, resetActivePresetToDefault } from '../layout/store.svelte';
 import LayoutRenderer from '../layout/LayoutRenderer.svelte';
@@ -19,7 +19,7 @@ describe('launchApp — scenario A.1 step order', () => {
         const order = [];
         const shard = makeShard({
             manifest: makeShardManifest({ id: 'shard-A' }),
-            activate: () => {
+            register: () => {
                 order.push('shard.activate');
             },
         });
@@ -54,7 +54,7 @@ describe('launchApp — scenario A.2 shard failure', () => {
     it('detaches the app and re-throws when a required shard throws during activate', async () => {
         const badShard = makeShard({
             manifest: makeShardManifest({ id: 'bad' }),
-            activate: () => {
+            register: () => {
                 throw new Error('boom');
             },
         });
@@ -77,7 +77,7 @@ describe('launchApp — scenario A.3 re-entry from home', () => {
         const shardActivate = vi.fn();
         const shard = makeShard({
             manifest: makeShardManifest({ id: 'shard-R' }),
-            activate: shardActivate,
+            register: shardActivate,
         });
         registerShard(shard);
         const appResume = vi.fn();
@@ -107,7 +107,7 @@ describe('launchApp — scenario A.4 fast path', () => {
         const shardDeactivate = vi.fn();
         registerShard(makeShard({
             manifest: makeShardManifest({ id: 'shard-F' }),
-            activate: shardActivate,
+            register: shardActivate,
             deactivate: shardDeactivate,
         }));
         registerApp(makeApp({
@@ -163,7 +163,7 @@ describe('presets — scenario B.2 switch from shard.activate', () => {
     it('does not throw "no app attached" when a shard calls presets.switch from activate', async () => {
         registerShard(makeShard({
             manifest: makeShardManifest({ id: 'switcher' }),
-            activate: () => {
+            register: () => {
                 presetManager.switch('alt');
             },
         }));
@@ -297,7 +297,7 @@ describe('installPackage evict-before-register (simulated via registerLoadedBund
     it('replaces an existing shard entry when a new version is registered', async () => {
         var _a, _b;
         const { registerLoadedBundle } = await import('../registry/register');
-        const { deactivateShard, registeredShards } = await import('../shards/activate.svelte');
+        const { deactivateShard, registeredShards } = await import('../shards/lifecycle.svelte');
         const s1 = makeShard({ manifest: makeShardManifest({ id: 'S', version: '' }) });
         registerLoadedBundle({ shards: [s1], apps: [] }, { version: '1.0.0', sourceRegistry: '', contractVersion: '1' });
         expect((_a = registeredShards.get('S')) === null || _a === void 0 ? void 0 : _a.manifest.version).toBe('1.0.0');
@@ -434,7 +434,7 @@ describe('sh3coreShard — sh3.app.reset-layout registration', () => {
         // would — tests don't run bootstrap, so the shard's actions wouldn't
         // otherwise be present.
         const { sh3coreShard } = await import('../sh3core-shard/sh3coreShard.svelte');
-        const { activateShard } = await import('../shards/activate.svelte');
+        const { activateShard } = await import('../shards/lifecycle.svelte');
         const { addAutostartShard } = await import('../actions/state.svelte');
         registerShard(sh3coreShard);
         // Mirror what bootstrap() does: mark the framework shard as autostart so
@@ -457,7 +457,7 @@ describe('sh3coreShard — sh3.app.reset-layout registration', () => {
     });
     it('hides "app"-scope actions after returnToHome', async () => {
         const { sh3coreShard } = await import('../sh3core-shard/sh3coreShard.svelte');
-        const { activateShard } = await import('../shards/activate.svelte');
+        const { activateShard } = await import('../shards/lifecycle.svelte');
         const { addAutostartShard } = await import('../actions/state.svelte');
         registerShard(sh3coreShard);
         addAutostartShard(sh3coreShard.manifest.id);
@@ -529,7 +529,7 @@ describe('launchApp — error toast on shard failure', () => {
             .mockImplementation(() => ({ close: () => { } }));
         const badShard = makeShard({
             manifest: makeShardManifest({ id: 'bad-toast' }),
-            activate: () => {
+            register: () => {
                 throw new Error('shard "other" not registered');
             },
         });
@@ -660,3 +660,191 @@ describe('launchApp — ctx.args', () => {
         expect(receivedArgs).toEqual({});
     });
 });
+// ---------------------------------------------------------------------------
+// Scenario — onAppActivate / onAppDeactivate / layout hooks
+// ---------------------------------------------------------------------------
+describe('launchApp — onAppActivate hook', () => {
+    beforeEach(resetFramework);
+    it('calls onAppActivate on required shards after activation with correct appId', async () => {
+        const calls = [];
+        const shard = makeShard({
+            manifest: makeShardManifest({ id: 'activate-hook-shard' }),
+            register() { },
+            onAppActivate(_ctx, appId) { calls.push({ shardId: 'activate-hook-shard', appId }); },
+        });
+        registerShard(shard);
+        const app = makeApp({
+            manifest: makeAppManifest({ id: 'activate-hook-app', requiredShards: ['activate-hook-shard'] }),
+        });
+        registerApp(app);
+        await launchApp('activate-hook-app');
+        expect(calls).toEqual([{ shardId: 'activate-hook-shard', appId: 'activate-hook-app' }]);
+    });
+    // v3: AppActivateContext is gone. ctx.documents (the shard's pre-minted
+    // handle) auto-resolves to the active app's namespace because
+    // runAppActivate rotated the binding. See lifecycle.test.ts for v3 coverage.
+});
+describe('unloadApp — onAppDeactivate hook', () => {
+    beforeEach(resetFramework);
+    it('calls onAppDeactivate on required shards when the app is unloaded', async () => {
+        const deactivated = [];
+        const shard = makeShard({
+            manifest: makeShardManifest({ id: 'deact-shard' }),
+            register() { },
+            onAppDeactivate(_ctx, appId) { deactivated.push(appId); },
+        });
+        registerShard(shard);
+        const app = makeApp({
+            manifest: makeAppManifest({ id: 'deact-app', requiredShards: ['deact-shard'] }),
+        });
+        registerApp(app);
+        await launchApp('deact-app');
+        unregisterApp('deact-app');
+        expect(deactivated).toEqual(['deact-app']);
+    });
+});
+describe('launchApp — onLayoutWillRestore / onLayoutRestored hooks', () => {
+    beforeEach(resetFramework);
+    it('calls onLayoutWillRestore before slot acquisition and onLayoutRestored after switchToApp', async () => {
+        const order = [];
+        const capturedSlots = [];
+        const shard = makeShard({
+            manifest: makeShardManifest({ id: 'restore-shard' }),
+            register() { },
+            onLayoutWillRestore(_ctx, slots) {
+                order.push('onLayoutWillRestore');
+                capturedSlots.push([...slots]);
+            },
+            onLayoutRestored(_ctx, slots) {
+                order.push('onLayoutRestored');
+                capturedSlots.push([...slots]);
+            },
+        });
+        registerShard(shard);
+        const app = makeApp({
+            manifest: makeAppManifest({ id: 'restore-app', requiredShards: ['restore-shard'] }),
+            initialLayout: [
+                { name: 'default', tree: makeTree(makeSlotNode('r-slot', 'restore:view')) },
+            ],
+        });
+        registerApp(app);
+        await launchApp('restore-app');
+        await Promise.resolve();
+        expect(order).toEqual(['onLayoutWillRestore', 'onLayoutRestored']);
+        // Both calls receive the same slot list
+        expect(capturedSlots[0]).toEqual(capturedSlots[1]);
+        expect(capturedSlots[0]).toHaveLength(1);
+        expect(capturedSlots[0][0]).toMatchObject({ slotId: 'r-slot', viewId: 'restore:view' });
+    });
+    it('awaits onLayoutWillRestore before slot factories mount', async () => {
+        // This is the load-bearing assertion: a slow async hook must complete
+        // before any acquireAppSlotHosts triggers a view factory mount() call.
+        // If launchApp uses `void shard.onLayoutWillRestore(...)`, the Promise
+        // resolves AFTER the microtask that mounts views — failing this test.
+        const order = [];
+        let resolveHook = null;
+        const hookGate = new Promise((r) => { resolveHook = r; });
+        registerView('slow-restore:view', {
+            mount() {
+                order.push('mount');
+                return { unmount() { } };
+            },
+        });
+        const shard = makeShard({
+            manifest: makeShardManifest({ id: 'slow-restore-shard' }),
+            register() { },
+            async onLayoutWillRestore() {
+                order.push('onLayoutWillRestore:start');
+                await hookGate;
+                order.push('onLayoutWillRestore:end');
+            },
+        });
+        registerShard(shard);
+        const app = makeApp({
+            manifest: makeAppManifest({ id: 'slow-restore-app', requiredShards: ['slow-restore-shard'] }),
+            initialLayout: [
+                { name: 'default', tree: makeTree(makeSlotNode('sr-slot', 'slow-restore:view')) },
+            ],
+        });
+        registerApp(app);
+        const launching = launchApp('slow-restore-app');
+        // Let microtasks run so the hook has started (launchApp awaits shard
+        // activation and onAppActivate before reaching onLayoutWillRestore, so
+        // we need several drains to get past those).
+        for (let i = 0; i < 10; i++)
+            await Promise.resolve();
+        // At this point the hook is suspended on the gate; mount must NOT have run yet.
+        expect(order).toEqual(['onLayoutWillRestore:start']);
+        resolveHook();
+        await launching;
+        for (let i = 0; i < 5; i++)
+            await Promise.resolve();
+        // The hook completed before any view factory ran.
+        const hookEndIdx = order.indexOf('onLayoutWillRestore:end');
+        const mountIdx = order.indexOf('mount');
+        expect(hookEndIdx).toBeGreaterThanOrEqual(0);
+        expect(mountIdx).toBeGreaterThanOrEqual(0);
+        expect(hookEndIdx).toBeLessThan(mountIdx);
+    });
+});
+// ---------------------------------------------------------------------------
+// Scenario E — document auto-scope: two shards in same app share namespace
+// ---------------------------------------------------------------------------
+describe('launchApp — document auto-scope', () => {
+    beforeEach(resetFramework);
+    it('routes ctx.documents() from two non-autostart shards in the same app to the appId namespace', async () => {
+        const { MemoryDocumentBackend } = await import('../documents/backends');
+        const { __setDocumentBackend } = await import('../documents/config');
+        const backend = new MemoryDocumentBackend();
+        __setDocumentBackend(backend);
+        let handleA = null;
+        let handleB = null;
+        registerShard(makeShard({
+            manifest: makeShardManifest({ id: 'shard-share-A' }),
+            register(ctx) { handleA = ctx.documents; },
+        }));
+        registerShard(makeShard({
+            manifest: makeShardManifest({ id: 'shard-share-B' }),
+            register(ctx) { handleB = ctx.documents; },
+        }));
+        registerApp(makeApp({
+            manifest: makeAppManifest({
+                id: 'app-share',
+                requiredShards: ['shard-share-A', 'shard-share-B'],
+            }),
+        }));
+        await launchApp('app-share');
+        await handleA.writeText('shared.json', '{"from":"A"}');
+        expect(await handleB.readText('shared.json')).toBe('{"from":"A"}');
+        expect(await backend.list('local', 'app-share')).toHaveLength(1);
+        expect(await backend.list('local', 'shard-share-A')).toHaveLength(0);
+        expect(await backend.list('local', 'shard-share-B')).toHaveLength(0);
+    });
+});
+// v3: autostart is gone. Every shard's document handle rotates to the
+// active app's namespace via runAppActivate, no exceptions. See
+// lifecycle.test.ts for the v3 binding-rotation coverage.
+describe('unloadApp — clears document binding', () => {
+    beforeEach(resetFramework);
+    it('reverts a non-autostart shard back to shard-scope when the app is unloaded', async () => {
+        const { MemoryDocumentBackend } = await import('../documents/backends');
+        const { __setDocumentBackend } = await import('../documents/config');
+        const backend = new MemoryDocumentBackend();
+        __setDocumentBackend(backend);
+        const { getShardBinding } = await import('../shards/lifecycle.svelte');
+        registerShard(makeShard({
+            manifest: makeShardManifest({ id: 'binding-shard' }),
+            register() { },
+        }));
+        registerApp(makeApp({
+            manifest: makeAppManifest({
+                id: 'binding-app',
+                requiredShards: ['binding-shard'],
+            }),
+        }));
+        await launchApp('binding-app');
+        expect(getShardBinding('binding-shard')).toBe('binding-app');
+        unregisterApp('binding-app');
+        expect(getShardBinding('binding-shard')).toBeNull();
+    });
+});

package/dist/artifact.d.ts

@@ -31,4 +31,6 @@ export interface ArtifactManifest {
     }>;
     /** Shard ids this app requires to be installed on the server. Written by sh3Artifact for app/combo bundles. */
     requiredShards?: string[];
+    /** Shard ids that are bundled inside this combo artifact. Written by sh3Artifact for combo bundles. */
+    bundledShards?: string[];
 }

package/dist/build.js

@@ -362,7 +362,7 @@ export function sh3Artifact(options = {}) {
             if (!finalAuthor) {
                 throw new Error('[sh3-artifact] Missing "author". Add it to package.json or pass it via sh3Artifact({ manifest: { author } }).');
             }
-            const manifest = Object.assign(Object.assign(Object.assign(Object.assign({ id: id || 'unknown', type, label: label || id || 'unknown', version: artifactVersion, contractVersion: 1 }, (hasServer ? { server: 'server.js' } : {})), { description: finalDescription, author: finalAuthor }), ((type === 'app' || type === 'combo') ? { requiredShards } : {})), overrides);
+            const manifest = Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ id: id || 'unknown', type, label: label || id || 'unknown', version: artifactVersion, contractVersion: 1 }, (hasServer ? { server: 'server.js' } : {})), { description: finalDescription, author: finalAuthor }), ((type === 'app' || type === 'combo') ? { requiredShards } : {})), (type === 'combo' && bundledShardIds.size > 0 ? { bundledShards: [...bundledShardIds] } : {})), overrides);
             // Read the emitted JS files as bytes for the archive
             const clientBytes = readFileSync(join(outDir, 'client.js'));
             const serverBytes = hasServer ? readFileSync(join(outDir, 'server.js')) : undefined;

package/dist/conflicts/adapter-documents.js

@@ -19,8 +19,7 @@
 import { ConflictPermissionError, } from './api';
 import { resolvePrimitive } from './resolve-primitive';
 function ownShardHandle(ctx) {
-    // No extension filter — the adapter takes caller-supplied paths, any type.
-    const h = ctx.documents({ format: 'text' });
+    const h = ctx.documents;
     return {
         status: (p) => h.status(p),
         readBranch: (p, o) => h.readBranch(p, o),

package/dist/createShell.js

@@ -14,7 +14,7 @@ import { apiFetch } from './transport/apiFetch';
 import { hydrateTokenOverrides } from './theme';
 import { __setEnvServerUrl, getEnvServerUrl } from './env/index';
 import { __setActiveScope, __setScopeResolver } from './documents/config';
-import { __setScopeResolver as __setShardScopeResolver } from './shards/activate.svelte';
+import { __setScopeResolver as __setShardScopeResolver } from './shards/lifecycle.svelte';
 import { initFromBoot } from './auth/index';
 import SignInWall from './auth/SignInWall.svelte';
 import { loadBundleModule } from './registry/loader';

package/dist/documents/handle.d.ts

@@ -1,6 +1,11 @@
-import type { DocumentBackend, DocumentHandle, DocumentHandleOptions } from './types';
+import type { DocumentBackend, DocumentHandle } from './types';
 /**
- * Create a document handle scoped to a tenant, shard, and file filter.
- * The framework calls this from `ShardContext.documents()`.
+ * Create a document handle scoped to a tenant and namespace. The framework
+ * pre-mints one handle per shard at boot; the namespace resolves lazily on
+ * every operation via `getShardBinding(shardId) ?? shardId` so it follows
+ * the shard's currently-bound app without re-minting.
+ *
+ * Format moves from the handle to per-call (readText/writeText/readJson/
+ * writeJson/readBinary/writeBinary) — see ADR-027.
  */
-export declare function createDocumentHandle(tenantId: string, shardId: string, backend: DocumentBackend, options: DocumentHandleOptions): DocumentHandle;
+export declare function createDocumentHandle(tenantId: string | (() => string), shardOrNamespace: string | (() => string), backend: DocumentBackend): DocumentHandle;