@ox-content/code-play 3.0.0-alpha.9 → 3.0.0-beta.0

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,21 +34,41 @@ 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>
+```
+
+Project-level examples stay opt-in per sample:
+
+````md
+```ts play play-project=stackblitz play-file=src/main.ts play-entry=src/main.ts play-files=package.json,src/App.tsx play-project-url=https://stackblitz.com/edit/example
+console.log("project");
 ```
+````
+
+`play-file` names the current fence inside the project, `play-files` lists
+extra files relative to the Markdown source file, and `play-project-url`
+provides the external fallback link. Providers are metadata adapters; no
+StackBlitz, CodeSandbox, or WebContainer script is loaded by Code Play.
 
 ## Headless API
 
@@ -66,6 +87,10 @@ 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
@@ -83,6 +108,9 @@ visitor-supplied snippets as `play`.
   The Vite `/__ox-code-play/*` proxy is **dev-only**.
 - Other languages need a Piston-compatible `endpoint` you trust.
 - `sh` never spawns a local shell.
+- Project sandboxes include trusted source in the static payload. `play-files`
+  are read only from relative paths inside the configured Markdown source root,
+  with symlink real paths checked before embedding.
 
 ## Example