sh3-core 0.22.0 → 0.22.2

package/dist/app-appearance/appearanceShard.svelte.js

@@ -49,7 +49,7 @@ export const appearanceShard = {
         version: VERSION,
         views: [],
     },
-    activate(ctx) {
+    register(ctx) {
         const zone = ctx.state({
             user: { overrides: {} },
         });
@@ -64,10 +64,6 @@ export const appearanceShard = {
         };
         ctx.actions.register(customize);
     },
-    autostart() {
-        // Self-start so the `app.customize` action is registered before the
-        // user right-clicks a home card. No imperative work required.
-    },
     deactivate() {
         __unbindZone();
     },

package/dist/apps/lifecycle.js

@@ -13,8 +13,8 @@
  */
 import { createStateZones } from '../state/zones.svelte';
 import { createGestureRegistry } from '../gestures';
-import { activateShard, deactivateShard, getShardContext, registeredShards, } from '../shards/activate.svelte';
-import { bindShardToApp, clearShardBinding } from '../shards/app-binding.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';
@@ -24,9 +24,8 @@ 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, getDocumentBackend } from '../documents/config';
+import { getActiveScopeId } 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 ------------------------------------
 /**
@@ -98,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`);
@@ -113,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;
     }
@@ -144,19 +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) {
-            const shard = registeredShards.get(shardId);
-            if (!(shard === null || shard === void 0 ? void 0 : shard.autostart))
-                bindShardToApp(shardId, id);
+            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).
@@ -164,47 +177,33 @@ 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);
+        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();
     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);
+        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 ((_h = app.onAppReady) === null || _h === void 0 ? void 0 : _h.call(app, getOrCreateAppContext(id)));
+    void ((_g = app.onAppReady) === null || _g === void 0 ? void 0 : _g.call(app, getOrCreateAppContext(id)));
     if (!opts.skipLastApp)
         writeLastApp(id);
     breadcrumbApp.id = id;
@@ -228,12 +227,11 @@ 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.
+    // 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) {
-        const shard = registeredShards.get(shardId);
-        if (shard === null || shard === void 0 ? void 0 : shard.onAppDeactivate) {
-            void shard.onAppDeactivate(id);
-        }
+        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).
@@ -242,22 +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;
-        clearShardBinding(shardId);
-        if (shard.autostart)
-            continue; // self-starter stays running
-        deactivateShard(shardId);
-    }
     activeApp.id = null;
     setActiveApp(null, new Set());
     clearSelectionUnconditional();
@@ -304,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');
             },
         });
@@ -669,8 +669,8 @@ describe('launchApp — onAppActivate hook', () => {
         const calls = [];
         const shard = makeShard({
             manifest: makeShardManifest({ id: 'activate-hook-shard' }),
-            activate() { },
-            onAppActivate(appId) { calls.push({ shardId: 'activate-hook-shard', appId }); },
+            register() { },
+            onAppActivate(_ctx, appId) { calls.push({ shardId: 'activate-hook-shard', appId }); },
         });
         registerShard(shard);
         const app = makeApp({
@@ -680,32 +680,9 @@ describe('launchApp — onAppActivate hook', () => {
         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);
-    });
+    // 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);
@@ -713,8 +690,8 @@ describe('unloadApp — onAppDeactivate hook', () => {
         const deactivated = [];
         const shard = makeShard({
             manifest: makeShardManifest({ id: 'deact-shard' }),
-            activate() { },
-            onAppDeactivate(appId) { deactivated.push(appId); },
+            register() { },
+            onAppDeactivate(_ctx, appId) { deactivated.push(appId); },
         });
         registerShard(shard);
         const app = makeApp({
@@ -733,12 +710,12 @@ describe('launchApp — onLayoutWillRestore / onLayoutRestored hooks', () => {
         const capturedSlots = [];
         const shard = makeShard({
             manifest: makeShardManifest({ id: 'restore-shard' }),
-            activate() { },
-            onLayoutWillRestore(slots) {
+            register() { },
+            onLayoutWillRestore(_ctx, slots) {
                 order.push('onLayoutWillRestore');
                 capturedSlots.push([...slots]);
             },
-            onLayoutRestored(slots) {
+            onLayoutRestored(_ctx, slots) {
                 order.push('onLayoutRestored');
                 capturedSlots.push([...slots]);
             },
@@ -775,7 +752,7 @@ describe('launchApp — onLayoutWillRestore / onLayoutRestored hooks', () => {
         });
         const shard = makeShard({
             manifest: makeShardManifest({ id: 'slow-restore-shard' }),
-            activate() { },
+            register() { },
             async onLayoutWillRestore() {
                 order.push('onLayoutWillRestore:start');
                 await hookGate;
@@ -824,11 +801,11 @@ describe('launchApp — document auto-scope', () => {
         let handleB = null;
         registerShard(makeShard({
             manifest: makeShardManifest({ id: 'shard-share-A' }),
-            activate(ctx) { handleA = ctx.documents({ format: 'text' }); },
+            register(ctx) { handleA = ctx.documents; },
         }));
         registerShard(makeShard({
             manifest: makeShardManifest({ id: 'shard-share-B' }),
-            activate(ctx) { handleB = ctx.documents({ format: 'text' }); },
+            register(ctx) { handleB = ctx.documents; },
         }));
         registerApp(makeApp({
             manifest: makeAppManifest({
@@ -837,39 +814,16 @@ describe('launchApp — document auto-scope', () => {
             }),
         }));
         await launchApp('app-share');
-        await handleA.write('shared.json', '{"from":"A"}');
-        expect(await handleB.read('shared.json')).toBe('{"from":"A"}');
+        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);
     });
 });
-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);
-    });
-});
+// 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 () => {
@@ -877,10 +831,10 @@ describe('unloadApp — clears document binding', () => {
         const { __setDocumentBackend } = await import('../documents/config');
         const backend = new MemoryDocumentBackend();
         __setDocumentBackend(backend);
-        const { getShardBinding } = await import('../shards/app-binding.svelte');
+        const { getShardBinding } = await import('../shards/lifecycle.svelte');
         registerShard(makeShard({
             manifest: makeShardManifest({ id: 'binding-shard' }),
-            activate() { },
+            register() { },
         }));
         registerApp(makeApp({
             manifest: makeAppManifest({

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 | (() => string), shardOrNamespace: string | (() => string), backend: DocumentBackend, options: DocumentHandleOptions): DocumentHandle;
+export declare function createDocumentHandle(tenantId: string | (() => string), shardOrNamespace: string | (() => string), backend: DocumentBackend): DocumentHandle;

package/dist/documents/handle.js

@@ -20,24 +20,19 @@ var _AutosaveControllerImpl_instances, _AutosaveControllerImpl_handle, _Autosave
 import { documentChanges } from './notifications';
 const DEFAULT_DEBOUNCE_MS = 1000;
 /**
- * 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 function createDocumentHandle(tenantId, shardOrNamespace, backend, options) {
+export function createDocumentHandle(tenantId, shardOrNamespace, backend) {
     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;
-        return options.extensions.some((ext) => path.endsWith(ext));
-    }
+    const resolveNamespace = typeof shardOrNamespace === 'function' ? shardOrNamespace : () => shardOrNamespace;
     function resolveTenant(opts) {
         var _a;
         return (_a = opts === null || opts === void 0 ? void 0 : opts.scope) !== null && _a !== void 0 ? _a : resolveBoundTenant();
@@ -48,26 +43,47 @@ export function createDocumentHandle(tenantId, shardOrNamespace, backend, option
     const handle = {
         async list(opts) {
             const tid = resolveTenant(opts);
-            const all = await backend.list(tid, resolveNamespace());
-            if (!options.extensions || options.extensions.length === 0)
-                return all;
-            return all.filter((meta) => matchesExtensions(meta.path));
+            return backend.list(tid, resolveNamespace());
         },
-        async read(path, opts) {
+        async readText(path, opts) {
             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
-            // but the handle types it as string for text-format handles.
-            return typeof content === 'string' ? content : new TextDecoder().decode(content);
+            if (typeof content === 'string')
+                return content;
+            return new TextDecoder().decode(content);
         },
-        async write(path, content, opts) {
+        async readBinary(path, opts) {
+            const content = await backend.read(resolveTenant(opts), resolveNamespace(), path);
+            if (content === null)
+                return null;
+            if (content instanceof ArrayBuffer)
+                return content;
+            return new TextEncoder().encode(content).buffer;
+        },
+        async readJson(path, opts) {
+            const text = await this.readText(path, opts);
+            if (text === null)
+                return null;
+            return JSON.parse(text);
+        },
+        async writeText(path, content, opts) {
             const tid = resolveTenant(opts);
             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 writeBinary(path, content, opts) {
+            const tid = resolveTenant(opts);
+            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 writeJson(path, data, opts) {
+            await this.writeText(path, JSON.stringify(data), opts);
+        },
         async delete(path, opts) {
             const tid = resolveTenant(opts);
             const ns = resolveNamespace();
@@ -77,9 +93,6 @@ export function createDocumentHandle(tenantId, shardOrNamespace, backend, option
                 emitChange('delete', path, tid);
         },
         async rename(oldPath, newPath, opts) {
-            if (!matchesExtensions(newPath)) {
-                throw new Error(`Cannot rename to ${newPath}: violates handle extensions filter`);
-            }
             for (const ctrl of controllers) {
                 if (ctrl.path === oldPath) {
                     throw new Error(`Cannot rename: active autosave on ${oldPath}; flush and dispose first`);
@@ -167,8 +180,6 @@ export function createDocumentHandle(tenantId, shardOrNamespace, backend, option
                     return;
                 if (change.shardId !== resolveNamespace())
                     return;
-                if (!matchesExtensions(change.path))
-                    return;
                 callback(change);
             });
             unsubscribers.add(unsub);
@@ -234,7 +245,7 @@ class AutosaveControllerImpl {
             const content = __classPrivateFieldGet(this, _AutosaveControllerImpl_pending, "f");
             __classPrivateFieldSet(this, _AutosaveControllerImpl_pending, null, "f");
             __classPrivateFieldSet(this, _AutosaveControllerImpl_dirty, false, "f");
-            await __classPrivateFieldGet(this, _AutosaveControllerImpl_handle, "f").write(__classPrivateFieldGet(this, _AutosaveControllerImpl_path, "f"), content);
+            await __classPrivateFieldGet(this, _AutosaveControllerImpl_handle, "f").writeText(__classPrivateFieldGet(this, _AutosaveControllerImpl_path, "f"), content);
         }
     }
     async dispose() {