sh3-core 0.1.0

package/dist/registry-shard/registryShard.svelte.js

@@ -0,0 +1,125 @@
+/*
+ * Registry shard — framework-shipped shard for managing packages on the
+ * local SH3 server's registry.
+ *
+ * Contributes one view:
+ *   - `sh3-registry:manage` — package list, publish, edit, update, delete
+ *
+ * Auth is handled via getAuthHeader() from the framework's auth module.
+ * No user zone — all server calls include the Authorization header
+ * automatically.
+ *
+ * `.svelte.ts` because mounting Svelte components requires rune access.
+ */
+import { mount, unmount } from 'svelte';
+import RegistryView from './RegistryView.svelte';
+import { getAuthHeader } from '../auth/index';
+/**
+ * Module-level context set during activate(). Imported by the Svelte
+ * view component so it can read/write state and trigger actions.
+ */
+export let registryContext = undefined;
+/** Build fetch headers with auth. Throws if not elevated. */
+function authHeaders(contentType) {
+    const auth = getAuthHeader();
+    const headers = {};
+    if (auth)
+        headers['Authorization'] = auth;
+    if (contentType)
+        headers['Content-Type'] = contentType;
+    return headers;
+}
+/** Server base URL — same-origin. */
+const apiBase = '';
+export const registryShard = {
+    manifest: {
+        id: 'sh3-registry',
+        label: 'Registry Manager',
+        version: '0.1.0',
+        views: [
+            { id: 'sh3-registry:manage', label: 'Registry' },
+        ],
+    },
+    activate(ctx) {
+        const state = ctx.state({
+            ephemeral: {
+                packages: [],
+                loading: false,
+                error: null,
+            },
+        });
+        async function refreshPackages() {
+            var _a;
+            state.ephemeral.loading = true;
+            state.ephemeral.error = null;
+            try {
+                const res = await fetch(`${apiBase}/registry.json`);
+                if (!res.ok)
+                    throw new Error(`HTTP ${res.status} ${res.statusText}`);
+                const data = await res.json();
+                state.ephemeral.packages = (_a = data.packages) !== null && _a !== void 0 ? _a : [];
+            }
+            catch (err) {
+                state.ephemeral.error = err instanceof Error ? err.message : String(err);
+            }
+            finally {
+                state.ephemeral.loading = false;
+            }
+        }
+        async function publishPackage(form) {
+            var _a;
+            const res = await fetch(`${apiBase}/api/registry/publish`, {
+                method: 'POST',
+                headers: authHeaders(),
+                body: form,
+            });
+            if (!res.ok) {
+                const data = await res.json().catch(() => ({ error: res.statusText }));
+                throw new Error((_a = data.error) !== null && _a !== void 0 ? _a : `HTTP ${res.status}`);
+            }
+            await refreshPackages();
+        }
+        async function patchPackage(id, fields) {
+            var _a;
+            const res = await fetch(`${apiBase}/api/registry/packages/${id}`, {
+                method: 'PATCH',
+                headers: authHeaders('application/json'),
+                body: JSON.stringify(fields),
+            });
+            if (!res.ok) {
+                const data = await res.json().catch(() => ({ error: res.statusText }));
+                throw new Error((_a = data.error) !== null && _a !== void 0 ? _a : `HTTP ${res.status}`);
+            }
+            await refreshPackages();
+        }
+        async function deletePackage(id) {
+            var _a;
+            const res = await fetch(`${apiBase}/api/registry/packages/${id}`, {
+                method: 'DELETE',
+                headers: authHeaders(),
+            });
+            if (!res.ok) {
+                const data = await res.json().catch(() => ({ error: res.statusText }));
+                throw new Error((_a = data.error) !== null && _a !== void 0 ? _a : `HTTP ${res.status}`);
+            }
+            await refreshPackages();
+        }
+        // Set the module-level context so the view component can import it.
+        registryContext = { state, refreshPackages, publishPackage, patchPackage, deletePackage };
+        const manageFactory = {
+            mount(container, _context) {
+                const instance = mount(RegistryView, { target: container });
+                void refreshPackages();
+                return {
+                    unmount() {
+                        unmount(instance);
+                    },
+                };
+            },
+        };
+        ctx.registerView('sh3-registry:manage', manageFactory);
+    },
+    autostart() {
+        // Self-starting so the view is available from the launcher.
+    },
+};

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

@@ -0,0 +1,45 @@
+import type { Shard } 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. shell 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>;
+/**
+ * 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 immediately for self-starting shards).
+ *
+ * @param shard - The shard module to register. `shard.manifest.id` must be unique.
+ * @throws If a shard with the same id is already registered.
+ */
+export declare function registerShard(shard: Shard): void;
+/**
+ * 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.
+ *
+ * @param id - The `ShardManifest.id` of the shard to activate. Must be registered.
+ * @throws If the shard is not registered, or if a manifest view has no factory after activation.
+ */
+export declare function activateShard(id: string): 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;

package/dist/shards/activate.svelte.js

@@ -0,0 +1,124 @@
+/*
+ * 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 { shell } from '../shellRuntime.svelte';
+import { registerView, unregisterView } from './registry';
+import { createDocumentHandle, getTenantId, getDocumentBackend } from '../documents';
+/**
+ * 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. shell 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());
+/**
+ * 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 immediately for self-starting shards).
+ *
+ * @param shard - The shard module to register. `shard.manifest.id` must be unique.
+ * @throws If a shard with the same id is already registered.
+ */
+export function registerShard(shard) {
+    const id = shard.manifest.id;
+    if (registeredShards.has(id)) {
+        throw new Error(`Shard "${id}" is already registered`);
+    }
+    registeredShards.set(id, shard);
+}
+/**
+ * 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.
+ *
+ * @param id - The `ShardManifest.id` of the shard to activate. Must be registered.
+ * @throws If the shard is not registered, or if a manifest view has no factory after activation.
+ */
+export async function activateShard(id) {
+    var _a;
+    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, viewIds: new Set(), cleanupFns: [] };
+    const ctx = {
+        state: (schema) => shell.state(id, schema),
+        registerView: (viewId, factory) => {
+            registerView(viewId, factory);
+            entry.viewIds.add(viewId);
+        },
+        documents: (options) => {
+            const handle = createDocumentHandle(getTenantId(), id, getDocumentBackend(), options);
+            entry.cleanupFns.push(() => handle.dispose());
+            return handle;
+        },
+    };
+    active.set(id, entry);
+    activeShards.set(id, shard);
+    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.`);
+        }
+    }
+    void ((_a = shard.autostart) === null || _a === void 0 ? void 0 : _a.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 viewId of entry.viewIds)
+        unregisterView(viewId);
+    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);
+}

package/dist/shards/registry.d.ts

@@ -0,0 +1,4 @@
+import type { ViewFactory } from './types';
+export declare function registerView(viewId: string, factory: ViewFactory): void;
+export declare function getView(viewId: string): ViewFactory | undefined;
+export declare function unregisterView(viewId: string): void;

package/dist/shards/registry.js

@@ -0,0 +1,28 @@
+/*
+ * Contribution registry — phase 4 stub.
+ *
+ * Tracks which ViewFactory answers a given viewId. In this phase the
+ * registry is a flat module-level Map with no awareness of shard identity;
+ * writes come from `activateShard` which additionally remembers which
+ * viewIds a given shard registered so they can be torn down in
+ * `deactivateShard`.
+ *
+ * The shape of this registry is deliberately narrow so later phases can
+ * expand it without breaking callers:
+ *   - Resolution by viewId is the only query slots need.
+ *   - Commands, toolbar items, menus, hotkeys get their own sibling maps
+ *     (one per contribution kind) when those kinds land.
+ */
+const views = new Map();
+export function registerView(viewId, factory) {
+    if (views.has(viewId)) {
+        throw new Error(`View "${viewId}" is already registered`);
+    }
+    views.set(viewId, factory);
+}
+export function getView(viewId) {
+    return views.get(viewId);
+}
+export function unregisterView(viewId) {
+    views.delete(viewId);
+}

package/dist/shards/types.d.ts

@@ -0,0 +1,155 @@
+import type { StateZones } from '../state/zones.svelte';
+import type { ZoneSchema } from '../state/types';
+import type { DocumentHandle, DocumentHandleOptions } from '../documents/types';
+/**
+ * The object returned by `ViewFactory.mount`. The framework calls
+ * `unmount()` when the slot goes away, and `onResize(w, h)` whenever the
+ * slot's container changes size (including splitter drags and window
+ * resize). `remountOnMove` is the opt-out from the re-parenting-survival
+ * contract (rare, GL-edge-case shards); phase 4 does not exercise it.
+ */
+export interface ViewHandle {
+    /** Called by the framework when the slot is removed from the layout. Release all resources here. */
+    unmount(): void;
+    /** Optional callback invoked when the slot's container dimensions change. */
+    onResize?(width: number, height: number): void;
+    /**
+     * When true the framework will unmount and remount this view if its slot
+     * moves to a different DOM parent (e.g. a splitter drag). Set to false
+     * (or omit) if the view can survive DOM re-parenting without reinitializing.
+     */
+    remountOnMove?: boolean;
+    /**
+     * Closability mode for this view instance.
+     *   - undefined / false: non-closable (no close button rendered).
+     *   - true: pure close — instant removal, no confirmation.
+     *   - { canClose() }: guarded close — layout engine awaits the promise;
+     *     resolve true to allow, false to cancel.
+     */
+    closable?: boolean | {
+        canClose(): Promise<boolean>;
+    };
+}
+/**
+ * Context passed to `ViewFactory.mount` so the view knows which layout
+ * instance it is and can push reactive metadata back to the tab strip.
+ */
+export interface MountContext {
+    /** Stable identifier for the slot this view is mounted into. */
+    slotId: string;
+    /** The view id that was used to look up this factory. */
+    viewId: string;
+    /** Initial label for the tab; may be updated by the view via future API. */
+    label: string;
+    /**
+     * Push dirty-state to the tab strip. The framework renders a dirty
+     * indicator (filled dot) on the tab when true, clears it when false.
+     * Call this whenever the view's save-state changes.
+     */
+    setDirty(dirty: boolean): void;
+}
+/**
+ * The shard-side adapter that knows how to bring a view to life inside a
+ * given HTMLElement. The container is owned by the framework (the slot);
+ * the factory writes into it and returns a ViewHandle.
+ */
+export interface ViewFactory {
+    /**
+     * Mount the view into `container`. The container element is owned and sized
+     * by the framework; the factory should not modify its dimensions or position.
+     * Returns a `ViewHandle` the framework uses to communicate with the view.
+     */
+    mount(container: HTMLElement, context: MountContext): ViewHandle;
+}
+/**
+ * Static description of a view a shard provides. Lives inside
+ * `ShardManifest.views` so apps and tooling can enumerate a shard's views
+ * without running `activate()`. Phase 8 only uses `id` and `label`; `icon`
+ * is reserved and not rendered yet.
+ */
+export interface ViewDeclaration {
+    /** Unique view id within this shard. Used to look up the factory at mount time. */
+    id: string;
+    /** Human-readable label used in tab strips and launchers. */
+    label: string;
+    /** Optional icon hint (reserved; not yet rendered in phase 8). */
+    icon?: string;
+}
+/**
+ * Static description of a shard. Declared once and read by the framework
+ * before `activate` runs, so the shell can enumerate a shard's capabilities
+ * without executing any shard code.
+ */
+export interface ShardManifest {
+    /** Unique shard identifier. Used as the state namespace and view id prefix. */
+    id: string;
+    /** Human-readable display name. */
+    label: string;
+    /** Semver version string for the shard package. */
+    version: string;
+    /**
+     * Static list of the view ids this shard provides. Every id listed here
+     * must be backed by a `ctx.registerView(id, factory)` call from within
+     * `activate()`; the framework verifies this after `activate` returns and
+     * throws on any missing factory. Phase 8 adds this field; shards that
+     * predate phase 8 must be updated to declare their views here.
+     */
+    views: ViewDeclaration[];
+}
+/**
+ * Handed to `shard.activate`. The shard uses it to declare state and
+ * register contributions. `state` is pre-bound to the shard's id so the
+ * shard never has to pass its own id through — the framework guarantees
+ * isolation by construction.
+ */
+export interface ShardContext {
+    /**
+     * Declare the state zones this shard uses and receive a live reactive
+     * object. The shard id is baked in — shards never pass their own id.
+     * Persistent zones (`workspace`, `user`) are hydrated before the call
+     * returns.
+     *
+     * @param schema - Zone names mapped to their default values.
+     */
+    state<T extends ZoneSchema>(schema: T): StateZones<T>;
+    /**
+     * Register a view factory for a view id declared in the shard manifest.
+     * Must be called for every id listed in `manifest.views` during `activate`.
+     *
+     * @param viewId  - Must match an entry in `manifest.views`.
+     * @param factory - The adapter that mounts the view into a container element.
+     */
+    registerView(viewId: string, factory: ViewFactory): void;
+    /** Obtain a file-oriented document handle scoped to this shard. */
+    documents(options: DocumentHandleOptions): DocumentHandle;
+}
+/**
+ * A shard module. Shards are the fundamental unit of contribution in SH3.
+ * Each shard activates once, receives a `ShardContext`, and registers views
+ * and other capabilities that the shell and apps can use. Shard lifecycle is
+ * separate from view lifecycle — a shard may be active with no views visible.
+ */
+export interface Shard {
+    /** Static description of this shard's identity and declared contributions. */
+    manifest: ShardManifest;
+    /**
+     * Run once when the shard is activated. Use `ctx` to declare state zones,
+     * register view factories, and obtain document handles. Must register a
+     * factory for every view id declared in `manifest.views`.
+     */
+    activate(ctx: ShardContext): void | Promise<void>;
+    /**
+     * Optional self-starting hook. A shard that defines `autostart` is
+     * eagerly activated by the framework at boot (right after the register
+     * pass finishes) instead of waiting for an app to require it. `activate`
+     * runs first; `autostart` runs immediately after and may take imperative
+     * action — docking its own views into the active layout, opening a
+     * modal, subscribing to framework state, etc. The `__shell__` pseudo-
+     * shard uses this with a no-op body so its activation path is uniform
+     * with other self-starting shards. Diagnostic-style shards use it to
+     * do real work.
+     */
+    autostart?(ctx: ShardContext): void | Promise<void>;
+    /** Optional cleanup hook called when the shard is deactivated. Release timers, subscriptions, and external resources here. */
+    deactivate?(): void | Promise<void>;
+}

package/dist/shards/types.js

@@ -0,0 +1,20 @@
+/*
+ * Shard contract — minimum viable draft for phase 4.
+ *
+ * A shard is a self-contained module that contributes capabilities (views,
+ * commands, services, …) to the shell. See docs/design/shards.md for the
+ * full design; phase 4 implements only the pieces needed to mount a view
+ * into a layout slot:
+ *
+ *   - A shard declares a manifest.
+ *   - `activate(ctx)` runs once, receives a ShardContext, and registers
+ *     whichever contributions it wants the shell to know about.
+ *   - A ViewFactory knows how to mount a view into a raw HTMLElement and
+ *     return a handle the framework uses to unmount / notify of resizes.
+ *
+ * Deferred to later phases: bus scoping, command/toolbar/menu/hotkey
+ * registration, modal provider contributions, background services, lazy
+ * activation events. They'll slot into `ShardContext` as new `register*`
+ * methods without disturbing the phase-4 shape.
+ */
+export {};