@appstrata/protocol 0.1.0

package/README.md

@@ -0,0 +1,106 @@
+# @appstrata/protocol
+
+Protocol implementation for AppStrata Digital Signage SDK.
+
+This package contains the complete protocol implementation used by both app-side (`@appstrata/web`) and host-side (`@appstrata/player-lib`) SDKs.
+
+## Contents
+
+- **Messages**: Protocol message types (HELLO, READY, REQUEST, RESPONSE, EVENT)
+- **Transport**: Message delivery abstraction
+- **Client**: App-side protocol implementation (ProxyPlayer, RpcClient)
+- **Host**: Player-side protocol implementation (MessageBridge)
+
+## Installation
+
+> **Note:** This is a private npm package. Requires an npm access token — contact the AppStrata team to get one, then add it to your `~/.npmrc`:
+>
+> ```
+> //registry.npmjs.org/:_authToken=YOUR_TOKEN
+> ```
+
+```bash
+npm install @appstrata/protocol
+# or
+pnpm add @appstrata/protocol
+```
+
+## Usage
+
+This is a low-level package. Most developers should use:
+- `@appstrata/web` for building apps
+- `@appstrata/player-lib` for building players
+
+### For Advanced Use Cases
+
+```typescript
+import { ProxyPlayer, createAppTransport } from "@appstrata/protocol";
+
+// App side
+const transport = createAppTransport(); // uses window.parent.postMessage
+const player = new ProxyPlayer(transport);
+
+player.onInit((context) => {
+  console.log("App initialized:", context);
+});
+```
+
+```typescript
+import { MessageBridge, createPostMessageTransport } from "@appstrata/protocol";
+
+// Host side
+const transport = createPostMessageTransport({
+  targetWindow: iframe.contentWindow!,
+  targetOrigin: "*",
+});
+const bridge = new MessageBridge({
+  transport,
+  player: myPlayer,
+  getContext: async () => buildAppContext(),
+});
+
+// Start handshake
+bridge.start();
+
+// Fire lifecycle events
+bridge.fireShow();
+bridge.fireStart();
+```
+
+### Relay Transport (Advanced)
+
+For scenarios where you need to bridge between different transport mechanisms:
+
+```typescript
+import { createRelayTransport, createPostMessageTransport, createHttpTransport } from "@appstrata/protocol";
+
+// Relay between local app (postMessage) and remote host (HTTP)
+const relay = createRelayTransport({
+  appTransport: createPostMessageTransport({
+    targetWindow: iframe.contentWindow,
+    targetOrigin: "*"
+  }),
+  hostTransport: createHttpTransport({
+    sendUrl: "https://player.example.com/api/send",
+    receiveUrl: "https://player.example.com/api/receive",
+    sessionId: "abc-123"
+  }),
+  debug: true
+});
+
+// Relay automatically forwards messages between transports
+```
+
+## Architecture
+
+```
+@appstrata/protocol
+├── messages     - Protocol message types and utilities
+├── transport    - Transport layer
+├── client       - App-side (ProxyPlayer, RpcClient)
+└── host         - Player-side (MessageBridge)
+```
+
+## License
+
+MIT

package/dist/client/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Client-side protocol implementation (App side).
+ */
+export * from "./rpc.js";
+export * from "./proxy.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC"}

package/dist/client/index.js

@@ -0,0 +1,5 @@
+/**
+ * Client-side protocol implementation (App side).
+ */
+export * from "./rpc.js";
+export * from "./proxy.js";

package/dist/client/proxy.d.ts

@@ -0,0 +1,72 @@
+/**
+ * ProxyPlayer - App-side SignagePlayer implementation over the message protocol.
+ *
+ * Uses the message protocol for handshake and RPC-based capability operations.
+ */
+import { LifecyclePhase, type SignagePlayer, type AppContext, type Capability, type LogLevel, type EstimatedEndOptions, type NoContentOptions, type StorageApi, type ProxyApi, type MediaCacheApi, type StaticApi, type InteractionApi } from "@appstrata/core";
+import type { Transport } from "../transport/index.js";
+/**
+ * ProxyPlayer - App-side SignagePlayer that communicates with the Host via the message protocol.
+ *
+ * Handles the HELLO/READY/READY_ACK handshake and uses RPC for capability operations.
+ */
+export declare class ProxyPlayer implements SignagePlayer {
+    readonly apiVersion = "1.0.0";
+    lifecyclePhase: LifecyclePhase;
+    private transport;
+    private rpc;
+    private context;
+    private readyPromise;
+    private resolveReady;
+    private isReady;
+    private _terminated;
+    private _startTime;
+    private _pendingTotalDuration;
+    private initHandlers;
+    private showHandlers;
+    private startHandlers;
+    private hideHandlers;
+    private stopHandlers;
+    private contextChangeHandlers;
+    private interactionHandlers;
+    /**
+     * Create a ProxyPlayer instance.
+     *
+     * @param transport - Transport for sending/receiving messages
+     */
+    constructor(transport: Transport);
+    /**
+     * Send the HELLO message to initiate the handshake.
+     */
+    private sendHello;
+    /**
+     * Handle READY message from host.
+     */
+    private handleReady;
+    /**
+     * Handle EVENT message from host.
+     */
+    private handleEvent;
+    private fireLifecycleHandlers;
+    private fireContextHandlers;
+    private fireInteractionHandlers;
+    getContext(): Promise<AppContext>;
+    hasCapability(capability: Capability): Promise<boolean>;
+    onInit(handler: (context: AppContext) => void): void;
+    onShow(handler: () => void): void;
+    onStart(handler: () => void): void;
+    onHide(handler: () => void): void;
+    onStop(handler: () => void): void;
+    private invokeLateSubscriber;
+    onContextChange(handler: (context: AppContext) => void): void;
+    notifyComplete(): void;
+    notifyEstimatedEnd(options: EstimatedEndOptions): void;
+    notifyNoContent(options?: NoContentOptions): void;
+    get storage(): StorageApi | undefined;
+    get proxy(): ProxyApi | undefined;
+    get mediaCache(): MediaCacheApi | undefined;
+    get static(): StaticApi | undefined;
+    get interaction(): InteractionApi | undefined;
+    log(level: LogLevel, message: string, data?: unknown): void;
+}
+//# sourceMappingURL=proxy.d.ts.map

package/dist/client/proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../../src/client/proxy.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,cAAc,EAEd,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,KAAK,UAAU,EACf,KAAK,QAAQ,EAIb,KAAK,aAAa,EAGlB,KAAK,SAAS,EACd,KAAK,cAAc,EAEpB,MAAM,iBAAiB,CAAC;AAWzB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAavD;;;;GAIG;AACH,qBAAa,WAAY,YAAW,aAAa;IAC/C,QAAQ,CAAC,UAAU,WAAW;IAC9B,cAAc,EAAE,cAAc,CAAuB;IAErD,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,GAAG,CAAY;IAGvB,OAAO,CAAC,OAAO,CAA2B;IAC1C,OAAO,CAAC,YAAY,CAAgB;IACpC,OAAO,CAAC,YAAY,CAAc;IAClC,OAAO,CAAC,OAAO,CAAS;IAGxB,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,qBAAqB,CAAuB;IAGpD,OAAO,CAAC,YAAY,CAA4C;IAChE,OAAO,CAAC,YAAY,CAAyB;IAC7C,OAAO,CAAC,aAAa,CAAyB;IAC9C,OAAO,CAAC,YAAY,CAAyB;IAC7C,OAAO,CAAC,YAAY,CAAyB;IAC7C,OAAO,CAAC,qBAAqB,CAA4C;IACzE,OAAO,CAAC,mBAAmB,CAAgD;IAE3E;;;;OAIG;gBACS,SAAS,EAAE,SAAS;IAuChC;;OAEG;IACH,OAAO,CAAC,SAAS;IAmBjB;;OAEG;IACH,OAAO,CAAC,WAAW;IAgCnB;;OAEG;IACH,OAAO,CAAC,WAAW;IAqCnB,OAAO,CAAC,qBAAqB;IAU7B,OAAO,CAAC,mBAAmB;IAU3B,OAAO,CAAC,uBAAuB;IAczB,UAAU,IAAI,OAAO,CAAC,UAAU,CAAC;IAKjC,aAAa,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC;IAS7D,MAAM,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,IAAI,GAAG,IAAI;IAcpD,MAAM,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI;IAOjC,OAAO,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI;IAOlC,MAAM,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI;IAOjC,MAAM,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI;IAOjC,OAAO,CAAC,oBAAoB;IAY5B,eAAe,CAAC,OAAO,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,IAAI,GAAG,IAAI;IAQ7D,cAAc,IAAI,IAAI;IAStB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI;IAkCtD,eAAe,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,IAAI;IA+BjD,IAAI,OAAO,IAAI,UAAU,GAAG,SAAS,CAwBpC;IAED,IAAI,KAAK,IAAI,QAAQ,GAAG,SAAS,CAqBhC;IAED,IAAI,UAAU,IAAI,aAAa,GAAG,SAAS,CA8B1C;IAED,IAAI,MAAM,IAAI,SAAS,GAAG,SAAS,CAoBlC;IAED,IAAI,WAAW,IAAI,cAAc,GAAG,SAAS,CAW5C;IAMD,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI;CAI5D"}

package/dist/client/proxy.js

@@ -0,0 +1,446 @@
+/**
+ * ProxyPlayer - App-side SignagePlayer implementation over the message protocol.
+ *
+ * Uses the message protocol for handshake and RPC-based capability operations.
+ */
+import { LifecyclePhase, createLogger } from "@appstrata/core";
+const PHASE_ORDER = {
+    [LifecyclePhase.None]: 0,
+    [LifecyclePhase.Init]: 1,
+    [LifecyclePhase.Show]: 2,
+    [LifecyclePhase.Start]: 3,
+    [LifecyclePhase.Hide]: 4,
+    [LifecyclePhase.Stop]: 5,
+};
+import { RpcClient } from "./rpc.js";
+const logger = createLogger("ProxyPlayer");
+import { wireContextToAppContext, isReadyMessage, isEventMessage, generateRequestId, } from "../messages.js";
+/**
+ * ProxyPlayer - App-side SignagePlayer that communicates with the Host via the message protocol.
+ *
+ * Handles the HELLO/READY/READY_ACK handshake and uses RPC for capability operations.
+ */
+export class ProxyPlayer {
+    /**
+     * Create a ProxyPlayer instance.
+     *
+     * @param transport - Transport for sending/receiving messages
+     */
+    constructor(transport) {
+        this.apiVersion = "1.0.0";
+        this.lifecyclePhase = LifecyclePhase.None;
+        // Context state
+        this.context = null;
+        this.isReady = false;
+        // Playback control state
+        this._terminated = false;
+        this._startTime = null;
+        this._pendingTotalDuration = null;
+        // Lifecycle handlers
+        this.initHandlers = new Set();
+        this.showHandlers = new Set();
+        this.startHandlers = new Set();
+        this.hideHandlers = new Set();
+        this.stopHandlers = new Set();
+        this.contextChangeHandlers = new Set();
+        this.interactionHandlers = new Set();
+        this.transport = transport;
+        // Create ready promise
+        this.readyPromise = new Promise((resolve) => {
+            this.resolveReady = resolve;
+        });
+        // RPC client gates calls on readyPromise (spec §2.2)
+        this.rpc = new RpcClient(transport, this.readyPromise);
+        // Install message listener immediately so we're ready to receive READY
+        this.transport.onMessage((msg) => {
+            if (isReadyMessage(msg)) {
+                logger.debug(`↓ Received READY (requestId=${msg.requestId}, timestamp=${msg.timestamp})`);
+                this.handleReady(msg);
+            }
+            else if (isEventMessage(msg)) {
+                // Spec §2.2: Apps MUST ignore EVENT messages received before READY
+                if (!this.isReady) {
+                    logger.debug("↓ Ignoring EVENT before READY");
+                    return;
+                }
+                logger.debug(`↓ Received EVENT: ${msg.name} (timestamp=${msg.timestamp})`);
+                this.handleEvent(msg);
+            }
+        });
+        // Defer HELLO by one microtask so synchronous handler registrations
+        // (e.g. getPlayer().onStart(...)) complete before the handshake begins.
+        // With sync transports this prevents the entire handshake from completing inside
+        // the constructor (even though send READY is already asynchronous but this adds
+        // an extra safety measure).
+        queueMicrotask(() => this.sendHello());
+    }
+    // ═══════════════════════════════════════════════════════════════════════
+    // HANDSHAKE
+    // ═══════════════════════════════════════════════════════════════════════
+    /**
+     * Send the HELLO message to initiate the handshake.
+     */
+    sendHello() {
+        if (this.isReady) {
+            logger.debug("Skipping HELLO — handshake already completed via proactive READY");
+            return;
+        }
+        const hello = {
+            protocol: "appstrata-protocol",
+            version: "1.0",
+            type: "HELLO",
+            timestamp: Date.now(),
+            requestId: generateRequestId(),
+        };
+        logger.debug(`↑ Sending HELLO (requestId=${hello.requestId}, timestamp=${hello.timestamp})`);
+        this.transport.send(hello);
+    }
+    /**
+     * Handle READY message from host.
+     */
+    handleReady(msg) {
+        // Convert wire format to AppContext
+        this.context = wireContextToAppContext(msg.context);
+        // Send READY_ACK, always echoing requestId from READY
+        const requestId = msg.requestId;
+        const ack = {
+            protocol: "appstrata-protocol",
+            version: "1.0",
+            type: "READY_ACK",
+            timestamp: Date.now(),
+            requestId,
+        };
+        logger.debug(`↑ Sending READY_ACK (requestId=${requestId}, timestamp=${ack.timestamp})`);
+        // Set isReady BEFORE sending READY_ACK so that EVENT messages flushed
+        // synchronously by the host in response to READY_ACK are not dropped
+        // by the isReady guard (in case the transport is synchronous).
+        const firstReady = !this.isReady;
+        this.isReady = true;
+        this.lifecyclePhase = LifecyclePhase.Init;
+        this.transport.send(ack);
+        if (firstReady) {
+            this.resolveReady();
+            // Fire onInit handlers (late subscriber pattern)
+            this.fireContextHandlers(this.initHandlers, this.context);
+        }
+    }
+    /**
+     * Handle EVENT message from host.
+     */
+    handleEvent(msg) {
+        const eventName = msg.name;
+        const suppressible = this._terminated && this.context?.duration == null;
+        if (eventName === "show") {
+            if (suppressible)
+                return;
+            this.lifecyclePhase = LifecyclePhase.Show;
+            this.fireLifecycleHandlers(this.showHandlers);
+        }
+        else if (eventName === "start") {
+            if (suppressible)
+                return;
+            this.lifecyclePhase = LifecyclePhase.Start;
+            this._startTime = Date.now();
+            if (this._pendingTotalDuration != null) {
+                const expectedFinishTime = this._startTime + this._pendingTotalDuration * 1000;
+                this._pendingTotalDuration = null;
+                this.rpc.notify("notifyEstimatedEnd", { expectedFinishTime });
+            }
+            this.fireLifecycleHandlers(this.startHandlers);
+        }
+        else if (eventName === "hide") {
+            if (suppressible && PHASE_ORDER[this.lifecyclePhase] < PHASE_ORDER[LifecyclePhase.Show])
+                return;
+            this.lifecyclePhase = LifecyclePhase.Hide;
+            this.fireLifecycleHandlers(this.hideHandlers);
+        }
+        else if (eventName === "stop") {
+            this.lifecyclePhase = LifecyclePhase.Stop;
+            this.fireLifecycleHandlers(this.stopHandlers);
+        }
+        else if (eventName === "contextChange") {
+            const newContext = wireContextToAppContext(msg.payload);
+            this.context = newContext;
+            this.fireContextHandlers(this.contextChangeHandlers, newContext);
+        }
+        else if (eventName === "interaction") {
+            // Interaction event
+            const interactionEvent = msg.payload;
+            this.fireInteractionHandlers(this.interactionHandlers, interactionEvent);
+        }
+    }
+    fireLifecycleHandlers(handlers) {
+        handlers.forEach((handler) => {
+            try {
+                handler();
+            }
+            catch (error) {
+                logger.error("Error in handler", error);
+            }
+        });
+    }
+    fireContextHandlers(handlers, context) {
+        handlers.forEach((handler) => {
+            try {
+                handler(context);
+            }
+            catch (error) {
+                logger.error("Error in handler", error);
+            }
+        });
+    }
+    fireInteractionHandlers(handlers, event) {
+        handlers.forEach((handler) => {
+            try {
+                handler(event);
+            }
+            catch (error) {
+                logger.error("Error in interaction handler", error);
+            }
+        });
+    }
+    // ═══════════════════════════════════════════════════════════════════════
+    // CONTEXT ACCESS (async - waits for READY)
+    // ═══════════════════════════════════════════════════════════════════════
+    async getContext() {
+        await this.readyPromise;
+        return this.context;
+    }
+    async hasCapability(capability) {
+        const context = await this.getContext();
+        return context.hasCapability(capability);
+    }
+    // ═══════════════════════════════════════════════════════════════════════
+    // LIFECYCLE
+    // ═══════════════════════════════════════════════════════════════════════
+    onInit(handler) {
+        // Late subscriber pattern: fire immediately if ready
+        if (this.context) {
+            try {
+                handler(this.context);
+            }
+            catch (error) {
+                logger.error("Error in onInit late subscriber handler", error);
+            }
+        }
+        // Register for future (though READY typically fires once per session)
+        this.initHandlers.add(handler);
+    }
+    onShow(handler) {
+        this.showHandlers.add(handler);
+        if (this.lifecyclePhase === LifecyclePhase.Show && !(this._terminated && this.context?.duration == null)) {
+            this.invokeLateSubscriber(handler);
+        }
+    }
+    onStart(handler) {
+        this.startHandlers.add(handler);
+        if (this.lifecyclePhase === LifecyclePhase.Start && !(this._terminated && this.context?.duration == null)) {
+            this.invokeLateSubscriber(handler);
+        }
+    }
+    onHide(handler) {
+        this.hideHandlers.add(handler);
+        if (this.lifecyclePhase === LifecyclePhase.Hide) {
+            this.invokeLateSubscriber(handler);
+        }
+    }
+    onStop(handler) {
+        this.stopHandlers.add(handler);
+        if (this.lifecyclePhase === LifecyclePhase.Stop) {
+            this.invokeLateSubscriber(handler);
+        }
+    }
+    invokeLateSubscriber(handler) {
+        try {
+            handler();
+        }
+        catch (error) {
+            logger.error("Error in late subscriber handler", error);
+        }
+    }
+    // ═══════════════════════════════════════════════════════════════════════
+    // CONTEXT CHANGES
+    // ═══════════════════════════════════════════════════════════════════════
+    onContextChange(handler) {
+        this.contextChangeHandlers.add(handler);
+    }
+    // ═══════════════════════════════════════════════════════════════════════
+    // PLAYBACK CONTROL
+    // ═══════════════════════════════════════════════════════════════════════
+    notifyComplete() {
+        if (this._terminated) {
+            logger.warn("ignoring notifyComplete() call after session ended");
+            return;
+        }
+        this._terminated = true;
+        this.rpc.notify("notifyComplete");
+    }
+    notifyEstimatedEnd(options) {
+        if (this._terminated) {
+            logger.warn("ignoring notifyEstimatedEnd() call after session ended");
+            return;
+        }
+        if ('finishTime' in options && 'totalDuration' in options) {
+            logger.warn("EstimatedEndOptions has both finishTime and totalDuration, using finishTime");
+        }
+        if ('finishTime' in options && options.finishTime != null) {
+            if (options.finishTime <= Date.now()) {
+                logger.warn("notifyEstimatedEnd: finishTime must not be in the past");
+                return;
+            }
+            this._pendingTotalDuration = null;
+            this.rpc.notify("notifyEstimatedEnd", {
+                expectedFinishTime: options.finishTime,
+            });
+        }
+        else if ('totalDuration' in options && options.totalDuration != null) {
+            if (options.totalDuration <= 0) {
+                logger.warn("notifyEstimatedEnd: totalDuration must be positive");
+                return;
+            }
+            if (this._startTime != null) {
+                this.rpc.notify("notifyEstimatedEnd", {
+                    expectedFinishTime: this._startTime + options.totalDuration * 1000,
+                });
+            }
+            else {
+                this._pendingTotalDuration = options.totalDuration;
+            }
+        }
+    }
+    notifyNoContent(options) {
+        if (this._terminated) {
+            logger.warn("ignoring notifyNoContent() call after session ended");
+            return;
+        }
+        this._terminated = true;
+        const wirePayload = {};
+        if (options?.reason) {
+            wirePayload.reason = options.reason;
+        }
+        if (options && 'retryIn' in options && options.retryIn != null) {
+            if (options.retryIn <= 0) {
+                logger.warn("notifyNoContent: retryIn must be positive");
+            }
+            else {
+                wirePayload.retryNotBefore = Date.now() + options.retryIn * 1000;
+            }
+        }
+        else if (options && 'retryAt' in options && options.retryAt != null) {
+            if (options.retryAt <= Date.now()) {
+                logger.warn("notifyNoContent: retryAt must not be in the past");
+            }
+            else {
+                wirePayload.retryNotBefore = options.retryAt;
+            }
+        }
+        this.rpc.notify("notifyNoContent", wirePayload);
+    }
+    // ═══════════════════════════════════════════════════════════════════════
+    // CAPABILITY APIS
+    // ═══════════════════════════════════════════════════════════════════════
+    get storage() {
+        return {
+            get: async (key) => {
+                const result = await this.rpc.call("storage.get", { key });
+                return result?.value;
+            },
+            set: async (key, value) => {
+                await this.rpc.call("storage.set", { key, value });
+            },
+            remove: async (key) => {
+                await this.rpc.call("storage.remove", { key });
+            },
+            list: async () => {
+                const result = await this.rpc.call("storage.list");
+                return result?.keys || [];
+            },
+            clear: async () => {
+                await this.rpc.call("storage.clear");
+            }
+        };
+    }
+    get proxy() {
+        return {
+            fetch: async (request) => {
+                const wireResponse = await this.rpc.call("proxy.fetch", request);
+                // Reconstruct ProxyResponse from wire format
+                const response = {
+                    ok: wireResponse.ok,
+                    status: wireResponse.status,
+                    statusText: wireResponse.statusText,
+                    headers: wireResponse.headers,
+                    cached: wireResponse.cached,
+                    stale: wireResponse.stale,
+                    cachedAt: wireResponse.cachedAt,
+                    json: async () => JSON.parse(wireResponse.body),
+                    text: async () => wireResponse.body,
+                };
+                return response;
+            }
+        };
+    }
+    get mediaCache() {
+        return {
+            download: async (url) => {
+                const result = await this.rpc.call("mediaCache.download", { url });
+                return result;
+            },
+            get: async (url) => {
+                const result = await this.rpc.call("mediaCache.get", { url });
+                return result;
+            },
+            list: async () => {
+                const result = await this.rpc.call("mediaCache.list");
+                return result?.files || [];
+            },
+            delete: async (fileName) => {
+                await this.rpc.call("mediaCache.delete", { fileName });
+            },
+            clear: async () => {
+                await this.rpc.call("mediaCache.clear");
+            },
+            getStorageInfo: async () => {
+                const result = await this.rpc.call("mediaCache.getStorageInfo");
+                return result;
+            }
+        };
+    }
+    get static() {
+        return {
+            markStatic: () => {
+                this.rpc.call("static.markStatic").catch((error) => {
+                    logger.error("static.markStatic failed", error);
+                });
+            },
+            markSemiStatic: (refreshIntervalSeconds) => {
+                this.rpc.call("static.markSemiStatic", { refreshIntervalSeconds }).catch((error) => {
+                    logger.error("static.markSemiStatic failed", error);
+                });
+            },
+            disableStatic: () => {
+                this.rpc.call("static.disableStatic").catch((error) => {
+                    logger.error("static.disableStatic failed", error);
+                });
+            }
+        };
+    }
+    get interaction() {
+        return {
+            onEvent: (handler) => {
+                this.interactionHandlers.add(handler);
+                // Return unsubscribe function
+                return () => {
+                    this.interactionHandlers.delete(handler);
+                };
+            }
+        };
+    }
+    // ═══════════════════════════════════════════════════════════════════════
+    // LOGGING
+    // ═══════════════════════════════════════════════════════════════════════
+    log(level, message, data) {
+        // Fire-and-forget: no RESPONSE expected (spec §4.4, Logging spec §10.1)
+        this.rpc.notify("log", { level, message, data }).catch(() => { });
+    }
+}