@timurproko/a1 0.1.0 → 0.1.1-dev.10

package/dist/src/foundation/supervision/server.js

@@ -2,35 +2,55 @@ import { randomUUID } from "node:crypto";
 import { mkdir, rename, rm, writeFile } from "node:fs/promises";
 import { createConnection, createServer } from "node:net";
 import { platform } from "node:os";
-import { assertNativeProcessIdentity, assertTransparentTerminalLaunchProfile, } from "../lifecycle/index.js";
+import { assertLaunchInstanceOutcome, assertNativeProcessIdentity, assertProcessContainmentIdentity, } from "../lifecycle/index.js";
 import { encodeFrame, isCommandMessage, isControlHello, LineFrameDecoder, localControlHello, MAX_CONTROL_FRAME_BYTES, negotiateControlFeatures } from "../protocol/index.js";
+import { processIsAlive } from "../release/index.js";
 import { ControlStore } from "../storage/index.js";
-import { resolveAddOnePaths } from "./paths.js";
+import { resolveProductPaths } from "./paths.js";
+import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
 export class SupervisorServer {
     store;
     release;
     terminateProcess;
+    reconciliationDeadlineMs;
+    shutdownDeadlineMs;
     id = randomUUID();
     bootNonce;
     pidStartIdentity = `${process.pid}:${Math.floor(Date.now() - process.uptime() * 1_000)}`;
     startedAt = new Date().toISOString();
     paths;
     #server = null;
-    #foregroundLease;
+    #instances = new Map();
+    #instanceOwners = new Map();
+    #clientIds = new Map();
+    #clientInstances = new Map();
+    #uncertainInstances = new Set();
+    #reconciliations = new Map();
     #revision = 0;
     #clients = new Set();
     #results = new Map();
     #metadataWrites = Promise.resolve();
-    constructor(store, paths = resolveAddOnePaths(), release, bootNonce = randomUUID(), terminateProcess = code => process.exit(code)) {
+    #closing = false;
+    constructor(store, paths = resolveProductPaths(), release, bootNonce = randomUUID(), terminateProcess = code => process.exit(code), reconciliationDeadlineMs = 3_000, shutdownDeadlineMs = 1_500) {
         this.store = store;
         this.release = release;
         this.terminateProcess = terminateProcess;
+        this.reconciliationDeadlineMs = reconciliationDeadlineMs;
+        this.shutdownDeadlineMs = shutdownDeadlineMs;
         this.bootNonce = bootNonce;
         this.paths = paths;
-        this.#foregroundLease = store.loadLiveForegroundTerminalLease();
+        for (const instance of store.loadActiveLaunchInstances())
+            this.#instances.set(instance.id, instance);
     }
     snapshot() {
-        return { revision: this.#revision };
+        return {
+            revision: this.#revision,
+            activeInstances: [...this.#instances.values()].flatMap(instance => {
+                if (instance.state !== "requested" && instance.state !== "active" && instance.state !== "stopping")
+                    return [];
+                return [{ id: instance.id, profileId: instance.profileId, state: instance.state }];
+            }),
+        };
     }
     async listen() {
         if (this.#server)
@@ -38,7 +58,7 @@ export class SupervisorServer {
         await mkdir(this.paths.runtimeDir, { recursive: true, mode: 0o700 });
         if (platform() !== "win32") {
             if (await endpointIsLive(this.paths.endpoint))
-                throw new Error(`an AddOne supervisor already owns ${this.paths.endpoint}`);
+                throw new Error(PRODUCT_TEXT.diagnostic(`supervisor already owns ${this.paths.endpoint}`));
             await rm(this.paths.endpoint, { force: true });
         }
         const server = createServer(socket => this.#attach(socket));
@@ -53,8 +73,10 @@ export class SupervisorServer {
         await this.#writeEndpointMetadata();
     }
     async close(stopAgents = false) {
-        if (stopAgents && this.#foregroundLease)
-            this.#releaseForegroundLeaseForUpdate();
+        if (stopAgents && !await this.#drainInstances("update", this.shutdownDeadlineMs)) {
+            throw new Error("active launch instances did not release ownership within the shutdown deadline");
+        }
+        this.#closing = true;
         for (const client of this.#clients)
             client.destroy();
         if (this.#server)
@@ -85,13 +107,13 @@ export class SupervisorServer {
                         if (isMessageType(value, "release-idle-ownership")) {
                             const request = value;
                             const identityMatches = request.bootNonce === this.bootNonce && typeof request.candidateReleaseId === "string";
-                            const released = identityMatches && this.#foregroundLease === null;
+                            const released = identityMatches && this.#instances.size === 0;
                             this.#send(socket, {
                                 type: "release-ownership-result",
                                 released,
                                 reason: released ? "idle cohort released ownership"
-                                    : identityMatches ? "foreground terminal lease is still live" : "boot nonce or candidate release mismatch",
-                                liveGenerationIds: this.#liveGenerationIds(),
+                                    : identityMatches ? "launch instances are still active" : "boot nonce or candidate release mismatch",
+                                liveInstanceIds: this.#liveInstanceIds(),
                             });
                             if (released)
                                 setTimeout(() => void this.closeForReleaseReplacement(false), 25);
@@ -99,19 +121,11 @@ export class SupervisorServer {
                         }
                         if (isMessageType(value, "release-update-ownership")) {
                             const request = value;
-                            const accepted = request.bootNonce === this.bootNonce && typeof request.targetVersion === "string";
-                            this.#send(socket, {
-                                type: "release-update-result",
-                                accepted,
-                                reason: accepted ? "verified AddOne owner accepted immediate update shutdown" : "boot nonce or target version mismatch",
-                                liveGenerationIds: this.#liveGenerationIds(),
-                            });
-                            if (accepted)
-                                setTimeout(() => void this.closeForReleaseReplacement(true), 25);
+                            void this.#handleUpdateRelease(socket, request);
                             continue;
                         }
                         if (!isControlHello(value)) {
-                            this.#send(socket, { type: "protocol-error", code: "invalid-control-handshake", message: "the first message must be a valid AddOne control feature handshake", diagnostics: { received: value } });
+                            this.#send(socket, { type: "protocol-error", code: "invalid-control-handshake", message: `the first message must be a valid ${PRODUCT_TEXT.displayName} control feature handshake`, diagnostics: { received: value } });
                             socket.destroy();
                             return;
                         }
@@ -124,6 +138,8 @@ export class SupervisorServer {
                         }
                         welcomed = true;
                         this.#clients.add(socket);
+                        this.#clientIds.set(socket, value.clientId);
+                        this.#clientInstances.set(socket, new Set());
                         this.#send(socket, { type: "server-hello", ...serverHello, releaseId: this.release.releaseId, supervisorId: this.id, bootNonce: this.bootNonce, pidStartIdentity: this.pidStartIdentity, negotiatedFeatures: negotiation.negotiatedFeatures, snapshot: this.snapshot() });
                     }
                     else if (isCommandMessage(value)) {
@@ -136,25 +152,35 @@ export class SupervisorServer {
                 socket.destroy();
             }
         });
-        socket.on("close", () => this.#clients.delete(socket));
-        socket.on("error", () => this.#clients.delete(socket));
+        socket.on("close", () => this.#onSocketClosed(socket));
+        socket.on("error", () => this.#onSocketClosed(socket));
     }
     async #execute(command, socket) {
-        const recorded = this.#results.get(command.requestId);
+        const clientId = this.#clientIds.get(socket);
+        if (!clientId) {
+            this.#send(socket, { type: "protocol-error", code: "unauthenticated-command", message: "launch-instance commands require an authenticated client" });
+            return;
+        }
+        const resultKey = `${clientId}:${command.requestId}`;
+        const recorded = this.#results.get(resultKey);
         if (recorded) {
             this.#send(socket, { type: "command-result", result: recorded });
             return;
         }
         let result;
         try {
-            if (command.type === "acquire-foreground-terminal-lease")
-                this.#acquireForegroundLease(command);
-            if (command.type === "activate-foreground-terminal-lease")
-                this.#activateForegroundLease(command);
-            if (command.type === "heartbeat-foreground-terminal-lease")
-                this.#heartbeatForegroundLease(command);
-            if (command.type === "release-foreground-terminal-lease")
-                this.#releaseForegroundLease(command);
+            if (command.type === "create-launch-instance")
+                this.#createLaunchInstance(command, socket, clientId);
+            if (command.type === "activate-launch-instance")
+                this.#activateLaunchInstance(command, socket, clientId);
+            if (command.type === "begin-launch-instance-stop")
+                this.#beginLaunchInstanceStop(command, socket, clientId);
+            if (command.type === "complete-launch-instance")
+                this.#completeLaunchInstance(command, socket, clientId);
+            if (command.type === "reconcile-launch-instance") {
+                this.#ownedInstance(command.instanceId, socket, clientId);
+                await this.#reconcileLaunchInstance(command.instanceId);
+            }
             if (command.type === "resynchronize")
                 this.#send(socket, { type: "snapshot", snapshot: this.snapshot() });
             await this.#metadataWrites;
@@ -162,76 +188,212 @@ export class SupervisorServer {
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
-            const code = /not found/i.test(message) ? "not-found" : "driver-error";
+            const code = /not found/i.test(message) ? "not-found" : /owner|ownership|authenticated/i.test(message) ? "ownership-error" : "driver-error";
             result = { requestId: command.requestId, ok: false, revision: this.#revision, error: { code, message } };
         }
-        this.#results.set(command.requestId, result);
+        this.#results.set(resultKey, result);
         this.#send(socket, { type: "command-result", result });
     }
-    #acquireForegroundLease(command) {
-        if (!command.leaseId || !command.ownerId)
-            throw new Error("foreground lease and owner identities are required");
-        assertTransparentTerminalLaunchProfile(command.profile);
-        const lease = {
-            id: command.leaseId,
-            ownerId: command.ownerId,
-            profile: command.profile,
+    #createLaunchInstance(command, socket, clientId) {
+        assertNativeProcessIdentity(command.guardianIdentity);
+        const existing = this.store.loadLaunchInstance(command.instanceId);
+        if (existing) {
+            if (existing.ownerClientId !== clientId
+                || existing.profileId !== command.profileId
+                || existing.shutdownPolicy !== command.shutdownPolicy
+                || !sameProcessIdentity(existing.guardianIdentity, command.guardianIdentity)) {
+                throw new Error("launch instance already exists with different authenticated ownership");
+            }
+            if (existing.state === "completed" || existing.state === "interrupted")
+                throw new Error("launch instance already has a terminal outcome");
+            this.#instances.set(existing.id, existing);
+            this.#bindOwner(existing.id, socket);
+            return;
+        }
+        const instance = {
+            id: command.instanceId,
+            ownerClientId: clientId,
+            profileId: command.profileId,
             state: "requested",
-            generationId: null,
-            processIdentity: null,
-            acquiredAt: new Date().toISOString(),
-            heartbeatAt: null,
-            releasedAt: null,
+            shutdownPolicy: command.shutdownPolicy,
+            guardianIdentity: command.guardianIdentity,
+            rootIdentity: null,
+            containmentIdentity: null,
+            createdAt: new Date().toISOString(),
+            activatedAt: null,
+            stoppingAt: null,
+            completedAt: null,
             outcome: null,
         };
-        this.store.acquireForegroundTerminalLease(lease);
-        this.#foregroundLease = lease;
-        void this.#writeEndpointMetadata();
+        this.store.createLaunchInstance(instance);
+        this.#instances.set(instance.id, instance);
+        this.#bindOwner(instance.id, socket);
+        this.#mutated();
     }
-    #activateForegroundLease(command) {
-        assertNativeProcessIdentity(command.processIdentity);
-        if (!this.#foregroundLease || this.#foregroundLease.id !== command.leaseId || this.#foregroundLease.state !== "requested")
-            throw new Error("foreground terminal lease not found or is not requested");
-        const heartbeatAt = new Date().toISOString();
-        if (!this.store.activateForegroundTerminalLease(command.leaseId, command.generationId, command.processIdentity, heartbeatAt))
-            throw new Error("foreground terminal lease activation was rejected");
-        this.#foregroundLease = { ...this.#foregroundLease, state: "active", generationId: command.generationId, processIdentity: command.processIdentity, heartbeatAt };
-        void this.#writeEndpointMetadata();
+    #activateLaunchInstance(command, socket, clientId) {
+        assertNativeProcessIdentity(command.rootIdentity);
+        assertProcessContainmentIdentity(command.containmentIdentity);
+        const instance = this.#ownedInstance(command.instanceId, socket, clientId);
+        if (instance.state === "active"
+            && sameProcessIdentity(instance.rootIdentity, command.rootIdentity)
+            && sameContainmentIdentity(instance.containmentIdentity, command.containmentIdentity))
+            return;
+        if (instance.state !== "requested")
+            throw new Error("launch instance is not requested");
+        const activatedAt = new Date().toISOString();
+        if (!this.store.activateLaunchInstance(instance.id, clientId, command.rootIdentity, command.containmentIdentity, activatedAt)) {
+            throw new Error("launch instance activation ownership mismatch");
+        }
+        this.#instances.set(instance.id, { ...instance, state: "active", rootIdentity: command.rootIdentity, containmentIdentity: command.containmentIdentity, activatedAt });
+        this.#mutated();
     }
-    #heartbeatForegroundLease(command) {
-        assertNativeProcessIdentity(command.processIdentity);
-        if (!this.#foregroundLease || this.#foregroundLease.id !== command.leaseId || this.#foregroundLease.state !== "active")
-            throw new Error("active foreground terminal lease not found");
-        const heartbeatAt = new Date().toISOString();
-        if (!this.store.heartbeatForegroundTerminalLease(command.leaseId, command.processIdentity, heartbeatAt))
-            throw new Error("foreground terminal lease ownership mismatch");
-        this.#foregroundLease = { ...this.#foregroundLease, heartbeatAt };
+    #beginLaunchInstanceStop(command, socket, clientId) {
+        const instance = this.#ownedInstance(command.instanceId, socket, clientId);
+        if (instance.state === "stopping")
+            return;
+        if (instance.state !== "active")
+            throw new Error("active launch instance not found");
+        const stoppingAt = new Date().toISOString();
+        if (!this.store.beginLaunchInstanceStop(instance.id, clientId, stoppingAt))
+            throw new Error("launch instance stop ownership mismatch");
+        this.#instances.set(instance.id, { ...instance, state: "stopping", stoppingAt });
+        this.#mutated();
     }
-    #releaseForegroundLease(command) {
-        if (command.processIdentity)
-            assertNativeProcessIdentity(command.processIdentity);
-        if (!this.#foregroundLease || this.#foregroundLease.id !== command.leaseId)
-            throw new Error("foreground terminal lease not found");
-        const releasedAt = new Date().toISOString();
-        if (!this.store.releaseForegroundTerminalLease(command.leaseId, command.processIdentity, command.outcome, releasedAt))
-            throw new Error("foreground terminal lease ownership mismatch");
-        this.#foregroundLease = null;
-        void this.#writeEndpointMetadata();
+    #completeLaunchInstance(command, socket, clientId) {
+        assertLaunchInstanceOutcome(command.outcome);
+        const stored = this.store.loadLaunchInstance(command.instanceId);
+        if (!stored)
+            throw new Error("launch instance not found");
+        if (stored.ownerClientId !== clientId || this.#instanceOwners.get(stored.id) !== socket)
+            throw new Error("launch instance ownership mismatch");
+        if (stored.state === "completed" || stored.state === "interrupted") {
+            if (stored.state === command.terminalState && JSON.stringify(stored.outcome) === JSON.stringify(command.outcome))
+                return;
+            throw new Error("launch instance already has a different terminal outcome");
+        }
+        const completedAt = new Date().toISOString();
+        if (!this.store.completeLaunchInstance(stored.id, clientId, command.terminalState, command.outcome, completedAt)) {
+            throw new Error("launch instance completion ownership mismatch");
+        }
+        this.#instances.delete(stored.id);
+        this.#uncertainInstances.delete(stored.id);
+        this.#unbindOwner(stored.id, socket);
+        this.#mutated();
+    }
+    #ownedInstance(instanceId, socket, clientId) {
+        const instance = this.#instances.get(instanceId) ?? this.store.loadLaunchInstance(instanceId);
+        if (!instance || instance.state === "completed" || instance.state === "interrupted")
+            throw new Error("active launch instance not found");
+        if (instance.ownerClientId !== clientId || this.#instanceOwners.get(instanceId) !== socket)
+            throw new Error("launch instance ownership mismatch");
+        return instance;
+    }
+    #bindOwner(instanceId, socket) {
+        const current = this.#instanceOwners.get(instanceId);
+        if (current && current !== socket)
+            throw new Error("launch instance already belongs to another authenticated connection");
+        this.#instanceOwners.set(instanceId, socket);
+        this.#clientInstances.get(socket)?.add(instanceId);
+    }
+    #unbindOwner(instanceId, socket) {
+        this.#instanceOwners.delete(instanceId);
+        this.#clientInstances.get(socket)?.delete(instanceId);
+    }
+    #onSocketClosed(socket) {
+        if (!this.#clients.delete(socket) && !this.#clientIds.has(socket))
+            return;
+        const instanceIds = [...(this.#clientInstances.get(socket) ?? [])];
+        this.#clientInstances.delete(socket);
+        this.#clientIds.delete(socket);
+        for (const instanceId of instanceIds) {
+            if (this.#instanceOwners.get(instanceId) === socket)
+                this.#instanceOwners.delete(instanceId);
+            if (!this.#closing)
+                void this.#reconcileLaunchInstance(instanceId);
+        }
+    }
+    #reconcileLaunchInstance(instanceId) {
+        const existing = this.#reconciliations.get(instanceId);
+        if (existing)
+            return existing;
+        const reconciliation = this.#performReconciliation(instanceId).finally(() => this.#reconciliations.delete(instanceId));
+        this.#reconciliations.set(instanceId, reconciliation);
+        return reconciliation;
     }
-    #releaseForegroundLeaseForUpdate() {
-        const lease = this.#foregroundLease;
-        if (!lease)
+    async #performReconciliation(instanceId) {
+        const instance = this.#instances.get(instanceId);
+        if (!instance)
+            return;
+        const deadline = Date.now() + this.reconciliationDeadlineMs;
+        while (instance.rootIdentity && processIsAlive(instance.rootIdentity.pid) && Date.now() < deadline) {
+            await new Promise(resolvePromise => setTimeout(resolvePromise, 25));
+        }
+        if (instance.state === "requested" || (instance.rootIdentity && !processIsAlive(instance.rootIdentity.pid))) {
+            const outcome = { kind: "interrupted", reason: "owner-disconnect", message: "launch instance owner disconnected before reporting a terminal outcome" };
+            if (this.store.completeLaunchInstance(instance.id, instance.ownerClientId, "interrupted", outcome, new Date().toISOString())) {
+                this.#instances.delete(instance.id);
+                this.#uncertainInstances.delete(instance.id);
+                this.#mutated();
+            }
+            return;
+        }
+        this.#uncertainInstances.add(instance.id);
+        await this.#writeEndpointMetadata();
+    }
+    async #handleUpdateRelease(socket, request) {
+        const identityMatches = request.bootNonce === this.bootNonce && typeof request.targetVersion === "string";
+        if (!identityMatches) {
+            this.#send(socket, {
+                type: "release-update-result",
+                accepted: false,
+                reason: "boot nonce or target version mismatch",
+                liveInstanceIds: this.#liveInstanceIds(),
+            });
             return;
-        const outcome = { kind: "stopped", reason: "update" };
-        if (!this.store.releaseForegroundTerminalLease(lease.id, lease.processIdentity, outcome, new Date().toISOString()))
-            throw new Error("foreground terminal lease update shutdown was rejected");
-        this.#foregroundLease = null;
+        }
+        const released = await this.#drainInstances("update", this.shutdownDeadlineMs);
+        this.#send(socket, {
+            type: "release-update-result",
+            accepted: released,
+            reason: released
+                ? `verified ${PRODUCT_TEXT.displayName} owner drained all launch instances for immediate update shutdown`
+                : "one or more launch instances did not release verified ownership within the update deadline",
+            liveInstanceIds: this.#liveInstanceIds(),
+        });
+        if (released)
+            setTimeout(() => void this.closeForReleaseReplacement(false), 25);
+    }
+    async #drainInstances(reason, timeoutMs) {
+        if (this.#instances.size === 0)
+            return true;
+        this.#requestStopAll(reason);
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            if (this.#instances.size === 0) {
+                // Let the terminal command result flush before closing owner sockets.
+                await new Promise(resolvePromise => setTimeout(resolvePromise, 25));
+                return this.#instances.size === 0;
+            }
+            await new Promise(resolvePromise => setTimeout(resolvePromise, 25));
+        }
+        return this.#instances.size === 0;
     }
-    #liveGenerationIds() {
-        return this.#foregroundLease?.generationId ? [this.#foregroundLease.generationId] : [];
+    #requestStopAll(reason) {
+        for (const [instanceId, socket] of this.#instanceOwners) {
+            this.#send(socket, { type: "stop-launch-instance", requestId: randomUUID(), instanceId, reason });
+        }
+    }
+    #mutated() {
+        this.#revision += 1;
+        void this.#writeEndpointMetadata();
+    }
+    #liveInstanceIds() {
+        return [...this.#instances.keys()];
     }
     #writeEndpointMetadata() {
+        const liveInstanceIds = this.#liveInstanceIds();
         const metadata = {
+            schema: PRODUCT_IDENTITY.protocol.supervisorSchema,
             ...localControlHello(this.release.releaseId),
             supervisorId: this.id,
             pid: process.pid,
@@ -244,9 +406,10 @@ export class SupervisorServer {
             releaseRoot: this.release.releaseRoot,
             contentDigest: this.release.contentDigest,
             ownership: {
-                state: this.#foregroundLease ? "busy" : "idle",
-                liveGenerationIds: this.#liveGenerationIds(),
-                nonResumableGenerationIds: this.#liveGenerationIds(),
+                state: this.#uncertainInstances.size > 0 ? "blocked" : liveInstanceIds.length > 0 ? "busy" : "idle",
+                liveInstanceIds,
+                nonResumableInstanceIds: liveInstanceIds,
+                uncertainInstanceIds: [...this.#uncertainInstances],
             },
         };
         const temporary = `${this.paths.endpointMetadataPath}.${process.pid}.tmp`;
@@ -268,6 +431,12 @@ export class SupervisorServer {
         socket.write(frame);
     }
 }
+function sameProcessIdentity(left, right) {
+    return left !== null && left.pid === right.pid && left.startIdentity === right.startIdentity;
+}
+function sameContainmentIdentity(left, right) {
+    return left !== null && left.provider === right.provider && left.token === right.token;
+}
 function isMessageType(value, type) {
     return typeof value === "object" && value !== null && "type" in value && value.type === type;
 }
@@ -280,4 +449,3 @@ async function endpointIsLive(endpoint) {
         setTimeout(() => done(false), 250).unref();
     });
 }
-//# sourceMappingURL=server.js.map

package/dist/src/foundation/ui-apps/contracts.d.ts

@@ -0,0 +1,42 @@
+import type { PaneInputResult, PaneMouseEvent, PaneRect, UiTheme } from "../ui-components/index.js";
+export interface AppSize {
+    readonly width: number;
+    readonly height: number;
+}
+/**
+ * What a host offers a presented app. An app reaches the terminal, the pinned
+ * shell, or another app only through these — never around them.
+ */
+export interface AppHostServices {
+    getSize(): AppSize;
+    requestRender(): void;
+    close(): void;
+    /** Restores the surface that opened this app without closing the host. */
+    returnToPrevious(): void;
+    /** Leaves A1 entirely, as the interrupt chord does from any screen. */
+    exit(): void;
+    /** True once one interrupt has been seen and the chord is waiting for the second. */
+    readonly interruptArmed: boolean;
+    /**
+     * Whether an idle interrupt closes the presented app. Every host chooses
+     * explicitly: a standalone screen closes, a persistent host stays open.
+     */
+    readonly closeOnInterrupt: boolean;
+    /** Colours for the presented app. Absent renders plain text. */
+    readonly theme?: UiTheme;
+}
+export interface UiApp {
+    readonly id: string;
+    render(rect: PaneRect, host: AppHostServices): readonly string[];
+    onInput?(data: string, host: AppHostServices): PaneInputResult;
+    onMouse?(event: PaneMouseEvent, host: AppHostServices): PaneInputResult;
+    onActivate?(host: AppHostServices): void;
+    onClose?(host: AppHostServices): void;
+}
+export interface AppRegistration {
+    readonly id: string;
+    /** Route that opens the app, without its leading slash. */
+    readonly route: string;
+    create(): UiApp;
+}
+export declare function assertAppRegistration(registration: AppRegistration): void;

package/dist/src/foundation/ui-apps/contracts.js

@@ -0,0 +1,12 @@
+const ID_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
+export function assertAppRegistration(registration) {
+    if (!ID_PATTERN.test(registration.id)) {
+        throw new Error(`owned UI app id is not a bounded slug: ${registration.id}`);
+    }
+    if (!ID_PATTERN.test(registration.route)) {
+        throw new Error(`owned UI app ${registration.id} has an invalid route: ${registration.route}`);
+    }
+    if (typeof registration.create !== "function") {
+        throw new TypeError(`owned UI app ${registration.id} has no create()`);
+    }
+}

package/dist/src/foundation/ui-apps/host.d.ts

@@ -0,0 +1,42 @@
+import { type PaneInputResult, type PaneMouseEvent, type UiTheme } from "../ui-components/index.js";
+import type { AppSize, UiApp } from "./contracts.js";
+import type { UiAppRegistry } from "./registry.js";
+export interface AppHostSurface {
+    /** Current viewport, re-read on every frame so a resize is picked up. */
+    size(): AppSize;
+    /** Asks the surrounding runtime to repaint. */
+    requestRender(): void;
+    /** Presents these rows, or clears the surface when null. */
+    present(lines: readonly string[] | null): void;
+    /** Reports a failure that closed an app. */
+    reportFailure?(appId: string, error: unknown): void;
+    /** Leaves A1 entirely. Invoked by the interrupt chord from a presented app. */
+    exit?(): void;
+}
+export interface AppHostOptions {
+    readonly registry: UiAppRegistry;
+    readonly surface: AppHostSurface;
+    /** Whether an idle interrupt closes the presented app. Chosen explicitly. */
+    readonly closeOnInterrupt: boolean;
+    /** Colours handed to every presented app. Absent renders plain text. */
+    readonly theme?: UiTheme;
+}
+/**
+ * Presents at most one app. Input reaches the presented app first; anything it
+ * does not consume continues to the caller. A failure while rendering or
+ * handling input closes the app rather than leaving a broken surface on screen.
+ */
+export declare class UiAppHost {
+    #private;
+    constructor(options: AppHostOptions);
+    get presented(): UiApp | null;
+    get isPresenting(): boolean;
+    /** Opens a registered app, replacing whatever was presented. */
+    open(id: string): void;
+    openRoute(route: string): boolean;
+    render(): void;
+    handleInput(data: string): PaneInputResult;
+    handleMouse(event: PaneMouseEvent): PaneInputResult;
+    get interruptArmed(): boolean;
+    close(): void;
+}