Skip to content

docs: ADR 0004, Playground glossary and research - #199

Merged
mnaimfaizy merged 1 commit into
mainfrom
docs/playground-adr-0004
Oct 11, 2026
Merged

mnaimfaizy merged 1 commit into
mainfrom
docs/playground-adr-0004

Conversation

@mnaimfaizy

Copy link
Copy Markdown
Owner

Summary

Documentation only; no application code changes.

  • ADR 0004 (accepted): Playground traces share the story snapshot and the 2D/3D views, are recorded by AST instrumentation on the browser's own engine, and are never presented as stories. There is exactly one Playground, it is dark, and work is JavaScript-first. The old src/components/playground/ is to be retired.
  • CONTEXT.md: adds the Playground vocabulary (Playground, Trace, Step, Snapshot, Lens, Console, Example, Exercise), the story terms that were in use but undefined (Region, Entity, Cell, Slot, Reference, Focus, Timeline), the Marble diagram tool, and renames Step model to Beat model. Shot and Transcript are updated to match the code.
  • AGENTS.md: a Playground rules section and the dark-theme exception to "Light mode only". .github/copilot-instructions.md is regenerated by npm run agents:sync.
  • Research: the October 2026 playground audit (what happened when the Playground was run, and why) and the playground design research with sources.

Known gaps after this PR

  • The glossary says "Beat model", while AGENTS.md, the step-model skill, ADR 0001, the 3D standard and the code still say "step model". The rename is a separate pass.
  • The new Playground rules describe the target. The current Playground code does not follow them yet (its lenses still use React Flow).
  • The old playground is still mounted on the Big-O and Data Structures pages.

Checks

  • npm run agents:check passes.
  • tsc, lint, tests and build were not run locally, since no code changed.

🤖 Generated with Claude Code

Record the decision that Playground traces share the story snapshot and
the 2D/3D views, are recorded by AST instrumentation, and that there is
exactly one (dark) Playground. Extend CONTEXT.md with the Playground
vocabulary (trace, step, snapshot, lens, console, example, exercise) and
the story terms that were in use but undefined. Add the October 2026
playground audit and the design research the decision rests on.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@mnaimfaizy mnaimfaizy self-assigned this Oct 11, 2026
@mnaimfaizy
mnaimfaizy merged commit 9d643bb into main Oct 11, 2026
9 checks passed
@mnaimfaizy
mnaimfaizy deleted the docs/playground-adr-0004 branch October 11, 2026 08:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant