Code Play Roadmap#

Copy as MarkdownView Markdown

Tracking issue: #648.

Code Play is an opt-in plugin, @ox-content/code-play. Installing @ox-content/vite-plugin must not pull it in, and installing Code Play must not enable any language until the site lists that language.

The work is split into small pull requests so each one can land with its own tests and changelog entry. A later PR may depend on an earlier one, never the reverse.

Architecture Principles#

1. Two opt-in layers. Install the package, then enable languages. Disabled languages stay ordinary highlighted fences.
2. Headless first. createCodePlay() / CodePlaySession are the source of truth. Presets and viewers render that data; they do not own execution.
3. No transform-time execution. Markdown transform and SSG never run sample code. Readers trigger execute / type-check on demand.
4. Sandboxes stay sandboxed. JavaScript and TypeScript run in node:vm or a browser iframe. Native languages use official playgrounds or a user-configured HTTP executor. Code Play does not spawn sh, python, or rustc on the docs host unless a later local-runtime PR says so.
5. Observability is API data. stdio, dedicated stdout / stderr strings, config, provenance, and timing are returned on every RunResult, not only painted in the default UI.

Language Matrix#

PR Sequence#

1. feat(code-play): plugin scaffold, headless API, viewers#

Shipped in #649. Package, catalog, headless client, default/compact/headless UI, config / stdio / provenance / timing viewers, Vite plugin, and tests with injected transports (no live network in CI).

1b. feat(code-play): dedicated stderr viewer#

Shipped in #662. First-class RunResult.stdout / RunResult.stderr, a dedicated stderr viewer, and compact preset coverage for stderr.

2. feat(code-play): Vite SSG hydration and docs dogfood#

Docs example page, package guide, and examples/code-play shipped in #697. Standalone ox-code-play.js + bootCodePlay() shipped in #703. This PR adds a Playwright check that written SSG HTML hydrates and Run prints stdio, session.cancel() plus a toolbar Cancel control, and hides TypeScript Typecheck on published pages unless endpoints.typecheck is set.

3. feat(code-play): official playground proxies#

Shipped in #663. Dev proxies stay POST-only, cap bodies, refuse non-http(s) destinations, and hide upstream fetch details. Production pages must set endpoints (the proxy is not in SSG output).

4. feat(code-play): framework preview compilers#

Optional peer compilers for Vue SFC, React JSX, Svelte, and Solid so previews compile locally instead of shipping raw source into an import-map iframe.

5. feat(code-play): optional in-browser runtimes#

Opt-in loaders such as Pyodide or Scheme interpreters. Still off by default; each runtime is its own language enable flag.

6. docs(code-play): security and privacy notes#

This PR. Trusted play fences, iframe sandbox="allow-scripts" for JS/TS execute and framework previews, third-party playgrounds, endpoint trust, production typecheck / CORS, and the "no local shell" guarantee in SECURITY.md and the package guide.

7. feat(code-play): project-level sandbox provider adapters#

Tracked in #873. Project examples add provider metadata adapters, multi-file payloads, safe Markdown-relative file collection, and fallback links while leaving ordinary single-file snippets on the existing local execution paths. StackBlitz, CodeSandbox, WebContainer, and external links are represented as payload metadata first; provider runtime scripts stay out of pages unless a later adapter runtime explicitly opts in.

Out of Scope#

• Making Code Play a built-in @ox-content/vite-plugin option.
• Replacing WebContainer or StackBlitz embeds.
• Vendoring compilers or a hosted execute service.
• Running samples during transformMarkdown or buildSsg.

Tracking#

Progress is tracked through the conventional commit log and #648. This document is updated in the same PR when an item lands.