@rashidazarang/subframe-engine-live

Reference reader implementation for the subframe-v1 dynamic attention format. Renders a book of compositions with sovereign continuous audio, reader-led narration, and reader-paced text — without coupling visual state to audio playback.

This is the TypeScript extraction of the original wireframe engine (docs/wireframes/engine/engine.js in the Subtrace repo) split into focused modules with a pluggable NarrationProvider abstraction.

Install

pnpm add @rashidazarang/subframe-engine-live @rashidazarang/subframe-core

Basic mount

import { mountBook } from '@rashidazarang/subframe-engine-live';

const root = document.getElementById('root');
if (!root) throw new Error('no root');

const handle = await mountBook('/compositions/book.json', root, {
  locale: 'es-ES',
  onStateChange: (state) => {
    console.log('engine state', state);
  }
});

// Later
handle.unmount();

The engine builds the chrome (TOC, control bar, breathing background) once, then loads chapters on-demand. URL-hash routing (#/chapter-id/paragraph-id), localStorage persistence, prev/next chapter nav, and the click-to-snap-narration gesture all work out of the box.

AudioProvider extension

Narration backends are pluggable through the NarrationProvider interface. The simplest path is selectNarrationProvider, which probes mentu-ane first and falls back to the platform voice (or a no-op that surfaces NarrationUnavailableError when nothing is available, so the engine's toggle UI doesn't get stuck "on" silently):

import { mountBook, selectNarrationProvider } from '@rashidazarang/subframe-engine-live';

const narrationProvider = await selectNarrationProvider();
await mountBook('/book.json', root, { narrationProvider });

If you need explicit control:

import {
  mountBook,
  MentuANEVoiceProvider,
  PlatformVoiceProvider
} from '@rashidazarang/subframe-engine-live';

await mountBook('/book.json', root, {
  // PlatformVoiceProvider tries pre-rendered `segment.src` first, falls back
  // to speechSynthesis when the audio file 404s or decode fails.
  narrationProvider: new PlatformVoiceProvider()
});

PlatformVoiceProvider wraps the browser Audio element + speechSynthesis API in that order. MentuANEVoiceProvider is a stub today — calling its speak() directly throws MentuANEUnavailableError. Until the mentu-ane on-device TTS daemon is published, prefer selectNarrationProvider over instantiating MentuANEVoiceProvider directly. See the comment block in src/audio/MentuANEVoiceProvider.ts for the wire-up plan.

SoundtrackProvider produces a Web Audio drone fallback as a SoundtrackBuffer; you can swap in a streamed track that publishes the same gainNode and stop() shape.

Sovereignty rule

This engine honors the subframe-v1 sovereignty rule (spec/subframe-v1.md § 9). Specifically:

• Continuous tracks own their timeline. The soundtrack does not pause, mute, or seek on paragraph clicks, scrolls, narration toggles, or chapter swaps within the same book session. The only state changes are explicit mute/unmute, segment end, and the duck-gain envelope (which is a gain change, not a timeline change).
• Reader-led tracks follow the reader. Active-paragraph is set by reader gesture (click, hash, resume) or post-segment auto-advance. The implementation does not compute the active paragraph from any audio timeline. Sub-paragraph highlight synchronized to audio playback is forbidden.

The Apple Books Read Aloud pattern (audio-driven classList.add per word, audio-driven page turn) is the canonical non-conformant shape and is what the rule is written to exclude.

Module layout

| Module | Role | | --- | --- | | src/index.ts | Public mountBook and EngineHandle | | src/loader.ts | Chapter load + asset URL resolution | | src/render.ts | DOM rendering of header, paragraphs, nav, footer | | src/router.ts | Hash parse / write, chapter lookup, neighbors | | src/persistence.ts | localStorage-backed reader state | | src/controls.ts | Control bar, toggles, active paragraph | | src/narration.ts | Reader-led narration, ducking, snap | | src/toc.ts | Table of contents overlay | | src/scroll.ts | Smooth scroll animation | | src/state.ts | Shared EngineState | | src/audio/* | NarrationProvider / SoundtrackProvider and implementations |

Scripts

pnpm typecheck   # tsc --noEmit
pnpm test        # vitest run (jsdom)
pnpm build       # tsc → dist

License

Apache-2.0