@bongos/core 1.23.22 → 1.24.2

package/modules/government/routes/government.js

@@ -34,6 +34,7 @@ const counts = require('../counts');
 const asks = require('../asks');
 const asksDb = require('../asks-db');
 const routing = require('../routing');
+const { accessHandlers } = require('../access-routes');
 const governmentConfig = require('../config');
 const membershipPredicate = require('../membership-predicate');
 const positions = require('../positions');
@@ -689,6 +690,14 @@ module.exports = function buildGovernmentRouter() {
     }
   });
 
+  // ACCESS HOLDERS (task 1005000): who holds the keys outside Bongos, so an ask can wait
+  // on access:<key>. Read on the docket's atom; recorded by the owner. A record of who to
+  // ask, never authority (access.js). Bodies: access-routes.js.
+  const accessRoutes = accessHandlers({ db, log, parseId, validateOrRespond });
+  router.get('/government/access', api.requireBuilder, api.requirePermission('board.vote.cast'), accessRoutes.read);
+  router.post('/government/access/:accessKey/holders', api.requireBuilder, api.requirePermission('government.manage'), accessRoutes.grant);
+  router.delete('/government/access/:accessKey/holders/:builderId', api.requireBuilder, api.requirePermission('government.manage'), accessRoutes.revoke);
+
   // rank: perm board.vote.cast — the Board Room view: open items with their
   // clock, the OPEN BALLOT, the closed history (R16 of goal 1000069). Gated on
   // the XENOS-floored vote atom, deliberately: seeing the ballot is part of
@@ -767,6 +776,28 @@ module.exports = function buildGovernmentRouter() {
   // treasury; `rule` ∈ decide first consent majority unanimous signoff rule (or
   // null); `state` ∈ needs moving settled. Nothing is ever sample data: a source
   // with nothing recorded yet is `coming`, never a placeholder row.
+  // OPEN BLOCKERS UNDER PEOPLE (task 1004999): every open blocker grouped under each
+  // person its seat resolves to (routing.js, the City's own rule), and the viewer's own
+  // group. The docket's atom: it floors at xenos, so every builder can see whose a
+  // blocker is; resolving one keeps its own blocker.review gate.
+  router.get('/government/blockers/people', api.requireBuilder, api.requirePermission('board.vote.cast'), async (req, res) => {
+    try {
+      res.json(await docket.blockersByPerson(req.builder));
+    } catch (err) {
+      log.error('[gds] GET /government/blockers/people', err);
+      res.fail('blockers_people_read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+  router.get('/government/blockers/for-me', api.requireBuilder, api.requirePermission('board.vote.cast'), async (req, res) => {
+    try {
+      const r = await docket.blockersByPerson(req.builder);
+      res.json({ available: r.available, reason: r.reason || null, ...r.yours });
+    } catch (err) {
+      log.error('[gds] GET /government/blockers/for-me', err);
+      res.fail('blockers_for_me_read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
   router.get('/government/docket', api.requireBuilder, api.requirePermission('board.vote.cast'), async (req, res) => {
     try {
       res.json(await docket.docketFor(req.builder));

package/modules/government/routing.js

@@ -38,6 +38,7 @@
 // request, uncached (ADR 0016), and routes every matter with routeAll.
 
 const { answerFor } = require('./leads');
+const access = require('./access');
 const asks = require('./asks');
 
 const BUILDING_NAMES = Object.freeze({
@@ -59,6 +60,7 @@ function seatOf(matter) {
 function seatLabel(seat) {
   const s = String(seat || '');
   if (s === 'owner') return 'the owner';
+  if (/^access:/.test(s)) return access.accessLabel(s.slice(7));
   const m = /^(lead|board):([a-z]+)$/.exec(s);
   if (m) return `the ${BUILDING_NAMES[m[2]] || m[2]} ${m[1] === 'lead' ? 'Lead' : 'board'}`;
   return asks.seatWords(s);
@@ -69,12 +71,42 @@ const idsOf = (list) => (Array.isArray(list) ? list : [])
   .filter((id) => id != null)
   .map(String);
 
+// Who each builder id is, from the seats already read (task 1004999): the owner
+// seat's Archons, the Leads in office and each building's holders. A route names
+// people, not just a seat — "waits on Lars, the owner", not "waits on the owner".
+// Pure; an id no seat row names reads as { id, login: null, name: null }.
+function directoryOf(ctx) {
+  const c = ctx || {};
+  const dir = new Map();
+  const put = (id, login, name) => {
+    if (id == null) return;
+    const key = String(id);
+    const prev = dir.get(key);
+    if (prev && prev.name) return;
+    dir.set(key, { id: key, login: login || null, name: name || login || null });
+  };
+  for (const b of (c.owner && c.owner.builders) || []) put(b.id, b.login, b.name);
+  for (const l of Array.isArray(c.leads) ? c.leads : Object.values(c.leads || {})) {
+    if (l && !l.removed_at) put(l.builder_id, l.github_login, l.display_name);
+  }
+  for (const list of [...Object.values(c.holders || {}), ...Object.values(c.access || {})]) {
+    for (const p of Array.isArray(list) ? list : []) {
+      if (p && typeof p === 'object') put(p.builder_id ?? p.id, p.github_login ?? p.login, p.display_name ?? p.name);
+    }
+  }
+  return dir;
+}
+function peopleOf(ids, dir) {
+  return (ids || []).map((id) => dir.get(String(id)) || { id: String(id), login: null, name: null });
+}
+
 // resolveSeat(asked, ctx) → { asked, seat, label, builder_ids, fell_to_owner }
 //   asked        the seat the matter names
 //   seat         the seat that answers it, after any fall
 //   builder_ids  who sits there now ([] when nobody does)
 // ctx { leads: Lead rows in office, owner: leads ownerOf(archons) shape
-//       { builders: [{ id }] }, holders: { building: [people] | null } }
+//       { builders: [{ id }] }, holders: { building: [people] | null },
+//       access: { key: [holder rows] } (task 1005000) }
 function resolveSeat(asked, ctx) {
   const c = ctx || {};
   const owner = c.owner || { builders: [] };
@@ -91,17 +123,24 @@ function resolveSeat(asked, ctx) {
     const held = idsOf((c.holders || {})[m[1]]);
     return held.length ? seated(asked, held) : toOwner();
   }
+  // task 1005000: an outside access — its recorded holders; nobody recorded → the owner.
+  if ((m = /^access:([a-z-]+)$/.exec(String(asked || ''))) && access.isAccessKey(m[1])) {
+    const held = idsOf((c.access || {})[m[1]]);
+    return held.length ? seated(asked, held) : toOwner();
+  }
   if ((m = /^committee:([a-z]+)\.[a-z0-9_]+$/.exec(String(asked || '')))) {
     return { ...resolveSeat(`lead:${m[1]}`, c), asked };
   }
   return toOwner();
 }
 
-// routeMatter(matter, viewerId, ctx, now) → the route the docket carries:
-//   { seat, label, asked, fell_to_owner, yours, nobody: null | { why, outcome } }
+// routeMatter(matter, viewerId, ctx, now, dir) → the route the docket carries:
+//   { seat, label, asked, fell_to_owner, people, yours, nobody: null | { why, outcome } }
 // `yours` is the one answer to "is this on me": an open matter that needs a
 // person, on a seat the viewer sits in, that somebody can still answer.
-function routeMatter(matter, viewerId, ctx, now = Date.now()) {
+// `dir` is directoryOf(ctx); routeAll builds it ONCE per request and passes it,
+// so a docket of N matters does not rebuild the same name map N times.
+function routeMatter(matter, viewerId, ctx, now = Date.now(), dir = directoryOf(ctx)) {
   const m = matter || {};
   const needs = m.state === 'needs';
   // a sitting's voters are the item's own (its snapshot), never a fall to the owner
@@ -120,6 +159,8 @@ function routeMatter(matter, viewerId, ctx, now = Date.now()) {
     label: r.label,
     asked: r.asked,
     fell_to_owner: r.fell_to_owner,
+    // who sits in that seat now, by name (task 1004999); [] for a sitting's own voters
+    people: peopleOf(r.builder_ids, dir),
     yours: needs && !nobody && !!viewer && sits,
     nobody,
   };
@@ -128,8 +169,9 @@ function routeMatter(matter, viewerId, ctx, now = Date.now()) {
 // Route every matter in place; → how many are the viewer's.
 function routeAll(matters, viewerId, ctx, now = Date.now()) {
   let yours = 0;
+  const dir = directoryOf(ctx);
   for (const m of matters || []) {
-    m.route = routeMatter(m, viewerId, ctx, now);
+    m.route = routeMatter(m, viewerId, ctx, now, dir);
     if (m.route.yours) yours += 1;
   }
   return yours;
@@ -144,11 +186,11 @@ function passRefusal(matter, viewerId, toSeat, ctx, now = Date.now()) {
   if (!m.ask) return { code: 'no_ask', status: 409, message: 'This matter has no ask to pass on yet.' };
   if (m.source === 'board') return { code: 'vote_not_passable', status: 409, message: 'A vote is its voters\' to answer; it cannot be passed on.' };
   const to = String(toSeat || '').trim();
-  if (!asks.SEAT.test(to)) return { code: 'unknown_seat', status: 400, message: 'Name a seat: owner, lead:<building>, committee:<building>.<name> or board:<building>.' };
+  if (!asks.SEAT.test(to)) return { code: 'unknown_seat', status: 400, message: 'Name a seat: owner, lead:<building>, committee:<building>.<name>, board:<building> or access:<key>.' };
   const route = routeMatter(m, viewerId, ctx, now);
   if (!route.yours) return { code: 'not_yours', status: 403, message: 'Only whoever this waits on can pass it on.' };
   if (to === m.ask.waits_on || resolveSeat(to, ctx).seat === route.seat) return { code: 'same_seat', status: 409, message: 'It already waits on that seat.' };
   return null;
 }
 
-module.exports = { seatOf, resolveSeat, routeMatter, routeAll, passRefusal, BUILDING_NAMES };
+module.exports = { seatOf, resolveSeat, directoryOf, peopleOf, routeMatter, routeAll, passRefusal, BUILDING_NAMES };

package/modules/government/waiting.js

@@ -0,0 +1,78 @@
+'use strict';
+
+// modules/government/waiting.js — open blockers grouped UNDER THE PEOPLE they wait on
+// (task 1004999, goal 1000111).
+//
+// WHY. A blocker has no person on it: the blockers table has no assignee, and the only
+// "who" is the seat its ask names (owner | lead:<b> | board:<b> | committee:…). So every
+// surface listed every blocker to everyone, /blocker-review framed them all as the
+// owner's, and nobody could open one place and see "these wait on me" — or see that a
+// blocker was waiting on Lars rather than on "the owner".
+//
+// THE RULE. The seat is the truth; the person is resolved at READ time with the same
+// routing the City uses (routing.js seatOf → resolveSeat), so the two can never
+// disagree about whose a blocker is, and seating a new Lead moves their blockers with
+// no blocker edited. Never copy a name onto a blocker.
+//
+// A blocker waits on EVERY person its seat resolves to (a board's members, or two
+// Archons as the owner), so it is listed under each of them. One that resolves to
+// nobody is listed under `nobody`, never dropped.
+//
+// PURE: no db. docket.js reads the blockers, their asks and the seats, then calls this.
+
+const routing = require('./routing');
+const access = require('./access');
+
+// One blocker as a line under a person: what it is, where it lives, and the seat it
+// reaches that person through, in words ("as the owner", "as the Planning Lead").
+function itemOf(m, r) {
+  return {
+    id: m.ref && m.ref.id != null ? String(m.ref.id) : String(m.id),
+    matter_id: String(m.id),
+    title: m.title,
+    href: m.href || null,
+    opened_at: m.opened_at || null,
+    where: m.where || null,
+    seat: r.seat,
+    as: r.label,
+    asked: r.asked,
+    fell_to_owner: !!r.fell_to_owner,
+    // task 1005000: a blocker only an outside-access holder can clear reads as its own
+    // category ("needs repo-owner access"), not as one more of the owner's.
+    needs: /^access:/.test(String(r.asked || '')) ? access.needsWords(String(r.asked).slice(7)) : null,
+    question: m.ask && m.ask.question ? String(m.ask.question) : null,
+  };
+}
+
+const byOpened = (a, b) => String(a.opened_at || '').localeCompare(String(b.opened_at || '')) || a.id.localeCompare(b.id, 'en', { numeric: true });
+
+// groupByPerson(matters, seats) → { people: [{ person, count, items }], nobody: [items] }
+// People with the most waiting first, then by name; inside a person, oldest first.
+function groupByPerson(matters, seats) {
+  const dir = routing.directoryOf(seats);
+  const groups = new Map();
+  const nobody = [];
+  for (const m of matters || []) {
+    if (!m || m.state === 'settled') continue;
+    const r = routing.resolveSeat(routing.seatOf(m), seats);
+    const item = itemOf(m, r);
+    if (!r.builder_ids.length) { nobody.push(item); continue; }
+    for (const p of routing.peopleOf(r.builder_ids, dir)) {
+      if (!groups.has(p.id)) groups.set(p.id, { person: p, items: [] });
+      groups.get(p.id).items.push(item);
+    }
+  }
+  const people = [...groups.values()]
+    .map((g) => ({ person: g.person, count: g.items.length, items: g.items.sort(byOpened) }))
+    .sort((a, b) => b.count - a.count || String(a.person.name || a.person.id).localeCompare(String(b.person.name || b.person.id)));
+  return { people, nobody: nobody.sort(byOpened) };
+}
+
+// The viewer's own group: what waits on THEM. → { person, count, items } (count 0 when none).
+function forViewer(grouped, viewerId) {
+  const id = viewerId == null ? null : String(viewerId);
+  const g = id && grouped && Array.isArray(grouped.people) ? grouped.people.find((x) => x.person.id === id) : null;
+  return g || { person: id ? { id, login: null, name: null } : null, count: 0, items: [] };
+}
+
+module.exports = { groupByPerson, forViewer };

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

@@ -0,0 +1,268 @@
+// modules/hall-ui/public/ai-studio-lib.js — the pure rules of the Studio's AI
+// pages, /builders/ai-studio (task 1004921, goal 1000136, ADR 0392).
+//
+// Built 1:1 on the owner's pick, option C of the AI Studio options canvas
+// ("Three steps: pick, describe, make"), with the owner's addition that the
+// results page lets the request be changed and made again. Everything here is
+// pure: money in words, the receipt, the month's summary of the ledger, the
+// waiting checklist, which view a URL names, and the reply's safe markup.
+// ai-studio.js does the reads, the writes and the painting.
+//
+// Money is integer micro-dollars everywhere (1,000,000 = $1), as the server
+// sends it. A PRICE with sub-cent digits shows four decimals ($0.0421); a
+// whole-cent amount and a BALANCE show two ($12.40). A balance rounds DOWN, so
+// the page never promises a cent that is not there.
+//
+// The file limits below are the upload checks' (modules/ai-studio/studio.js),
+// repeated so the page can say no before a 4 MB upload starts. The server
+// still checks every file; these only spare the wait.
+//
+// Node-require-safe: assignment to window is the only side effect, and only
+// when a window exists (tests/hall_ai_studio.mjs requires it directly).
+
+(function (root) {
+  'use strict';
+
+  const MICRO_PER_USD = 1000000;
+  const MICRO_PER_CENT = 10000;
+  const MAX_FILES = 6;
+  const MAX_IMAGE_BYTES = 4 * 1024 * 1024;
+  const MAX_PDF_BYTES = 8 * 1024 * 1024;
+  const IMAGE_TYPES = Object.freeze(['image/png', 'image/jpeg', 'image/gif', 'image/webp']);
+  const PDF_TYPE = 'application/pdf';
+  const FINISHED = Object.freeze(['done', 'failed', 'refused']);
+  const STEPS = Object.freeze(['pick', 'describe', 'make']);
+  const TOPUP_CHOICES = Object.freeze([5, 10, 20, 50]);
+  // The waiting checklist is paced by the clock: the server reports a request
+  // as queued or running, not which call it is on, so "wrote the answer" is
+  // ticked once a run has gone on long enough for the reply to be back.
+  const ANSWER_AFTER_SEC = 25;
+
+  function isMicro(v) { return Number.isSafeInteger(v); }
+
+  // "$0.0421", "$0.50", "$12.40". Sub-cent amounts keep four decimals.
+  function usd(micro) {
+    if (!isMicro(micro)) return '';
+    const neg = micro < 0;
+    const a = Math.abs(micro);
+    const text = a % MICRO_PER_CENT === 0
+      ? (a / MICRO_PER_USD).toFixed(2)
+      : (Math.round(a / 100) / 10000).toFixed(4);
+    return `${neg ? '−' : ''}$${text}`;
+  }
+
+  // A balance: two decimals, rounded down.
+  function balanceUsd(micro) {
+    if (!isMicro(micro)) return '';
+    const cents = Math.floor(micro / MICRO_PER_CENT);
+    return `$${(cents / 100).toFixed(2)}`;
+  }
+
+  function sizeText(bytes) {
+    const n = Number(bytes) || 0;
+    if (n >= 1024 * 1024) return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+    if (n >= 1024) return `${Math.round(n / 1024)} KB`;
+    return `${n} B`;
+  }
+
+  // Which page the address names. ?request=N is the waiting page or the
+  // result; ?view=balance the balance; otherwise one of the three steps.
+  function routeOf(search) {
+    const q = new URLSearchParams(String(search || ''));
+    const request = q.get('request');
+    if (request && /^\d{1,18}$/.test(request)) return { view: 'request', id: request };
+    if (q.get('view') === 'balance') return { view: 'balance', all: q.get('all') === '1' };
+    const step = STEPS.includes(q.get('step')) ? q.get('step') : 'pick';
+    const from = q.get('from');
+    return { view: 'step', step, from: from && /^\d{1,18}$/.test(from) ? from : null };
+  }
+
+  // Says no to a file before it is sent, in the same words the server would.
+  function checkFile(file, count) {
+    if (count >= MAX_FILES) return `Send up to ${MAX_FILES} files at a time.`;
+    const type = String(file && file.type || '');
+    if (type !== PDF_TYPE && !IMAGE_TYPES.includes(type)) return 'Pictures (PNG, JPG, GIF, WebP) or a PDF only.';
+    const max = type === PDF_TYPE ? MAX_PDF_BYTES : MAX_IMAGE_BYTES;
+    if ((Number(file.size) || 0) > max) return type === PDF_TYPE ? 'PDFs up to 8 MB.' : 'Pictures up to 4 MB.';
+    return null;
+  }
+
+  function isImage(contentType) { return IMAGE_TYPES.includes(String(contentType || '')); }
+
+  // The step header: "1 Pick ✓", "2 Describe", "3 Make".
+  function stepMarks(step) {
+    const at = STEPS.indexOf(step);
+    return [['1', 'Pick'], ['2', 'Describe'], ['3', 'Make']].map(([n, label], i) => ({
+      text: `${n} ${label}${i < at ? ' ✓' : ''}`,
+      state: i < at ? 'done' : (i === at ? 'now' : 'later'),
+    }));
+  }
+
+  // The prompt as one quoted line for step 3's summary row.
+  function quoteLine(prompt, max) {
+    const t = String(prompt || '').replace(/\s+/g, ' ').trim();
+    const cap = max || 64;
+    return `“${t.length > cap ? `${t.slice(0, cap - 1).trimEnd()}…` : t}”`;
+  }
+
+  // The own key the server will run on: OpenRouter first, as keys.chooseKey
+  // prefers it (it reports its cost). null when none is saved.
+  function ownKey(keys) {
+    const list = (keys && keys.keys) || [];
+    const set = (p) => list.find((k) => k && k.provider === p && k.set);
+    const k = set('openrouter') || set('gemini');
+    if (!k) return null;
+    return k.provider === 'openrouter'
+      ? { provider: 'openrouter', name: 'OpenRouter', billedBy: 'OpenRouter', last4: k.last4 }
+      : { provider: 'gemini', name: 'Gemini', billedBy: 'Google', last4: k.last4 };
+  }
+
+  // Step 3's two cards. balance is GET /ai-studio/balance's body.
+  function payChoices(keys, balance) {
+    const own = ownKey(keys);
+    const b = balance || {};
+    const avail = b.balance ? b.balance.available_micro : null;
+    const max = isMicro(b.max_cost_micro) ? b.max_cost_micro : null;
+    const payments = !!b.balance;
+    return {
+      own,
+      payments,
+      setAside: max === null ? '' : usd(max),
+      left: payments ? `${balanceUsd(avail)} left` : '',
+      short: payments && max !== null && avail < max,
+    };
+  }
+
+  // The waiting page's three lines, from the request's status and how long it
+  // has run.
+  function waitSteps(status, elapsedSec, fileCount) {
+    const n = Number(fileCount) || 0;
+    const files = n === 1 ? 'Read your file' : `Read your ${n} files`;
+    const running = status === 'running';
+    const answered = running && elapsedSec >= ANSWER_AFTER_SEC;
+    return [
+      { text: files, state: running ? 'done' : 'now' },
+      { text: 'Wrote the answer', state: answered ? 'done' : (running ? 'now' : 'later') },
+      { text: 'Drawing the pictures', state: answered ? 'now' : 'later' },
+    ];
+  }
+
+  function clock(sec) {
+    const s = Math.max(0, Math.floor(Number(sec) || 0));
+    return `${Math.floor(s / 60)}:${String(s % 60).padStart(2, '0')}`;
+  }
+
+  function isFinished(status) { return FINISHED.includes(status); }
+
+  // The receipt on the results page: rows of [label, value] and a note.
+  // (The stored request does not name which of the builder's keys ran.)
+  // key_source 'ours' is the balance; 'own' with a reported cost is an
+  // OpenRouter key; 'own' with none is a Gemini key (Google reports no price).
+  // A request that did not finish has no receipt: its error line already says
+  // what was (not) charged.
+  function receipt(req, multiplier) {
+    const r = req || {};
+    if (r.status !== 'done') return { rows: [], note: '' };
+    if (r.key_source === 'ours' && isMicro(r.price_micro)) {
+      const pct = Number(multiplier) > 1 ? Math.round((Number(multiplier) - 1) * 100) : null;
+      return {
+        rows: [
+          ['Paid with', 'your balance'],
+          ['OpenRouter', usd(r.provider_cost_micro)],
+          [pct === null ? 'Ours' : `Our ${pct}%`, usd(r.markup_micro)],
+          ['You paid', usd(r.price_micro)],
+        ],
+        note: '',
+      };
+    }
+    if (r.key_source === 'own' && isMicro(r.provider_cost_micro)) {
+      return {
+        rows: [['Paid with', 'your own OpenRouter key'], ['Cost', usd(r.provider_cost_micro)]],
+        note: 'OpenRouter bills you for it directly. We charged nothing.',
+      };
+    }
+    if (r.key_source === 'own') {
+      return {
+        rows: [['Paid with', 'your own Gemini key'], ['Cost', 'not reported']],
+        note: "Google doesn't tell us the price on your own key, so check your Google bill. We charged nothing.",
+      };
+    }
+    return { rows: [], note: '' };
+  }
+
+  // "Same 3 files, paid the same way."
+  function againLine(uploadCount) {
+    const n = Number(uploadCount) || 0;
+    return `Change the words and make it again. Same ${n === 1 ? 'file' : `${n} files`}, paid the same way.`;
+  }
+
+  // The month's summary of the ledger rows that fall in `now`'s month.
+  function monthSummary(ledger, now) {
+    const d = now instanceof Date ? now : new Date();
+    const inMonth = (row) => {
+      const t = new Date(row.created_at);
+      return !Number.isNaN(t.getTime()) && t.getFullYear() === d.getFullYear() && t.getMonth() === d.getMonth();
+    };
+    const rows = (ledger || []).filter(inMonth);
+    const sum = (kind) => rows.filter((r) => r.kind === kind).reduce((a, r) => a + (Number(r.amount_micro) || 0), 0);
+    const count = (kind) => rows.filter((r) => r.kind === kind).length;
+    const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+    const lines = [];
+    if (count('topup')) lines.push({ label: 'Added', value: `+${usd(sum('topup'))}`, tone: 'ok' });
+    if (count('capture')) lines.push({ label: `Spent on ${plural(count('capture'), 'request', 'requests')}`, value: usd(-sum('capture')), tone: '' });
+    if (count('release')) lines.push({ label: `Money back from ${plural(count('release'), 'failed request', 'failed requests')}`, value: `${usd(sum('release'))} returned`, tone: 'ok' });
+    if (count('own_key')) lines.push({ label: `On your own keys, ${plural(count('own_key'), 'request', 'requests')}`, value: 'free', tone: 'dim' });
+    return { month: d.toLocaleString('en', { month: 'long' }), lines };
+  }
+
+  // One line of the full ledger. `prompts` maps request id to its prompt.
+  function ledgerLine(row, prompts) {
+    const r = row || {};
+    const what = (r.request_id && prompts && prompts[String(r.request_id)])
+      ? quoteLine(prompts[String(r.request_id)], 40).slice(1, -1)
+      : 'A request';
+    const amt = Number(r.amount_micro) || 0;
+    switch (r.kind) {
+      case 'topup': return { what: 'Top up', detail: String(r.note || '').replace(/^card charged /, 'card '), value: `+${usd(amt)}`, tone: 'ok' };
+      case 'hold': return { what, detail: 'set aside while it ran', value: usd(amt), tone: 'dim' };
+      case 'capture': return { what, detail: `${usd(Number(r.provider_cost_micro) || 0)} + ${usd(Number(r.markup_micro) || 0)}`, value: usd(-amt), tone: '' };
+      case 'release': return { what, detail: 'failed, all money back', value: `${usd(amt)} returned`, tone: 'ok' };
+      case 'own_key': return { what, detail: 'your own key', value: 'free', tone: 'dim' };
+      default: return { what, detail: '', value: usd(amt), tone: '' };
+    }
+  }
+
+  // The model's reply as paragraphs, **bold** kept, everything else escaped by
+  // the hall's ONE escaper, handed in (window.OTB.escapeHtml in the page).
+  function replyHtml(md, escape) {
+    const text = String(md || '').replace(/\r\n/g, '\n').trim();
+    if (!text || typeof escape !== 'function') return '';
+    return text.split(/\n{2,}/).map((para) => {
+      const safe = escape(para.trim()).replace(/\*\*([^*\n]+)\*\*/g, '<b>$1</b>').replace(/\n/g, '<br>');
+      return `<p>${safe}</p>`;
+    }).join('');
+  }
+
+  // The home's AI action line: the newest request, while it is being made or
+  // when it finished in the last day, is what the line points at.
+  function homeLine(requests, now) {
+    const newest = (requests || [])[0];
+    const t = now instanceof Date ? now.getTime() : Date.now();
+    if (newest && (newest.status === 'queued' || newest.status === 'running')) {
+      return { detail: 'one is being made now', href: `/builders/ai-studio?request=${newest.id}` };
+    }
+    const fin = newest && newest.finished_at ? new Date(newest.finished_at).getTime() : NaN;
+    if (newest && newest.status === 'done' && t - fin < 24 * 3600 * 1000) {
+      return { detail: 'your newest pictures are ready', href: `/builders/ai-studio?request=${newest.id}` };
+    }
+    return { detail: 'sketches in, ideas and pictures out', href: '/builders/ai-studio' };
+  }
+
+  const lib = {
+    MAX_FILES, MAX_IMAGE_BYTES, MAX_PDF_BYTES, IMAGE_TYPES, PDF_TYPE, STEPS, TOPUP_CHOICES, ANSWER_AFTER_SEC,
+    usd, balanceUsd, sizeText, routeOf, checkFile, isImage, stepMarks, quoteLine, ownKey, payChoices,
+    waitSteps, clock, isFinished, receipt, againLine, monthSummary, ledgerLine, replyHtml, homeLine,
+  };
+  if (typeof module !== 'undefined' && module.exports) module.exports = lib;
+  if (root) root.OTBAiStudioLib = lib;
+})(typeof window !== 'undefined' ? window : null);