@jarenjs/play 0.34.0 → 0.34.2

package/README.md

@@ -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/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
@@ -206,11 +247,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
  */

package/docs/PLAY-FORMAT.md

@@ -38,10 +38,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 +71,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.34.2",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",
@@ -56,9 +56,9 @@
     "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/core": "^0.34.2",
+    "@jarenjs/josl": "^0.34.2",
+    "@jarenjs/json": "^0.34.2",
+    "@jarenjs/validate": "^0.34.2"
   }
 }

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

@@ -27,10 +27,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 +93,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 +126,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 +185,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 +214,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 +243,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 +265,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 +274,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 +290,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 +319,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 +345,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 +367,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 +407,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 +443,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 +513,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,11 +546,11 @@ 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));
     },

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
  */

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; }