Guides: tapes to browse beside the site's markdown #7

The web app opens on the site's markdown (fizzyed.it/app/?open=/site.zip), with a list of guides to browse beside it. Pick a guide and it plays over the site; when it ends, the person is back in the site's markdown. This is milestone 6 of AUTOMATION_PLAN.md (plugin demos, registerDemo), coming in through the browser that lists them.

What there is:

• A demo already costs the person nothing. Demo.begin sets their session aside (project folder, open documents), and end closes the demo's files, reloads their layout and reopens what they had.
• The tapes are hosted beside each copy of the app as demos/*.tape plus demos/index.json (web: the site's copies of the app serve every demo as a tape fizzy#569). ?demo=<url> already plays one.
• Guides can be found only through the palette's "Demo: …" commands and Help › Take the Tour. The automation service plays only live tapes. A guide is a demo tape: it opens on a keyframe and goes through Demo.playTape, which only fizzy can call. A plugin can neither list guides nor play one.

Decided:

• The browser is a plugin (guides). Fizzy owns no features. What it needs from the host is a general seam: a registry of demos it can list and play. Pixi's own guides come in through the same seam later.

• A registered demo is tape bytes the host copies, not a build callback across the boundary. A plugin builds its Script in register and hands over tape.binary bytes. Fizzy's bundled demos are listed from catalog.entries and still built when played, so they read the window they play in.

• Hosted guides are web-only. A native app lists bundled and plugin guides. Tapes fetched from the site may be for a different version of the app.

• 0. Check the premise: a demo started over ?open=/site.zip gives back the mounted zip, its open files and the explorer when it ends. saved.folder has only been exercised with disk folders. Fix it here if it doesn't. It didn't: the keyframe closed the zip's tab, which unmounted it, and a path can't reopen what the page fetched. Fixed by keeping the bytes of what its path can't reopen (app: a demo gives back a folder opened from a zip's bytes fizzy#596).

• 1. sdk: a demo registry (label sdk, fingerprint moves), sdk: plugins register demos, and the demos service lists and plays them fizzy#608. Host.registerDemo(.{ name, title, tape }), with the host keeping its own copy of the bytes. A demos service of its own (sdk.services.demos, not the automation service, which is live tapes on whatever is open): list (name, title, length, chapters, origin), play(name, at_ms) with the same refusals as Demo.play (busy, unsaved) plus unknown, current, and generation. Bundled demos are listed through it. One fizzy.demo.play command plays any listed demo by name, rather than a palette row per plugin demo: a Command carries only its owner's state, so per-demo rows at runtime would need a context it doesn't have.

• 2. guides: the plugin (guides: a rail view lists the demos and plays the one clicked fizzy#613; a tree in #619; folding fixed in #628). A view with a rail icon lists the registry, each row with its title, length and chapters. A click plays the guide, and a chapter row starts it at that chapter. While a guide plays, its row shows that it is the current one.

• 3. web: hosted guides. At startup on the web, the host reads demos/index.json beside the page (core.transport) into the registry, and fetches a tape only when it is played. scripts/demos.zig writes each tape's chapters (title and time) into index.json. A bundled demo also listed as hosted is listed once, as bundled.

• 4. web: open on a view. A ?view=<id> parameter opens with that view showing (?open=/site.zip&view=guides). Then fizzyedit/website's links and embed use it, with the embed loading the app only on a click so the page stays light.

Not here: recording guides (RECORDER_PLAN.md), and plugin demos with requires chapters (the rest of milestone 6).

🤖 Generated with Claude Code

The tour, rewritten (fizzyedit/fizzy#629, draft): tabs, places, floats, materials, plugins and history in under a minute. What it needed, each its own PR:

• settings: the window's material is a setting fizzy#621: the window material as a setting, with fizzy.windowMaterial for tapes (the settings step of roadmap#6).
• app: a demo sets the person's panes aside fizzy#623: a demo sets the person's panes aside.
• app: the history grip fills toward the history's cap fizzy#624: the history grip fills toward the history's cap.
• replay: a seek back to a keyframe checks no snapshot of the scene before fizzy#626: a seek back to a keyframe checks no snapshot of the scene before.