sh3-core 0.1.0

package/dist/Shell.svelte

@@ -0,0 +1,185 @@
+<script lang="ts">
+  /*
+   * <Shell> — top-level chrome component.
+   *
+   * Owns the tab bar, status bar, docked content area (layer 0), and the
+   * six overlay roots (layers 1-6). This is a stub implementation for
+   * phase 1: the content area is empty and the overlay roots are present
+   * but unmanaged. Layout tree rendering arrives in phase 2; overlay layer
+   * managers arrive in phase 5.
+   *
+   * The six overlay roots are mounted here (not lazily) so that layer
+   * managers in later phases have stable DOM targets to portal into.
+   */
+
+  import './tokens.css';
+  import LayoutRenderer from './layout/LayoutRenderer.svelte';
+  import DragPreview from './layout/DragPreview.svelte';
+  import type { OverlayLayer } from './overlays/types';
+  import { registerLayerRoot, unregisterLayerRoot } from './overlays/roots';
+  import { returnToHome, getActiveApp } from './api';
+  import iconsUrl from './assets/icons.svg';
+
+  // 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 (shell.modal,
+  // shell.popup, shell.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);
+    };
+  });
+</script>
+
+<div class="shell">
+  <header class="shell-tabbar" data-shell-region="tabbar">
+    <span class="shell-tabbar-brand">SH3</span>
+    {#if getActiveApp()}
+      <button
+        type="button"
+        class="shell-tabbar-home-button"
+        onclick={() => returnToHome()}
+        title="Home"
+      >
+        <svg class="shell-tabbar-home-icon" aria-hidden="true">
+          <use href="{iconsUrl}#house" />
+        </svg>
+      </button>
+    {/if}
+  </header>
+
+  <main class="shell-content" data-shell-region="content" data-shell-layer="0">
+    <LayoutRenderer />
+  </main>
+
+  <footer class="shell-statusbar" data-shell-region="statusbar">
+    <span class="shell-statusbar-alpha">alpha</span>
+  </footer>
+
+  <!--
+    Overlay roots. Each is absolutely positioned over the entire shell with
+    pointer-events: none by default; layer managers enable pointer events on
+    the specific surfaces they portal in.
+  -->
+  <div class="shell-overlays" aria-hidden="true">
+    {#each overlayLayers as { layer, name } (layer)}
+      <div
+        class="shell-overlay-root"
+        data-shell-overlay={name}
+        data-shell-layer={layer}
+        style="z-index: var(--shell-z-layer-{layer});"
+        bind:this={overlayRoots[name]}
+      >
+        {#if name === 'drag-preview'}
+          <DragPreview />
+        {/if}
+      </div>
+    {/each}
+  </div>
+</div>
+
+<style>
+  .shell {
+    display: grid;
+    grid-template-rows: var(--shell-tabbar-height) 1fr var(--shell-statusbar-height);
+    height: 100%;
+    width: 100%;
+    position: relative;
+    background: var(--shell-bg);
+    color: var(--shell-fg);
+  }
+
+  .shell-tabbar {
+    display: flex;
+    align-items: center;
+    gap: var(--shell-pad-md);
+    padding: 0 var(--shell-pad-md);
+    background: var(--shell-bg-elevated);
+    border-bottom: 1px solid var(--shell-border);
+    user-select: none;
+  }
+  .shell-tabbar-brand {
+    font-weight: 600;
+    color: var(--shell-accent);
+    letter-spacing: 0.5px;
+  }
+
+  .shell-content {
+    position: relative;
+    overflow: hidden;
+    background: var(--shell-bg);
+    min-width: 0;
+    min-height: 0;
+  }
+  .shell-statusbar {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 0 var(--shell-pad-md);
+    background: var(--shell-bg-sunken);
+    border-top: 1px solid var(--shell-border);
+    color: var(--shell-fg-muted);
+    font-size: 11px;
+    user-select: none;
+  }
+
+  .shell-overlays {
+    position: absolute;
+    inset: 0;
+    pointer-events: none;
+  }
+  .shell-overlay-root {
+    position: absolute;
+    inset: 0;
+    pointer-events: none;
+  }
+
+  .shell-tabbar-home-button {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 24px;
+    height: 24px;
+    padding: 0;
+    background: transparent;
+    color: var(--shell-fg-muted);
+    border: 1px solid var(--shell-border);
+    border-radius: 4px;
+    cursor: pointer;
+  }
+  .shell-tabbar-home-button:hover {
+    color: var(--shell-fg);
+    border-color: var(--shell-fg-muted);
+  }
+  .shell-tabbar-home-icon {
+    width: 14px;
+    height: 14px;
+  }
+
+  .shell-statusbar-alpha {
+    font-size: 9px;
+    font-weight: 700;
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+    color: #fff;
+    background: var(--shell-accent);
+    padding: 1px 6px;
+    border-radius: 8px;
+  }
+</style>

package/dist/Shell.svelte.d.ts

@@ -0,0 +1,4 @@
+import './tokens.css';
+declare const Shell: import("svelte").Component<Record<string, never>, {}, "">;
+type Shell = ReturnType<typeof Shell>;
+export default Shell;

package/dist/api.d.ts

@@ -0,0 +1,22 @@
+export { shell } from './shellRuntime.svelte';
+export type { Shell } from './shellRuntime.svelte';
+export type { Shard, ShardManifest, ShardContext, ViewDeclaration, ViewFactory, ViewHandle, MountContext, } from './shards/types';
+export type { LayoutNode, SplitNode, TabsNode, SlotNode, TabEntry, SplitDirection, SizeMode, } from './layout/types';
+export type { ZoneSchema, ZoneName } from './state/types';
+export type { StateZones } from './state/zones.svelte';
+export type { App, AppManifest, AppContext } from './apps/types';
+export { listRegisteredApps, getActiveApp } from './apps/registry.svelte';
+export { launchApp, returnToHome } from './apps/lifecycle';
+export { inspectActiveLayout, spliceIntoActiveLayout, focusTab, focusView, collapseChild, expandChild, closeTab, } from './layout/inspection';
+export type { DocumentHandle, DocumentHandleOptions, DocumentFormat, DocumentMeta, DocumentChange, AutosaveController, } from './documents/types';
+export { registeredShards, activeShards } from './shards/activate.svelte';
+export type { RegistryIndex, PackageEntry, PackageVersion, RequiredDependency, InstalledPackage, InstallResult, PackageMeta, } from './registry/types';
+export type { ResolvedPackage } from './registry/client';
+export { fetchRegistries, fetchBundle, buildPackageMeta } from './registry/client';
+export { validateRegistryIndex } from './registry/schema';
+export { isAdmin, getAuthHeader } from './auth/index';
+/** Runtime feature flags for target-dependent behavior. */
+export declare const capabilities: {
+    /** Whether this target supports hot-installing packages via dynamic import from blob URL. */
+    readonly hotInstall: boolean;
+};

package/dist/api.js

@@ -0,0 +1,45 @@
+/*
+ * Public framework API — the single import path shards and apps are
+ * allowed to touch. The phase 9 package boundary turns this file (and
+ * only this file) into the published entry point.
+ *
+ * What belongs here:
+ *   - Types that shards and apps consume (Shard, App, ShardContext, etc.)
+ *   - The `shell` runtime singleton (modal/popup/toast)
+ *   - Layout inspection/mutation helpers for advanced shards (added in
+ *     Task 12)
+ *   - Host actions callable from inside views (launchApp, returnToHome,
+ *     listRegisteredApps — added in Task 7 and Task 10)
+ *
+ * What does NOT belong here:
+ *   - `registerShard` / `registerApp` — those are host-only and live in
+ *     `host.ts`. Shards and apps must not register each other.
+ *   - Framework internals (state zone plumbing, layout manager internals,
+ *     shard activation machinery).
+ *
+ * Anything re-exported from this file is part of the public contract.
+ * Phase 10 adds a validator that enforces the import-hygiene rule; for
+ * now the convention is documented and honored by hand.
+ */
+// Runtime singleton.
+export { shell } from './shellRuntime.svelte';
+// Host actions callable from inside views (shell home, status bar, etc.).
+export { listRegisteredApps, getActiveApp } from './apps/registry.svelte';
+export { launchApp, returnToHome } from './apps/lifecycle';
+// Layout inspection / mutation for advanced shards (diagnostic, etc.).
+export { inspectActiveLayout, spliceIntoActiveLayout, focusTab, focusView, collapseChild, expandChild, closeTab, } from './layout/inspection';
+// Shard introspection — read-only reactive maps exposing which shards are
+// known to the host and which are currently active. Intended for diagnostic
+// and tooling shards that need to visualize framework state. Phase 9
+// addition: diagnostic used to reach `activate.svelte` directly via $lib;
+// the package boundary requires routing through the public surface.
+export { registeredShards, activeShards } from './shards/activate.svelte';
+export { fetchRegistries, fetchBundle, buildPackageMeta } from './registry/client';
+export { validateRegistryIndex } from './registry/schema';
+// Admin mode (framework-internal components read admin status).
+export { isAdmin, getAuthHeader } from './auth/index';
+/** Runtime feature flags for target-dependent behavior. */
+export const capabilities = {
+    /** Whether this target supports hot-installing packages via dynamic import from blob URL. */
+    hotInstall: typeof Blob !== 'undefined' && typeof URL.createObjectURL === 'function',
+};

package/dist/apps/lifecycle.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Read the id of the last-launched app from the user state zone. Used at
+ * boot to decide whether to auto-launch. Returns null if the user last
+ * returned to home or no app has ever been launched.
+ */
+export declare function readLastApp(): string | null;
+/**
+ * Launch an app by id. Activates all required shards (idempotent for
+ * already-active shards), attaches the app's layout, calls `App.activate`,
+ * and switches the rendered root to the app tree.
+ *
+ * If a different app is already active, it is unloaded first. Launching the
+ * same app that is already active is a no-op on shards — it only switches
+ * back from the home view if needed.
+ *
+ * @param id - The `AppManifest.id` of the app to launch. Must be registered.
+ * @throws If the app is not registered or a required shard is not registered.
+ */
+export declare function launchApp(id: string): Promise<void>;
+/**
+ * Unload an active app. Calls `App.deactivate`, detaches the layout, and
+ * deactivates the app's non-self-starting required shards. Switches the
+ * rendered root to home. No-op if the app is not currently active.
+ *
+ * @param id - The `AppManifest.id` of the app to unload.
+ */
+export declare function unloadApp(id: string): void;
+/**
+ * Return to the shell home view without unloading the active app. The
+ * app's shards stay running, its layout proxy stays attached with its
+ * refcount hold intact, and its view containers stay alive in the pool.
+ * Launching the same app again is a root swap only.
+ *
+ * Writes `null` to `__shell__:last-app` so reloading the page while on
+ * home lands on home, not on the formerly-active app.
+ */
+export declare function returnToHome(): void;

package/dist/apps/lifecycle.js

@@ -0,0 +1,153 @@
+/*
+ * App lifecycle — launch, unload, return-to-home.
+ *
+ * All three functions operate on the shared apps registry and the layout
+ * manager. `launchApp` is public (shell home calls it); `unloadApp` is
+ * internal (called from launchApp when replacing a different app);
+ * `returnToHome` is public (shell UI calls it).
+ *
+ * "Last active app" is persisted in the user state zone under the
+ * reserved shardId `__shell__:last-app`. The value shape is simply
+ * `{ id: string | null }`. Writing happens on launch (id) and on
+ * return-to-home (null). Boot reads it to decide whether to auto-launch.
+ */
+import { createStateZones } from '../state/zones.svelte';
+import { activateShard, deactivateShard, registeredShards, } from '../shards/activate.svelte';
+import { attachApp, detachApp, switchToApp, switchToHome, } from '../layout/store.svelte';
+import { activeApp, getRegisteredApp } from './registry.svelte';
+// ---------- last-active-app user zone ------------------------------------
+/**
+ * Framework-reserved user-zone slot storing which app to boot into on
+ * the next session. Keyed under `__shell__:last-app` to avoid collision
+ * with any real shard. Reading/writing uses the same zones machinery as
+ * any shard — nothing special.
+ */
+const lastAppState = createStateZones('__shell__:last-app', {
+    user: { id: null },
+});
+/**
+ * Read the id of the last-launched app from the user state zone. Used at
+ * boot to decide whether to auto-launch. Returns null if the user last
+ * returned to home or no app has ever been launched.
+ */
+export function readLastApp() {
+    return lastAppState.user.id;
+}
+function writeLastApp(id) {
+    lastAppState.user.id = id;
+}
+// ---------- app-context state factories ----------------------------------
+const appContexts = new Map();
+function getOrCreateAppContext(appId) {
+    let ctx = appContexts.get(appId);
+    if (!ctx) {
+        ctx = {
+            state: (schema) => createStateZones(`__app__:${appId}`, schema),
+        };
+        appContexts.set(appId, ctx);
+    }
+    return ctx;
+}
+// ---------- launch --------------------------------------------------------
+/**
+ * Launch an app by id. Activates all required shards (idempotent for
+ * already-active shards), attaches the app's layout, calls `App.activate`,
+ * and switches the rendered root to the app tree.
+ *
+ * If a different app is already active, it is unloaded first. Launching the
+ * same app that is already active is a no-op on shards — it only switches
+ * back from the home view if needed.
+ *
+ * @param id - The `AppManifest.id` of the app to launch. Must be registered.
+ * @throws If the app is not registered or a required shard is not registered.
+ */
+export async function launchApp(id) {
+    var _a;
+    const app = getRegisteredApp(id);
+    if (!app) {
+        throw new Error(`Cannot launch app "${id}": not registered`);
+    }
+    // If a different app is already active, unload it first. Relaunching
+    // the same app (while it's active) is a no-op on shards and layout;
+    // we only swap the rendered root back to 'app' in case the user was
+    // on home.
+    if (activeApp.id && activeApp.id !== id) {
+        unloadApp(activeApp.id);
+    }
+    else if (activeApp.id === id) {
+        switchToApp();
+        writeLastApp(id);
+        return;
+    }
+    // Activate every required shard. `activateShard` is idempotent for
+    // already-active shards (self-starting shards, or shards shared with
+    // a previous app that stayed resident) so this is safe to call
+    // unconditionally.
+    for (const shardId of app.manifest.requiredShards) {
+        if (!registeredShards.has(shardId)) {
+            throw new Error(`App "${id}" requires shard "${shardId}" which is not registered`);
+        }
+        await activateShard(shardId);
+    }
+    // Attach the layout (creates the workspace-zone proxy with version
+    // gate) and run the app's optional activate hook.
+    attachApp(app);
+    void ((_a = app.activate) === null || _a === void 0 ? void 0 : _a.call(app, getOrCreateAppContext(id)));
+    activeApp.id = id;
+    switchToApp();
+    writeLastApp(id);
+}
+// ---------- unload --------------------------------------------------------
+/**
+ * Unload an active app. Calls `App.deactivate`, detaches the layout, and
+ * deactivates the app's non-self-starting required shards. Switches the
+ * rendered root to home. No-op if the app is not currently active.
+ *
+ * @param id - The `AppManifest.id` of the app to unload.
+ */
+export function unloadApp(id) {
+    var _a;
+    if (activeApp.id !== id)
+        return;
+    const app = getRegisteredApp(id);
+    if (!app)
+        return;
+    void ((_a = app.deactivate) === null || _a === void 0 ? void 0 : _a.call(app));
+    // Detach layout (releases the refcount holds; pool cleanup runs on
+    // the next microtask for any slots that no longer have a renderer).
+    // Switch to home first so LayoutRenderer stops reading the app's
+    // tree before detachApp drops its references.
+    switchToHome();
+    detachApp();
+    // Deactivate this app's required shards IF no other consumer needs
+    // them. Phase 8 has at most one app active at a time, so "no other
+    // consumer" reduces to "not self-starting AND not required by any
+    // other registered app that happens to already be active" — but we
+    // don't run multiple apps, so the only survivors are self-starters.
+    // The simple rule: deactivate a required shard unless it was
+    // self-starting (has an `autostart` field defined).
+    for (const shardId of app.manifest.requiredShards) {
+        const shard = registeredShards.get(shardId);
+        if (!shard)
+            continue;
+        if (shard.autostart)
+            continue; // self-starter stays running
+        deactivateShard(shardId);
+    }
+    activeApp.id = null;
+    appContexts.delete(id);
+}
+// ---------- return to home -----------------------------------------------
+/**
+ * Return to the shell home view without unloading the active app. The
+ * app's shards stay running, its layout proxy stays attached with its
+ * refcount hold intact, and its view containers stay alive in the pool.
+ * Launching the same app again is a root swap only.
+ *
+ * Writes `null` to `__shell__:last-app` so reloading the page while on
+ * home lands on home, not on the formerly-active app.
+ */
+export function returnToHome() {
+    switchToHome();
+    writeLastApp(null);
+}

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

@@ -0,0 +1,37 @@
+import type { App, AppManifest } from './types';
+/**
+ * Reactive map of all registered apps keyed by `AppManifest.id`. Populated
+ * once at boot by the host's glob-discovery loop via `registerApp`. A future
+ * runtime loader may append entries at runtime.
+ */
+export declare const registeredApps: Map<string, App>;
+/**
+ * Reactive slot tracking the currently-active app id. Null when the shell is
+ * showing the home screen or no app has been launched yet. Phase 8 allows at
+ * most one active app at a time.
+ */
+export declare const activeApp: {
+    id: string | null;
+};
+/**
+ * Register an app with the framework. Must be called before `launchApp`.
+ * Throws if an app with the same id is already registered.
+ *
+ * @param app - The app module to register.
+ */
+export declare function registerApp(app: App): void;
+/**
+ * Reactive snapshot of all registered app manifests. Shell home iterates
+ * this to populate its launcher list. Returns only manifests so callers
+ * don't reach into app bodies (initialLayout, activate hook) — those are
+ * launch-time concerns.
+ */
+export declare function listRegisteredApps(): AppManifest[];
+/** Reactive current-app manifest (or null when none is active). */
+export declare function getActiveApp(): AppManifest | null;
+/**
+ * Lookup for framework-internal use — returns the full App (not just the
+ * manifest) so lifecycle code can reach into `initialLayout` and the
+ * activate hook. Not re-exported through `api.ts`.
+ */
+export declare function getRegisteredApp(id: string): App | undefined;

package/dist/apps/registry.svelte.js

@@ -0,0 +1,60 @@
+/*
+ * App registry — reactive record of every registered app, plus the
+ * single slot for the currently-active app.
+ *
+ * Registration is called from the host (main.ts glob loop or a future
+ * runtime loader). The shell home view reads `listRegisteredApps()`
+ * reactively so newly-registered apps appear in the list without
+ * reboot. `activeApp` tracks which app (if any) is currently launched;
+ * phase 8 allows at most one.
+ */
+/**
+ * Reactive map of all registered apps keyed by `AppManifest.id`. Populated
+ * once at boot by the host's glob-discovery loop via `registerApp`. A future
+ * runtime loader may append entries at runtime.
+ */
+export const registeredApps = $state(new Map());
+/**
+ * Reactive slot tracking the currently-active app id. Null when the shell is
+ * showing the home screen or no app has been launched yet. Phase 8 allows at
+ * most one active app at a time.
+ */
+export const activeApp = $state({ id: null });
+/**
+ * Register an app with the framework. Must be called before `launchApp`.
+ * Throws if an app with the same id is already registered.
+ *
+ * @param app - The app module to register.
+ */
+export function registerApp(app) {
+    const id = app.manifest.id;
+    if (registeredApps.has(id)) {
+        throw new Error(`App "${id}" is already registered`);
+    }
+    registeredApps.set(id, app);
+}
+/**
+ * Reactive snapshot of all registered app manifests. Shell home iterates
+ * this to populate its launcher list. Returns only manifests so callers
+ * don't reach into app bodies (initialLayout, activate hook) — those are
+ * launch-time concerns.
+ */
+export function listRegisteredApps() {
+    return Array.from(registeredApps.values()).map((a) => a.manifest);
+}
+/** Reactive current-app manifest (or null when none is active). */
+export function getActiveApp() {
+    var _a, _b;
+    const id = activeApp.id;
+    if (!id)
+        return null;
+    return (_b = (_a = registeredApps.get(id)) === null || _a === void 0 ? void 0 : _a.manifest) !== null && _b !== void 0 ? _b : null;
+}
+/**
+ * Lookup for framework-internal use — returns the full App (not just the
+ * manifest) so lifecycle code can reach into `initialLayout` and the
+ * activate hook. Not re-exported through `api.ts`.
+ */
+export function getRegisteredApp(id) {
+    return registeredApps.get(id);
+}

package/dist/apps/types.d.ts

@@ -0,0 +1,61 @@
+import type { LayoutNode } from '../layout/types';
+import type { ZoneSchema } from '../state/types';
+import type { StateZones } from '../state/zones.svelte';
+/**
+ * Static description of an app. Declared by every app module and read by
+ * the shell launcher to populate the home screen list without running any
+ * activation code.
+ */
+export interface AppManifest {
+    /** Unique app identifier. Must match the app's registration key. */
+    id: string;
+    /** Human-readable display name shown in the launcher. */
+    label: string;
+    /** Semver string for the app package. */
+    version: string;
+    /**
+     * Shard ids this app requires. All required shards are activated at
+     * launch time (skipping any already-active from a previous launch or
+     * from self-starting). Deactivation at unload deactivates only the
+     * shards this app is the last consumer of; shared shards and self-
+     * starting shards (diagnostic, __shell__) stay running.
+     */
+    requiredShards: string[];
+    /**
+     * Bump to invalidate persisted layouts. On launch, a persisted blob
+     * whose version doesn't match this is discarded and `initialLayout`
+     * is used instead. Phase 8 does not migrate — version bumps reset
+     * user customization.
+     */
+    layoutVersion: number;
+}
+/**
+ * Context object passed to `App.activate`. Provides app-scoped state zones
+ * that are namespaced to the app id, preventing collision with any shard
+ * that happens to share the same name.
+ */
+export interface AppContext {
+    /**
+     * App-scoped state zones. The shardId underneath is the app id, so
+     * `state({ workspace: { x: 0 } }).workspace.x = 1` persists to
+     * `sh3:workspace:<appId>` with no collision risk against any shard
+     * of the same name.
+     */
+    state<T extends ZoneSchema>(schema: T): StateZones<T>;
+}
+/**
+ * An app module. An app is a composition document — it declares required
+ * shards and an initial layout blueprint, but does not register views or
+ * commands itself. The framework activates the required shards on launch,
+ * restores or applies the initial layout, and calls the optional hooks.
+ */
+export interface App {
+    /** Static manifest describing the app and its requirements. */
+    manifest: AppManifest;
+    /** Starting layout tree. Used on first launch or when the persisted layout version mismatches. */
+    initialLayout: LayoutNode;
+    /** Optional hook called after all required shards are active and the layout is attached. */
+    activate?(ctx: AppContext): void | Promise<void>;
+    /** Optional hook called before the app's shards are deactivated and the layout is detached. */
+    deactivate?(): void | Promise<void>;
+}

package/dist/apps/types.js

@@ -0,0 +1,10 @@
+/*
+ * App contract — phase 8.
+ *
+ * An app is a composition document. It declares what shards it needs
+ * and what layout to start with, plus an optional activate hook for
+ * app-internal startup work. Apps are NOT shards — they do not register
+ * contributions, do not have their own views, and do not contribute to
+ * other apps' layouts. They compose existing shard views.
+ */
+export {};