From cf7e7f4df22441884f49f1c2d4459249d5ca0f7f Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sun, 31 May 2026 12:58:55 +0100 Subject: [PATCH] Add Eve surface projection module --- README.md | 12 ++ dist/eve.js | 299 ++++++++++++++++++++++++++++++++++++++++++++++ docs/eve.md | 96 +++++++++++++++ package.json | 1 + scripts/build.mjs | 2 +- scripts/check.mjs | 6 + src/eve.js | 299 ++++++++++++++++++++++++++++++++++++++++++++++ 7 files changed, 714 insertions(+), 1 deletion(-) create mode 100644 dist/eve.js create mode 100644 docs/eve.md create mode 100644 src/eve.js diff --git a/README.md b/README.md index 2fe61e9..7d97631 100644 --- a/README.md +++ b/README.md @@ -144,6 +144,16 @@ that with `data-ink-runtime`, `data-sai-runtime`, or `window.Sai.runtimeSrc`. See [docs/manifest.md](docs/manifest.md). +## Eve Surface Module + +Sai also ships `eve.js`, a portable projection module for Eve/CultMesh clients. +It turns Sai visual-novel state into a retained `gamecult.eve.surface.v1` +component tree instead of browser DOM. Browser, iOS, Android, Direct2D, and +future renderers can consume the same tree and send back `story.*` or +`style.patch` commands. + +See [docs/eve.md](docs/eve.md). + ## Development ```powershell @@ -168,6 +178,7 @@ Sai owns: - browser-side Ink loading through `inkjs` - player DOM and mode rendering - visual manifest interpretation +- Eve surface projection for portable renderers - default CSS and theme variables - static-site auto-init @@ -175,6 +186,7 @@ Sai does not own: - authoring Ink - compiling `.ink` to `.ink.json` +- Eve/CultMesh transport or provider command acceptance - Quartz page chrome - GameCult-specific assets, lore, or characters - a full VN/game engine loop diff --git a/dist/eve.js b/dist/eve.js new file mode 100644 index 0000000..d602144 --- /dev/null +++ b/dist/eve.js @@ -0,0 +1,299 @@ +(function (global) { + const surfaceSchema = "gamecult.eve.surface.v1"; + const commandSchema = "gamecult.eve.command.v1"; + const providerKind = "sai.visual_novel"; + + function nowIso() { + return new Date().toISOString(); + } + + function compact(value) { + if (Array.isArray(value)) return value.map(compact).filter(Boolean); + if (!value || typeof value !== "object") return value; + const result = {}; + for (const [key, child] of Object.entries(value)) { + if (child === undefined || child === null || child === "") continue; + if (Array.isArray(child) && child.length === 0) continue; + result[key] = compact(child); + } + return result; + } + + function component(id, kind, props = {}, children = []) { + return compact({ + id, + kind, + props, + children, + }); + } + + function action(command, label, payload = {}) { + return compact({ + schema: commandSchema, + command, + label, + payload, + }); + } + + function styleTokens(input = {}) { + return { + themeId: input.themeId || "sai.vn.default", + tokens: { + colorBackground: input.colorBackground || "#05080d", + colorPanel: input.colorPanel || "rgba(5, 8, 13, 0.92)", + colorPanelAlt: input.colorPanelAlt || "rgba(9, 14, 22, 0.82)", + colorText: input.colorText || "#f6f1e2", + colorMuted: input.colorMuted || "#b7c7d9", + colorAccent: input.colorAccent || "#ff8a2a", + colorLink: input.colorLink || "#59b7ff", + radiusPanel: input.radiusPanel || 8, + fontBody: input.fontBody || "Ubuntu", + fontTitle: input.fontTitle || "Montserrat", + pixelArt: input.pixelArt ?? true, + motion: input.motion || "subtle", + }, + controls: [ + { + id: "theme.accent", + kind: "color", + label: "Accent", + token: "colorAccent", + command: "style.patch", + }, + { + id: "theme.panel", + kind: "color", + label: "Panel", + token: "colorPanel", + command: "style.patch", + }, + { + id: "theme.motion", + kind: "select", + label: "Motion", + token: "motion", + options: ["none", "subtle", "expressive"], + command: "style.patch", + }, + ], + }; + } + + function graphComponent(graph = {}) { + if (!graph.nodes?.length) return null; + const rawXs = graph.nodes.map((node) => node.viewX ?? node.x ?? 0); + const rawYs = graph.nodes.map((node) => node.viewY ?? node.y ?? 0); + const minX = Math.min(...rawXs); + const maxX = Math.max(...rawXs); + const minY = Math.min(...rawYs); + const maxY = Math.max(...rawYs); + const spanX = Math.max(1, maxX - minX); + const spanY = Math.max(1, maxY - minY); + const normalizeX = (value) => + value >= 0 && value <= 1 ? value : (value - minX) / spanX; + const normalizeY = (value) => + value >= 0 && value <= 1 ? value : (value - minY) / spanY; + + return component( + "sai.graph", + "graph", + { + label: graph.label || "Ink knot graph", + layout: graph.layout || "norn.2d", + nodes: graph.nodes.map((node) => + compact({ + id: node.id, + label: node.label || node.id, + target: node.target || node.knot || node.id, + x: normalizeX(node.viewX ?? node.x ?? 0), + y: normalizeY(node.viewY ?? node.y ?? 0), + rank: node.rank, + order: node.order, + current: Boolean(node.current), + visited: Boolean(node.visited), + available: Boolean(node.available), + weight: node.weight, + }), + ), + edges: graph.edges || [], + }, + [], + ); + } + + function spriteComponents(sprites = []) { + return sprites.map((sprite, index) => + component(`sai.sprite.${sprite.actorName || index}`, "image.sprite", { + actor: sprite.actorName, + expression: sprite.expression || "default", + src: sprite.image || sprite.src, + alt: sprite.alt, + slot: sprite.position || "center", + scale: sprite.scale || 1, + offsetX: sprite.offsetX || 0, + offsetY: sprite.offsetY || 0, + }), + ); + } + + function domCardComponents(cards = []) { + return cards.map((card) => + component(`sai.card.${card.key}`, "card.external", { + key: card.key, + title: card.title || card.label, + selector: card.selector, + htmlRef: card.htmlRef, + mode: "provider-owned-fragment", + }), + ); + } + + function choiceComponents(choices = []) { + return choices.map((choice, index) => + component(`sai.choice.${choice.id || index}`, "control.button", { + label: choice.text || choice.label, + primary: index === 0, + action: action("story.choose", choice.text || choice.label, { + index, + targetPath: choice.targetPath, + }), + }), + ); + } + + function variableComponents(variables = []) { + if (!variables.length) return null; + return component( + "sai.variables", + "inspector.kv", + { + title: "Story Variables", + items: variables.map((item) => ({ + key: item.name, + value: item.value, + })), + }, + [], + ); + } + + function createVisualNovelSurface(input = {}) { + const metadata = input.metadata || {}; + const style = styleTokens(input.style || input.styleTokens || {}); + const scene = input.scene || {}; + const speaker = input.speaker || metadata.speaker || "Void"; + const line = input.line || ""; + const title = input.title || scene.label || "Sai Visual Novel"; + const graph = graphComponent(input.graph); + const variables = variableComponents(input.variables || []); + + const stageChildren = [ + component("sai.background", "image.background", { + src: input.background || scene.background, + label: scene.label, + fit: "cover", + pixelArt: style.tokens.pixelArt, + }), + graph, + component("sai.sprites", "layer.sprites", {}, spriteComponents(input.sprites)), + component("sai.cards", "layer.cards", {}, domCardComponents(input.domCards)), + component( + "sai.dialogue", + "panel.dialogue", + { + speaker, + avatar: input.avatar, + text: line, + scene: scene.label || metadata.scene, + }, + [ + component("sai.dialogue.avatar", "avatar", { + src: input.avatar, + label: speaker, + }), + component("sai.dialogue.text", "text.dialogue", { + speaker, + text: line, + }), + ], + ), + component("sai.choices", "rail.actions", {}, choiceComponents(input.choices)), + variables, + ].filter(Boolean); + + return compact({ + type: "surface-state", + schema: surfaceSchema, + providerKind, + providerId: input.providerId || "sai.vn", + title, + version: input.version || 1, + updatedAt: input.updatedAt || nowIso(), + surface: { + id: input.surfaceId || "sai.visual_novel.surface", + root: component( + "sai.root", + "vn.stage", + { + mode: "visual-novel", + storyId: input.storyId, + currentPath: input.currentPath || metadata.knot || metadata.route, + style: style.themeId, + }, + stageChildren, + ), + styles: style, + }, + selection: { + currentPath: input.currentPath || metadata.knot || metadata.route, + speaker, + }, + commands: [ + action("story.continue", "Continue"), + action("story.choose", "Choose", { index: 0 }), + action("story.jump", "Jump to knot", { targetPath: "" }), + action("style.patch", "Patch style", { token: "", value: "" }), + ], + assets: input.assets || [], + detail: { + source: "Sai Eve module", + notes: + "This document is a retained CultUI surface. Renderers project it to DOM, UIKit, Android views, Direct2D, or other native controls.", + }, + }); + } + + function createCommand(command, payload = {}, options = {}) { + return compact({ + type: "surface-command", + schema: commandSchema, + providerId: options.providerId || "sai.vn", + surfaceId: options.surfaceId || "sai.visual_novel.surface", + command, + payload, + issuedAt: options.issuedAt || nowIso(), + clientId: options.clientId, + }); + } + + function createStylePatch(token, value, options = {}) { + return createCommand("style.patch", { token, value }, options); + } + + const api = { + version: "0.1.0", + surfaceSchema, + commandSchema, + createVisualNovelSurface, + createCommand, + createStylePatch, + }; + + if (typeof module !== "undefined" && module.exports) { + module.exports = api; + } + + global.SaiEve = api; +})(typeof globalThis !== "undefined" ? globalThis : window); diff --git a/docs/eve.md b/docs/eve.md new file mode 100644 index 0000000..92391be --- /dev/null +++ b/docs/eve.md @@ -0,0 +1,96 @@ +# Sai Eve Surface Module + +`eve.js` is Sai's portable surface projection. It does not render the browser +DOM. It emits an Eve/CultMesh surface document whose `surface.root` is a +CultUI-shaped retained component tree. + +Sai still owns Ink playback and visual-manifest interpretation. Eve owns the +portable control surface contract. Web DOM, UIKit, Android views, Direct2D, and +future renderers are projections of that contract. + +## Module + +```html + +``` + +```js +const surface = window.SaiEve.createVisualNovelSurface({ + providerId: "gamecult.home.vn", + storyId: "gamecult-compound", + title: "GameCult Compound", + scene: { + label: "Front Gate", + background: "/static/interactive/cotsc-praxis/backgrounds/compound.png", + }, + metadata: { + knot: "hub", + speaker: "Void", + }, + speaker: "Void", + line: "Pick a door. The map will keep accusing us of being real.", + avatar: "/static/interactive/cotsc-praxis/avatars/void.png", + sprites: [], + domCards: [ + { + key: "projects", + title: "Project Atlas", + selector: "#gamecult-vn-projects", + }, + ], + graph: { + label: "GameCult Ink Knot Graph", + layout: "norn.2d", + nodes: [ + { id: "hub", label: "Hub", target: "hub", x: 0, y: 0, current: true }, + { id: "eve", label: "Eve", target: "eve", x: 1, y: 0 }, + ], + edges: [{ source: "hub", target: "eve" }], + }, + choices: [ + { text: "What is Eve trying to turn the web into?", targetPath: "eve" }, + ], + style: { + themeId: "gamecult.vn", + colorAccent: "#ff8a2a", + colorLink: "#59b7ff", + pixelArt: true, + }, +}); +``` + +The returned document uses `gamecult.eve.surface.v1`. Controls publish +`gamecult.eve.command.v1` command envelopes. Sai currently defines these command +names: + +- `story.continue` +- `story.choose` +- `story.jump` +- `style.patch` + +`style.patch` exists so native and web renderers can synchronize appearance +without each renderer inventing its own theme protocol. A renderer may expose +native color pickers, segmented controls, or accessibility settings, but the +accepted style state belongs to the provider and comes back as surface tokens. + +## Component Kinds + +The first VN surface uses: + +- `vn.stage` +- `image.background` +- `graph` +- `layer.sprites` +- `image.sprite` +- `layer.cards` +- `card.external` +- `panel.dialogue` +- `avatar` +- `text.dialogue` +- `rail.actions` +- `control.button` +- `inspector.kv` + +Native renderers should preserve semantics first and choose platform-native +controls second. A Direct2D renderer does not need to imitate CSS boxes, but it +must preserve the same tree, commands, selection, and style tokens. diff --git a/package.json b/package.json index f0368a1..4e43670 100644 --- a/package.json +++ b/package.json @@ -17,6 +17,7 @@ ".": "./dist/sai.js", "./sai.js": "./dist/sai.js", "./sai.css": "./dist/sai.css", + "./eve.js": "./dist/eve.js", "./ink.js": "./dist/ink.js" }, "scripts": { diff --git a/scripts/build.mjs b/scripts/build.mjs index 6faf6ea..e911bd6 100644 --- a/scripts/build.mjs +++ b/scripts/build.mjs @@ -2,7 +2,7 @@ import fs from "node:fs/promises"; import path from "node:path"; const root = new URL("..", import.meta.url); -const files = ["sai.js", "sai.css", "ink.js"]; +const files = ["sai.js", "sai.css", "ink.js", "eve.js"]; await fs.mkdir(new URL("dist/", root), { recursive: true }); diff --git a/scripts/check.mjs b/scripts/check.mjs index 205b6fe..b5a9764 100644 --- a/scripts/check.mjs +++ b/scripts/check.mjs @@ -5,6 +5,7 @@ const required = [ "dist/sai.js", "dist/sai.css", "dist/ink.js", + "dist/eve.js", "examples/static-site/index.html", "docs/manifest.md", ]; @@ -15,6 +16,7 @@ for (const file of required) { const script = await fs.readFile(new URL("dist/sai.js", root), "utf8"); const css = await fs.readFile(new URL("dist/sai.css", root), "utf8"); +const eve = await fs.readFile(new URL("dist/eve.js", root), "utf8"); if (!script.includes("window.Sai")) { throw new Error("dist/sai.js must expose window.Sai"); @@ -28,4 +30,8 @@ if (!css.includes(".sai-player")) { throw new Error("dist/sai.css must style .sai-player"); } +if (!eve.includes("gamecult.eve.surface.v1")) { + throw new Error("dist/eve.js must publish the Eve surface schema id"); +} + console.log("Sai package checks passed."); diff --git a/src/eve.js b/src/eve.js new file mode 100644 index 0000000..d602144 --- /dev/null +++ b/src/eve.js @@ -0,0 +1,299 @@ +(function (global) { + const surfaceSchema = "gamecult.eve.surface.v1"; + const commandSchema = "gamecult.eve.command.v1"; + const providerKind = "sai.visual_novel"; + + function nowIso() { + return new Date().toISOString(); + } + + function compact(value) { + if (Array.isArray(value)) return value.map(compact).filter(Boolean); + if (!value || typeof value !== "object") return value; + const result = {}; + for (const [key, child] of Object.entries(value)) { + if (child === undefined || child === null || child === "") continue; + if (Array.isArray(child) && child.length === 0) continue; + result[key] = compact(child); + } + return result; + } + + function component(id, kind, props = {}, children = []) { + return compact({ + id, + kind, + props, + children, + }); + } + + function action(command, label, payload = {}) { + return compact({ + schema: commandSchema, + command, + label, + payload, + }); + } + + function styleTokens(input = {}) { + return { + themeId: input.themeId || "sai.vn.default", + tokens: { + colorBackground: input.colorBackground || "#05080d", + colorPanel: input.colorPanel || "rgba(5, 8, 13, 0.92)", + colorPanelAlt: input.colorPanelAlt || "rgba(9, 14, 22, 0.82)", + colorText: input.colorText || "#f6f1e2", + colorMuted: input.colorMuted || "#b7c7d9", + colorAccent: input.colorAccent || "#ff8a2a", + colorLink: input.colorLink || "#59b7ff", + radiusPanel: input.radiusPanel || 8, + fontBody: input.fontBody || "Ubuntu", + fontTitle: input.fontTitle || "Montserrat", + pixelArt: input.pixelArt ?? true, + motion: input.motion || "subtle", + }, + controls: [ + { + id: "theme.accent", + kind: "color", + label: "Accent", + token: "colorAccent", + command: "style.patch", + }, + { + id: "theme.panel", + kind: "color", + label: "Panel", + token: "colorPanel", + command: "style.patch", + }, + { + id: "theme.motion", + kind: "select", + label: "Motion", + token: "motion", + options: ["none", "subtle", "expressive"], + command: "style.patch", + }, + ], + }; + } + + function graphComponent(graph = {}) { + if (!graph.nodes?.length) return null; + const rawXs = graph.nodes.map((node) => node.viewX ?? node.x ?? 0); + const rawYs = graph.nodes.map((node) => node.viewY ?? node.y ?? 0); + const minX = Math.min(...rawXs); + const maxX = Math.max(...rawXs); + const minY = Math.min(...rawYs); + const maxY = Math.max(...rawYs); + const spanX = Math.max(1, maxX - minX); + const spanY = Math.max(1, maxY - minY); + const normalizeX = (value) => + value >= 0 && value <= 1 ? value : (value - minX) / spanX; + const normalizeY = (value) => + value >= 0 && value <= 1 ? value : (value - minY) / spanY; + + return component( + "sai.graph", + "graph", + { + label: graph.label || "Ink knot graph", + layout: graph.layout || "norn.2d", + nodes: graph.nodes.map((node) => + compact({ + id: node.id, + label: node.label || node.id, + target: node.target || node.knot || node.id, + x: normalizeX(node.viewX ?? node.x ?? 0), + y: normalizeY(node.viewY ?? node.y ?? 0), + rank: node.rank, + order: node.order, + current: Boolean(node.current), + visited: Boolean(node.visited), + available: Boolean(node.available), + weight: node.weight, + }), + ), + edges: graph.edges || [], + }, + [], + ); + } + + function spriteComponents(sprites = []) { + return sprites.map((sprite, index) => + component(`sai.sprite.${sprite.actorName || index}`, "image.sprite", { + actor: sprite.actorName, + expression: sprite.expression || "default", + src: sprite.image || sprite.src, + alt: sprite.alt, + slot: sprite.position || "center", + scale: sprite.scale || 1, + offsetX: sprite.offsetX || 0, + offsetY: sprite.offsetY || 0, + }), + ); + } + + function domCardComponents(cards = []) { + return cards.map((card) => + component(`sai.card.${card.key}`, "card.external", { + key: card.key, + title: card.title || card.label, + selector: card.selector, + htmlRef: card.htmlRef, + mode: "provider-owned-fragment", + }), + ); + } + + function choiceComponents(choices = []) { + return choices.map((choice, index) => + component(`sai.choice.${choice.id || index}`, "control.button", { + label: choice.text || choice.label, + primary: index === 0, + action: action("story.choose", choice.text || choice.label, { + index, + targetPath: choice.targetPath, + }), + }), + ); + } + + function variableComponents(variables = []) { + if (!variables.length) return null; + return component( + "sai.variables", + "inspector.kv", + { + title: "Story Variables", + items: variables.map((item) => ({ + key: item.name, + value: item.value, + })), + }, + [], + ); + } + + function createVisualNovelSurface(input = {}) { + const metadata = input.metadata || {}; + const style = styleTokens(input.style || input.styleTokens || {}); + const scene = input.scene || {}; + const speaker = input.speaker || metadata.speaker || "Void"; + const line = input.line || ""; + const title = input.title || scene.label || "Sai Visual Novel"; + const graph = graphComponent(input.graph); + const variables = variableComponents(input.variables || []); + + const stageChildren = [ + component("sai.background", "image.background", { + src: input.background || scene.background, + label: scene.label, + fit: "cover", + pixelArt: style.tokens.pixelArt, + }), + graph, + component("sai.sprites", "layer.sprites", {}, spriteComponents(input.sprites)), + component("sai.cards", "layer.cards", {}, domCardComponents(input.domCards)), + component( + "sai.dialogue", + "panel.dialogue", + { + speaker, + avatar: input.avatar, + text: line, + scene: scene.label || metadata.scene, + }, + [ + component("sai.dialogue.avatar", "avatar", { + src: input.avatar, + label: speaker, + }), + component("sai.dialogue.text", "text.dialogue", { + speaker, + text: line, + }), + ], + ), + component("sai.choices", "rail.actions", {}, choiceComponents(input.choices)), + variables, + ].filter(Boolean); + + return compact({ + type: "surface-state", + schema: surfaceSchema, + providerKind, + providerId: input.providerId || "sai.vn", + title, + version: input.version || 1, + updatedAt: input.updatedAt || nowIso(), + surface: { + id: input.surfaceId || "sai.visual_novel.surface", + root: component( + "sai.root", + "vn.stage", + { + mode: "visual-novel", + storyId: input.storyId, + currentPath: input.currentPath || metadata.knot || metadata.route, + style: style.themeId, + }, + stageChildren, + ), + styles: style, + }, + selection: { + currentPath: input.currentPath || metadata.knot || metadata.route, + speaker, + }, + commands: [ + action("story.continue", "Continue"), + action("story.choose", "Choose", { index: 0 }), + action("story.jump", "Jump to knot", { targetPath: "" }), + action("style.patch", "Patch style", { token: "", value: "" }), + ], + assets: input.assets || [], + detail: { + source: "Sai Eve module", + notes: + "This document is a retained CultUI surface. Renderers project it to DOM, UIKit, Android views, Direct2D, or other native controls.", + }, + }); + } + + function createCommand(command, payload = {}, options = {}) { + return compact({ + type: "surface-command", + schema: commandSchema, + providerId: options.providerId || "sai.vn", + surfaceId: options.surfaceId || "sai.visual_novel.surface", + command, + payload, + issuedAt: options.issuedAt || nowIso(), + clientId: options.clientId, + }); + } + + function createStylePatch(token, value, options = {}) { + return createCommand("style.patch", { token, value }, options); + } + + const api = { + version: "0.1.0", + surfaceSchema, + commandSchema, + createVisualNovelSurface, + createCommand, + createStylePatch, + }; + + if (typeof module !== "undefined" && module.exports) { + module.exports = api; + } + + global.SaiEve = api; +})(typeof globalThis !== "undefined" ? globalThis : window);