@jarenjs/play

A JSON-engine playground — understand an engine before you compose it.

Pick an engine (JSONPath, JSON Pointer, JSON Patch, $query, JSLT, markdown, mermaid, a $contract document, …), feed it a source input and one or more datasets from a curated example library, and watch it run. Where @jarenjs/studio is for building an application out of many files, @jarenjs/play is for learning one engine standalone — a reference bench you experiment on first.

Two layers, the suite's convention:

• the engine (@jarenjs/play) — headless: an engine registry, a curated example library, and a pure runExample(engineId, source, data) → { ok, panels, timing, error }. Wraps the real shipped compilers; knows nothing of the DOM.
• the component (@jarenjs/play/component) — the playground UI, a createPlayComponent() factory (like @jarenjs/calc): a JSLT view (example rail, source editors, a dataset switcher, the run stage) the host composes.

Play is a student tool: it opens calm — one clean result per run — and drills deeper on demand. An engine's rich explainers (match cards, the compiled program, a geometry-free AST, a canonical round-trip) are deep result panels behind a quiet "Explain ▸" depth toggle: revealed beside the answer on desktop, as a full-pane swap with a ← back on a phone. And when a run fails, the error says where: the editor it is about is marked invalid and its label carries the compiler's own location — the rule of the stylesheet (at /rules/0/match), the token of the selector (at position 7), the line of the document (at line 2, column 5) — so the learner is pointed at the text to fix, not just told it is wrong (PLAY-FORMAT §2).

The model

An engine's inputs are heterogeneous — a selector needs one JSON document, a patch needs a target, markdown needs no data at all. Each engine is a descriptor (the panes it consumes + a pure run); each example presets those panes plus a list of datasets:

{ engine: 'path',
  source:   { selector: '$.store.book[*].title' },
  datasets: [ { label: 'store',   data: { data: '{ … }' } },
              { label: 'catalog', data: { data: '{ … }' } } ] }

The datasets list length is the whole story: 0 → the engine takes no data (markdown/mermaid); 1 → one dataset; N → a switcher that runs the same source over each shape. Adding an engine is a descriptor plus examples — the picker, panes and switcher all derive from the descriptor. See docs/PLAY-FORMAT.md for descriptors and results, and ARCHITECTURE.md for the state, action and run-loop contract an embedding host supplies. Query, JSLT, JTLT and XQuery expose an editable JSON externals pane.

Exports

Every subpath a consumer can import, derived from the manifest by npm run docs:derive (npm run docs:check fails when the two drift):

| Import | Kind | Declarations | |---|---|---| | @jarenjs/play | JavaScript | declared | | @jarenjs/play/component | JavaScript | declared | | @jarenjs/play/styles/play.css | asset | — | | @jarenjs/play/package.json | metadata | — |

Install

npm install @jarenjs/play

Zero third-party runtime dependencies — only other @jarenjs/* packages. Node ≥ 24, ESM.