sh3-core 0.16.0 → 0.17.0

package/dist/Sh3.svelte

@@ -15,11 +15,7 @@
   import './tokens.css';
   import './primitives/base.css';
   import LayoutRenderer from './layout/LayoutRenderer.svelte';
-  import DragPreview from './layout/DragPreview.svelte';
-  import FloatLayer from './overlays/FloatLayer.svelte';
-  import type { OverlayLayer } from './overlays/types';
-  import { registerLayerRoot, unregisterLayerRoot } from './overlays/roots';
-  import { bindFloatStore, unbindFloatStore } from './overlays/float';
+  import OverlayRoots from './overlays/OverlayRoots.svelte';
   import { returnToHome, isAdmin } from './api';
   import { getActiveRoot, layoutStore } from './layout/store.svelte';
   import { syncMountedViewIdsFromLayout } from './actions/state.svelte';
@@ -39,41 +35,6 @@
   // stays set) and only flips the layout store's activeRoot back to 'home'.
   const onHome = $derived(getActiveRoot() === 'home');
 
-  // Layer metadata — order matches the stack in docs/design/layout.md.
-  // Index 0 here is layer 1 (floating panels); layer 0 is the content area.
-  const overlayLayers: { layer: number; name: OverlayLayer }[] = [
-    { layer: 1, name: 'floating'     },
-    { layer: 2, name: 'drag-preview' },
-    { layer: 3, name: 'popup'        },
-    { layer: 4, name: 'modal'        },
-    { layer: 5, name: 'toast'        },
-    { layer: 6, name: 'command'      },
-  ];
-
-  // Populated by bind:this during render; registered with the overlay
-  // module via $effect after mount so layer managers (sh3.modal,
-  // sh3.popup, sh3.toast) can find their target DOM roots.
-  const overlayRoots: Partial<Record<OverlayLayer, HTMLDivElement>> = $state({});
-
-  $effect(() => {
-    for (const { name } of overlayLayers) {
-      const el = overlayRoots[name];
-      if (el) registerLayerRoot(name, el);
-    }
-    return () => {
-      for (const { name } of overlayLayers) unregisterLayerRoot(name);
-    };
-  });
-
-  $effect(() => {
-    const tree = layoutStore.tree;
-    bindFloatStore(tree.floats, () => ({
-      w: window.innerWidth,
-      h: window.innerHeight,
-    }));
-    return () => unbindFloatStore();
-  });
-
   // Keep the actions dispatcher's `mountedViewIds` set in sync with the
   // live layout tree, so `view:<viewId>` scope checks (context menu,
   // palette, keyboard) see currently-mounted views. Deep Svelte 5
@@ -144,28 +105,7 @@
     <!-- alpha tag moved to Sh3Home title row -->
   </footer>
 
-  <!--
-    Overlay roots. Each is absolutely positioned over the entire sh3 with
-    pointer-events: none by default; layer managers enable pointer events on
-    the specific surfaces they portal in.
-  -->
-  <div class="sh3-overlays" aria-hidden="true">
-    {#each overlayLayers as { layer, name } (layer)}
-      <div
-        class="sh3-overlay-root"
-        data-sh3-overlay={name}
-        data-sh3-layer={layer}
-        style="z-index: var(--sh3-z-layer-{layer});"
-        bind:this={overlayRoots[name]}
-      >
-        {#if name === 'floating'}
-          <FloatLayer />
-        {:else if name === 'drag-preview'}
-          <DragPreview />
-        {/if}
-      </div>
-    {/each}
-  </div>
+  <OverlayRoots />
 
   <!--
     Sh3-owned consent dialog for ctx.keys.mint().
@@ -217,17 +157,6 @@
     user-select: none;
   }
 
-  .sh3-overlays {
-    position: absolute;
-    inset: 0;
-    pointer-events: none;
-  }
-  .sh3-overlay-root {
-    position: absolute;
-    inset: 0;
-    pointer-events: none;
-  }
-
   .sh3-tabbar-home-button {
     display: flex;
     align-items: center;

package/dist/actions/ctx-actions.svelte.test.js

@@ -35,7 +35,7 @@ describe('ShardContext.listActions / runAction (integration)', () => {
         });
         await activateShard('producer');
         await activateShard('consumer');
-        const list = consumerCtx.listActions();
+        const list = consumerCtx.sh3.listActions();
         const ids = list.map((d) => d.id);
         expect(ids).toContain('producer.do');
         const desc = list.find((d) => d.id === 'producer.do');
@@ -62,7 +62,7 @@ describe('ShardContext.listActions / runAction (integration)', () => {
         });
         await activateShard('producer');
         await activateShard('consumer');
-        const snapshot = consumerCtx.listActions({ activeOnly: true });
+        const snapshot = consumerCtx.sh3.listActions({ activeOnly: true });
         const ids = snapshot.map((d) => d.id);
         expect(ids).toContain('home.go');
         expect(ids).not.toContain('app.go');
@@ -87,7 +87,7 @@ describe('ShardContext.listActions / runAction (integration)', () => {
         });
         await activateShard('producer');
         await activateShard('consumer');
-        await consumerCtx.runAction('producer.go');
+        await consumerCtx.sh3.runAction('producer.go');
         expect(invokedVia).toBe('programmatic');
     });
     it('runAction rejects when the target action is inactive', async () => {
@@ -106,6 +106,6 @@ describe('ShardContext.listActions / runAction (integration)', () => {
         });
         await activateShard('producer');
         await activateShard('consumer');
-        await expect(consumerCtx.runAction('gated.go')).rejects.toThrow(/not active/);
+        await expect(consumerCtx.sh3.runAction('gated.go')).rejects.toThrow(/not active/);
     });
 });

package/dist/api.d.ts

@@ -80,3 +80,5 @@ export { default as Select } from './primitives/widgets/Select.svelte';
 export type { SelectOption } from './primitives/widgets/Select';
 export { default as AppPicker } from './primitives/widgets/AppPicker.svelte';
 export { default as UserPicker } from './primitives/widgets/UserPicker.svelte';
+export type { FieldKind, FieldAddress, FieldView, ControllableFieldDescriptor, ImperativeFieldDescriptor, ElementRefFieldDescriptor, ReadonlyFieldDescriptor, FieldsApi, DecorationHandle, } from './fields/types';
+export { fieldAddressToString, fieldAddressFromString } from './fields/address';

package/dist/api.js

@@ -97,3 +97,4 @@ export { default as FilePicker } from './primitives/widgets/FilePicker.svelte';
 export { default as Select } from './primitives/widgets/Select.svelte';
 export { default as AppPicker } from './primitives/widgets/AppPicker.svelte';
 export { default as UserPicker } from './primitives/widgets/UserPicker.svelte';
+export { fieldAddressToString, fieldAddressFromString } from './fields/address';

package/dist/build.d.ts

@@ -36,7 +36,34 @@ export interface Sh3ArtifactOptions {
     serverEntry?: string;
     /** Override manifest fields not extractable from code (description, author, requires). */
     manifest?: Partial<Pick<ArtifactManifest, 'description' | 'author' | 'requires'>>;
+    /**
+     * Append a semver build-metadata suffix to the artifact `version` written
+     * into `manifest.json`. Per ADR-013 the package.json version remains the
+     * release-version source; this option layers an artifact-level counter on
+     * top so test iterations and hotfix variants of the same release can ship
+     * as distinct artifacts without bumping the release number.
+     *
+     *   - omit / undefined: artifact version equals package.json.version (default).
+     *   - 'auto': resolved from `git describe --tags --abbrev=0` →
+     *     `git rev-list --count <tag>..HEAD`. Suffix is omitted when the
+     *     count is 0 (canonical release) or when git is unavailable.
+     *   - string: literal suffix. Empty string is treated as no suffix.
+     *
+     * Example: package.json says "1.2.3", git is 4 commits past `v1.2.3` →
+     * manifest.json says `"version": "1.2.3+4"`.
+     */
+    buildSuffix?: 'auto' | string;
 }
+/**
+ * Compose a release version (`pkgVersion`) with an optional semver
+ * build-metadata suffix. Pure function — no I/O — for testability.
+ *
+ * Returns `pkgVersion` unchanged when `suffix` is empty/undefined.
+ * Throws when `pkgVersion` already carries build metadata or when the
+ * suffix is not a valid semver build-metadata identifier
+ * (dot-separated `[0-9A-Za-z-]+`).
+ */
+export declare function composeArtifactVersion(pkgVersion: string, suffix: string | undefined): string;
 /**
  * Vite plugin that produces a distributable artifact directory after build.
  *

package/dist/build.js

@@ -17,6 +17,7 @@
  *   });
  */
 import { readFileSync, writeFileSync, unlinkSync, readdirSync, copyFileSync, existsSync } from 'node:fs';
+import { execSync } from 'node:child_process';
 import { join } from 'node:path';
 /**
  * Vite plugin that inlines extracted CSS into the JS bundle.
@@ -83,6 +84,52 @@ export function sh3CssInline() {
         },
     };
 }
+/**
+ * Compose a release version (`pkgVersion`) with an optional semver
+ * build-metadata suffix. Pure function — no I/O — for testability.
+ *
+ * Returns `pkgVersion` unchanged when `suffix` is empty/undefined.
+ * Throws when `pkgVersion` already carries build metadata or when the
+ * suffix is not a valid semver build-metadata identifier
+ * (dot-separated `[0-9A-Za-z-]+`).
+ */
+export function composeArtifactVersion(pkgVersion, suffix) {
+    if (!suffix)
+        return pkgVersion;
+    if (pkgVersion.includes('+')) {
+        throw new Error(`[sh3-artifact] package.json version "${pkgVersion}" already contains semver build metadata; cannot append additional suffix "${suffix}".`);
+    }
+    if (!/^[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*$/.test(suffix)) {
+        throw new Error(`[sh3-artifact] buildSuffix "${suffix}" is not a valid semver build-metadata identifier (expected dot-separated [0-9A-Za-z-]+).`);
+    }
+    return `${pkgVersion}+${suffix}`;
+}
+/**
+ * Resolve the auto build suffix from git: count of commits between the
+ * latest reachable tag and HEAD. Returns '' if git is unavailable, no
+ * tags exist, or HEAD is exactly at the tag (canonical release).
+ */
+function resolveAutoBuildSuffix() {
+    try {
+        const lastTag = execSync('git describe --tags --abbrev=0', {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        if (!lastTag)
+            return '';
+        const count = execSync(`git rev-list --count ${lastTag}..HEAD`, {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        const n = parseInt(count, 10);
+        if (!Number.isFinite(n) || n <= 0)
+            return '';
+        return String(n);
+    }
+    catch (_a) {
+        return '';
+    }
+}
 /**
  * Vite plugin that produces a distributable artifact directory after build.
  *
@@ -224,6 +271,17 @@ export function sh3Artifact(options = {}) {
                 throw new Error('[sh3-artifact] Missing "version" in package.json. Per ADR-013 the package '
                     + 'version is read from package.json, not from the source manifest.');
             }
+            // --- Resolve build suffix and compose the artifact version ---
+            // Per ADR-013 amendment: package.json holds the release version;
+            // sh3Artifact may layer a build-metadata suffix on top.
+            let resolvedSuffix = '';
+            if (options.buildSuffix === 'auto') {
+                resolvedSuffix = resolveAutoBuildSuffix();
+            }
+            else if (typeof options.buildSuffix === 'string') {
+                resolvedSuffix = options.buildSuffix;
+            }
+            const artifactVersion = composeArtifactVersion(pkgVersion, resolvedSuffix);
             // --- Write manifest.json ---
             const overrides = (_c = options.manifest) !== null && _c !== void 0 ? _c : {};
             const finalDescription = (_d = overrides.description) !== null && _d !== void 0 ? _d : pkgDescription;
@@ -234,7 +292,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({ id: id || 'unknown', type, label: label || id || 'unknown', version: pkgVersion, contractVersion: 1, client: 'client.js' }, (hasServer ? { server: 'server.js' } : {})), { description: finalDescription, author: finalAuthor }), overrides);
+            const manifest = Object.assign(Object.assign(Object.assign({ id: id || 'unknown', type, label: label || id || 'unknown', version: artifactVersion, contractVersion: 1, client: 'client.js' }, (hasServer ? { server: 'server.js' } : {})), { description: finalDescription, author: finalAuthor }), overrides);
             writeFileSync(join(outDir, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n');
             // --- Log summary ---
             const files = ['manifest.json', 'client.js'];

package/dist/build.test.d.ts

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

package/dist/build.test.js

@@ -0,0 +1,31 @@
+import { describe, it, expect } from 'vitest';
+import { composeArtifactVersion } from './build';
+describe('composeArtifactVersion', () => {
+    it('returns pkgVersion unchanged when suffix is undefined', () => {
+        expect(composeArtifactVersion('1.2.3', undefined)).toBe('1.2.3');
+    });
+    it('returns pkgVersion unchanged when suffix is empty string', () => {
+        expect(composeArtifactVersion('1.2.3', '')).toBe('1.2.3');
+    });
+    it('appends a numeric suffix as build metadata', () => {
+        expect(composeArtifactVersion('1.2.3', '42')).toBe('1.2.3+42');
+    });
+    it('appends dotted alphanumeric suffix as build metadata', () => {
+        expect(composeArtifactVersion('1.2.3', 'build.42')).toBe('1.2.3+build.42');
+    });
+    it('composes onto a prerelease version (semver allows -pre+meta)', () => {
+        expect(composeArtifactVersion('1.2.3-rc.1', '7')).toBe('1.2.3-rc.1+7');
+    });
+    it('throws when pkgVersion already has build metadata', () => {
+        expect(() => composeArtifactVersion('1.2.3+local', '42')).toThrow(/already contains semver build metadata/);
+    });
+    it('throws when suffix contains an invalid character', () => {
+        expect(() => composeArtifactVersion('1.2.3', 'build_42')).toThrow(/not a valid semver build-metadata identifier/);
+    });
+    it('throws when suffix has empty dot-separated identifier', () => {
+        expect(() => composeArtifactVersion('1.2.3', 'build..42')).toThrow(/not a valid semver build-metadata identifier/);
+    });
+    it('throws when suffix starts with a plus', () => {
+        expect(() => composeArtifactVersion('1.2.3', '+42')).toThrow(/not a valid semver build-metadata identifier/);
+    });
+});

package/dist/contributions/index.d.ts

@@ -1,2 +1,2 @@
 export type { ContributionsApi } from './types';
-export { register, list, listPoints, onChange, onAnyChange, __resetContributionsForTest } from './registry';
+export { register, list, listPoints, onChange, onAnyChange, __disposeSlotContributions, __resetContributionsForTest, } from './registry';

package/dist/contributions/index.js

@@ -5,4 +5,4 @@
  * file is internal-only, re-exporting the registry for activate.svelte.ts
  * and for tests.
  */
-export { register, list, listPoints, onChange, onAnyChange, __resetContributionsForTest } from './registry';
+export { register, list, listPoints, onChange, onAnyChange, __disposeSlotContributions, __resetContributionsForTest, } from './registry';

package/dist/contributions/registry.d.ts

@@ -1,8 +1,18 @@
 /**
  * Register a descriptor under the given point. Returns an unregister
  * function; calling it more than once is a safe no-op.
+ *
+ * Pass `opts.scope.slotId` to tie cleanup to a slot's lifecycle:
+ * `__disposeSlotContributions(slotId)` will fire the disposer on slot
+ * unmount. The disposer is idempotent — manual dispose detaches it from
+ * the slot bag, so a later slot-cleanup pass becomes a no-op for that
+ * entry.
  */
-export declare function register<T = unknown>(pointId: string, descriptor: T): () => void;
+export declare function register<T = unknown>(pointId: string, descriptor: T, opts?: {
+    scope?: {
+        slotId?: string;
+    };
+}): () => void;
 /** Enumerate descriptors at the named point in registration order. */
 export declare function list<T = unknown>(pointId: string): T[];
 /** Enumerate every point id with at least one registration. */
@@ -21,6 +31,12 @@ export declare function onChange(pointId: string, cb: () => void): () => void;
  * safe no-op. Symmetric with `onChange`, but global.
  */
 export declare function onAnyChange(cb: (pointId: string) => void): () => void;
+/**
+ * Drain every disposer registered with `scope.slotId === slotId`. Safe
+ * to call on unknown slot ids. Used by the layout module on slot unmount
+ * to release contributions tied to that slot's lifetime.
+ */
+export declare function __disposeSlotContributions(slotId: string): void;
 /**
  * Test-only reset. Not exported from the barrel; tests import it
  * directly from this module.

package/dist/contributions/registry.js

@@ -13,6 +13,7 @@
 const points = new Map();
 const listeners = new Map();
 const anyListeners = new Set();
+const slotCleanup = new Map();
 function emit(pointId) {
     const set = listeners.get(pointId);
     if (set) {
@@ -22,11 +23,34 @@ function emit(pointId) {
     for (const cb of anyListeners)
         cb(pointId);
 }
+function attachToSlot(slotId, dispose) {
+    let bag = slotCleanup.get(slotId);
+    if (!bag) {
+        bag = new Set();
+        slotCleanup.set(slotId, bag);
+    }
+    bag.add(dispose);
+}
+function detachFromSlot(slotId, dispose) {
+    const bag = slotCleanup.get(slotId);
+    if (!bag)
+        return;
+    bag.delete(dispose);
+    if (bag.size === 0)
+        slotCleanup.delete(slotId);
+}
 /**
  * Register a descriptor under the given point. Returns an unregister
  * function; calling it more than once is a safe no-op.
+ *
+ * Pass `opts.scope.slotId` to tie cleanup to a slot's lifecycle:
+ * `__disposeSlotContributions(slotId)` will fire the disposer on slot
+ * unmount. The disposer is idempotent — manual dispose detaches it from
+ * the slot bag, so a later slot-cleanup pass becomes a no-op for that
+ * entry.
  */
-export function register(pointId, descriptor) {
+export function register(pointId, descriptor, opts) {
+    var _a;
     const handle = Symbol();
     let map = points.get(pointId);
     if (!map) {
@@ -35,11 +59,14 @@ export function register(pointId, descriptor) {
     }
     map.set(handle, descriptor);
     emit(pointId);
+    const slotId = (_a = opts === null || opts === void 0 ? void 0 : opts.scope) === null || _a === void 0 ? void 0 : _a.slotId;
     let disposed = false;
-    return () => {
+    const dispose = () => {
         if (disposed)
             return;
         disposed = true;
+        if (slotId)
+            detachFromSlot(slotId, dispose);
         const m = points.get(pointId);
         if (!m)
             return;
@@ -49,6 +76,9 @@ export function register(pointId, descriptor) {
             emit(pointId);
         }
     };
+    if (slotId)
+        attachToSlot(slotId, dispose);
+    return dispose;
 }
 /** Enumerate descriptors at the named point in registration order. */
 export function list(pointId) {
@@ -98,6 +128,23 @@ export function onAnyChange(cb) {
         anyListeners.delete(cb);
     };
 }
+/**
+ * Drain every disposer registered with `scope.slotId === slotId`. Safe
+ * to call on unknown slot ids. Used by the layout module on slot unmount
+ * to release contributions tied to that slot's lifetime.
+ */
+export function __disposeSlotContributions(slotId) {
+    const bag = slotCleanup.get(slotId);
+    if (!bag)
+        return;
+    // Snapshot before iterating: each dispose detaches itself from the bag
+    // via detachFromSlot, which mutates the live set.
+    const snapshot = Array.from(bag);
+    for (const dispose of snapshot)
+        dispose();
+    // detachFromSlot already removes empty bags, but be explicit.
+    slotCleanup.delete(slotId);
+}
 /**
  * Test-only reset. Not exported from the barrel; tests import it
  * directly from this module.
@@ -106,4 +153,5 @@ export function __resetContributionsForTest() {
     points.clear();
     listeners.clear();
     anyListeners.clear();
+    slotCleanup.clear();
 }

package/dist/contributions/scope.test.d.ts

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

package/dist/contributions/scope.test.js

@@ -0,0 +1,52 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { register, list, onChange, __disposeSlotContributions, __resetContributionsForTest, } from './registry';
+describe('contributions slot scope', () => {
+    beforeEach(() => {
+        __resetContributionsForTest();
+    });
+    it('register without scope behaves exactly as before', () => {
+        const dispose = register('p', { id: 'a' });
+        expect(list('p')).toEqual([{ id: 'a' }]);
+        dispose();
+        expect(list('p')).toEqual([]);
+    });
+    it('register with slot scope is reachable like any contribution', () => {
+        register('p', { id: 'a' }, { scope: { slotId: 's1' } });
+        expect(list('p')).toEqual([{ id: 'a' }]);
+    });
+    it('__disposeSlotContributions drains only the targeted slot', () => {
+        register('p', { id: 'a-s1' }, { scope: { slotId: 's1' } });
+        register('p', { id: 'b-s1' }, { scope: { slotId: 's1' } });
+        register('p', { id: 'c-s2' }, { scope: { slotId: 's2' } });
+        register('p', { id: 'd-noscope' });
+        __disposeSlotContributions('s1');
+        const remaining = list('p').map((d) => d.id).sort();
+        expect(remaining).toEqual(['c-s2', 'd-noscope']);
+    });
+    it('__disposeSlotContributions on unknown slot is a no-op', () => {
+        register('p', { id: 'a' }, { scope: { slotId: 's1' } });
+        expect(() => __disposeSlotContributions('s999')).not.toThrow();
+        expect(list('p')).toEqual([{ id: 'a' }]);
+    });
+    it('manually calling the disposer first makes __disposeSlotContributions a no-op for that entry', () => {
+        const dispose = register('p', { id: 'a' }, { scope: { slotId: 's1' } });
+        dispose();
+        expect(() => __disposeSlotContributions('s1')).not.toThrow();
+        expect(list('p')).toEqual([]);
+    });
+    it('double-dispose is idempotent', () => {
+        const dispose = register('p', { id: 'a' }, { scope: { slotId: 's1' } });
+        dispose();
+        dispose();
+        expect(list('p')).toEqual([]);
+    });
+    it('slot cleanup fires onChange for the affected pointId', () => {
+        const cb = vi.fn();
+        onChange('p', cb);
+        register('p', { id: 'a' }, { scope: { slotId: 's1' } });
+        expect(cb).toHaveBeenCalledTimes(1);
+        cb.mockClear();
+        __disposeSlotContributions('s1');
+        expect(cb).toHaveBeenCalledTimes(1);
+    });
+});

package/dist/contributions/types.d.ts

@@ -5,11 +5,19 @@ export interface ContributionsApi {
      * for ergonomics — provider and contributor agree on the shape via
      * a type-only import of the provider's public types.
      *
+     * Pass `opts.scope.slotId` to tie cleanup to a slot's lifecycle: the
+     * disposer will fire on slot unmount in addition to shard deactivate.
+     * Whichever fires first wins; the disposer is idempotent.
+     *
      * Returns an unregister function. Calling it is optional (the
-     * framework auto-unregisters on shard deactivate) and safe to call
-     * more than once.
+     * framework auto-unregisters on shard deactivate, and on slot unmount
+     * when scoped) and safe to call more than once.
      */
-    register<T = unknown>(pointId: string, descriptor: T): () => void;
+    register<T = unknown>(pointId: string, descriptor: T, opts?: {
+        scope?: {
+            slotId?: string;
+        };
+    }): () => void;
     /** Enumerate descriptors at `pointId` in registration order. */
     list<T = unknown>(pointId: string): T[];
     /** Enumerate every point id with at least one registration. */

package/dist/createShell.js

@@ -70,8 +70,14 @@ export async function createShell(config) {
         // via /api/packages aren't in IndexedDB on the satellite's view of the
         // world unless we fetch and register them, same as the main path.
         await loadDiscoveredPackages(config === null || config === void 0 ? void 0 : config.discoveredPackages);
+        // For app payloads, defer required-shard activation to launchApp so it
+        // runs *after* attachApp() binds the preset manager + slot holds. The
+        // payload's activateShards (manifest.requiredShards) are still carried
+        // for diagnostics, but launchApp drives activation in the same order
+        // as the host bootstrap. Float payloads have no launchApp so the walked
+        // view-providing shards must still activate here.
         await bootstrapSatellite({
-            activateShardIds: satellite.payload.activateShards,
+            activateShardIds: satellite.payload.kind === 'app' ? [] : satellite.payload.activateShards,
         });
         attachGlobalListeners();
         mount(SatelliteShell, { target, props: { payload: satellite.payload } });

package/dist/fields/address.d.ts

@@ -0,0 +1,3 @@
+import type { FieldAddress } from './types';
+export declare function fieldAddressToString(a: FieldAddress): string;
+export declare function fieldAddressFromString(s: string): FieldAddress;

package/dist/fields/address.js

@@ -0,0 +1,36 @@
+const ID_RE = /^[a-zA-Z0-9.\-_]+$/;
+const SLOT_RE = /^[a-zA-Z0-9.\-_]*$/; // slotId may be empty in the wire form
+function validateIdPart(value, partName) {
+    if (value.length === 0)
+        throw new Error(`fieldAddress: ${partName} is empty`);
+    if (!ID_RE.test(value)) {
+        throw new Error(`fieldAddress: invalid ${partName} "${value}" (must match [a-zA-Z0-9.\\-_]+)`);
+    }
+}
+function validateSlotPart(value) {
+    if (!SLOT_RE.test(value)) {
+        throw new Error(`fieldAddress: invalid slotId "${value}"`);
+    }
+}
+export function fieldAddressToString(a) {
+    var _a;
+    validateIdPart(a.shardId, 'shardId');
+    validateIdPart(a.fieldId, 'fieldId');
+    if (a.slotId !== undefined)
+        validateSlotPart(a.slotId);
+    return `${a.shardId}::${(_a = a.slotId) !== null && _a !== void 0 ? _a : ''}::${a.fieldId}`;
+}
+export function fieldAddressFromString(s) {
+    const parts = s.split('::');
+    if (parts.length !== 3) {
+        throw new Error(`fieldAddress: malformed "${s}" (expected three ::-separated parts)`);
+    }
+    const [shardId, slotPart, fieldId] = parts;
+    validateIdPart(shardId, 'shardId');
+    validateIdPart(fieldId, 'fieldId');
+    validateSlotPart(slotPart);
+    const out = { shardId, fieldId };
+    if (slotPart.length > 0)
+        out.slotId = slotPart;
+    return out;
+}

package/dist/fields/address.test.d.ts

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

package/dist/fields/address.test.js

@@ -0,0 +1,34 @@
+import { describe, it, expect } from 'vitest';
+import { fieldAddressToString, fieldAddressFromString } from './address';
+describe('fieldAddress codec', () => {
+    it('roundtrips a slot-scoped address', () => {
+        const a = { shardId: 'editor', slotId: 'slot-1', fieldId: 'title' };
+        expect(fieldAddressFromString(fieldAddressToString(a))).toEqual(a);
+    });
+    it('roundtrips a shard-scoped address (slotId absent)', () => {
+        const a = { shardId: 'settings', fieldId: 'theme' };
+        expect(fieldAddressFromString(fieldAddressToString(a))).toEqual(a);
+    });
+    it('serializes shard-scoped as <shardId>::<empty>::<fieldId>', () => {
+        expect(fieldAddressToString({ shardId: 's', fieldId: 'f' })).toBe('s::::f');
+    });
+    it('serializes slot-scoped as <shardId>::<slotId>::<fieldId>', () => {
+        expect(fieldAddressToString({ shardId: 's', slotId: 'sl', fieldId: 'f' })).toBe('s::sl::f');
+    });
+    it('rejects malformed input — too few parts', () => {
+        expect(() => fieldAddressFromString('s::sl')).toThrow(/malformed/);
+    });
+    it('rejects malformed input — too many parts', () => {
+        expect(() => fieldAddressFromString('s::sl::f::extra')).toThrow(/malformed/);
+    });
+    it('rejects an empty shardId', () => {
+        expect(() => fieldAddressFromString('::sl::f')).toThrow(/shardId/);
+    });
+    it('rejects an empty fieldId', () => {
+        expect(() => fieldAddressFromString('s::sl::')).toThrow(/fieldId/);
+    });
+    it('rejects characters outside [a-zA-Z0-9.\\-_]', () => {
+        expect(() => fieldAddressToString({ shardId: 's space', fieldId: 'f' })).toThrow(/invalid/);
+        expect(() => fieldAddressToString({ shardId: 's', fieldId: 'a:b' })).toThrow(/invalid/);
+    });
+});

package/dist/fields/decoration.d.ts

@@ -0,0 +1,7 @@
+import type { FieldAddress, DecorationHandle } from './types';
+export declare function attachDecoration(addr: FieldAddress, factory: (target: {
+    element: HTMLElement;
+    rect: DOMRect;
+}) => HTMLElement | DecorationHandle): () => void;
+/** Test-only: tear everything down and reset module state. */
+export declare function __resetDecorationLayerForTest(): void;