qiksy-mcp 1.30.0 → 1.41.0

package/AGENT-GUIDE.md

@@ -44,6 +44,31 @@ instead.
 Need eval? Say so and let the human decide. Everything else that
 looks impossible is a verb below, or a rung on [the ladder](#when-a-control-refuses--the-ladder).
 
+**And three things that used to cost a dozen calls now cost one.**
+
+- **A TABLE INSTEAD OF A PAGE — `qa_collect`.** Name which nodes (a CSS `selector`, a `role`, a
+  fragment of the name, scoped by `within`) and which properties to `take`: `text`, `value`,
+  `name`, `role`, `tag`, `selector`, `href`, `state`, `geometry`, plus `attr:<name>` and
+  `style:<property>`. «Every row with its price», «every input with what it holds» is one answer
+  instead of a snapshot plus a read per element — and `value` is what a control HOLDS, which a
+  snapshot cannot tell you.
+- **SOMETHING HAPPENS LATER — `qa_watch`.** Every other verb answers about NOW, so a toast that
+  appears and leaves, a request fired by a timer, a late row or a live-region announcement are
+  invisible to a snapshot taken before or after them, and polling misses the gaps between looks.
+  Start a watch (`mutations` · `network` · `console` · `announcements`), do the thing, read the
+  buffer. **Every watch expires by itself** — there is no «until stopped», because a watch left
+  running is silent and the readings taken after it are the ones that quietly go wrong.
+- **ASK A REPLY FOR THE FIELDS YOU WANT.** The big reads take `select` (keep these paths) and
+  `omit` (drop these): `qa_snapshot { select: ["nodes[].name", "nodes[].ref"] }`. A path that
+  matches nothing is reported with the names that ARE there, so a mistyped field costs one call
+  rather than a bigger request.
+
+**When the bridge genuinely cannot — `qa_gap`.** One sentence saying what you needed, and it lands
+in a file the human reads. This is the sanctioned way out of a dead end; the unsanctioned one —
+quietly switching to another browser driver — ends the run's meaning, and they find out from the
+results. Use it for a missing capability, never for a control that refused once: that is the
+ladder.
+
 ---
 
 ## Setup, once

package/README.md

@@ -22,7 +22,7 @@ unless the licence (or the 28-day trial) is valid, so once a trial lapses *every
 tool fails — `qa_export` included — with a message saying so. Do not plan a
 free-tier integration around read-only tools.
 
-**npm carries `qiksy-mcp@1.8.0`** — the current build, with all thirty-six tools
+**npm carries `qiksy-mcp@1.41.0`** — the current build, with all sixty-one tools
 including a filterable full-page `qa_snapshot`, `qa_fill_json` (a whole wizard step —
 custom dropdowns, calendars, cascaders, trees, tags and time included — in one call),
 the `qa_pick_*` verbs for the composites, `qa_probe` for the one control that refuses,
@@ -52,7 +52,7 @@ Flags: `--dir <project>`, `--out <path>`, `--no-claude` (print the block instead
 
 ## Tools
 
-Thirty-six in total. **Read** — sense the page (all accept an optional `tabId` from `qa_tabs`; default = the tabs you attached to the agent session, or the active tab if you attached none):
+Fifty-five in total. **Read** — sense the page (all accept an optional `tabId` from `qa_tabs`; default = the tabs you attached to the agent session, or the active tab if you attached none):
 
 | Tool          | What it returns |
 |---------------|-----------------|
@@ -60,8 +60,26 @@ Thirty-six in total. **Read** — sense the page (all accept an optional `tabId`
 | `qa_status`   | URL + error/warning/form counts + isolated-login name. |
 | `qa_findings` | Findings (with selectors + detail); `severity` = `all` \| `error` \| `warning`. |
 | `qa_export`   | The full `qa-export/v1` bundle: findings, failed requests + bodies, form structure, repro steps, env. |
+| `qa_annotate` | **Marks that name an ELEMENT, not a coordinate.** A box, a numbered pin, or an arrow between two controls — placed from the page at capture time, so the same instruction draws the correct picture after a re-render or at another width. `fromFindings` makes the page's own findings draw themselves. A mark whose element is not there is reported, never dropped. |
+| `qa_focus_proof` | **Is focus visible on this control?** Two measurements instead of an argument: which ring-drawing property changed, and what fraction of the PIXELS differ between the two frames. A screenshot of a missing ring looks exactly like one of a faint ring; «0% of the pixels differ» does not. |
+| `qa_wiring`   | **Which error message is attached to which field, and which to nothing.** Proximity on screen is not association; assistive technology reads the attachment. Under-reports on purpose — a message inside its label, or a summary linking to its fields, is correct by another route. |
+| `qa_diff`     | **What changed, by control rather than by pixel.** «The Submit button moved 8px down, padding 8 → 12, and it went disabled» instead of «23 417 pixels differ». Text is not compared: a name or a total differs between two healthy runs, and that noise is why pixel diffing gets switched off. |
+| `qa_failure_gallery` | **How this screen looks when everything goes wrong** — empty, 500 with the server's own words, a held request, 403, a dropped connection — as one self-contained HTML sheet. It CAUSES the failures rather than waiting for them, and always removes the rules afterwards. |
+| `qa_collect`  | **A table instead of a page.** Name which nodes (`selector` / `role` / `nameContains`, scoped by `within`) and which properties to `take` — `text`, `value`, `name`, `role`, `tag`, `selector`, `href`, `state`, `geometry`, plus `attr:<name>` and `style:<property>` — and the answer is that table, once. «Every row with its price», «every input with what it holds» is one call here and a dozen with a snapshot plus a read per element; `value` is what a control HOLDS, which a snapshot cannot tell you. A property nobody can supply is named back rather than dropped. |
+| `qa_watch`    | **Watches for a few seconds** — the one question the other verbs cannot answer. Everything else reports NOW, so a toast that appears and leaves, a request fired by a timer, a late row or a live-region announcement are invisible to a snapshot taken before or after them, and polling misses the gaps between looks. `op:"start"` with `what`: `mutations` \| `network` \| `console` \| `announcements`; then `op:"read"` for the buffer. **Every watch expires by itself** — `ttlMs` is capped at two minutes and there is no «until stopped», because a watch left running is silent and the readings taken after it are the ones that go wrong. Observes only: no consent beyond the bridge. |
+| `qa_gap`      | **What the bridge could not do**, in one sentence, appended to `~/.qiksy/gaps.jsonl`. The sanctioned way out of a dead end — the unsanctioned one is a quiet switch to another browser driver, which has none of your logins and ends the run's meaning. `op:"list"` reads them back. |
 | `qa_snapshot` | A full-page accessibility snapshot — interactive elements + landmarks with their roles, labels and a `ref` you can pass to `qa_click`/`qa_type`/`qa_press` instead of a CSS selector. Read-only. **One snapshot owns its refs**: taking a new one renumbers them, so `e12` from an earlier snapshot may now be a different control and the click will succeed on the wrong thing — keep only the latest snapshot's refs, or target by `name`. **Narrow it** on a component-heavy app: `fields_only` (form controls only), `roles: ["button"]`, `match` on the accessible name, `within: "<selector of a container>"` for one dialog or wizard step, `limit`, `format: "tree"` for about half the bytes. Filtering happens on the way out, so the refs you get back are as valid as the full tree's. |
 
+
+**Asking a reply for the fields you want.** The big reads (`qa_snapshot`, `qa_export`, `qa_findings`,
+`qa_axe`, `qa_run_audit`, and both new verbs) take `select` — keep only these field paths — and
+`omit` — drop these: `qa_snapshot { select: ["nodes[].name", "nodes[].ref"] }`. Dots walk into
+objects, and a path through a list applies to every entry while keeping it a list, so anything you
+already knew about the reply stays true. A path that matches nothing is reported back with the field
+names that *are* there, so a mistyped field costs one call rather than a bigger request. Paths only:
+no expressions and no code — the caller names a field, exactly as every verb here names an element
+rather than a program.
+
 **Command** — drive Qiksy's own UI / analysis (never the app under test; all accept `tabId`):
 
 | Tool            | What it does |

package/diff.mjs

@@ -0,0 +1,73 @@
+// src/content/engine/color.ts
+function canvasNormaliser() {
+  let ctx;
+  return (css) => {
+    if (ctx === void 0) {
+      try {
+        ctx = document.createElement("canvas").getContext("2d");
+      } catch {
+        ctx = null;
+      }
+    }
+    if (!ctx) return null;
+    const read = (seed) => {
+      ctx.fillStyle = seed;
+      ctx.fillStyle = css;
+      return String(ctx.fillStyle);
+    };
+    const fromBlack = read("#000000");
+    const fromWhite = read("#ffffff");
+    return fromBlack === fromWhite ? fromBlack : null;
+  };
+}
+
+// src/content/engine/a11y.ts
+var normalise = canvasNormaliser();
+
+// src/content/page-state.ts
+var MOVE_THRESHOLD = 2;
+function diffStates(before, after) {
+  const bySelector = new Map(before.nodes.map((n) => [n.selector, n]));
+  const byName = new Map(before.nodes.filter((n) => n.name).map((n) => [`${n.role}|${n.name}`, n]));
+  const usedBefore = /* @__PURE__ */ new Set();
+  const changed = [];
+  const appeared = [];
+  let unchanged = 0;
+  for (const now of after.nodes) {
+    const was = bySelector.get(now.selector) ?? (now.name ? byName.get(`${now.role}|${now.name}`) : void 0);
+    if (!was) {
+      appeared.push({ what: now.name || now.role, selector: now.selector });
+      continue;
+    }
+    usedBefore.add(was);
+    const diffs = [];
+    const dx = now.box.x - was.box.x;
+    const dy = now.box.y - was.box.y;
+    if (Math.abs(dx) > MOVE_THRESHOLD || Math.abs(dy) > MOVE_THRESHOLD) {
+      diffs.push(`moved ${dx ? `${dx > 0 ? dx + "px right" : -dx + "px left"}` : ""}${dx && dy ? " and " : ""}${dy ? `${dy > 0 ? dy + "px down" : -dy + "px up"}` : ""}`);
+    }
+    if (Math.abs(now.box.w - was.box.w) > MOVE_THRESHOLD) diffs.push(`width ${was.box.w} \u2192 ${now.box.w}`);
+    if (Math.abs(now.box.h - was.box.h) > MOVE_THRESHOLD) diffs.push(`height ${was.box.h} \u2192 ${now.box.h}`);
+    if (now.state !== was.state) diffs.push(`state "${was.state || "none"}" \u2192 "${now.state || "none"}"`);
+    for (const [k, v] of Object.entries(now.styles)) {
+      if (was.styles[k] !== void 0 && was.styles[k] !== v) diffs.push(`${k} ${was.styles[k]} \u2192 ${v}`);
+    }
+    if (diffs.length) changed.push({ what: now.name || now.role, selector: now.selector, changes: diffs });
+    else unchanged++;
+  }
+  const disappeared = before.nodes.filter((n) => !usedBefore.has(n)).map((n) => ({ what: n.name || n.role, selector: n.selector }));
+  const matched = after.nodes.length - appeared.length;
+  const unmatched = after.nodes.length > 10 && matched < after.nodes.length * 0.4 ? `only ${matched} of ${after.nodes.length} controls could be matched between the two states \u2014 the page is probably re-rendered from scratch (a virtualised list, new React keys). Read the list below as \xABwhat is there now\xBB, not as \xABwhat changed\xBB.` : void 0;
+  return {
+    ok: true,
+    appeared,
+    disappeared,
+    changed,
+    unchanged,
+    ...unmatched ? { unmatched } : {},
+    note: "Text content is deliberately NOT compared: a name, a total or a timestamp differs between two healthy runs, and reporting those is the noise that gets visual diffing switched off. Movements under 2px are the browser rounding a layout, not a change."
+  };
+}
+export {
+  diffStates
+};

package/gallery.mjs

@@ -0,0 +1,141 @@
+/**
+ * HOW THIS SCREEN LOOKS WHEN EVERYTHING GOES WRONG.
+ *
+ * The states nobody designs and nobody screenshots: the empty list, the 500 with the server's own
+ * words in it, the spinner that never ends, the connection that drops mid-submit. A tester does
+ * this by hand before every release — half an hour a screen — and a designer usually has never
+ * seen their own error state at all.
+ *
+ * Three of the six people asked about this independently proposed it, and for the same reason:
+ * every other capture tool can only PHOTOGRAPH a failure that happens to occur. This one can
+ * CAUSE it, because the mocks and the camera are the same product. That is not a feature gap, it
+ * is a category difference — and it costs almost nothing to build, because both halves already
+ * exist and this file is only the recipe that walks them.
+ *
+ * THE ONE RULE THAT MATTERS: every path out of here clears the mocks. A forgotten rule outlives
+ * the reason it was set, and the next thing anybody measures on that tab is a lie they cannot see.
+ * The product already learned this once; a loop that sets rules in sequence is the easiest place
+ * in the whole codebase to forget it, so the clearing is in a `finally` and is also asserted by
+ * the stand.
+ */
+
+/** The failures worth having a picture of, and what each one is FOR. */
+export const STATES = [
+  {
+    key: 'empty',
+    title: 'Empty',
+    why: 'the list came back with nothing in it — the state that is designed last and shipped broken most often',
+    rule: { status: 200, body: '{"data":[],"items":[],"results":[],"total":0}' },
+  },
+  {
+    key: 'server-error',
+    title: 'Server error (500)',
+    why: 'the back end fell over and said why — does the app show its words, or its own guess?',
+    rule: { status: 500, body: '{"error":"upstream timeout","message":"The request could not be completed."}' },
+  },
+  {
+    key: 'forbidden',
+    title: 'Forbidden (403)',
+    why: 'the session is alive but this user may not — the state that usually renders as an empty page with no explanation',
+    rule: { status: 403, body: '{"error":"forbidden","message":"You do not have access to this resource."}' },
+  },
+  {
+    key: 'slow',
+    title: 'Slow (holding for 8s)',
+    why: 'the answer is coming but has not arrived — this is the picture of the loading state, which is otherwise impossible to catch by hand',
+    rule: { status: 200, body: '{"data":[]}', delayMs: 8000 },
+    /* Photographed WHILE it is held, not after: the whole point is the spinner. */
+    shootAfterMs: 2500,
+  },
+  {
+    key: 'dropped',
+    title: 'Connection dropped',
+    why: 'the request failed at the transport level — no status, no body, the case most apps forget entirely',
+    rule: { fail: true },
+  },
+];
+
+export const STATE_KEYS = STATES.map((s) => s.key);
+
+const esc = (s) =>
+  String(s ?? '')
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+
+/**
+ * ONE FILE THAT OPENS IN A BROWSER, and that is deliberate: the person who needs to see this —
+ * a designer, a product owner, a client — does not have the extension and never will. Pictures are
+ * embedded rather than linked, because a folder of files loses its pictures the moment it is
+ * forwarded.
+ */
+export function renderGallery({ url, shots, build, receipt, at }) {
+  const cards = shots
+    .map((s) => {
+      const img = s.dataUri
+        ? `<img src="${s.dataUri}" alt="${esc(s.title)}">`
+        : `<div class="missing">no picture — ${esc(s.error || 'the shot did not come back')}</div>`;
+      return `<figure class="card${s.dataUri ? '' : ' bad'}">
+  <figcaption>
+    <h2>${esc(s.title)}</h2>
+    <p class="why">${esc(s.why)}</p>
+    <p class="rule">answered with: <code>${esc(s.ruleText)}</code></p>
+  </figcaption>
+  ${img}
+</figure>`;
+    })
+    .join('\n');
+
+  const hidden = (receipt?.hidden || []).map((h) => `${esc(h.what)} (${h.count})`).join(' · ') || '—';
+  const notIncluded = (receipt?.notIncluded || []).map((n) => `<li>${esc(n)}</li>`).join('') || '';
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Failure states — ${esc(url)}</title>
+<style>
+  :root { color-scheme: light dark; }
+  body { font: 14px/1.5 -apple-system, Segoe UI, Roboto, sans-serif; margin: 0; padding: 28px 32px 60px; background: #f6f7fb; color: #101828; }
+  h1 { font-size: 19px; margin: 0 0 2px; }
+  .sub { color: #667085; margin: 0 0 6px; }
+  .stamp { color: #667085; font-size: 12px; margin: 0 0 24px; }
+  .stamp code { background: #eceff4; padding: 1px 5px; border-radius: 4px; }
+  .card { margin: 0 0 28px; background: #fff; border: 1px solid #e4e7ec; border-radius: 12px; overflow: hidden; }
+  .card.bad { border-color: #fda29b; }
+  figcaption { padding: 14px 18px; border-bottom: 1px solid #f2f4f7; }
+  h2 { font-size: 15px; margin: 0 0 2px; }
+  .why { margin: 0 0 6px; color: #475467; }
+  .rule { margin: 0; font-size: 12px; color: #667085; }
+  code { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 12px; }
+  img { display: block; width: 100%; height: auto; }
+  .missing { padding: 26px 18px; color: #b42318; }
+  footer { margin-top: 30px; padding-top: 16px; border-top: 1px solid #e4e7ec; color: #667085; font-size: 12px; max-width: 760px; }
+  footer ul { margin: 6px 0 0; padding-left: 18px; }
+  @media (prefers-color-scheme: dark) {
+    body { background: #14161a; color: #e6e8ec; }
+    .card { background: #1b1e24; border-color: #2b2f37; }
+    figcaption { border-color: #2b2f37; }
+    .why { color: #aeb4bf; } .sub, .stamp, footer { color: #98a0ad; }
+    .stamp code { background: #262a31; }
+  }
+</style>
+</head>
+<body>
+  <h1>How this screen looks when things go wrong</h1>
+  <p class="sub">${esc(url)}</p>
+  <p class="stamp">Taken ${esc(at)}${build?.viewport ? ` · window ${build.viewport.w}×${build.viewport.h} at ${build.viewport.dpr}× · ${esc(build.colourScheme)} scheme` : ''}${
+    build?.scripts?.length ? ` · running <code>${esc(build.scripts.slice(0, 3).join(' '))}</code>` : ''
+  }</p>
+  ${cards}
+  <footer>
+    <p><b>Each picture was caused, not waited for.</b> The app was answered from a rule instead of by its server; the rule is printed under every state. The rules were removed when the sheet was finished — a rule left behind would make the next measurement on this tab wrong.</p>
+    <p><b>Covered before every frame:</b> ${hidden}.</p>
+    ${notIncluded ? `<p><b>Not in this file at all:</b></p><ul>${notIncluded}</ul>` : ''}
+    <p>This says what was hidden, not that the file is safe to send — whatever was on screen is in the pictures. Look before you forward it.</p>
+  </footer>
+</body>
+</html>
+`;
+}

package/gaps.mjs

@@ -0,0 +1,87 @@
+/**
+ * WHAT THE BRIDGE COULD NOT DO — written down instead of lost in a transcript.
+ *
+ * Owner, 16.09.2026, asking whether the bridge should become flexible enough to do anything: the
+ * honest answer is that no tool does anything, and the ones that try end up executing whatever
+ * they are handed. What a tool CAN do is say precisely what it could not do, and remember it.
+ *
+ * So this is the other half of flexibility, and the half that survives a Web Store review: the
+ * agent hits a wall, names it in one call, and the wall goes into a file the human reads. The
+ * flexibility then happens where it is safe — in the next version, with a verb that has a name
+ * and a stand — rather than at runtime inside somebody's browser.
+ *
+ * Why a file and not a counter: the interesting part of a gap is the SENTENCE. «qa_read cannot see
+ * inside the iframe on the payment step» is a feature request; «iframe: 7» is a statistic nobody
+ * can act on. One line of JSON per gap, appended, never rewritten — the log is the record, and a
+ * record a process can rewrite is a record it can lose.
+ */
+import { appendFileSync, readFileSync, existsSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+
+export const GAPS_FILE = process.env.QIKSY_GAPS_FILE || join(homedir(), '.qiksy', 'gaps.jsonl');
+
+const clip = (v, n) => (typeof v === 'string' ? v.replace(/\s+/g, ' ').trim().slice(0, n) : undefined);
+
+/**
+ * Record one gap. `at` is passed in rather than read from the clock so the caller owns the
+ * timestamp — and so this file can be tested without one.
+ */
+export function recordGap(entry, at) {
+  const wanted = clip(entry?.wanted, 400);
+  if (!wanted) return { ok: false, error: 'say what you wanted the bridge to do, in one sentence (`wanted`)' };
+  const row = {
+    at: at ?? new Date().toISOString(),
+    wanted,
+    verb: clip(entry?.verb, 60) || null,
+    tried: Array.isArray(entry?.tried) ? entry.tried.slice(0, 8).map((t) => clip(t, 120)).filter(Boolean) : [],
+    /* The address is the difference between a report somebody can reproduce and a wish. Stripped
+       of its query the same way every other artefact here is: a gap report is a document that
+       leaves this machine, and a one-time token in a URL must not ride along. */
+    url: clip(String(entry?.url ?? '').split('?')[0], 200) || null,
+    blocked: entry?.blocked === true,
+  };
+  try {
+    mkdirSync(dirname(GAPS_FILE), { recursive: true });
+    appendFileSync(GAPS_FILE, JSON.stringify(row) + '\n', 'utf8');
+  } catch (e) {
+    return { ok: false, error: `could not write ${GAPS_FILE}: ${String(e?.message || e).slice(0, 120)}` };
+  }
+  return { ok: true, recorded: row, file: GAPS_FILE };
+}
+
+/** Read the log back, newest first. A malformed line is skipped rather than taking the list down. */
+export function listGaps(limit = 50) {
+  if (!existsSync(GAPS_FILE)) return [];
+  let text = '';
+  try {
+    text = readFileSync(GAPS_FILE, 'utf8');
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      out.push(JSON.parse(line));
+    } catch {
+      /* a half-written line from a killed process is not a reason to lose the rest */
+    }
+  }
+  return out.reverse().slice(0, Math.max(1, Math.min(500, limit)));
+}
+
+/**
+ * THE INVITATION THAT RIDES A REFUSAL.
+ *
+ * A verb that says no and nothing else teaches the agent to go round it — usually by switching to
+ * another driver, which is the failure this project spends the most words preventing. The same
+ * refusal carrying «and if the bridge genuinely cannot, say so with qa_gap» turns a dead end into
+ * one call. Rate-limited by the caller: an invitation on every refusal is noise, and noise is how
+ * a good instruction stops being read.
+ */
+export function gapInvite(verb) {
+  return {
+    ifTheBridgeCannot: `If this is not a mistake in the call but something the bridge genuinely cannot do, record it: qa_gap { verb: "${verb}", wanted: "<one sentence>" }. It goes into a file the human reads, and that is how the missing verb gets built.`,
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qiksy-mcp",
-  "version": "1.30.0",
+  "version": "1.41.0",
   "description": "Browser MCP server for the Chrome tab you already have open — your session, your logins. Gives Claude Code, Cursor, Codex and VS Code the live page: findings, forms, failed requests with server bodies.",
   "keywords": [
     "mcp",
@@ -31,6 +31,11 @@
   "files": [
     "server.mjs",
     "widgets.mjs",
+    "project.mjs",
+    "gaps.mjs",
+    "gallery.mjs",
+    "svg-shot.mjs",
+    "diff.mjs",
     "README.md",
     "AGENT-GUIDE.md"
   ],

package/project.mjs

@@ -0,0 +1,158 @@
+/**
+ * ORDERING THE FIELDS OF A REPLY — the cheapest kind of flexibility there is.
+ *
+ * Owner, 16.09.2026: «стоит ли делать мост гибким, чтобы Клод мог структурно его переделывать?»
+ * The answer this file implements is the half of that question which costs nothing and risks
+ * nothing. Almost every «the bridge cannot do this» turns out to be «the verb did not hand back
+ * something it had already measured», or the opposite — it handed back a whole page when three
+ * fields were wanted and the caller paid for the rest in context.
+ *
+ * So a reply can be ASKED FOR: `select` keeps only these paths, `omit` drops these. No new verb,
+ * no new capability, nothing executed — the caller names fields, exactly as every other verb here
+ * names an element rather than a program.
+ *
+ * WHY THIS IS NOT «FLEXIBILITY» IN THE DANGEROUS SENSE. A path is a closed, enumerable thing:
+ * letters, digits, dots, `[]`. It cannot compute, branch or loop, so shipping it is not shipping
+ * an interpreter for somebody else's code — the line the Web Store draws, and the line this
+ * product's whole design follows.
+ */
+
+/** A path is `a.b.c`; `[]` maps over an array: `fields[].name` takes `name` from every entry. */
+const STEP = /^[A-Za-z0-9_$-]+(\[\])?$/;
+
+export function validPath(path) {
+  if (typeof path !== 'string' || !path.length || path.length > 200) return false;
+  return path.split('.').every((s) => STEP.test(s));
+}
+
+const isPlain = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+/**
+ * THE PROJECTION KEEPS THE SHAPE IT PROJECTS.
+ *
+ * The first cut read each path separately and wrote it into a fresh object, which turned
+ * `fields[].name` into `{ fields: { name: [...] } }` — an answer in a shape the original never
+ * had, so anything the caller knew about the reply stopped being true. Paths are folded into one
+ * tree instead and the tree is walked over the value: a list stays a list of the same length, an
+ * object keeps its keys, and only the unasked-for fields go.
+ */
+const LEAF = Symbol('leaf');
+
+function buildTree(paths) {
+  const root = {};
+  for (const path of paths) {
+    let node = root;
+    const steps = path.split('.');
+    steps.forEach((step, i) => {
+      const key = step.endsWith('[]') ? step.slice(0, -2) : step;
+      const last = i === steps.length - 1;
+      if (last) node[key] = LEAF;
+      else {
+        if (node[key] === LEAF || node[key] === undefined) node[key] = {};
+        node = node[key];
+      }
+    });
+  }
+  return root;
+}
+
+/** Walk a value through the tree. Returns `undefined` when nothing on this branch was there. */
+function applyTree(value, node, hit) {
+  if (node === LEAF) {
+    if (value !== undefined) hit.any = true;
+    return value;
+  }
+  if (value == null) return undefined;
+  if (Array.isArray(value)) {
+    /* A list stays a list — and an entry that held none of the asked-for fields is dropped rather
+       than left as an empty object, so `fields[].name` over a mixed list answers with the ones
+       that have a name and not with a row of blanks. */
+    const out = value.map((v) => applyTree(v, node, hit)).filter((v) => v !== undefined);
+    return out.length ? out : undefined;
+  }
+  if (!isPlain(value)) return undefined;
+  const out = {};
+  let got = false;
+  for (const [key, child] of Object.entries(node)) {
+    const sub = applyTree(value[key], child, hit);
+    if (sub !== undefined) {
+      out[key] = sub;
+      got = true;
+    }
+  }
+  return got ? out : undefined;
+}
+
+/**
+ * Keep only the named paths. A path that matches nothing is REPORTED rather than dropped in
+ * silence: an agent that mistyped a field name and got `{}` back learns nothing, and the next
+ * thing it does is call again with a bigger request.
+ */
+export function pickPaths(value, paths) {
+  const bad = paths.filter((p) => !validPath(p));
+  if (bad.length) return { ok: false, error: `not a field path: ${bad.slice(0, 4).join(', ')}` };
+  if (value == null || typeof value !== 'object') return { ok: true, value, missed: [] };
+  /* Each path is tried on its own FIRST, only to find out which ones matched nothing; the answer
+     itself is then built in one walk so its shape survives. */
+  const missed = [];
+  for (const path of paths) {
+    const hit = { any: false };
+    applyTree(value, buildTree([path]), hit);
+    if (!hit.any) missed.push(path);
+  }
+  const out = applyTree(value, buildTree(paths), { any: false });
+  return { ok: true, value: out === undefined ? {} : out, missed };
+}
+
+/** Drop the named paths, keeping everything else. */
+export function omitPaths(value, paths) {
+  const bad = paths.filter((p) => !validPath(p));
+  if (bad.length) return { ok: false, error: `not a field path: ${bad.slice(0, 4).join(', ')}` };
+  const strip = (v, steps) => {
+    if (Array.isArray(v)) return v.map((x) => strip(x, steps));
+    if (!isPlain(v)) return v;
+    const [head, ...rest] = steps;
+    const key = head.endsWith('[]') ? head.slice(0, -2) : head;
+    if (!(key in v)) return v;
+    const copy = { ...v };
+    if (!rest.length) delete copy[key];
+    else copy[key] = strip(copy[key], rest);
+    return copy;
+  };
+  let out = value;
+  for (const path of paths) out = strip(out, path.split('.'));
+  return { ok: true, value: out };
+}
+
+/**
+ * The one entry point the verbs use. Returns the reply as asked for, plus a `projected` line
+ * saying what was done — a reply that has been trimmed and does not say so is a reply nobody can
+ * reason about later, and this project has paid for that mistake in other places already.
+ */
+export function project(value, { select, omit } = {}) {
+  const sel = Array.isArray(select) ? select.filter(Boolean).map(String) : null;
+  const omt = Array.isArray(omit) ? omit.filter(Boolean).map(String) : null;
+  if (!sel?.length && !omt?.length) return value;
+  if (value == null || typeof value !== 'object') return value;
+
+  let out = value;
+  const note = {};
+  if (omt?.length) {
+    const r = omitPaths(out, omt);
+    if (!r.ok) return { ...value, projectionError: r.error };
+    out = r.value;
+    note.omitted = omt;
+  }
+  if (sel?.length) {
+    const r = pickPaths(out, sel);
+    if (!r.ok) return { ...value, projectionError: r.error };
+    out = r.value;
+    note.selected = sel;
+    if (r.missed.length) {
+      note.notThere = r.missed;
+      /* The fields that ARE there, so a mistyped name is one call from being right. */
+      note.available = Object.keys(isPlain(value) ? value : {}).slice(0, 30);
+    }
+  }
+  return { ...out, projected: note };
+}