Lorelei Core

Lorelei is a lightweight visual novel engine for AI agents and LLM-driven scene loops.

Packages

• @lorelei-app/core: canonical turn contract, validation, parsing, reducer, session serialization
• @lorelei-app/agent-sdk: prompt helpers, ADVENTURE_DATA: extraction, session driver
• @lorelei-app/react: official React renderer and persistence hooks
• @lorelei-app/companion-adapter: companion relationship helpers, prompt shaping, and background resolution

Authored Runtime

Lorelei core now ships an authored story runtime for deterministic VN progression:

• createTurnFromStoryNode(...) builds the canonical start/scene turn for a story node
• applyStoryChoice(...) advances the current session through the authored graph
• LoreleiStoryRunner gives hosts one canonical runner for start(), choose(), snapshot(), and hydrate()
• selectStoryChoices(...) filters authored choices against runtime requirements
• session state persists story.currentNodeId, story.branchPath, story.variables, and visited nodes

That means hosts can let an LLM author scenes turn-by-turn, or run a published authored graph directly through the same session contract.

Scene Primitives

Lorelei scenes are still backward-compatible with the original single-beat shape, but v1 now supports richer VN presentation fields:

• dialogueLines[] for multi-line authored beats
• characters[] for visible cast/layer metadata
• transition for beat-to-beat scene changes
• audio.ambienceUrl and audio.sfx[]
• commands[] for host-facing scene actions

Canonical Turn

{
  "version": "1",
  "kind": "scene",
  "session": {
    "id": "session_demo",
    "status": "active",
    "step": 2
  },
  "scene": {
    "id": "scene_rooftop",
    "title": "Rooftop Pause",
    "description": "City light hangs in the air while the tension slows down.",
    "dialogue": {
      "speaker": "guide",
      "speakerName": "Companion",
      "content": "stay with me a second.",
      "emotion": "tender"
    },
    "background": {
      "scenario": "rooftop",
      "variant": "intimate"
    },
    "choices": [
      { "id": "c1", "text": "Move closer", "kind": "dialog" },
      { "id": "c2", "text": "Tease her first", "kind": "dialog" },
      { "id": "c3", "text": "Ask what she wants", "kind": "dialog" }
    ]
  }
}

Compatibility

Lorelei still supports terminal marker output:

ADVENTURE_DATA: { ... }

That marker is treated as a compatibility adapter, not the canonical format.

Package Commands

pnpm --filter @lorelei-app/core run type-check
pnpm --filter @lorelei-app/core run test
pnpm --filter @lorelei-app/core run build