sh3-core 0.21.2 → 0.22.0

package/dist/__test__/reset.js

@@ -9,6 +9,7 @@ import { __resetLayoutStoreForTest } from '../layout/store.svelte';
 import { resetSlotHostPool } from '../layout/slotHostPool.svelte';
 import { __resetViewRegistryForTest } from '../shards/registry';
 import { __resetShardRegistryForTest } from '../shards/activate.svelte';
+import { __resetShardBindingsForTest } from '../shards/app-binding.svelte';
 import { __resetAppRegistryForTest } from '../apps/registry.svelte';
 import { __resetDispatcherStateForTest } from '../actions/state.svelte';
 import { __resetSelectionForTest } from '../actions/selection.svelte';
@@ -35,6 +36,7 @@ export function resetFramework() {
     resetSlotHostPool();
     __resetViewRegistryForTest();
     __resetShardRegistryForTest();
+    __resetShardBindingsForTest();
     __resetAppRegistryForTest();
     __resetDispatcherStateForTest();
     __resetSelectionForTest();

package/dist/apps/lifecycle.js

@@ -14,7 +14,8 @@
 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 { bindShardToApp, clearShardBinding } from '../shards/app-binding.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';
@@ -23,8 +24,10 @@ import { clearSelectionUnconditional } from '../actions/selection.svelte';
 import { loadUserBindings } from '../actions/bindings-store';
 import { toastManager } from '../overlays/toast';
 import { clearAppNavEntries } from '../navigation/back-stack';
-import { getActiveScopeId } from '../documents/config';
+import { getActiveScopeId, getDocumentBackend } from '../documents/config';
 import { sessionState } from '../projects/session-state.svelte';
+import { createDocumentHandle } from '../documents/handle';
+import { collectRestoredSlots } from '../layout/tree-walk';
 // ---------- last-active-app user zone ------------------------------------
 /**
  * Framework-reserved user-zone slot storing which app to boot into on
@@ -144,6 +147,11 @@ export async function launchApp(id, opts = {}) {
         for (const shardId of app.manifest.requiredShards) {
             await activateShard(shardId, { phase: 'launch' });
         }
+        for (const shardId of app.manifest.requiredShards) {
+            const shard = registeredShards.get(shardId);
+            if (!(shard === null || shard === void 0 ? void 0 : shard.autostart))
+                bindShardToApp(shardId, id);
+        }
     }
     catch (err) {
         detachApp();
@@ -156,6 +164,31 @@ export async function launchApp(id, opts = {}) {
         }
         throw err;
     }
+    // Notify shards that an app is activating so they can set up app-scoped resources.
+    const appActivateCtx = {
+        appId: id,
+        documents(options) {
+            return createDocumentHandle(getActiveScopeId(), id, getDocumentBackend(), Object.assign(Object.assign({ format: 'text' }, options), { appId: id }));
+        },
+    };
+    for (const shardId of app.manifest.requiredShards) {
+        const shard = registeredShards.get(shardId);
+        const shardCtx = getShardContext(shardId);
+        if ((shard === null || shard === void 0 ? void 0 : shard.onAppActivate) && shardCtx) {
+            await shard.onAppActivate(id, appActivateCtx);
+        }
+    }
+    // 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 shard = registeredShards.get(shardId);
+        if (shard === null || shard === void 0 ? void 0 : shard.onLayoutWillRestore) {
+            await shard.onLayoutWillRestore(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).
@@ -165,6 +198,12 @@ export async function launchApp(id, opts = {}) {
     setActiveApp(id, new Set((_g = app.manifest.requiredShards) !== null && _g !== void 0 ? _g : []));
     void loadUserBindings(id).then(setUserBindings);
     switchToApp();
+    for (const shardId of app.manifest.requiredShards) {
+        const shard = registeredShards.get(shardId);
+        if (shard === null || shard === void 0 ? void 0 : shard.onLayoutRestored) {
+            shard.onLayoutRestored(restoredSlots);
+        }
+    }
     void ((_h = app.onAppReady) === null || _h === void 0 ? void 0 : _h.call(app, getOrCreateAppContext(id)));
     if (!opts.skipLastApp)
         writeLastApp(id);
@@ -189,6 +228,13 @@ export function unloadApp(id, skipSwitchToHome = false) {
     if (!app)
         return;
     void ((_a = app.deactivate) === null || _a === void 0 ? void 0 : _a.call(app));
+    // Notify shards that the app is deactivating so they can tear down app-scoped resources.
+    for (const shardId of app.manifest.requiredShards) {
+        const shard = registeredShards.get(shardId);
+        if (shard === null || shard === void 0 ? void 0 : shard.onAppDeactivate) {
+            void shard.onAppDeactivate(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
@@ -207,6 +253,7 @@ export function unloadApp(id, skipSwitchToHome = false) {
         const shard = registeredShards.get(shardId);
         if (!shard)
             continue;
+        clearShardBinding(shardId);
         if (shard.autostart)
             continue; // self-starter stays running
         deactivateShard(shardId);

package/dist/apps/lifecycle.test.js

@@ -660,3 +660,237 @@ 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' }),
+            activate() { },
+            onAppActivate(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' }]);
+    });
+    it('provides a documents() factory on AppActivateContext that uses appId namespace', async () => {
+        const { MemoryDocumentBackend } = await import('../documents/backends');
+        const { __setDocumentBackend } = await import('../documents/config');
+        const backend = new MemoryDocumentBackend();
+        __setDocumentBackend(backend);
+        // Capture appCtx so we can test synchronously after launch
+        let capturedAppCtx = null;
+        const shard = makeShard({
+            manifest: makeShardManifest({ id: 'ns-shard2' }),
+            activate() { },
+            onAppActivate(_appId, appCtx) { capturedAppCtx = appCtx; },
+        });
+        registerShard(shard);
+        const app = makeApp({
+            manifest: makeAppManifest({ id: 'ns-app2', requiredShards: ['ns-shard2'] }),
+        });
+        registerApp(app);
+        await launchApp('ns-app2');
+        const handle = capturedAppCtx.documents({ format: 'text' });
+        await handle.write('probe.txt', 'hello');
+        // Written under appId namespace, not shardId (scope is 'local' by default)
+        const inAppNs = await backend.list('local', 'ns-app2');
+        const inShardNs = await backend.list('local', 'ns-shard2');
+        expect(inAppNs.some((k) => k.path === 'probe.txt')).toBe(true);
+        expect(inShardNs).toHaveLength(0);
+    });
+});
+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' }),
+            activate() { },
+            onAppDeactivate(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' }),
+            activate() { },
+            onLayoutWillRestore(slots) {
+                order.push('onLayoutWillRestore');
+                capturedSlots.push([...slots]);
+            },
+            onLayoutRestored(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' }),
+            activate() { },
+            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' }),
+            activate(ctx) { handleA = ctx.documents({ format: 'text' }); },
+        }));
+        registerShard(makeShard({
+            manifest: makeShardManifest({ id: 'shard-share-B' }),
+            activate(ctx) { handleB = ctx.documents({ format: 'text' }); },
+        }));
+        registerApp(makeApp({
+            manifest: makeAppManifest({
+                id: 'app-share',
+                requiredShards: ['shard-share-A', 'shard-share-B'],
+            }),
+        }));
+        await launchApp('app-share');
+        await handleA.write('shared.json', '{"from":"A"}');
+        expect(await handleB.read('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);
+    });
+});
+describe('launchApp — document auto-scope autostart exception', () => {
+    beforeEach(resetFramework);
+    it('keeps autostart shards on shard-scoped namespace even when required by an active app', async () => {
+        const { MemoryDocumentBackend } = await import('../documents/backends');
+        const { __setDocumentBackend } = await import('../documents/config');
+        const backend = new MemoryDocumentBackend();
+        __setDocumentBackend(backend);
+        let handle = null;
+        registerShard(makeShard({
+            manifest: makeShardManifest({ id: 'autostart-shard' }),
+            activate(ctx) { handle = ctx.documents({ format: 'text' }); },
+            autostart() { },
+        }));
+        registerApp(makeApp({
+            manifest: makeAppManifest({
+                id: 'app-with-autostart',
+                requiredShards: ['autostart-shard'],
+            }),
+        }));
+        await launchApp('app-with-autostart');
+        await handle.write('persistent.txt', 'lives in autostart-shard');
+        expect((await backend.list('local', 'autostart-shard')).map(d => d.path))
+            .toContain('persistent.txt');
+        expect(await backend.list('local', 'app-with-autostart')).toHaveLength(0);
+    });
+});
+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/app-binding.svelte');
+        registerShard(makeShard({
+            manifest: makeShardManifest({ id: 'binding-shard' }),
+            activate() { },
+        }));
+        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/documents/handle.d.ts

@@ -3,4 +3,4 @@ import type { DocumentBackend, DocumentHandle, DocumentHandleOptions } from './t
  * Create a document handle scoped to a tenant, shard, and file filter.
  * The framework calls this from `ShardContext.documents()`.
  */
-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, options: DocumentHandleOptions): DocumentHandle;

package/dist/documents/handle.js

@@ -23,9 +23,16 @@ const DEFAULT_DEBOUNCE_MS = 1000;
  * Create a document handle scoped to a tenant, shard, and file filter.
  * The framework calls this from `ShardContext.documents()`.
  */
-export function createDocumentHandle(tenantId, shardId, backend, options) {
+export function createDocumentHandle(tenantId, shardOrNamespace, backend, options) {
     const controllers = new Set();
     const unsubscribers = new Set();
+    const resolveBoundTenant = typeof tenantId === 'function' ? tenantId : () => tenantId;
+    const baseNamespace = typeof shardOrNamespace === 'function' ? shardOrNamespace : () => shardOrNamespace;
+    // `options.appId` is the explicit override — when set it wins over the lazy
+    // resolver (used by appCtx.documents and as a power-user escape hatch).
+    const resolveNamespace = options.appId
+        ? () => options.appId
+        : baseNamespace;
     function matchesExtensions(path) {
         if (!options.extensions || options.extensions.length === 0)
             return true;
@@ -33,21 +40,21 @@ export function createDocumentHandle(tenantId, shardId, backend, options) {
     }
     function resolveTenant(opts) {
         var _a;
-        return (_a = opts === null || opts === void 0 ? void 0 : opts.scope) !== null && _a !== void 0 ? _a : tenantId;
+        return (_a = opts === null || opts === void 0 ? void 0 : opts.scope) !== null && _a !== void 0 ? _a : resolveBoundTenant();
     }
     function emitChange(type, path, tid) {
-        documentChanges.emit({ type, path, tenantId: tid, shardId });
+        documentChanges.emit({ type, path, tenantId: tid, shardId: resolveNamespace() });
     }
     const handle = {
         async list(opts) {
             const tid = resolveTenant(opts);
-            const all = await backend.list(tid, shardId);
+            const all = await backend.list(tid, resolveNamespace());
             if (!options.extensions || options.extensions.length === 0)
                 return all;
             return all.filter((meta) => matchesExtensions(meta.path));
         },
         async read(path, opts) {
-            const content = await backend.read(resolveTenant(opts), shardId, path);
+            const content = await backend.read(resolveTenant(opts), resolveNamespace(), path);
             if (content === null)
                 return null;
             // Phase 1: text format only. Binary returns as-is from the backend
@@ -56,14 +63,16 @@ export function createDocumentHandle(tenantId, shardId, backend, options) {
         },
         async write(path, content, opts) {
             const tid = resolveTenant(opts);
-            const existed = await backend.exists(tid, shardId, path);
-            await backend.write(tid, shardId, path, content);
+            const ns = resolveNamespace();
+            const existed = await backend.exists(tid, ns, path);
+            await backend.write(tid, ns, path, content);
             emitChange(existed ? 'update' : 'create', path, tid);
         },
         async delete(path, opts) {
             const tid = resolveTenant(opts);
-            const existed = await backend.exists(tid, shardId, path);
-            await backend.delete(tid, shardId, path);
+            const ns = resolveNamespace();
+            const existed = await backend.exists(tid, ns, path);
+            await backend.delete(tid, ns, path);
             if (existed)
                 emitChange('delete', path, tid);
         },
@@ -77,19 +86,21 @@ export function createDocumentHandle(tenantId, shardId, backend, options) {
                 }
             }
             const tid = resolveTenant(opts);
-            await backend.rename(tid, shardId, oldPath, newPath);
+            const ns = resolveNamespace();
+            await backend.rename(tid, ns, oldPath, newPath);
             documentChanges.emit({
                 type: 'rename',
                 path: newPath,
                 oldPath,
                 tenantId: tid,
-                shardId,
+                shardId: ns,
             });
         },
         async mkdir(path, opts) {
             const tid = resolveTenant(opts);
-            await backend.mkdir(tid, shardId, path);
-            documentChanges.emit({ type: 'folder-create', path, tenantId: tid, shardId });
+            const ns = resolveNamespace();
+            await backend.mkdir(tid, ns, path);
+            documentChanges.emit({ type: 'folder-create', path, tenantId: tid, shardId: ns });
         },
         async rmdir(path, opts) {
             var _a;
@@ -103,8 +114,9 @@ export function createDocumentHandle(tenantId, shardId, backend, options) {
                 }
             }
             const tid = resolveTenant(opts);
-            await backend.rmdir(tid, shardId, path, { recursive });
-            documentChanges.emit({ type: 'folder-delete', path, tenantId: tid, shardId });
+            const ns = resolveNamespace();
+            await backend.rmdir(tid, ns, path, { recursive });
+            documentChanges.emit({ type: 'folder-delete', path, tenantId: tid, shardId: ns });
         },
         async renameFolder(oldPath, newPath, opts) {
             const folderPrefix = oldPath + '/';
@@ -114,25 +126,26 @@ export function createDocumentHandle(tenantId, shardId, backend, options) {
                 }
             }
             const tid = resolveTenant(opts);
-            await backend.renameFolder(tid, shardId, oldPath, newPath);
+            const ns = resolveNamespace();
+            await backend.renameFolder(tid, ns, oldPath, newPath);
             documentChanges.emit({
                 type: 'folder-rename',
                 path: newPath,
                 oldPath,
                 tenantId: tid,
-                shardId,
+                shardId: ns,
             });
         },
         async listFolders(prefix, opts) {
-            return backend.listFolders(resolveTenant(opts), shardId, prefix !== null && prefix !== void 0 ? prefix : '');
+            return backend.listFolders(resolveTenant(opts), resolveNamespace(), prefix !== null && prefix !== void 0 ? prefix : '');
         },
         async exists(path) {
-            return backend.exists(tenantId, shardId, path);
+            return backend.exists(resolveBoundTenant(), resolveNamespace(), path);
         },
         async status(path) {
             if (!backend.readMeta)
                 throw new Error('Backend does not support status()');
-            return backend.readMeta(tenantId, shardId, path);
+            return backend.readMeta(resolveBoundTenant(), resolveNamespace(), path);
         },
         async resolveConflict(path, choice) {
             if (!backend.resolve)
@@ -140,19 +153,19 @@ export function createDocumentHandle(tenantId, shardId, backend, options) {
             if (typeof choice !== 'string' && !(typeof choice === 'object' && 'origin' in choice)) {
                 throw new Error('choice must be a string or { origin } object');
             }
-            return backend.resolve(tenantId, shardId, path, choice);
+            return backend.resolve(resolveBoundTenant(), resolveNamespace(), path, choice);
         },
         async readBranch(path, origin) {
             if (!backend.readBranch)
                 throw new Error('Backend does not support readBranch()');
-            return backend.readBranch(tenantId, shardId, path, origin);
+            return backend.readBranch(resolveBoundTenant(), resolveNamespace(), path, origin);
         },
         watch(callback) {
             // Subscribe to global emitter, filtered to this handle's scope.
             const unsub = documentChanges.subscribe((change) => {
-                if (change.tenantId !== tenantId)
+                if (change.tenantId !== resolveBoundTenant())
                     return;
-                if (change.shardId !== shardId)
+                if (change.shardId !== resolveNamespace())
                     return;
                 if (!matchesExtensions(change.path))
                     return;

package/dist/documents/handle.test.js

@@ -251,3 +251,66 @@ describe('DocumentHandle folder ops', () => {
         ]);
     });
 });
+describe('createDocumentHandle — appId override', () => {
+    it('uses appId as the namespace root when provided', async () => {
+        const backend = new MemoryDocumentBackend();
+        const handle = createDocumentHandle('tenant-1', 'sh3-editor', backend, { format: 'text', appId: 'guml-ide' });
+        await handle.write('test.guml', 'content');
+        const keysAppId = await backend.list('tenant-1', 'guml-ide');
+        expect(keysAppId.some((k) => k.path === 'test.guml')).toBe(true);
+        const keysShardId = await backend.list('tenant-1', 'sh3-editor');
+        expect(keysShardId).toHaveLength(0);
+    });
+    it('falls back to shardId when appId is not provided', async () => {
+        const backend = new MemoryDocumentBackend();
+        const handle = createDocumentHandle('tenant-1', 'sh3-editor', backend, { format: 'text' });
+        await handle.write('test.guml', 'content');
+        const keys = await backend.list('tenant-1', 'sh3-editor');
+        expect(keys.some((k) => k.path === 'test.guml')).toBe(true);
+    });
+});
+describe('createDocumentHandle — lazy resolvers', () => {
+    it('resolves namespace per operation from a function', async () => {
+        const { MemoryDocumentBackend } = await import('./backends');
+        const backend = new MemoryDocumentBackend();
+        let ns = 'shard-A';
+        const handle = createDocumentHandle('local', () => ns, backend, { format: 'text' });
+        await handle.write('foo.txt', 'first');
+        expect((await backend.list('local', 'shard-A')).map(d => d.path)).toContain('foo.txt');
+        ns = 'app-X';
+        await handle.write('bar.txt', 'second');
+        expect((await backend.list('local', 'app-X')).map(d => d.path)).toContain('bar.txt');
+        expect((await backend.list('local', 'shard-A')).map(d => d.path)).not.toContain('bar.txt');
+    });
+    it('resolves tenant per operation from a function', async () => {
+        const { MemoryDocumentBackend } = await import('./backends');
+        const backend = new MemoryDocumentBackend();
+        let tenant = 'alice';
+        const handle = createDocumentHandle(() => tenant, () => 'shard-A', backend, { format: 'text' });
+        await handle.write('p.txt', 'a');
+        expect((await backend.list('alice', 'shard-A')).map(d => d.path)).toContain('p.txt');
+        tenant = 'bob';
+        await handle.write('q.txt', 'b');
+        expect((await backend.list('bob', 'shard-A')).map(d => d.path)).toContain('q.txt');
+    });
+    it('watchers resolve namespace at emit time, not subscribe time', async () => {
+        const { MemoryDocumentBackend } = await import('./backends');
+        const backend = new MemoryDocumentBackend();
+        let ns = 'shard-A';
+        const handle = createDocumentHandle('local', () => ns, backend, { format: 'text' });
+        const seen = [];
+        handle.watch((c) => seen.push(`${c.type}:${c.path}`));
+        await handle.write('a.txt', 'x');
+        ns = 'app-X';
+        await handle.write('b.txt', 'y');
+        expect(seen).toContain('create:a.txt');
+        expect(seen).toContain('create:b.txt');
+    });
+    it('still accepts string tenant + namespace for back-compat', async () => {
+        const { MemoryDocumentBackend } = await import('./backends');
+        const backend = new MemoryDocumentBackend();
+        const handle = createDocumentHandle('local', 'shard-A', backend, { format: 'text' });
+        await handle.write('foo.txt', 'hi');
+        expect((await backend.list('local', 'shard-A')).map(d => d.path)).toContain('foo.txt');
+    });
+});

package/dist/documents/types.d.ts

@@ -50,6 +50,12 @@ export interface DocumentHandleOptions {
     format: DocumentFormat;
     /** File extensions this handle operates on, e.g. ['.guml', '.md']. */
     extensions?: string[];
+    /**
+     * When set, this handle's namespace root becomes `{scope}/docs/{appId}/`
+     * instead of `{scope}/docs/{shardId}/`. Use in `onAppActivate` to get
+     * a handle scoped to the app's shared document namespace.
+     */
+    appId?: string;
 }
 /** Metadata about a stored document. */
 export interface DocumentMeta {

package/dist/layout/LayoutRenderer.svelte

@@ -227,7 +227,7 @@
         {#if entry}
           <div class="tab-slot-wrapper">
             <SlotContainer
-              node={{ type: 'slot', slotId: entry.slotId, viewId: entry.viewId }}
+              node={{ type: 'slot', slotId: entry.slotId, viewId: entry.viewId, props: entry.props }}
               label={entry.label}
               meta={entry.meta}
             />

package/dist/layout/SlotContainer.svelte

@@ -71,6 +71,7 @@
       node.viewId,
       label || node.viewId || currentSlotId,
       meta,
+      node.props,
     );
     wrapperEl.appendChild(host);