[Tooling] "Open in Playground" links from doc snippets — url-encoded short, raw-URL fetch long — with tag/commit version pinning #382

New issue

Closed

opened 2026-07-16 00:28:04 +00:00 by john · 0 comments

john commented

2026-07-16 00:28:04 +00:00

Owner

Goal

Every doc snippet gets an "Open in Playground" action that loads its source into the WASM REPL playground. Snippets are copy-pasteable with no sys.exit(), so they run in the REPL as-is — ideal payloads.

Requirements

Two payload transports, chosen by size

Short snippets → URL-encoded. base64 the source into the playground URL fragment (#code=…); the playground shell decodes on load and populates/runs the REPL. Fragment stays client-side (never hits the server) and comfortably carries a few KB.
Long snippets → raw-URL fetch. Extend the playground to fetch a GitHub raw file URL (engine repo) for the snippet by ref, instead of inlining. Avoids URL-length limits on the big procgen samples.

Version-pinned source references (applies to the raw-URL fetch AND existing doc source links)

Old / tagged doc versions → point at the tagged file (raw @ tag, e.g. 0.2.8).
Cutting-edge docs → point at the engine repo commit hash.
This extends the distinction the docs pipeline already draws between RELEASE_REF (the tag being cut) and the working commit — build_library.py already pins source links per ref; this generalizes that ref choice to the playground raw-fetch and the "Open in Playground" link generation.

Playground shell work

A fragment/URL-param reader that decodes-or-fetches, then loads the code into the REPL.
Reuse reset_python_environment() so a loaded snippet starts from a clean scene.
Deflate+base64 as a fallback only if any inline payload is genuinely too large for a fragment.

Sketch of the pieces

Playground shell (shell.html / src/scripts_playground/, EmscriptenStubs.cpp interop) URL/fragment reader + raw-URL fetch path.
Site build_library.py link generation: per-snippet "Open in Playground" URL, ref-pinned (tag vs commit) to match the doc build.
Ref-selection plumbing shared with the source-link pinning already in the pipeline.

Sibling issue #381 (deterministic snippet screenshots) — same "make the gated snippets pay off on the site" thread.
#239 (automated WASM/headless-browser testing) — adjacent playground infra, distinct goal.
Docs-as-tests pipeline; engine is on GitHub (raw URLs), doc site on Forgejo.

## Goal Every doc snippet gets an **"Open in Playground"** action that loads its source into the WASM REPL playground. Snippets are copy-pasteable with no `sys.exit()`, so they run in the REPL as-is — ideal payloads. ## Requirements ### Two payload transports, chosen by size - **Short snippets → URL-encoded.** base64 the source into the playground URL **fragment** (`#code=…`); the playground shell decodes on load and populates/runs the REPL. Fragment stays client-side (never hits the server) and comfortably carries a few KB. - **Long snippets → raw-URL fetch.** Extend the playground to fetch a **GitHub raw file URL** (engine repo) for the snippet by ref, instead of inlining. Avoids URL-length limits on the big procgen samples. ### Version-pinned source references (applies to the raw-URL fetch AND existing doc source links) - **Old / tagged doc versions → point at the tagged file** (raw @ tag, e.g. `0.2.8`). - **Cutting-edge docs → point at the engine repo commit hash.** - This extends the distinction the docs pipeline already draws between `RELEASE_REF` (the tag being cut) and the working commit — `build_library.py` already pins source links per ref; this generalizes that ref choice to the playground raw-fetch and the "Open in Playground" link generation. ### Playground shell work - A fragment/URL-param reader that decodes-or-fetches, then loads the code into the REPL. - Reuse `reset_python_environment()` so a loaded snippet starts from a clean scene. - Deflate+base64 as a fallback only if any inline payload is genuinely too large for a fragment. ## Sketch of the pieces - Playground shell (`shell.html` / `src/scripts_playground/`, `EmscriptenStubs.cpp` interop) URL/fragment reader + raw-URL fetch path. - Site `build_library.py` link generation: per-snippet "Open in Playground" URL, ref-pinned (tag vs commit) to match the doc build. - Ref-selection plumbing shared with the source-link pinning already in the pipeline. ## Related - Sibling issue #381 (deterministic snippet screenshots) — same "make the gated snippets pay off on the site" thread. - #239 (automated WASM/headless-browser testing) — adjacent playground infra, distinct goal. - Docs-as-tests pipeline; engine is on GitHub (raw URLs), doc site on Forgejo.