diff --git a/README.md b/README.md index 574373f..12d3b6e 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,11 @@ commands, receipts, and embedded documents. CultMesh and MessagePack are constructor dependencies supplied from the application's installed CultLib packages; the runtime owns protocol flow without pinning a sibling checkout. +Electron hosts that use the standard Eve IPC channels can point their +`BrowserWindow` preload directly at `src/eve-provider-preload-entry.cjs`. The +entry exposes only `window.eveProvider`; provider-specific APIs do not share the +renderer boundary. + ```powershell npm install npm test diff --git a/package.json b/package.json index 66417aa..c0fb7bf 100644 --- a/package.json +++ b/package.json @@ -15,7 +15,12 @@ "types": "./src/cultmesh-provider-client.d.ts", "import": "./src/cultmesh-provider-client.mjs" }, - "./preload": "./src/eve-provider-preload.cjs" + "./renderer": { + "types": "./src/eve-electron-renderer.d.mts", + "import": "./src/eve-electron-renderer.mjs" + }, + "./preload": "./src/eve-provider-preload.cjs", + "./preload-entry": "./src/eve-provider-preload-entry.cjs" }, "files": ["src", "capture", "scripts", "eve-runtime-capability.json", "README.md", "LICENSE"], "scripts": { diff --git a/src/cultmesh-provider-client.d.ts b/src/cultmesh-provider-client.d.ts index 10e4a1f..d1b60dc 100644 --- a/src/cultmesh-provider-client.d.ts +++ b/src/cultmesh-provider-client.d.ts @@ -22,7 +22,7 @@ export declare class EveCultMeshProviderClient { providerAdvertisement(): Promise>; surface(surfaceId?: string): Promise>; document(request: { schemaId: string; recordRef: string }): Promise; - resolveDocument(request: { documentId: string; schemaId: string }): Promise<{ documentId: string; schemaId: string; document: unknown }>; + resolveDocument(request: { documentId: string; schemaId: string }): Promise<{ documentId: string; schemaId: string; document?: unknown; surface?: Record }>; submitCommand(request: Record): Promise; receipt(submission: Record): Promise; } diff --git a/src/cultmesh-provider-client.mjs b/src/cultmesh-provider-client.mjs index eee18e1..8a87c0a 100644 --- a/src/cultmesh-provider-client.mjs +++ b/src/cultmesh-provider-client.mjs @@ -54,7 +54,11 @@ export class EveCultMeshProviderClient { const documentId = String(request?.documentId || request?.recordRef || "").trim(); const schemaId = String(request?.schemaId || "").trim(); if (!documentId || !schemaId) throw new Error("Embedded documents require documentId and schemaId."); - return { documentId, schemaId, document: await this.document({ schemaId, recordRef: documentId }) }; + const document = await this.document({ schemaId, recordRef: documentId }); + if (schemaId === "gamecult.eve.surface.v1") { + return { documentId, schemaId, surface: normalizeSurfaceDocument(document).surface }; + } + return { documentId, schemaId, document }; } async submitCommand(request) { diff --git a/src/eve-electron-renderer.d.mts b/src/eve-electron-renderer.d.mts new file mode 100644 index 0000000..4327fd5 --- /dev/null +++ b/src/eve-electron-renderer.d.mts @@ -0,0 +1,12 @@ +export declare function createEveElectronRendererTransport(eveProvider: Record Promise>, options?: { resolveAssetUrl?: (uri: string) => string }): Record; +export declare function mountEveElectronProvider(options: { + EveBrowserProviderHost: new (...args: any[]) => { start(): Promise }; + window?: Window & { eveProvider: Record Promise> }; + document?: Document; + hostSelector?: string; + statusSelector?: string; + clientId?: string; + pollMs?: number; + source?: string; + resolveAssetUrl?: (uri: string) => string; +}): Promise<{ start(): Promise }>; diff --git a/src/eve-electron-renderer.mjs b/src/eve-electron-renderer.mjs new file mode 100644 index 0000000..e129396 --- /dev/null +++ b/src/eve-electron-renderer.mjs @@ -0,0 +1,77 @@ +export function createEveElectronRendererTransport(eveProvider, { resolveAssetUrl } = {}) { + if (!eveProvider) throw new Error("window.eveProvider is required."); + return { + providerAdvertisement: () => eveProvider.providerAdvertisement(), + surface: surface => eveProvider.surface({ surfaceId: surface.surfaceId }), + submitCommand: intent => eveProvider.submitCommand({ + providerId: intent.providerId, + surfaceId: intent.surfaceId, + command: intent.command, + clientId: intent.clientId, + issuedAtUtc: intent.issuedAt, + payload: intent.payload, + }), + resolveDocument: request => eveProvider.document(request), + resolveAssetUrl, + }; +} + +export async function mountEveElectronProvider({ + EveBrowserProviderHost, + window: windowObject = globalThis.window, + document: documentObject = globalThis.document, + hostSelector = "#eve-surface-host", + statusSelector = "#status", + clientId = "eve-electron-client", + pollMs = 250, + source = "CultMesh provider", + resolveAssetUrl, +} = {}) { + if (typeof EveBrowserProviderHost !== "function") throw new Error("EveBrowserProviderHost is required."); + const host = requiredElement(documentObject, hostSelector); + const status = requiredElement(documentObject, statusSelector); + const requestedSurfaceId = new URLSearchParams(windowObject.location.search).get("surface") || ""; + const transport = createEveElectronRendererTransport(windowObject.eveProvider, { resolveAssetUrl }); + const providerHost = new EveBrowserProviderHost(host, { + ...transport, + submitCommand: async intent => { + try { + const receipt = await transport.submitCommand(intent); + status.textContent = `${intent.command}: ${receipt?.accepted === false ? "rejected" : receipt?.state || "submitted"}`; + return receipt; + } catch (error) { + status.textContent = error instanceof Error ? error.message : `Failed to submit ${intent.command}.`; + throw error; + } + }, + }, { + body: documentObject.body, + clientId, + pollMs, + requestedSurfaceId, + source, + statusElement: status, + }); + documentObject.body.classList.add("eve-game-mode"); + await providerHost.start(); + wireWindowControls(documentObject, windowObject.eveProvider); + new windowObject.MutationObserver(() => wireWindowControls(documentObject, windowObject.eveProvider)) + .observe(host, { childList: true, subtree: true }); + return providerHost; +} + +function wireWindowControls(documentObject, eveProvider) { + documentObject.querySelectorAll("[data-window-control]").forEach(button => { + if (button.dataset.windowControlWired === "true") return; + button.dataset.windowControlWired = "true"; + button.addEventListener("click", () => { + if (button.dataset.windowControl) void eveProvider.windowControl(button.dataset.windowControl); + }); + }); +} + +function requiredElement(documentObject, selector) { + const element = documentObject.querySelector(selector); + if (!element) throw new Error(`EveElectron renderer is missing ${selector}.`); + return element; +} diff --git a/src/eve-provider-preload-entry.cjs b/src/eve-provider-preload-entry.cjs new file mode 100644 index 0000000..b021649 --- /dev/null +++ b/src/eve-provider-preload-entry.cjs @@ -0,0 +1,4 @@ +const { contextBridge, ipcRenderer } = require("electron"); +const { installEveProviderBridge } = require("./eve-provider-preload.cjs"); + +installEveProviderBridge({ contextBridge, ipcRenderer }); diff --git a/src/index.d.ts b/src/index.d.ts index f58ef65..8943621 100644 --- a/src/index.d.ts +++ b/src/index.d.ts @@ -1,6 +1,7 @@ import type { BrowserWindow, BrowserWindowConstructorOptions, IpcMain, Shell } from "electron"; export * from "./cultmesh-provider-client.js"; +export * from "./eve-electron-renderer.mjs"; export interface EveElectronWindowOptions extends BrowserWindowConstructorOptions { browserWindow?: BrowserWindowConstructorOptions; diff --git a/src/index.mjs b/src/index.mjs index 96e90c3..d67d7ab 100644 --- a/src/index.mjs +++ b/src/index.mjs @@ -1,3 +1,4 @@ export * from "./eve-electron-shell.mjs"; +export * from "./eve-electron-renderer.mjs"; export * from "./cultmesh-provider-client.mjs"; export * from "./window-host.mjs"; diff --git a/test/cultmesh-provider-client.test.mjs b/test/cultmesh-provider-client.test.mjs index 9d03640..7e1dd9b 100644 --- a/test/cultmesh-provider-client.test.mjs +++ b/test/cultmesh-provider-client.test.mjs @@ -67,6 +67,11 @@ test("resolves embedded documents without provider-specific slot logic", async ( }); }); +test("resolves nested Eve surfaces as surface projections", async () => { + const { client } = harness(); + assert.equal((await client.resolveDocument({ documentId: "records/world", schemaId: "gamecult.eve.surface.v1" })).surface.id, "world"); +}); + test("refuses unadvertised surfaces", async () => { const { client } = harness(); await assert.rejects(() => client.surface("missing"), /does not advertise/); diff --git a/test/renderer.test.mjs b/test/renderer.test.mjs new file mode 100644 index 0000000..e0737c7 --- /dev/null +++ b/test/renderer.test.mjs @@ -0,0 +1,22 @@ +import assert from "node:assert/strict"; +import test from "node:test"; +import { createEveElectronRendererTransport } from "../src/eve-electron-renderer.mjs"; + +test("adapts only the generic Eve provider renderer boundary", async () => { + const calls = []; + const provider = { + providerAdvertisement: async () => ({ providerId: "fixture" }), + surface: async request => { calls.push(["surface", request]); return { surface: { id: "world" } }; }, + document: async request => { calls.push(["document", request]); return { document: true }; }, + submitCommand: async request => { calls.push(["command", request]); return { state: "accepted" }; }, + }; + const transport = createEveElectronRendererTransport(provider); + await transport.surface({ surfaceId: "world", recordRef: "provider-owned" }); + await transport.resolveDocument({ documentId: "objects", schemaId: "objects.v1" }); + await transport.submitCommand({ providerId: "fixture", surfaceId: "world", command: "move", clientId: "renderer", issuedAt: "now", payload: { x: 1 } }); + assert.deepEqual(calls, [ + ["surface", { surfaceId: "world" }], + ["document", { documentId: "objects", schemaId: "objects.v1" }], + ["command", { providerId: "fixture", surfaceId: "world", command: "move", clientId: "renderer", issuedAtUtc: "now", payload: { x: 1 } }], + ]); +});