sh3-core 0.7.3 → 0.8.0

package/dist/apps/lifecycle.test.js

@@ -0,0 +1,309 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+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 { presetManager } from '../overlays/presets';
+import { layoutStore } from '../layout/store.svelte';
+import LayoutRenderer from '../layout/LayoutRenderer.svelte';
+import { renderWithShell } from '../__test__/render';
+import { registerView } from '../shards/registry';
+import { tick } from 'svelte';
+// ---------------------------------------------------------------------------
+// Scenario A.1 — step order
+// ---------------------------------------------------------------------------
+describe('launchApp — scenario A.1 step order', () => {
+    beforeEach(resetFramework);
+    it('runs attachApp → activate shards → acquireAppSlotHolds → app.activate → switchToApp → onAppReady', async () => {
+        const order = [];
+        const shard = makeShard({
+            manifest: makeShardManifest({ id: 'shard-A' }),
+            activate: () => {
+                order.push('shard.activate');
+            },
+        });
+        registerShard(shard);
+        const app = makeApp({
+            manifest: makeAppManifest({
+                id: 'app-1',
+                requiredShards: ['shard-A'],
+            }),
+            activate: () => {
+                order.push('app.activate');
+            },
+            onAppReady: () => {
+                order.push('app.onAppReady');
+            },
+        });
+        registerApp(app);
+        await launchApp('app-1');
+        const iShard = order.indexOf('shard.activate');
+        const iApp = order.indexOf('app.activate');
+        const iReady = order.indexOf('app.onAppReady');
+        expect(iShard).toBeGreaterThanOrEqual(0);
+        expect(iApp).toBeGreaterThan(iShard);
+        expect(iReady).toBeGreaterThan(iApp);
+    });
+});
+// ---------------------------------------------------------------------------
+// Scenario A.2 — shard activate failure rolls back attach
+// ---------------------------------------------------------------------------
+describe('launchApp — scenario A.2 shard failure', () => {
+    beforeEach(resetFramework);
+    it('detaches the app and re-throws when a required shard throws during activate', async () => {
+        const badShard = makeShard({
+            manifest: makeShardManifest({ id: 'bad' }),
+            activate: () => {
+                throw new Error('boom');
+            },
+        });
+        registerShard(badShard);
+        const app = makeApp({
+            manifest: makeAppManifest({ id: 'app-2', requiredShards: ['bad'] }),
+        });
+        registerApp(app);
+        const { getAttachedAppId } = await import('../layout/store.svelte');
+        await expect(launchApp('app-2')).rejects.toThrow('boom');
+        expect(getAttachedAppId()).toBeNull();
+    });
+});
+// ---------------------------------------------------------------------------
+// Scenario A.3 — re-entry from home uses resume, skips shard re-activation
+// ---------------------------------------------------------------------------
+describe('launchApp — scenario A.3 re-entry from home', () => {
+    beforeEach(resetFramework);
+    it('fires resume and onAppReady on re-entry, does not re-activate shards', async () => {
+        const shardActivate = vi.fn();
+        const shard = makeShard({
+            manifest: makeShardManifest({ id: 'shard-R' }),
+            activate: shardActivate,
+        });
+        registerShard(shard);
+        const appResume = vi.fn();
+        const appReady = vi.fn();
+        const app = makeApp({
+            manifest: makeAppManifest({ id: 'app-3', requiredShards: ['shard-R'] }),
+            resume: appResume,
+            onAppReady: appReady,
+        });
+        registerApp(app);
+        await launchApp('app-3');
+        expect(shardActivate).toHaveBeenCalledTimes(1);
+        await returnToHome();
+        await launchApp('app-3');
+        expect(shardActivate).toHaveBeenCalledTimes(1);
+        expect(appResume).toHaveBeenCalledTimes(1);
+        expect(appReady).toHaveBeenCalledTimes(2);
+    });
+});
+// ---------------------------------------------------------------------------
+// Scenario A.4 — returnToHome then launch(same) fast path
+// ---------------------------------------------------------------------------
+describe('launchApp — scenario A.4 fast path', () => {
+    beforeEach(resetFramework);
+    it('does not call shard.deactivate or shard.activate when relaunching the same app from home', async () => {
+        const shardActivate = vi.fn();
+        const shardDeactivate = vi.fn();
+        registerShard(makeShard({
+            manifest: makeShardManifest({ id: 'shard-F' }),
+            activate: shardActivate,
+            deactivate: shardDeactivate,
+        }));
+        registerApp(makeApp({
+            manifest: makeAppManifest({ id: 'app-4', requiredShards: ['shard-F'] }),
+        }));
+        await launchApp('app-4');
+        await returnToHome();
+        await launchApp('app-4');
+        expect(shardActivate).toHaveBeenCalledTimes(1);
+        expect(shardDeactivate).not.toHaveBeenCalled();
+    });
+});
+// ---------------------------------------------------------------------------
+// Scenario A.5 — missing required shard fails fast
+// ---------------------------------------------------------------------------
+describe('launchApp — scenario A.5 missing shard', () => {
+    beforeEach(resetFramework);
+    it('throws before attachApp when a required shard is not registered', async () => {
+        registerApp(makeApp({
+            manifest: makeAppManifest({ id: 'app-5', requiredShards: ['missing'] }),
+        }));
+        const { getAttachedAppId } = await import('../layout/store.svelte');
+        await expect(launchApp('app-5')).rejects.toThrow(/missing/);
+        expect(getAttachedAppId()).toBeNull();
+    });
+});
+// ---------------------------------------------------------------------------
+// Scenario B.1 — presets.switch mutates synchronously
+// ---------------------------------------------------------------------------
+describe('presets — scenario B.1 sync mutation', () => {
+    beforeEach(resetFramework);
+    it('mutates the active-preset blob synchronously on switch', async () => {
+        const app = makeApp({
+            manifest: makeAppManifest({ id: 'presets-1' }),
+            initialLayout: [
+                { name: 'one', tree: makeTree(makeTabsNode([makeTabEntry({ slotId: 'a', label: 'A' })])) },
+                { name: 'two', tree: makeTree(makeTabsNode([makeTabEntry({ slotId: 'b', label: 'B' })])) },
+            ],
+        });
+        registerApp(app);
+        await launchApp('presets-1');
+        expect(presetManager.active()).toBe('one');
+        presetManager.switch('two');
+        expect(presetManager.active()).toBe('two');
+        expect(layoutStore.root).toMatchObject({ type: 'tabs' });
+    });
+});
+// ---------------------------------------------------------------------------
+// Scenario B.2 — shard.activate can call presets.switch
+// ---------------------------------------------------------------------------
+describe('presets — scenario B.2 switch from shard.activate', () => {
+    beforeEach(resetFramework);
+    it('does not throw "no app attached" when a shard calls presets.switch from activate', async () => {
+        registerShard(makeShard({
+            manifest: makeShardManifest({ id: 'switcher' }),
+            activate: () => {
+                presetManager.switch('alt');
+            },
+        }));
+        registerApp(makeApp({
+            manifest: makeAppManifest({ id: 'presets-2', requiredShards: ['switcher'] }),
+            initialLayout: [
+                { name: 'default', tree: makeTree(makeSlotNode('x')) },
+                { name: 'alt', tree: makeTree(makeSlotNode('y')) },
+            ],
+        }));
+        await expect(launchApp('presets-2')).resolves.not.toThrow();
+        expect(presetManager.active()).toBe('alt');
+    });
+});
+// ---------------------------------------------------------------------------
+// Scenario B.3 — unknown preset throws
+// ---------------------------------------------------------------------------
+describe('presets — scenario B.3 unknown name', () => {
+    beforeEach(resetFramework);
+    it('throws with a useful message when switching to an unknown preset', async () => {
+        registerApp(makeApp({
+            manifest: makeAppManifest({ id: 'presets-3' }),
+            initialLayout: [{ name: 'only', tree: makeTree(makeSlotNode('x')) }],
+        }));
+        await launchApp('presets-3');
+        expect(() => presetManager.switch('nope')).toThrow(/nope/);
+    });
+});
+// ---------------------------------------------------------------------------
+// Scenario B.4 — round-trip preserves customization
+// ---------------------------------------------------------------------------
+describe('presets — scenario B.4 round-trip preserves customization', () => {
+    beforeEach(resetFramework);
+    it('preserves per-preset sizes and activeTab across switch A → B → A', async () => {
+        var _a;
+        registerApp(makeApp({
+            manifest: makeAppManifest({ id: 'presets-4' }),
+            initialLayout: [
+                {
+                    name: 'A',
+                    tree: makeTree(makeTabsNode([
+                        makeTabEntry({ slotId: 't1', label: 'T1' }),
+                        makeTabEntry({ slotId: 't2', label: 'T2' }),
+                    ])),
+                },
+                { name: 'B', tree: makeTree(makeSlotNode('solo')) },
+            ],
+        }));
+        await launchApp('presets-4');
+        const rootA = layoutStore.root;
+        expect(rootA === null || rootA === void 0 ? void 0 : rootA.type).toBe('tabs');
+        if ((rootA === null || rootA === void 0 ? void 0 : rootA.type) === 'tabs')
+            rootA.activeTab = 1;
+        presetManager.switch('B');
+        expect((_a = layoutStore.root) === null || _a === void 0 ? void 0 : _a.type).toBe('slot');
+        presetManager.switch('A');
+        const back = layoutStore.root;
+        expect(back === null || back === void 0 ? void 0 : back.type).toBe('tabs');
+        if ((back === null || back === void 0 ? void 0 : back.type) === 'tabs')
+            expect(back.activeTab).toBe(1);
+    });
+});
+// ---------------------------------------------------------------------------
+// Scenario B.5 — post-launch switch re-renders (TDD + fix)
+// ---------------------------------------------------------------------------
+describe('presets — scenario B.5 post-launch switch re-renders', () => {
+    beforeEach(resetFramework);
+    it('updates the rendered DOM when presets.switch is called after launchApp', async () => {
+        registerView('test:slot-view', {
+            mount(container, ctx) {
+                const span = document.createElement('span');
+                span.dataset.viewFor = ctx.slotId;
+                span.textContent = ctx.slotId;
+                container.appendChild(span);
+                return { unmount: () => span.remove() };
+            },
+        });
+        registerApp(makeApp({
+            manifest: makeAppManifest({ id: 'presets-5' }),
+            initialLayout: [
+                { name: 'one', tree: makeTree(makeSlotNode('slot-one', 'test:slot-view')) },
+                { name: 'two', tree: makeTree(makeSlotNode('slot-two', 'test:slot-view')) },
+            ],
+        }));
+        await launchApp('presets-5');
+        const { container } = renderWithShell(LayoutRenderer, { path: [] });
+        await tick();
+        expect(container.querySelector('[data-view-for="slot-one"]')).toBeTruthy();
+        presetManager.switch('two');
+        await tick();
+        expect(container.querySelector('[data-view-for="slot-two"]')).toBeTruthy();
+        expect(container.querySelector('[data-view-for="slot-one"]')).toBeNull();
+    });
+});
+// ---------------------------------------------------------------------------
+// unregisterApp — android-style force-close + removal
+// ---------------------------------------------------------------------------
+describe('unregisterApp', () => {
+    beforeEach(resetFramework);
+    it('removes an inactive app from the registry', async () => {
+        const { registeredApps } = await import('./registry.svelte');
+        const app = makeApp({ manifest: makeAppManifest({ id: 'app-u1' }) });
+        registerApp(app);
+        expect(registeredApps.has('app-u1')).toBe(true);
+        unregisterApp('app-u1');
+        expect(registeredApps.has('app-u1')).toBe(false);
+    });
+    it('force-closes to home if the app being unregistered is active', async () => {
+        const { activeApp, registeredApps } = await import('./registry.svelte');
+        const shard = makeShard({ manifest: makeShardManifest({ id: 'shard-U' }) });
+        registerShard(shard);
+        const app = makeApp({
+            manifest: makeAppManifest({ id: 'app-u2', requiredShards: ['shard-U'] }),
+        });
+        registerApp(app);
+        await launchApp('app-u2');
+        expect(activeApp.id).toBe('app-u2');
+        unregisterApp('app-u2');
+        expect(activeApp.id).toBeNull();
+        expect(registeredApps.has('app-u2')).toBe(false);
+    });
+    it('is a no-op for unknown ids', async () => {
+        expect(() => unregisterApp('does-not-exist')).not.toThrow();
+    });
+});
+// ---------------------------------------------------------------------------
+// installPackage — evict-before-register (via registerLoadedBundle)
+// ---------------------------------------------------------------------------
+describe('installPackage evict-before-register (simulated via registerLoadedBundle)', () => {
+    beforeEach(resetFramework);
+    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 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');
+        deactivateShard('S');
+        const s2 = makeShard({ manifest: makeShardManifest({ id: 'S', version: '' }) });
+        registerLoadedBundle({ shards: [s2], apps: [] }, { version: '1.0.1', sourceRegistry: '', contractVersion: '1' });
+        expect((_b = registeredShards.get('S')) === null || _b === void 0 ? void 0 : _b.manifest.version).toBe('1.0.1');
+    });
+});

package/dist/apps/registry.svelte.d.ts

@@ -38,3 +38,5 @@ export declare function getActiveApp(): AppManifest | null;
  * activate hook. Not re-exported through `api.ts`.
  */
 export declare function getRegisteredApp(id: string): App | undefined;
+/** Test-only reset: clear registered apps and the active-app pointer. */
+export declare function __resetAppRegistryForTest(): void;

package/dist/apps/registry.svelte.js

@@ -57,3 +57,8 @@ export function getActiveApp() {
 export function getRegisteredApp(id) {
     return registeredApps.get(id);
 }
+/** Test-only reset: clear registered apps and the active-app pointer. */
+export function __resetAppRegistryForTest() {
+    registeredApps.clear();
+    activeApp.id = null;
+}

package/dist/apps/types.d.ts

@@ -39,8 +39,9 @@ export interface AppManifest {
     /**
      * Optional permissions this app requests beyond the default sandbox.
      * Declared in the manifest and surfaced to the user at install time
-     * by the store app. Currently recognized: `'state:manage'` — cross-
-     * shard zone access.
+     * by the store app. Currently recognized:
+     *   - 'state:manage' — cross-shard zone access.
+     *   - 'documents:sync' — cross-shard document sync API.
      */
     permissions?: string[];
 }
@@ -61,6 +62,10 @@ export interface AppContext {
      * Cross-shard zone management API. Only present when the app's
      * manifest declares the `'state:manage'` permission. Check with
      * `if (ctx.zones)` before use.
+     *
+     * Related permissions also recognized by the framework:
+     *   - 'documents:sync' — cross-shard document sync API (exposed on
+     *     shard contexts as `ctx.sync()`, not on app contexts).
      */
     zones?: ZoneManager;
 }
@@ -96,6 +101,23 @@ export interface App {
      * same `AppContext` that `activate` received.
      */
     resume?(ctx: AppContext): void | Promise<void>;
+    /**
+     * Called after the framework has switched the rendered root to this
+     * app's layout (i.e. `activeLayout()` now returns the app's active
+     * preset tree). Fires on both first launch (after `activate`) and
+     * on re-entry from home (after `resume`). This is the earliest hook
+     * from which layout-mutation APIs like `spliceIntoActiveLayout`,
+     * `focusTab`, `dockIntoActiveLayout` reliably target the app's tree.
+     *
+     * Use this for boot UX that needs to act on the rendered layout —
+     * e.g. reopening a last-used document, restoring tab state, or
+     * inserting a "welcome" tab into the current preset. Setup that
+     * does not touch the rendered layout (registering views, hydrating
+     * state, starting bus subscriptions) belongs in `activate`.
+     *
+     * See ADR-014.
+     */
+    onAppReady?(ctx: AppContext): void | Promise<void>;
 }
 /**
  * Source-declared shape of an app manifest — what external package authors

package/dist/createShell.d.ts

@@ -15,6 +15,8 @@ export interface ShellConfig {
         type: string;
         version: string;
         bundleUrl: string;
+        sourceRegistry?: string;
+        contractVersion?: string;
     }>;
     /** Mount target — CSS selector or element (defaults to '#app') */
     target?: string | HTMLElement;

package/dist/createShell.js

@@ -15,8 +15,10 @@ import { __setEnvServerUrl } from './env/index';
 import { __setTenantId } from './documents/config';
 import { initFromBoot } from './auth/index';
 import SignInWall from './auth/SignInWall.svelte';
+import { loadBundleModule } from './registry/loader';
+import { registerLoadedBundle } from './registry/register';
 export async function createShell(config) {
-    var _a, _b, _c;
+    var _a, _b, _c, _d, _e;
     const sUrl = (_a = config === null || config === void 0 ? void 0 : config.serverUrl) !== null && _a !== void 0 ? _a : '';
     // 1. Platform detection
     const platform = await resolvePlatform();
@@ -45,7 +47,7 @@ export async function createShell(config) {
                 bootConfig = await res.json();
             }
         }
-        catch (_d) {
+        catch (_f) {
             // Server unreachable — boot without auth (offline mode)
         }
     }
@@ -73,7 +75,6 @@ export async function createShell(config) {
     }
     // 5. Load server-discovered packages
     if ((_c = config === null || config === void 0 ? void 0 : config.discoveredPackages) === null || _c === void 0 ? void 0 : _c.length) {
-        const { loadBundleModule } = await import('./registry/loader');
         for (const pkg of config.discoveredPackages) {
             try {
                 const res = await fetch(pkg.bundleUrl);
@@ -83,10 +84,11 @@ export async function createShell(config) {
                 }
                 const bytes = await res.arrayBuffer();
                 const loaded = await loadBundleModule(bytes);
-                for (const s of loaded.shards)
-                    registerShard(s);
-                for (const a of loaded.apps)
-                    registerApp(a);
+                registerLoadedBundle(loaded, {
+                    version: pkg.version,
+                    sourceRegistry: (_d = pkg.sourceRegistry) !== null && _d !== void 0 ? _d : '',
+                    contractVersion: (_e = pkg.contractVersion) !== null && _e !== void 0 ? _e : '',
+                });
                 console.log(`[sh3] Loaded discovered package: ${pkg.id}`);
             }
             catch (err) {

package/dist/documents/handle.js

@@ -18,6 +18,8 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
 };
 var _AutosaveControllerImpl_instances, _AutosaveControllerImpl_handle, _AutosaveControllerImpl_path, _AutosaveControllerImpl_debounceMs, _AutosaveControllerImpl_pending, _AutosaveControllerImpl_timer, _AutosaveControllerImpl_dirty, _AutosaveControllerImpl_disposed, _AutosaveControllerImpl_scheduleFlush, _AutosaveControllerImpl_clearTimer;
 import { documentChanges } from './notifications';
+import { notifyJournal } from './journal-hook';
+import { hashContent } from './sync/hash';
 const DEFAULT_DEBOUNCE_MS = 1000;
 /**
  * Create a document handle scoped to a tenant, shard, and file filter.
@@ -53,10 +55,13 @@ export function createDocumentHandle(tenantId, shardId, backend, options) {
             const existed = await backend.exists(tenantId, shardId, path);
             await backend.write(tenantId, shardId, path, content);
             emitChange(existed ? 'update' : 'create', path);
+            const hash = await hashContent(content);
+            await notifyJournal({ shardId, path, op: 'upsert', hash });
         },
         async delete(path) {
             await backend.delete(tenantId, shardId, path);
             emitChange('delete', path);
+            await notifyJournal({ shardId, path, op: 'delete', hash: null });
         },
         async exists(path) {
             return backend.exists(tenantId, shardId, path);

package/dist/documents/index.d.ts

@@ -4,3 +4,4 @@ export { HttpDocumentBackend } from './http-backend';
 export { createDocumentHandle } from './handle';
 export { documentChanges } from './notifications';
 export { getTenantId, getDocumentBackend, __setTenantId, __setDocumentBackend, } from './config';
+export * from './sync';

package/dist/documents/index.js

@@ -6,3 +6,4 @@ export { HttpDocumentBackend } from './http-backend';
 export { createDocumentHandle } from './handle';
 export { documentChanges } from './notifications';
 export { getTenantId, getDocumentBackend, __setTenantId, __setDocumentBackend, } from './config';
+export * from './sync';

package/dist/documents/journal-hook.d.ts

@@ -0,0 +1,6 @@
+import type { JournalEntry } from './sync/types';
+type Appender = (entry: Omit<JournalEntry, 'seq' | 'ts'>) => Promise<void>;
+export declare function setJournalAppender(fn: Appender): void;
+export declare function clearJournalAppender(): void;
+export declare function notifyJournal(entry: Omit<JournalEntry, 'seq' | 'ts'>): Promise<void>;
+export {};

package/dist/documents/journal-hook.js

@@ -0,0 +1,16 @@
+/*
+ * Journal appender hook — lets the sync engine subscribe to regular
+ * shard writes/deletes without creating an import cycle between the
+ * document handle and the sync subsystem.
+ */
+let appender = null;
+export function setJournalAppender(fn) {
+    appender = fn;
+}
+export function clearJournalAppender() {
+    appender = null;
+}
+export async function notifyJournal(entry) {
+    if (appender)
+        await appender(entry);
+}

package/dist/documents/sync/activate-integration.test.d.ts

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

package/dist/documents/sync/activate-integration.test.js

@@ -0,0 +1,37 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { MemoryDocumentBackend } from '../backends';
+import { __setDocumentBackend, __setTenantId } from '../config';
+import { __resetShardRegistryForTest, registerShard, activateShard } from '../../shards/activate.svelte';
+import { __resetSyncBundlesForTest } from './singleton';
+import { PERMISSION_DOCUMENTS_SYNC } from './types';
+describe('ctx.sync() gating', () => {
+    beforeEach(() => {
+        __resetShardRegistryForTest();
+        __resetSyncBundlesForTest();
+        __setDocumentBackend(new MemoryDocumentBackend());
+        __setTenantId('tenant-a');
+    });
+    it('is undefined without documents:sync permission', async () => {
+        let captured;
+        const shard = {
+            manifest: { id: 's-none', version: '0', views: [] },
+            activate: async (ctx) => { captured = ctx; },
+        };
+        registerShard(shard);
+        await activateShard('s-none');
+        expect(captured.sync).toBeUndefined();
+    });
+    it('is a function when documents:sync is declared', async () => {
+        let captured;
+        const shard = {
+            manifest: { id: 's-sync', version: '0', views: [], permissions: [PERMISSION_DOCUMENTS_SYNC] },
+            activate: async (ctx) => { captured = ctx; },
+        };
+        registerShard(shard);
+        await activateShard('s-sync');
+        expect(typeof captured.sync).toBe('function');
+        const h = captured.sync();
+        expect(h.connectorId).toBe('s-sync');
+        expect(await h.grantedScopes()).toEqual([]);
+    });
+});

package/dist/documents/sync/components/DocumentSyncExplorer.svelte

@@ -0,0 +1,99 @@
+<script lang="ts">
+  import { onMount } from 'svelte';
+  import SyncGrantPicker from './SyncGrantPicker.svelte';
+  import { createSyncRegistry, type SyncRegistry } from '../registry';
+  import { getDocumentBackend, getTenantId } from '../../config';
+  import type { GrantRecord, SyncScope, ConflictResolution } from '../types';
+
+  interface Props {
+    /** Optional connector-specific filter; if omitted, shows everything. */
+    connectorId?: string;
+    /** Shard IDs whose conflict artifacts should be listed. */
+    conflictShardIds?: string[];
+    /** Pending grant request, if any — embeds the picker when set. */
+    pendingRequest?: { connectorId: string; scope: SyncScope };
+  }
+
+  let { connectorId, conflictShardIds = [], pendingRequest }: Props = $props();
+
+  let registry: SyncRegistry | null = $state(null);
+  let grants: GrantRecord[] = $state([]);
+  let conflicts: ConflictResolution[] = $state([]);
+
+  async function refresh() {
+    if (!registry) return;
+    grants = await registry.list(connectorId);
+    const all: ConflictResolution[] = [];
+    for (const shardId of conflictShardIds) {
+      all.push(...await registry.listConflicts(shardId));
+    }
+    conflicts = all;
+  }
+
+  onMount(async () => {
+    registry = createSyncRegistry(getDocumentBackend(), getTenantId());
+    await refresh();
+  });
+
+  async function revoke(record: GrantRecord) {
+    if (!registry) return;
+    await registry.revoke(record.connectorId, record.scope);
+    await refresh();
+  }
+
+  function describeScope(s: SyncScope): string {
+    if (s.kind === 'tenant') return 'entire tenant';
+    if (s.kind === 'shard') return `shard:${s.shardId}`;
+    return `shard:${s.shardId}/${s.prefix}`;
+  }
+</script>
+
+<section class="document-sync-explorer" part="container">
+  <h2 part="title">Document Sync</h2>
+
+  {#if pendingRequest}
+    <SyncGrantPicker
+      connectorId={pendingRequest.connectorId}
+      scope={pendingRequest.scope}
+      onGranted={refresh}
+    />
+  {/if}
+
+  <h3 part="subtitle">Granted scopes</h3>
+  {#if grants.length === 0}
+    <p part="empty">No scopes granted yet.</p>
+  {:else}
+    <ul part="grants">
+      {#each grants as g}
+        <li>
+          <span part="grant-connector">{g.connectorId}</span>
+          <span part="grant-scope">{describeScope(g.scope)}</span>
+          <button type="button" onclick={() => revoke(g)} part="revoke">Revoke</button>
+        </li>
+      {/each}
+    </ul>
+  {/if}
+
+  <h3 part="subtitle">Conflicts</h3>
+  {#if conflicts.length === 0}
+    <p part="empty">No active conflicts.</p>
+  {:else}
+    <ul part="conflicts">
+      {#each conflicts as c}
+        <li>
+          <code part="conflict-path">{c.shardId}:{c.path}</code>
+          <small part="conflict-artifact">{c.conflictArtifactPath}</small>
+        </li>
+      {/each}
+    </ul>
+  {/if}
+</section>
+
+<style>
+  .document-sync-explorer {
+    display: grid;
+    gap: 0.75rem;
+  }
+  ul { list-style: none; padding: 0; margin: 0; }
+  li { display: flex; gap: 0.5rem; align-items: center; }
+</style>

package/dist/documents/sync/components/DocumentSyncExplorer.svelte.d.ts

@@ -0,0 +1,15 @@
+import type { SyncScope } from '../types';
+interface Props {
+    /** Optional connector-specific filter; if omitted, shows everything. */
+    connectorId?: string;
+    /** Shard IDs whose conflict artifacts should be listed. */
+    conflictShardIds?: string[];
+    /** Pending grant request, if any — embeds the picker when set. */
+    pendingRequest?: {
+        connectorId: string;
+        scope: SyncScope;
+    };
+}
+declare const DocumentSyncExplorer: import("svelte").Component<Props, {}, "">;
+type DocumentSyncExplorer = ReturnType<typeof DocumentSyncExplorer>;
+export default DocumentSyncExplorer;