@nextclaw/app-runtime 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NextClaw contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,50 @@
+# NextClaw App Runtime
+
+`@nextclaw/app-runtime` 是一个独立的微应用 runtime/CLI 包。
+
+当前 MVP 提供三件事：
+
+- `napp inspect <app-dir>`：校验应用目录与 manifest
+- `napp run <app-dir>`：启动本地宿主，提供 UI 静态服务和桥接 API
+- `napp dev <app-dir>`：当前等价于 `run`
+
+## 安装
+
+```bash
+npm install -g @nextclaw/app-runtime
+```
+
+安装后可用：
+
+```bash
+napp --help
+napp --version
+```
+
+第一版先聚焦“独立可运行的微应用宿主”，不接入现有 NextClaw 主产品路由、服务或传播层。
+
+## 应用目录
+
+```text
+manifest.json
+main/
+  app.wasm
+ui/
+  index.html
+assets/
+```
+
+## 当前 MVP 范围
+
+- `main` 执行形态：`wasm`
+- UI 装载：本地静态服务
+- 宿主桥接：`/__napp/*`
+- 权限词汇：`documentAccess`、`allowedDomains`、`storage`、`capabilities`
+- 当前 Wasm 执行底座：Node 原生 `WebAssembly`
+
+## 示例
+
+```bash
+napp inspect ./apps/examples/hello-notes
+napp run ./apps/examples/hello-notes --document notes=/absolute/path/to/notes
+```

package/dist/bridge/host-bridge.service.d.ts

@@ -0,0 +1,13 @@
+import { AppInstanceService } from "../host/app-instance.service.js";
+import { IncomingMessage, ServerResponse } from "node:http";
+
+//#region src/bridge/host-bridge.service.d.ts
+declare class HostBridgeServer {
+  private readonly appInstance;
+  constructor(appInstance: AppInstanceService);
+  handle: (request: IncomingMessage, response: ServerResponse) => Promise<boolean>;
+  private readJsonBody;
+  private writeJson;
+}
+//#endregion
+export { HostBridgeServer };

package/dist/bridge/host-bridge.service.js

@@ -0,0 +1,61 @@
+//#region src/bridge/host-bridge.service.ts
+var HostBridgeServer = class {
+	constructor(appInstance) {
+		this.appInstance = appInstance;
+	}
+	handle = async (request, response) => {
+		const requestUrl = new URL(request.url ?? "/", "http://127.0.0.1");
+		if (!requestUrl.pathname.startsWith("/__napp")) return false;
+		if (request.method === "GET" && requestUrl.pathname === "/__napp/health") {
+			this.writeJson(response, 200, { ok: true });
+			return true;
+		}
+		if (request.method === "GET" && requestUrl.pathname === "/__napp/manifest") {
+			this.writeJson(response, 200, {
+				ok: true,
+				manifest: this.appInstance.summarizeManifest()
+			});
+			return true;
+		}
+		if (request.method === "GET" && requestUrl.pathname === "/__napp/permissions") {
+			this.writeJson(response, 200, {
+				ok: true,
+				permissions: this.appInstance.summarizePermissions()
+			});
+			return true;
+		}
+		if (request.method === "POST" && requestUrl.pathname === "/__napp/run") {
+			const body = await this.readJsonBody(request);
+			const result = await this.appInstance.runAction(body.action);
+			this.writeJson(response, 200, {
+				ok: true,
+				result
+			});
+			return true;
+		}
+		this.writeJson(response, 404, {
+			ok: false,
+			error: {
+				code: "NOT_FOUND",
+				message: `Unknown bridge path: ${requestUrl.pathname}`
+			}
+		});
+		return true;
+	};
+	readJsonBody = async (request) => {
+		const chunks = [];
+		for await (const chunk of request) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+		const rawBody = Buffer.concat(chunks).toString("utf-8").trim();
+		if (!rawBody) return {};
+		return JSON.parse(rawBody);
+	};
+	writeJson = (response, statusCode, payload) => {
+		response.writeHead(statusCode, {
+			"content-type": "application/json; charset=utf-8",
+			"cache-control": "no-store"
+		});
+		response.end(JSON.stringify(payload, null, 2));
+	};
+};
+//#endregion
+export { HostBridgeServer };

package/dist/commands/dev.controller.js

@@ -0,0 +1,12 @@
+import { RunCommand } from "./run.controller.js";
+//#region src/commands/dev.controller.ts
+var DevCommand = class {
+	constructor(runCommand = new RunCommand()) {
+		this.runCommand = runCommand;
+	}
+	run = async (params) => {
+		await this.runCommand.run(params);
+	};
+};
+//#endregion
+export { DevCommand };

package/dist/commands/inspect.controller.js

@@ -0,0 +1,26 @@
+import { AppManifestService } from "../manifest/app-manifest.service.js";
+//#region src/commands/inspect.controller.ts
+var InspectCommand = class {
+	constructor(manifestService = new AppManifestService()) {
+		this.manifestService = manifestService;
+	}
+	run = async (params) => {
+		const { appDirectory, json, write } = params;
+		const bundle = await this.manifestService.load(appDirectory);
+		const summary = this.manifestService.summarize(bundle);
+		if (json) {
+			write(`${JSON.stringify({
+				ok: true,
+				summary
+			}, null, 2)}\n`);
+			return;
+		}
+		write(`App: ${summary.name} (${summary.id})\n`);
+		write(`Version: ${summary.version}\n`);
+		write(`Action: ${summary.action}\n`);
+		write(`Main: ${summary.mainEntryPath}\n`);
+		write(`UI: ${summary.uiEntryPath}\n`);
+	};
+};
+//#endregion
+export { InspectCommand };

package/dist/commands/run.controller.js

@@ -0,0 +1,40 @@
+import { AppHostService } from "../host/app-host.service.js";
+import { AppManifestService } from "../manifest/app-manifest.service.js";
+import { AppInstanceService } from "../host/app-instance.service.js";
+//#region src/commands/run.controller.ts
+var RunCommand = class {
+	constructor(manifestService = new AppManifestService()) {
+		this.manifestService = manifestService;
+	}
+	run = async (params) => {
+		const { appDirectory, host, port, json, documentGrantMap, write } = params;
+		const bundle = await this.manifestService.load(appDirectory);
+		const appInstance = new AppInstanceService(bundle);
+		await appInstance.initialize(documentGrantMap);
+		const appHost = new AppHostService(appInstance);
+		const hostHandle = await appHost.start({
+			host,
+			port
+		});
+		const shutdown = async () => {
+			await appHost.stop();
+			process.exit(0);
+		};
+		process.once("SIGINT", () => {
+			shutdown();
+		});
+		process.once("SIGTERM", () => {
+			shutdown();
+		});
+		if (json) {
+			write(`${JSON.stringify({
+				ok: true,
+				host: hostHandle
+			}, null, 2)}\n`);
+			return;
+		}
+		write(`[napp] ${bundle.manifest.name} listening on ${hostHandle.url}\n`);
+	};
+};
+//#endregion
+export { RunCommand };

package/dist/host/app-host.service.d.ts

@@ -0,0 +1,25 @@
+import { AppInstanceService } from "./app-instance.service.js";
+
+//#region src/host/app-host.service.d.ts
+type AppHostStartOptions = {
+  host: string;
+  port: number;
+};
+type AppHostHandle = {
+  appId: string;
+  url: string;
+  host: string;
+  port: number;
+};
+declare class AppHostService {
+  private readonly appInstance;
+  private server?;
+  private readonly bridgeServer;
+  private readonly uiServer;
+  constructor(appInstance: AppInstanceService);
+  start: (options: AppHostStartOptions) => Promise<AppHostHandle>;
+  stop: () => Promise<void>;
+  private handleRequest;
+}
+//#endregion
+export { AppHostHandle, AppHostService, AppHostStartOptions };

package/dist/host/app-host.service.js

@@ -0,0 +1,66 @@
+import { HostBridgeServer } from "../bridge/host-bridge.service.js";
+import { UiServerService } from "../ui/ui-server.service.js";
+import { createServer } from "node:http";
+//#region src/host/app-host.service.ts
+var AppHostService = class {
+	server;
+	bridgeServer;
+	uiServer;
+	constructor(appInstance) {
+		this.appInstance = appInstance;
+		this.bridgeServer = new HostBridgeServer(appInstance);
+		this.uiServer = new UiServerService(appInstance.bundle);
+	}
+	start = async (options) => {
+		if (this.server) throw new Error("应用宿主已经启动。");
+		const server = createServer((request, response) => {
+			this.handleRequest(request, response);
+		});
+		this.server = server;
+		await new Promise((resolve, reject) => {
+			server.once("error", reject);
+			server.listen(options.port, options.host, () => {
+				server.off("error", reject);
+				resolve();
+			});
+		});
+		const address = server.address();
+		if (!address || typeof address === "string") throw new Error("无法获取应用宿主监听地址。");
+		return {
+			appId: this.appInstance.bundle.manifest.id,
+			url: `http://${address.address}:${address.port}`,
+			host: address.address,
+			port: address.port
+		};
+	};
+	stop = async () => {
+		if (!this.server) return;
+		await new Promise((resolve, reject) => {
+			this.server?.close((error) => {
+				if (error) {
+					reject(error);
+					return;
+				}
+				resolve();
+			});
+		});
+		this.server = void 0;
+	};
+	handleRequest = async (request, response) => {
+		try {
+			if (await this.bridgeServer.handle(request, response)) return;
+			await this.uiServer.handle(request, response);
+		} catch (error) {
+			response.writeHead(500, { "content-type": "application/json; charset=utf-8" });
+			response.end(JSON.stringify({
+				ok: false,
+				error: {
+					code: "APP_HOST_ERROR",
+					message: error instanceof Error ? error.message : String(error)
+				}
+			}, null, 2));
+		}
+	};
+};
+//#endregion
+export { AppHostService };

package/dist/host/app-instance.service.d.ts

@@ -0,0 +1,31 @@
+import { AppManifestBundle, AppManifestSummary } from "../manifest/app-manifest.types.js";
+import { AppManifestService } from "../manifest/app-manifest.service.js";
+import { AppDocumentGrantMap, AppPermissionSummary } from "../permissions/app-permissions.types.js";
+import { AppPermissionsService } from "../permissions/app-permissions.service.js";
+import { MainRunResult, WasmDocumentSummaryInput } from "../runtime/main-runner.types.js";
+import { WasmMainRunnerService } from "../runtime/wasm-main-runner.service.js";
+
+//#region src/host/app-instance.service.d.ts
+type AppRunResult = {
+  action: string;
+  input: WasmDocumentSummaryInput;
+  output: MainRunResult;
+  observedAt: string;
+};
+declare class AppInstanceService {
+  readonly bundle: AppManifestBundle;
+  private readonly permissionsService;
+  private readonly mainRunner;
+  private readonly manifestService;
+  private permissions?;
+  constructor(bundle: AppManifestBundle, permissionsService?: AppPermissionsService, mainRunner?: WasmMainRunnerService, manifestService?: AppManifestService);
+  initialize: (documentGrantMap: AppDocumentGrantMap) => Promise<void>;
+  summarizeManifest: () => AppManifestSummary;
+  summarizePermissions: () => AppPermissionSummary;
+  runAction: (action?: string) => Promise<AppRunResult>;
+  private collectDocumentSummaryInput;
+  private collectDirectorySummary;
+  private getPermissions;
+}
+//#endregion
+export { AppInstanceService, AppRunResult };

package/dist/host/app-instance.service.js

@@ -0,0 +1,80 @@
+import { AppManifestService } from "../manifest/app-manifest.service.js";
+import { AppPermissionsService } from "../permissions/app-permissions.service.js";
+import { WasmMainRunnerService } from "../runtime/wasm-main-runner.service.js";
+import { readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+//#region src/host/app-instance.service.ts
+var AppInstanceService = class {
+	permissions;
+	constructor(bundle, permissionsService = new AppPermissionsService(), mainRunner = new WasmMainRunnerService(), manifestService = new AppManifestService()) {
+		this.bundle = bundle;
+		this.permissionsService = permissionsService;
+		this.mainRunner = mainRunner;
+		this.manifestService = manifestService;
+	}
+	initialize = async (documentGrantMap) => {
+		this.permissions = await this.permissionsService.resolve(this.bundle, documentGrantMap);
+	};
+	summarizeManifest = () => {
+		return this.manifestService.summarize(this.bundle);
+	};
+	summarizePermissions = () => {
+		return this.permissionsService.summarize(this.bundle, this.getPermissions());
+	};
+	runAction = async (action) => {
+		const expectedAction = this.bundle.manifest.main.action;
+		if (action && action !== expectedAction) throw new Error(`当前应用只支持动作 ${expectedAction}。`);
+		const input = await this.collectDocumentSummaryInput();
+		return {
+			action: expectedAction,
+			input,
+			output: await this.mainRunner.runDocumentSummary({
+				bundle: this.bundle,
+				input
+			}),
+			observedAt: (/* @__PURE__ */ new Date()).toISOString()
+		};
+	};
+	collectDocumentSummaryInput = async () => {
+		const permissions = this.getPermissions();
+		let documentCount = 0;
+		let textBytes = 0;
+		for (const grant of permissions.documentAccess) {
+			const scopeSummary = await this.collectDirectorySummary(grant.path);
+			documentCount += scopeSummary.documentCount;
+			textBytes += scopeSummary.textBytes;
+		}
+		return {
+			documentCount,
+			textBytes
+		};
+	};
+	collectDirectorySummary = async (directoryPath) => {
+		const entries = await readdir(directoryPath, { withFileTypes: true });
+		let documentCount = 0;
+		let textBytes = 0;
+		for (const entry of entries) {
+			const entryPath = path.join(directoryPath, entry.name);
+			if (entry.isDirectory()) {
+				const childSummary = await this.collectDirectorySummary(entryPath);
+				documentCount += childSummary.documentCount;
+				textBytes += childSummary.textBytes;
+				continue;
+			}
+			if (!entry.isFile()) continue;
+			const content = await readFile(entryPath, "utf-8");
+			documentCount += 1;
+			textBytes += Buffer.byteLength(content, "utf-8");
+		}
+		return {
+			documentCount,
+			textBytes
+		};
+	};
+	getPermissions = () => {
+		if (!this.permissions) throw new Error("应用实例尚未初始化权限。");
+		return this.permissions;
+	};
+};
+//#endregion
+export { AppInstanceService };

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+import { AppDocumentAccessMode, AppDocumentAccessScope, AppMainManifest, AppManifest, AppManifestBundle, AppManifestSummary, AppPermissions, AppUiManifest } from "./manifest/app-manifest.types.js";
+import { AppManifestService } from "./manifest/app-manifest.service.js";
+import { AppDocumentGrantMap, AppPermissionSummary, ResolvedDocumentGrant, ResolvedPermissions } from "./permissions/app-permissions.types.js";
+import { AppPermissionsService } from "./permissions/app-permissions.service.js";
+import { MainRunRequest, MainRunResult, WasmDocumentSummaryInput } from "./runtime/main-runner.types.js";
+import { MainRunnerService } from "./runtime/main-runner.service.js";
+import { WasmSidecarClientService } from "./sidecar/wasm-sidecar-client.service.js";
+import { WasmMainRunnerService } from "./runtime/wasm-main-runner.service.js";
+import { AppInstanceService, AppRunResult } from "./host/app-instance.service.js";
+import { HostBridgeServer } from "./bridge/host-bridge.service.js";
+import { AppHostHandle, AppHostService, AppHostStartOptions } from "./host/app-host.service.js";
+import { UiServerService } from "./ui/ui-server.service.js";
+export { AppDocumentAccessMode, AppDocumentAccessScope, AppDocumentGrantMap, AppHostHandle, AppHostService, AppHostStartOptions, AppInstanceService, AppMainManifest, AppManifest, AppManifestBundle, AppManifestService, AppManifestSummary, AppPermissionSummary, AppPermissions, AppPermissionsService, AppRunResult, AppUiManifest, HostBridgeServer, MainRunRequest, MainRunResult, MainRunnerService, ResolvedDocumentGrant, ResolvedPermissions, UiServerService, WasmDocumentSummaryInput, WasmMainRunnerService, WasmSidecarClientService };

package/dist/index.js

@@ -0,0 +1,10 @@
+import { HostBridgeServer } from "./bridge/host-bridge.service.js";
+import { UiServerService } from "./ui/ui-server.service.js";
+import { AppHostService } from "./host/app-host.service.js";
+import { AppManifestService } from "./manifest/app-manifest.service.js";
+import { AppPermissionsService } from "./permissions/app-permissions.service.js";
+import { MainRunnerService } from "./runtime/main-runner.service.js";
+import { WasmSidecarClientService } from "./sidecar/wasm-sidecar-client.service.js";
+import { WasmMainRunnerService } from "./runtime/wasm-main-runner.service.js";
+import { AppInstanceService } from "./host/app-instance.service.js";
+export { AppHostService, AppInstanceService, AppManifestService, AppPermissionsService, HostBridgeServer, MainRunnerService, UiServerService, WasmMainRunnerService, WasmSidecarClientService };

package/dist/main.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/main.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+import { version } from "./package.js";
+import { RunCommand } from "./commands/run.controller.js";
+import { DevCommand } from "./commands/dev.controller.js";
+import { InspectCommand } from "./commands/inspect.controller.js";
+//#region src/main.ts
+var AppRuntimeCli = class {
+	run = async () => {
+		const [command, appDirectory, ...restArgs] = process.argv.slice(2);
+		if (command === "--help" || command === "help") {
+			this.writeUsage();
+			return;
+		}
+		if (command === "--version" || command === "version") {
+			this.write(`${version}\n`);
+			return;
+		}
+		if (!command || !appDirectory) {
+			this.writeUsage();
+			process.exit(1);
+		}
+		const options = this.readOptions(restArgs);
+		if (command === "inspect") {
+			await new InspectCommand().run({
+				appDirectory,
+				json: options.json,
+				write: this.write
+			});
+			return;
+		}
+		if (command === "run") {
+			await new RunCommand().run({
+				appDirectory,
+				host: options.host,
+				port: options.port,
+				json: options.json,
+				documentGrantMap: options.documentGrantMap,
+				write: this.write
+			});
+			return;
+		}
+		if (command === "dev") {
+			await new DevCommand().run({
+				appDirectory,
+				host: options.host,
+				port: options.port,
+				json: options.json,
+				documentGrantMap: options.documentGrantMap,
+				write: this.write
+			});
+			return;
+		}
+		this.writeUsage();
+		process.exit(1);
+	};
+	readOptions = (rawArgs) => {
+		const options = {
+			host: "127.0.0.1",
+			port: 3100,
+			json: false,
+			documentGrantMap: {}
+		};
+		for (let index = 0; index < rawArgs.length; index += 1) {
+			const current = rawArgs[index];
+			if (!current?.startsWith("--")) continue;
+			const nextValue = rawArgs[index + 1];
+			switch (current) {
+				case "--host":
+					options.host = this.requireOptionValue(current, nextValue);
+					index += 1;
+					break;
+				case "--port":
+					options.port = Number.parseInt(this.requireOptionValue(current, nextValue), 10);
+					if (Number.isNaN(options.port) || options.port < 0) throw new Error("--port 必须是非负整数。");
+					index += 1;
+					break;
+				case "--json":
+					options.json = true;
+					break;
+				case "--document":
+					this.assignDocumentGrant(options.documentGrantMap, this.requireOptionValue(current, nextValue));
+					index += 1;
+					break;
+				default: throw new Error(`未知参数：${current}`);
+			}
+		}
+		return options;
+	};
+	assignDocumentGrant = (documentGrantMap, rawGrant) => {
+		const delimiterIndex = rawGrant.indexOf("=");
+		if (delimiterIndex < 1) throw new Error("--document 必须使用 scopeId=/absolute/or/relative/path 格式。");
+		const scopeId = rawGrant.slice(0, delimiterIndex).trim();
+		const directoryPath = rawGrant.slice(delimiterIndex + 1).trim();
+		if (!scopeId || !directoryPath) throw new Error("--document 缺少 scopeId 或 path。");
+		documentGrantMap[scopeId] = directoryPath;
+	};
+	requireOptionValue = (flag, nextValue) => {
+		if (!nextValue || nextValue.startsWith("--")) throw new Error(`${flag} 缺少值。`);
+		return nextValue;
+	};
+	writeUsage = () => {
+		this.write("Usage: napp <inspect|run|dev> <app-dir> [--host 127.0.0.1] [--port 3100] [--json] [--document scope=/path]\n");
+		this.write("       napp --help\n");
+		this.write("       napp --version\n");
+	};
+	write = (text) => {
+		process.stdout.write(text);
+	};
+};
+new AppRuntimeCli().run();
+//#endregion
+export {};

package/dist/manifest/app-manifest.service.d.ts

@@ -0,0 +1,23 @@
+import { AppManifestBundle, AppManifestSummary } from "./app-manifest.types.js";
+
+//#region src/manifest/app-manifest.service.d.ts
+declare class AppManifestService {
+  load: (appDirectory: string) => Promise<AppManifestBundle>;
+  summarize: (bundle: AppManifestBundle) => AppManifestSummary;
+  private parseManifest;
+  private parseMain;
+  private parseUi;
+  private parsePermissions;
+  private parseDocumentAccess;
+  private parseStringArray;
+  private parseStorage;
+  private parseCapabilities;
+  private assertResolvedFile;
+  private assertObject;
+  private readRequiredString;
+  private readOptionalString;
+  private readNumber;
+  private readBoolean;
+}
+//#endregion
+export { AppManifestService };

package/dist/manifest/app-manifest.service.js

@@ -0,0 +1,139 @@
+import { access, readFile } from "node:fs/promises";
+import path from "node:path";
+//#region src/manifest/app-manifest.service.ts
+var AppManifestService = class {
+	load = async (appDirectory) => {
+		const normalizedDirectory = path.resolve(appDirectory);
+		const manifestPath = path.join(normalizedDirectory, "manifest.json");
+		const rawManifest = JSON.parse(await readFile(manifestPath, "utf-8"));
+		const manifest = this.parseManifest(rawManifest);
+		const mainEntryPath = await this.assertResolvedFile(normalizedDirectory, manifest.main.entry, "main.entry");
+		const uiEntryPath = await this.assertResolvedFile(normalizedDirectory, manifest.ui.entry, "ui.entry");
+		return {
+			appDirectory: normalizedDirectory,
+			manifestPath,
+			manifest,
+			mainEntryPath,
+			uiEntryPath,
+			uiDirectoryPath: path.dirname(uiEntryPath),
+			assetsDirectoryPath: path.join(normalizedDirectory, "assets"),
+			iconPath: manifest.icon ? await this.assertResolvedFile(normalizedDirectory, manifest.icon, "icon") : void 0
+		};
+	};
+	summarize = (bundle) => {
+		const permissions = bundle.manifest.permissions ?? {};
+		return {
+			id: bundle.manifest.id,
+			name: bundle.manifest.name,
+			version: bundle.manifest.version,
+			description: bundle.manifest.description,
+			action: bundle.manifest.main.action,
+			manifestPath: bundle.manifestPath,
+			mainEntryPath: bundle.mainEntryPath,
+			uiEntryPath: bundle.uiEntryPath,
+			iconPath: bundle.iconPath,
+			permissions
+		};
+	};
+	parseManifest = (rawManifest) => {
+		if (!rawManifest || typeof rawManifest !== "object" || Array.isArray(rawManifest)) throw new Error("manifest.json 必须是一个对象。");
+		const candidate = rawManifest;
+		if (this.readNumber(candidate.schemaVersion, "schemaVersion") !== 1) throw new Error("当前只支持 schemaVersion = 1。");
+		const permissions = this.parsePermissions(candidate.permissions);
+		return {
+			schemaVersion: 1,
+			id: this.readRequiredString(candidate.id, "id"),
+			name: this.readRequiredString(candidate.name, "name"),
+			version: this.readRequiredString(candidate.version, "version"),
+			description: this.readOptionalString(candidate.description, "description"),
+			icon: this.readOptionalString(candidate.icon, "icon"),
+			main: this.parseMain(candidate.main),
+			ui: this.parseUi(candidate.ui),
+			permissions
+		};
+	};
+	parseMain = (rawMain) => {
+		const candidate = this.assertObject(rawMain, "main");
+		if (this.readRequiredString(candidate.kind, "main.kind") !== "wasm") throw new Error("当前 main.kind 只支持 wasm。");
+		return {
+			kind: "wasm",
+			entry: this.readRequiredString(candidate.entry, "main.entry"),
+			export: this.readRequiredString(candidate.export, "main.export"),
+			action: this.readRequiredString(candidate.action, "main.action")
+		};
+	};
+	parseUi = (rawUi) => {
+		const candidate = this.assertObject(rawUi, "ui");
+		return { entry: this.readRequiredString(candidate.entry, "ui.entry") };
+	};
+	parsePermissions = (rawPermissions) => {
+		if (rawPermissions === void 0) return;
+		const candidate = this.assertObject(rawPermissions, "permissions");
+		return {
+			documentAccess: this.parseDocumentAccess(candidate.documentAccess),
+			allowedDomains: this.parseStringArray(candidate.allowedDomains, "permissions.allowedDomains"),
+			storage: this.parseStorage(candidate.storage),
+			capabilities: this.parseCapabilities(candidate.capabilities)
+		};
+	};
+	parseDocumentAccess = (rawDocumentAccess) => {
+		if (rawDocumentAccess === void 0) return;
+		if (!Array.isArray(rawDocumentAccess)) throw new Error("permissions.documentAccess 必须是数组。");
+		return rawDocumentAccess.map((scope, index) => {
+			const candidate = this.assertObject(scope, `permissions.documentAccess[${index}]`);
+			const mode = this.readRequiredString(candidate.mode, `permissions.documentAccess[${index}].mode`);
+			if (mode !== "read" && mode !== "read-write") throw new Error(`permissions.documentAccess[${index}].mode 只支持 read 或 read-write。`);
+			return {
+				id: this.readRequiredString(candidate.id, `permissions.documentAccess[${index}].id`),
+				mode,
+				description: this.readOptionalString(candidate.description, `permissions.documentAccess[${index}].description`)
+			};
+		});
+	};
+	parseStringArray = (rawValue, fieldName) => {
+		if (rawValue === void 0) return;
+		if (!Array.isArray(rawValue)) throw new Error(`${fieldName} 必须是字符串数组。`);
+		return rawValue.map((item, index) => this.readRequiredString(item, `${fieldName}[${index}]`));
+	};
+	parseStorage = (rawStorage) => {
+		if (rawStorage === void 0) return;
+		if (typeof rawStorage === "boolean") return rawStorage;
+		const candidate = this.assertObject(rawStorage, "permissions.storage");
+		return { namespace: this.readOptionalString(candidate.namespace, "permissions.storage.namespace") };
+	};
+	parseCapabilities = (rawCapabilities) => {
+		if (rawCapabilities === void 0) return;
+		const candidate = this.assertObject(rawCapabilities, "permissions.capabilities");
+		return { hostBridge: candidate.hostBridge === void 0 ? void 0 : this.readBoolean(candidate.hostBridge, "permissions.capabilities.hostBridge") };
+	};
+	assertResolvedFile = async (appDirectory, relativePath, fieldName) => {
+		if (path.isAbsolute(relativePath)) throw new Error(`${fieldName} 必须使用应用目录内的相对路径。`);
+		const resolvedPath = path.resolve(appDirectory, relativePath);
+		const relative = path.relative(appDirectory, resolvedPath);
+		if (relative.startsWith("..") || path.isAbsolute(relative)) throw new Error(`${fieldName} 不能指向应用目录之外。`);
+		await access(resolvedPath);
+		return resolvedPath;
+	};
+	assertObject = (value, fieldName) => {
+		if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${fieldName} 必须是对象。`);
+		return value;
+	};
+	readRequiredString = (value, fieldName) => {
+		if (typeof value !== "string" || !value.trim()) throw new Error(`${fieldName} 必须是非空字符串。`);
+		return value.trim();
+	};
+	readOptionalString = (value, fieldName) => {
+		if (value === void 0) return;
+		return this.readRequiredString(value, fieldName);
+	};
+	readNumber = (value, fieldName) => {
+		if (typeof value !== "number" || Number.isNaN(value)) throw new Error(`${fieldName} 必须是数字。`);
+		return value;
+	};
+	readBoolean = (value, fieldName) => {
+		if (typeof value !== "boolean") throw new Error(`${fieldName} 必须是布尔值。`);
+		return value;
+	};
+};
+//#endregion
+export { AppManifestService };

package/dist/manifest/app-manifest.types.d.ts

@@ -0,0 +1,61 @@
+//#region src/manifest/app-manifest.types.d.ts
+type AppDocumentAccessMode = "read" | "read-write";
+type AppDocumentAccessScope = {
+  id: string;
+  mode: AppDocumentAccessMode;
+  description?: string;
+};
+type AppPermissions = {
+  documentAccess?: AppDocumentAccessScope[];
+  allowedDomains?: string[];
+  storage?: boolean | {
+    namespace?: string;
+  };
+  capabilities?: {
+    hostBridge?: boolean;
+  };
+};
+type AppMainManifest = {
+  kind: "wasm";
+  entry: string;
+  export: string;
+  action: string;
+};
+type AppUiManifest = {
+  entry: string;
+};
+type AppManifest = {
+  schemaVersion: 1;
+  id: string;
+  name: string;
+  version: string;
+  description?: string;
+  icon?: string;
+  main: AppMainManifest;
+  ui: AppUiManifest;
+  permissions?: AppPermissions;
+};
+type AppManifestBundle = {
+  appDirectory: string;
+  manifestPath: string;
+  manifest: AppManifest;
+  mainEntryPath: string;
+  uiEntryPath: string;
+  uiDirectoryPath: string;
+  assetsDirectoryPath: string;
+  iconPath?: string;
+};
+type AppManifestSummary = {
+  id: string;
+  name: string;
+  version: string;
+  description?: string;
+  action: string;
+  manifestPath: string;
+  mainEntryPath: string;
+  uiEntryPath: string;
+  iconPath?: string;
+  permissions: AppPermissions;
+};
+//#endregion
+export { AppDocumentAccessMode, AppDocumentAccessScope, AppMainManifest, AppManifest, AppManifestBundle, AppManifestSummary, AppPermissions, AppUiManifest };

package/dist/package.js

@@ -0,0 +1,4 @@
+//#region package.json
+var version = "0.1.0";
+//#endregion
+export { version };

package/dist/permissions/app-permissions.service.d.ts

@@ -0,0 +1,11 @@
+import { AppManifestBundle } from "../manifest/app-manifest.types.js";
+import { AppDocumentGrantMap, AppPermissionSummary, ResolvedPermissions } from "./app-permissions.types.js";
+
+//#region src/permissions/app-permissions.service.d.ts
+declare class AppPermissionsService {
+  resolve: (bundle: AppManifestBundle, documentGrantMap: AppDocumentGrantMap) => Promise<ResolvedPermissions>;
+  summarize: (bundle: AppManifestBundle, permissions: ResolvedPermissions) => AppPermissionSummary;
+  private resolveDocumentGrant;
+}
+//#endregion
+export { AppPermissionsService };

package/dist/permissions/app-permissions.service.js

@@ -0,0 +1,40 @@
+import { access } from "node:fs/promises";
+import path from "node:path";
+//#region src/permissions/app-permissions.service.ts
+var AppPermissionsService = class {
+	resolve = async (bundle, documentGrantMap) => {
+		const requestedPermissions = bundle.manifest.permissions ?? {};
+		return {
+			documentAccess: requestedPermissions.documentAccess === void 0 ? [] : await Promise.all(requestedPermissions.documentAccess.map((scope) => this.resolveDocumentGrant(scope, documentGrantMap))),
+			allowedDomains: requestedPermissions.allowedDomains ?? [],
+			storage: {
+				enabled: requestedPermissions.storage !== void 0 && requestedPermissions.storage !== false,
+				namespace: typeof requestedPermissions.storage === "object" ? requestedPermissions.storage.namespace : void 0
+			},
+			capabilities: { hostBridge: requestedPermissions.capabilities?.hostBridge !== false }
+		};
+	};
+	summarize = (bundle, permissions) => {
+		return {
+			requested: bundle.manifest.permissions ?? {},
+			documentAccess: permissions.documentAccess,
+			allowedDomains: permissions.allowedDomains,
+			storage: permissions.storage,
+			capabilities: permissions.capabilities
+		};
+	};
+	resolveDocumentGrant = async (scope, documentGrantMap) => {
+		const grantedPath = documentGrantMap[scope.id];
+		if (!grantedPath) throw new Error(`缺少 documentAccess 授权：${scope.id}`);
+		const normalizedPath = path.resolve(grantedPath);
+		await access(normalizedPath);
+		return {
+			id: scope.id,
+			mode: scope.mode,
+			description: scope.description,
+			path: normalizedPath
+		};
+	};
+};
+//#endregion
+export { AppPermissionsService };

package/dist/permissions/app-permissions.types.d.ts

@@ -0,0 +1,26 @@
+import { AppPermissions } from "../manifest/app-manifest.types.js";
+
+//#region src/permissions/app-permissions.types.d.ts
+type AppDocumentGrantMap = Record<string, string>;
+type ResolvedDocumentGrant = {
+  id: string;
+  mode: "read" | "read-write";
+  description?: string;
+  path: string;
+};
+type ResolvedPermissions = {
+  documentAccess: ResolvedDocumentGrant[];
+  allowedDomains: string[];
+  storage: {
+    enabled: boolean;
+    namespace?: string;
+  };
+  capabilities: {
+    hostBridge: boolean;
+  };
+};
+type AppPermissionSummary = Pick<ResolvedPermissions, "documentAccess" | "allowedDomains" | "storage" | "capabilities"> & {
+  requested: AppPermissions;
+};
+//#endregion
+export { AppDocumentGrantMap, AppPermissionSummary, ResolvedDocumentGrant, ResolvedPermissions };

package/dist/runtime/main-runner.service.d.ts

@@ -0,0 +1,8 @@
+import { MainRunRequest, MainRunResult } from "./main-runner.types.js";
+
+//#region src/runtime/main-runner.service.d.ts
+declare abstract class MainRunnerService {
+  abstract runDocumentSummary(request: MainRunRequest): Promise<MainRunResult>;
+}
+//#endregion
+export { MainRunnerService };

package/dist/runtime/main-runner.service.js

@@ -0,0 +1,4 @@
+//#region src/runtime/main-runner.service.ts
+var MainRunnerService = class {};
+//#endregion
+export { MainRunnerService };

package/dist/runtime/main-runner.types.d.ts

@@ -0,0 +1,17 @@
+import { AppManifestBundle } from "../manifest/app-manifest.types.js";
+
+//#region src/runtime/main-runner.types.d.ts
+type WasmDocumentSummaryInput = {
+  documentCount: number;
+  textBytes: number;
+};
+type MainRunRequest = {
+  bundle: AppManifestBundle;
+  input: WasmDocumentSummaryInput;
+};
+type MainRunResult = {
+  exportName: string;
+  output: number;
+};
+//#endregion
+export { MainRunRequest, MainRunResult, WasmDocumentSummaryInput };

package/dist/runtime/wasm-main-runner.service.d.ts

@@ -0,0 +1,12 @@
+import { MainRunRequest, MainRunResult } from "./main-runner.types.js";
+import { MainRunnerService } from "./main-runner.service.js";
+import { WasmSidecarClientService } from "../sidecar/wasm-sidecar-client.service.js";
+
+//#region src/runtime/wasm-main-runner.service.d.ts
+declare class WasmMainRunnerService extends MainRunnerService {
+  private readonly sidecarClient;
+  constructor(sidecarClient?: WasmSidecarClientService);
+  runDocumentSummary: (request: MainRunRequest) => Promise<MainRunResult>;
+}
+//#endregion
+export { WasmMainRunnerService };

package/dist/runtime/wasm-main-runner.service.js

@@ -0,0 +1,22 @@
+import { MainRunnerService } from "./main-runner.service.js";
+import { WasmSidecarClientService } from "../sidecar/wasm-sidecar-client.service.js";
+//#region src/runtime/wasm-main-runner.service.ts
+var WasmMainRunnerService = class extends MainRunnerService {
+	constructor(sidecarClient = new WasmSidecarClientService()) {
+		super();
+		this.sidecarClient = sidecarClient;
+	}
+	runDocumentSummary = async (request) => {
+		const output = await this.sidecarClient.runExport({
+			wasmPath: request.bundle.mainEntryPath,
+			exportName: request.bundle.manifest.main.export,
+			args: [request.input.documentCount, request.input.textBytes]
+		});
+		return {
+			exportName: request.bundle.manifest.main.export,
+			output
+		};
+	};
+};
+//#endregion
+export { WasmMainRunnerService };

package/dist/sidecar/wasm-sidecar-client.service.d.ts

@@ -0,0 +1,10 @@
+//#region src/sidecar/wasm-sidecar-client.service.d.ts
+declare class WasmSidecarClientService {
+  runExport: (params: {
+    wasmPath: string;
+    exportName: string;
+    args: number[];
+  }) => Promise<number>;
+}
+//#endregion
+export { WasmSidecarClientService };

package/dist/sidecar/wasm-sidecar-client.service.js

@@ -0,0 +1,17 @@
+import { readFile } from "node:fs/promises";
+//#region src/sidecar/wasm-sidecar-client.service.ts
+var WasmSidecarClientService = class {
+	runExport = async (params) => {
+		const { wasmPath, exportName, args } = params;
+		const wasmBytes = await readFile(wasmPath);
+		const wasmRuntime = globalThis.WebAssembly;
+		if (!wasmRuntime) throw new Error("当前 Node 运行时不支持 WebAssembly。");
+		const exported = (await wasmRuntime.instantiate(wasmBytes, {})).instance.exports[exportName];
+		if (typeof exported !== "function") throw new Error(`Wasm 导出不存在或不可调用：${exportName}`);
+		const result = exported(...args);
+		if (typeof result !== "number") throw new Error(`Wasm 导出 ${exportName} 必须返回 number。`);
+		return result;
+	};
+};
+//#endregion
+export { WasmSidecarClientService };

package/dist/ui/ui-server.service.d.ts

@@ -0,0 +1,14 @@
+import { AppManifestBundle } from "../manifest/app-manifest.types.js";
+import { IncomingMessage, ServerResponse } from "node:http";
+
+//#region src/ui/ui-server.service.d.ts
+declare class UiServerService {
+  private readonly bundle;
+  constructor(bundle: AppManifestBundle);
+  handle: (request: IncomingMessage, response: ServerResponse) => Promise<boolean>;
+  private resolveContentType;
+  private exists;
+  private isInsideAllowedDirectory;
+}
+//#endregion
+export { UiServerService };

package/dist/ui/ui-server.service.js

@@ -0,0 +1,51 @@
+import { access, readFile } from "node:fs/promises";
+import path from "node:path";
+//#region src/ui/ui-server.service.ts
+const CONTENT_TYPE_BY_EXTENSION = {
+	".css": "text/css; charset=utf-8",
+	".html": "text/html; charset=utf-8",
+	".js": "text/javascript; charset=utf-8",
+	".json": "application/json; charset=utf-8",
+	".png": "image/png",
+	".svg": "image/svg+xml; charset=utf-8"
+};
+var UiServerService = class {
+	constructor(bundle) {
+		this.bundle = bundle;
+	}
+	handle = async (request, response) => {
+		const requestUrl = new URL(request.url ?? "/", "http://127.0.0.1");
+		const requestPath = requestUrl.pathname === "/" ? "/index.html" : requestUrl.pathname;
+		const candidatePaths = [path.join(this.bundle.uiDirectoryPath, requestPath.slice(1)), path.join(this.bundle.assetsDirectoryPath, requestPath.slice(1))];
+		for (const candidatePath of candidatePaths) {
+			if (!await this.isInsideAllowedDirectory(candidatePath)) continue;
+			if (!await this.exists(candidatePath)) continue;
+			const content = await readFile(candidatePath);
+			response.writeHead(200, { "content-type": this.resolveContentType(candidatePath) });
+			response.end(content);
+			return true;
+		}
+		response.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+		response.end(`Not found: ${requestPath}`);
+		return true;
+	};
+	resolveContentType = (filePath) => {
+		return CONTENT_TYPE_BY_EXTENSION[path.extname(filePath).toLowerCase()] ?? "application/octet-stream";
+	};
+	exists = async (filePath) => {
+		try {
+			await access(filePath);
+			return true;
+		} catch {
+			return false;
+		}
+	};
+	isInsideAllowedDirectory = async (candidatePath) => {
+		return [this.bundle.uiDirectoryPath, this.bundle.assetsDirectoryPath].some((directoryPath) => {
+			const relative = path.relative(directoryPath, candidatePath);
+			return relative === "" || !relative.startsWith("..") && !path.isAbsolute(relative);
+		});
+	};
+};
+//#endregion
+export { UiServerService };

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@nextclaw/app-runtime",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Standalone micro app runtime and CLI for NextClaw apps.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Peiiii/nextclaw.git"
+  },
+  "homepage": "https://github.com/Peiiii/nextclaw/tree/master/packages/nextclaw-app-runtime",
+  "bugs": {
+    "url": "https://github.com/Peiiii/nextclaw/issues"
+  },
+  "keywords": [
+    "nextclaw",
+    "micro-app",
+    "wasm",
+    "webview",
+    "app-runtime",
+    "cli"
+  ],
+  "bin": {
+    "napp": "dist/main.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^20.17.6",
+    "prettier": "^3.3.3",
+    "typescript": "^5.6.3",
+    "vitest": "^4.1.2"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts src/main.ts --dts --clean --target es2022 --no-fixedExtension --unbundle",
+    "lint": "eslint .",
+    "tsc": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "smoke": "node scripts/smoke.mjs"
+  }
+}