@ox-content/code-play 3.0.0-alpha.1 → 3.0.0-alpha.10

package/README.md

@@ -4,6 +4,7 @@ Opt-in Code Play plugin for Ox Content. It runs documentation samples on demand
 and exposes a headless API plus Headless / preset UI.
 
 Nothing runs until you install this package **and** enable specific languages.
+Pages without matching `play` blocks do not load `ox-code-play.js`.
 
 ## Install
 
@@ -33,20 +34,27 @@ export default {
 ## Authoring
 
 ````md
-```ts play
+```ts play typecheck play-title="Strict TypeScript" play-strict=false play-target=ESNext
 const n: number = 1;
 console.log(n);
 ```
 
-```rust play typecheck
+```rust play typecheck play-title="Release-mode Rust" play-mode=release
 fn main() {
     println!("ok");
 }
 ```
 ````
 
+Use `play-title`, `play-compact` / `play-headless`, `play-timeout=2500`,
+`play-viewers=stdio,stderr,-timing`, and `play-<config-key>=...` for one
+sample. The MDX-style `<CodePlay>` tag accepts `title`, `ui`, `timeout`,
+`viewers`, and `config-*` attributes.
+
 ```html
-<CodePlay lang="python"> print("hello") </CodePlay>
+<CodePlay lang="ts" title="Loose TS" typecheck ui="compact" config-strict="false">
+  const n = 1;
+</CodePlay>
 ```
 
 ## Headless API
@@ -66,15 +74,20 @@ run.provenance;
 run.timing;
 ```
 
+`run.status` is `ok`, `error`, `offline`, `timeout`, `cancelled`, or
+`unsupported`. Custom UIs can use the exported `RunActionState` helpers to
+model idle, running, result, error, and offline states.
+
 ## Security
 
 `play` fences are trusted site content. Do not mark unreviewed or
 visitor-supplied snippets as `play`.
 
 - No sample is executed during Markdown transform or SSG.
-- JavaScript and TypeScript run in `node:vm` on Node, or in
-  `<iframe sandbox="allow-scripts">` in the browser (no `allow-same-origin`).
-  They are never run with page-origin `Function`.
+- JavaScript and TypeScript run in `node:vm` on Node, or in a Web Worker in the
+  browser. Browsers without Worker support fall back to
+  `<iframe sandbox="allow-scripts">` with no `allow-same-origin`. Snippets are
+  never run with page-origin `Function`.
 - Published widgets hide **Typecheck** unless `endpoints.typecheck` is set.
   **Cancel** appears while a run is in flight.
 - Framework previews use the same iframe flags and load runtimes from esm.sh.