@bongos/core 1.19.664 → 1.19.665

package/modules/hall-ui/public/studio.js

@@ -16,21 +16,35 @@
 //      shows people. Best-effort: an instance without the copy-desk module has
 //      no queue, and the room degrades to reviews alone rather than erroring.
 //
-// It writes NOTHING and gates NOTHING (ADR 0162 / the goal's no-live-CMS rule):
-// "open this" routes to where the craft is actually done (the task record, the
-// copy desk), and "let it be for now" only advances the reader to the next
-// piece. The full tables it replaces stay one link away in the footer.
+// It gates NOTHING (ADR 0162 / ADR 0241): nothing here holds a ship or a deploy.
+// And it writes NOTHING to any live string or asset — the goal's no-live-CMS
+// rule, unchanged. What it DOES write, since task 1003829, is the artist's own
+// VERDICT on their own queue: a review is a task in the ledger, and the three
+// weights below move that task the way triage always could. The craft itself
+// still happens on the surface that owns it (the task record, the copy desk),
+// and every change to the product still lands as a claimed, graded, shipped
+// task. The allowlist of what may be written is WRITE_ROUTES below, pinned in
+// tests/hall_studio_world.mjs.
+//
+// THE PICTURE (task 1003829). A review names the shipped task it is about, and
+// that task may carry a ship-time visual. The room reads it for the card in
+// focus and renders the image AS the card, because "look at it" is the whole of
+// what an artist is being asked to do here. One read per card, lazily, so a
+// 50-deep queue still costs one /tasks/:id.
 
 (() => {
   'use strict';
 
   const API = '/api/bongos';
   const api = window.BongosClient.createClient({ baseUrl: '', credentials: 'same-origin', throwOnError: false });
-  const { escapeHtml, $ } = window.OTB;
+  const { escapeHtml, $, toast, errMessage } = window.OTB;
+  const kit = window.OTBKit;
 
   let viewer = null;
   let pieces = [];   // the combined garden: [{ type:'review'|'flag', … }]
   let idx = 0;       // which stone is in focus
+  let busy = false;  // a verdict is in flight — one at a time, so a double-click cannot file twice
+  let tended = false; // at least one verdict landed this sitting, so an emptied garden reads as finished
 
   // Bound the reviews read. cascade.js files a review per qualifying ship and they
   // sit at backlog until claimed or dismissed ("dismissable rather than nagging"),
@@ -42,6 +56,43 @@
   // keeps the most-prioritised waiting reviews.
   const REVIEW_LIMIT = 50;
 
+  // The ONLY writes this room may issue, as an explicit allowlist rather than a
+  // convention (tests/hall_studio_world.mjs asserts studio.js writes nothing
+  // outside it). Each moves the REVIEW TASK — the artist's own queue item — and
+  // none of them touches a live string, an asset, a claim, a grade or a deploy:
+  //
+  //   abandon  looks good   → the review is dismissed, which cascade.js's own
+  //                           body calls "a real, expected outcome".
+  //   patch    note it      → the artist's words are appended to the review's
+  //                           brief, which is what whoever claims it reads.
+  //   create   needs work   → the words become a new task in the reviewed
+  //                           work's goal…
+  //   merge                 → …and the review is closed against that task, so
+  //                           the follow-up carries the lineage instead of the
+  //                           review just vanishing.
+  //
+  // All four floor at METIC server-side (modules/government/catalog.js:
+  // task.abandon / task.edit / task.create / task.merge). The room therefore
+  // OFFERS them only to a viewer who holds that floor — the task 1003751 lesson,
+  // that a card must not print a verb its route will refuse. ADR 0016 still
+  // stands: this is cosmetic, and the routes are the wall.
+  const WRITE_ROUTES = Object.freeze({
+    abandon: (reviewId) => `${API}/tasks/${reviewId}/abandon`,
+    patch: (reviewId) => `${API}/tasks/${reviewId}`,
+    create: () => `${API}/tasks`,
+    merge: (reviewId) => `${API}/tasks/${reviewId}/merge`,
+  });
+
+  // The verdict floor, read off /me. Local like goals-render.js's copy — four
+  // ranks, one comparison, and no reason for the kit to own a ladder.
+  const RANK_ORDER = { archon: 4, metic: 3, thetes: 2, xenos: 1 };
+  const MAX_WORDS = 2000;  // the abandon/merge `reason` cap the routes apply anyway
+
+  function canVerdict() {
+    const rank = String((viewer && viewer.rank) || '').toLowerCase();
+    return (RANK_ORDER[rank] ?? 0) >= RANK_ORDER.metic;
+  }
+
   // ---------------------------------------------------------------------------
   // helpers
   // ---------------------------------------------------------------------------
@@ -80,18 +131,81 @@
   // the focus card, one shape per kind of work
   // ---------------------------------------------------------------------------
 
+  // THE PLATE — the reviewed work's ship-time visual, at the size the card can
+  // give it. Through the kit's one renderer (OTBKit.taskVisualFigureHtml, which
+  // carries the server-minted-URL guard and the escaping) with the Studio's own
+  // class, because the size is this surface's decision: here the picture is the
+  // subject, not an illustration beside a record.
+  //
+  // Draws nothing when there is no visual, when the reviewed task could not be
+  // read, or when the kit is absent — a review with no picture must read as a
+  // review, never as an empty frame (the degrade rule).
+  function plateHtml(p) {
+    if (!p.shipped || !kit || typeof kit.taskVisualFigureHtml !== 'function') return '';
+    return kit.taskVisualFigureHtml(p.shipped, { className: 'studio-plate' });
+  }
+
+  // The three weights, and the one field they share. Offered only to a viewer
+  // whose rank clears the routes' floor (see WRITE_ROUTES) — otherwise the card
+  // says plainly where the verdict is recorded instead of printing three
+  // buttons that would 403.
+  //
+  // "looks good" takes words or no words; the other two require them, because a
+  // note with no note and a follow-up task with no brief are both worse than
+  // nothing. The check is in the handler, and it answers inline.
+  function verdictHtml(p) {
+    if (!canVerdict()) {
+      return `<p class="studio-verdict__sealed">Your verdict on a review is recorded from the review itself — open it to dismiss it, note what you saw, or file the follow-up.</p>`;
+    }
+    const id = escapeHtml(String(p.taskId));
+    return `
+      <div class="studio-verdict">
+        <label class="studio-verdict__label" for="studio-words">What you saw <small>— your words, in your voice. Needed for a note or a follow-up.</small></label>
+        <textarea class="studio-verdict__words" id="studio-words" rows="3" maxlength="${MAX_WORDS}"
+          placeholder="The headline lands, but the sub-line reads like a brochure."></textarea>
+        <p class="studio-verdict__err" id="studio-verdict-err" hidden></p>
+        <!-- Three ghosts, no accent: the weights are three equal answers, and
+             the One Warm Thing Rule spends the accent on the door to the craft
+             below. Nothing here should push an artist toward filing work. -->
+        <div class="studio-verdict__weights">
+          <button type="button" class="btn-ghost" data-verdict="good" data-review="${id}">Looks good</button>
+          <button type="button" class="btn-ghost" data-verdict="note" data-review="${id}">Note it</button>
+          <button type="button" class="btn-ghost" data-verdict="work" data-review="${id}">Needs work</button>
+        </div>
+      </div>`;
+  }
+
+  // The two steps of the craft (R04) — what happens INSIDE a review once it is
+  // opened. Today's copy, and the whole of what a review card could say before
+  // there was a picture on it.
+  const STEPS = `
+      <ol class="studio-steps">
+        <li class="studio-step"><span class="studio-step__n">01</span><span>Coach the grader<small>Review how it judged this work, and teach it what good looked like.</small></span></li>
+        <li class="studio-step"><span class="studio-step__n">02</span><span>Remake or tweak<small>Only if it needs it — with the AI at your side, or on your own.</small></span></li>
+      </ol>`;
+
   function reviewCard(p, n) {
     const title = p.shippedId
       ? `The copy and visuals that shipped in task #${escapeHtml(p.shippedId)}`
       : escapeHtml(p.title || 'A review of what shipped');
+    const plate = plateHtml(p);
+    // WITH A PICTURE the card is the picture: one line of framing, then the
+    // verdict, so the thing being judged and the answer to it are on one screen.
+    // The two steps describe the work done AFTER opening the review, and they
+    // belong behind that door rather than between the artist and their answer.
+    //
+    // WITHOUT ONE the card degrades to exactly the copy it has always shown —
+    // the framing paragraph and both steps — so a review with no visual still
+    // reads as a review and never as an empty frame.
+    const body = plate
+      ? `<p class="studio-card__context">It shipped and it is live. Say what you see — your review coaches the grader and never blocks what shipped.</p>`
+      : `<p class="studio-card__context">It shipped and it is live. Your review coaches the grader on how it judged the work, then remakes or tweaks the words or art only if they need it — it never blocks what shipped.</p>${STEPS}`;
     return `
       <p class="studio-card__eyebrow">to tend now · ${escapeHtml(n)}</p>
       <h2 class="studio-card__title">${title}</h2>
-      <p class="studio-card__context">It shipped and it is live. Your review coaches the grader on how it judged the work, then remakes or tweaks the words or art only if they need it — it never blocks what shipped.</p>
-      <ol class="studio-steps">
-        <li class="studio-step"><span class="studio-step__n">01</span><span>Coach the grader<small>Review how it judged this work, and teach it what good looked like.</small></span></li>
-        <li class="studio-step"><span class="studio-step__n">02</span><span>Remake or tweak<small>Only if it needs it — with the AI at your side, or on your own.</small></span></li>
-      </ol>
+      ${plate}
+      ${body}
+      ${verdictHtml(p)}
       <div class="studio-card__actions">
         <a class="btn-accent" href="/builders/task/${escapeHtml(String(p.taskId))}">Open this review</a>
         <button type="button" class="btn-ghost" data-skip>Let it be for now</button>
@@ -139,11 +253,17 @@
     const focus = $('#studio-focus');
     const rest = $('#studio-rest');
 
-    if (!pieces.length) { focus.innerHTML = emptyCard(false); rest.hidden = true; return; }
+    // An emptied garden reads as FINISHED once the reader has actually tended
+    // something this sitting, and as quiet when there was nothing to begin with.
+    if (!pieces.length) { focus.innerHTML = emptyCard(tended); rest.hidden = true; return; }
     if (idx >= pieces.length) { focus.innerHTML = emptyCard(true); rest.hidden = true; return; }
 
     const p = pieces[idx];
     focus.innerHTML = p.type === 'review' ? reviewCard(p, `${idx + 1} of ${pieces.length}`) : flagCard(p, `${idx + 1} of ${pieces.length}`);
+    // The reviewed work is read for the card in FOCUS, and only once. hydrate()
+    // repaints when it lands, so the card appears immediately and the picture
+    // arrives a beat later rather than the room waiting on a second request.
+    hydrate(p);
 
     // The rest of the garden: one stone per remaining piece, quiet and
     // non-interactive — the room asks the reader to tend one thing, not to scan.
@@ -160,6 +280,190 @@
     }
   }
 
+  // ---------------------------------------------------------------------------
+  // the reviewed work — read for the card in focus, once
+  // ---------------------------------------------------------------------------
+
+  // Hydrate ONE review with the task it is about, then repaint. Lazy on purpose:
+  // the queue is capped at 50 and the room shows one piece at a time, so eagerly
+  // reading every reviewed task would be 50 requests to render one card — the
+  // unbounded-read shape modules/hall-ui/CLAUDE.md flags. `hydrated` is set
+  // whether or not the read succeeded, so a 404 or a 403 is asked once and the
+  // card then simply carries no picture.
+  async function hydrate(p) {
+    if (!p || p.type !== 'review' || p.hydrated || !p.shippedId) return;
+    p.hydrated = true;
+    const res = await api.request('GET', `${API}/tasks/${encodeURIComponent(p.shippedId)}`);
+    if (!res.ok) return;
+    const t = (res.data && res.data.task) || null;
+    if (!t) return;
+    // The security_sensitive narrowing, taken from the server's own audience
+    // predicate (modules/lifecycle/task-visuals.js isPubliclyViewable, and the
+    // public feed's SQL): a security_sensitive task's image is the one visual
+    // the platform does not re-publish, so this room does not re-publish it
+    // either. The review still reads as a review — it degrades to the copy.
+    //
+    // BE CLEAR WHAT THIS IS: a UI choice, not a wall. isPubliclyViewable gates
+    // the UNAUTHENTICATED path, so GET /tasks/:id hands the full visual_url and
+    // visual_alt to any signed-in builder and the response in this very browser
+    // already carries them. Dropping them here keeps a sensitive image off a
+    // room that exists for looking at things, and keeps the URL out of the DOM
+    // and out of a screenshot of it. It secures nothing on its own, and nothing
+    // here should be read as a substitute for the server's gate.
+    p.shipped = t.security_sensitive === true ? { id: t.id } : t;
+    if (pieces[idx] === p) paint();
+  }
+
+  // ---------------------------------------------------------------------------
+  // the verdict — the artist's answer, recorded against the review
+  // ---------------------------------------------------------------------------
+
+  function words() {
+    const el = $('#studio-words');
+    return el ? String(el.value || '').trim().slice(0, MAX_WORDS) : '';
+  }
+
+  function verdictError(msg) {
+    const el = $('#studio-verdict-err');
+    if (!el) return;
+    el.textContent = msg || '';
+    el.hidden = !msg;
+  }
+
+  // The review is done with: drop it from the garden and move to the next stone
+  // without renumbering what the reader already passed.
+  function retire(p) {
+    const at = pieces.indexOf(p);
+    if (at === -1) return;
+    tended = true;
+    pieces.splice(at, 1);
+    if (idx > at) idx -= 1;
+    paintHead();
+    paint();
+    window.scrollTo({ top: 0 });
+  }
+
+  // "Looks good" — dismiss. cascade.js's own body says this is a real and
+  // expected outcome, so it is a first-class button and not a hidden one. The
+  // words are optional here and ride along as the retire reason, which
+  // db.abandonTask stores on the task as "Abandoned: <reason>".
+  async function verdictGood(p) {
+    const said = words();
+    const who = (viewer && (viewer.display_name || viewer.github_login)) || 'an artist';
+    const reason = `Reviewed in the studio by ${who} — the copy and visuals are good as shipped.${said ? ` ${said}` : ''}`;
+    const res = await api.request('POST', WRITE_ROUTES.abandon(p.taskId), { reason });
+    if (!res.ok) return verdictError(errMessage(res.data) || 'That could not be recorded. Nothing changed.');
+    toast('Dismissed — the copy and visuals are good as shipped.');
+    retire(p);
+    return undefined;
+  }
+
+  // "Note it" — the artist's words, recorded against the review, which stays
+  // open. They are APPENDED to the review's own description because that is the
+  // text whoever claims this review actually reads; the route audit-logs every
+  // description edit, so the note has a trail as well as a home.
+  //
+  // THE BASE IS RE-READ, not taken from the queue row, and both halves of that
+  // matter. PATCH description REPLACES the field, so appending to a stale or
+  // absent base does not add a note — it DELETES the cascade's brief. The list
+  // read happens to carry `description` today (db-tasks.js listTasks is
+  // SELECT t.*), but that projection is already under pressure from the board's
+  // read sizes, and a narrowing there must not silently blank a review body
+  // here. The re-read also means a second artist noting on the same review
+  // appends after the first instead of overwriting them. No base, no write.
+  async function verdictNote(p) {
+    const said = words();
+    if (!said) return verdictError('Write what you saw first — a note with no note is worse than none.');
+    const cur = await api.request('GET', `${API}/tasks/${p.taskId}`);
+    const base = cur.ok && cur.data && cur.data.task ? String(cur.data.task.description || '') : null;
+    if (base === null) {
+      return verdictError('The review could not be re-read just now, so nothing was written — try again in a moment.');
+    }
+    const who = (viewer && (viewer.display_name || viewer.github_login)) || 'an artist';
+    const stamp = new Date().toISOString().slice(0, 10);
+    const block = `\n\n---\n\nARTIST NOTE (${stamp}, ${who}, from the studio):\n\n${said}`;
+    const res = await api.request('PATCH', WRITE_ROUTES.patch(p.taskId), { description: `${base}${block}` });
+    if (!res.ok) return verdictError(errMessage(res.data) || 'That could not be recorded. Nothing changed.');
+    p.description = `${base}${block}`;
+    toast('Noted on the review — it stays open.');
+    const el = $('#studio-words');
+    if (el) el.value = '';
+    verdictError('');
+    return undefined;
+  }
+
+  // "Needs work" — the words become a NEW task in the reviewed work's goal, and
+  // the review is closed AGAINST it.
+  //
+  // No live edit happens here and none can: what this files is an ordinary
+  // backlog task that somebody has to claim, build, have graded and ship, which
+  // is goal 1000074's hard rule stated as a mechanism rather than a promise.
+  //
+  // The review's own goal_id/version_id are the reviewed work's — cascade.js
+  // property 3: a generated review inherits the source task's goal and version.
+  // So the follow-up lands beside the work it is about with no second read.
+  //
+  // source_ref makes the pair idempotent: POST /tasks keys on (source,
+  // source_ref), so a double-click or a retry resolves to the SAME follow-up
+  // rather than minting a second one, and the merge below is idempotent when it
+  // re-merges into the target already recorded.
+  async function verdictWork(p) {
+    const said = words();
+    if (!said) return verdictError('Write what needs work first — a follow-up with no brief cannot be claimed.');
+    const who = (viewer && (viewer.display_name || viewer.github_login)) || 'an artist';
+    const about = p.shippedId ? `task ${p.shippedId}` : `review ${p.taskId}`;
+    const created = await api.request('POST', WRITE_ROUTES.create(), {
+      version_id: p.versionId,
+      goal_id: p.goalId ? Number(p.goalId) : undefined,
+      title: `Artist verdict: the copy or visuals shipped in ${about} need work`,
+      description: [
+        `Filed from the studio by ${who}, as the verdict on artist review ${p.taskId} of ${about}.`,
+        '',
+        'WHAT THE ARTIST SAW:',
+        '',
+        said,
+        '',
+        'This is ordinary work: claim it, make the change, have it graded and ship it. The studio files the judgement and never edits a live string or asset (goal 1000074\'s rule).',
+      ].join('\n'),
+      discipline: 'artist',
+      source: 'studio-verdict',
+      source_ref: `studio-needs-work-on-review-${p.taskId}`,
+    });
+    if (!created.ok) return verdictError(errMessage(created.data) || 'The follow-up could not be filed. Nothing changed.');
+    const newId = created.data && created.data.task && created.data.task.id;
+    if (!newId) return verdictError('The follow-up came back without an id, so the review was left open.');
+    // Close the review against the follow-up. If this half fails the follow-up
+    // still exists and is reported as such — a stranded-but-visible task beats
+    // a silent success, and re-running the same verdict is safe.
+    const closed = await api.request('POST', WRITE_ROUTES.merge(p.taskId), {
+      into_task_id: Number(newId),
+      reason: `Artist verdict from the studio: the review's answer is task ${newId}, which carries the work.`,
+    });
+    if (!closed.ok) {
+      return verdictError(`Task ${newId} was filed, but this review could not be closed against it — close it from the review itself.`);
+    }
+    toast(`Filed as task ${newId} — this review is closed against it.`);
+    retire(p);
+    return undefined;
+  }
+
+  const VERDICTS = { good: verdictGood, note: verdictNote, work: verdictWork };
+
+  async function runVerdict(kind) {
+    const p = pieces[idx];
+    if (busy || !p || p.type !== 'review' || !VERDICTS[kind]) return;
+    if (!canVerdict()) return;
+    busy = true;
+    verdictError('');
+    try {
+      await VERDICTS[kind](p);
+    } catch (_err) {
+      verdictError('That could not be recorded. Nothing changed.');
+    } finally {
+      busy = false;
+    }
+  }
+
   // ---------------------------------------------------------------------------
   // load
   // ---------------------------------------------------------------------------
@@ -174,7 +478,19 @@
     return tasks
       .filter((t) => t.source === 'cascade' || /^artist review\b/i.test(t.title || ''))
       .sort((a, b) => new Date(b.created_at || 0) - new Date(a.created_at || 0))
-      .map((t) => ({ type: 'review', taskId: t.id, title: t.title, shippedId: reviewShippedId(t) }));
+      // goalId/versionId are the REVIEWED work's — cascade.js property 3: a
+      // generated review inherits its source task's goal and version. They ride
+      // here so the "needs work" follow-up needs no second read, and
+      // `description` rides here so "note it" appends rather than overwrites.
+      .map((t) => ({
+        type: 'review',
+        taskId: t.id,
+        title: t.title,
+        description: t.description,
+        goalId: t.goal_id,
+        versionId: t.version_id,
+        shippedId: reviewShippedId(t),
+      }));
   }
 
   // The open flags. Best-effort: no copy-desk module → 404 → no flags, and the
@@ -198,7 +514,15 @@
 
   document.addEventListener('click', (ev) => {
     if (ev.target.closest('[data-skip]')) { idx += 1; paint(); window.scrollTo({ top: 0 }); return; }
-    if (ev.target.closest('[data-restart]')) { idx = 0; paint(); window.scrollTo({ top: 0 }); }
+    if (ev.target.closest('[data-restart]')) { idx = 0; paint(); window.scrollTo({ top: 0 }); return; }
+    const weight = ev.target.closest('[data-verdict]');
+    if (weight) runVerdict(weight.dataset.verdict);
+  });
+
+  // Clear the inline error as soon as the artist edits the field — the design
+  // system's rule: an error stands until the input that caused it changes.
+  document.addEventListener('input', (ev) => {
+    if (ev.target && ev.target.id === 'studio-words') verdictError('');
   });
 
   (async () => {

package/modules/hall-ui/public/studio.states.json

@@ -1,5 +1,5 @@
 {
-  "_": "The Studio (artist mode), R06 of goal 1000074 (task 1003117). A calm room that surfaces the artist's real work — backlog review requests (cascade, R04) and open copy flags (R02) — one piece at a time, never a table. Against the kit's own stub the page renders its EMPTY state (no /tasks or /copy-desk feed), which is a state the floors must hold in; against the hall-preview harness with the studio__reviews / copy-desk__queue fixtures it renders the focus card and the garden's stones.",
+  "_": "The Studio (artist mode), R06 of goal 1000074 (task 1003117). A calm room that surfaces the artist's real work — backlog review requests (cascade, R04) and open copy flags (R02) — one piece at a time, never a table. Against the kit's own stub the page renders its EMPTY state (no /tasks or /copy-desk feed), which is a state the floors must hold in. TO SEE IT POPULATED, point the kit at the hall-preview harness instead: `node scripts/hall-preview/server.js --port 4629 --fixture-me` then `render.js --base-in http://builders.localhost:4629 --base-out http://builders.localhost:4629`. That harness answers /tasks from fixtures/tasks.json (whose first row IS a cascade artist review), the reviewed task from fixtures/tasks__detail.json (which carries a visual_url), and the visual itself as a generated stand-in — task 1003829, where the review card's picture became the subject of the card and a broken frame stopped being reviewable. An earlier version of this note named a studio__reviews.json fixture; there is no such file and there never was.",
   "page": "/builders/studio",
   "surface": "hall-ui",
   "stub": {

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.664",
+  "version": "1.19.665",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.664",
+      "version": "1.19.665",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.664",
+  "version": "1.19.665",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/hall-preview/server.js

@@ -183,6 +183,17 @@ app.use((req, res, next) => {
     return;
   }
 
+  // The ship-time VISUAL is an image, not a fixture (task 1003829). Without
+  // this, every surface that renders one — the task record, a ship feed, the
+  // Studio's review card, where the picture IS the card — previews as a broken
+  // frame, so the one thing being reviewed is the one thing you cannot see.
+  // A generated stand-in; see scripts/hall-preview/task-visual.js.
+  if (/^task-visuals\/[A-Za-z0-9._-]+$/.test(apiPath) && req.method === 'GET') {
+    const png = require('./task-visual').placeholderPng();
+    res.set({ 'content-type': 'image/png', 'cache-control': 'no-store' });
+    return res.end(png);
+  }
+
   if (req.method !== 'GET') {
     return res.status(501).json({ error: { code: 'preview_readonly', message: 'the preview harness serves fixtures; writes are not wired' } });
   }

package/scripts/hall-preview/task-visual.js

@@ -0,0 +1,89 @@
+'use strict';
+// scripts/hall-preview/task-visual.js — a stand-in ship-time visual for the
+// preview harness (task 1003829).
+//
+// WHY THIS EXISTS. Everything else in this harness is answered from a checked-in
+// JSON fixture, but a ship-time visual is an IMAGE: the API stub answers
+// /api/bongos/* with JSON, so a page that renders <img src="/api/bongos/
+// task-visuals/task-1899-….png"> got a 404 body and a broken frame. The Studio's
+// review card (task 1003829) makes that image the subject of the card, and a
+// surface whose subject cannot be rendered cannot be reviewed — the whole point
+// of this harness.
+//
+// It is a GENERATED placeholder, not a checked-in screenshot: a few flat bands
+// at a real screenshot's aspect ratio, so a reviewer can judge the plate's size,
+// fit, caption and crop without a binary in the repo. Deliberately obvious —
+// nobody should mistake it for a real ship's visual.
+//
+// A ~40-line PNG encoder rather than a dependency, matching the kit's own
+// png.js (a ~50-line DEcoder for the same reason). One IDAT, filter type 0.
+const zlib = require('node:zlib');
+
+function chunk(type, data) {
+  const len = Buffer.alloc(4);
+  len.writeUInt32BE(data.length);
+  const body = Buffer.concat([Buffer.from(type, 'ascii'), data]);
+  const crc = Buffer.alloc(4);
+  crc.writeUInt32BE(crc32(body) >>> 0);
+  return Buffer.concat([len, body, crc]);
+}
+
+let CRC_TABLE = null;
+function crc32(buf) {
+  if (!CRC_TABLE) {
+    CRC_TABLE = new Int32Array(256);
+    for (let n = 0; n < 256; n++) {
+      let c = n;
+      for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+      CRC_TABLE[n] = c;
+    }
+  }
+  let c = -1;
+  for (let i = 0; i < buf.length; i++) c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+  return c ^ -1;
+}
+
+// An RGB PNG from a per-pixel colour function. RGB (colour type 2), 8-bit,
+// non-interlaced — the shape the kit's decoder also speaks.
+function encodeRgb(w, h, at) {
+  const stride = w * 3;
+  const raw = Buffer.alloc((stride + 1) * h);
+  for (let y = 0; y < h; y++) {
+    const row = y * (stride + 1);
+    raw[row] = 0;  // filter: none
+    for (let x = 0; x < w; x++) {
+      const [r, g, b] = at(x, y);
+      const p = row + 1 + x * 3;
+      raw[p] = r; raw[p + 1] = g; raw[p + 2] = b;
+    }
+  }
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(w, 0);
+  ihdr.writeUInt32BE(h, 4);
+  ihdr[8] = 8; ihdr[9] = 2; ihdr[10] = 0; ihdr[11] = 0; ihdr[12] = 0;
+  return Buffer.concat([
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    chunk('IHDR', ihdr),
+    chunk('IDAT', zlib.deflateSync(raw, { level: 9 })),
+    chunk('IEND', Buffer.alloc(0)),
+  ]);
+}
+
+// The stand-in: a wide plate of flat bands with a paler inset, so its edges,
+// aspect ratio and any crop are all visible at a glance. Cached — the harness
+// may serve it on every paint.
+let CACHED = null;
+function placeholderPng() {
+  if (CACHED) return CACHED;
+  const W = 1200, H = 700;
+  const BANDS = [[38, 34, 30], [74, 66, 58], [176, 96, 62], [214, 200, 184], [246, 243, 238]];
+  CACHED = encodeRgb(W, H, (x, y) => {
+    const inset = x > W * 0.08 && x < W * 0.92 && y > H * 0.14 && y < H * 0.86;
+    const band = BANDS[Math.min(BANDS.length - 1, Math.floor((y / H) * BANDS.length))];
+    if (!inset) return band;
+    return band.map((c) => Math.min(255, Math.round(c + (255 - c) * 0.42)));
+  });
+  return CACHED;
+}
+
+module.exports = { placeholderPng, encodeRgb };

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // 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.664'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.665'; // 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');