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

Author: vanceingalls

packages/sdk-playground/README.md

@@ -10,6 +10,19 @@ bun run --cwd packages/sdk-playground dev
 
 Serves at `http://localhost:5173`. On first load it reads `packages/sdk-playground/composition.html` from disk (if present) or falls back to a built-in demo composition.
 
+## What this demonstrates
+
+The playground exercises the full SDK surface end-to-end in a real browser against a
+file-backed persist adapter. It was built to verify SDK stages 3b and 4 before Studio
+migration begins:
+
+| SDK stage              | What is exercised                                                                                                                                       |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Stage 3a — Session API | `openComposition`, `dispatch`, `undo`/`redo`, `batch`, `on('patch')`, `on('selectionchange')`, `on('persist:error')`, `flush`                           |
+| Stage 3b — GSAP engine | `addGsapTween`, `setGsapTween`, `removeGsapTween`, `addLabel`, `removeLabel`, `setClassStyle`, `setTiming` (GSAP-script sync)                           |
+| Stage 4 (partial)      | `can()` returning `CanResult`, `getOverrides()`, `selection()` proxy, `find()`, `setVariableValue`                                                      |
+| Stage 5 (partial)      | `FsAdapter` — file-backed persistence with version history; `FileAdapter` — browser fetch adapter; `PlaygroundPreview` — concrete `PreviewAdapter` impl |
+
 ## Features
 
 ### File persistence
@@ -22,7 +35,7 @@ Full composition rendered in a sandboxed `<iframe>`. Supports:
 
 - **Play / Pause / Seek** via the transport bar
 - **Click-to-select** elements (highlights in the tree and properties panel)
-- **Drag-to-reposition** — drag any element to a new position; on drop the playground calls `comp.setStyle(id, { left, top })`
+- **Drag-to-reposition** — drag any element; on drop calls `comp.setStyle(id, { left, top })`
 
 ### Element tree
 
@@ -35,50 +48,55 @@ Editable per-element properties for the selected element:
 | Section    | SDK op                                                                      |
 | ---------- | --------------------------------------------------------------------------- |
 | Content    | `comp.setText(id, value)`                                                   |
-| Typography | `comp.setStyle(id, { fontSize, fontWeight, color, fontFamily })`            |
-| Box        | `comp.setStyle(id, { top, left, width, height })`                           |
-| Attributes | `comp.element(id).setAttribute(name, value)` — shows all non-internal attrs |
+| Typography | `comp.setStyle(id, { fontSize, fontWeight, color })`                        |
+| Box        | `comp.setStyle(id, { background, opacity, left, top })`                     |
+| Attributes | `comp.element(id).setAttribute(name, value)` — all non-internal attrs       |
 | Danger     | `comp.element(id).removeElement()`                                          |
-| Animations | `comp.setTiming(id, { start, duration })` — inline form per GSAP tween      |
+| Animations | Lists tween IDs + inline "Add tween" form via `comp.addGsapTween(id, spec)` |
 
 ### Timeline
 
-DAW-style per-element tween blocks. Drag handles to trim start/end; drag body to move. All edits go through `comp.setTiming(id, { start, duration })` which keeps the GSAP script and DOM attributes in sync.
+DAW-style per-element tween blocks. Drag handles to trim start/end; drag body to move. All edits go through `comp.setTiming(id, { start, duration })`, which keeps the GSAP script and `data-start`/`data-end` attributes in sync.
 
 ### Ops panel
 
 Full op surface, grouped by feature:
 
-| Section                      | SDK op                                                                            |
-| ---------------------------- | --------------------------------------------------------------------------------- |
-| PreviewAdapter.select()      | `preview.select([id])`                                                            |
-| setStyle                     | `comp.setStyle(id, styles)`                                                       |
-| setText                      | `comp.setText(id, value)`                                                         |
-| addGsapTween                 | `comp.addGsapTween(target, spec)`                                                 |
-| setTiming                    | `comp.setTiming(id, { start, duration })`                                         |
-| setGsapTween                 | `comp.setGsapTween(animId, updates)`                                              |
-| moveElement                  | `comp.moveElement(id, { parent, index })`                                         |
-| setClassStyle                | `comp.dispatch({ type: "setClassStyle", selector, styles })`                      |
-| setAttribute / removeElement | `comp.element(id).setAttribute()` / `.removeElement()`                            |
-| setVariableValue             | `comp.setVariableValue(id, value)`                                                |
-| find(query)                  | `comp.find({ tag, text, name, track })`                                           |
-| selection() proxy            | `comp.selection().setStyle()` / `.removeElement()`                                |
-| listVersions / loadFrom      | `adapter.listVersions()` / `adapter.loadFrom()`                                   |
-| History / inspect            | `comp.undo()`, `comp.redo()`, `comp.can()`, `comp.getOverrides()`, `comp.flush()` |
+| Section                        | SDK op                                                                                          |
+| ------------------------------ | ----------------------------------------------------------------------------------------------- |
+| PreviewAdapter.select()        | `preview.select([id])`                                                                          |
+| setStyle                       | `comp.setStyle(id, styles)`                                                                     |
+| setText                        | `comp.setText(id, value)`                                                                       |
+| addGsapTween                   | `comp.addGsapTween(target, spec)`                                                               |
+| setGsapTween / removeGsapTween | `comp.setGsapTween(animId, { duration })` / `comp.removeGsapTween(animId)`                      |
+| addLabel / removeLabel         | `comp.dispatch({ type: "addLabel", name, position })` / `removeLabel`                           |
+| setClassStyle                  | `comp.dispatch({ type: "setClassStyle", selector, styles })`                                    |
+| setAttribute / removeElement   | `comp.element(id).setAttribute()` / `.removeElement()`                                          |
+| setVariableValue               | `comp.setVariableValue(id, value)`                                                              |
+| find(query)                    | `comp.find({ tag, text })`                                                                      |
+| selection() proxy              | `comp.selection().setStyle()` / `.removeElement()`                                              |
+| listVersions / loadFrom        | `adapter.listVersions(path)` / `adapter.loadFrom(path, key)`                                    |
+| History / inspect              | `comp.undo()`, `comp.redo()`, `comp.can(op) → CanResult`, `comp.getOverrides()`, `comp.flush()` |
+
+`can(op)` returns a `CanResult`: `{ok: true}` or `{ok: false, code, message, hint?}`. The ops panel logs the full result object so you can inspect validation failures in real time.
 
 ### Editor modal
 
-Click "Open editor" to view and directly edit the raw composition HTML. Saving re-opens the composition through the SDK.
+Click "Open editor" to view and directly edit the raw composition HTML. Saving re-opens the composition through the SDK, so all patches and history are reset cleanly.
+
+### Event log
+
+Every `patch`, `undo`, `redo`, `selectionchange`, and `persist:error` event is logged with its payload. Useful for verifying RFC 6902 patch shape and override-set accumulation.
 
 ---
 
 ## Planned / not yet wired
 
+- `addGsapKeyframe` / `setGsapKeyframe` / `removeGsapKeyframe` — ops are implemented in the SDK; not yet exposed in the UI
 - `comp.setTrackVariable(trackId, variableId)` — variable binding per track
 - `comp.addElement(spec)` — create new elements from the UI
 - `comp.duplicateElement(id)` — duplicate with offset
 - Selection multi-select (current: single-select only)
 - Timeline zoom and horizontal scroll for long compositions
-- Version history browser — list/preview/restore past versions inline (API is implemented; UI shows only list + load-oldest)
-- `comp.on('change', cb)` live event log fed from SDK event stream
+- Version history browser — list/preview/restore past versions inline (listVersions/loadFrom API is implemented; UI shows raw list + load-oldest button only)
 - Render to video via `@hyperframes/producer` integration

packages/sdk-playground/src/main.ts

@@ -11,7 +11,7 @@ const DEMO_HTML = `
 <div data-hf-id="hf-stage" data-hf-root style="width:1280px;height:720px;background:#111827;position:relative;" data-duration="6">
   <style>.badge{background:#3b82f6;border-radius:6px;}</style>
   <div data-hf-id="hf-headline" style="position:absolute;top:200px;left:140px;font-size:72px;font-weight:700;color:#f9fafb;font-family:system-ui,sans-serif;">SDK Playground</div>
-  <div data-hf-id="hf-sub" style="position:absolute;top:300px;left:142px;font-size:28px;color:#9ca3af;font-family:system-ui,sans-serif;">@hyperframes/sdk &middot; Phase 3b</div>
+  <div data-hf-id="hf-sub" style="position:absolute;top:300px;left:142px;font-size:28px;color:#9ca3af;font-family:system-ui,sans-serif;">@hyperframes/sdk &middot; Phase 3b + 4</div>
   <div data-hf-id="hf-badge" class="badge" style="position:absolute;top:390px;left:142px;padding:10px 24px;font-size:20px;font-weight:600;color:#fff;font-family:system-ui,sans-serif;">v0.6</div>
   <script>
 var tl = gsap.timeline({ paused: true });
@@ -936,37 +936,51 @@ function buildSelectionProxySection(): HTMLDivElement {
 }
 
 function buildVersionsSection(): HTMLDivElement {
-  const display = mkNote("");
-  display.style.maxHeight = "80px";
-  display.style.overflowY = "auto";
+  const display = document.createElement("div");
+  display.style.cssText = "max-height:100px;overflow-y:auto;margin-top:4px;";
   const list = mkBtn("List versions", "", () => listVersionsInto(display));
-  const loadOldest = mkBtn("Load oldest", "", () => loadOldestVersion());
-  return opSection("listVersions / loadFrom", opRow(list, loadOldest), display);
+  return opSection("listVersions / loadFrom", opRow(list), display);
 }
 
 async function listVersionsInto(display: HTMLElement) {
   const { adapter } = await createFileAdapter();
   const versions = await adapter.listVersions("composition.html");
-  display.textContent = versions.length ? versions.map(versionLabel).join("\n") : "(no versions)";
+  display.innerHTML = "";
+  if (!versions.length) {
+    display.textContent = "(no versions saved yet)";
+    return;
+  }
   logEntry("info", { versions: versions.map((v) => v.key) });
+  for (const v of versions) {
+    const row = document.createElement("div");
+    row.className = "op-note";
+    row.style.cssText += "cursor:pointer;padding:3px 4px;border-radius:3px;";
+    row.textContent = versionLabel(v);
+    row.title = `Click to restore ${v.key}`;
+    row.addEventListener("mouseenter", () => (row.style.background = "#374151"));
+    row.addEventListener("mouseleave", () => (row.style.background = ""));
+    row.addEventListener("click", () => loadVersion(adapter, v.key));
+    display.appendChild(row);
+  }
 }
 
 function versionLabel(v: { key: string; timestamp?: number }): string {
-  return `${v.key} (${new Date(v.timestamp ?? 0).toLocaleTimeString()})`;
-}
-
-async function loadOldestVersion() {
-  const { adapter } = await createFileAdapter();
-  const versions = await adapter.listVersions("composition.html");
-  const oldest = versions[versions.length - 1];
-  if (!oldest) {
-    logEntry("info", "no versions");
+  const ts = v.timestamp ?? 0;
+  const time = ts > 0 ? new Date(ts).toLocaleTimeString() : "unknown time";
+  return `${time}  (${v.key})`;
+}
+
+async function loadVersion(
+  adapter: import("@hyperframes/sdk/adapters/types").PersistAdapter,
+  key: string,
+): Promise<void> {
+  const html = await adapter.loadFrom("composition.html", key);
+  if (!html) {
+    logEntry("info", `version ${key} not found`);
     return;
   }
-  const html = await adapter.loadFrom("composition.html", oldest.key);
-  if (!html) return;
-  await openEditor(html, `v${oldest.key}`);
-  logEntry("info", `loaded version ${oldest.key}`);
+  await openEditor(html, `restored ${key.split("_")[0]}`);
+  logEntry("info", `loaded version ${key}`);
 }
 
 function buildHistorySection(): HTMLDivElement {
@@ -978,19 +992,38 @@ function buildHistorySection(): HTMLDivElement {
     comp!.redo();
     logEntry("redo", "dispatched");
   });
+
+  const canResult = document.createElement("div");
+  canResult.className = "op-note";
+  canResult.style.cssText += "font-size:10px;padding:2px 4px;";
+  canResult.textContent = "—";
+
   const canCheck = mkBtn("can(addGsapTween)?", "", () => {
     const r = comp!.can({
       type: "addGsapTween",
       target: "hf-badge",
       tween: { method: "to", duration: 0.5 },
     });
     logEntry("info", { "can(addGsapTween)": r });
+    if (r.ok) {
+      canResult.textContent = "✓ ok";
+      canResult.style.color = "#34d399";
+    } else {
+      canResult.textContent = `✗ ${r.code}: ${r.message}`;
+      canResult.style.color = "#f87171";
+    }
   });
+
   const overrides = mkBtn("getOverrides()", "", () => logEntry("info", comp!.getOverrides()));
   const flush = mkBtn("flush", "", () => {
     comp!.flush().then(() => logEntry("info", "flush complete"));
   });
-  return opSection("History / inspect", opRow(undo, redo), opRow(canCheck, overrides, flush));
+  return opSection(
+    "History / inspect",
+    opRow(undo, redo),
+    opRow(canCheck, canResult),
+    opRow(overrides, flush),
+  );
 }
 
 const OPS_SECTIONS = [