[foxnne]

Part of fizzyedit/plans#30 (step 1: a demo registry).

What changes

A plugin can ship demos, and anything can list and play the demos the app has. This is the seam the guides plugin (step 2) is built on, and that pixi's own guides come in through later.

• host.registerDemo(.{ .name, .title, .tape }), called in register. The tape is ZON or binary bytes built with the SDK's tape module. The host copies the name, title and tape, so nothing points into the plugin's image, and drops them when the plugin unregisters. A name already registered is refused (error.DemoExists). Host.demos_generation moves whenever the list changes.
• The demos service (sdk.services.demos), provided by fizzy in src/editor/Demos.zig:
  • list returns every demo fizzy can play, its own first, each with its length, chapters and origin (bundled, plugin, or hosted for step 3).
  • play(name, at_ms) plays one, from a chapter's start if asked. It returns unknown, busy (a live tape is driving) or unsaved (the same refusals a demo already had, now with a reason).
  • current names the demo playing. A tape loaded some other way since isn't mistaken for it.
  • generation is cheap to ask every frame.
• The list is built lazily, and again only when the host's demos change. A plugin's tape is loaded the way a demo is played. One that wouldn't play is left out with a warning instead of being listed and then refused: a live tape, a step no loaded plugin applies, or a name fizzy already has.
• fizzy.demo.play ("Demo: Play by Name…") plays any listed demo by name, from at. The bundled demos keep their own palette rows. A plugin's demo gets none, because a Command carries only its owner's state, so one row per runtime demo would need a context it doesn't have. The guides view (step 2) is where those are browsed.
• Demo.startable says why a demo can't start, and Demo.loadDemoTape is the demo check playTape already used.

Changed from the plan: the plan had the automation service growing demos() and playDemo(). automation is about live tapes on whatever is open. A demo is fizzy's player setting the session aside, so it got a service of its own, and automation's version is untouched.

SDK impact

• None
• Core-only or additive: reaches plugins at the next SDK release
• Fingerprint moved: recorded in sdk/src/version.zig, sdk_version untouched, PR labelled sdk
• SDK release: bumps sdk_version, lists the sdk PRs since the last sdk-v* tag

For plugin authors: sdk.Demo and Host.registerDemo are new; sdk.services.demos is a new service at version 1. Nothing existing changed shape.

Verified

• macOS:
  • zig build test: a new Host test checks that registerDemo keeps its own copy (the caller's buffers are overwritten after it returns), refuses a name twice, and drops a plugin's demos at unregisterPlugin, with the generation moving each time.
  • zig build test-integration (81/81 steps, after merging main with app: a demo gives back a folder opened from a zip's bytes #596 in): the demo test lists the bundled demos through the service, then registers three demos. A plugin demo is listed with two chapters; one reusing the name tour and a live tape are left out, with exactly those two warnings. The plugin demo plays by name to its end, named by current. Started at its second chapter, it's at that chapter. A tape loaded another way isn't current, and nothing is once unloaded.
  • zig build, zig build check-web, zig build test-sdk-version, zig build check-tests-reached, scripts/check-fmt.sh.
• Windows:
• Linux:
• Web: compiles (check-web); not run in a browser.

Follow-ups

• Step 2, the guides plugin, lists the service and plays what's clicked.
• Step 3: hosted returns unknown until the web's demos/index.json is read into the list.

🤖 Generated with Claude Code