sh3-core 0.21.2 → 0.22.1

package/dist/shards/activate.svelte.d.ts

@@ -1,102 +0,0 @@
-import type { Shard, ShardContext } from './types';
-/**
- * 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
- * `registerShard`); a future runtime loader appends late without touching
- * the rest of the framework. Callers that need a live list subscribe via
- * Svelte reactivity (e.g. sh3 home listing apps cross-references this
- * map to show which shards they require).
- */
-export declare const registeredShards: Map<string, Shard>;
-export declare const activeShards: Map<string, Shard>;
-/**
- * Reactive map of shard ids that failed to activate. Populated by
- * `activateShard`'s catch block; cleared when the shard is successfully
- * re-registered or activated. Read-only for shards; intended for diagnostic
- * and admin tooling that wants to surface broken shards to the user.
- */
-export interface ShardErrorEntry {
-    id: string;
-    error: unknown;
-    phase: 'autostart' | 'launch' | 'satellite';
-    timestamp: number;
-}
-export declare const erroredShards: Map<string, ShardErrorEntry>;
-/** Host-only. Register a callback that resolves whether the current scope
- *  is a personal tenant or an active project. Wired by createShell after
- *  bootstrap. Avoids circular dependencies with session-state. */
-export declare function __setScopeResolver(resolver: (() => 'tenant' | 'project') | null): void;
-/**
- * Register (or re-register) a shard with the framework so it can later be
- * activated. Records the shard in `registeredShards` but does not run
- * `activate` — that happens at app launch (or for self-starting shards).
- *
- * If a shard with the same id already exists it is silently replaced,
- * which is the expected path during package updates. If the old shard was
- * active it is deactivated first so the new version can be cleanly
- * activated on next launch.
- */
-export declare function registerShard(shard: Shard): void;
-export interface ActivateShardOpts {
-    /**
-     * Where this activation was initiated from. Determines the `phase` field
-     * recorded in `erroredShards` if activation fails. Defaults to 'launch'
-     * (the common case — required by an app being launched).
-     */
-    phase?: 'autostart' | 'launch' | 'satellite';
-}
-/**
- * Activate a registered shard. Builds a `ShardContext`, calls `shard.activate`,
- * verifies that every view declared in the manifest received a factory, then
- * calls `shard.autostart` if defined. Idempotent — calling on an already-active
- * shard is a no-op.
- *
- * If `shard.activate` throws, partial state (registered views, verbs,
- * contributions, document handles, actions, env subscription) is unwound
- * and the failure is recorded in `erroredShards` before the error is
- * re-thrown. Callers in `host.ts` (autostart loop) and `launchApp`
- * (required-shard loop) decide how to react.
- *
- * @param id - The `ShardManifest.id` of the shard to activate. Must be registered.
- * @param opts - Optional. `phase` is recorded in `erroredShards` on failure (default 'launch').
- * @throws If the shard is not registered, if `shard.activate` throws, or if a manifest view has no factory after activation.
- */
-export declare function activateShard(id: string, opts?: ActivateShardOpts): Promise<void>;
-/**
- * Deactivate an active shard. Calls `shard.deactivate`, flushes and disposes
- * all document handles, unregisters all view factories, and removes the shard
- * from `activeShards`. The shard remains in `registeredShards` and can be
- * re-activated. No-op if the shard is not currently active.
- *
- * @param id - The `ShardManifest.id` of the shard to deactivate.
- */
-export declare function deactivateShard(id: string): void;
-/**
- * Return true if the shard with the given id is currently active.
- *
- * @param id - The `ShardManifest.id` to check.
- */
-export declare function isActive(id: string): boolean;
-/**
- * Return the ShardContext for an active shard, or undefined if not active.
- * Used by lifecycle.ts to pass context to `shard.resume()`.
- */
-export declare function getShardContext(id: string): ShardContext | undefined;
-/**
- * Enumerate every view declared as `standalone` across the currently
- * active shards. Intended for the `views --standalone` verb and any
- * launcher UI that wants to surface "summonable" primitives. Only
- * pulls from `activeShards` — registered-but-inactive shards aren't
- * ready to mount.
- */
-export declare function listStandaloneViews(): Array<{
-    shardId: string;
-    viewId: string;
-    label: string;
-}>;
-/**
- * Test-only reset. Tears down any active shard entries (without running
- * deactivate hooks — tests should run deactivate explicitly if they care)
- * and clears both registered and active maps.
- */
-export declare function __resetShardRegistryForTest(): void;

package/dist/shards/activate.svelte.js

@@ -1,403 +0,0 @@
-/*
- * Shard lifecycle — phase 8 split into register and activate.
- *
- * registerShard(shard): adds the shard's manifest to the reactive
- *   `registeredShards` map. No side effects. The host (main.ts) calls
- *   this once per shard via its glob-discovery boot loop. A future
- *   runtime loader calls it after fetching a shard module.
- *
- * activateShard(id): looks up a registered shard, builds its
- *   ShardContext, runs `activate(ctx)`, verifies every manifest view id
- *   received a factory, then runs `autostart(ctx)` if present. The shard
- *   moves into the reactive `activeShards` map. Called internally by
- *   app launch and by the bootstrap self-starting pass. Not public.
- *
- * deactivateShard(id): inverse of activate. Calls `deactivate()`,
- *   unregisters view factories, drops from `activeShards`. The shard
- *   stays in `registeredShards` — it's still known, just not running.
- */
-import { sh3 } from '../sh3Runtime.svelte';
-import { registerView, unregisterView, registerVerb as fwRegisterVerb, unregisterVerb as fwUnregisterVerb } from './registry';
-import { makeSh3Api } from '../sh3Api/headless';
-import { createDocumentHandle, getDocumentBackend, getActiveScopeId } from '../documents';
-import { fetchEnvState, putEnvState } from '../env/client';
-import { getEnvServerUrl } from '../env/index';
-import { apiFetch } from '../transport/apiFetch';
-import { isAdmin as checkIsAdmin } from '../auth/index';
-import { createZoneManager } from '../state/manage';
-import { PERMISSION_STATE_MANAGE } from '../state/types';
-import { PERMISSION_DOCUMENTS_BROWSE, PERMISSION_DOCUMENTS_READ, PERMISSION_DOCUMENTS_WRITE, } from '../documents/types';
-import { createBrowseCapability } from '../documents/browse';
-import { createDocumentPicker } from '../documents/picker-primitive';
-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, onAnyChange as contributionsOnAnyChange, } from '../contributions';
-import { registerAction } from '../actions/registry';
-import { makeSelectionApi, clearSelectionForShard } from '../actions/selection.svelte';
-import { openContextMenu as sh3OpenContextMenu, openPalette as sh3OpenPalette, } from '../actions/listeners';
-/**
- * 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
- * `registerShard`); a future runtime loader appends late without touching
- * the rest of the framework. Callers that need a live list subscribe via
- * Svelte reactivity (e.g. sh3 home listing apps cross-references this
- * map to show which shards they require).
- */
-export const registeredShards = $state(new Map());
-/**
- * Reactive map of currently-active shards. A shard lands here when
- * `activateShard` runs successfully and stays until `deactivateShard`.
- */
-const active = new Map();
-export const activeShards = $state(new Map());
-export const erroredShards = $state(new Map());
-let scopeResolver = null;
-/** Host-only. Register a callback that resolves whether the current scope
- *  is a personal tenant or an active project. Wired by createShell after
- *  bootstrap. Avoids circular dependencies with session-state. */
-export function __setScopeResolver(resolver) {
-    scopeResolver = resolver;
-}
-/**
- * Register (or re-register) a shard with the framework so it can later be
- * activated. Records the shard in `registeredShards` but does not run
- * `activate` — that happens at app launch (or for self-starting shards).
- *
- * If a shard with the same id already exists it is silently replaced,
- * which is the expected path during package updates. If the old shard was
- * active it is deactivated first so the new version can be cleanly
- * activated on next launch.
- */
-export function registerShard(shard) {
-    const id = shard.manifest.id;
-    if (registeredShards.has(id) && activeShards.has(id)) {
-        deactivateShard(id);
-    }
-    registeredShards.set(id, shard);
-    // Re-registering wipes any prior error: the new shard module gets a
-    // clean slate, and a hot-reload of a fixed shard removes the stale entry.
-    erroredShards.delete(id);
-}
-/**
- * Activate a registered shard. Builds a `ShardContext`, calls `shard.activate`,
- * verifies that every view declared in the manifest received a factory, then
- * calls `shard.autostart` if defined. Idempotent — calling on an already-active
- * shard is a no-op.
- *
- * If `shard.activate` throws, partial state (registered views, verbs,
- * contributions, document handles, actions, env subscription) is unwound
- * and the failure is recorded in `erroredShards` before the error is
- * re-thrown. Callers in `host.ts` (autostart loop) and `launchApp`
- * (required-shard loop) decide how to react.
- *
- * @param id - The `ShardManifest.id` of the shard to activate. Must be registered.
- * @param opts - Optional. `phase` is recorded in `erroredShards` on failure (default 'launch').
- * @throws If the shard is not registered, if `shard.activate` throws, or if a manifest view has no factory after activation.
- */
-export async function activateShard(id, opts) {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
-    const shard = registeredShards.get(id);
-    if (!shard) {
-        throw new Error(`Cannot activate shard "${id}": not registered`);
-    }
-    if (active.has(id)) {
-        // Already active (e.g. self-starting shard that was activated at boot
-        // and is now being required by an app). Idempotent — no error.
-        return;
-    }
-    const entry = { shard, ctx: undefined, viewIds: new Set(), verbNames: new Set(), cleanupFns: [] };
-    // envState holds the reactive env data for this shard.
-    // Must be declared with $state at variable declaration time (Svelte 5 rule).
-    const envState = $state({
-        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, contribOpts) {
-            var _a;
-            // Auto-wrap controllable-field descriptors with ownership metadata so
-            // fields/dispatch.ts can route addressed get/set without the user
-            // descriptor needing to know about the framework's wire format.
-            let stored = descriptor;
-            if (pointId === 'sh3.controllable-field') {
-                const owner = { shardId: id };
-                if (((_a = contribOpts === null || contribOpts === void 0 ? void 0 : contribOpts.scope) === null || _a === void 0 ? void 0 : _a.slotId) !== undefined) {
-                    owner.slotId = contribOpts.scope.slotId;
-                }
-                stored = { owner, descriptor };
-            }
-            const dispose = contributionsRegister(pointId, stored, contribOpts);
-            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;
-        },
-        onAnyChange(cb) {
-            const off = contributionsOnAnyChange(cb);
-            entry.cleanupFns.push(async () => off());
-            return off;
-        },
-    };
-    const hasBrowse = (_a = shard.manifest.permissions) === null || _a === void 0 ? void 0 : _a.includes(PERMISSION_DOCUMENTS_BROWSE);
-    const browseCap = hasBrowse
-        ? createBrowseCapability(getActiveScopeId, getDocumentBackend(), {
-            canRead: (_c = (_b = shard.manifest.permissions) === null || _b === void 0 ? void 0 : _b.includes(PERMISSION_DOCUMENTS_READ)) !== null && _c !== void 0 ? _c : false,
-            canWrite: (_e = (_d = shard.manifest.permissions) === null || _d === void 0 ? void 0 : _d.includes(PERMISSION_DOCUMENTS_WRITE)) !== null && _e !== void 0 ? _e : false,
-        })
-        : undefined;
-    const ctx = {
-        state: (schema) => sh3.state(id, schema),
-        registerView: (viewId, factory) => {
-            registerView(viewId, factory, shard.manifest.id);
-            entry.viewIds.add(viewId);
-        },
-        registerVerb: (verb) => {
-            var _a;
-            let prefixed;
-            if (id === 'shell') {
-                prefixed = verb.name;
-            }
-            else {
-                const ns = (_a = shard.manifest.verbNamespace) !== null && _a !== void 0 ? _a : id;
-                prefixed = `${ns}:${verb.name}`;
-            }
-            if (fwRegisterVerb(prefixed, Object.assign(Object.assign({}, verb), { name: prefixed }), id)) {
-                entry.verbNames.add(prefixed);
-            }
-        },
-        documents: (options) => {
-            const handle = createDocumentHandle(getActiveScopeId(), id, getDocumentBackend(), options);
-            entry.cleanupFns.push(() => handle.dispose());
-            return handle;
-        },
-        fetch(path, init) {
-            return apiFetch(this.resolveUrl(path), init);
-        },
-        get serverUrl() {
-            return getEnvServerUrl();
-        },
-        resolveUrl(path) {
-            const isAbsolute = path.startsWith('http://') || path.startsWith('https://');
-            if (isAbsolute)
-                return path;
-            const base = getEnvServerUrl();
-            const sep = path.startsWith('/') ? '' : '/';
-            return `${base}${sep}${path}`;
-        },
-        env(defaults) {
-            if (envState.proxy) {
-                console.warn(`[sh3] Shard "${id}" called ctx.env() more than once; extra calls are ignored.`);
-                return envState.proxy;
-            }
-            envState.defaults = defaults;
-            envState.proxy = Object.assign({}, defaults);
-            return envState.proxy;
-        },
-        async envUpdate(patch) {
-            if (!envState.proxy || !envState.defaults) {
-                throw new Error(`Shard "${id}" called envUpdate() without declaring env state`);
-            }
-            const previous = $state.snapshot(envState.proxy);
-            Object.assign(envState.proxy, patch);
-            try {
-                const snapshot = $state.snapshot(envState.proxy);
-                await putEnvState(id, snapshot);
-            }
-            catch (err) {
-                Object.assign(envState.proxy, previous);
-                throw err;
-            }
-        },
-        get isAdmin() {
-            return checkIsAdmin();
-        },
-        get tenantId() {
-            return getActiveScopeId();
-        },
-        getScope: () => { var _a; return (_a = scopeResolver === null || scopeResolver === void 0 ? void 0 : scopeResolver()) !== null && _a !== void 0 ? _a : 'tenant'; },
-        zones: ((_f = shard.manifest.permissions) === null || _f === void 0 ? void 0 : _f.includes(PERMISSION_STATE_MANAGE))
-            ? createZoneManager()
-            : undefined,
-        browse: browseCap,
-        documentPicker: browseCap
-            ? createDocumentPicker(() => browseCap.listDocuments())
-            : createDocumentPicker(async () => {
-                const docs = await getDocumentBackend().list(getActiveScopeId(), id);
-                return docs.map(d => (Object.assign(Object.assign({}, d), { shardId: id })));
-            }),
-        keys: ((_g = shard.manifest.permissions) === null || _g === void 0 ? void 0 : _g.includes(PERMISSION_KEYS_MINT))
-            ? createShardKeysApi({
-                shardId: id,
-                shardPermissions: (_h = shard.manifest.permissions) !== null && _h !== void 0 ? _h : [],
-            })
-            : undefined,
-        contributions,
-        actions: {
-            register(action) {
-                const dispose = registerAction(action, id);
-                entry.cleanupFns.push(async () => dispose());
-                return dispose;
-            },
-            selection: makeSelectionApi(id),
-            openContextMenu(opts) { sh3OpenContextMenu(opts); },
-            openPalette(opts) { sh3OpenPalette(opts); },
-        },
-        sh3: makeSh3Api({
-            callerKind: 'shard',
-            callerShardId: id,
-            zones: ((_j = shard.manifest.permissions) === null || _j === void 0 ? void 0 : _j.includes(PERMISSION_STATE_MANAGE))
-                ? createZoneManager()
-                : undefined,
-        }),
-    };
-    entry.ctx = ctx;
-    // Wire onKeyRevoked hook: subscribe to the revocation bus for this shard.
-    // Only shards that declare the hook incur the subscription overhead.
-    if (shard.onKeyRevoked) {
-        const off = subscribe(id, async (keyId) => {
-            try {
-                await shard.onKeyRevoked(keyId);
-            }
-            catch (err) {
-                console.error(`[sh3] onKeyRevoked failed in "${id}":`, err);
-            }
-        });
-        entry.cleanupFns.push(async () => off());
-    }
-    active.set(id, entry);
-    activeShards.set(id, shard);
-    try {
-        await shard.activate(ctx);
-        for (const view of shard.manifest.views) {
-            if (!entry.viewIds.has(view.id)) {
-                throw new Error(`Shard "${id}" declared view "${view.id}" in its manifest but registered no factory for it.`);
-            }
-        }
-        // Hydrate env state if the shard declared it via ctx.env().
-        if (envState.proxy && envState.defaults) {
-            try {
-                const stored = await fetchEnvState(id);
-                const merged = Object.assign({}, envState.defaults, stored);
-                Object.assign(envState.proxy, merged);
-            }
-            catch (err) {
-                console.warn(`[sh3] Failed to hydrate env state for shard "${id}":`, err instanceof Error ? err.message : err);
-            }
-        }
-    }
-    catch (err) {
-        // Unwind partial state. Mirror deactivateShard's body, minus the
-        // shard.deactivate?.() call — the shard never finished activating.
-        // Each cleanup fn runs inside its own swallow so a teardown failure
-        // cannot mask the original activation error.
-        for (const fn of entry.cleanupFns) {
-            try {
-                void fn();
-            }
-            catch (_m) {
-                // intentionally swallowed: original error is what matters.
-            }
-        }
-        for (const name of entry.verbNames)
-            fwUnregisterVerb(name);
-        for (const viewId of entry.viewIds)
-            unregisterView(viewId);
-        clearSelectionForShard(id);
-        active.delete(id);
-        activeShards.delete(id);
-        erroredShards.set(id, {
-            id,
-            error: err,
-            phase: (_k = opts === null || opts === void 0 ? void 0 : opts.phase) !== null && _k !== void 0 ? _k : 'launch',
-            timestamp: Date.now(),
-        });
-        console.error(`[sh3] Shard "${id}" failed to activate:`, err);
-        throw err;
-    }
-    // Activation succeeded — clear any prior error record for this shard.
-    erroredShards.delete(id);
-    void ((_l = shard.autostart) === null || _l === void 0 ? void 0 : _l.call(shard, ctx));
-}
-/**
- * Deactivate an active shard. Calls `shard.deactivate`, flushes and disposes
- * all document handles, unregisters all view factories, and removes the shard
- * from `activeShards`. The shard remains in `registeredShards` and can be
- * re-activated. No-op if the shard is not currently active.
- *
- * @param id - The `ShardManifest.id` of the shard to deactivate.
- */
-export function deactivateShard(id) {
-    var _a, _b;
-    const entry = active.get(id);
-    if (!entry)
-        return;
-    void ((_b = (_a = entry.shard).deactivate) === null || _b === void 0 ? void 0 : _b.call(_a));
-    // Flush and dispose document handles before tearing down views.
-    for (const fn of entry.cleanupFns)
-        void fn();
-    for (const name of entry.verbNames)
-        fwUnregisterVerb(name);
-    for (const viewId of entry.viewIds)
-        unregisterView(viewId);
-    clearSelectionForShard(id);
-    active.delete(id);
-    activeShards.delete(id);
-}
-/**
- * Return true if the shard with the given id is currently active.
- *
- * @param id - The `ShardManifest.id` to check.
- */
-export function isActive(id) {
-    return active.has(id);
-}
-/**
- * Return the ShardContext for an active shard, or undefined if not active.
- * Used by lifecycle.ts to pass context to `shard.resume()`.
- */
-export function getShardContext(id) {
-    var _a;
-    return (_a = active.get(id)) === null || _a === void 0 ? void 0 : _a.ctx;
-}
-/**
- * Enumerate every view declared as `standalone` across the currently
- * active shards. Intended for the `views --standalone` verb and any
- * launcher UI that wants to surface "summonable" primitives. Only
- * pulls from `activeShards` — registered-but-inactive shards aren't
- * ready to mount.
- */
-export function listStandaloneViews() {
-    const out = [];
-    for (const shard of activeShards.values()) {
-        for (const view of shard.manifest.views) {
-            if (view.standalone) {
-                out.push({ shardId: shard.manifest.id, viewId: view.id, label: view.label });
-            }
-        }
-    }
-    return out;
-}
-/**
- * Test-only reset. Tears down any active shard entries (without running
- * deactivate hooks — tests should run deactivate explicitly if they care)
- * and clears both registered and active maps.
- */
-export function __resetShardRegistryForTest() {
-    active.clear();
-    activeShards.clear();
-    registeredShards.clear();
-    erroredShards.clear();
-}