sh3-core 0.9.1 → 0.10.1

package/dist/api.d.ts

@@ -19,6 +19,7 @@ export { inspectActiveLayout, spliceIntoActiveLayout, dockIntoActiveLayout, focu
 export type { DocumentHandle, DocumentHandleOptions, DocumentFormat, DocumentMeta, DocumentChange, AutosaveController, } from './documents/types';
 export { PERMISSION_DOCUMENTS_BROWSE, PERMISSION_DOCUMENTS_READ, PERMISSION_DOCUMENTS_WRITE, } from './documents/types';
 export type { BrowseCapability } from './documents/browse';
+export type { ContributionsApi } from './contributions/types';
 export type { SyncPolicy, SyncPolicyRule, DocStatus, ConflictFile, ConflictBranch, } from './documents/sync-types';
 export { PERMISSION_SYNC_PEER, PERMISSION_SYNC_POLICY } from './documents/sync-types';
 export { registeredShards, activeShards } from './shards/activate.svelte';

package/dist/contributions/index.d.ts

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

package/dist/contributions/index.js

@@ -0,0 +1,8 @@
+/*
+ * Contribution-points barrel — internal re-exports.
+ *
+ * The public type (ContributionsApi) reaches shards via api.ts; this
+ * file is internal-only, re-exporting the registry for activate.svelte.ts
+ * and for tests.
+ */
+export { register, list, listPoints, onChange, __resetContributionsForTest } from './registry';

package/dist/contributions/registry.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Register a descriptor under the given point. Returns an unregister
+ * function; calling it more than once is a safe no-op.
+ */
+export declare function register<T = unknown>(pointId: string, descriptor: T): () => 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. */
+export declare function listPoints(): string[];
+/**
+ * Subscribe to registration changes at the named point. The callback
+ * receives no arguments — subscribers call `list` themselves to read
+ * the current state. Returns an unsubscribe; double-unsubscribe is a
+ * safe no-op.
+ */
+export declare function onChange(pointId: string, cb: () => void): () => void;
+/**
+ * Test-only reset. Not exported from the barrel; tests import it
+ * directly from this module.
+ */
+export declare function __resetContributionsForTest(): void;

package/dist/contributions/registry.js

@@ -0,0 +1,89 @@
+/*
+ * Contribution point registry — shard-to-shard runtime collaboration.
+ *
+ * One module-level map holds every point's descriptors. Handles are
+ * Symbols so two registrations with identical content stay distinct.
+ * Emitters are a Set of zero-arg callbacks; subscribers re-read `list`
+ * themselves when notified.
+ *
+ * No tenant partitioning: the shell is single-tenant per session; a
+ * future multi-tenant client would add a tenant dimension to the
+ * outer map (see direction spec §5.2).
+ */
+const points = new Map();
+const listeners = new Map();
+function emit(pointId) {
+    const set = listeners.get(pointId);
+    if (!set)
+        return;
+    for (const cb of set)
+        cb();
+}
+/**
+ * Register a descriptor under the given point. Returns an unregister
+ * function; calling it more than once is a safe no-op.
+ */
+export function register(pointId, descriptor) {
+    const handle = Symbol();
+    let map = points.get(pointId);
+    if (!map) {
+        map = new Map();
+        points.set(pointId, map);
+    }
+    map.set(handle, descriptor);
+    emit(pointId);
+    let disposed = false;
+    return () => {
+        if (disposed)
+            return;
+        disposed = true;
+        const m = points.get(pointId);
+        if (!m)
+            return;
+        if (m.delete(handle)) {
+            if (m.size === 0)
+                points.delete(pointId);
+            emit(pointId);
+        }
+    };
+}
+/** Enumerate descriptors at the named point in registration order. */
+export function list(pointId) {
+    const m = points.get(pointId);
+    return m ? Array.from(m.values()) : [];
+}
+/** Enumerate every point id with at least one registration. */
+export function listPoints() {
+    return Array.from(points.keys());
+}
+/**
+ * Subscribe to registration changes at the named point. The callback
+ * receives no arguments — subscribers call `list` themselves to read
+ * the current state. Returns an unsubscribe; double-unsubscribe is a
+ * safe no-op.
+ */
+export function onChange(pointId, cb) {
+    let set = listeners.get(pointId);
+    if (!set) {
+        set = new Set();
+        listeners.set(pointId, set);
+    }
+    set.add(cb);
+    let disposed = false;
+    return () => {
+        if (disposed)
+            return;
+        disposed = true;
+        set.delete(cb);
+        if (set.size === 0)
+            listeners.delete(pointId);
+    };
+}
+/**
+ * Test-only reset. Not exported from the barrel; tests import it
+ * directly from this module.
+ */
+export function __resetContributionsForTest() {
+    points.clear();
+    listeners.clear();
+}

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

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

package/dist/contributions/registry.test.js

@@ -0,0 +1,109 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { register, list, listPoints, onChange, __resetContributionsForTest, } from './registry';
+describe('contributions registry', () => {
+    beforeEach(() => {
+        __resetContributionsForTest();
+    });
+    describe('register / list', () => {
+        it('returns an unregister function', () => {
+            const unreg = register('p', { id: 'a' });
+            expect(typeof unreg).toBe('function');
+        });
+        it('register then list returns the descriptor', () => {
+            register('p', { id: 'a' });
+            expect(list('p')).toEqual([{ id: 'a' }]);
+        });
+        it('lists multiple descriptors in registration order', () => {
+            register('p', { id: 'a' });
+            register('p', { id: 'b' });
+            register('p', { id: 'c' });
+            expect(list('p').map((d) => d.id)).toEqual(['a', 'b', 'c']);
+        });
+        it('separates descriptors by pointId', () => {
+            register('p1', { id: 'a' });
+            register('p2', { id: 'b' });
+            expect(list('p1')).toEqual([{ id: 'a' }]);
+            expect(list('p2')).toEqual([{ id: 'b' }]);
+        });
+        it('returns an empty array for an unknown pointId', () => {
+            expect(list('nope')).toEqual([]);
+        });
+        it('unregister removes the descriptor', () => {
+            const unreg = register('p', { id: 'a' });
+            unreg();
+            expect(list('p')).toEqual([]);
+        });
+        it('double-unregister is a no-op', () => {
+            const unreg = register('p', { id: 'a' });
+            unreg();
+            unreg();
+            expect(list('p')).toEqual([]);
+        });
+        it('allows duplicate descriptors (framework does not inspect content)', () => {
+            register('p', { id: 'a' });
+            register('p', { id: 'a' });
+            expect(list('p')).toHaveLength(2);
+        });
+    });
+    describe('listPoints', () => {
+        it('returns empty when nothing is registered', () => {
+            expect(listPoints()).toEqual([]);
+        });
+        it('returns every pointId with at least one registration', () => {
+            register('p1', { id: 'a' });
+            register('p2', { id: 'b' });
+            expect(listPoints().sort()).toEqual(['p1', 'p2']);
+        });
+        it('excludes pointIds whose last registration was unregistered', () => {
+            const u1 = register('p1', { id: 'a' });
+            register('p2', { id: 'b' });
+            u1();
+            expect(listPoints()).toEqual(['p2']);
+        });
+    });
+    describe('onChange', () => {
+        it('fires on register', () => {
+            const cb = vi.fn();
+            onChange('p', cb);
+            register('p', { id: 'a' });
+            expect(cb).toHaveBeenCalledTimes(1);
+        });
+        it('fires on unregister', () => {
+            const cb = vi.fn();
+            const unreg = register('p', { id: 'a' });
+            onChange('p', cb);
+            unreg();
+            expect(cb).toHaveBeenCalledTimes(1);
+        });
+        it('does not fire for other pointIds', () => {
+            const cb = vi.fn();
+            onChange('p1', cb);
+            register('p2', { id: 'a' });
+            expect(cb).not.toHaveBeenCalled();
+        });
+        it('supports multiple subscribers', () => {
+            const a = vi.fn();
+            const b = vi.fn();
+            onChange('p', a);
+            onChange('p', b);
+            register('p', { id: 'x' });
+            expect(a).toHaveBeenCalledTimes(1);
+            expect(b).toHaveBeenCalledTimes(1);
+        });
+        it('unsubscribe stops callbacks', () => {
+            const cb = vi.fn();
+            const off = onChange('p', cb);
+            off();
+            register('p', { id: 'x' });
+            expect(cb).not.toHaveBeenCalled();
+        });
+        it('double-unsubscribe is a no-op', () => {
+            const cb = vi.fn();
+            const off = onChange('p', cb);
+            off();
+            off();
+            register('p', { id: 'x' });
+            expect(cb).not.toHaveBeenCalled();
+        });
+    });
+});

package/dist/contributions/types.d.ts

@@ -0,0 +1,24 @@
+export interface ContributionsApi {
+    /**
+     * Register `descriptor` under `pointId`. Descriptors are freeform;
+     * the framework does not inspect them. The type parameter exists
+     * for ergonomics — provider and contributor agree on the shape via
+     * a type-only import of the provider's public types.
+     *
+     * Returns an unregister function. Calling it is optional (the
+     * framework auto-unregisters on shard deactivate) and safe to call
+     * more than once.
+     */
+    register<T = unknown>(pointId: string, descriptor: T): () => void;
+    /** Enumerate descriptors at `pointId` in registration order. */
+    list<T = unknown>(pointId: string): T[];
+    /** Enumerate every point id with at least one registration. */
+    listPoints(): string[];
+    /**
+     * Subscribe to registration changes at `pointId`. The callback
+     * receives no arguments — call `list` from inside to read the
+     * current state. Returns an unsubscribe; auto-unsubscribed on
+     * shard deactivate.
+     */
+    onChange(pointId: string, cb: () => void): () => void;
+}

package/dist/contributions/types.js

@@ -0,0 +1,10 @@
+/*
+ * ContributionsApi — the per-shard surface exposed on ShardContext.
+ *
+ * See docs/sh3-rfcs/2026-04-20-shard-contribution-points.md for
+ * motivation and semantics. Every registration and every onChange
+ * subscription made through this API is auto-cleaned when the owning
+ * shard deactivates; callers should not need to call the returned
+ * disposer unless they want to release early.
+ */
+export {};

package/dist/shards/activate-contributions.test.d.ts

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

package/dist/shards/activate-contributions.test.js

@@ -0,0 +1,110 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { MemoryDocumentBackend } from '../documents/backends';
+import { __setDocumentBackend, __setTenantId } from '../documents/config';
+import { registerShard, activateShard, deactivateShard, __resetShardRegistryForTest, } from './activate.svelte';
+import { __resetContributionsForTest, list, listPoints } from '../contributions';
+describe('ctx.contributions', () => {
+    beforeEach(() => {
+        __resetShardRegistryForTest();
+        __resetContributionsForTest();
+        __setDocumentBackend(new MemoryDocumentBackend());
+        __setTenantId('tenant-a');
+    });
+    it('is always present on ShardContext (no permission required)', async () => {
+        let captured = null;
+        registerShard({
+            manifest: { id: 'a', label: 'A', version: '0.0.0', views: [] },
+            activate(ctx) { captured = ctx; },
+        });
+        await activateShard('a');
+        expect(typeof captured.contributions.register).toBe('function');
+        expect(typeof captured.contributions.list).toBe('function');
+        expect(typeof captured.contributions.listPoints).toBe('function');
+        expect(typeof captured.contributions.onChange).toBe('function');
+    });
+    it('register() makes the descriptor visible via the global list()', async () => {
+        registerShard({
+            manifest: { id: 'provider', label: 'P', version: '0.0.0', views: [] },
+            activate(ctx) {
+                ctx.contributions.register('my.point', { id: 'alpha' });
+            },
+        });
+        await activateShard('provider');
+        expect(list('my.point')).toEqual([{ id: 'alpha' }]);
+    });
+    it('deactivate auto-unregisters every descriptor the shard registered', async () => {
+        registerShard({
+            manifest: { id: 'provider', label: 'P', version: '0.0.0', views: [] },
+            activate(ctx) {
+                ctx.contributions.register('p1', { id: 'a' });
+                ctx.contributions.register('p1', { id: 'b' });
+                ctx.contributions.register('p2', { id: 'c' });
+            },
+        });
+        await activateShard('provider');
+        expect(list('p1')).toHaveLength(2);
+        expect(list('p2')).toHaveLength(1);
+        deactivateShard('provider');
+        expect(list('p1')).toEqual([]);
+        expect(list('p2')).toEqual([]);
+        expect(listPoints()).toEqual([]);
+    });
+    it('deactivate auto-unsubscribes every onChange listener the shard registered', async () => {
+        const cb = vi.fn();
+        registerShard({
+            manifest: { id: 'watcher', label: 'W', version: '0.0.0', views: [] },
+            activate(ctx) {
+                ctx.contributions.onChange('p', cb);
+            },
+        });
+        await activateShard('watcher');
+        registerShard({
+            manifest: { id: 'provider', label: 'P', version: '0.0.0', views: [] },
+            activate(ctx) {
+                ctx.contributions.register('p', { id: 'x' });
+            },
+        });
+        await activateShard('provider');
+        expect(cb).toHaveBeenCalledTimes(1);
+        deactivateShard('watcher');
+        // Further registrations must not reach the watcher's callback.
+        registerShard({
+            manifest: { id: 'provider-2', label: 'P2', version: '0.0.0', views: [] },
+            activate(ctx) {
+                ctx.contributions.register('p', { id: 'y' });
+            },
+        });
+        await activateShard('provider-2');
+        expect(cb).toHaveBeenCalledTimes(1);
+    });
+    it('two shards can contribute to the same point independently', async () => {
+        registerShard({
+            manifest: { id: 'a', label: 'A', version: '0.0.0', views: [] },
+            activate(ctx) { ctx.contributions.register('shared', { from: 'a' }); },
+        });
+        registerShard({
+            manifest: { id: 'b', label: 'B', version: '0.0.0', views: [] },
+            activate(ctx) { ctx.contributions.register('shared', { from: 'b' }); },
+        });
+        await activateShard('a');
+        await activateShard('b');
+        expect(list('shared')).toEqual([{ from: 'a' }, { from: 'b' }]);
+        deactivateShard('a');
+        expect(list('shared')).toEqual([{ from: 'b' }]);
+    });
+    it('explicit unregister returned by register() is safe alongside auto-cleanup', async () => {
+        let earlyUnregister;
+        registerShard({
+            manifest: { id: 'p', label: 'P', version: '0.0.0', views: [] },
+            activate(ctx) {
+                earlyUnregister = ctx.contributions.register('p', { id: 'a' });
+            },
+        });
+        await activateShard('p');
+        expect(list('p')).toHaveLength(1);
+        earlyUnregister();
+        expect(list('p')).toEqual([]);
+        // Deactivate must not throw when the entry is already gone.
+        expect(() => deactivateShard('p')).not.toThrow();
+    });
+});

package/dist/shards/activate.svelte.js

@@ -28,6 +28,7 @@ import { createBrowseCapability } from '../documents/browse';
 import { createShardKeysApi } from '../keys/client';
 import { PERMISSION_KEYS_MINT } from '../keys/types';
 import { subscribe } from '../keys/revocation-bus.svelte';
+import { register as contributionsRegister, list as contributionsList, listPoints as contributionsListPoints, onChange as contributionsOnChange, } from '../contributions';
 /**
  * Reactive registry of every shard known to the host. Keys are shard ids.
  * Populated once at boot by the glob-discovery loop in main.ts (through
@@ -87,6 +88,27 @@ export async function activateShard(id) {
         proxy: null,
         defaults: null,
     });
+    // Per-shard wrapper: every register/onChange call goes into the
+    // global registry, and its disposer is pushed into entry.cleanupFns
+    // so deactivate auto-unregisters.
+    const contributions = {
+        register(pointId, descriptor) {
+            const dispose = contributionsRegister(pointId, descriptor);
+            entry.cleanupFns.push(async () => dispose());
+            return dispose;
+        },
+        list(pointId) {
+            return contributionsList(pointId);
+        },
+        listPoints() {
+            return contributionsListPoints();
+        },
+        onChange(pointId, cb) {
+            const off = contributionsOnChange(pointId, cb);
+            entry.cleanupFns.push(async () => off());
+            return off;
+        },
+    };
     const ctx = {
         state: (schema) => shell.state(id, schema),
         registerView: (viewId, factory) => {
@@ -148,6 +170,7 @@ export async function activateShard(id) {
                 shardPermissions: (_d = shard.manifest.permissions) !== null && _d !== void 0 ? _d : [],
             })
             : undefined,
+        contributions,
     };
     entry.ctx = ctx;
     // Wire onKeyRevoked hook: subscribe to the revocation bus for this shard.

package/dist/shards/types.d.ts

@@ -5,6 +5,7 @@ import type { BrowseCapability } from '../documents/browse';
 import type { EnvState } from '../env/types';
 import type { Verb } from '../verbs/types';
 import type { ShardContextKeys } from '../keys/types';
+import type { ContributionsApi } from '../contributions/types';
 export { PERMISSION_KEYS_MINT, type ShardContextKeys, type ApiKeyPublic, type MintOpts, ScopeEscalationError, ConsentDeniedError } from '../keys/types';
 /**
  * The object returned by `ViewFactory.mount`. The framework calls
@@ -225,6 +226,12 @@ export interface ShardContext {
      * manifest declares the `keys:mint` permission.
      */
     keys?: ShardContextKeys;
+    /**
+     * Runtime registry for inter-shard contribution points. Every
+     * shard receives this — no permission gate in v1. See
+     * docs/sh3-rfcs/2026-04-20-shard-contribution-points.md.
+     */
+    contributions: ContributionsApi;
 }
 /**
  * A shard module. Shards are the fundamental unit of contribution in SH3.

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** Auto-generated from package.json — do not edit manually. */
-export declare const VERSION = "0.9.1";
+export declare const VERSION = "0.10.1";

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Auto-generated from package.json — do not edit manually. */
-export const VERSION = '0.9.1';
+export const VERSION = '0.10.1';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sh3-core",
-  "version": "0.9.1",
+  "version": "0.10.1",
   "type": "module",
   "files": [
     "dist"