@backdrop-augmentation-protocol/component-sdk 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Backdrop Augmentation Protocol 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

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+# BAP Component SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+Official MVP SDK for building dual-mode BAP components. A component can run independently in Standalone Mode or inside a compatible host through an Embedded iframe.
+
+## Quick start
+
+```js
+import { StandaloneShell } from '@backdrop-augmentation-protocol/component-sdk';
+
+const manifest = {
+  protocol: { name: 'bap', version: '0.1.0', profile: 'core' },
+  id: 'example.clock', name: 'Example Clock', version: '0.1.0',
+  role: 'component', capabilities: [], modes: ['standalone', 'embedded'],
+  entrypoints: {
+    default: './component.js',
+    embedded: './component.js',
+    standalone: './component.js'
+  }
+};
+
+new StandaloneShell({ manifest, render(root, runtime) {
+  root.textContent = runtime.getConfig('label') ?? 'Hello BAP';
+} }).start();
+```
+
+The official Standalone Shell is an optional convenience. The protocol only requires that Standalone Mode can run as a real component entry point.
+
+## MVP API
+
+- `validateManifest` / `assertManifest`: runtime manifest validation.
+- `createEmbeddedEntry`: creates a component runtime for a Host-provided iframe.
+- `createStandaloneEntry`: creates a minimal standalone runtime without a shell.
+- `StandaloneShell`: optional minimal document shell for examples and development.
+- `PostMessageClient`: request/response and event messaging over `postMessage`.
+- `ComponentRuntime`: lifecycle (`start`, `pause`, `resume`, `stop`) and configuration APIs.
+
+Run tests with `npm test`. Run the minimal example with `npm run example`, then open `http://localhost:4173`.

package/README.zh-CN.md

@@ -0,0 +1,42 @@
+# BAP Component SDK
+
+[English](README.md) | 简体中文
+
+用于构建 BAP 双模式组件的官方 MVP SDK。组件可以在 Standalone Mode 中独立
+运行，也可以通过 Embedded iframe 运行在兼容 Host 中。
+
+## 快速开始
+
+```js
+import { StandaloneShell } from '@backdrop-augmentation-protocol/component-sdk';
+
+const manifest = {
+  protocol: { name: 'bap', version: '0.1.0', profile: 'core' },
+  id: 'example.clock', name: 'Example Clock', version: '0.1.0',
+  role: 'component', capabilities: [], modes: ['standalone', 'embedded'],
+  entrypoints: {
+    default: './component.js',
+    embedded: './component.js',
+    standalone: './component.js'
+  }
+};
+
+new StandaloneShell({ manifest, render(root, runtime) {
+  root.textContent = runtime.getConfig('label') ?? 'Hello BAP';
+} }).start();
+```
+
+官方 Standalone Shell 是可选的便利工具。协议只要求 Standalone Mode 能够
+作为真实组件入口运行。
+
+## MVP API
+
+- `validateManifest` / `assertManifest`：运行时 Manifest 校验；
+- `createEmbeddedEntry`：为 Host 提供的 iframe 创建组件运行时；
+- `createStandaloneEntry`：不依赖 Shell 创建最小独立运行时；
+- `StandaloneShell`：供示例和开发使用的可选最小文档外壳；
+- `PostMessageClient`：通过 `postMessage` 实现请求/响应和事件通信；
+- `ComponentRuntime`：生命周期（`start`、`pause`、`resume`、`stop`）和配置 API。
+
+使用 `npm test` 运行测试。使用 `npm run example` 运行最小示例，然后打开
+`http://localhost:4173`。

package/examples/minimal/component.js

@@ -0,0 +1,3 @@
+import { StandaloneShell } from '../../src/index.js';
+const manifest = { protocol: { name: 'bap', version: '0.1.0', profile: 'core' }, id: 'example.clock', name: 'BAP Example Clock', version: '0.1.0', role: 'component', capabilities: [], modes: ['standalone', 'embedded'], entrypoints: { default: './component.js', embedded: './component.js', standalone: './component.js' } };
+new StandaloneShell({ manifest, render(root, runtime) { const title = document.createElement('h1'); const time = document.createElement('time'); title.textContent = 'BAP Component SDK'; root.append(title, time); const tick = () => { time.textContent = new Date().toLocaleTimeString(); }; tick(); const timer = setInterval(tick, 1000); runtime.onLifecycle('stopped', () => clearInterval(timer)); } }).start();

package/examples/minimal/index.html

@@ -0,0 +1 @@
+<!doctype html><meta charset="utf-8"><title>BAP Example Clock</title><body><script type="module" src="./examples/minimal/component.js"></script></body>

package/examples/minimal/manifest.json

@@ -0,0 +1,11 @@
+{
+  "protocol": { "name": "bap", "version": "0.1.0", "profile": "core" },
+  "id": "example.clock",
+  "name": "BAP Example Clock",
+  "version": "0.1.0",
+  "role": "component",
+  "modes": ["standalone", "embedded"],
+  "entrypoints": { "default": "./component.js", "embedded": "./component.js", "standalone": "./component.js" },
+  "capabilities": [],
+  "permissions": []
+}

package/examples/minimal/serve.mjs

@@ -0,0 +1,7 @@
+import { createServer } from 'node:http';
+import { readFile } from 'node:fs/promises';
+import { extname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const root = fileURLToPath(new URL('../../', import.meta.url));
+const types = { '.html': 'text/html', '.js': 'text/javascript', '.json': 'application/json' };
+createServer(async (req, res) => { try { const pathname = new URL(req.url, 'http://localhost').pathname; const fileName = pathname === '/' ? 'examples/minimal/index.html' : pathname.slice(1); const file = await readFile(join(root, fileName)); res.writeHead(200, { 'content-type': types[extname(fileName)] || 'text/plain' }); res.end(file); } catch { res.writeHead(404); res.end('Not found'); } }).listen(4173, () => console.log('Example: http://localhost:4173'));

package/package.json

@@ -1,6 +1,21 @@
 {
   "name": "@backdrop-augmentation-protocol/component-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "license": "MIT",
+  "description": "Official BAP Component SDK for dual-mode web components.",
+  "publishConfig": { "access": "public" },
+  "type": "module",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": "./src/index.js",
+    "./manifest": "./src/manifest.js",
+    "./client": "./src/post-message-client.js",
+    "./runtime": "./src/runtime.js",
+    "./standalone-shell": "./src/standalone-shell.js"
+  },
+  "scripts": {
+    "test": "node --test",
+    "example": "node examples/minimal/serve.mjs"
+  },
+  "files": ["src", "examples", "README.md", "README.zh-CN.md", "LICENSE"]
+}

package/src/index.d.ts

@@ -0,0 +1,11 @@
+export type ComponentMode = 'embedded' | 'standalone';
+export interface ComponentManifest { protocol: { name: 'bap'; version: string; profile: string }; id: string; name: string; version: string; implementationVersion?: string; role: 'component'; capabilities: string[]; permissions?: string[]; modes: ComponentMode[]; entrypoints: { default: string; embedded?: string; standalone?: string }; configScopes?: Array<'global' | 'series' | 'wallpaper' | 'instance'>; description?: string; }
+export interface ManifestResult { valid: boolean; errors: string[]; }
+export declare function validateManifest(value: unknown): ManifestResult;
+export declare function assertManifest(manifest: unknown): ComponentManifest;
+export declare class ManifestValidationError extends Error { errors: string[]; }
+export declare class PostMessageClient { constructor(options: { target: Window; targetOrigin?: string; receiveWindow?: Window; timeoutMs?: number; sessionId?: string }); request(method: string, payload?: unknown): Promise<unknown>; notify(event: string, payload?: unknown, options?: { sessionId?: string }): void; on(event: string, listener: (payload: unknown, message: unknown) => void): () => void; onRequest(handler: (message: unknown) => Promise<Record<string, unknown>> | Record<string, unknown>): () => void; close(): void; }
+export declare class ComponentRuntime { manifest: ComponentManifest; mode: ComponentMode; state: string; constructor(options: { manifest: ComponentManifest; mode: ComponentMode; client?: PostMessageClient; config?: Record<string, unknown>; root?: HTMLElement }); start(): Promise<void>; pause(): Promise<void>; resume(): Promise<void>; stop(): Promise<void>; getConfig(key?: string): unknown; setConfig(patch: Record<string, unknown>): Promise<Record<string, unknown>>; onConfigChange(listener: (config: Record<string, unknown>) => void): () => void; onLifecycle(state: string, listener: (event: unknown) => void): () => void; hostRequest(method: string, params?: unknown): Promise<unknown>; }
+export declare function createEmbeddedEntry(options: Record<string, unknown>): { runtime: ComponentRuntime; start(): Promise<void>; pause(): Promise<void>; resume(): Promise<void>; stop(): Promise<void> };
+export declare function createStandaloneEntry(options: Record<string, unknown>): { runtime: ComponentRuntime; start(): Promise<void>; pause(): Promise<void>; resume(): Promise<void>; stop(): Promise<void> };
+export declare class StandaloneShell { constructor(options: { manifest: ComponentManifest; root?: HTMLElement; config?: Record<string, unknown>; render?: (root: HTMLElement, runtime: ComponentRuntime) => void }); start(): Promise<void>; pause(): Promise<void>; resume(): Promise<void>; stop(): Promise<void>; }

package/src/index.js

@@ -0,0 +1,5 @@
+export * from './manifest.js';
+export * from './post-message-client.js';
+export * from './runtime.js';
+export * from './standalone-shell.js';
+export * from './protocol.js';

package/src/manifest.js

@@ -0,0 +1,46 @@
+const ID = /^[a-z0-9][a-z0-9._-]{1,127}$/;
+const VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+
+export class ManifestValidationError extends Error {
+  constructor(errors) {
+    super(`Invalid BAP component manifest: ${errors.join('; ')}`);
+    this.name = 'ManifestValidationError';
+    this.errors = errors;
+  }
+}
+
+export function validateManifest(value) {
+  const errors = [];
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return { valid: false, errors: ['manifest must be an object'] };
+  }
+  const allowed = new Set(['protocol', 'id', 'name', 'version', 'implementationVersion', 'role', 'capabilities', 'permissions', 'modes', 'entrypoints', 'configScopes', 'description']);
+  for (const key of Object.keys(value)) if (!allowed.has(key)) errors.push(`unknown field: ${key}`);
+  if (!value.protocol || value.protocol.name !== 'bap' || typeof value.protocol.version !== 'string' || !VERSION.test(value.protocol.version) || typeof value.protocol.profile !== 'string') errors.push('protocol must be { name: bap, version, profile }');
+  if (typeof value.id !== 'string' || !ID.test(value.id)) errors.push('id must be a lowercase package identifier');
+  if (typeof value.name !== 'string' || !value.name.trim()) errors.push('name must be a non-empty string');
+  if (typeof value.version !== 'string' || !VERSION.test(value.version)) errors.push('version must be semver-like (x.y.z)');
+  if (value.role !== 'component') errors.push('role must be component');
+  if (!Array.isArray(value.capabilities) || value.capabilities.some((item) => typeof item !== 'string')) errors.push('capabilities must be an array of strings');
+  if (!Array.isArray(value.modes) || value.modes.length === 0 || value.modes.some((item) => !['embedded', 'standalone'].includes(item))) errors.push('modes must contain standalone and/or embedded');
+  if (!value.entrypoints || typeof value.entrypoints !== 'object') errors.push('entrypoints is required');
+  else {
+    if (typeof value.entrypoints.default !== 'string' || !value.entrypoints.default.trim()) errors.push('entrypoints.default must be a non-empty path');
+    for (const mode of value.modes || []) {
+      if (typeof value.entrypoints[mode] !== 'string' || !value.entrypoints[mode].trim()) errors.push(`entrypoints.${mode} must be a non-empty path`);
+    }
+  }
+  for (const field of ['permissions', 'configScopes']) {
+    if (value[field] !== undefined && (!Array.isArray(value[field]) || value[field].some((item) => typeof item !== 'string'))) {
+      errors.push(`${field} must be an array of strings`);
+    }
+  }
+  if (Array.isArray(value.configScopes) && value.configScopes.some((item) => !['global', 'series', 'wallpaper', 'instance'].includes(item))) errors.push('configScopes contains an unsupported scope');
+  return { valid: errors.length === 0, errors };
+}
+
+export function assertManifest(manifest) {
+  const result = validateManifest(manifest);
+  if (!result.valid) throw new ManifestValidationError(result.errors);
+  return manifest;
+}

package/src/post-message-client.js

@@ -0,0 +1,50 @@
+import { createErrorResponse, createEvent, createRequest, createResponse, isProtocolMessage } from './protocol.js';
+
+export class BapProtocolError extends Error {
+  constructor(error) {
+    super(error?.message || 'BAP protocol error');
+    this.name = 'BapProtocolError';
+    Object.assign(this, error);
+  }
+}
+
+export class PostMessageClient {
+  constructor({ target, targetOrigin = '*', receiveWindow = globalThis.window, timeoutMs = 5000, sessionId } = {}) {
+    if (!target || typeof target.postMessage !== 'function') throw new TypeError('target must support postMessage');
+    this.target = target; this.targetOrigin = targetOrigin; this.receiveWindow = receiveWindow; this.timeoutMs = timeoutMs; this.sessionId = sessionId;
+    this.pending = new Map(); this.listeners = new Map(); this.requestHandler = null; this.peerOrigin = null; this._onMessage = (event) => this._receive(event);
+    this.receiveWindow?.addEventListener?.('message', this._onMessage);
+  }
+  request(method, payload = {}) {
+    const request = createRequest(method, payload, { sessionId: this.sessionId });
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => { this.pending.delete(request.id); reject(new BapProtocolError({ code: 'TIMEOUT', message: `BAP request timed out: ${method}`, retryable: true })); }, this.timeoutMs);
+      this.pending.set(request.id, { resolve, reject, timer }); this.target.postMessage(request, this.targetOrigin);
+    });
+  }
+  notify(event, payload = {}, options = {}) { this.target.postMessage(createEvent(event, payload, { ...options, sessionId: options.sessionId || this.sessionId }), this.targetOrigin); }
+  on(event, listener) { if (!this.listeners.has(event)) this.listeners.set(event, new Set()); this.listeners.get(event).add(listener); return () => this.listeners.get(event)?.delete(listener); }
+  onRequest(handler) { this.requestHandler = handler; return () => { if (this.requestHandler === handler) this.requestHandler = null; }; }
+  _receive(event) {
+    if (event.source && event.source !== this.target) return;
+    const message = event.data;
+    if (!isProtocolMessage(message)) return;
+    if (this.peerOrigin !== null && event.origin !== this.peerOrigin) return;
+    if (message.kind === 'request' && this.requestHandler) {
+      if (this.sessionId && message.method !== 'hello' && message.sessionId !== this.sessionId) return;
+      if (this.peerOrigin === null && message.method === 'hello') this.peerOrigin = event.origin ?? 'null';
+      void Promise.resolve().then(() => this.requestHandler(message)).then(
+        (result) => this._reply(createResponse(message, result, { sessionId: this.sessionId })),
+        (error) => this._reply(createErrorResponse(message, error?.code || 'INTERNAL_ERROR', error?.message || 'Component request failed', { sessionId: this.sessionId }))
+      );
+      return;
+    }
+    if (this.sessionId && message.sessionId !== this.sessionId) return;
+    if (message.kind === 'response' && message.correlationId && this.pending.has(message.correlationId)) {
+      const pending = this.pending.get(message.correlationId); this.pending.delete(message.correlationId); clearTimeout(pending.timer);
+      if (message.ok) pending.resolve(message.result); else pending.reject(new BapProtocolError(message.error));
+    } else if (message.kind === 'event') for (const listener of this.listeners.get(message.event) || []) listener(message.payload, message);
+  }
+  _reply(message) { this.target.postMessage(message, this.targetOrigin); }
+  close() { this.receiveWindow?.removeEventListener?.('message', this._onMessage); for (const pending of this.pending.values()) { clearTimeout(pending.timer); pending.reject(new BapProtocolError({ code: 'INTERNAL_ERROR', message: 'BAP client closed' })); } this.pending.clear(); }
+}

package/src/protocol.js

@@ -0,0 +1,43 @@
+export const BAP_PROTOCOL = Object.freeze({ name: 'bap', version: '0.1.0', profile: 'core' });
+export const CORE_METHODS = Object.freeze(['hello', 'initialize', 'start', 'pause', 'resume', 'stop']);
+export const ERROR_CODES = Object.freeze([
+  'INVALID_MESSAGE', 'UNSUPPORTED_VERSION', 'UNSUPPORTED_PROFILE', 'UNAUTHORIZED',
+  'CAPABILITY_DENIED', 'INVALID_STATE', 'NOT_FOUND', 'CONFLICT', 'TIMEOUT', 'INTERNAL_ERROR'
+]);
+
+export function timestamp() { return new Date().toISOString(); }
+
+export function createRequest(method, payload = {}, { id = createId(), sessionId } = {}) {
+  return withSession({ protocol: BAP_PROTOCOL, kind: 'request', id, timestamp: timestamp(), method, payload }, sessionId);
+}
+
+export function createResponse(request, result = {}, { sessionId } = {}) {
+  return withSession({ protocol: BAP_PROTOCOL, kind: 'response', id: createId(), correlationId: request.id, timestamp: timestamp(), ok: true, result }, sessionId);
+}
+
+export function createErrorResponse(request, code, message, { details, retryable = false, sessionId } = {}) {
+  if (!ERROR_CODES.includes(code)) throw new TypeError(`Unsupported BAP error code: ${code}`);
+  const error = { code, message, retryable };
+  if (details !== undefined) error.details = details;
+  return withSession({ protocol: BAP_PROTOCOL, kind: 'response', id: createId(), correlationId: request.id, timestamp: timestamp(), ok: false, error }, sessionId);
+}
+
+export function createEvent(event, payload = {}, { id = createId(), sessionId, correlationId } = {}) {
+  const message = { protocol: BAP_PROTOCOL, kind: 'event', id, timestamp: timestamp(), event, payload };
+  if (correlationId) message.correlationId = correlationId;
+  return withSession(message, sessionId);
+}
+
+export function createId() { return `msg-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`; }
+
+export function isProtocolMessage(message) {
+  return Boolean(message && typeof message === 'object' && message.protocol?.name === 'bap' &&
+    typeof message.protocol.version === 'string' && message.protocol.profile === 'core' &&
+    ['request', 'response', 'event'].includes(message.kind) && typeof message.id === 'string' &&
+    typeof message.timestamp === 'string');
+}
+
+function withSession(message, sessionId) {
+  if (sessionId) message.sessionId = sessionId;
+  return message;
+}

package/src/runtime.js

@@ -0,0 +1,77 @@
+import { assertManifest } from './manifest.js';
+import { PostMessageClient } from './post-message-client.js';
+import { BAP_PROTOCOL, createId } from './protocol.js';
+
+export class ComponentRuntime {
+  constructor({ manifest, mode, client = null, config = {}, root = null } = {}) {
+    assertManifest(manifest);
+    if (!['embedded', 'standalone'].includes(mode)) throw new TypeError('mode must be embedded or standalone');
+    this.manifest = manifest; this.mode = mode; this.client = client; this.root = root;
+    this.state = 'created'; this.sessionId = null; this.config = globalThis.structuredClone ? globalThis.structuredClone(config) : { ...config }; this.configListeners = new Set();
+    this.lifecycleListeners = new Map();
+    if (this.mode === 'embedded' && this.client) this.client.onRequest((message) => this._hostRequest(message));
+  }
+  onLifecycle(state, listener) { if (!this.lifecycleListeners.has(state)) this.lifecycleListeners.set(state, new Set()); this.lifecycleListeners.get(state).add(listener); return () => this.lifecycleListeners.get(state)?.delete(listener); }
+  async start() {
+    if (this.mode === 'embedded') {
+      if (!this.client) throw new Error('Embedded mode requires a Host session channel');
+      return;
+    }
+    if (this.state === 'running') return;
+    if (this.state !== 'created' && this.state !== 'stopped') throw this._invalidState('start');
+    if (this.state === 'created') {
+      this.sessionId = `standalone-${Date.now().toString(36)}`;
+      await this._transition('connected'); await this._requestLifecycle('initialize'); await this._transition('initialized');
+    } else { await this._requestLifecycle('initialize'); await this._transition('initialized'); }
+    await this._requestLifecycle('start'); await this._transition('running');
+  }
+  async pause() { if (this.state === 'paused') return; if (this.state !== 'running') throw this._invalidState('pause'); await this._requestLifecycle('pause'); await this._transition('paused'); }
+  async resume() { if (this.state === 'paused') { await this._requestLifecycle('resume'); await this._transition('running'); } }
+  async stop() { if (this.state === 'stopped') return; if (!['running', 'paused'].includes(this.state)) throw this._invalidState('stop'); await this._requestLifecycle('stop'); await this._transition('stopped'); }
+  async _requestLifecycle(method) { if (this.client) await this.client.request(method, { componentId: this.manifest.id, mode: this.mode }); }
+  _invalidState(method) { const error = new Error(`Cannot ${method} from ${this.state}`); error.code = 'INVALID_STATE'; return error; }
+  async _hostRequest(message) {
+    const { method, payload } = message;
+    if (method === 'hello') {
+      if (this.state !== 'created') throw this._invalidState('hello');
+      if (message.protocol?.name !== BAP_PROTOCOL.name || message.protocol.profile !== BAP_PROTOCOL.profile) {
+        const error = new Error('Unsupported Core profile'); error.code = 'UNSUPPORTED_PROFILE'; throw error;
+      }
+      if (payload?.role !== 'host' || !payload.identity?.id || !Array.isArray(payload.protocolVersions) || !Array.isArray(payload.capabilities) || !Array.isArray(payload.requestedPermissions)) {
+        const error = new Error('Invalid hello payload'); error.code = 'INVALID_MESSAGE'; throw error;
+      }
+      if (!payload.protocolVersions.includes(BAP_PROTOCOL.version) || message.protocol.version !== BAP_PROTOCOL.version) {
+        const error = new Error('Unsupported protocol version'); error.code = 'UNSUPPORTED_VERSION'; throw error;
+      }
+      this.sessionId = createId(); this.client.sessionId = this.sessionId;
+      await this._transition('connected');
+      return { selectedProtocol: BAP_PROTOCOL, role: 'component', capabilities: this.manifest.capabilities.filter(value => payload.capabilities.includes(value)), permissions: (this.manifest.permissions || []).filter(value => payload.requestedPermissions.includes(value)) };
+    }
+    if (!this.sessionId || message.sessionId !== this.sessionId) {
+      const error = new Error('Missing or invalid session'); error.code = 'UNAUTHORIZED'; throw error;
+    }
+    if (method === 'initialize' && (this.state === 'connected' || this.state === 'stopped')) { await this._transition('initialized'); return { state: this.state }; }
+    if (method === 'start' && this.state === 'initialized') { await this._transition('running'); return { state: this.state }; }
+    if (method === 'pause' && this.state === 'running') { await this._transition('paused'); return { state: this.state }; }
+    if (method === 'resume' && this.state === 'paused') { await this._transition('running'); return { state: this.state }; }
+    if (method === 'stop' && ['running', 'paused'].includes(this.state)) { await this._transition('stopped'); return { state: this.state }; }
+    if ((method === 'pause' && this.state === 'paused') || (method === 'resume' && this.state === 'running') || (method === 'stop' && this.state === 'stopped')) return { state: this.state };
+    if (['initialize', 'start', 'pause', 'resume', 'stop'].includes(method)) throw this._invalidState(method);
+    const error = new Error(`Unknown method: ${method}`); error.code = 'NOT_FOUND'; throw error;
+  }
+  async _transition(state) { this.state = state; for (const listener of this.lifecycleListeners.get(state) || []) await listener({ state, runtime: this }); if (state !== 'connected') this.client?.notify('state.changed', { role: 'component', state, id: this.manifest.id }, { sessionId: this.sessionId }); }
+  getConfig(key) { return key === undefined ? this.config : this.config[key]; }
+  async setConfig(patch) { if (!patch || typeof patch !== 'object' || Array.isArray(patch)) throw new TypeError('config patch must be an object'); this.config = { ...this.config, ...patch }; for (const listener of this.configListeners) await listener(this.config); this.client?.notify('config.changed', { scope: 'wallpaper', config: this.config }, { sessionId: this.sessionId }); return this.config; }
+  onConfigChange(listener) { this.configListeners.add(listener); return () => this.configListeners.delete(listener); }
+  hostRequest(method, params) { if (!this.client) return Promise.reject(new Error('Host API is unavailable in standalone mode')); return this.client.request(method, params); }
+}
+
+export function createEmbeddedEntry(options) { return createEntry({ ...options, mode: 'embedded' }); }
+export function createStandaloneEntry(options) { return createEntry({ ...options, mode: 'standalone' }); }
+function createEntry({ manifest, mode, root = globalThis.document?.body, client, config, targetOrigin = '*' } = {}) {
+  if (mode === 'embedded' && !client && globalThis.window?.parent && globalThis.window.parent !== globalThis.window) {
+    client = new PostMessageClient({ target: globalThis.window.parent, targetOrigin, receiveWindow: globalThis.window });
+  }
+  const runtime = new ComponentRuntime({ manifest, mode, root, client, config });
+  return { runtime, start: () => runtime.start(), pause: () => runtime.pause(), resume: () => runtime.resume(), stop: () => runtime.stop() };
+}

package/src/standalone-shell.js

@@ -0,0 +1,19 @@
+import { createStandaloneEntry } from './runtime.js';
+
+export class StandaloneShell {
+  constructor({ manifest, root = document.body, config = {}, render } = {}) {
+    this.root = root; this.render = render;
+    root.classList.add('bap-standalone-shell');
+    root.style.cssText = 'margin:0;min-height:100vh;background:#111;color:#eee;font:14px system-ui,sans-serif;';
+    this.surface = document.createElement('main');
+    this.surface.dataset.bapComponent = manifest.id;
+    this.surface.style.cssText = 'min-height:100vh;box-sizing:border-box;padding:24px;';
+    root.append(this.surface);
+    this.entry = createStandaloneEntry({ manifest, root: this.surface, config });
+    if (render) render(this.surface, this.entry.runtime);
+  }
+  start() { return this.entry.start(); }
+  pause() { return this.entry.pause(); }
+  resume() { return this.entry.resume(); }
+  stop() { return this.entry.stop(); }
+}