Skip to content

Add an in-browser playground to the docs site - #69

Merged
k0d13 merged 3 commits into
mainfrom
kodie/playground
Jul 29, 2026
Merged

Add an in-browser playground to the docs site#69
k0d13 merged 3 commits into
mainfrom
kodie/playground

Conversation

@k0d13

@k0d13 k0d13 commented Jul 29, 2026

Copy link
Copy Markdown
Owner

Adds a playground at /playground where you can paste code and watch SayKit extract its messages and compile it, live.

How it works

The transformers are pure Babel with no Node dependencies, so the whole thing runs client-side with no server involved. Each version is loaded from esm.sh at runtime rather than bundled, which means the version list picks up new releases without rebuilding the site.

The version selector offers every stable release from 0.5.0 up, plus whatever the beta dist-tag currently points at. Betas are published as 0.0.0-beta-<timestamp>, which sorts meaninglessly, so only the current one is surfaced rather than the whole list.

@saykit/transform-jsx also handles the plain-JS tagged-template and call forms by delegating to @saykit/transform-js, so one package covers both and there's no transformer picker to get wrong.

Notes

  • esm.sh can't resolve the workspace caret ranges. ^0.0.0-beta-<timestamp> gives a 200 on the entry but 404s on its imports. The siblings are pinned via ?deps= to the exact version being loaded, which fixes beta and is a no-op for stable releases.
  • Message ids fall back to the hash, loaded from @saykit/config at the same version as the transformer, so a displayed id always matches what that release would write into the catalogue. Generated ids render muted to distinguish them from explicit ones.
  • Share links put code and version in the URL fragment, not the query string, so what you're experimenting with is never sent to the server. A hashchange listener handles opening a share link while already on the page, which is a same-document navigation that never remounts.
  • Messages render as a list, not a table. In a half-width pane five columns leave the message fighting its own metadata for space, and every id, context or comment added makes it narrower.
  • Also adds a Documentation link to the nav, so docs are one click from anywhere.

Verification

Type-check and build pass; /playground prerenders as static with a 1h revalidate, and the build doesn't try to resolve the esm.sh URL.

Verified in a browser: extraction and transformation on load, live updates while typing, syntax errors surfacing without reflowing the page or blanking the last good result, format, share round-trip on a cold load, light and dark, and no page-level horizontal overflow with a very long message.

Version switching is wired to the transformer rather than decorative. Same input, say\Your total is ${{ cartTotal: getTotal() }} today``:

version message
0.5.0 Your total is {0} today
beta Your total is {cartTotal} today

Not verified: a true phone-width render, and behaviour when esm.sh is unreachable.

Summary by CodeRabbit

  • New Features
    • Added an interactive Playground for writing, formatting, running, and sharing SayKit code.
    • Added version selection, message extraction, transformed output, and copy/share actions.
    • Added Documentation and Playground links to the site navigation.
    • Added light and dark theme syntax highlighting for the code editor.
  • Enhancements
    • Playground version options include beta and supported stable releases, with a fallback when unavailable.

@changeset-bot

changeset-bot Bot commented Jul 29, 2026

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: 0cc765c

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@vercel

vercel Bot commented Jul 29, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
saykit Ready Ready Preview, Comment Jul 29, 2026 1:07pm

@github-actions github-actions Bot added dependencies Updates or changes related to project dependencies website Updates to the documentation website labels Jul 29, 2026
@coderabbitai

coderabbitai Bot commented Jul 29, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

Warning

Review limit reached

@k0d13, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 44 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: a7e4aa99-f458-48ad-8bc4-2e4da4684b0f

📥 Commits

Reviewing files that changed from the base of the PR and between 29eb08d and 0cc765c.

📒 Files selected for processing (2)
  • website/app/(home)/playground/versions.ts
  • website/components/playground.tsx

Walkthrough

Changes

Playground feature

Layer / File(s) Summary
Page entry and version loading
website/app/(home)/playground/page.tsx, website/app/(home)/playground/versions.ts, website/lib/layout.shared.tsx
Adds the playground route, default SayKit example, npm-backed version selection, and Documentation/Playground navigation links.
Code editor foundation
website/components/code-editor.tsx, website/app/global.css, website/package.json
Adds a themed CodeMirror editor, syntax colour variables, and editor, highlighting, and formatting dependencies.
Runtime transformation flow
website/components/playground.tsx
Loads version-specific browser runtimes, extracts and transforms messages, formats input, highlights output, handles shared URL state, and manages debounced asynchronous runs.
Playground controls and output
website/components/playground.tsx
Renders version selection, editor and output panes, copy/share actions, message metadata, errors, and highlighted transformed code.

Estimated code review effort: 4 (Complex) | ~45 minutes

Suggested labels: package: config, package: transform-js, package: transform-jsx

Poem

A rabbit hops through code so bright,
With versions queued in tidy flight.
Messages bloom and outputs glow,
Shareable links are set to go.
“Type, transform!” the bunny sings,
While syntax sprouts on editor wings.

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly matches the main change: adding an in-browser playground to the docs site.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch kodie/playground

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@k0d13

k0d13 commented Jul 29, 2026

Copy link
Copy Markdown
Owner Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Jul 29, 2026

Copy link
Copy Markdown
Contributor
✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 5

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@website/app/`(home)/playground/versions.ts:
- Line 9: Update the FALLBACK VersionOption label to remove the inaccurate
“latest” designation, using a neutral fallback label or no suffix while
preserving the existing fallback version value.
- Around line 51-56: Update the beta option construction in the versions-loading
flow to include tags.beta only when it exists in registry.versions and is not
already represented in stable. Preserve the existing beta label, stable options,
and FALLBACK behavior, while ensuring stale or duplicate beta values are
omitted.
- Around line 30-38: Add an API-supported abort timeout to the fetch call in the
registry-loading flow, passing the signal through the request options while
preserving the existing revalidation setting. Ensure timeout failures are
handled by the current catch path so the function returns FALLBACK.

In `@website/components/playground.tsx`:
- Around line 386-402: Handle rejected navigator.clipboard.writeText promises in
both CopyAction and ShareButton by adding failure handling that prevents
unhandled rejections and provides appropriate user feedback. Preserve the
existing success behavior, including updating copied state only after a
successful write, and anchor the changes to the onClick handlers in those
components.
- Around line 86-106: Update getHighlighter so a rejected highlighter
initialization promise clears the shared highlighter cache, allowing subsequent
calls to retry after transient Shiki or CDN failures. Preserve the existing
successful caching behavior and highlighting implementation, mirroring the
rejection-eviction approach used by loadRuntime.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: db913e2d-613c-41ef-9929-e1d8a4faea2d

📥 Commits

Reviewing files that changed from the base of the PR and between 93a52ce and 29eb08d.

⛔ Files ignored due to path filters (1)
  • pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml
📒 Files selected for processing (7)
  • website/app/(home)/playground/page.tsx
  • website/app/(home)/playground/versions.ts
  • website/app/global.css
  • website/components/code-editor.tsx
  • website/components/playground.tsx
  • website/lib/layout.shared.tsx
  • website/package.json

Comment thread website/app/(home)/playground/versions.ts Outdated
Comment thread website/app/(home)/playground/versions.ts
Comment thread website/app/(home)/playground/versions.ts
Comment thread website/components/playground.tsx
Comment thread website/components/playground.tsx Outdated
@k0d13
k0d13 merged commit 15f3a12 into main Jul 29, 2026
30 checks passed
@k0d13
k0d13 deleted the kodie/playground branch July 29, 2026 13:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

dependencies Updates or changes related to project dependencies website Updates to the documentation website

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant