@bongos/core 1.19.491 → 1.19.493

package/scripts/gds/copy-apply.js

@@ -0,0 +1,338 @@
+#!/usr/bin/env node
+'use strict';
+//
+// scripts/gds/copy-apply.js — land a copy proposal as a real diff (R03 of goal
+// 1000074, the artist's loop; task 1003114).
+//
+// WHAT IT IS FOR. R03's done-when is that "an artist with no terminal can propose
+// a copy change that reaches main through a claim". The copy desk gives them the
+// first half: a proposal becomes a GDS task carrying a patch
+// (modules/copy-desk/proposals.js). This command is the second half — the thing
+// whoever claims that task runs. It is the direct analogue of `adapter.export()`
+// in the design half (ADR 0081, modules/ui-design/adapters/*): tool output lands
+// in the repo as a committed diff under a claim, with a path guard, and the repo
+// stays the source of truth. Nothing about the copy path bypasses the ledger,
+// because this command IS the ledger's hands.
+//
+// WHY IT RE-DERIVES INSTEAD OF TRUSTING THE PATCH. The patch names a file and a
+// line, but a line number is stale the moment anything above it changes, and the
+// registry's committed rows deliberately carry no character offsets (see the
+// note in copy-inventory.js's buildRegistry). So this re-runs R01's OWN
+// extractor over the working tree and finds the occurrence there. One set of
+// matching rules, in one file, used by both the inventory and the applier —
+// which is what stops this command from editing a byte the inventory would never
+// have called copy.
+//
+// THE REFUSALS ARE THE FEATURE. A copy change that lands on the wrong characters
+// is worse than one that does not land, so every ambiguity is a named refusal
+// with the reason on one line: the string is gone, it moved and is no longer
+// unique, its literal is escaped so no exact span exists, the placeholder
+// arithmetic does not hold, or the file is outside a registry surface. None of
+// them means the wording was wrong — they mean a person should look.
+//
+// Run:  node scripts/gds/copy-apply.js                    (the task you are HOLDING — the normal call)
+//       node scripts/gds/copy-apply.js --dry-run          (say what would change, write nothing)
+//       node scripts/gds/copy-apply.js --task 1234        (a named task, when you hold more than one)
+//       node scripts/gds/copy-apply.js --patch-file p.json  (a local patch — used by the tests)
+//
+// WHY THE BARE FORM DEFAULTS TO YOUR CLAIM rather than taking an id. The task a
+// proposal creates has to print the exact line that lands it, and it cannot know
+// its own id at the moment its description is written. Every workaround for that
+// is worse than the rule it would paper over: this command may only be run under
+// a claim (that is the whole point of the feature), and a claim already names a
+// task. So the bare call reads the claim, and holding no claim is a refusal that
+// says to go and claim the task — the methodology's own rule, enforced by the
+// command instead of restated in its output.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const ci = require('./copy-inventory.js');
+const proposals = require('../../modules/copy-desk/proposals.js');
+const { apiCall, arg, hasFlag, cliExit } = require('./cli-lib.js');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const PLACEHOLDER = proposals.PLACEHOLDER;
+
+// ---------------------------------------------------------------------------
+// PURE below this line, down to `main`. The tests drive these directly with
+// string sources — no fs, no network, no task.
+// ---------------------------------------------------------------------------
+
+// THE PATH GUARD, and it is the same rule the design adapter enforces: an export
+// may only write inside the surfaces the contract knows about. Here the surface
+// roots come from R01's own SURFACES table, so a patch can only ever touch a
+// directory the inventory actually walks. A patch naming anything else — a
+// traversal, a config file, a migration — is refused before a single byte is
+// read, not after.
+function surfaceRootFor(surfaceId) {
+  const surface = ci.SURFACES.find((s) => s.id === surfaceId);
+  return surface ? surface.at : null;
+}
+
+function checkPatchPath(patch) {
+  const root = surfaceRootFor(patch.surface);
+  if (!root) return { ok: false, code: 'unknown_surface', detail: { surface: patch.surface, known: ci.SURFACES.map((s) => s.id) } };
+  // Compare normalized, repo-relative, forward-slash paths — the same form the
+  // registry stores — and require the file to sit under its surface's root.
+  const rel = String(patch.file).replace(/\\/g, '/');
+  const abs = path.resolve(REPO_ROOT, rel);
+  const rootAbs = path.resolve(REPO_ROOT, root);
+  if (!abs.startsWith(rootAbs + path.sep)) {
+    return {
+      ok: false,
+      code: 'path_outside_surface',
+      detail: { file: rel, surface: patch.surface, must_be_under: root },
+    };
+  }
+  return { ok: true, rel, abs };
+}
+
+// Find the one occurrence this patch is about, in the tree as it stands now.
+//
+// Matching is on (origin, current text) within the file, NOT on the line: a line
+// number is the first thing to go stale, and the registry id is explicitly
+// designed to survive a string moving. The line is used only to disambiguate
+// when the same sentence appears at several sites in one file — which is the
+// duplicate case R01 already reports, and where guessing would be indefensible.
+function locateOccurrence(source, rel, patch) {
+  const rows = (path.extname(rel) === '.html'
+    ? ci.fromHtml({ source, rel })
+    : ci.fromJs({ source, rel }))
+    .filter((r) => r.origin === patch.origin && r.text === patch.current);
+
+  if (!rows.length) {
+    return {
+      ok: false,
+      code: 'target_gone',
+      detail: {
+        file: rel,
+        looked_for: patch.current,
+        what_this_means: 'That exact wording is no longer in this file — it has already been edited, or the proposal was written against an older tree. Nothing was changed. Re-read the string on the copy desk and propose again if it still needs work.',
+      },
+    };
+  }
+  let row = rows[0];
+  if (rows.length > 1) {
+    const onLine = rows.filter((r) => r.line === patch.line);
+    if (onLine.length !== 1) {
+      return {
+        ok: false,
+        code: 'ambiguous_target',
+        detail: {
+          file: rel,
+          occurrences: rows.length,
+          lines: rows.map((r) => r.line),
+          what_this_means: 'This sentence appears more than once in this file and the proposal cannot say which one it meant. That is the duplicate case the copy desk reports — decide whether they should all change, and land it as an ordinary edit under this claim.',
+        },
+      };
+    }
+    row = onLine[0];
+  }
+  if (row.start === undefined) {
+    return {
+      ok: false,
+      code: 'no_exact_span',
+      detail: {
+        file: rel,
+        line: row.line,
+        what_this_means: 'This string lives inside an escaped quoted literal, so the inventory cannot point at its exact characters and this command will not guess. Edit it by hand under this claim.',
+      },
+    };
+  }
+  return { ok: true, row };
+}
+
+// Rebuild the replacement text, re-injecting the source's own interpolations.
+//
+// The registry writes `{…}` where the source has `${expr}`, so the artist edits a
+// readable sentence with holes in it. Landing it means putting the ORIGINAL
+// expressions back, in order — the k-th hole takes the k-th expression. The
+// count was already checked when the proposal was made; it is checked again here
+// against the real source, because the source is what is about to be written.
+function reinjectInterpolations(rawSpan, proposedText) {
+  const expressions = String(rawSpan).match(/\$\{[^{}]*\}/g) || [];
+  const holes = proposals.placeholderCount(proposedText);
+  if (holes !== expressions.length) {
+    return {
+      ok: false,
+      code: 'placeholder_mismatch',
+      detail: {
+        expected: expressions.length,
+        got: holes,
+        placeholder: PLACEHOLDER,
+        what_this_means: 'The values this sentence drops in at render time do not line up with the proposed wording. Nothing was changed.',
+      },
+    };
+  }
+  let out = '';
+  let rest = String(proposedText);
+  for (const expr of expressions) {
+    const at = rest.indexOf(PLACEHOLDER);
+    out += rest.slice(0, at) + expr;
+    rest = rest.slice(at + PLACEHOLDER.length);
+  }
+  return { ok: true, text: out + rest };
+}
+
+// The whole edit, as a pure function of the file's current contents and a patch.
+// Returns the new source — or a named refusal. Writes nothing.
+function applyPatchToSource(source, rel, patch) {
+  const located = locateOccurrence(source, rel, patch);
+  if (!located.ok) return located;
+  const { row } = located;
+  const rawSpan = source.slice(row.start, row.end);
+  const rebuilt = reinjectInterpolations(rawSpan, patch.proposed);
+  if (!rebuilt.ok) return rebuilt;
+  return {
+    ok: true,
+    line: row.line,
+    before: rawSpan,
+    after: rebuilt.text,
+    source: source.slice(0, row.start) + rebuilt.text + source.slice(row.end),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The command.
+// ---------------------------------------------------------------------------
+
+function refuse(result) {
+  const detail = result.detail || {};
+  console.error(`copy-apply: REFUSED (${result.code})`);
+  if (detail.what_this_means) console.error(`  ${detail.what_this_means}`);
+  for (const [k, v] of Object.entries(detail)) {
+    if (k === 'what_this_means') continue;
+    console.error(`  ${k}: ${typeof v === 'object' ? JSON.stringify(v) : v}`);
+  }
+  return 2;
+}
+
+// The task this session is holding. Returns a named refusal rather than an id
+// when there is nothing to act under — "claim it first" is the correct answer,
+// not an inconvenience to route around.
+async function claimedTaskId() {
+  const me = await apiCall('GET', '/api/gds/me');
+  if (!me.ok) return { ok: false, code: 'no_session', detail: { status: me.status, run: 'node scripts/gds/setup.js' } };
+  const claims = me.data.active_claims || (me.data.active_claim ? [me.data.active_claim] : []);
+  if (!claims.length) {
+    return {
+      ok: false,
+      code: 'no_active_claim',
+      detail: {
+        what_this_means: 'A copy change lands under a claim like every other change. Claim the proposal task first (node scripts/gds/claim.js <id>), then run this again — or name one with --task <id>.',
+      },
+    };
+  }
+  if (claims.length > 1) {
+    return {
+      ok: false,
+      code: 'several_active_claims',
+      detail: {
+        held: claims.map((c) => c.task_id),
+        what_this_means: 'You hold more than one claim, so this command will not guess which proposal you meant. Name it with --task <id>.',
+      },
+    };
+  }
+  return { ok: true, taskId: claims[0].task_id };
+}
+
+async function loadPatch({ taskId, patchFile }) {
+  if (patchFile) {
+    let raw;
+    try {
+      raw = fs.readFileSync(path.resolve(process.cwd(), patchFile), 'utf8');
+    } catch (err) {
+      return { ok: false, code: 'patch_file_unreadable', detail: { reason: err.message } };
+    }
+    // A bare patch file is still parsed through the SAME reader the task path
+    // uses, so the local shortcut can never accept a shape the real path rejects.
+    return proposals.parseProposalBlock(raw.trim().startsWith('{')
+      ? ['```' + proposals.FENCE, raw.trim(), '```'].join('\n')
+      : raw);
+  }
+  const res = await apiCall('GET', `/api/gds/tasks/${taskId}`);
+  if (!res.ok) {
+    return { ok: false, code: 'task_unreadable', detail: { task: taskId, status: res.status } };
+  }
+  const task = (res.data && res.data.task) || {};
+  const parsed = proposals.parseProposalBlock(task.description || '');
+  if (!parsed.ok) return parsed;
+  return { ok: true, patch: parsed.patch, task };
+}
+
+async function main() {
+  let taskId = arg('--task');
+  const patchFile = arg('--patch-file');
+  const dryRun = hasFlag('--dry-run');
+
+  if (!taskId && !patchFile) {
+    const held = await claimedTaskId();
+    if (!held.ok) return cliExit(refuse(held));
+    taskId = held.taskId;
+    console.log(`copy-apply: the task you are holding — #${taskId}`);
+  }
+
+  const loaded = await loadPatch({ taskId, patchFile });
+  if (!loaded.ok) return cliExit(refuse(loaded));
+  const { patch } = loaded;
+
+  const guard = checkPatchPath(patch);
+  if (!guard.ok) return cliExit(refuse(guard));
+
+  let source;
+  try {
+    source = fs.readFileSync(guard.abs, 'utf8');
+  } catch (err) {
+    return cliExit(refuse({ code: 'file_unreadable', detail: { file: guard.rel, reason: err.message } }));
+  }
+
+  const applied = applyPatchToSource(source, guard.rel, patch);
+  if (!applied.ok) return cliExit(refuse(applied));
+
+  console.log(`copy-apply: ${guard.rel}:${applied.line} (${patch.origin})`);
+  console.log(`  -  ${applied.before}`);
+  console.log(`  +  ${applied.after}`);
+
+  if (dryRun) {
+    console.log('copy-apply: --dry-run, nothing written.');
+    return cliExit(0);
+  }
+
+  fs.writeFileSync(guard.abs, applied.source);
+
+  // Regenerate the inventory in the same breath. The registry is a committed
+  // artifact whose CI check fails on drift, so an applier that edited a surface
+  // and left the registry describing the old tree would hand the builder a
+  // red build and a puzzle. It also gives us the verification below.
+  const { reg } = ci.write();
+
+  // VERIFY OUR OWN WORK, because a copy change that lands on the wrong characters
+  // is the failure this whole command is shaped to avoid — and the registry we
+  // just rebuilt is an independent read of the file we just wrote.
+  const nowThere = reg.entries.some((e) => e.file === guard.rel && e.text === patch.proposed);
+  if (!nowThere) {
+    console.error('copy-apply: WROTE THE FILE, but the regenerated registry does not contain the new wording at that path.');
+    console.error('  The edit landed somewhere the inventory does not read as copy. Review `git diff` before doing anything else.');
+    return cliExit(3);
+  }
+
+  console.log(`copy-apply: applied, registry regenerated (${reg.counts.strings} strings).`);
+  console.log('  Review with `git diff`, then ship this task the normal way.');
+  return cliExit(0);
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    console.error(`copy-apply: ${err && err.message ? err.message : err}`);
+    process.exitCode = 1;
+  });
+}
+
+module.exports = {
+  surfaceRootFor,
+  checkPatchPath,
+  locateOccurrence,
+  reinjectInterpolations,
+  applyPatchToSource,
+};

package/scripts/gds/copy-inventory.js

@@ -132,6 +132,28 @@ function looksLikeCopy(raw) {
   return true;
 }
 
+// THE SPAN: where a row's text physically SITS in the file, as [start, end)
+// character offsets. Every extractor below records one alongside the text.
+//
+// It is deliberately NOT part of the committed registry — buildRegistry drops it
+// (see the note there). A committed offset would go stale on the next edit to an
+// unrelated line of the same file, and the registry's whole point is an id that
+// survives movement. The span is a LIVE fact, recomputed from the tree by whoever
+// needs it: today that is scripts/gds/copy-apply.js (R03 of goal 1000074), which
+// re-runs this extractor against the working tree and uses the span to replace
+// exactly the characters a string occupies and nothing else. Deriving it here,
+// beside the regex that captured the text, is what keeps the applier from owning
+// a second, drifting copy of these matching rules.
+//
+// The span covers the TRIMMED text — a row's `text` is whitespace-collapsed and
+// trimmed, so the indentation around a multi-line literal belongs to the file's
+// formatting, not to the copy, and an applier must leave it alone.
+function trimmedSpan(group, groupStart) {
+  const lead = group.length - group.replace(/^\s+/, '').length;
+  const trail = group.length - group.replace(/\s+$/, '').length;
+  return { start: groupStart + lead, end: groupStart + group.length - trail };
+}
+
 // Strip <script>/<style> bodies so their contents are not read as page text.
 // Replaced with spaces of equal length so every line number stays truthful.
 function stripEmbedded(html) {
@@ -151,7 +173,8 @@ function fromHtml({ source, rel }) {
   const textRe = />([^<>]+)</g;
   while ((m = textRe.exec(cleaned)) !== null) {
     if (!looksLikeCopy(m[1])) continue;
-    out.push({ text: m[1].replace(/\s+/g, ' ').trim(), file: rel, line: lineAt(starts, m.index), origin: 'html-text', confidence: 'certain' });
+    // The captured group opens one character past the '>' that anchored the match.
+    out.push({ text: m[1].replace(/\s+/g, ' ').trim(), file: rel, line: lineAt(starts, m.index), origin: 'html-text', confidence: 'certain', ...trimmedSpan(m[1], m.index + 1) });
   }
 
   // 2. copy-bearing attributes.
@@ -159,14 +182,19 @@ function fromHtml({ source, rel }) {
     re.lastIndex = 0;
     while ((m = re.exec(cleaned)) !== null) {
       if (!looksLikeCopy(m[1])) continue;
-      out.push({ text: m[1].replace(/\s+/g, ' ').trim(), file: rel, line: lineAt(starts, m.index), origin: `html-attr:${attr}`, confidence: 'certain' });
+      // Every COPY_ATTR_RE ends with the closing quote, so the group's last
+      // character sits exactly one before the match's end. DERIVED, never
+      // searched for — indexOf would land on an earlier copy of the same text.
+      const attrStart = m.index + m[0].length - 1 - m[1].length;
+      out.push({ text: m[1].replace(/\s+/g, ' ').trim(), file: rel, line: lineAt(starts, m.index), origin: `html-attr:${attr}`, confidence: 'certain', ...trimmedSpan(m[1], attrStart) });
     }
   }
 
   // 3. <title> is the page's own name — always copy.
   const titleRe = /<title>([^<]{2,200})<\/title>/gi;
   while ((m = titleRe.exec(source)) !== null) {
-    out.push({ text: m[1].replace(/\s+/g, ' ').trim(), file: rel, line: lineAt(starts, m.index), origin: 'html-title', confidence: 'certain' });
+    const titleStart = m.index + '<title>'.length;
+    out.push({ text: m[1].replace(/\s+/g, ' ').trim(), file: rel, line: lineAt(starts, m.index), origin: 'html-title', confidence: 'certain', ...trimmedSpan(m[1], titleStart) });
   }
   return out;
 }
@@ -198,24 +226,75 @@ function unescapeLiteral(raw) {
   return String(raw).replace(/\\(['"`\\])/g, '$1');
 }
 
-// A literal that carries markup: extract what a person reads out of it.
+// Can offsets into this match's BODY be read as offsets into the file?
+//
+// A template literal (group 1) is used raw, so yes. A quoted literal is
+// `unescapeLiteral`d first, and that SHIFTS every character after a backslash —
+// so yes only when the unescape changed nothing. The alternative, an
+// escape-aware index map, would buy spans for a handful of quoted-markup rows
+// and add a second place for the escaping rules to be wrong. A row with no span
+// is refused BY NAME in copy-apply.js instead, which is the honest trade.
+function literalIsUnshifted(m) {
+  if (m[1] !== undefined) return true;
+  const raw = m[2] ?? m[3];
+  return raw === undefined ? false : unescapeLiteral(raw) === raw;
+}
+
+// Interpolations are replaced by a fixed-width PLACEHOLDER before matching, so a
+// position in the holed string is NOT a position in the source. This records the
+// literal runs between the holes so one can be converted back to the other —
+// which is what lets a markup row carry a source span (see `trimmedSpan`).
+//
+// The conversion is only ever asked for at a capture BOUNDARY, and every boundary
+// sits on a real character: a text node's group opens just past a '>' and closes
+// just before a '<', and neither can appear inside `{…}`. A boundary that lands
+// where a hole meets the next run resolves to the character after the closing
+// '}' of the interpolation, which is the right place to cut.
+function holeMap(body) {
+  const re = /\$\{[^{}]*\}/g;
+  const runs = [];
+  let withHoles = '';
+  let last = 0;
+  let m;
+  while ((m = re.exec(body)) !== null) {
+    const literal = body.slice(last, m.index);
+    runs.push({ holed: withHoles.length, raw: last, length: literal.length });
+    withHoles += literal + PLACEHOLDER;
+    last = m.index + m[0].length;
+  }
+  const tail = body.slice(last);
+  runs.push({ holed: withHoles.length, raw: last, length: tail.length });
+  return { withHoles: withHoles + tail, runs };
+}
+
+function holedToRaw(runs, at) {
+  for (const run of runs) {
+    if (at >= run.holed && at <= run.holed + run.length) return run.raw + (at - run.holed);
+  }
+  return null; // only reachable for a position strictly inside a placeholder
+}
+
+// A literal that carries markup: extract what a person reads out of it, each row
+// carrying [start, end) offsets into the RAW body it was found in.
 function copyFromMarkupLiteral(body) {
-  const withHoles = body.replace(/\$\{[^{}]*\}/g, PLACEHOLDER);
+  const { withHoles, runs } = holeMap(body);
   const out = [];
+  const emit = (group, groupStart) => {
+    const t = group.replace(/\s+/g, ' ').trim();
+    if (t === PLACEHOLDER || !looksLikeCopy(t.replace(/\{…\}/g, 'x'))) return;
+    const span = trimmedSpan(group, groupStart);
+    const start = holedToRaw(runs, span.start);
+    const end = holedToRaw(runs, span.end);
+    // A span that cannot be mapped back is reported as text with no span rather
+    // than as a guess; the applier refuses such a row by name.
+    out.push(start === null || end === null ? { text: t } : { text: t, start, end });
+  };
   let m;
   const textRe = />([^<>]+)</g;
-  while ((m = textRe.exec(withHoles)) !== null) {
-    const t = m[1].replace(/\s+/g, ' ').trim();
-    if (t === PLACEHOLDER || !looksLikeCopy(t.replace(/\{…\}/g, 'x'))) continue;
-    out.push(t);
-  }
+  while ((m = textRe.exec(withHoles)) !== null) emit(m[1], m.index + 1);
   for (const { re } of COPY_ATTR_RES) {
     re.lastIndex = 0;
-    while ((m = re.exec(withHoles)) !== null) {
-      const t = m[1].replace(/\s+/g, ' ').trim();
-      if (!looksLikeCopy(t.replace(/\{…\}/g, 'x'))) continue;
-      out.push(t);
-    }
+    while ((m = re.exec(withHoles)) !== null) emit(m[1], m.index + m[0].length - 1 - m[1].length);
   }
   return out;
 }
@@ -224,12 +303,12 @@ function fromJs({ source, rel }) {
   const out = [];
   const starts = lineIndex(source);
   const seen = new Set(); // (text, line) — one row per string per site
-  const push = (text, index, origin) => {
+  const push = (text, index, origin, span = null) => {
     const line = lineAt(starts, index);
     const key = `${text}\u0000${line}\u0000${origin}`;
     if (seen.has(key)) return;
     seen.add(key);
-    out.push({ text, file: rel, line, origin, confidence: 'certain' });
+    out.push({ text, file: rel, line, origin, confidence: 'certain', ...(span || {}) });
   };
 
   let m;
@@ -238,19 +317,31 @@ function fromJs({ source, rel }) {
   while ((m = JS_LITERALS.exec(source)) !== null) {
     const body = m[1] ?? unescapeLiteral(m[2] ?? m[3] ?? '');
     if (!body || !/<[a-zA-Z/]/.test(body) || !/>/.test(body)) continue;
-    for (const t of copyFromMarkupLiteral(body)) push(t, m.index, 'js-markup');
-  }
-  // 2. strings shown directly to a person.
-  UI_CALL.lastIndex = 0;
-  while ((m = UI_CALL.exec(source)) !== null) {
-    const body = (m[1] ?? unescapeLiteral(m[2] ?? m[3] ?? '')).replace(/\$\{[^{}]*\}/g, PLACEHOLDER).replace(/\s+/g, ' ').trim();
-    if (body && looksLikeCopy(body.replace(/\{…\}/g, 'x'))) push(body, m.index, 'js-notice');
-  }
-  TEXT_ASSIGN.lastIndex = 0;
-  while ((m = TEXT_ASSIGN.exec(source)) !== null) {
-    const body = (m[1] ?? unescapeLiteral(m[2] ?? m[3] ?? '')).replace(/\$\{[^{}]*\}/g, PLACEHOLDER).replace(/\s+/g, ' ').trim();
-    if (body && looksLikeCopy(body.replace(/\{…\}/g, 'x'))) push(body, m.index, 'js-text-assign');
+    // Each alternative opens with exactly one delimiter, so the body starts one
+    // character past the match.
+    const mapped = literalIsUnshifted(m);
+    for (const f of copyFromMarkupLiteral(body)) {
+      const span = mapped && f.start !== undefined
+        ? { start: m.index + 1 + f.start, end: m.index + 1 + f.end }
+        : null;
+      push(f.text, m.index, 'js-markup', span);
+    }
   }
+  // 2. strings shown directly to a person. Both of these normalize the WHOLE
+  // literal into the row's text, so the span is the whole body: the delimiter
+  // closes the match, so the body ends one character before the match does.
+  const wholeLiteral = (re, origin) => {
+    re.lastIndex = 0;
+    while ((m = re.exec(source)) !== null) {
+      const rawBody = m[1] ?? m[2] ?? m[3] ?? '';
+      const body = (m[1] ?? unescapeLiteral(m[2] ?? m[3] ?? '')).replace(/\$\{[^{}]*\}/g, PLACEHOLDER).replace(/\s+/g, ' ').trim();
+      if (!body || !looksLikeCopy(body.replace(/\{…\}/g, 'x'))) continue;
+      const bodyStart = m.index + m[0].length - 1 - rawBody.length;
+      push(body, m.index, origin, literalIsUnshifted(m) ? trimmedSpan(rawBody, bodyStart) : null);
+    }
+  };
+  wholeLiteral(UI_CALL, 'js-notice');
+  wholeLiteral(TEXT_ASSIGN, 'js-text-assign');
   return out;
 }
 
@@ -276,7 +367,14 @@ function buildRegistry() {
         ? fromHtml({ source, rel })
         : fromJs({ source, rel });
       for (const f of found) {
-        entries.push({ id: stableId(surface.id, f.text), surface: surface.id, ...f });
+        // THE SPAN IS DROPPED HERE, DELIBERATELY. Every extractor records where a
+        // string physically sits (see `trimmedSpan`), and none of it is committed:
+        // an offset goes stale the moment anything above it in the file changes,
+        // so a registry carrying one would be wrong far more often than the id —
+        // which is designed to survive exactly that movement — ever is. The span
+        // is recomputed from the tree by the applier, at the moment it edits.
+        const { start, end, ...row } = f;
+        entries.push({ id: stableId(surface.id, f.text), surface: surface.id, ...row });
         count += 1;
       }
     }

package/src/module-api.js

@@ -45,7 +45,7 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.491'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.493'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/hall_collab_world.mjs

@@ -158,13 +158,32 @@ test('the filters and the search are the kit\'s bar; the duplicates are paged th
   assert.match(read('copy-desk.html'), /src="\/builders\/hall-kit\.js/, 'the page loads the kit');
 });
 
-test('the two dialogs are the family modal on a native <dialog>, with the number input in a field', () => {
+test('the three dialogs are the family modal on a native <dialog>, with the number input in a field', () => {
   const html = read('copy-desk.html');
-  assert.equal((html.match(/<dialog id="cd-(close-)?dialog" class="ov-modal cd-dialog">/g) || []).length, 2);
+  // Three since task 1003114 (R03): flag, close, and the proposal composer.
+  assert.equal((html.match(/<dialog id="cd-(close-dialog|dialog|propose-dialog)" class="ov-modal cd-dialog">/g) || []).length, 3);
   assert.match(html, /<div class="ov-field ov-field--wide">\s*<label class="ov-field__l" for="cd-close-task">[^<]*<\/label>\s*<input type="number" id="cd-close-task"/, 'the number input sits in the family field, which restates the 30px pill');
   assert.ok(!/<label[^>]*>[^<]*<span class="cd-dialog__hint"/.test(html), 'no hint lives inside a label (the label voice would uppercase it)');
-  assert.equal((html.match(/class="ov-form__why"/g) || []).length, 3, 'the three hints are the form\'s own explainer line');
+  assert.equal((html.match(/class="ov-form__why"/g) || []).length, 4, 'the four hints are the form\'s own explainer line');
   assert.match(html, /class="btn-accent" id="cd-submit"/, 'the accent door files the flag');
+  assert.match(html, /class="btn-accent" id="cd-propose-submit"/, 'and the proposal composer has its own');
+});
+
+test('the proposal composer is prefilled, and says what filing it does and does not do', () => {
+  const html = read('copy-desk.html');
+  const js = read('copy-desk.js');
+  // The composer opens with the CURRENT wording in the box — an artist edits a
+  // sentence rather than retyping it out of the quote above, which is how a
+  // proposal accidentally changes a word nobody meant to change.
+  assert.match(js, /\$\('#cd-propose-text'\)\.value = t\.text;/, 'the textarea opens prefilled with the current wording');
+  // The placeholder rule is shown only when the sentence has holes, because for
+  // most strings it is noise and for a few it is the reason the change refuses.
+  assert.match(html, /id="cd-propose-holes" hidden/, 'the placeholder rule starts hidden');
+  assert.match(js, /hint\.hidden = n === 0;/, 'and is shown only for a sentence with holes');
+  // NO LIVE CMS, said to the person in the dialog rather than only in an ADR.
+  assert.match(html, /Nothing changes yet\. This files a task carrying your wording/,
+    'the composer tells the artist their words do not reach a reader until a task ships');
+  assert.match(js, /copy-desk\/proposals/, 'and it posts to the proposal route');
 });
 
 test('the copy desk renders MORE facts per row than any other page, and lost none', () => {
@@ -205,10 +224,11 @@ test('the harness fixtures exist and carry the shapes the pages read', () => {
 
 test('the states files walk the new states', () => {
   const cd = JSON.parse(read('copy-desk.states.json'));
-  assert.deepEqual(Object.keys(cd.states), ['queue', 'out', 'search', 'composer', 'closer']);
+  assert.deepEqual(Object.keys(cd.states), ['queue', 'out', 'search', 'composer', 'closer', 'proposer']);
   assert.deepEqual(cd.states.search.actions[1], ['fill', '#cd-search', 'save']);
   assert.deepEqual(cd.states.composer.actions[1], ['clickIfVisible', '.cd-flag-btn'], 'clickIfVisible: against the kit\'s stub the button does not exist');
   assert.deepEqual(cd.states.closer.actions[1], ['clickIfVisible', '.cd-close-btn']);
+  assert.deepEqual(cd.states.proposer.actions[1], ['clickIfVisible', '.cd-propose-btn'], 'task 1003114: the proposal composer is a measured state, not one looked at once');
   const cb = JSON.parse(read('collab.states.json'));
   assert.deepEqual(cb.states.board.expect.visible, ['#cb-for-me']);
 });