@quario/editor 0.1.0

package/lib/index.js

@@ -0,0 +1,820 @@
+/**
+ * @quario/editor — the embeddable banded document designer. Not a target: it
+ * compiles nothing itself and never touches the event stream. `<quario-editor>`
+ * takes a starter `schema` plus the host's engine and html target through
+ * properties, displays the report rendered on sample data as its design
+ * surface, and lets the author rearrange it structurally — every edit
+ * recompiles and re-renders through the real engine, so what the author sees
+ * is the report, not an approximation of it. The edited document reaches the
+ * host on every committed change, deep-frozen, with its problem list.
+ *
+ * Importing this module defines nothing: the element class is the export, and
+ * `@quario/editor/register` performs the one-line define
+ * (docs/adr/0005-the-surfaces-are-custom-elements.md).
+ *
+ * The engine and the renderer arrive as properties, not imports (`instance`,
+ * `target`), so the editor forces no runtime dependency on either and the
+ * licence stays on the instance where the §6 mechanics put it. The unlicensed
+ * marking is left exactly as the fragment carries it: it depends on no grant,
+ * and the editor adds no wording of its own.
+ */
+import { Task, TaskStatus } from "@lit/task";
+import { LitElement, html, nothing } from "lit";
+import { tinykeys } from "tinykeys";
+import { CHROME, SURFACE } from "./chrome.js";
+import {
+  addGroupBand,
+  bandOfItem,
+  checkFunctions,
+  checkInstance,
+  checkPage,
+  checkScheme,
+  checkSchema,
+  checkTarget,
+  crumbsOf,
+  duplicateColumn,
+  duplicateItem,
+  indexOfItem,
+  insertColumn,
+  insertItem,
+  legalSlots,
+  moveColumn,
+  moveGroup,
+  moveItem,
+  nodeKindAt,
+  placeholders,
+  removeColumn,
+  removeGroup,
+  removeGroupBand,
+  removeItem,
+  resolve,
+  widenHeader,
+  writeField,
+} from "./document.js";
+import { history } from "./history.js";
+import { groupsSection, problemsSection, propertiesSection } from "./rail.js";
+import { stage } from "./stage.js";
+import { REPORT } from "./style.js";
+
+/** The tag `@quario/editor/register` defines the element under. */
+export const TAG = "quario-editor";
+
+/** @type {(value: any) => any} */
+let deepFreeze = (value) => {
+  if (value && typeof value === "object")
+    for (let key of Object.keys(value)) deepFreeze(value[key]);
+  return Object.freeze(value);
+};
+
+/** A column header's own key, or one of the keys inside its object form. */
+/** @type {(key: string) => boolean} */
+let isHeaderKey = (key) => key === "header" || key.startsWith("header.");
+/** @type {(key: string) => string} */
+let headerKey = (key) => (key === "header" ? "value" : key.slice("header.".length));
+
+/** One step up a schema path: `detail[0].value` -> `detail[0]` -> `detail`.
+ * A path with nowhere left to climb answers "" and ends the walk. */
+/** @type {(path: string) => string} */
+let up = (path) => {
+  let above = path.replace(/(\.[^.[\]]+|\[\d+\])$/, "");
+  return above === path ? "" : above;
+};
+
+/** The error's own message: what the panel prints beside its label, and what
+ * `#checkOptions` compares by, since each check mints a fresh TypeError and
+ * the wording is the identity there. */
+/** @type {(error: unknown) => string} */
+let wording = (error) => String(/** @type {any} */ (error)?.message || error);
+
+/** Whether an announcement says what the standing one already says. The same
+ * failure re-reported is the same failure: it owes the host no second event,
+ * and it must not re-open a panel the author has dismissed. Wording is the
+ * identity for the same reason `#checkOptions` compares by it — each failure
+ * mints a fresh error object, so the objects never match. */
+/** @type {(failure: { label: string, error: unknown } | undefined, label: string, error: unknown) => boolean} */
+let repeats = (failure, label, error) =>
+  !!failure && failure.label === label && wording(failure.error) === wording(error);
+
+/** How long typing has to stop before it counts as a finished gesture. Yjs's
+ * `captureTimeout` default: short enough that one sentence is one entry, long
+ * enough that a thinking pause mid-expression is not five. */
+let PAUSE = 500;
+
+/** Whether two documents say the same thing. Every write hands back a fresh
+ * clone, so identity cannot tell a gesture that changed something from one
+ * that changed nothing — and the pause that commits typing is followed by the
+ * blur that would otherwise commit it again. Cheap beside the recompile every
+ * edit already pays. */
+/** @type {(a: any, b: any) => boolean} */
+let same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+/** Whether this write is a column's own header template, on a header still in
+ * its shorthand string form. */
+/** @type {(base: any, path: string, key: string) => boolean} */
+let shorthand = (base, path, key) =>
+  key === "header" && typeof resolve(base, path)?.header === "string";
+
+/** A column's shorthand string header stays shorthand for its own template;
+ * anything else about it widens the header first, and nothing narrows it back
+ * — `{ value: "Product" }` is a legal resting state. */
+/** @type {(base: any, path: string, key: string, value: any) => any} */
+let headerWritten = (base, path, key, value) =>
+  shorthand(base, path, key)
+    ? writeField(base, path, "header", value)
+    : writeField(widenHeader(base, path), path + ".header", headerKey(key), value);
+
+/** One field of `base` written, wherever that field actually lives. */
+/** @type {(base: any, path: string, key: string, value: any) => any} */
+let written = (base, path, key, value) =>
+  isHeaderKey(key) ? headerWritten(base, path, key, value) : writeField(base, path, key, value);
+
+/** Where a dropped item lands, mirroring `moveItem`'s own arithmetic. */
+/** @type {(path: string, slot: { band: string, index: number }) => string} */
+let landedAt = (path, slot) => {
+  let shifts = bandOfItem(path) === slot.band && indexOfItem(path) < slot.index;
+  return slot.band + "[" + (shifts ? slot.index - 1 : slot.index) + "]";
+};
+
+/**
+ * The editor element. Hosts assign `schema` (the starter document — the
+ * editor is uncontrolled and owns the document thereafter), `instance` (a
+ * quario instance), `target` (the html target, made with `paths: true`),
+ * plus `functions`, `data`, `page` and `colorScheme`, and listen for `change`
+ * and `error`; `renderComplete` is the one awaitable.
+ *
+ * Reassignment semantics differ per property, deliberately: only a **new**
+ * `schema` object resets the document, history and selection — assigning back
+ * the object the last `change` carried (or the one already adopted) is a
+ * no-op, which is the write-back guard a naive persist-and-restore loop
+ * needs. A new `instance`, `target`, `functions`, `data` or `page` recompiles
+ * and re-renders while leaving the author's work untouched; `colorScheme`
+ * repaints chrome without re-rendering.
+ *
+ * Removal is not destruction: disconnecting abandons in-flight work, the
+ * document and history persist, and reconnecting re-renders from them.
+ */
+export class QuarioEditor extends LitElement {
+  static styles = [CHROME, SURFACE, REPORT];
+
+  static properties = {
+    schema: { attribute: false },
+    instance: { attribute: false },
+    target: { attribute: false },
+    functions: { attribute: false },
+    data: { attribute: false },
+    page: { attribute: false },
+    colorScheme: { attribute: false },
+  };
+
+  /** The working document: what the sheet and the problem list answer to. It
+   * follows the author continuously — per keystroke, per colour-picker step —
+   * so correctness is reported live. May be invalid; that is legitimate and
+   * undoable. */
+  /** @type {any} */
+  #doc;
+  /** The live edit in flight: the field it is writing — both halves, since a
+   * `value` on one node is not a `value` on another — and the pause that will
+   * commit it. Undefined when the working and committed documents agree. */
+  /** @type {{ path: string, key: string, timer: ReturnType<typeof setTimeout> } | undefined} */
+  #pending;
+  /** @type {ReturnType<typeof history> | undefined} */
+  #history;
+  /** @type {string | null} */
+  #selection = null;
+  #revealed = false;
+  /** @type {readonly any[]} */
+  #problems = [];
+  /** @type {Record<string, readonly string[]>} */
+  #anchors = {};
+  /** Bumped per edit, live or committed; the task's argument for document
+   * changes. */
+  #epoch = 0;
+  /** The schema identities that mean "the document already here". */
+  /** @type {any} */
+  #adopted;
+  /** @type {any} */
+  #emitted;
+  /** Whether the next settled validation owes the host a change event. */
+  #owes = false;
+  /** Whether a fragment ever reached the sheet. */
+  #landed = false;
+  #stale = false;
+  /** @type {unknown} */
+  #invalid;
+  /** @type {{ label: string, error: unknown } | undefined} */
+  #failure;
+  #dismissed = false;
+  /** @type {(() => void) | undefined} */
+  #unbind;
+
+  #stage = stage({
+    select: (path, el) => this.#select(path, el),
+    slots: (path) => legalSlots(this.#doc, this.#anchors, path),
+    drop: (path, slot) => {
+      // The moved item stays selected, at the index `moveItem` actually put
+      // it: removing from an earlier position in the same band shifts the
+      // insertion point left, and the selection has to shift with it.
+      this.#commit(moveItem(this.#doc, path, slot), landedAt(path, slot));
+    },
+    dropColumn: (at, to) => {
+      let next = moveColumn(this.#doc, at, to);
+      this.#commit(next, "detail.columns[" + (at < to ? to - 1 : to) + "]");
+    },
+    insert: (band, index) => {
+      this.#commit(insertItem(this.#doc, band, index), band + "[" + index + "]");
+    },
+    remove: (path) => {
+      this.#commit(removeItem(this.#doc, path), null);
+    },
+    duplicate: (path) => {
+      // The copy lands right after its original, and takes the selection.
+      let index = indexOfItem(path) + 1;
+      this.#commit(duplicateItem(this.#doc, path), bandOfItem(path) + "[" + index + "]");
+    },
+  });
+
+  // The rail's three seams, built once rather than per render: they close over
+  // nothing but `this`, and the panel re-renders on every keystroke now.
+  #properties = {
+    edit: {
+      touch: (/** @type {string} */ key, /** @type {any} */ value) => this.#touch(key, value),
+      settle: (/** @type {string} */ key, /** @type {any} */ value) => this.#settle(key, value),
+      write: (/** @type {string} */ key, /** @type {any} */ value) => this.#write(key, value),
+    },
+    insertColumn: () => this.#columns((at) => insertColumn(this.#doc, at + 1), 1),
+    removeColumn: () => this.#columns((at) => removeColumn(this.#doc, at), 0),
+    duplicateColumn: () => this.#columns((at) => duplicateColumn(this.#doc, at), 1),
+  };
+
+  #groups = {
+    select: (/** @type {string} */ path) => this.#select(path, null),
+    move: (/** @type {number} */ at, /** @type {number} */ to) =>
+      this.#commit(moveGroup(this.#doc, at, to), null),
+    remove: (/** @type {number} */ at, /** @type {any} */ mode) =>
+      this.#commit(removeGroup(this.#doc, at, mode), null),
+    band: (/** @type {number} */ at, /** @type {any} */ which, /** @type {boolean} */ add) =>
+      this.#band(at, which, add),
+  };
+
+  #faults = { select: (/** @type {string} */ path) => this.#selectProblem(path) };
+
+  // The whole plan/render pipeline: one task, keyed on the host properties
+  // plus the document epoch, coalesced by Lit — validation runs once per
+  // element update cycle, no hand-rolled debounce. Side effects live only in
+  // the callbacks, which the task's call-id guard restricts to the newest
+  // run.
+  #task = new Task(this, {
+    args: () => [this.instance, this.target, this.functions, this.data, this.#epoch],
+    task: async ([instance, target, functions, data], { signal }) => {
+      if (!this.#ready(instance, target)) return this.#idle();
+      let planned = /** @type {any} */ (instance).plan(this.#doc, functions);
+      // A document with problems compiles to nothing; the sheet keeps the
+      // last version that did.
+      let fragment = planned.report ? await planned.report.render(target, data) : null;
+      // The engine takes no signal, so abandonment is the guard around this
+      // body; it only spares the swap when the answer arrives after a
+      // disconnect mid-render.
+      return this.#dropped(signal) ? this.#abandon() : { planned, fragment };
+    },
+    onComplete: (result) => {
+      if (result === null || !this.isConnected) return;
+      this.#problems = result.planned.problems;
+      this.#anchors = result.planned.anchors;
+      if (result.fragment != null) this.#land(result.fragment);
+      this.#placeholders();
+      this.#deliver();
+      this.requestUpdate();
+    },
+    onError: (error) => {
+      if (!this.isConnected) return;
+      this.#announce(error, this.#landed ? "update-render" : "mount-render");
+      this.#deliver();
+    },
+  });
+
+  constructor() {
+    super();
+    // Constructor assignment, never class fields: the source ships verbatim,
+    // so a declared field would shadow the accessor `static properties`
+    // installs and reactivity would go quiet.
+    /** @type {any} */
+    this.schema = undefined;
+    /** @type {any} */
+    this.instance = undefined;
+    /** @type {any} */
+    this.target = undefined;
+    /** @type {Record<string, Function> | undefined} */
+    this.functions = undefined;
+    /** @type {unknown} */
+    this.data = undefined;
+    /** @type {import('./index.d.ts').EditorPage | undefined} */
+    this.page = undefined;
+    /** @type {"light" | "dark" | "auto" | undefined} */
+    this.colorScheme = undefined;
+    // The stage receives keyboard focus on interaction, so the shortcuts are
+    // live exactly while focus is inside the element.
+    this.#stage.element.tabIndex = -1;
+    this.#stage.element.addEventListener("pointerdown", () => this.#stage.element.focus());
+  }
+
+  /**
+   * The newest render settling: `true` when it reached the sheet. Never
+   * rejects — a failed render is handled, on the panel and through the error
+   * event.
+   *
+   * @returns {Promise<boolean>}
+   */
+  get renderComplete() {
+    return this.updateComplete.then(() =>
+      this.#task.status === TaskStatus.INITIAL
+        ? this.#landed
+        : this.#task.taskComplete.then(
+            () => this.#landed,
+            () => false,
+          ),
+    );
+  }
+
+  /** The properties whose validity is re-derived per update cycle. */
+  static #CHECKED = ["instance", "target", "functions", "page", "colorScheme"];
+
+  /** @param {Map<string, unknown>} changed */
+  willUpdate(changed) {
+    let touched = (/** @type {string[]} */ keys) =>
+      !this.hasUpdated || keys.some((key) => changed.has(key));
+    if (touched(["schema"])) this.#adopt();
+    if (touched(QuarioEditor.#CHECKED)) this.#checkOptions(changed);
+  }
+
+  // The breadcrumb is load-bearing, not decoration: clicking a group header in
+  // the preview selects the item inside it, so a container needs another route.
+  #crumbs() {
+    let crumbs = this.#selection ? crumbsOf(this.#doc, this.#selection) : [];
+    return crumbs.map((path, i) =>
+      i === crumbs.length - 1
+        ? html`<code class="qe-crumb qe-here">${path}</code>`
+        : html`<button class="qe-button qe-crumb" @click=${() => this.#select(path, null)}>
+                ${path}</button
+              ><span>›</span>`,
+    );
+  }
+
+  #bar() {
+    return html`<div class="qe-bar">
+      <button
+        class="qe-button"
+        title="Undo"
+        ?disabled=${!this.#history?.canUndo}
+        @click=${() => this.#undo()}
+      >
+        ↩
+      </button>
+      <button
+        class="qe-button"
+        title="Redo"
+        ?disabled=${!this.#history?.canRedo}
+        @click=${() => this.#redo()}
+      >
+        ↪
+      </button>
+      <span class="qe-crumbs">${this.#crumbs()}</span>
+      <button
+        class="qe-button"
+        title="Reveal what the render leaves out"
+        aria-pressed=${this.#revealed ? "true" : "false"}
+        @click=${() => this.#reveal()}
+      >
+        Reveal
+      </button>
+    </div>`;
+  }
+
+  #rail() {
+    return html`<div class="qe-rail">
+      ${propertiesSection(this.#doc, this.#selection, this.#problems, this.#properties)}
+      ${groupsSection(this.#doc, this.#groups)}
+      ${problemsSection(this.#problems, this.#faults)}
+    </div>`;
+  }
+
+  /** Add or remove a group's header or footer band — the explicit verbs the
+   * absent-is-not-empty rule leaves as the only way to move one. */
+  /** @type {(at: number, which: "header" | "footer", add: boolean) => void} */
+  #band(at, which, add) {
+    let next = add ? addGroupBand(this.#doc, at, which) : removeGroupBand(this.#doc, at, which);
+    this.#commit(next, "groups[" + at + "]");
+  }
+
+  render() {
+    let busy = this.#task.status === TaskStatus.PENDING;
+    return html`
+      <div class="qe-editor" aria-busy=${String(busy)}>
+        ${this.#bar()}
+        <div class="qe-body">${this.#panel()} ${this.#stage.element} ${this.#rail()}</div>
+      </div>
+    `;
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+    // Mod+Z / Shift+Mod+Z / Escape, live only while focus is inside the
+    // element; tinykeys' default ignore rule keeps them inert inside text
+    // fields, so the browser's own undo owns typing.
+    this.#unbind ??= tinykeys(this, {
+      "$mod+KeyZ": (event) => {
+        if (this.#typing(event)) return;
+        event.preventDefault();
+        this.#undo();
+      },
+      "$mod+Shift+KeyZ": (event) => {
+        if (this.#typing(event)) return;
+        event.preventDefault();
+        this.#redo();
+      },
+      Escape: () => {
+        if (!this.#stage.cancel() && this.#selection) this.#select(null, null);
+      },
+    });
+    this.#wake();
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    // A pending live edit is deliberately left alone: its pause is an ordinary
+    // timer that keeps running across the disconnect, and removal is not
+    // destruction — the document, history and the edit in flight all persist.
+    this.#task.abort();
+    this.#unbind?.();
+    this.#unbind = undefined;
+  }
+
+  // tinykeys ignores key events retargeted from inputs only when they carry
+  // the elements themselves as targets; composed shadow events retarget to
+  // the host, so the guard re-derives the real target.
+  /** @param {KeyboardEvent} event */
+  #typing(event) {
+    let target = /** @type {any} */ (event.composedPath?.()[0] ?? event.target);
+    return !!target?.closest?.("input, textarea, select, [contenteditable]");
+  }
+
+  #abandon() {
+    this.#stale = true;
+    return null;
+  }
+
+  /**
+   * Whether there is anything to plan: a host mistake fails loudly even with
+   * nothing assigned yet, so a misconfigured host is caught in development.
+   *
+   * @param {unknown} instance
+   * @param {unknown} target
+   */
+  #ready(instance, target) {
+    if (this.#invalid) throw this.#invalid;
+    return instance !== undefined && target !== undefined && this.#doc !== undefined;
+  }
+
+  /** @param {AbortSignal} signal */
+  #dropped(signal) {
+    return signal.aborted && !this.isConnected;
+  }
+
+  /** Nothing to show — and a disconnected element abandons rather than hides. */
+  #idle() {
+    return this.isConnected ? null : this.#abandon();
+  }
+
+  /** A fragment that compiled reaches the sheet, and takes the panel down. */
+  /** @param {string} fragment */
+  #land(fragment) {
+    this.#stage.swap(fragment);
+    this.#landed = true;
+    this.#stale = false;
+    this.#failure = undefined;
+    this.#dismissed = false;
+    this.#checkIdentity();
+    this.#stage.select(this.#selection);
+  }
+
+  #wake() {
+    if (this.#stale || this.#task.status === TaskStatus.PENDING) {
+      this.#epoch++;
+      this.requestUpdate();
+    }
+  }
+
+  /** Only a new schema identity resets; the write-back guard lives here. */
+  #adopt() {
+    let value = checkSchemaSafe(this.schema, (error) => {
+      this.#invalid = error;
+    });
+    if (value === undefined) return;
+    if (value === this.#adopted || value === this.#emitted) return;
+    this.#adopted = value;
+    this.#calm();
+    this.#doc = structuredClone(value);
+    this.#history = history(this.#doc, null);
+    this.#selection = null;
+    this.#problems = [];
+    this.#epoch++;
+  }
+
+  /** @param {Map<string, unknown>} changed */
+  #checkOptions(changed) {
+    let was = this.#invalid;
+    this.#invalid = undefined;
+    /** @type {(run: () => void) => void} */
+    let take = (run) => {
+      try {
+        run();
+      } catch (error) {
+        this.#invalid ??= error;
+      }
+    };
+    take(() => checkInstance(this.instance));
+    take(() => checkTarget(this.target));
+    take(() => checkFunctions(this.functions));
+    take(() => {
+      let box = checkPage(this.page);
+      if (!this.hasUpdated || changed.has("page")) this.#stage.resize(box);
+    });
+    take(() => {
+      let used = checkScheme(this.colorScheme);
+      if (!this.hasUpdated || changed.has("colorScheme")) this.style.colorScheme = used;
+    });
+    if (wording(was) !== wording(this.#invalid)) this.#epoch++;
+  }
+
+  /** One committed gesture, from anywhere but the field being typed into: a
+   * live edit still pending belongs to a gesture of its own and lands first.
+   * An operation that refused — `removeColumn` on the last column — hands
+   * back the document it was given, so nothing happened and the pending edit
+   * stays pending; that is the one case this identity guard still earns, since
+   * `#enter` answers the equal-content question on its own. */
+  /** @type {(next: any, selection: string | null) => void} */
+  #commit(next, selection) {
+    if (next === this.#doc) return;
+    this.#flush();
+    this.#enter(next, selection);
+  }
+
+  /** One history entry, one change event owed — unless the gesture said what
+   * the document already says, which is what a pause followed by a blur says
+   * twice. The working document still moves, so a live edit that wandered
+   * away and came back lands back in step. */
+  /** @type {(next: any, selection: string | null) => void} */
+  #enter(next, selection) {
+    this.#doc = next;
+    this.#selection = selection === undefined ? this.#selection : selection;
+    this.#epoch++;
+    this.requestUpdate();
+    if (same(next, this.#committed)) return;
+    this.#history?.commit(next, this.#selection);
+    this.#owes = true;
+  }
+
+  /** The committed document: the last thing that entered history, which is
+   * where history already keeps it (ADR 0031) — a second copy beside it would
+   * be two places to remember. This is the base every live write derives
+   * from, never the previous live document: `writeField` removes an optional
+   * key on an empty value and re-appends it later, so chaining live writes
+   * would reorder `style` the moment a field is selected-all and retyped. */
+  get #committed() {
+    return this.#history?.current.schema;
+  }
+
+  /** Stop the pause and forget what it was going to commit. */
+  #calm() {
+    if (this.#pending) clearTimeout(this.#pending.timer);
+    this.#pending = undefined;
+  }
+
+  /** The pending live edit becomes its own history entry — because the author
+   * stopped typing, or because something else is about to commit. */
+  #flush() {
+    if (!this.#pending) return;
+    this.#calm();
+    this.#enter(this.#doc, this.#selection);
+  }
+
+  #undo() {
+    // Typing then undoing undoes the typing: the pending edit lands first, so
+    // the step back is over it rather than over the gesture before it.
+    this.#flush();
+    let entry = this.#history?.undo();
+    if (!entry) return;
+    this.#restore(entry);
+  }
+
+  #redo() {
+    // Typing after an undo ends the redo road, as it does in every editor:
+    // the flush commits, and committing is what clears the redo stack.
+    this.#flush();
+    let entry = this.#history?.redo();
+    if (!entry) return;
+    this.#restore(entry);
+  }
+
+  /** @param {{ schema: any, selection: string | null }} entry */
+  #restore(entry) {
+    this.#doc = structuredClone(entry.schema);
+    this.#selection = entry.selection;
+    this.#stage.select(entry.selection);
+    this.#owes = true;
+    this.#epoch++;
+    this.requestUpdate();
+  }
+
+  /** The committed document reaches the host frozen, with its problems. */
+  #deliver() {
+    if (!this.#owes) return;
+    this.#owes = false;
+    let schema = deepFreeze(structuredClone(this.#doc));
+    this.#emitted = schema;
+    this.dispatchEvent(new CustomEvent("change", { detail: { schema, problems: this.#problems } }));
+  }
+
+  /** @type {(path: string | null, el: Element | null) => void} */
+  #select(path, el) {
+    // Selecting elsewhere ends the gesture: the pending edit lands under the
+    // path it was made on, not the one about to replace it. Clicking the
+    // sheet blurs the field and commits it first, but a rail button — a
+    // problem, a group — need not, and on some browsers does not.
+    this.#flush();
+    this.#selection = path;
+    this.#stage.select(path, el ?? null);
+    this.requestUpdate();
+  }
+
+  /** A problem's path selects the nearest selectable node behind it. */
+  /** @type {(path: string) => void} */
+  #selectProblem(path) {
+    let at = this.#selectable(path);
+    if (at) this.#select(at, null);
+  }
+
+  /** Climb a problem's path until it names a node the panel can edit. */
+  /** @type {(path: string) => string | null} */
+  #selectable(path) {
+    let at = path;
+    while (at && !nodeKindAt(this.#doc, at)) at = up(at);
+    return at || null;
+  }
+
+  #reveal() {
+    this.#revealed = !this.#revealed;
+    this.#placeholders();
+    this.requestUpdate();
+  }
+
+  #placeholders() {
+    this.#stage.revealPlaceholders(
+      placeholders(this.#doc ?? {}, this.#stage.rendered()),
+      this.#revealed,
+    );
+  }
+
+  /** Whether the live edit in flight is this very field, so ending its gesture
+   * settles what it already wrote rather than entering that first. */
+  /** @type {(path: string, key: string) => boolean} */
+  #mine(path, key) {
+    return this.#pending?.path === path && this.#pending.key === key;
+  }
+
+  /** A typed control's own gesture ending: a text field blurred or Entered, a
+   * colour picker released, a select changed. When it is the field with a live
+   * edit pending, the `touch`es before it were building toward this and settle
+   * into it; otherwise it is an ordinary commit. */
+  /** @type {(key: string, value: any) => void} */
+  #settle(key, value) {
+    let path = this.#selection;
+    if (!path) return;
+    if (!this.#mine(path, key)) return this.#commit(written(this.#doc, path, key, value), path);
+    // The pending edits were building toward this one, so they settle into it
+    // rather than landing ahead of it — that is what makes a burst one entry.
+    this.#calm();
+    this.#enter(written(this.#committed, path, key, value), path);
+  }
+
+  /** A discrete gesture in one act — a checkbox, an alignment button, an fx
+   * toggle. Always a commit, never a settle, even when it carries the key of
+   * the field being typed into: interrupting typing to press fx must leave the
+   * typing behind as its own entry rather than swallow it. */
+  /** @type {(key: string, value: any) => void} */
+  #write(key, value) {
+    let path = this.#selection;
+    if (!path) return;
+    this.#commit(written(this.#doc, path, key, value), path);
+  }
+
+  /** One live field edit from the panel: the working document follows the
+   * author and the pause will commit it — no history entry, no change event,
+   * since only commits are observable outside the element. Always derived
+   * from the committed document, so the intermediate states of one gesture
+   * never compound. */
+  /** @type {(key: string, value: any) => void} */
+  #touch(key, value) {
+    let path = this.#selection;
+    if (!path) return;
+    this.#calm();
+    this.#doc = written(this.#committed, path, key, value);
+    this.#epoch++;
+    this.#pending = { path, key, timer: setTimeout(() => this.#flush(), PAUSE) };
+    this.requestUpdate();
+  }
+
+  /** Column verbs act on the selected column (or the table's end). */
+  /** @type {(run: (at: number) => any, land: number) => void} */
+  #columns(run, land) {
+    let at = this.#columnAt();
+    let next = run(at);
+    let count = next?.detail?.columns?.length ?? 0;
+    let index = Math.min(at + land, Math.max(count - 1, 0));
+    this.#commit(next, count ? "detail.columns[" + index + "]" : null);
+  }
+
+  /** The column a verb acts on: the selected one, or the table's last. */
+  #columnAt() {
+    let selected = Number(this.#selection?.match(/^detail\.columns\[(\d+)\]$/)?.[1] ?? NaN);
+    return Number.isNaN(selected) ? this.#lastColumn() : selected;
+  }
+
+  #lastColumn() {
+    return (this.#doc?.detail?.columns?.length ?? 1) - 1;
+  }
+
+  /** A fragment with content but no identity cannot be edited by clicking —
+   * a host that passed `html()` without `paths` hears it here, near the
+   * mistake, instead of wondering why selection is dead. */
+  #checkIdentity() {
+    if (this.#stage.identified() || this.#failure || !this.#renders()) return;
+    this.#announce(
+      new TypeError("quario-editor: target: pass html({ paths: true }) so output maps to schema"),
+      "target",
+    );
+  }
+
+  /** Whether the document has anything that should have rendered at all. */
+  #renders() {
+    let filled = (/** @type {string} */ key) => {
+      let value = this.#doc?.[key];
+      return Array.isArray(value) && value.length > 0;
+    };
+    return this.#doc?.detail != null || ["header", "footer", "groups"].some(filled);
+  }
+
+  #dismiss() {
+    this.#dismissed = true;
+    this.requestUpdate();
+  }
+
+  #panel() {
+    if (!this.#failure || this.#dismissed) return nothing;
+    let { label, error } = this.#failure;
+    return html`<div class="qe-panel" role="alert">
+      <strong>${label}</strong>
+      <code>${wording(error)}</code>
+      <button
+        class="qe-button"
+        title="Dismiss"
+        style="margin-left:auto"
+        @click=${() => this.#dismiss()}
+      >
+        ×
+      </button>
+    </div>`;
+  }
+
+  /**
+   * Report one failure: the panel for the author, the event for the host —
+   * once per distinct failure, not once per attempt at it.
+   *
+   * @param {unknown} error
+   * @param {string} kind
+   */
+  #announce(error, kind) {
+    let label = LABELS[kind] ?? kind;
+    if (repeats(this.#failure, label, error)) return;
+    this.#failure = { error, label };
+    this.#dismissed = false;
+    this.requestUpdate();
+    this.dispatchEvent(new CustomEvent("error", { detail: { error, kind } }));
+  }
+}
+
+/** @type {Record<string, string>} */
+let LABELS = {
+  "mount-render": "The report could not be displayed.",
+  "update-render": "The report could not be updated.",
+  target: "The editor cannot map this fragment to the schema.",
+};
+
+/** @type {(value: any, invalid: (error: unknown) => void) => any} */
+let checkSchemaSafe = (value, invalid) => {
+  try {
+    return checkSchema(value);
+  } catch (error) {
+    invalid(error);
+    return undefined;
+  }
+};