@aigne/afs-ui 1.11.0-beta.12

package/dist/degradation.mjs

@@ -0,0 +1,84 @@
+//#region src/degradation.ts
+/**
+* Each entry maps a primitive type to its ordered degradation chain.
+* The chain is tried left-to-right; the first supported type wins.
+* "unsupported" means no meaningful fallback exists.
+*/
+const DEGRADATION_CHAINS = {
+	globe: [
+		"map",
+		"media",
+		"text"
+	],
+	chart: ["table", "text"],
+	map: ["media", "text"],
+	editor: ["input", "text"],
+	terminal: ["text"],
+	canvas: ["media", "text"],
+	rtc: ["unsupported"],
+	calendar: ["table", "text"],
+	time: ["text"],
+	overlay: ["text"]
+};
+/**
+* Walk the AUP tree and degrade unsupported primitives.
+* Returns a new tree (does not mutate the original).
+*/
+function degradeTree(node, caps) {
+	return degradeNode(node, caps);
+}
+function isSupported(primitiveType, caps) {
+	const cap = caps.primitives[primitiveType];
+	return cap === "native" || cap === "webview" || cap === "partial";
+}
+function degradeNode(node, caps) {
+	let result = degradeNodeType(node, caps);
+	if (result.children && result.children.length > 0) {
+		const degradedChildren = result.children.map((child) => degradeNode(child, caps));
+		if (degradedChildren.some((c, i) => c !== result.children[i])) result = {
+			...result,
+			children: degradedChildren
+		};
+	}
+	return result;
+}
+function degradeNodeType(node, caps) {
+	const nodeType = node.type;
+	if (isSupported(nodeType, caps)) return node;
+	const chain = DEGRADATION_CHAINS[nodeType];
+	if (!chain) return node;
+	const originalType = nodeType;
+	for (const fallbackType of chain) {
+		if (fallbackType === "unsupported") return {
+			...node,
+			type: "text",
+			props: {
+				...node.props,
+				_degradedFrom: originalType,
+				_unsupported: true,
+				content: node.props?.content ?? `[${originalType}: unsupported on this device]`
+			}
+		};
+		if (isSupported(fallbackType, caps)) return {
+			...node,
+			type: fallbackType,
+			props: {
+				...node.props,
+				_degradedFrom: originalType
+			}
+		};
+	}
+	return {
+		...node,
+		type: "text",
+		props: {
+			...node.props,
+			_degradedFrom: originalType,
+			content: node.props?.content ?? `[${originalType}: degraded to text]`
+		}
+	};
+}
+
+//#endregion
+export { DEGRADATION_CHAINS, degradeTree };
+//# sourceMappingURL=degradation.mjs.map

package/dist/degradation.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"degradation.mjs","names":[],"sources":["../src/degradation.ts"],"sourcesContent":["/**\n * AUP Degradation Transformer (D14)\n *\n * Walks an AUP node tree and degrades unsupported primitives\n * according to protocol-defined degradation chains.\n * Annotates degraded nodes with `_degradedFrom` in props.\n */\n\nimport type { AUPNode, DeviceCaps, PrimitiveCap } from \"./aup-types.js\";\n\n// ── Degradation Chain Registry ──\n\n/**\n * Each entry maps a primitive type to its ordered degradation chain.\n * The chain is tried left-to-right; the first supported type wins.\n * \"unsupported\" means no meaningful fallback exists.\n */\nexport const DEGRADATION_CHAINS: Record<string, string[]> = {\n  globe: [\"map\", \"media\", \"text\"],\n  chart: [\"table\", \"text\"],\n  map: [\"media\", \"text\"],\n  editor: [\"input\", \"text\"],\n  terminal: [\"text\"],\n  canvas: [\"media\", \"text\"],\n  rtc: [\"unsupported\"],\n  calendar: [\"table\", \"text\"],\n  time: [\"text\"],\n  overlay: [\"text\"],\n  // media(video) handled via subtype check in degradeNode\n};\n\n// ── Core API ──\n\n/**\n * Walk the AUP tree and degrade unsupported primitives.\n * Returns a new tree (does not mutate the original).\n */\nexport function degradeTree(node: AUPNode, caps: DeviceCaps): AUPNode {\n  return degradeNode(node, caps);\n}\n\n// ── Internal ──\n\nfunction isSupported(primitiveType: string, caps: DeviceCaps): boolean {\n  const cap: PrimitiveCap | undefined = caps.primitives[primitiveType];\n  // \"native\", \"webview\", \"partial\" are all considered supported\n  // \"unsupported\" or missing means not supported\n  return cap === \"native\" || cap === \"webview\" || cap === \"partial\";\n}\n\nfunction degradeNode(node: AUPNode, caps: DeviceCaps): AUPNode {\n  // First, degrade this node if needed\n  let result = degradeNodeType(node, caps);\n\n  // Then recurse into children\n  if (result.children && result.children.length > 0) {\n    const degradedChildren = result.children.map((child) => degradeNode(child, caps));\n    // Only create new object if children actually changed\n    if (degradedChildren.some((c, i) => c !== result.children![i])) {\n      result = { ...result, children: degradedChildren };\n    }\n  }\n\n  return result;\n}\n\nfunction degradeNodeType(node: AUPNode, caps: DeviceCaps): AUPNode {\n  const nodeType = node.type;\n\n  // Already supported — no degradation needed\n  if (isSupported(nodeType, caps)) {\n    return node;\n  }\n\n  // No degradation chain defined — pass through (unknown/custom type)\n  const chain = DEGRADATION_CHAINS[nodeType];\n  if (!chain) {\n    return node;\n  }\n\n  // Walk the chain to find the first supported fallback\n  const originalType = nodeType;\n  for (const fallbackType of chain) {\n    if (fallbackType === \"unsupported\") {\n      // No meaningful fallback — mark as unsupported\n      return {\n        ...node,\n        type: \"text\",\n        props: {\n          ...node.props,\n          _degradedFrom: originalType,\n          _unsupported: true,\n          content: node.props?.content ?? `[${originalType}: unsupported on this device]`,\n        },\n      };\n    }\n\n    if (isSupported(fallbackType, caps)) {\n      // Found a supported fallback\n      return {\n        ...node,\n        type: fallbackType,\n        props: {\n          ...node.props,\n          _degradedFrom: originalType,\n        },\n      };\n    }\n  }\n\n  // Exhausted chain without finding support — degrade to text with annotation\n  return {\n    ...node,\n    type: \"text\",\n    props: {\n      ...node.props,\n      _degradedFrom: originalType,\n      content: node.props?.content ?? `[${originalType}: degraded to text]`,\n    },\n  };\n}\n"],"mappings":";;;;;;AAiBA,MAAa,qBAA+C;CAC1D,OAAO;EAAC;EAAO;EAAS;EAAO;CAC/B,OAAO,CAAC,SAAS,OAAO;CACxB,KAAK,CAAC,SAAS,OAAO;CACtB,QAAQ,CAAC,SAAS,OAAO;CACzB,UAAU,CAAC,OAAO;CAClB,QAAQ,CAAC,SAAS,OAAO;CACzB,KAAK,CAAC,cAAc;CACpB,UAAU,CAAC,SAAS,OAAO;CAC3B,MAAM,CAAC,OAAO;CACd,SAAS,CAAC,OAAO;CAElB;;;;;AAQD,SAAgB,YAAY,MAAe,MAA2B;AACpE,QAAO,YAAY,MAAM,KAAK;;AAKhC,SAAS,YAAY,eAAuB,MAA2B;CACrE,MAAM,MAAgC,KAAK,WAAW;AAGtD,QAAO,QAAQ,YAAY,QAAQ,aAAa,QAAQ;;AAG1D,SAAS,YAAY,MAAe,MAA2B;CAE7D,IAAI,SAAS,gBAAgB,MAAM,KAAK;AAGxC,KAAI,OAAO,YAAY,OAAO,SAAS,SAAS,GAAG;EACjD,MAAM,mBAAmB,OAAO,SAAS,KAAK,UAAU,YAAY,OAAO,KAAK,CAAC;AAEjF,MAAI,iBAAiB,MAAM,GAAG,MAAM,MAAM,OAAO,SAAU,GAAG,CAC5D,UAAS;GAAE,GAAG;GAAQ,UAAU;GAAkB;;AAItD,QAAO;;AAGT,SAAS,gBAAgB,MAAe,MAA2B;CACjE,MAAM,WAAW,KAAK;AAGtB,KAAI,YAAY,UAAU,KAAK,CAC7B,QAAO;CAIT,MAAM,QAAQ,mBAAmB;AACjC,KAAI,CAAC,MACH,QAAO;CAIT,MAAM,eAAe;AACrB,MAAK,MAAM,gBAAgB,OAAO;AAChC,MAAI,iBAAiB,cAEnB,QAAO;GACL,GAAG;GACH,MAAM;GACN,OAAO;IACL,GAAG,KAAK;IACR,eAAe;IACf,cAAc;IACd,SAAS,KAAK,OAAO,WAAW,IAAI,aAAa;IAClD;GACF;AAGH,MAAI,YAAY,cAAc,KAAK,CAEjC,QAAO;GACL,GAAG;GACH,MAAM;GACN,OAAO;IACL,GAAG,KAAK;IACR,eAAe;IAChB;GACF;;AAKL,QAAO;EACL,GAAG;EACH,MAAM;EACN,OAAO;GACL,GAAG,KAAK;GACR,eAAe;GACf,SAAS,KAAK,OAAO,WAAW,IAAI,aAAa;GAClD;EACF"}

package/dist/index.cjs

@@ -0,0 +1,36 @@
+const require_aup_types = require('./aup-types.cjs');
+const require_aup_protocol = require('./aup-protocol.cjs');
+const require_backend = require('./backend.cjs');
+const require_degradation = require('./degradation.cjs');
+const require_runtime = require('./runtime.cjs');
+const require_session = require('./session.cjs');
+const require_tty = require('./tty.cjs');
+const require_term = require('./term.cjs');
+const require_web_page = require('./web-page.cjs');
+const require_web = require('./web.cjs');
+const require_ui_provider = require('./ui-provider.cjs');
+
+exports.AFSRuntime = require_runtime.AFSRuntime;
+exports.AFSUIProvider = require_ui_provider.AFSUIProvider;
+exports.AUPNodeStore = require_aup_protocol.AUPNodeStore;
+exports.AUPSceneManager = require_aup_protocol.AUPSceneManager;
+exports.AUP_PRIMITIVES = require_aup_types.AUP_PRIMITIVES;
+exports.DEGRADATION_CHAINS = require_degradation.DEGRADATION_CHAINS;
+exports.DEVICE_CAPS_TERM = require_aup_types.DEVICE_CAPS_TERM;
+exports.DEVICE_CAPS_TTY = require_aup_types.DEVICE_CAPS_TTY;
+exports.DEVICE_CAPS_WEB_CHAT = require_aup_types.DEVICE_CAPS_WEB_CHAT;
+exports.DEVICE_CAPS_WEB_FULL = require_aup_types.DEVICE_CAPS_WEB_FULL;
+exports.Session = require_session.Session;
+exports.SessionManager = require_session.SessionManager;
+exports.TTYBackend = require_tty.TTYBackend;
+exports.TermBackend = require_term.TermBackend;
+exports.WEB_CLIENT_HTML = require_web_page.WEB_CLIENT_HTML;
+exports.WebBackend = require_web.WebBackend;
+exports.createMockInputSource = require_tty.createMockInputSource;
+exports.degradeTree = require_degradation.degradeTree;
+exports.fillPrimitives = require_aup_types.fillPrimitives;
+exports.isAUPTransport = require_backend.isAUPTransport;
+exports.isSessionAware = require_backend.isSessionAware;
+exports.validateDeviceCaps = require_aup_types.validateDeviceCaps;
+exports.validateNode = require_aup_types.validateNode;
+exports.validatePatchOp = require_aup_types.validatePatchOp;

package/dist/index.d.cts

@@ -0,0 +1,12 @@
+import { AUPClientMessage, AUPCreateOp, AUPEvent, AUPEventMessage, AUPEventResultMessage, AUPIntent, AUPNode, AUPPatchMessage, AUPPatchOp, AUPRemoveOp, AUPRenderMessage, AUPReorderOp, AUPServerMessage, AUPSize, AUPUpdateOp, AUPVariant, AUP_PRIMITIVES, DEVICE_CAPS_TERM, DEVICE_CAPS_TTY, DEVICE_CAPS_WEB_CHAT, DEVICE_CAPS_WEB_FULL, DeviceCaps, DeviceDisplay, DeviceInput, PrimitiveCap, fillPrimitives, validateDeviceCaps, validateNode, validatePatchOp } from "./aup-types.cjs";
+import { AUPNodeStore, AUPSceneManager } from "./aup-protocol.cjs";
+import { AUPTransportBackend, AupEventHandler, ChannelJoinHandler, FormField, PageResolver, PromptOptions, PromptResult, ReadOptions, SessionAwareBackend, SessionFactory, SessionJoinHandler, UIBackend, ViewportInfo, WriteOptions, isAUPTransport, isSessionAware } from "./backend.cjs";
+import { DEGRADATION_CHAINS, degradeTree } from "./degradation.cjs";
+import { AFSRuntime, RuntimeHandler } from "./runtime.cjs";
+import { Message, MessageFilter, PageData, Session, SessionManager } from "./session.cjs";
+import { TTYBackend, TTYBackendOptions, TTYInputSource, createMockInputSource } from "./tty.cjs";
+import { TermBackend, TermBackendOptions } from "./term.cjs";
+import { WebBackend, WebBackendOptions } from "./web.cjs";
+import { AFSUIProvider, AFSUIProviderOptions } from "./ui-provider.cjs";
+import { WEB_CLIENT_HTML } from "./web-page.cjs";
+export { AFSRuntime, AFSUIProvider, type AFSUIProviderOptions, type AUPClientMessage, type AUPCreateOp, type AUPEvent, type AUPEventMessage, type AUPEventResultMessage, type AUPIntent, type AUPNode, AUPNodeStore, type AUPPatchMessage, type AUPPatchOp, type AUPRemoveOp, type AUPRenderMessage, type AUPReorderOp, AUPSceneManager, type AUPServerMessage, type AUPSize, type AUPTransportBackend, type AUPUpdateOp, type AUPVariant, AUP_PRIMITIVES, type AupEventHandler, type ChannelJoinHandler, DEGRADATION_CHAINS, DEVICE_CAPS_TERM, DEVICE_CAPS_TTY, DEVICE_CAPS_WEB_CHAT, DEVICE_CAPS_WEB_FULL, type DeviceCaps, type DeviceDisplay, type DeviceInput, type FormField, type Message, type MessageFilter, type PageData, type PageResolver, type PrimitiveCap, type PromptOptions, type PromptResult, type ReadOptions, type RuntimeHandler, Session, type SessionAwareBackend, type SessionFactory, type SessionJoinHandler, SessionManager, TTYBackend, type TTYBackendOptions, type TTYInputSource, TermBackend, type TermBackendOptions, type UIBackend, type ViewportInfo, WEB_CLIENT_HTML, WebBackend, type WebBackendOptions, type WriteOptions, createMockInputSource, degradeTree, fillPrimitives, isAUPTransport, isSessionAware, validateDeviceCaps, validateNode, validatePatchOp };

package/dist/index.d.mts

@@ -0,0 +1,12 @@
+import { AUPClientMessage, AUPCreateOp, AUPEvent, AUPEventMessage, AUPEventResultMessage, AUPIntent, AUPNode, AUPPatchMessage, AUPPatchOp, AUPRemoveOp, AUPRenderMessage, AUPReorderOp, AUPServerMessage, AUPSize, AUPUpdateOp, AUPVariant, AUP_PRIMITIVES, DEVICE_CAPS_TERM, DEVICE_CAPS_TTY, DEVICE_CAPS_WEB_CHAT, DEVICE_CAPS_WEB_FULL, DeviceCaps, DeviceDisplay, DeviceInput, PrimitiveCap, fillPrimitives, validateDeviceCaps, validateNode, validatePatchOp } from "./aup-types.mjs";
+import { AUPNodeStore, AUPSceneManager } from "./aup-protocol.mjs";
+import { AUPTransportBackend, AupEventHandler, ChannelJoinHandler, FormField, PageResolver, PromptOptions, PromptResult, ReadOptions, SessionAwareBackend, SessionFactory, SessionJoinHandler, UIBackend, ViewportInfo, WriteOptions, isAUPTransport, isSessionAware } from "./backend.mjs";
+import { DEGRADATION_CHAINS, degradeTree } from "./degradation.mjs";
+import { AFSRuntime, RuntimeHandler } from "./runtime.mjs";
+import { Message, MessageFilter, PageData, Session, SessionManager } from "./session.mjs";
+import { TTYBackend, TTYBackendOptions, TTYInputSource, createMockInputSource } from "./tty.mjs";
+import { TermBackend, TermBackendOptions } from "./term.mjs";
+import { WebBackend, WebBackendOptions } from "./web.mjs";
+import { AFSUIProvider, AFSUIProviderOptions } from "./ui-provider.mjs";
+import { WEB_CLIENT_HTML } from "./web-page.mjs";
+export { AFSRuntime, AFSUIProvider, type AFSUIProviderOptions, type AUPClientMessage, type AUPCreateOp, type AUPEvent, type AUPEventMessage, type AUPEventResultMessage, type AUPIntent, type AUPNode, AUPNodeStore, type AUPPatchMessage, type AUPPatchOp, type AUPRemoveOp, type AUPRenderMessage, type AUPReorderOp, AUPSceneManager, type AUPServerMessage, type AUPSize, type AUPTransportBackend, type AUPUpdateOp, type AUPVariant, AUP_PRIMITIVES, type AupEventHandler, type ChannelJoinHandler, DEGRADATION_CHAINS, DEVICE_CAPS_TERM, DEVICE_CAPS_TTY, DEVICE_CAPS_WEB_CHAT, DEVICE_CAPS_WEB_FULL, type DeviceCaps, type DeviceDisplay, type DeviceInput, type FormField, type Message, type MessageFilter, type PageData, type PageResolver, type PrimitiveCap, type PromptOptions, type PromptResult, type ReadOptions, type RuntimeHandler, Session, type SessionAwareBackend, type SessionFactory, type SessionJoinHandler, SessionManager, TTYBackend, type TTYBackendOptions, type TTYInputSource, TermBackend, type TermBackendOptions, type UIBackend, type ViewportInfo, WEB_CLIENT_HTML, WebBackend, type WebBackendOptions, type WriteOptions, createMockInputSource, degradeTree, fillPrimitives, isAUPTransport, isSessionAware, validateDeviceCaps, validateNode, validatePatchOp };

package/dist/index.mjs

@@ -0,0 +1,13 @@
+import { AUP_PRIMITIVES, DEVICE_CAPS_TERM, DEVICE_CAPS_TTY, DEVICE_CAPS_WEB_CHAT, DEVICE_CAPS_WEB_FULL, fillPrimitives, validateDeviceCaps, validateNode, validatePatchOp } from "./aup-types.mjs";
+import { AUPNodeStore, AUPSceneManager } from "./aup-protocol.mjs";
+import { isAUPTransport, isSessionAware } from "./backend.mjs";
+import { DEGRADATION_CHAINS, degradeTree } from "./degradation.mjs";
+import { AFSRuntime } from "./runtime.mjs";
+import { Session, SessionManager } from "./session.mjs";
+import { TTYBackend, createMockInputSource } from "./tty.mjs";
+import { TermBackend } from "./term.mjs";
+import { WEB_CLIENT_HTML } from "./web-page.mjs";
+import { WebBackend } from "./web.mjs";
+import { AFSUIProvider } from "./ui-provider.mjs";
+
+export { AFSRuntime, AFSUIProvider, AUPNodeStore, AUPSceneManager, AUP_PRIMITIVES, DEGRADATION_CHAINS, DEVICE_CAPS_TERM, DEVICE_CAPS_TTY, DEVICE_CAPS_WEB_CHAT, DEVICE_CAPS_WEB_FULL, Session, SessionManager, TTYBackend, TermBackend, WEB_CLIENT_HTML, WebBackend, createMockInputSource, degradeTree, fillPrimitives, isAUPTransport, isSessionAware, validateDeviceCaps, validateNode, validatePatchOp };

package/dist/runtime.cjs

@@ -0,0 +1,117 @@
+let ufo = require("ufo");
+
+//#region src/runtime.ts
+/**
+* AFSRuntime — minimal event loop for UI device interaction.
+*
+* Reads input from a mounted UI device, dispatches to a registered handler,
+* and writes the handler's response back to device output.
+*
+* Usage:
+*   const runtime = new AFSRuntime(afs);
+*   runtime.on("/ui", async (input) => `Echo: ${input}`);
+*   await runtime.start();
+*   // ... running ...
+*   await runtime.stop();
+*/
+var AFSRuntime = class {
+	afs;
+	handlers = /* @__PURE__ */ new Map();
+	running = false;
+	stopRequested = false;
+	loopPromise = null;
+	resolveStop = null;
+	stopSignal = null;
+	/**
+	* Orphaned read promises from previous stop/start cycles.
+	* When the loop is blocked on read() and stop() is called, the read
+	* promise is preserved here so the next start() can consume it
+	* instead of losing the input.
+	*/
+	orphanedReads = /* @__PURE__ */ new Map();
+	constructor(afs) {
+		this.afs = afs;
+	}
+	/** Whether the runtime is currently running. */
+	get isRunning() {
+		return this.running;
+	}
+	/**
+	* Register a handler for a device mount path.
+	* The handler receives user input and optionally returns a response.
+	*/
+	on(devicePath, handler) {
+		this.handlers.set(devicePath, handler);
+		return this;
+	}
+	/**
+	* Start the event loop. Validates all registered device paths,
+	* then begins reading input and dispatching to handlers.
+	*/
+	async start() {
+		if (this.running) throw new Error("Runtime is already running");
+		if (this.handlers.size === 0) throw new Error("No handlers registered");
+		for (const path of this.handlers.keys()) await this.afs.stat((0, ufo.joinURL)(path, "input"));
+		this.running = true;
+		this.stopRequested = false;
+		this.stopSignal = new Promise((resolve) => {
+			this.resolveStop = resolve;
+		});
+		this.loopPromise = this.runLoops();
+	}
+	/**
+	* Stop the event loop. Waits for any in-progress handler to complete.
+	*/
+	async stop() {
+		if (!this.running) return;
+		this.stopRequested = true;
+		this.resolveStop?.();
+		if (this.loopPromise) await this.loopPromise;
+		this.running = false;
+		this.loopPromise = null;
+		this.resolveStop = null;
+		this.stopSignal = null;
+	}
+	async runLoops() {
+		const loops = [...this.handlers.entries()].map(([path, handler]) => this.runLoop(path, handler));
+		await Promise.allSettled(loops);
+	}
+	async runLoop(devicePath, handler) {
+		const inputPath = (0, ufo.joinURL)(devicePath, "input");
+		const outputPath = (0, ufo.joinURL)(devicePath, "output");
+		while (!this.stopRequested) {
+			let input;
+			const orphaned = this.orphanedReads.get(devicePath);
+			if (orphaned) {
+				this.orphanedReads.delete(devicePath);
+				input = await orphaned;
+			} else {
+				const readPromise = this.afs.read(inputPath).then((r) => String(r.data?.content ?? ""));
+				const result = await Promise.race([readPromise.then((value) => ({
+					stopped: false,
+					value
+				})), this.stopSignal.then(() => ({
+					stopped: true,
+					value: ""
+				}))]);
+				if (result.stopped || this.stopRequested) {
+					this.orphanedReads.set(devicePath, readPromise);
+					break;
+				}
+				input = result.value;
+			}
+			try {
+				const response = await handler(input);
+				if (response != null) await this.afs.write(outputPath, { content: String(response) });
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err);
+				try {
+					await this.afs.write(outputPath, { content: `Error: ${message}` });
+				} catch {}
+			}
+		}
+	}
+};
+
+//#endregion
+exports.AFSRuntime = AFSRuntime;

package/dist/runtime.d.cts

@@ -0,0 +1,59 @@
+import { AFS } from "@aigne/afs";
+
+//#region src/runtime.d.ts
+/**
+ * Handler function for processing user input.
+ * Return a string to write to device output, or null/undefined to skip output.
+ */
+type RuntimeHandler = (input: string) => string | void | null | undefined | Promise<string | void | null | undefined>;
+/**
+ * AFSRuntime — minimal event loop for UI device interaction.
+ *
+ * Reads input from a mounted UI device, dispatches to a registered handler,
+ * and writes the handler's response back to device output.
+ *
+ * Usage:
+ *   const runtime = new AFSRuntime(afs);
+ *   runtime.on("/ui", async (input) => `Echo: ${input}`);
+ *   await runtime.start();
+ *   // ... running ...
+ *   await runtime.stop();
+ */
+declare class AFSRuntime {
+  private afs;
+  private handlers;
+  private running;
+  private stopRequested;
+  private loopPromise;
+  private resolveStop;
+  private stopSignal;
+  /**
+   * Orphaned read promises from previous stop/start cycles.
+   * When the loop is blocked on read() and stop() is called, the read
+   * promise is preserved here so the next start() can consume it
+   * instead of losing the input.
+   */
+  private orphanedReads;
+  constructor(afs: AFS);
+  /** Whether the runtime is currently running. */
+  get isRunning(): boolean;
+  /**
+   * Register a handler for a device mount path.
+   * The handler receives user input and optionally returns a response.
+   */
+  on(devicePath: string, handler: RuntimeHandler): this;
+  /**
+   * Start the event loop. Validates all registered device paths,
+   * then begins reading input and dispatching to handlers.
+   */
+  start(): Promise<void>;
+  /**
+   * Stop the event loop. Waits for any in-progress handler to complete.
+   */
+  stop(): Promise<void>;
+  private runLoops;
+  private runLoop;
+}
+//#endregion
+export { AFSRuntime, RuntimeHandler };
+//# sourceMappingURL=runtime.d.cts.map

package/dist/runtime.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.cts","names":[],"sources":["../src/runtime.ts"],"mappings":";;;;;AAOA;;KAAY,cAAA,IACV,KAAA,gDACsC,OAAA;;;AAexC;;;;;;;;;;;cAAa,UAAA;EAAA,QACH,GAAA;EAAA,QACA,QAAA;EAAA,QACA,OAAA;EAAA,QACA,aAAA;EAAA,QACA,WAAA;EAAA,QACA,WAAA;EAAA,QACA,UAAA;EAUI;;;;;;EAAA,QAFJ,aAAA;cAEI,GAAA,EAAK,GAAA;EA+CX;EAAA,IA1CF,SAAA,CAAA;EA0DU;;;;EAlDd,EAAA,CAAG,UAAA,UAAoB,OAAA,EAAS,cAAA;;;;;EAS1B,KAAA,CAAA,GAAS,OAAA;;;;EAyBT,IAAA,CAAA,GAAQ,OAAA;EAAA,QAgBA,QAAA;EAAA,QAOA,OAAA;AAAA"}

package/dist/runtime.d.mts

@@ -0,0 +1,59 @@
+import { AFS } from "@aigne/afs";
+
+//#region src/runtime.d.ts
+/**
+ * Handler function for processing user input.
+ * Return a string to write to device output, or null/undefined to skip output.
+ */
+type RuntimeHandler = (input: string) => string | void | null | undefined | Promise<string | void | null | undefined>;
+/**
+ * AFSRuntime — minimal event loop for UI device interaction.
+ *
+ * Reads input from a mounted UI device, dispatches to a registered handler,
+ * and writes the handler's response back to device output.
+ *
+ * Usage:
+ *   const runtime = new AFSRuntime(afs);
+ *   runtime.on("/ui", async (input) => `Echo: ${input}`);
+ *   await runtime.start();
+ *   // ... running ...
+ *   await runtime.stop();
+ */
+declare class AFSRuntime {
+  private afs;
+  private handlers;
+  private running;
+  private stopRequested;
+  private loopPromise;
+  private resolveStop;
+  private stopSignal;
+  /**
+   * Orphaned read promises from previous stop/start cycles.
+   * When the loop is blocked on read() and stop() is called, the read
+   * promise is preserved here so the next start() can consume it
+   * instead of losing the input.
+   */
+  private orphanedReads;
+  constructor(afs: AFS);
+  /** Whether the runtime is currently running. */
+  get isRunning(): boolean;
+  /**
+   * Register a handler for a device mount path.
+   * The handler receives user input and optionally returns a response.
+   */
+  on(devicePath: string, handler: RuntimeHandler): this;
+  /**
+   * Start the event loop. Validates all registered device paths,
+   * then begins reading input and dispatching to handlers.
+   */
+  start(): Promise<void>;
+  /**
+   * Stop the event loop. Waits for any in-progress handler to complete.
+   */
+  stop(): Promise<void>;
+  private runLoops;
+  private runLoop;
+}
+//#endregion
+export { AFSRuntime, RuntimeHandler };
+//# sourceMappingURL=runtime.d.mts.map

package/dist/runtime.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.mts","names":[],"sources":["../src/runtime.ts"],"mappings":";;;;;AAOA;;KAAY,cAAA,IACV,KAAA,gDACsC,OAAA;;;AAexC;;;;;;;;;;;cAAa,UAAA;EAAA,QACH,GAAA;EAAA,QACA,QAAA;EAAA,QACA,OAAA;EAAA,QACA,aAAA;EAAA,QACA,WAAA;EAAA,QACA,WAAA;EAAA,QACA,UAAA;EAUI;;;;;;EAAA,QAFJ,aAAA;cAEI,GAAA,EAAK,GAAA;EA+CX;EAAA,IA1CF,SAAA,CAAA;EA0DU;;;;EAlDd,EAAA,CAAG,UAAA,UAAoB,OAAA,EAAS,cAAA;;;;;EAS1B,KAAA,CAAA,GAAS,OAAA;;;;EAyBT,IAAA,CAAA,GAAQ,OAAA;EAAA,QAgBA,QAAA;EAAA,QAOA,OAAA;AAAA"}

package/dist/runtime.mjs

@@ -0,0 +1,118 @@
+import { joinURL } from "ufo";
+
+//#region src/runtime.ts
+/**
+* AFSRuntime — minimal event loop for UI device interaction.
+*
+* Reads input from a mounted UI device, dispatches to a registered handler,
+* and writes the handler's response back to device output.
+*
+* Usage:
+*   const runtime = new AFSRuntime(afs);
+*   runtime.on("/ui", async (input) => `Echo: ${input}`);
+*   await runtime.start();
+*   // ... running ...
+*   await runtime.stop();
+*/
+var AFSRuntime = class {
+	afs;
+	handlers = /* @__PURE__ */ new Map();
+	running = false;
+	stopRequested = false;
+	loopPromise = null;
+	resolveStop = null;
+	stopSignal = null;
+	/**
+	* Orphaned read promises from previous stop/start cycles.
+	* When the loop is blocked on read() and stop() is called, the read
+	* promise is preserved here so the next start() can consume it
+	* instead of losing the input.
+	*/
+	orphanedReads = /* @__PURE__ */ new Map();
+	constructor(afs) {
+		this.afs = afs;
+	}
+	/** Whether the runtime is currently running. */
+	get isRunning() {
+		return this.running;
+	}
+	/**
+	* Register a handler for a device mount path.
+	* The handler receives user input and optionally returns a response.
+	*/
+	on(devicePath, handler) {
+		this.handlers.set(devicePath, handler);
+		return this;
+	}
+	/**
+	* Start the event loop. Validates all registered device paths,
+	* then begins reading input and dispatching to handlers.
+	*/
+	async start() {
+		if (this.running) throw new Error("Runtime is already running");
+		if (this.handlers.size === 0) throw new Error("No handlers registered");
+		for (const path of this.handlers.keys()) await this.afs.stat(joinURL(path, "input"));
+		this.running = true;
+		this.stopRequested = false;
+		this.stopSignal = new Promise((resolve) => {
+			this.resolveStop = resolve;
+		});
+		this.loopPromise = this.runLoops();
+	}
+	/**
+	* Stop the event loop. Waits for any in-progress handler to complete.
+	*/
+	async stop() {
+		if (!this.running) return;
+		this.stopRequested = true;
+		this.resolveStop?.();
+		if (this.loopPromise) await this.loopPromise;
+		this.running = false;
+		this.loopPromise = null;
+		this.resolveStop = null;
+		this.stopSignal = null;
+	}
+	async runLoops() {
+		const loops = [...this.handlers.entries()].map(([path, handler]) => this.runLoop(path, handler));
+		await Promise.allSettled(loops);
+	}
+	async runLoop(devicePath, handler) {
+		const inputPath = joinURL(devicePath, "input");
+		const outputPath = joinURL(devicePath, "output");
+		while (!this.stopRequested) {
+			let input;
+			const orphaned = this.orphanedReads.get(devicePath);
+			if (orphaned) {
+				this.orphanedReads.delete(devicePath);
+				input = await orphaned;
+			} else {
+				const readPromise = this.afs.read(inputPath).then((r) => String(r.data?.content ?? ""));
+				const result = await Promise.race([readPromise.then((value) => ({
+					stopped: false,
+					value
+				})), this.stopSignal.then(() => ({
+					stopped: true,
+					value: ""
+				}))]);
+				if (result.stopped || this.stopRequested) {
+					this.orphanedReads.set(devicePath, readPromise);
+					break;
+				}
+				input = result.value;
+			}
+			try {
+				const response = await handler(input);
+				if (response != null) await this.afs.write(outputPath, { content: String(response) });
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err);
+				try {
+					await this.afs.write(outputPath, { content: `Error: ${message}` });
+				} catch {}
+			}
+		}
+	}
+};
+
+//#endregion
+export { AFSRuntime };
+//# sourceMappingURL=runtime.mjs.map

package/dist/runtime.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.mjs","names":[],"sources":["../src/runtime.ts"],"sourcesContent":["import type { AFS } from \"@aigne/afs\";\nimport { joinURL } from \"ufo\";\n\n/**\n * Handler function for processing user input.\n * Return a string to write to device output, or null/undefined to skip output.\n */\nexport type RuntimeHandler = (\n  input: string,\n) => string | void | null | undefined | Promise<string | void | null | undefined>;\n\n/**\n * AFSRuntime — minimal event loop for UI device interaction.\n *\n * Reads input from a mounted UI device, dispatches to a registered handler,\n * and writes the handler's response back to device output.\n *\n * Usage:\n *   const runtime = new AFSRuntime(afs);\n *   runtime.on(\"/ui\", async (input) => `Echo: ${input}`);\n *   await runtime.start();\n *   // ... running ...\n *   await runtime.stop();\n */\nexport class AFSRuntime {\n  private afs: AFS;\n  private handlers = new Map<string, RuntimeHandler>();\n  private running = false;\n  private stopRequested = false;\n  private loopPromise: Promise<void> | null = null;\n  private resolveStop: (() => void) | null = null;\n  private stopSignal: Promise<void> | null = null;\n\n  /**\n   * Orphaned read promises from previous stop/start cycles.\n   * When the loop is blocked on read() and stop() is called, the read\n   * promise is preserved here so the next start() can consume it\n   * instead of losing the input.\n   */\n  private orphanedReads = new Map<string, Promise<string>>();\n\n  constructor(afs: AFS) {\n    this.afs = afs;\n  }\n\n  /** Whether the runtime is currently running. */\n  get isRunning(): boolean {\n    return this.running;\n  }\n\n  /**\n   * Register a handler for a device mount path.\n   * The handler receives user input and optionally returns a response.\n   */\n  on(devicePath: string, handler: RuntimeHandler): this {\n    this.handlers.set(devicePath, handler);\n    return this;\n  }\n\n  /**\n   * Start the event loop. Validates all registered device paths,\n   * then begins reading input and dispatching to handlers.\n   */\n  async start(): Promise<void> {\n    if (this.running) {\n      throw new Error(\"Runtime is already running\");\n    }\n    if (this.handlers.size === 0) {\n      throw new Error(\"No handlers registered\");\n    }\n\n    // Validate all device paths exist by stat-ing the input channel\n    for (const path of this.handlers.keys()) {\n      await this.afs.stat(joinURL(path, \"input\"));\n    }\n\n    this.running = true;\n    this.stopRequested = false;\n    this.stopSignal = new Promise((resolve) => {\n      this.resolveStop = resolve;\n    });\n\n    this.loopPromise = this.runLoops();\n  }\n\n  /**\n   * Stop the event loop. Waits for any in-progress handler to complete.\n   */\n  async stop(): Promise<void> {\n    if (!this.running) return;\n\n    this.stopRequested = true;\n    this.resolveStop?.();\n\n    if (this.loopPromise) {\n      await this.loopPromise;\n    }\n\n    this.running = false;\n    this.loopPromise = null;\n    this.resolveStop = null;\n    this.stopSignal = null;\n  }\n\n  private async runLoops(): Promise<void> {\n    const loops = [...this.handlers.entries()].map(([path, handler]) =>\n      this.runLoop(path, handler),\n    );\n    await Promise.allSettled(loops);\n  }\n\n  private async runLoop(devicePath: string, handler: RuntimeHandler): Promise<void> {\n    const inputPath = joinURL(devicePath, \"input\");\n    const outputPath = joinURL(devicePath, \"output\");\n\n    while (!this.stopRequested) {\n      let input: string;\n\n      // Check for an orphaned read from a previous stop/start cycle\n      const orphaned = this.orphanedReads.get(devicePath);\n      if (orphaned) {\n        this.orphanedReads.delete(devicePath);\n        input = await orphaned;\n      } else {\n        // Race between reading input and the stop signal\n        const readPromise = this.afs.read(inputPath).then((r) => String(r.data?.content ?? \"\"));\n\n        const result = await Promise.race([\n          readPromise.then((value) => ({ stopped: false as const, value })),\n          this.stopSignal!.then(() => ({ stopped: true as const, value: \"\" })),\n        ]);\n\n        if (result.stopped || this.stopRequested) {\n          // Preserve the orphaned read for the next cycle\n          this.orphanedReads.set(devicePath, readPromise);\n          break;\n        }\n\n        input = result.value;\n      }\n\n      try {\n        const response = await handler(input);\n        if (response != null) {\n          await this.afs.write(outputPath, { content: String(response) });\n        }\n      } catch (err) {\n        // Write error to device output; don't crash the loop\n        const message = err instanceof Error ? err.message : String(err);\n        try {\n          await this.afs.write(outputPath, { content: `Error: ${message}` });\n        } catch {\n          // If even error output fails, silently continue\n        }\n      }\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAwBA,IAAa,aAAb,MAAwB;CACtB,AAAQ;CACR,AAAQ,2BAAW,IAAI,KAA6B;CACpD,AAAQ,UAAU;CAClB,AAAQ,gBAAgB;CACxB,AAAQ,cAAoC;CAC5C,AAAQ,cAAmC;CAC3C,AAAQ,aAAmC;;;;;;;CAQ3C,AAAQ,gCAAgB,IAAI,KAA8B;CAE1D,YAAY,KAAU;AACpB,OAAK,MAAM;;;CAIb,IAAI,YAAqB;AACvB,SAAO,KAAK;;;;;;CAOd,GAAG,YAAoB,SAA+B;AACpD,OAAK,SAAS,IAAI,YAAY,QAAQ;AACtC,SAAO;;;;;;CAOT,MAAM,QAAuB;AAC3B,MAAI,KAAK,QACP,OAAM,IAAI,MAAM,6BAA6B;AAE/C,MAAI,KAAK,SAAS,SAAS,EACzB,OAAM,IAAI,MAAM,yBAAyB;AAI3C,OAAK,MAAM,QAAQ,KAAK,SAAS,MAAM,CACrC,OAAM,KAAK,IAAI,KAAK,QAAQ,MAAM,QAAQ,CAAC;AAG7C,OAAK,UAAU;AACf,OAAK,gBAAgB;AACrB,OAAK,aAAa,IAAI,SAAS,YAAY;AACzC,QAAK,cAAc;IACnB;AAEF,OAAK,cAAc,KAAK,UAAU;;;;;CAMpC,MAAM,OAAsB;AAC1B,MAAI,CAAC,KAAK,QAAS;AAEnB,OAAK,gBAAgB;AACrB,OAAK,eAAe;AAEpB,MAAI,KAAK,YACP,OAAM,KAAK;AAGb,OAAK,UAAU;AACf,OAAK,cAAc;AACnB,OAAK,cAAc;AACnB,OAAK,aAAa;;CAGpB,MAAc,WAA0B;EACtC,MAAM,QAAQ,CAAC,GAAG,KAAK,SAAS,SAAS,CAAC,CAAC,KAAK,CAAC,MAAM,aACrD,KAAK,QAAQ,MAAM,QAAQ,CAC5B;AACD,QAAM,QAAQ,WAAW,MAAM;;CAGjC,MAAc,QAAQ,YAAoB,SAAwC;EAChF,MAAM,YAAY,QAAQ,YAAY,QAAQ;EAC9C,MAAM,aAAa,QAAQ,YAAY,SAAS;AAEhD,SAAO,CAAC,KAAK,eAAe;GAC1B,IAAI;GAGJ,MAAM,WAAW,KAAK,cAAc,IAAI,WAAW;AACnD,OAAI,UAAU;AACZ,SAAK,cAAc,OAAO,WAAW;AACrC,YAAQ,MAAM;UACT;IAEL,MAAM,cAAc,KAAK,IAAI,KAAK,UAAU,CAAC,MAAM,MAAM,OAAO,EAAE,MAAM,WAAW,GAAG,CAAC;IAEvF,MAAM,SAAS,MAAM,QAAQ,KAAK,CAChC,YAAY,MAAM,WAAW;KAAE,SAAS;KAAgB;KAAO,EAAE,EACjE,KAAK,WAAY,YAAY;KAAE,SAAS;KAAe,OAAO;KAAI,EAAE,CACrE,CAAC;AAEF,QAAI,OAAO,WAAW,KAAK,eAAe;AAExC,UAAK,cAAc,IAAI,YAAY,YAAY;AAC/C;;AAGF,YAAQ,OAAO;;AAGjB,OAAI;IACF,MAAM,WAAW,MAAM,QAAQ,MAAM;AACrC,QAAI,YAAY,KACd,OAAM,KAAK,IAAI,MAAM,YAAY,EAAE,SAAS,OAAO,SAAS,EAAE,CAAC;YAE1D,KAAK;IAEZ,MAAM,UAAU,eAAe,QAAQ,IAAI,UAAU,OAAO,IAAI;AAChE,QAAI;AACF,WAAM,KAAK,IAAI,MAAM,YAAY,EAAE,SAAS,UAAU,WAAW,CAAC;YAC5D"}