@jarenjs/play 0.34.0 → 0.43.1

package/README.md

@@ -3,8 +3,8 @@
 **A JSON-engine playground — understand an engine before you compose it.**
 
 Pick an engine (JSONPath, JSON Pointer, JSON Patch, `$query`, JSLT,
-markdown, mermaid, …), feed it a source input and one or more datasets from
-a curated example library, and watch it run. Where `@jarenjs/studio` is for
+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.
 
@@ -23,7 +23,13 @@ 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.
+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](./docs/PLAY-FORMAT.md#2-the-result)).
 
 ## The model
 

package/dist/types/component/index.d.ts

@@ -72,7 +72,7 @@ export declare function createPlayComponent(options?: {
     engines: Readonly<Record<string, import("../index.js").EngineDescriptor>>;
     examples: readonly import("../index.js").PlayExample[];
     engineIds: typeof engineIds;
-    runExample: (engineId: any, source: any, data: any, perCall?: {}) => import("../index.js").PlayResult;
+    runExample: (engineId: any, source: any, data: any, perCall?: {}) => import("../index.js").PlayResult | Promise<import("../index.js").PlayResult>;
     operators: {
         toOptions: () => any;
     } | undefined;

package/dist/types/index.d.ts

@@ -77,17 +77,58 @@ export type Panel = {
         note?: string;
     }>;
 };
+export type PlayError = {
+    /**
+     * - the compiler's message, verbatim (a coded
+     * error composes `code: reason at path` itself)
+     */
+    message: string;
+    /**
+     * - the stable diagnosis code, when there is one
+     */
+    code?: string;
+    /**
+     * - the pane KEY (source or data) the error is
+     * about: the source pane for a compile or run failure, the data pane
+     * whose JSON did not parse
+     */
+    pane?: string;
+    /**
+     * - JSON Pointer into that pane's DOCUMENT (a
+     * coded error's `docPath`: the failing patch operation, the query
+     * construct, the stylesheet rule)
+     */
+    path?: string;
+    /**
+     * - JSON Pointer into the DATA the document
+     * was applied to, when a runtime error blames both (a patch operation
+     * AND the target location it failed at)
+     */
+    dataPath?: string;
+    /**
+     * - 0-based offset into that pane's TEXT
+     * (the syntax family: a JSONPath selector, a JSON Pointer, an XQuery)
+     */
+    position?: number;
+    /**
+     * - 1-based line (the JOSL / CSV family)
+     */
+    line?: number;
+    /**
+     * - 1-based column (with `line`)
+     */
+    column?: number;
+};
 export type PlayResult = {
     ok: boolean;
     timing: {
         compileMs: number;
         runMs: number;
     } | null;
-    error: {
-        message: string;
-        code?: string;
-        path?: string;
-    } | null;
+    /**
+     * - null on an ok run
+     */
+    error: PlayError | null;
     /**
      * - the result screens (`[]` on error); a single
      * `code` panel for most engines, several for the richer ones
@@ -113,7 +154,13 @@ export type EngineDescriptor = {
      * - live mode selects (may be absent)
      */
     optionPanes?: OptionPane[];
-    run: (source: Record<string, string>, data: Record<string, string>, options?: RunOptions) => PlayResult;
+    /**
+     *   most engines answer synchronously; an engine whose run resolves real
+     *   promises (the contract engine's dispatch panel) answers a thenable
+     *   Result, which `runExample` passes through with the same never-throw
+     *   contract (a rejection settles into an error Result)
+     */
+    run: (source: Record<string, string>, data: Record<string, string>, options?: RunOptions) => PlayResult | Promise<PlayResult>;
 };
 export type RunOptions = {
     /**
@@ -206,11 +253,37 @@ export type PlayExample = {
  * @property {Array<{ title: string, value: string, note?: string }>} [items]
  *   `cards`: a row of stat cards (matches, compile/run timings, …)
  */
+/**
+ * The error half of a Result: what the compiler said, plus WHERE — in the
+ * format's own fields, so the view can point at the pane and the location
+ * rather than only quoting the message. Every location field is present
+ * exactly when the compiler stated it (a field is never fabricated), and
+ * `pane` names the editor the location points into; a location into a
+ * document the learner never typed (XQuery's generated query document) has
+ * no pane. See PLAY-FORMAT §2.
+ * @typedef {Object} PlayError
+ * @property {string} message - the compiler's message, verbatim (a coded
+ *   error composes `code: reason at path` itself)
+ * @property {string} [code] - the stable diagnosis code, when there is one
+ * @property {string} [pane] - the pane KEY (source or data) the error is
+ *   about: the source pane for a compile or run failure, the data pane
+ *   whose JSON did not parse
+ * @property {string} [path] - JSON Pointer into that pane's DOCUMENT (a
+ *   coded error's `docPath`: the failing patch operation, the query
+ *   construct, the stylesheet rule)
+ * @property {string} [dataPath] - JSON Pointer into the DATA the document
+ *   was applied to, when a runtime error blames both (a patch operation
+ *   AND the target location it failed at)
+ * @property {number} [position] - 0-based offset into that pane's TEXT
+ *   (the syntax family: a JSONPath selector, a JSON Pointer, an XQuery)
+ * @property {number} [line] - 1-based line (the JOSL / CSV family)
+ * @property {number} [column] - 1-based column (with `line`)
+ */
 /**
  * @typedef {Object} PlayResult
  * @property {boolean} ok
  * @property {{ compileMs: number, runMs: number } | null} timing
- * @property {{ message: string, code?: string, path?: string } | null} error
+ * @property {PlayError | null} error - null on an ok run
  * @property {Panel[]} panels - the result screens (`[]` on error); a single
  *   `code` panel for most engines, several for the richer ones
  */
@@ -222,7 +295,11 @@ export type PlayExample = {
  * @property {EnginePane[]} sourcePanes - the engine INPUT pane(s)
  * @property {EnginePane[]} dataPanes - the JSON it runs against (may be [])
  * @property {OptionPane[]} [optionPanes] - live mode selects (may be absent)
- * @property {(source: Record<string, string>, data: Record<string, string>, options?: RunOptions) => PlayResult} run
+ * @property {(source: Record<string, string>, data: Record<string, string>, options?: RunOptions) => PlayResult | Promise<PlayResult>} run
+ *   most engines answer synchronously; an engine whose run resolves real
+ *   promises (the contract engine's dispatch panel) answers a thenable
+ *   Result, which `runExample` passes through with the same never-throw
+ *   contract (a rejection settles into an error Result)
  */
 /**
  * @typedef {Object} RunOptions
@@ -261,12 +338,15 @@ export declare function engineIds(): string[];
 export declare const EXAMPLES: readonly PlayExample[];
 /**
  * Run one engine over a source + data. An unknown engine (or a throwing
- * runner) yields an error Result — this never throws.
+ * runner) yields an error Result — this never throws. A synchronous
+ * engine answers a Result; an async engine (the contract dispatch)
+ * answers a Promise of one that never rejects — a host that must know
+ * which awaits `Promise.resolve(runExample(…))`.
  * @param {string} engineId
  * @param {Record<string, string>} source
  * @param {Record<string, string>} data
  * @param {RunOptions} [options] - operators (query/jslt), the option-pane
  *   config, and host renderers (markdown/mermaid/charts)
- * @returns {PlayResult}
+ * @returns {PlayResult | Promise<PlayResult>}
  */
-export declare function runExample(engineId: string, source: Record<string, string>, data: Record<string, string>, options?: RunOptions): PlayResult;
+export declare function runExample(engineId: string, source: Record<string, string>, data: Record<string, string>, options?: RunOptions): PlayResult | Promise<PlayResult>;

package/docs/PLAY-FORMAT.md

@@ -13,7 +13,7 @@ EngineDescriptor = {
   lead?:       string,        // one line describing the engine
   sourcePanes: EnginePane[],  // the engine INPUT (usually one)
   dataPanes:   EnginePane[],  // the JSON it runs against (may be empty)
-  run:         (source, data) => PlayResult,
+  run:         (source, data) => PlayResult | Promise<PlayResult>,
 }
 EnginePane = { key: string, label: string, control?: 'code' | 'text' }
 ```
@@ -27,6 +27,13 @@ EnginePane = { key: string, label: string, control?: 'code' | 'text' }
 - `run(source, data)` is PURE and NEVER throws: it wraps the real shipped
   compiler and returns a `PlayResult`. `source` / `data` are maps keyed
   by the pane `key`s, holding the raw text.
+- Most engines answer synchronously. An engine whose run resolves real
+  promises (the contract engine's dispatch panel invokes a local client)
+  answers a **thenable** `PlayResult`; `runExample` passes it through
+  under the same never-throw contract — a rejection settles into an
+  error Result, so `await Promise.resolve(runExample(…))` is total for
+  every engine. A host that renders live must drop a settled result an
+  even newer run superseded (the website keys runs by a sequence).
 
 ## §2 The result
 
@@ -38,10 +45,25 @@ PlayResult = {
   // and the stage omits that clause rather than printing `0 ms` — which
   // read as "it was free". Only measured phases are ever shown.
   timing: { compileMs: number | null, runMs: number | null } | null,
-  error:  { message: string, code?, path? } | null,
+  error:  PlayError | null,
   panels: Panel[],                                 // the result SCREENS ([] on error)
 }
 
+PlayError = {
+  message:   string,     // what the compiler said, verbatim
+  code?:     string,     // its stable diagnosis code, when it has one
+  // WHERE — the location half, in the format's own fields. A field is
+  // present exactly when the compiler stated it; nothing is fabricated.
+  pane?:     string,     // the pane KEY the error is about: the source pane
+                         // for a compile or run failure, the data pane
+                         // whose JSON did not parse
+  path?:     string,     // JSON Pointer into that pane's DOCUMENT
+  dataPath?: string,     // JSON Pointer into the DATA the document ran over
+  position?: number,     // 0-based offset into that pane's TEXT
+  line?:     number,     // 1-based line …
+  column?:   number,     // … and column
+}
+
 Panel = {
   id:     string,                                  // unique in the result (the tab key)
   label?: string,                                  // the tab label (defaults to id)
@@ -56,6 +78,36 @@ Panel = {
 }
 ```
 
+An error says **where**, because for a learner the location is the lesson:
+which token of the selector, which operation of the patch, which rule of
+the stylesheet. The compilers already carry it, in three shapes, and the
+error copies whichever its compiler stated: the **coded family** (patch,
+`$query`, JSLT, JTLT — `@jarenjs/core`'s `CodedError`) states `path`, a
+JSON Pointer into the document being compiled or run (`/rules/0/match`,
+`/$idiv`, `/0/path`), and a patch *runtime* error adds `dataPath`, the
+target location its operation failed at — two facts, both kept; the
+**syntax family** (JSONPath, JSON Pointer, XQuery) states `position`, a
+0-based offset into the source text; the **line/column family** (JOSL,
+CSV) states 1-based `line` and `column`. `pane` names the editor the
+location points into, and it is the whole location for a pane whose JSON
+does not parse: the host's `JSON.parse` states its offset only inside
+engine-specific message text, never as a field, so the pane is claimed and
+nothing finer. Two honest gaps: a missing host seam (`PLAY_NO_RENDERER`,
+`PLAY_NO_VALIDATOR`) is nobody's pane, and XQuery compiles a *generated*
+query document, so a location after its parse phase is a pointer into a
+document the learner never typed — stated, with no pane. `message` stays
+verbatim (a coded error composes `code: reason at path` itself), so a
+host with no structured reader still gets everything.
+
+The component lands it in two places: the editor the error is about is
+marked `aria-invalid` (the state the renderer owns; the ring is styled off
+it) and its label carries the phrase — `at /rules/0/match`, `at position
+7`, `at line 2, column 5` — while the stage's error line shows the code
+chip, the message with its own code prefix dropped rather than read twice,
+and the pane's label. A data pane a runtime error merely failed *at* is
+not marked invalid (the op was wrong, not the target) but shows the
+`dataPath` phrase, because that is where the reader looks next.
+
 Every ok run yields **at least one** panel — most engines a single `code`
 panel. The `simple` panels are the calm default: the component shows one
 inline, or — for more than one — a tab strip above the active panel body.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/play",
   "private": false,
-  "version": "0.34.0",
+  "version": "0.43.1",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",
@@ -56,9 +56,10 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.34.0",
-    "@jarenjs/josl": "^0.34.0",
-    "@jarenjs/json": "^0.34.0",
-    "@jarenjs/validate": "^0.34.0"
+    "@jarenjs/contract": "^0.43.1",
+    "@jarenjs/core": "^0.43.1",
+    "@jarenjs/josl": "^0.43.1",
+    "@jarenjs/json": "^0.43.1",
+    "@jarenjs/validate": "^0.43.1"
   }
 }

package/src/component/view.js

@@ -172,7 +172,15 @@ const shell = {
                   ], ''] },
               ], ''] },
           ],
-          ['p', { class: 'error-line' }, ['strong', {}, '$.result.error.code'], ' ', '$.result.error.message']] },
+          // the error line: the code chip (only when there is one), the message
+          // (its own code prefix dropped), and the editor the error is about —
+          // the pane itself is flagged and carries the location, see
+          // sourcePane / dataPane
+          ['p', { class: 'error-line' },
+            { $if: ['$.result.error.code', [['strong', {}, '$.result.error.code'], ' '], ''] },
+            '$.result.error.text',
+            { $if: ['$.result.error.paneLabel',
+              ['span', { class: 'jplay-error-pane' }, ' — ', '$.result.error.paneLabel'], ''] }]] },
         ['p', { class: 'muted jplay-hint' }, 'Pick an example, or edit the source or data — it runs live.']] },
     ],
   ],
@@ -197,15 +205,24 @@ const railExample = {
   }, '$.label'],
 };
 
+/** A pane label: the name, plus the last error's location in this pane
+ * (`at /rules/3`, `at position 7`, `at line 2, column 5`) when it has one. */
+const paneLabel = ['span', { class: 'jplay-pane-label muted' }, '$.label',
+  { $if: ['$.where', ['span', { class: 'jplay-pane-where' }, ' · ', '$.where'], ''] }];
+
+/** The editor the last error is about says so — `aria-invalid` is the
+ * state the renderer owns (the ring is styled off it), absent otherwise. */
+const invalid = { $if: ['$.invalid', 'true'] };
+
 /** One source editor (a `text` control renders an input, else a textarea). */
 const sourcePane = {
   match: `${PLAY_BASE}.sourcePanes[*]`, mode: PLAY_MODE,
   body: ['label', { class: 'jplay-pane' },
-    ['span', { class: 'jplay-pane-label muted' }, '$.label'],
+    paneLabel,
     { $if: [{ $eq: ['$.control', 'text'] },
-      ['input', { type: 'text', class: 'editor line', spellcheck: 'false', value: '$.value',
+      ['input', { type: 'text', class: 'editor line', spellcheck: 'false', value: '$.value', 'aria-invalid': invalid,
         on: { input: { action: 'play/source', with: { key: '$.key' } } } }],
-      ['textarea', { class: 'editor', rows: 6, spellcheck: 'false', value: '$.value',
+      ['textarea', { class: 'editor', rows: 6, spellcheck: 'false', value: '$.value', 'aria-invalid': invalid,
         on: { input: { action: 'play/source', with: { key: '$.key' } } } }]] },
   ],
 };
@@ -214,8 +231,8 @@ const sourcePane = {
 const dataPane = {
   match: `${PLAY_BASE}.dataPanes[*]`, mode: PLAY_MODE,
   body: ['label', { class: 'jplay-pane' },
-    ['span', { class: 'jplay-pane-label muted' }, '$.label'],
-    ['textarea', { class: 'editor', rows: 8, spellcheck: 'false', value: '$.value',
+    paneLabel,
+    ['textarea', { class: 'editor', rows: 8, spellcheck: 'false', value: '$.value', 'aria-invalid': invalid,
       on: { input: { action: 'play/data', with: { key: '$.key' } } } }],
   ],
 };

package/src/component/viewmodel.js

@@ -27,6 +27,59 @@ function formatTiming(timing) {
   return parts.length === 0 ? null : parts.join(' · ');
 }
 
+/**
+ * The location an error states, as the phrase a pane label carries — one
+ * per family, in the wording the compilers' own messages use: a JSON
+ * Pointer (`at /rules/3`; the root pointer `''` reads "at the root"), a
+ * 0-based source offset (`at position 7`), or a 1-based line and column
+ * (`at line 2, column 5`). Empty when the error states no location.
+ */
+function formatWhere(err) {
+  if (!err) return '';
+  const parts = [];
+  if (typeof err.path === 'string') parts.push(`at ${err.path === '' ? 'the root' : err.path}`);
+  if (typeof err.position === 'number') parts.push(`at position ${err.position}`);
+  if (typeof err.line === 'number') {
+    parts.push(`at line ${err.line}${typeof err.column === 'number' ? `, column ${err.column}` : ''}`);
+  }
+  return parts.join(', ');
+}
+
+/**
+ * The error's claim on one editor pane. The pane the error names is
+ * INVALID (its text is what failed — the compile, the run, or a JSON parse)
+ * and carries the location phrase; a data pane is not invalid when a
+ * runtime error merely failed AT a location in it (a patch op removing a
+ * path the target lacks blames the op, not the target), yet that location
+ * is the lesson, so the data pane carries it as `where` without the flag.
+ * @returns {{ invalid: boolean, where: string }}
+ */
+function paneError(err, key, isData) {
+  if (!err) return { invalid: false, where: '' };
+  if (err.pane === key) return { invalid: true, where: formatWhere(err) };
+  if (isData && typeof err.dataPath === 'string') {
+    return { invalid: false, where: `at ${err.dataPath === '' ? 'the root' : err.dataPath}` };
+  }
+  return { invalid: false, where: '' };
+}
+
+/**
+ * The stage's error line. `code` is shown as its own chip, so a message
+ * that begins with that same code (the coded family composes
+ * `code: reason at path`) drops the prefix rather than reading it twice;
+ * `paneLabel` names the editor the error is about (the pane's LABEL, for
+ * a reader), empty when no pane owns it.
+ */
+function deriveError(err, panes) {
+  if (!err) return null;
+  const code = err.code ?? '';
+  const message = err.message ?? '';
+  const prefix = `${code}: `;
+  const text = code !== '' && message.startsWith(prefix) ? message.slice(prefix.length) : message;
+  const pane = typeof err.pane === 'string' ? panes.find((p) => p.key === err.pane) : undefined;
+  return { code, message, text, paneLabel: pane?.label ?? '' };
+}
+
 /**
  * Shape one panel for the view: kind flags for the `$if` dispatch plus the
  * per-kind content (a `table` becomes column/cell records the JSLT can walk).
@@ -62,7 +115,7 @@ function shapePanel(p) {
  * else the first — so a fresh result with different screens never strands
  * the view on a tab that is gone.
  */
-function deriveResult(r, wantedId, deepWanted, deepPick) {
+function deriveResult(r, wantedId, deepWanted, deepPick, panes) {
   const all = Array.isArray(r.panels) ? r.panels : [];
   const panels = all.filter((p) => p.depth !== 'deep');
   const deep = all.filter((p) => p.depth === 'deep');
@@ -75,7 +128,7 @@ function deriveResult(r, wantedId, deepWanted, deepPick) {
   return {
     ran: true,
     ok: r.ok === true,
-    error: r.error ? { code: r.error.code ?? '', message: r.error.message ?? '' } : null,
+    error: deriveError(r.error, panes),
     timing: formatTiming(r.timing),
     tabbed: panels.length > 1,
     tabs: panels.map((p) => ({ id: p.id, label: p.label ?? p.id, active: p.id === activeId })),
@@ -113,11 +166,16 @@ export function playViewModel(state) {
     examples: exs.map((ex) => ({ id: ex.id, label: ex.label, active: ex.id === s.exampleId })),
   }));
 
+  // the editors, each carrying the last error's claim on it (an invalid
+  // flag + a location phrase) so the pane the learner has to fix says so
+  const err = s.result?.error ?? null;
   const sourcePanes = (engine?.sourcePanes ?? []).map((p) => ({
     key: p.key, label: p.label, control: p.control ?? 'code', value: s.source?.[p.key] ?? '',
+    ...paneError(err, p.key, false),
   }));
   const dataPanes = (engine?.dataPanes ?? []).map((p) => ({
     key: p.key, label: p.label, value: s.data?.[p.key] ?? '',
+    ...paneError(err, p.key, true),
   }));
 
   // option panes: live mode selects (josl dialect, csv repair/headers/…);
@@ -133,7 +191,7 @@ export function playViewModel(state) {
   const datasets = (active?.datasets ?? []).map((ds, i) => ({ index: i, label: ds.label, active: i === datasetIndex }));
 
   const r = s.result ?? null;
-  const result = r === null ? { ran: false } : deriveResult(r, s.panel, s.deep, s.deepPick);
+  const result = r === null ? { ran: false } : deriveResult(r, s.panel, s.deep, s.deepPick, [...sourcePanes, ...dataPanes]);
 
   // the IDE half: the saveable-session chrome
   const names = Array.isArray(s.names) ? s.names : [];

package/src/engines.js

@@ -18,6 +18,9 @@ import { parseXQuery } from '@jarenjs/json/xquery';
 import { parseJosl, stringifyJosl, stringifyJsonx } from '@jarenjs/josl';
 import { parseCsvDocument, stringifyCsv, sniffCsvDialect } from '@jarenjs/josl/csv';
 import { createTypeTestCompiler } from '@jarenjs/validate/query';
+import { compileContract } from '@jarenjs/contract';
+import { openLocalClient } from '@jarenjs/contract/local';
+import { toOpenApi, toTypeScript } from '@jarenjs/contract/project';
 import { formatMs } from './format.js';
 
 const compileTypeTest = createTypeTestCompiler();
@@ -27,10 +30,18 @@ const fmt = (v) => (v === undefined ? '(no result)' : JSON.stringify(v, null, 2)
 const msg = (err) => String(/** @type {any} */ (err)?.message ?? err);
 const code = (err) => /** @type {any} */ (err)?.code;
 
-/** Parse a pane's JSON text; `{ value }` or `{ error }`. */
-function parseJson(text, label) {
+/**
+ * Parse a pane's JSON text; `{ value }` or `{ error, pane }`. `pane` is the
+ * pane KEY (what the result's error location names); `label` is the word
+ * the message uses for it, which differs where the pane's label does (the
+ * patch engine's `data` pane is its "target"). The host's `JSON.parse`
+ * states the offending offset only inside its engine-specific message
+ * text, never as a field — so a parse failure locates the PANE and
+ * nothing finer.
+ */
+function parseJson(text, pane, label = pane) {
   try { return { value: JSON.parse((text ?? 'null') === '' ? 'null' : text) }; }
-  catch (err) { return { error: `${label}: ${msg(err)}` }; }
+  catch (err) { return { error: `${label}: ${msg(err)}`, pane }; }
 }
 
 /** A single-`code`-panel Result — the shape most engines return. */
@@ -85,7 +96,7 @@ function visual(id, label, lead, opts = {}) {
       const t0 = now();
       let view;
       try { view = render(source.source ?? '', options?.config); }
-      catch (err) { return fail(msg(err), code(err)); }
+      catch (err) { return fail(msg(err), code(err), locate(err, 'source')); }
       const t1 = now();
       return okPanels(renderedPanels(view), ...renderTiming(view, t1 - t0));
     },
@@ -118,8 +129,50 @@ function renderedPanels(view) {
     : [];
   return [{ id: 'preview', label: 'Preview', kind: 'view', vnode }, ...deep];
 }
-/** @returns {import('./index.js').PlayResult} */
-const fail = (message, c, path) => ({ ok: false, timing: null, error: { message, code: c, path }, panels: [] });
+/**
+ * An error Result. `where` is the location half of the format's error —
+ * `pane` plus whichever of `path`/`dataPath`/`position`/`line`/`column`
+ * the compiler stated (see {@link locate}); only stated fields land on
+ * the error, so a field's presence means the compiler said it.
+ * @returns {import('./index.js').PlayResult}
+ */
+const fail = (message, c, where) => ({
+  ok: false, timing: null,
+  error: { message, ...(c === undefined ? {} : { code: c }), ...where },
+  panels: [],
+});
+
+/** The error Result of a pane whose JSON did not parse — locates the pane. */
+const failParse = (d) => fail(d.error, undefined, { pane: d.pane });
+
+/**
+ * The location an engine error carries, in the format's own fields — one
+ * adapter over the three shapes the compilers use. The coded family
+ * (`@jarenjs/core` `CodedError`: patch, query, JSLT, JTLT) states a
+ * `docPath`, a JSON Pointer into the document being compiled or run, and
+ * a patch runtime error adds the `dataPath` its operation failed at in the
+ * target; the syntax family (JSONPath, JSON Pointer, XQuery) states a
+ * 0-based `position` into the source text; the line/column family (JOSL,
+ * CSV) states 1-based `line`/`column`. Only what the error carries is
+ * copied. `pane` names the editor the phase was working on — the source
+ * pane for compile AND run (a runtime location points into the compiled
+ * document, which is that pane's text) — and is omitted where the
+ * location is into a document the learner never typed (XQuery compiles a
+ * GENERATED query document, and a location in it has no pane).
+ * @param {unknown} err
+ * @param {string} [pane] the pane key the location points into
+ */
+function locate(err, pane) {
+  const e = /** @type {any} */ (err);
+  /** @type {{ pane?: string, path?: string, dataPath?: string, position?: number, line?: number, column?: number }} */
+  const where = pane === undefined ? {} : { pane };
+  if (typeof e?.docPath === 'string') where.path = e.docPath;
+  if (typeof e?.dataPath === 'string') where.dataPath = e.dataPath;
+  if (typeof e?.position === 'number') where.position = e.position;
+  if (typeof e?.line === 'number') where.line = e.line;
+  if (typeof e?.column === 'number') where.column = e.column;
+  return where;
+}
 
 /** The compile options the query/jslt engines run with (registry-aware). */
 function compileOptions(options) {
@@ -135,14 +188,14 @@ export const ENGINE_LIST = [
     sourcePanes: [{ key: 'selector', label: 'Selector', control: 'text' }],
     dataPanes: [{ key: 'data', label: 'Data' }],
     run(source, data) {
-      const d = parseJson(data.data, 'data'); if (d.error) return fail(d.error);
+      const d = parseJson(data.data, 'data'); if (d.error) return failParse(d);
       let compiled; const t0 = now();
       try { compiled = compileJSONPath(source.selector ?? ''); }
-      catch (err) { return fail(msg(err), code(err)); }
+      catch (err) { return fail(msg(err), code(err), locate(err, 'selector')); }
       const t1 = now();
       let nodes;
       try { nodes = compiled.nodes(d.value); }
-      catch (err) { return fail(msg(err), code(err)); }
+      catch (err) { return fail(msg(err), code(err), locate(err, 'selector')); }
       const t2 = now();
       return ok(fmt(nodes.map((n) => n.value)), t1 - t0, t2 - t1, [
         deepCards('how', 'How it matched', [
@@ -164,16 +217,16 @@ export const ENGINE_LIST = [
     ],
     dataPanes: [{ key: 'data', label: 'Data' }],
     run(source, data) {
-      const d = parseJson(data.data, 'data'); if (d.error) return fail(d.error);
+      const d = parseJson(data.data, 'data'); if (d.error) return failParse(d);
       const pointer = source.pointer ?? '';
       const relative = /^\d/.test(pointer);
       let getter; const t0 = now();
       try { getter = relative ? compileRelativeJSONPointer(pointer) : compileJSONPointer(pointer); }
-      catch (err) { return fail(msg(err), code(err)); }
+      catch (err) { return fail(msg(err), code(err), locate(err, 'pointer')); }
       const t1 = now();
       let value;
       try { value = relative ? getter(d.value, source.location ?? '') : getter(d.value); }
-      catch (err) { return fail(msg(err), code(err)); }
+      catch (err) { return fail(msg(err), code(err), locate(err, 'pointer')); }
       const t2 = now();
       if (value === JSONPOINTER_NOTHING) return ok('(nothing — the pointer addresses no value)', t1 - t0, t2 - t1);
       return ok(fmt(value), t1 - t0, t2 - t1);
@@ -193,13 +246,13 @@ export const ENGINE_LIST = [
     }],
     run(source, data, options) {
       const mode = options?.config?.mode ?? 'patch';
-      const target = parseJson(data.data, 'target'); if (target.error) return fail(target.error);
-      const patch = parseJson(source.patch, 'patch'); if (patch.error) return fail(patch.error);
+      const target = parseJson(data.data, 'data', 'target'); if (target.error) return failParse(target);
+      const patch = parseJson(source.patch, 'patch'); if (patch.error) return failParse(patch);
       if (mode === 'merge') {
         // RFC 7396: null members delete; an unchanged document is the INPUT
         let out; const t0 = now();
         try { out = applyMergePatch(target.value, patch.value); }
-        catch (err) { return fail(msg(err), code(err)); }
+        catch (err) { return fail(msg(err), code(err), locate(err, 'patch')); }
         const t1 = now();
         return ok(fmt(out), null, t1 - t0, [
           deepCards('how', 'How it merged', [
@@ -215,7 +268,7 @@ export const ENGINE_LIST = [
           jsonPatch = createJSONPatch(target.value, patch.value);
           mergePatch = createMergePatch(target.value, patch.value);
         }
-        catch (err) { return fail(msg(err), code(err)); }
+        catch (err) { return fail(msg(err), code(err), locate(err, 'patch')); }
         const t1 = now();
         return okPanels([
           { id: 'out', label: `JSON Patch (${jsonPatch.length} ops)`, kind: 'code', text: fmt(jsonPatch) },
@@ -224,11 +277,11 @@ export const ENGINE_LIST = [
       }
       let apply; const t0 = now();
       try { apply = compileJSONPatch(patch.value, { changes: true }); }
-      catch (err) { return fail(msg(err), code(err)); }
+      catch (err) { return fail(msg(err), code(err), locate(err, 'patch')); }
       const t1 = now();
       let run;
       try { run = apply(target.value); }
-      catch (err) { return fail(msg(err), code(err)); }
+      catch (err) { return fail(msg(err), code(err), locate(err, 'patch')); }
       const t2 = now();
       return ok(fmt(run.doc), t1 - t0, t2 - t1, [
         deepCode('changes', 'What changed', fmt(run.changes)),
@@ -240,19 +293,19 @@ export const ENGINE_LIST = [
     sourcePanes: [{ key: 'query', label: 'Query', control: 'code' }, { key: 'externals', label: 'Externals', control: 'code' }],
     dataPanes: [{ key: 'data', label: 'Data' }],
     run(source, data, options) {
-      const d = parseJson(data.data, 'data'); if (d.error) return fail(d.error);
-      const q = parseJson(source.query, 'query'); if (q.error) return fail(q.error);
+      const d = parseJson(data.data, 'data'); if (d.error) return failParse(d);
+      const q = parseJson(source.query, 'query'); if (q.error) return failParse(q);
       let externals = {};
       if (source.externals !== undefined && String(source.externals).trim() !== '') {
-        const e = parseJson(source.externals, 'externals'); if (e.error) return fail(e.error); externals = e.value;
+        const e = parseJson(source.externals, 'externals'); if (e.error) return failParse(e); externals = e.value;
       }
       let fn; const t0 = now();
       try { fn = compileJsonQuery(q.value, compileOptions(options)); }
-      catch (err) { return fail(msg(err), code(err)); }
+      catch (err) { return fail(msg(err), code(err), locate(err, 'query')); }
       const t1 = now();
       let out;
       try { out = fn(d.value, externals); }
-      catch (err) { return fail(msg(err), code(err)); }
+      catch (err) { return fail(msg(err), code(err), locate(err, 'query')); }
       const t2 = now();
       const items = out === undefined ? 0 : Array.isArray(out) ? out.length : 1;
       return ok(fmt(out), t1 - t0, t2 - t1, [
@@ -269,15 +322,15 @@ export const ENGINE_LIST = [
     sourcePanes: [{ key: 'stylesheet', label: 'Stylesheet', control: 'code' }],
     dataPanes: [{ key: 'data', label: 'Data' }],
     run(source, data, options) {
-      const d = parseJson(data.data, 'data'); if (d.error) return fail(d.error);
-      const s = parseJson(source.stylesheet, 'stylesheet'); if (s.error) return fail(s.error);
+      const d = parseJson(data.data, 'data'); if (d.error) return failParse(d);
+      const s = parseJson(source.stylesheet, 'stylesheet'); if (s.error) return failParse(s);
       let compiled; const t0 = now();
       try { compiled = compileJsltStylesheet(s.value, compileOptions(options)); }
-      catch (err) { return fail(msg(err), code(err)); }
+      catch (err) { return fail(msg(err), code(err), locate(err, 'stylesheet')); }
       const t1 = now();
       let out;
       try { out = compiled(d.value); }
-      catch (err) { return fail(msg(err), code(err)); }
+      catch (err) { return fail(msg(err), code(err), locate(err, 'stylesheet')); }
       const t2 = now();
       // the identity lesson: a rule that changes nothing hands the INPUT back
       // (shared, copy-on-write) — worth teaching, so the deep card says which
@@ -295,15 +348,15 @@ export const ENGINE_LIST = [
     sourcePanes: [{ key: 'template', label: 'Template', control: 'code' }],
     dataPanes: [{ key: 'data', label: 'Data' }],
     run(source, data, options) {
-      const d = parseJson(data.data, 'data'); if (d.error) return fail(d.error);
-      const t = parseJson(source.template, 'template'); if (t.error) return fail(t.error);
+      const d = parseJson(data.data, 'data'); if (d.error) return failParse(d);
+      const t = parseJson(source.template, 'template'); if (t.error) return failParse(t);
       let render; const t0 = now();
       try { render = compileJtltStylesheet(t.value, compileOptions(options)); }
-      catch (err) { return fail(msg(err), code(err)); }
+      catch (err) { return fail(msg(err), code(err), locate(err, 'template')); }
       const t1 = now();
       let out;
       try { out = render(d.value); }
-      catch (err) { return fail(msg(err), code(err)); }
+      catch (err) { return fail(msg(err), code(err), locate(err, 'template')); }
       const t2 = now();
       // JTLT emits TEXT (markdown / xml / source) — show it verbatim, not fmt'd
       return ok(out === '' ? '(empty)' : out, t1 - t0, t2 - t1, [
@@ -317,20 +370,22 @@ export const ENGINE_LIST = [
     sourcePanes: [{ key: 'text', label: 'XQuery', control: 'code' }],
     dataPanes: [{ key: 'data', label: 'Data' }],
     run(source, data, options) {
-      const d = parseJson(data.data, 'data'); if (d.error) return fail(d.error);
+      const d = parseJson(data.data, 'data'); if (d.error) return failParse(d);
       let doc, fn; const t0 = now();
-      try {
-        doc = parseXQuery(source.text ?? '');
-        fn = compileJsonQuery(doc, compileOptions(options));
-      }
-      catch (err) { return fail(msg(err), code(err)); }
+      // two phases: the text parses (a syntax error locates a position in
+      // the XQuery pane), then the GENERATED query document compiles and
+      // runs — a location in that document has no pane the learner typed
+      try { doc = parseXQuery(source.text ?? ''); }
+      catch (err) { return fail(msg(err), code(err), locate(err, 'text')); }
+      try { fn = compileJsonQuery(doc, compileOptions(options)); }
+      catch (err) { return fail(msg(err), code(err), locate(err)); }
       const t1 = now();
       let out;
       try {
         const externals = fn.externals.includes('doc') ? { doc: d.value } : {};
         out = fn(d.value, externals);
       }
-      catch (err) { return fail(msg(err), code(err)); }
+      catch (err) { return fail(msg(err), code(err), locate(err)); }
       const t2 = now();
       return ok(out === undefined ? '(empty sequence)' : fmt(out), t1 - t0, t2 - t1, [
         // the machinery: the XQuery text parses to a runnable query DOCUMENT
@@ -355,7 +410,7 @@ export const ENGINE_LIST = [
       // parser streams document-order events as it reads — capture (capped)
       // for the "how it streamed" drill-down
       try { parsed = parseJosl(source.text ?? '', { mode, onEvent: (e) => { if (events.length < 200) events.push(e); } }); }
-      catch (err) { return fail(msg(err), code(err)); }
+      catch (err) { return fail(msg(err), code(err), locate(err, 'text')); }
       const t1 = now();
       const out = stringifyJsonx(parsed, { indent: 2 });
       const t2 = now();
@@ -391,7 +446,7 @@ export const ENGINE_LIST = [
       // strict mode THROWS on the first RFC 4180 violation (with a code);
       // repair mode reads anyway and lists every fix — the lesson of the tab
       try { doc = parseCsvDocument(source.text ?? '', opts); }
-      catch (err) { return fail(msg(err), code(err)); }
+      catch (err) { return fail(msg(err), code(err), locate(err, 'text')); }
       const t1 = now();
       // one calm SCREEN (the summary note) plus the drill-down: the parsed
       // records, the sniffed dialect, the repairs, and the CSV round-trip
@@ -461,12 +516,12 @@ export const ENGINE_LIST = [
       if (typeof validate !== 'function') {
         return fail('the JSON Schema engine validates in the host — inject options.validate', 'PLAY_NO_VALIDATOR');
       }
-      const d = parseJson(data.data, 'data'); if (d.error) return fail(d.error);
+      const d = parseJson(data.data, 'data'); if (d.error) return failParse(d);
       const locale = options?.config?.locale ?? 'en';
       let report;
       try { report = validate(source.schema ?? '', d.value, locale); }
-      catch (err) { return fail(msg(err), code(err)); }
-      if (report.schemaError) return fail(report.schemaError, 'SCHEMA');
+      catch (err) { return fail(msg(err), code(err), locate(err)); }
+      if (report.schemaError) return fail(report.schemaError, 'SCHEMA', { pane: 'schema' });
       const errs = report.errors ?? [];
       const summary = (report.valid ? '✓ valid' : `✗ ${errs.length} error${errs.length === 1 ? '' : 's'}`)
         + ` · ${report.draft} · compiled ${formatMs(report.compileMs)} · validated ${formatMs(report.validateMs)}`;
@@ -494,15 +549,83 @@ export const ENGINE_LIST = [
       if (typeof render !== 'function') {
         return fail('the MDX engine renders in the host — inject options.renderers.mdx', 'PLAY_NO_RENDERER');
       }
-      const d = parseJson(data.data, 'data'); if (d.error) return fail(d.error);
+      const d = parseJson(data.data, 'data'); if (d.error) return failParse(d);
       const t0 = now();
       let view;
       try { view = render(source.source ?? '', d.value); }
-      catch (err) { return fail(msg(err), code(err)); }
+      catch (err) { return fail(msg(err), code(err), locate(err, 'source')); }
       const t1 = now();
       return okPanels(renderedPanels(view), ...renderTiming(view, t1 - t0));
     },
   },
+  {
+    // the one ASYNC engine: the dispatch panel resolves a real client
+    // outcome, so run() returns a Promise — runExample and the hosts
+    // pass a thenable Result through (PLAY-FORMAT §2)
+    id: 'contract', label: 'Contract', lead: 'A $contract document — operations two ends may exchange, compiled, projected and dispatched in-process.',
+    sourcePanes: [{ key: 'document', label: '$contract document', control: 'code' }],
+    dataPanes: [{ key: 'call', label: 'Dispatch — { "op", "input" }' }],
+    async run(source, data) {
+      const d = parseJson(source.document, 'document'); if (d.error) return failParse(d);
+      let contract; const t0 = now();
+      // a compile refusal is the engine's lesson: a stable JC00xx code
+      // with the JSON Pointer of the member at fault
+      try { contract = compileContract(d.value); }
+      catch (err) { return fail(msg(err), code(err), locate(err, 'document')); }
+      const t1 = now();
+      let openapi, types;
+      try {
+        openapi = toOpenApi(contract, {
+          info: {
+            title: typeof d.value?.id === 'string' ? d.value.id : 'contract',
+            version: typeof d.value?.version === 'string' ? d.value.version : '0',
+          },
+        });
+        types = toTypeScript(contract);
+      }
+      catch (err) { return fail(msg(err), code(err), locate(err, 'document')); }
+      // the dispatch pane: an op + input run against trivial echo
+      // handlers over the local binding — the whole pipeline with no
+      // network. Output validation is DECLARED off (a capability the
+      // binding states), so any echo crosses; input validation still
+      // refuses a bad input with its outcome, which is the lesson.
+      /** @type {import('./index.js').Panel} */
+      let dispatch = {
+        id: 'dispatch', label: 'Dispatch', kind: 'note', tone: 'info',
+        text: 'Type { "op": "<operation id>", "input": { … } } in the Dispatch pane to run an operation against echo handlers (validateOutput declared \'never\').',
+      };
+      if (String(data.call ?? '').trim() !== '') {
+        const call = parseJson(data.call, 'call'); if (call.error) return failParse(call);
+        const op = call.value !== null && typeof call.value === 'object' ? call.value.op : undefined;
+        if (typeof op !== 'string') {
+          dispatch = { id: 'dispatch', label: 'Dispatch', kind: 'note', tone: 'warn', text: 'the call must be an object naming an "op" (and optionally an "input")' };
+        }
+        else {
+          /** @type {Record<string, (input: any) => any>} */
+          const handlers = {};
+          for (const id of Object.keys(contract.operations)) handlers[id] = (input) => input;
+          const client = openLocalClient(contract, handlers, { validateOutput: 'never' });
+          try {
+            const outcome = await client.invoke(op, call.value.input ?? {});
+            dispatch = { id: 'dispatch', label: 'Dispatch (echo)', kind: 'code', text: fmt(outcome) };
+          }
+          catch (err) {
+            // a host mistake (JC1005: unknown, opaque or subscribe
+            // operation) is the panel's answer, not an engine failure
+            dispatch = { id: 'dispatch', label: 'Dispatch', kind: 'note', tone: 'warn', text: msg(err) };
+          }
+          finally { client.close(); }
+        }
+      }
+      const t2 = now();
+      return okPanels([
+        { id: 'describe', label: 'describe()', kind: 'code', text: fmt(contract.describe()) },
+        { id: 'openapi', label: 'OpenAPI', kind: 'code', text: fmt(openapi.document) },
+        { id: 'types', label: 'TypeScript', kind: 'code', text: types },
+        dispatch,
+      ], t1 - t0, t2 - t1);
+    },
+  },
   // ——— the visual engines: descriptor + examples here, rendering delegated ———
   visual('markdown', 'Markdown', 'CommonMark + GFM + frontmatter → a JSON AST, rendered live.', { sourceLabel: 'Markdown' }),
   visual('mermaid', 'Mermaid', 'Diagrams-as-code → a geometry-free AST → pure-vnode SVG.', { sourceLabel: 'Mermaid' }),

package/src/examples.js

@@ -543,4 +543,46 @@ is a fixed point.
       name: { type: 'string', minLength: 2 }, email: { type: 'string', format: 'email' }, age: { type: 'integer', minimum: 13 },
     }, required: ['name', 'email'] }) },
     datasets: [{ label: 'invalid', data: { data: j({ name: 'A', email: 'not-an-email', age: 7 }) } }] },
+
+  // ——— Contract ($contract document → describe / OpenAPI / TypeScript / dispatch) ———
+  { id: 'contract-shop', label: 'A shop contract', engine: 'contract',
+    source: { document: j({ $contract: '0.1', id: 'shop', version: '1',
+      $defs: { Product: { type: 'object', required: ['id', 'name', 'price'], properties: {
+        id: { type: 'integer' }, name: { type: 'string', minLength: 1 }, price: { type: 'number', minimum: 0 } } } },
+      operations: {
+        'catalog.load': { kind: 'read',
+          input: { type: 'object', properties: { since: { type: 'string', format: 'date-time' } } },
+          output: { type: 'array', items: { $ref: '#/$defs/Product' } },
+          http: { method: 'GET', path: '/api/catalog' },
+          doc: 'The whole catalog.' },
+        'product.save': { kind: 'command',
+          input: { type: 'object', required: ['id', 'product'], properties: {
+            id: { type: 'integer' }, product: { $ref: '#/$defs/Product' } } },
+          output: { $ref: '#/$defs/Product' },
+          errors: { conflict: { status: 409 } },
+          policy: { idempotency: 'optional' },
+          http: { method: 'PUT', path: '/api/products/{id}' } },
+      } }) },
+    datasets: [
+      { label: 'a valid save', data: { call: j({ op: 'product.save', input: { id: 7, product: { id: 7, name: 'Duck', price: 9.99 } } }) } },
+      { label: 'an invalid input', data: { call: j({ op: 'product.save', input: { id: 'seven' } }) } },
+      { label: 'no dispatch', data: { call: '' } },
+    ] },
+  { id: 'contract-minimal', label: 'One operation, no http', engine: 'contract',
+    source: { document: j({ $contract: '0.1', id: 'echo', operations: {
+      'echo.say': { kind: 'command',
+        input: { type: 'object', required: ['text'], properties: { text: { type: 'string' } } },
+        output: true,
+        doc: 'No http member: the binding defaults to POST /echo.say.' },
+    } }) },
+    datasets: [{ label: 'say something', data: { call: j({ op: 'echo.say', input: { text: 'hello' } }) } }] },
+  { id: 'contract-broken', label: 'A refusal, with its docPath', engine: 'contract',
+    source: { document: j({ $contract: '0.1', id: 'broken', operations: {
+      'catalog.load': { kind: 'read',
+        input: { type: 'object', properties: { since: { type: 'string' } } },
+        // no output member: JC00xx at compile, never at request time —
+        // the error names /operations/catalog.load with its code
+        http: { method: 'GET', path: '/api/catalog' } },
+    } }) },
+    datasets: [{ label: 'nothing to dispatch', data: { call: '' } }] },
 ];

package/src/index.js

@@ -54,11 +54,38 @@ import { EXAMPLE_LIST } from './examples.js';
  *   `cards`: a row of stat cards (matches, compile/run timings, …)
  */
 
+/**
+ * The error half of a Result: what the compiler said, plus WHERE — in the
+ * format's own fields, so the view can point at the pane and the location
+ * rather than only quoting the message. Every location field is present
+ * exactly when the compiler stated it (a field is never fabricated), and
+ * `pane` names the editor the location points into; a location into a
+ * document the learner never typed (XQuery's generated query document) has
+ * no pane. See PLAY-FORMAT §2.
+ * @typedef {Object} PlayError
+ * @property {string} message - the compiler's message, verbatim (a coded
+ *   error composes `code: reason at path` itself)
+ * @property {string} [code] - the stable diagnosis code, when there is one
+ * @property {string} [pane] - the pane KEY (source or data) the error is
+ *   about: the source pane for a compile or run failure, the data pane
+ *   whose JSON did not parse
+ * @property {string} [path] - JSON Pointer into that pane's DOCUMENT (a
+ *   coded error's `docPath`: the failing patch operation, the query
+ *   construct, the stylesheet rule)
+ * @property {string} [dataPath] - JSON Pointer into the DATA the document
+ *   was applied to, when a runtime error blames both (a patch operation
+ *   AND the target location it failed at)
+ * @property {number} [position] - 0-based offset into that pane's TEXT
+ *   (the syntax family: a JSONPath selector, a JSON Pointer, an XQuery)
+ * @property {number} [line] - 1-based line (the JOSL / CSV family)
+ * @property {number} [column] - 1-based column (with `line`)
+ */
+
 /**
  * @typedef {Object} PlayResult
  * @property {boolean} ok
  * @property {{ compileMs: number, runMs: number } | null} timing
- * @property {{ message: string, code?: string, path?: string } | null} error
+ * @property {PlayError | null} error - null on an ok run
  * @property {Panel[]} panels - the result screens (`[]` on error); a single
  *   `code` panel for most engines, several for the richer ones
  */
@@ -71,7 +98,11 @@ import { EXAMPLE_LIST } from './examples.js';
  * @property {EnginePane[]} sourcePanes - the engine INPUT pane(s)
  * @property {EnginePane[]} dataPanes - the JSON it runs against (may be [])
  * @property {OptionPane[]} [optionPanes] - live mode selects (may be absent)
- * @property {(source: Record<string, string>, data: Record<string, string>, options?: RunOptions) => PlayResult} run
+ * @property {(source: Record<string, string>, data: Record<string, string>, options?: RunOptions) => PlayResult | Promise<PlayResult>} run
+ *   most engines answer synchronously; an engine whose run resolves real
+ *   promises (the contract engine's dispatch panel) answers a thenable
+ *   Result, which `runExample` passes through with the same never-throw
+ *   contract (a rejection settles into an error Result)
  */
 
 /**
@@ -135,23 +166,31 @@ function withConfig(engine, options) {
 
 /**
  * Run one engine over a source + data. An unknown engine (or a throwing
- * runner) yields an error Result — this never throws.
+ * runner) yields an error Result — this never throws. A synchronous
+ * engine answers a Result; an async engine (the contract dispatch)
+ * answers a Promise of one that never rejects — a host that must know
+ * which awaits `Promise.resolve(runExample(…))`.
  * @param {string} engineId
  * @param {Record<string, string>} source
  * @param {Record<string, string>} data
  * @param {RunOptions} [options] - operators (query/jslt), the option-pane
  *   config, and host renderers (markdown/mermaid/charts)
- * @returns {PlayResult}
+ * @returns {PlayResult | Promise<PlayResult>}
  */
 export function runExample(engineId, source, data, options = {}) {
   const engine = ENGINES[engineId];
   if (engine === undefined) {
     return { ok: false, timing: null, error: { message: `unknown engine: ${engineId}` }, panels: [] };
   }
+  const failed = (/** @type {unknown} */ err) =>
+    /** @type {PlayResult} */ ({ ok: false, timing: null, error: { message: String(/** @type {any} */ (err)?.message ?? err) }, panels: [] });
   try {
-    return engine.run(source ?? {}, data ?? {}, withConfig(engine, options));
+    const result = engine.run(source ?? {}, data ?? {}, withConfig(engine, options));
+    return result !== null && typeof result === 'object' && typeof (/** @type {any} */ (result).then) === 'function'
+      ? /** @type {Promise<PlayResult>} */ (result).then((r) => r, failed)
+      : result;
   }
   catch (err) {
-    return { ok: false, timing: null, error: { message: String(/** @type {any} */ (err)?.message ?? err) }, panels: [] };
+    return failed(err);
   }
 }

package/styles/play.css

@@ -70,6 +70,12 @@
 .jplay-lead { font-size: 0.8rem; }
 .jplay-pane { display: flex; flex-direction: column; gap: 2px; min-width: 0; }
 .jplay-pane-label { font-size: 0.7rem; font-family: var(--mono, monospace); }
+/* the last error's claim on a pane: the location rides on the label, and the
+   editor it is about carries aria-invalid — the state the renderer owns —
+   which is what the ring is styled off (the --fail family, no new hue) */
+.jplay-pane-where { color: var(--fail, #dc2626); }
+.jplay .editor[aria-invalid='true'] { border-color: var(--fail, #dc2626); }
+.jplay-error-pane { color: var(--muted, #64748b); }
 .jplay-datasets { align-self: flex-start; }
 /* the validate engine's JSON ↔ form toggle + the generated-form container */
 .jplay-dataview { align-self: flex-start; }