Skip to content

feat: action runner + PrismScene public embed API#3

Merged
ClodoCapeo merged 1 commit into
mainfrom
feature/action-runner-v1
May 12, 2026
Merged

feat: action runner + PrismScene public embed API#3
ClodoCapeo merged 1 commit into
mainfrom
feature/action-runner-v1

Conversation

@ClodoCapeo
Copy link
Copy Markdown
Contributor

Summary

Closes the broadcast loop for Prism's animation redesign (P6 blocker)
and makes Solar embeddable in arbitrary web pages without Pulsar, CEF,
or Electron. Three consumers, one API : Prism preview (webview), Pulsar
broadcast (CEF), web embed (host page).

Changes

  • Patch.action descriptor on the wire protocol — six built-in
    kinds (count-up, curve-path, text-reveal, stagger-group,
    reorder, mask-reveal). Patches without action flow through
    the existing transitions.ts mapper untouched — fully backward
    compatible.
  • animate/action-runner.ts dispatcher + per-kind sub-runners
    in animate/runners/. Unknown kinds throw UnknownActionKindError.
    Hosts can register custom runners via registerActionRunner().
  • animate/flip.ts — single source of truth for FLIP. Solar's
    reorder runner consumes it directly ; Prism's preview will
    import it via @zablab/solar/animate/flip at P5.
  • animate/easing-resolver.tsEasingRef → CSS easing +
    t → eased t for runners that compute values in JS.
  • PrismScene public classmount, unmount,
    playAnimation, stopAnimation, on/off, connectToOrion,
    disconnectFromOrion, setScene. Concurrency-safe (rejects
    double plays of the same asset with code: "ALREADY_PLAYING")
    and abortable.
  • DOM binder — one-way bindings via data-anim-path /
    data-anim-attr. ${param.*} interpolation through patch
    path/value and action params.
  • Packaging : ESM main + ESM alias + UMD bundle +
    animate/flip subpath + public .d.ts. npm publish --dry-run
    green. Runtime gzipped budget : UMD 18.78 KiB ; ESM ~17.8 KiB.
    Well under the 80 KB criterion.
  • Docs : docs/embed-on-website.md (client deliverable),
    docs/action-descriptors.md (protocol reference).
  • Examples : examples/embed-vanilla/ (<script> tag) +
    examples/embed-react/ (forwardRef wrapper).
  • CHANGELOG.md narrative entry for 0.2.0.
  • react, react-dom, framer-motion moved to peerDependencies ;
    hosts supply their own copies.

Acceptance criteria

# Criterion Status
1 npm run lint && typecheck && test && build green
2 Backward-compatible Patch handling ✅ (no transitions.ts change)
3 Action runner — count-up (0 → 1891 in 800ms) tests/unit/runners-count-up.test.ts
4 Action runner — reorder FLIP tests/unit/runners-reorder-flip.test.ts
5 Action runner — text-reveal stagger tests/unit/runners-text-reveal.test.ts
6 Public API — vanilla embed examples/embed-vanilla/
7 Public API — React embed examples/embed-react/
8 Packaging — UMD + ESM + flip subpath + types, ≤ 80KB gzipped ✅ runtime 18.78 KiB
9 End-to-end visual parity with Prism ⏳ Depends on Prism P6 — visual diff to run jointly

Test plan

  • npm run lint && npm run typecheck clean
  • npm test — 68 vitest tests green (11 suites)
  • npm run build — ESM + UMD + flip subpath + types emitted
  • npm publish --dry-run — tarball valid, all required artefacts present
  • Manual : open examples/embed-vanilla/index.html in a browser, click the button, verify count-up animation
  • Manual : drop examples/embed-react/PrismSceneEmbed.tsx into a React app, verify play prop triggers animation
  • Joint E2E with Prism P6 once that chantier lands

🤖 Generated with Claude Code

Extends Solar so a single bundle now serves three identical consumers
(Pulsar CEF, Prism webview, arbitrary web embed) with a stable JS API,
and consumes Prism's Action descriptors locally rather than receiving
dense patches frame-by-frame over the wire.

Why now : without this, Prism's animation redesign (P6) can't close
the broadcast loop — animations would compose in preview but never
land in Pulsar or in a web embed.

Highlights :
- Patch.action descriptor (count-up, curve-path, text-reveal,
  stagger-group, reorder, mask-reveal) — additive, fully backward
  compatible with patches that have no action.
- animate/flip.ts as single source of truth for FLIP, shared with
  Prism preview via @zablab/solar/animate/flip.
- PrismScene class : mount/unmount/play/stop/on/off/connectToOrion/
  setScene. Concurrency-safe (ALREADY_PLAYING) and abortable.
- Packaging : ESM main + ESM alias + UMD + animate/flip subpath +
  public .d.ts. Tarball under the 80KB minified+gzipped budget.
- Docs : embed-on-website.md (client deliverable) + action-
  descriptors.md (protocol reference).
- Examples : embed-vanilla (<script>) + embed-react (forwardRef).
- 68 vitest tests green ; lint + typecheck clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@ClodoCapeo ClodoCapeo merged commit 7127025 into main May 12, 2026
4 of 5 checks passed
@ClodoCapeo ClodoCapeo deleted the feature/action-runner-v1 branch May 12, 2026 00:46
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