Demo And Story System

This document describes the planned demo/story architecture for AppWeaver. The goal is to show important workflows with the real web UI while keeping user data safe and keeping stories reusable as in-app tutorials.

Goals

Source Of Truth

Stories are authored locally beside the module that owns the workflow:

Generated JSON is not the source of truth. It is only a static export for the no-backend demo app.

Real App Runtime

The real app discovers stories by traversing the same runtime structures used by command/help/palette systems:

The /story built-in command is the user-facing entry point:

Story cards render in the normal timeline. We do not plan to use a timeline singleton for story cards.

Static Demo Runtime

The static demo has no backend, so it still needs generated data:

These files should remain committed artifacts so the static demo works predictably.

The generated files are produced from the same authored story modules used by the real app.

The static demo should eventually stop using a split-screen story navigator. Instead, it should open the normal app UI and use query params to start story mode:

The demo may also expose a highlighted header shortcut for stories/demo mode.

Presentation Model

Stories use normal timeline cards for the transcript:

When a story requires an exact user action, the app enters walkthrough mode.

Walkthrough Mode

Walkthrough mode is a client runtime layer, not just WebNode markup.

It should:

The first implementation should support both:

Example targets:

{ type: 'header_widget', command: 'todo', subcommand: 'list' }
{ type: 'web_node_action', command: 'todo', subcommand: 'add', options: { under: 101 } }

The walkthrough overlay state should live in an app-level client runtime, for example a StoryRuntimeProvider in the web app.

Sandbox Data

Mutating stories must use sandbox data.

When a story starts:

When a story quits or completes:

For the Todo plugin, a story can define initial sandbox state such as:

{
  todo: {
    items: [/* deterministic todos */],
    nextId: 104
  }
}

Story sandbox seeds should be defined inside the story definition. Larger fixture modules can be introduced later if story data grows too large.

Story Transport

When a story is active, the core should replace the normal story-relevant transport with a sandbox/stub transport for the duration of the story.

This is similar to the static demo stubs, but controlled by the core story runtime:

This keeps story workflows safe and deterministic while preserving the real UI.

Step Vocabulary

The initial guided story vocabulary should stay small:

Example sketch:

{
  id: 'todo-list-bootstrap',
  title: 'Open the Todo list',
  sandbox: {
    todo: {
      items: bootstrapItems,
      nextId: 104,
    },
  },
  steps: [
    {
      type: 'instruction',
      text: 'Open the Todo widget from the header.',
    },
    {
      type: 'focus_target',
      target: { type: 'header_widget', command: 'todo', subcommand: 'list' },
    },
    {
      type: 'wait_for_action',
      match: { type: 'widget_opened', command: 'todo', subcommand: 'list' },
    },
    {
      type: 'complete',
    },
  ],
}

Story Sequencing

Stories are ordered by catalog order for now.

Stories may optionally define nextStoryId. If present, completion should offer that story as the primary continuation instead of the next story from catalog order.

When a story completes, the runtime should append a completion card with:

If nextStoryId is absent, the runtime falls back to catalog order.

AI And Prompt Stories

AI/prompt-driven stories need a dedicated technical plan.

Open design questions include:

The first AI/prompt story should likely support only one golden path, such as:

Full branch coverage is a non-goal for the first AI/prompt story implementation.

Current State

Implemented pieces:

Not implemented yet:

Migration Plan

  1. Keep current /story list and /story start command surface.
  2. Add a client story runtime that can own active story state.
  3. Add walkthrough overlay support for header widget targets.
  4. Add WebNode/action target registration and highlighting.
  5. Add sandbox transport replacement for active stories.
  6. Implement Todo sandbox handlers for list and add first.
  7. Convert todo-list-bootstrap to the minimal guided step vocabulary.
  8. Add query-param startup for /demo/app/.
  9. Replace the split-screen static demo with normal in-app story flow.
  10. Expand Todo stories to include add-child and AI draft workflows.

Non-Goals For Now