docs(sdk-playground): accurate README with stage coverage and CanResult

[vanceingalls]

What

Rewrites packages/sdk-playground/README.md to accurately document what the playground does, what SDK stages it exercises, and what's still unimplemented.

Why

The original README had several inaccuracies that would mislead reviewers:

• Wrong ops table row — moveElement listed comp.moveElement(id, { parent, index }) but that method/signature doesn't exist. Drag-to-reposition uses comp.setStyle(id, { left, top }) internally. No explicit moveElement button in the ops panel.
• Outdated can() docs — described as returning a plain boolean; it now returns CanResult {ok: boolean, code?: string, message?: string, hint?: string} (landed in PR feat(sdk): can() returns CanResult; T4 dispatch-boundary tests #1426).
• Missing stage map — no explanation of which SDK stages the playground actually exercises, making it hard for reviewers to assess coverage.
• Keyframe ops not called out — addGsapKeyframe, setGsapKeyframe, removeGsapKeyframe are implemented in the SDK but have no UI in the playground; the old README omitted this gap.

Changes

• Added "What this demonstrates" table mapping playground features → SDK stages (3a session API, 3b GSAP engine, 4 partial: can/getOverrides/selection/find, 5 partial: FsAdapter/FileAdapter/PlaygroundPreview)
• Fixed ops panel table: removed incorrect moveElement row; added combined setGsapTween / removeGsapTween row; fixed addLabel/removeLabel dispatch syntax
• Updated can() docs to show CanResult shape with example
• Added Event log section (patch/undo/redo/selectionchange/persist:error all logged with full payload — useful for verifying RFC 6902 patch shape)
• Moved keyframe ops to Planned / not yet wired with note that SDK impls exist

Test plan

• README renders correctly on GitHub (tables, code spans)
• All ops panel table rows correspond to actual buttons in the playground (bun run --cwd packages/sdk-playground dev → Ops tab)
• "Planned" section accurately reflects what has no UI button

[vanceingalls]

• docs(sdk-playground): accurate README with stage coverage and CanResult #1429 👈 (View in Graphite)
• feat(sdk): stage 6 — sub-composition scoped ids (F9) #1434 : 1 other dependent PR (#1441 )
• feat(sdk): stage 5 — export adapter factories from package root #1432
• feat(sdk): stage 4 — canUndo/canRedo, removeElement GSAP cascade, override-set cleanup #1431
• feat(sdk): can() returns CanResult; T4 dispatch-boundary tests #1426
• fix(sdk): fs adapter flush() tracks in-flight writes; add to T13 contract suite #1425
• feat(sdk): file-backed fs adapter + setTiming GSAP-script sync; add sdk-playground #1423
• refactor(core): swap studio-api read path from recast to acorn parser (T6e) #1392
• feat(core): parse-parity suite for acorn parser (T6d) #1370 : 1 other dependent PR (#1379 )
• feat(core): acorn GSAP write path — magic-string offset-splice (T6c) #1369
• feat(core): acorn GSAP read path with T6b differential corpus tests #1368
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[james-russo-rames-d-jusso]

Verified at HEAD cb7cfd18.

Docs/playground README rewrite. Cross-checked the stage-coverage table and ops-panel rows against the actual SDK exports + playground wiring at the PR head. The mapping is accurate. No forward-reference to unmerged stages.

Verified

• Stage 5 row — createHeadlessAdapter + createMemoryAdapter are re-exported from @hyperframes/sdk and the playground imports both (main.ts:1, live demo at main.ts:1096–1104). README claim matches code.
• Stage 6 row — find({ composition }) exists in the sibling PR #1434 (session.ts:186); scoped-dispatch form is wired in the playground at main.ts:1070. Demo composition has the hf-card host with hf-card-title / hf-card-body so the documented example resolves against real DOM.
• CanResult shape — README example matches the type from PR #1426 ({ok, code?, message?, hint?}).
• Removed moveElement row is correct — no such op handler exists in the SDK.
• "Planned / not yet wired" section accurately calls out the keyframe ops gap.

Concern — Stage 6 row claims scoped-dispatch parity for "ops"

The Ops-panel "Scoped dispatch" row says comp.setStyle("hf-card/hf-card-title", styles) — Stage 6: address elements inside inlined sub-compositions. This is true for setStyle / setText / setAttribute / removeElement / setTiming (all resolve via resolveScoped per #1434). But addGsapTween with a scoped target writes a broken CSS selector (see my #1434 review for the underlying bug). If that's not fixed in #1434, the playground README should either (a) explicitly call out that addGsapTween does NOT yet accept scoped targets, or (b) wait on the #1434 fix before claiming full op coverage. Soft concern only — depends on #1434 verdict.

Nit — table column width

The Stage 5 / Ops-panel tables have very long second-column rows (line lengths past 200 chars). GitHub renders fine but README.md raw is awkward to diff. Not worth a reflow. (nit)

What I didn't verify

• Did not run bun run --cwd packages/sdk-playground dev to confirm every documented button exists in the rendered UI.
• Did not render the README on GitHub to confirm table alignment — relied on raw markdown shape only.

Review by Rames D Jusso

[jrusso1020]

Approved.

[miguel-heygen]

Docs-only PR — no code changes. CI blocked by root oxfmt failure in #1423.

README accurately reflects the stage coverage (T1–T7), CanResult API shape, and adapter contract table. A few content notes:

Nit:

• The "Stage coverage" table lists T7 as "HTTP persist adapter" but T7 now includes SDK session wiring into Studio, setSelection, reload-on-change, shadow dispatch, and cutover (PRs #1441–#1452). The table will need another pass once the full T7 stack merges.
• CanResult code examples in the README use result.code === "E_UNKNOWN_OP" — would be better to import the exported constant once #1426 exports it (see that PR's review).

Verdict: APPROVE (pending #1423 oxfmt fix)
Reasoning: Docs are accurate for the current merge state. Minor freshness notes above are follow-ups, not blockers.

— magi