# Sai **Ink stories that wake up inside static sites.** Sai is a small browser embedder for compiled Ink stories. It is not an Ink engine; it uses `inkjs` for that. Sai owns the article-shaped part: loading a story into an existing page, reading a visual manifest, rendering transcript, visual-novel, or cinematic layouts, and staying pleasant to drop into Quartz, Eleventy, Astro, Hugo, plain HTML, or whatever shrine of markup you dragged home at midnight. The name is the pitch: ink that becomes a living scene. ## Why Sai Exists Most Ink web players answer: "Can I play this story in a browser?" Sai answers: "Can this story become part of a page?" It is for interactive essays, lore posts, documentation rituals, cheap visual novels, pitch decks, character sermons, branching articles, and other story objects that want to live inside a site instead of becoming a separate web app. ## Quick Start Copy the built files from `dist/` into your site's static assets: ```text sai.js sai.css ink.js ``` Add the assets to a page: ```html ``` Embed a story: ```html
``` Sai auto-initialises every `.sai-player` when the document loads. It also listens for Quartz-style `nav` events after client-side page swaps. ## Formats ### Raven ```html ``` The default format is a compact interactive-fiction transcript. It is the simplest Raven Collective-style shape: text, choices, variables when useful, and no stage machinery. ### Visual Novel ```html ``` Visual-novel mode renders one scene image, a fixed dialogue bar, speaker avatar, speaker name, line text, optional character sprites, optional DOM cards, and a right-side option rail. Ink tags drive the speaker, scene, staged sprites, and staged page elements: ```ink # speaker: Void # scene: agora # avatar: void # sprite: welcome@left # sprites: Void.welcome@left, Aqua.listen@right # dom: roadmap, receipts The world is full of systems that say one thing and reward another. ``` If a speaker has `sprites` in the visual manifest, Sai shows the speaker's default sprite automatically. Use `# sprite: none` for lines that should stage only background, DOM cards, and dialogue. The `dom` tag reads card definitions from the visual manifest and clones matching page DOM into the scene stage. This is for static-site tours where the story frames canonical Quartz/HTML content without making the story file a second source of truth. ### Cinematic ```html ``` Cinematic mode is for slide/deck-like fragments: background plates, captions, references, and short blocks of text. ## Data Attributes - `data-ink-story`: required URL for compiled Ink JSON. - `data-ink-format`: `raven`, `visual-novel`, or `cinematic`. - `data-visual-manifest`: optional visual manifest URL. - `data-scene-label`: optional fallback scene label for visual-novel mode. - `data-ink-title`: optional player title/status text. - `data-ink-runtime`: optional URL for `ink.js`. - `data-sai-runtime`: alias for `data-ink-runtime`. - `data-show-variables="true"`: show Ink variables in visual modes. Legacy `.aetheria-ink-player` containers are still initialised so existing GameCult pages can migrate without ritual screaming. New work should use `.sai-player`. ## JavaScript API ```js window.Sai.init(document.querySelector(".sai-player")); window.Sai.initAll(); console.log(window.Sai.version); ``` By default, `sai.js` loads `ink.js` from the same directory as itself. Override that with `data-ink-runtime`, `data-sai-runtime`, or `window.Sai.runtimeSrc`. ## Visual Manifest 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 npm install npm run build npm run check ``` Compile the example story after dependencies are installed: ```powershell npm run compile:example ``` Open `examples/static-site/index.html` through a local static server. Browsers are right to dislike `fetch()` from `file://`; do not take it personally. ## Boundary 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 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 The brush is sharp. The painting is yours.