@swifttui/web 0.1.12 → 0.1.14

package/dist/src/SurfaceRenderer.js

@@ -0,0 +1,21 @@
+//#region src/SurfaceRenderer.ts
+/**
+* The effective text color for a cell, folding the reverse-video emphasis bit
+* (`em & 16`) over the host terminal theme's defaults.
+*/
+function resolvedSurfaceForeground(style, terminalStyle) {
+	if ((style?.em ?? 0) & 16) return style?.bg ?? terminalStyle.theme.background;
+	return style?.fg ?? terminalStyle.theme.foreground;
+}
+/**
+* The effective background fill for a cell (or `undefined` for the terminal's
+* base background), folding the reverse-video emphasis bit (`em & 16`).
+*/
+function resolvedSurfaceBackground(style, terminalStyle) {
+	if ((style?.em ?? 0) & 16) return style?.fg ?? terminalStyle.theme.foreground;
+	return style?.bg;
+}
+//#endregion
+export { resolvedSurfaceBackground, resolvedSurfaceForeground };
+
+//# sourceMappingURL=SurfaceRenderer.js.map

package/dist/src/SurfaceRenderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SurfaceRenderer.js","names":[],"sources":["../../src/SurfaceRenderer.ts"],"sourcesContent":["import type { ResolvedWebHostTerminalStyle } from \"./WebHostTerminalStyle.ts\";\nimport type {\n  WebHostSurfaceDamage,\n  WebHostSurfaceFrame,\n  WebHostSurfaceStyle,\n} from \"./WebHostSurfaceTransport.ts\";\n\n/**\n * Which presenter draws surface frames into the scene mount.\n *\n * - `\"canvas\"` (default): paints cells onto a 2D `<canvas>` — pixel-exact\n *   box-drawing seams and decoration patterns, one DOM node total.\n * - `\"dom\"`: renders cells as absolutely positioned text elements — native\n *   font rendering (fallback glyphs, subpixel AA, crisp zoom), an\n *   inspectable element tree, and real selectable text (hold Alt/Option and\n *   drag). Box drawing and decoration patterns render via font glyphs and\n *   CSS `text-decoration`, so hairline seams may differ from the canvas\n *   painter.\n */\nexport type WebHostSurfaceRendererKind = \"canvas\" | \"dom\";\n\n/**\n * A read-only snapshot of the cell grid geometry and active style a surface\n * painter needs for a single paint pass. The runtime owns this state and\n * mutates it as the surface resizes or restyles; passing a fresh snapshot per\n * `paint` keeps painters stateless about geometry and avoids stale reads.\n */\nexport interface SurfaceMetrics {\n  columns: number;\n  rows: number;\n  cellWidth: number;\n  cellHeight: number;\n  style: ResolvedWebHostTerminalStyle;\n}\n\n/**\n * The paint seam shared by the canvas and DOM painters. The runtime calls\n * `paint` with the latest metrics snapshot, the current frame (or `undefined`\n * before the first frame), and optional damage scoping the repaint.\n */\nexport interface WebHostSurfacePainter {\n  paint(\n    metrics: SurfaceMetrics,\n    frame: WebHostSurfaceFrame | undefined,\n    damage?: WebHostSurfaceDamage\n  ): void;\n}\n\n/**\n * The effective text color for a cell, folding the reverse-video emphasis bit\n * (`em & 16`) over the host terminal theme's defaults.\n */\nexport function resolvedSurfaceForeground(\n  style: WebHostSurfaceStyle | null | undefined,\n  terminalStyle: ResolvedWebHostTerminalStyle\n): string {\n  if ((style?.em ?? 0) & 16) {\n    return style?.bg ?? terminalStyle.theme.background;\n  }\n  return style?.fg ?? terminalStyle.theme.foreground;\n}\n\n/**\n * The effective background fill for a cell (or `undefined` for the terminal's\n * base background), folding the reverse-video emphasis bit (`em & 16`).\n */\nexport function resolvedSurfaceBackground(\n  style: WebHostSurfaceStyle | null | undefined,\n  terminalStyle: ResolvedWebHostTerminalStyle\n): string | undefined {\n  if ((style?.em ?? 0) & 16) {\n    return style?.fg ?? terminalStyle.theme.foreground;\n  }\n  return style?.bg;\n}\n"],"mappings":";;;;;AAoDA,SAAgB,0BACd,OACA,eACQ;CACR,KAAK,OAAO,MAAM,KAAK,IACrB,OAAO,OAAO,MAAM,cAAc,MAAM;CAE1C,OAAO,OAAO,MAAM,cAAc,MAAM;AAC1C;;;;;AAMA,SAAgB,0BACd,OACA,eACoB;CACpB,KAAK,OAAO,MAAM,KAAK,IACrB,OAAO,OAAO,MAAM,cAAc,MAAM;CAE1C,OAAO,OAAO;AAChB"}

package/dist/src/WebHostApp.d.ts

@@ -1,4 +1,5 @@
 import { WebHostTerminalStyle } from "./WebHostTerminalStyle.js";
+import { WebHostSurfaceRendererKind } from "./SurfaceRenderer.js";
 import { WebHostSceneDescriptor, WebHostSceneManifestSource } from "./WebHostSceneManifest.js";
 import { WebHostSceneBridge, WebHostSceneRuntime, WebHostSceneRuntimeOptions } from "./WebHostSceneRuntime.js";
 import { WebSocketSceneBridgeOptions } from "./WebSocketSceneBridge.js";
@@ -15,6 +16,16 @@ interface WebHostBridgeFactoryOptions {
   environment?: Record<string, string>;
 }
 type WebHostBridgeFactory = (options: WebHostBridgeFactoryOptions) => WebHostSceneBridge;
+/**
+ * The slice of `Document` the app controller needs to track page visibility.
+ * Injectable for tests and non-browser hosts; defaults to the global
+ * `document` when one exists.
+ */
+interface WebHostVisibilityDocument {
+  readonly hidden: boolean;
+  addEventListener(type: "visibilitychange", listener: () => void): void;
+  removeEventListener(type: "visibilitychange", listener: () => void): void;
+}
 interface WebHostAppOptions {
   mount: HTMLElement;
   manifest?: WebHostSceneManifestSource;
@@ -26,6 +37,22 @@ interface WebHostAppOptions {
   bridgeFactory?: WebHostBridgeFactory;
   createElement?: (tagName: string) => HTMLElement;
   sceneRuntimeFactory?: (options: WebHostSceneRuntimeOptions) => WebHostSceneRuntime;
+  /**
+   * Whether scenes that cannot be seen — background scenes after a switch,
+   * or every scene while the document is hidden — suspend their apps (run
+   * loop parked, monotonic clock frozen) instead of burning CPU. Forwarded to
+   * each scene runtime as `suspendWhenHidden`. Defaults to `true`.
+   */
+  suspendHiddenScenes?: boolean;
+  /** Visibility source override; defaults to the global `document`. */
+  visibilityDocument?: WebHostVisibilityDocument;
+  /**
+   * Which surface presenter every scene runtime uses: `"canvas"` (default)
+   * paints frames onto a 2D `<canvas>`; `"dom"` renders them as absolutely
+   * positioned text elements. Forwarded to each scene runtime as `renderer`.
+   * See {@link WebHostSurfaceRendererKind}.
+   */
+  renderer?: WebHostSurfaceRendererKind;
 }
 interface WebHostAppController {
   scenes: WebHostSceneDescriptor[];
@@ -36,5 +63,5 @@ interface WebHostAppController {
 }
 declare function createWebHostApp(options: WebHostAppOptions): Promise<WebHostAppController>;
 //#endregion
-export { WebHostAppController, WebHostAppOptions, WebHostBridgeFactory, WebHostBridgeFactoryOptions, WebHostEmbeddedHostConfig, createWebHostApp };
+export { WebHostAppController, WebHostAppOptions, WebHostBridgeFactory, WebHostBridgeFactoryOptions, WebHostEmbeddedHostConfig, WebHostVisibilityDocument, createWebHostApp };
 //# sourceMappingURL=WebHostApp.d.ts.map

package/dist/src/WebHostApp.js

@@ -15,7 +15,10 @@ async function createWebHostApp(options) {
 		bridgeFactory: options.bridgeFactory,
 		initialSceneId: options.initialSceneId,
 		createElement: options.createElement,
-		sceneRuntimeFactory: options.sceneRuntimeFactory ?? ((runtimeOptions) => new WebHostSceneRuntime(runtimeOptions))
+		sceneRuntimeFactory: options.sceneRuntimeFactory ?? ((runtimeOptions) => new WebHostSceneRuntime(runtimeOptions)),
+		suspendHiddenScenes: options.suspendHiddenScenes,
+		visibilityDocument: options.visibilityDocument ?? defaultVisibilityDocument(),
+		renderer: options.renderer
 	});
 	await controller.initialize();
 	return controller;
@@ -32,6 +35,10 @@ var InternalWebHostAppController = class {
 	sceneRuntimeFactory;
 	runtimes = /* @__PURE__ */ new Map();
 	bridges = /* @__PURE__ */ new Map();
+	suspendHiddenScenes;
+	renderer;
+	visibilityDocument;
+	detachVisibilityListener;
 	constructor(options) {
 		this.mount = options.mount;
 		this.style = normalizeWebHostTerminalStyle(options.style ?? {});
@@ -39,6 +46,9 @@ var InternalWebHostAppController = class {
 		this.embeddedHost = options.embeddedHost;
 		this.bridgeFactory = options.bridgeFactory;
 		this.sceneRuntimeFactory = options.sceneRuntimeFactory;
+		this.suspendHiddenScenes = options.suspendHiddenScenes;
+		this.renderer = options.renderer;
+		this.visibilityDocument = options.visibilityDocument;
 		this.scenes = options.manifest.scenes;
 		this.selectedSceneId = options.initialSceneId && options.manifest.scenes.some((scene) => scene.id === options.initialSceneId) ? options.initialSceneId : options.manifest.scenes.find((scene) => scene.id === options.manifest.defaultSceneId)?.id ?? options.manifest.defaultSceneId;
 		this.sceneRoot = (options.createElement ?? defaultCreateElement)("div");
@@ -47,6 +57,7 @@ var InternalWebHostAppController = class {
 		this.applyHostFrameStyle();
 	}
 	async initialize() {
+		this.installVisibilityListener();
 		await this.ensureRuntime(this.selectedSceneId);
 		await this.switchScene(this.selectedSceneId);
 	}
@@ -63,12 +74,26 @@ var InternalWebHostAppController = class {
 		this.applyHostFrameStyle();
 	}
 	async dispose() {
+		this.detachVisibilityListener?.();
+		this.detachVisibilityListener = void 0;
 		for (const runtime of this.runtimes.values()) runtime.dispose();
 		for (const bridge of this.bridges.values()) bridge.dispose();
 		this.runtimes.clear();
 		this.bridges.clear();
 		this.mount.replaceChildren();
 	}
+	installVisibilityListener() {
+		const visibilityDocument = this.visibilityDocument;
+		if (!visibilityDocument) return;
+		const listener = () => {
+			const visible = !visibilityDocument.hidden;
+			for (const runtime of this.runtimes.values()) runtime.setDocumentVisible(visible);
+		};
+		visibilityDocument.addEventListener("visibilitychange", listener);
+		this.detachVisibilityListener = () => {
+			visibilityDocument.removeEventListener("visibilitychange", listener);
+		};
+	}
 	async ensureRuntime(id) {
 		const existing = this.runtimes.get(id);
 		if (existing) return existing;
@@ -80,12 +105,15 @@ var InternalWebHostAppController = class {
 			descriptor,
 			style: this.style,
 			bridge,
-			onInput: (chunk) => bridge.sendInput(chunk)
+			onInput: (chunk) => bridge.sendInput(chunk),
+			suspendWhenHidden: this.suspendHiddenScenes,
+			renderer: this.renderer
 		});
 		this.bridges.set(id, bridge);
 		this.runtimes.set(id, runtime);
 		await runtime.mount();
 		runtime.setVisible(id === this.selectedSceneId);
+		if (this.visibilityDocument) runtime.setDocumentVisible(!this.visibilityDocument.hidden);
 		return runtime;
 	}
 	makeBridge(sceneId, descriptor) {
@@ -116,6 +144,10 @@ var InternalWebHostAppController = class {
 		this.mount.style.padding = "1rem";
 	}
 };
+function defaultVisibilityDocument() {
+	if (typeof document === "undefined") return;
+	return document;
+}
 function defaultCreateElement(tagName) {
 	if (typeof document === "undefined") throw new Error("document is not available");
 	return document.createElement(tagName);

package/dist/src/WebHostApp.js.map

@@ -1 +1 @@
-{"version":3,"file":"WebHostApp.js","names":[],"sources":["../../src/WebHostApp.ts"],"sourcesContent":["import { BrowserWASIBridge } from \"./wasi/BrowserWASIBridge.ts\";\nimport {\n  WebSocketSceneBridge,\n  type WebSocketSceneBridgeOptions,\n} from \"./WebSocketSceneBridge.ts\";\nimport {\n  loadWebHostSceneManifest,\n  normalizeWebHostSceneManifest,\n  type WebHostSceneDescriptor,\n  type WebHostSceneManifest,\n  type WebHostSceneManifestSource,\n} from \"./WebHostSceneManifest.ts\";\nimport {\n  mergeWebHostTerminalStyle,\n  normalizeWebHostTerminalStyle,\n  type ResolvedWebHostTerminalStyle,\n  type WebHostTerminalStyle,\n} from \"./WebHostTerminalStyle.ts\";\nimport {\n  WebHostSceneRuntime,\n  type WebHostSceneBridge,\n  type WebHostSceneRuntimeOptions,\n} from \"./WebHostSceneRuntime.ts\";\n\nexport interface WebHostEmbeddedHostConfig {\n  token: string;\n  webSocketBaseURL?: string | URL;\n  webSocketFactory?: WebSocketSceneBridgeOptions[\"webSocketFactory\"];\n}\n\nexport interface WebHostBridgeFactoryOptions {\n  sceneId: string;\n  descriptor: WebHostSceneDescriptor;\n  style: WebHostTerminalStyle;\n  environment?: Record<string, string>;\n}\n\nexport type WebHostBridgeFactory = (options: WebHostBridgeFactoryOptions) => WebHostSceneBridge;\n\nexport interface WebHostAppOptions {\n  mount: HTMLElement;\n  manifest?: WebHostSceneManifestSource;\n  manifestUrl?: string | URL;\n  initialSceneId?: string;\n  style?: WebHostTerminalStyle;\n  environment?: Record<string, string>;\n  embeddedHost?: WebHostEmbeddedHostConfig;\n  bridgeFactory?: WebHostBridgeFactory;\n  createElement?: (tagName: string) => HTMLElement;\n  sceneRuntimeFactory?: (options: WebHostSceneRuntimeOptions) => WebHostSceneRuntime;\n}\n\nexport interface WebHostAppController {\n  scenes: WebHostSceneDescriptor[];\n  selectedSceneId: string;\n  switchScene(id: string): Promise<void>;\n  setStyle(style: WebHostTerminalStyle): void;\n  dispose(): Promise<void>;\n}\n\ntype RuntimeFactory = (options: WebHostSceneRuntimeOptions) => WebHostSceneRuntime;\n\nexport async function createWebHostApp(\n  options: WebHostAppOptions\n): Promise<WebHostAppController> {\n  const manifest = await resolveManifest(options);\n  const controller = new InternalWebHostAppController({\n    mount: options.mount,\n    manifest,\n    style: options.style,\n    environment: options.environment,\n    embeddedHost: options.embeddedHost,\n    bridgeFactory: options.bridgeFactory,\n    initialSceneId: options.initialSceneId,\n    createElement: options.createElement,\n    sceneRuntimeFactory: options.sceneRuntimeFactory ?? ((runtimeOptions) => new WebHostSceneRuntime(runtimeOptions)),\n  });\n  await controller.initialize();\n  return controller;\n}\n\nclass InternalWebHostAppController implements WebHostAppController {\n  readonly scenes: WebHostSceneDescriptor[];\n  selectedSceneId: string;\n\n  private readonly mount: HTMLElement;\n  private readonly sceneRoot: HTMLElement;\n  private style: ResolvedWebHostTerminalStyle;\n  private readonly environment?: Record<string, string>;\n  private readonly embeddedHost?: WebHostEmbeddedHostConfig;\n  private readonly bridgeFactory?: WebHostBridgeFactory;\n  private readonly sceneRuntimeFactory: RuntimeFactory;\n  private readonly runtimes = new Map<string, WebHostSceneRuntime>();\n  private readonly bridges = new Map<string, WebHostSceneBridge>();\n\n  constructor(options: {\n    mount: HTMLElement;\n    manifest: WebHostSceneManifest;\n    style?: WebHostTerminalStyle;\n    environment?: Record<string, string>;\n    embeddedHost?: WebHostEmbeddedHostConfig;\n    bridgeFactory?: WebHostBridgeFactory;\n    initialSceneId?: string;\n    createElement?: (tagName: string) => HTMLElement;\n    sceneRuntimeFactory: RuntimeFactory;\n  }) {\n    this.mount = options.mount;\n    this.style = normalizeWebHostTerminalStyle(options.style ?? {});\n    this.environment = options.environment;\n    this.embeddedHost = options.embeddedHost;\n    this.bridgeFactory = options.bridgeFactory;\n    this.sceneRuntimeFactory = options.sceneRuntimeFactory;\n    this.scenes = options.manifest.scenes;\n    this.selectedSceneId =\n      options.initialSceneId &&\n      options.manifest.scenes.some((scene) => scene.id === options.initialSceneId)\n        ? options.initialSceneId\n        : options.manifest.scenes.find((scene) => scene.id === options.manifest.defaultSceneId)?.id ??\n          options.manifest.defaultSceneId;\n\n    this.sceneRoot = (options.createElement ?? defaultCreateElement)(\"div\");\n    this.sceneRoot.className = \"webhost-scene-root\";\n    this.mount.replaceChildren(this.sceneRoot);\n    this.applyHostFrameStyle();\n  }\n\n  async initialize(): Promise<void> {\n    await this.ensureRuntime(this.selectedSceneId);\n    await this.switchScene(this.selectedSceneId);\n  }\n\n  async switchScene(\n    id: string\n  ): Promise<void> {\n    const descriptor = this.scenes.find((scene) => scene.id === id);\n    if (!descriptor) {\n      throw new Error(`Unknown scene: ${id}`);\n    }\n\n    for (const [sceneId, runtime] of this.runtimes) {\n      runtime.setVisible(sceneId === id);\n    }\n\n    const runtime = await this.ensureRuntime(id);\n    runtime.setVisible(true);\n    this.selectedSceneId = id;\n  }\n\n  setStyle(\n    style: WebHostTerminalStyle\n  ): void {\n    const merged = mergeWebHostTerminalStyle(this.style, style);\n    this.style = merged;\n\n    for (const runtime of this.runtimes.values()) {\n      runtime.setStyle(this.style);\n    }\n    this.applyHostFrameStyle();\n  }\n\n  async dispose(): Promise<void> {\n    for (const runtime of this.runtimes.values()) {\n      runtime.dispose();\n    }\n    for (const bridge of this.bridges.values()) {\n      bridge.dispose();\n    }\n    this.runtimes.clear();\n    this.bridges.clear();\n    this.mount.replaceChildren();\n  }\n\n  private async ensureRuntime(\n    id: string\n  ): Promise<WebHostSceneRuntime> {\n    const existing = this.runtimes.get(id);\n    if (existing) {\n      return existing;\n    }\n\n    const descriptor = this.scenes.find((scene) => scene.id === id);\n    if (!descriptor) {\n      throw new Error(`Unknown scene: ${id}`);\n    }\n\n    const bridge = this.makeBridge(id, descriptor);\n    const runtime = this.sceneRuntimeFactory({\n      mount: this.sceneRoot,\n      descriptor,\n      style: this.style,\n      bridge,\n      onInput: (chunk) => bridge.sendInput(chunk),\n    });\n\n    this.bridges.set(id, bridge);\n    this.runtimes.set(id, runtime);\n    await runtime.mount();\n    runtime.setVisible(id === this.selectedSceneId);\n    return runtime;\n  }\n\n  private makeBridge(\n    sceneId: string,\n    descriptor: WebHostSceneDescriptor\n  ): WebHostSceneBridge {\n    if (this.bridgeFactory) {\n      return this.bridgeFactory({\n        sceneId,\n        descriptor,\n        style: this.style,\n        environment: this.environment,\n      });\n    }\n\n    if (this.embeddedHost) {\n      return new WebSocketSceneBridge({\n        sceneId,\n        token: this.embeddedHost.token,\n        baseURL: this.embeddedHost.webSocketBaseURL,\n        webSocketFactory: this.embeddedHost.webSocketFactory,\n      });\n    }\n\n    return new BrowserWASIBridge({\n      sceneId,\n      columns: 80,\n      rows: 24,\n      environment: this.environment,\n      renderStyle: this.style,\n    });\n  }\n\n  private applyHostFrameStyle(): void {\n    this.mount.style.background = \"linear-gradient(180deg, #0f172a 0%, #111827 100%)\";\n    this.mount.style.minHeight = \"100%\";\n    this.mount.style.display = \"block\";\n    this.mount.style.padding = \"1rem\";\n  }\n}\n\nfunction defaultCreateElement(\n  tagName: string\n): HTMLElement {\n  if (typeof document === \"undefined\") {\n    throw new Error(\"document is not available\");\n  }\n\n  return document.createElement(tagName);\n}\n\nasync function resolveManifest(\n  options: WebHostAppOptions\n): Promise<WebHostSceneManifest> {\n  if (options.manifest) {\n    return loadWebHostSceneManifest(options.manifest);\n  }\n\n  if (options.manifestUrl) {\n    return loadWebHostSceneManifest(options.manifestUrl);\n  }\n\n  return normalizeWebHostSceneManifest([\n    {\n      id: \"main\",\n      title: \"Main\",\n      isDefault: true,\n    },\n  ]);\n}\n"],"mappings":"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"}
+{"version":3,"file":"WebHostApp.js","names":[],"sources":["../../src/WebHostApp.ts"],"sourcesContent":["import { BrowserWASIBridge } from \"./wasi/BrowserWASIBridge.ts\";\nimport {\n  WebSocketSceneBridge,\n  type WebSocketSceneBridgeOptions,\n} from \"./WebSocketSceneBridge.ts\";\nimport {\n  loadWebHostSceneManifest,\n  normalizeWebHostSceneManifest,\n  type WebHostSceneDescriptor,\n  type WebHostSceneManifest,\n  type WebHostSceneManifestSource,\n} from \"./WebHostSceneManifest.ts\";\nimport {\n  mergeWebHostTerminalStyle,\n  normalizeWebHostTerminalStyle,\n  type ResolvedWebHostTerminalStyle,\n  type WebHostTerminalStyle,\n} from \"./WebHostTerminalStyle.ts\";\nimport {\n  WebHostSceneRuntime,\n  type WebHostSceneBridge,\n  type WebHostSceneRuntimeOptions,\n} from \"./WebHostSceneRuntime.ts\";\nimport type { WebHostSurfaceRendererKind } from \"./SurfaceRenderer.ts\";\n\nexport interface WebHostEmbeddedHostConfig {\n  token: string;\n  webSocketBaseURL?: string | URL;\n  webSocketFactory?: WebSocketSceneBridgeOptions[\"webSocketFactory\"];\n}\n\nexport interface WebHostBridgeFactoryOptions {\n  sceneId: string;\n  descriptor: WebHostSceneDescriptor;\n  style: WebHostTerminalStyle;\n  environment?: Record<string, string>;\n}\n\nexport type WebHostBridgeFactory = (options: WebHostBridgeFactoryOptions) => WebHostSceneBridge;\n\n/**\n * The slice of `Document` the app controller needs to track page visibility.\n * Injectable for tests and non-browser hosts; defaults to the global\n * `document` when one exists.\n */\nexport interface WebHostVisibilityDocument {\n  readonly hidden: boolean;\n  addEventListener(type: \"visibilitychange\", listener: () => void): void;\n  removeEventListener(type: \"visibilitychange\", listener: () => void): void;\n}\n\nexport interface WebHostAppOptions {\n  mount: HTMLElement;\n  manifest?: WebHostSceneManifestSource;\n  manifestUrl?: string | URL;\n  initialSceneId?: string;\n  style?: WebHostTerminalStyle;\n  environment?: Record<string, string>;\n  embeddedHost?: WebHostEmbeddedHostConfig;\n  bridgeFactory?: WebHostBridgeFactory;\n  createElement?: (tagName: string) => HTMLElement;\n  sceneRuntimeFactory?: (options: WebHostSceneRuntimeOptions) => WebHostSceneRuntime;\n  /**\n   * Whether scenes that cannot be seen — background scenes after a switch,\n   * or every scene while the document is hidden — suspend their apps (run\n   * loop parked, monotonic clock frozen) instead of burning CPU. Forwarded to\n   * each scene runtime as `suspendWhenHidden`. Defaults to `true`.\n   */\n  suspendHiddenScenes?: boolean;\n  /** Visibility source override; defaults to the global `document`. */\n  visibilityDocument?: WebHostVisibilityDocument;\n  /**\n   * Which surface presenter every scene runtime uses: `\"canvas\"` (default)\n   * paints frames onto a 2D `<canvas>`; `\"dom\"` renders them as absolutely\n   * positioned text elements. Forwarded to each scene runtime as `renderer`.\n   * See {@link WebHostSurfaceRendererKind}.\n   */\n  renderer?: WebHostSurfaceRendererKind;\n}\n\nexport interface WebHostAppController {\n  scenes: WebHostSceneDescriptor[];\n  selectedSceneId: string;\n  switchScene(id: string): Promise<void>;\n  setStyle(style: WebHostTerminalStyle): void;\n  dispose(): Promise<void>;\n}\n\ntype RuntimeFactory = (options: WebHostSceneRuntimeOptions) => WebHostSceneRuntime;\n\nexport async function createWebHostApp(\n  options: WebHostAppOptions\n): Promise<WebHostAppController> {\n  const manifest = await resolveManifest(options);\n  const controller = new InternalWebHostAppController({\n    mount: options.mount,\n    manifest,\n    style: options.style,\n    environment: options.environment,\n    embeddedHost: options.embeddedHost,\n    bridgeFactory: options.bridgeFactory,\n    initialSceneId: options.initialSceneId,\n    createElement: options.createElement,\n    sceneRuntimeFactory: options.sceneRuntimeFactory ?? ((runtimeOptions) => new WebHostSceneRuntime(runtimeOptions)),\n    suspendHiddenScenes: options.suspendHiddenScenes,\n    visibilityDocument: options.visibilityDocument ?? defaultVisibilityDocument(),\n    renderer: options.renderer,\n  });\n  await controller.initialize();\n  return controller;\n}\n\nclass InternalWebHostAppController implements WebHostAppController {\n  readonly scenes: WebHostSceneDescriptor[];\n  selectedSceneId: string;\n\n  private readonly mount: HTMLElement;\n  private readonly sceneRoot: HTMLElement;\n  private style: ResolvedWebHostTerminalStyle;\n  private readonly environment?: Record<string, string>;\n  private readonly embeddedHost?: WebHostEmbeddedHostConfig;\n  private readonly bridgeFactory?: WebHostBridgeFactory;\n  private readonly sceneRuntimeFactory: RuntimeFactory;\n  private readonly runtimes = new Map<string, WebHostSceneRuntime>();\n  private readonly bridges = new Map<string, WebHostSceneBridge>();\n  private readonly suspendHiddenScenes?: boolean;\n  private readonly renderer?: WebHostSurfaceRendererKind;\n  private readonly visibilityDocument?: WebHostVisibilityDocument;\n  private detachVisibilityListener?: () => void;\n\n  constructor(options: {\n    mount: HTMLElement;\n    manifest: WebHostSceneManifest;\n    style?: WebHostTerminalStyle;\n    environment?: Record<string, string>;\n    embeddedHost?: WebHostEmbeddedHostConfig;\n    bridgeFactory?: WebHostBridgeFactory;\n    initialSceneId?: string;\n    createElement?: (tagName: string) => HTMLElement;\n    sceneRuntimeFactory: RuntimeFactory;\n    suspendHiddenScenes?: boolean;\n    visibilityDocument?: WebHostVisibilityDocument;\n    renderer?: WebHostSurfaceRendererKind;\n  }) {\n    this.mount = options.mount;\n    this.style = normalizeWebHostTerminalStyle(options.style ?? {});\n    this.environment = options.environment;\n    this.embeddedHost = options.embeddedHost;\n    this.bridgeFactory = options.bridgeFactory;\n    this.sceneRuntimeFactory = options.sceneRuntimeFactory;\n    this.suspendHiddenScenes = options.suspendHiddenScenes;\n    this.renderer = options.renderer;\n    this.visibilityDocument = options.visibilityDocument;\n    this.scenes = options.manifest.scenes;\n    this.selectedSceneId =\n      options.initialSceneId &&\n      options.manifest.scenes.some((scene) => scene.id === options.initialSceneId)\n        ? options.initialSceneId\n        : options.manifest.scenes.find((scene) => scene.id === options.manifest.defaultSceneId)?.id ??\n          options.manifest.defaultSceneId;\n\n    this.sceneRoot = (options.createElement ?? defaultCreateElement)(\"div\");\n    this.sceneRoot.className = \"webhost-scene-root\";\n    this.mount.replaceChildren(this.sceneRoot);\n    this.applyHostFrameStyle();\n  }\n\n  async initialize(): Promise<void> {\n    this.installVisibilityListener();\n    await this.ensureRuntime(this.selectedSceneId);\n    await this.switchScene(this.selectedSceneId);\n  }\n\n  async switchScene(\n    id: string\n  ): Promise<void> {\n    const descriptor = this.scenes.find((scene) => scene.id === id);\n    if (!descriptor) {\n      throw new Error(`Unknown scene: ${id}`);\n    }\n\n    for (const [sceneId, runtime] of this.runtimes) {\n      runtime.setVisible(sceneId === id);\n    }\n\n    const runtime = await this.ensureRuntime(id);\n    runtime.setVisible(true);\n    this.selectedSceneId = id;\n  }\n\n  setStyle(\n    style: WebHostTerminalStyle\n  ): void {\n    const merged = mergeWebHostTerminalStyle(this.style, style);\n    this.style = merged;\n\n    for (const runtime of this.runtimes.values()) {\n      runtime.setStyle(this.style);\n    }\n    this.applyHostFrameStyle();\n  }\n\n  async dispose(): Promise<void> {\n    this.detachVisibilityListener?.();\n    this.detachVisibilityListener = undefined;\n    for (const runtime of this.runtimes.values()) {\n      runtime.dispose();\n    }\n    for (const bridge of this.bridges.values()) {\n      bridge.dispose();\n    }\n    this.runtimes.clear();\n    this.bridges.clear();\n    this.mount.replaceChildren();\n  }\n\n  private installVisibilityListener(): void {\n    const visibilityDocument = this.visibilityDocument;\n    if (!visibilityDocument) {\n      return;\n    }\n    const listener = (): void => {\n      const visible = !visibilityDocument.hidden;\n      for (const runtime of this.runtimes.values()) {\n        runtime.setDocumentVisible(visible);\n      }\n    };\n    visibilityDocument.addEventListener(\"visibilitychange\", listener);\n    this.detachVisibilityListener = () => {\n      visibilityDocument.removeEventListener(\"visibilitychange\", listener);\n    };\n  }\n\n  private async ensureRuntime(\n    id: string\n  ): Promise<WebHostSceneRuntime> {\n    const existing = this.runtimes.get(id);\n    if (existing) {\n      return existing;\n    }\n\n    const descriptor = this.scenes.find((scene) => scene.id === id);\n    if (!descriptor) {\n      throw new Error(`Unknown scene: ${id}`);\n    }\n\n    const bridge = this.makeBridge(id, descriptor);\n    const runtime = this.sceneRuntimeFactory({\n      mount: this.sceneRoot,\n      descriptor,\n      style: this.style,\n      bridge,\n      onInput: (chunk) => bridge.sendInput(chunk),\n      suspendWhenHidden: this.suspendHiddenScenes,\n      renderer: this.renderer,\n    });\n\n    this.bridges.set(id, bridge);\n    this.runtimes.set(id, runtime);\n    await runtime.mount();\n    runtime.setVisible(id === this.selectedSceneId);\n    if (this.visibilityDocument) {\n      runtime.setDocumentVisible(!this.visibilityDocument.hidden);\n    }\n    return runtime;\n  }\n\n  private makeBridge(\n    sceneId: string,\n    descriptor: WebHostSceneDescriptor\n  ): WebHostSceneBridge {\n    if (this.bridgeFactory) {\n      return this.bridgeFactory({\n        sceneId,\n        descriptor,\n        style: this.style,\n        environment: this.environment,\n      });\n    }\n\n    if (this.embeddedHost) {\n      return new WebSocketSceneBridge({\n        sceneId,\n        token: this.embeddedHost.token,\n        baseURL: this.embeddedHost.webSocketBaseURL,\n        webSocketFactory: this.embeddedHost.webSocketFactory,\n      });\n    }\n\n    return new BrowserWASIBridge({\n      sceneId,\n      columns: 80,\n      rows: 24,\n      environment: this.environment,\n      renderStyle: this.style,\n    });\n  }\n\n  private applyHostFrameStyle(): void {\n    this.mount.style.background = \"linear-gradient(180deg, #0f172a 0%, #111827 100%)\";\n    this.mount.style.minHeight = \"100%\";\n    this.mount.style.display = \"block\";\n    this.mount.style.padding = \"1rem\";\n  }\n}\n\nfunction defaultVisibilityDocument(): WebHostVisibilityDocument | undefined {\n  if (typeof document === \"undefined\") {\n    return undefined;\n  }\n  return document;\n}\n\nfunction defaultCreateElement(\n  tagName: string\n): HTMLElement {\n  if (typeof document === \"undefined\") {\n    throw new Error(\"document is not available\");\n  }\n\n  return document.createElement(tagName);\n}\n\nasync function resolveManifest(\n  options: WebHostAppOptions\n): Promise<WebHostSceneManifest> {\n  if (options.manifest) {\n    return loadWebHostSceneManifest(options.manifest);\n  }\n\n  if (options.manifestUrl) {\n    return loadWebHostSceneManifest(options.manifestUrl);\n  }\n\n  return normalizeWebHostSceneManifest([\n    {\n      id: \"main\",\n      title: \"Main\",\n      isDefault: true,\n    },\n  ]);\n}\n"],"mappings":"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"}

package/dist/src/WebHostSceneRuntime.d.ts

@@ -1,5 +1,6 @@
 import { WebHostTerminalStyle } from "./WebHostTerminalStyle.js";
 import { WebHostFocusPresentation, WebHostFrameDiagnosticRecord, WebHostOutputSink, WebHostRuntimeIssue } from "./WebHostSurfaceTransport.js";
+import { WebHostSurfaceRendererKind } from "./SurfaceRenderer.js";
 import { WebHostSceneDescriptor } from "./WebHostSceneManifest.js";
 //#region src/WebHostSceneRuntime.d.ts
 interface WebHostSceneBridge {
@@ -45,6 +46,23 @@ interface WebHostSceneRuntimeOptions {
    * and other schemes are ignored. Mirrors the Android host's tap-to-open.
    */
   onOpenHyperlink?: (url: string) => void;
+  /**
+   * Whether to suspend the scene's app while it cannot be seen — when the
+   * scene is switched to the background (`setVisible(false)`) or the whole
+   * document is hidden (`setDocumentVisible(false)`). Suspension parks the
+   * app's run loop and freezes its monotonic clock, so a hidden scene costs
+   * no CPU and resumes exactly where it left off. Defaults to `true`; set
+   * `false` to let background scenes keep running (pre-suspension behavior).
+   */
+  suspendWhenHidden?: boolean;
+  /**
+   * Which surface presenter draws the scene's frames. `"canvas"` (default)
+   * paints onto a 2D `<canvas>`; `"dom"` renders cells as absolutely
+   * positioned text elements — native font rendering and, uniquely, real
+   * text selection: hold Alt/Option and drag to select instead of sending
+   * pointer input to the app. See {@link WebHostSurfaceRendererKind}.
+   */
+  renderer?: WebHostSurfaceRendererKind;
 }
 type WheelMode = "capture" | "chain" | "passive";
 /**
@@ -63,10 +81,13 @@ declare class WebHostSceneRuntime {
   private readonly onFrameDiagnostic?;
   private readonly synchronizeAccessibilityFocus;
   private readonly wheelMode;
+  private readonly rendererKind;
   private readonly painter;
   private readonly inputEncoder;
   private currentStyle;
   private canvas?;
+  private domSurfaceRoot?;
+  private lastDomSurfaceSize?;
   private accessibilityTree?;
   private diagnosticText?;
   private resizeObserver?;
@@ -82,9 +103,26 @@ declare class WebHostSceneRuntime {
   private pointerDownLinkTarget?;
   private lastSentResize?;
   private isVisible;
+  private documentVisible;
+  private runtimeSuspended;
+  private readonly suspendWhenHidden;
   constructor(options: WebHostSceneRuntimeOptions);
   mount(): Promise<void>;
   setVisible(visible: boolean): void;
+  /**
+   * Reports whether the surrounding document can be seen at all (browser tab
+   * visible, iframe on-screen, …). Combined with the scene-level
+   * `setVisible`: the app is suspended while either says hidden, unless
+   * `suspendWhenHidden` is `false`.
+   */
+  setDocumentVisible(visible: boolean): void;
+  private updateRuntimeSuspension;
+  /**
+   * Suspension hook for subclasses that own an app execution vehicle (the
+   * WASI worker / JSPI executor). The base runtime only presents frames, so
+   * it has nothing to suspend.
+   */
+  protected onRuntimeSuspensionChange(_suspended: boolean): void;
   setStyle(style: WebHostTerminalStyle): void;
   resize(columns: number, rows: number): void;
   writeOutput(text: string): void;
@@ -112,17 +150,26 @@ declare class WebHostSceneRuntime {
   private linkTarget;
   private openHyperlink;
   private applyStyle;
+  /** The element the active painter presents frames into. */
+  private get surfaceElement();
   private applyVisibility;
   private installResizeObserver;
   private installInputHandlers;
   private resizeToMount;
   private sendResizeIfNeeded;
-  private resizeCanvas;
+  private resizeSurface;
   private measureCells;
   private draw;
   private syncAccessibilityTree;
   private surfaceMetrics;
   private pointerMetrics;
+  /**
+   * Whether this pointer event should be left to the browser for native text
+   * selection instead of being forwarded to the app. Only the DOM renderer
+   * has real text nodes to select, and only while Alt/Option is held — plain
+   * pointer input still belongs to the app.
+   */
+  private allowsNativeTextSelection;
   private cellLocation;
   private rawCellLocation;
 }

package/dist/src/WebHostSceneRuntime.js

@@ -1,5 +1,6 @@
 import { applyWebHostTerminalStyle, normalizeWebHostTerminalStyle, webTUITerminalBackgroundColor } from "./WebHostTerminalStyle.js";
 import { CanvasSurfacePainter, fontForStyle } from "./CanvasSurfacePainter.js";
+import { DomSurfacePainter } from "./DomSurfacePainter.js";
 import { InputEventEncoder } from "./InputEventEncoder.js";
 import { cellLocationForEvent, linkTargetAt, rawCellLocationForEvent, wheelTargetCanScroll } from "./PointerGeometry.js";
 import { AccessibilityTreeMounter } from "./AccessibilityTree.js";
@@ -30,10 +31,13 @@ var WebHostSceneRuntime = class {
 	onFrameDiagnostic;
 	synchronizeAccessibilityFocus;
 	wheelMode;
-	painter = new CanvasSurfacePainter();
+	rendererKind;
+	painter;
 	inputEncoder = new InputEventEncoder();
 	currentStyle;
 	canvas;
+	domSurfaceRoot;
+	lastDomSurfaceSize;
 	accessibilityTree;
 	diagnosticText;
 	resizeObserver;
@@ -49,6 +53,9 @@ var WebHostSceneRuntime = class {
 	pointerDownLinkTarget;
 	lastSentResize;
 	isVisible = false;
+	documentVisible = true;
+	runtimeSuspended = false;
+	suspendWhenHidden;
 	constructor(options) {
 		this.descriptor = options.descriptor;
 		this.currentStyle = normalizeWebHostTerminalStyle(options.style);
@@ -57,7 +64,10 @@ var WebHostSceneRuntime = class {
 		this.onFrameDiagnostic = options.onFrameDiagnostic;
 		this.synchronizeAccessibilityFocus = options.synchronizeAccessibilityFocus ?? true;
 		this.wheelMode = options.wheelMode ?? legacyWheelMode(options.captureWheelInput);
+		this.rendererKind = options.renderer ?? "canvas";
+		this.painter = this.rendererKind === "dom" ? new DomSurfacePainter() : new CanvasSurfacePainter();
 		this.onOpenHyperlink = options.onOpenHyperlink;
+		this.suspendWhenHidden = options.suspendWhenHidden ?? true;
 		this.element = document.createElement("section");
 		this.element.className = "webhost-scene";
 		this.element.dataset.sceneId = options.descriptor.id;
@@ -73,14 +83,22 @@ var WebHostSceneRuntime = class {
 		this.applyVisibility();
 	}
 	async mount() {
-		if (this.canvas) return;
-		const canvas = document.createElement("canvas");
-		canvas.className = "webhost-scene__surface";
-		canvas.setAttribute("aria-hidden", "true");
-		this.canvas = canvas;
-		this.painter.attach(canvas, () => this.draw());
+		if (this.surfaceElement) return;
+		if (this.painter instanceof DomSurfacePainter) {
+			const surfaceRoot = document.createElement("div");
+			surfaceRoot.className = "webhost-scene__surface webhost-scene__surface--dom";
+			surfaceRoot.setAttribute("aria-hidden", "true");
+			this.domSurfaceRoot = surfaceRoot;
+			this.painter.attach(surfaceRoot);
+		} else {
+			const canvas = document.createElement("canvas");
+			canvas.className = "webhost-scene__surface";
+			canvas.setAttribute("aria-hidden", "true");
+			this.canvas = canvas;
+			this.painter.attach(canvas, () => this.draw());
+		}
 		this.accessibilityTree = new AccessibilityTreeMounter();
-		this.terminalMount.replaceChildren(canvas, this.accessibilityTree.element, this.accessibilityTree.announcerElement);
+		this.terminalMount.replaceChildren(this.surfaceElement, this.accessibilityTree.element, this.accessibilityTree.announcerElement);
 		this.installInputHandlers();
 		this.installResizeObserver();
 		this.bridge?.bindOutput({
@@ -104,7 +122,30 @@ var WebHostSceneRuntime = class {
 			this.resizeToMount();
 			if (this.synchronizeAccessibilityFocus) this.terminalMount.focus?.({ preventScroll: true });
 		}
+		this.updateRuntimeSuspension();
+	}
+	/**
+	* Reports whether the surrounding document can be seen at all (browser tab
+	* visible, iframe on-screen, …). Combined with the scene-level
+	* `setVisible`: the app is suspended while either says hidden, unless
+	* `suspendWhenHidden` is `false`.
+	*/
+	setDocumentVisible(visible) {
+		this.documentVisible = visible;
+		this.updateRuntimeSuspension();
 	}
+	updateRuntimeSuspension() {
+		const suspended = this.suspendWhenHidden && (!this.isVisible || !this.documentVisible);
+		if (suspended === this.runtimeSuspended) return;
+		this.runtimeSuspended = suspended;
+		this.onRuntimeSuspensionChange(suspended);
+	}
+	/**
+	* Suspension hook for subclasses that own an app execution vehicle (the
+	* WASI worker / JSPI executor). The base runtime only presents frames, so
+	* it has nothing to suspend.
+	*/
+	onRuntimeSuspensionChange(_suspended) {}
 	setStyle(style) {
 		this.currentStyle = normalizeWebHostTerminalStyle(style);
 		this.applyStyle(this.currentStyle);
@@ -117,7 +158,7 @@ var WebHostSceneRuntime = class {
 	resize(columns, rows) {
 		this.columns = Math.max(1, Math.round(columns));
 		this.rows = Math.max(1, Math.round(rows));
-		this.resizeCanvas();
+		this.resizeSurface();
 		this.draw();
 		this.syncAccessibilityTree();
 	}
@@ -156,7 +197,7 @@ var WebHostSceneRuntime = class {
 		this.currentFrame = frame;
 		this.columns = Math.max(1, Math.round(frame.width));
 		this.rows = Math.max(1, Math.round(frame.height));
-		const resized = this.resizeCanvas();
+		const resized = this.resizeSurface();
 		this.draw(previousFrame && !resized ? frame.damage : void 0);
 		this.syncAccessibilityTree();
 	}
@@ -211,6 +252,14 @@ var WebHostSceneRuntime = class {
 			this.canvas.style.width = "100%";
 			this.canvas.style.height = "100%";
 		}
+		if (this.domSurfaceRoot) {
+			this.domSurfaceRoot.style.display = "block";
+			this.domSurfaceRoot.style.position = "relative";
+		}
+	}
+	/** The element the active painter presents frames into. */
+	get surfaceElement() {
+		return this.canvas ?? this.domSurfaceRoot;
 	}
 	applyVisibility() {
 		this.element.hidden = !this.isVisible;
@@ -238,6 +287,7 @@ var WebHostSceneRuntime = class {
 			event.preventDefault();
 		};
 		const handlePointerDown = (event) => {
+			if (this.allowsNativeTextSelection(event)) return;
 			const location = this.cellLocation(event);
 			if (!location) return;
 			const button = this.inputEncoder.pointerButton(event.button);
@@ -250,6 +300,7 @@ var WebHostSceneRuntime = class {
 			event.preventDefault();
 		};
 		const handlePointerUp = (event) => {
+			if (!this.hasCapturedPointer && this.allowsNativeTextSelection(event)) return;
 			const location = this.hasCapturedPointer ? this.rawCellLocation(event) : this.cellLocation(event);
 			this.terminalMount.releasePointerCapture?.(event.pointerId);
 			this.hasCapturedPointer = false;
@@ -262,6 +313,7 @@ var WebHostSceneRuntime = class {
 			event.preventDefault();
 		};
 		const handlePointerMove = (event) => {
+			if (!this.hasCapturedPointer && this.allowsNativeTextSelection(event)) return;
 			const location = event.buttons && this.hasCapturedPointer ? this.rawCellLocation(event) : this.cellLocation(event);
 			if (!location) return;
 			if (!this.hasCapturedPointer) this.terminalMount.style.cursor = this.linkTarget(location) !== void 0 ? "pointer" : "";
@@ -300,7 +352,7 @@ var WebHostSceneRuntime = class {
 		this.columns = nextColumns;
 		this.rows = nextRows;
 		this.sendResizeIfNeeded();
-		this.resizeCanvas();
+		this.resizeSurface();
 	}
 	sendResizeIfNeeded() {
 		const current = {
@@ -313,10 +365,21 @@ var WebHostSceneRuntime = class {
 		this.lastSentResize = current;
 		this.bridge?.resize(current.columns, current.rows, current.cellWidth, current.cellHeight);
 	}
-	resizeCanvas() {
-		if (!this.canvas) return false;
+	resizeSurface() {
 		const cssWidth = Math.max(1, this.columns * this.cellWidth);
 		const cssHeight = Math.max(1, this.rows * this.cellHeight);
+		if (this.domSurfaceRoot) {
+			const last = this.lastDomSurfaceSize;
+			if (last && last.width === cssWidth && last.height === cssHeight) return false;
+			this.lastDomSurfaceSize = {
+				width: cssWidth,
+				height: cssHeight
+			};
+			this.domSurfaceRoot.style.width = `${cssWidth}px`;
+			this.domSurfaceRoot.style.height = `${cssHeight}px`;
+			return true;
+		}
+		if (!this.canvas) return false;
 		const scale = globalThis.window?.devicePixelRatio || 1;
 		const width = Math.ceil(cssWidth * scale);
 		const height = Math.ceil(cssHeight * scale);
@@ -362,13 +425,22 @@ var WebHostSceneRuntime = class {
 	}
 	pointerMetrics() {
 		return {
-			rect: this.canvas?.getBoundingClientRect?.() ?? this.terminalMount.getBoundingClientRect?.(),
+			rect: this.surfaceElement?.getBoundingClientRect?.() ?? this.terminalMount.getBoundingClientRect?.(),
 			cellWidth: this.cellWidth,
 			cellHeight: this.cellHeight,
 			columns: this.columns,
 			rows: this.rows
 		};
 	}
+	/**
+	* Whether this pointer event should be left to the browser for native text
+	* selection instead of being forwarded to the app. Only the DOM renderer
+	* has real text nodes to select, and only while Alt/Option is held — plain
+	* pointer input still belongs to the app.
+	*/
+	allowsNativeTextSelection(event) {
+		return this.rendererKind === "dom" && event.altKey;
+	}
 	cellLocation(event) {
 		return cellLocationForEvent(event, this.pointerMetrics());
 	}