@bongos/core 1.23.21 → 1.24.1

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

@@ -0,0 +1,556 @@
+// modules/hall-ui/public/ai-studio.js — 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 (2026-10-29,
+// "when the image is made it needs the option to edit/update the prompt"): the
+// results page carries the request in an editable box, and "Make it again"
+// sends the changed words on the same files, paid the same way.
+//
+// One page, four views, each a full page in the studio's room (routeOf in
+// ai-studio-lib.js reads the address):
+//   ?step=pick       What are you starting from? Each file uploads as it is
+//                    picked, one per call (POST /ai-studio/uploads).
+//   ?step=describe   What should it make?
+//   ?step=make       How do you want to pay? A card press sends the request
+//                    (POST /ai-studio/requests) and opens its page.
+//   ?request=N       the waiting page (GET /ai-studio/requests/N, polled), then
+//                    the result: the pictures, the reply, the request to change
+//                    and make again, and the receipt.
+//   ?view=balance    what is left, add money (GET /ai-studio/topup/quote, POST
+//                    /ai-studio/topup), the month and every charge and refund.
+//
+// The draft (the picked files and the words) lives in sessionStorage, so the
+// three steps survive a reload and the back button. A key is NEVER asked for on
+// this page; the "add your own key" line links to Settings, the only place one
+// is entered.
+//
+// A file can go with one request only (the server's rule), so "Make it again"
+// and "Change files" carry the earlier request's uploads by their address and
+// upload a fresh copy of each when the new request is sent.
+
+(() => {
+  'use strict';
+
+  const API = '/api/bongos';
+  const lib = window.OTBAiStudioLib;
+  const studioLib = window.OTBStudioLib;
+  const api = window.BongosClient.createClient({ baseUrl: '', credentials: 'same-origin', throwOnError: false });
+  const toast = window.OTB.toast;
+  const esc = window.OTB.escapeHtml;
+
+  // The only writes this page makes, pinned in tests/hall_ai_studio.mjs. None
+  // of them carries a key.
+  const WRITE_ROUTES = Object.freeze({
+    upload: () => `${API}/ai-studio/uploads`,
+    request: () => `${API}/ai-studio/requests`,
+    topup: () => `${API}/ai-studio/topup`,
+  });
+
+  const DRAFT_KEY = 'otb.ai-studio.draft';
+  const POLL_MS = 2500;
+  const SETTINGS_KEYS = '/builders/settings#ai-keys';
+
+  const page = document.getElementById('ais-page');
+  const main = document.getElementById('hall-main');
+  const fileInput = document.getElementById('ais-file');
+
+  const state = {
+    signedIn: false,
+    off: false,
+    keys: null,
+    balance: null,
+    route: null,
+    draft: readDraft(),
+    request: null,
+    pick: 0,            // which picture is shown big on the result
+    timers: [],
+    busy: false,
+    topup: { amount: 20, other: false, quote: null },
+  };
+
+  // ---- the draft ------------------------------------------------------------
+
+  function blankDraft() { return { files: [], prompt: '', from: null }; }
+  function readDraft() {
+    try {
+      const d = JSON.parse(sessionStorage.getItem(DRAFT_KEY) || 'null');
+      if (d && Array.isArray(d.files)) return { files: d.files.filter((f) => f && f.url), prompt: String(d.prompt || ''), from: d.from || null };
+    } catch (_) { /* private mode, or nothing saved */ }
+    return blankDraft();
+  }
+  function saveDraft() {
+    try {
+      const keep = { ...state.draft, files: state.draft.files.filter((f) => f.status === 'ready') };
+      sessionStorage.setItem(DRAFT_KEY, JSON.stringify(keep));
+    } catch (_) { /* the draft then lives only as long as the page */ }
+  }
+  function clearDraft() { state.draft = blankDraft(); saveDraft(); }
+  function readyFiles() { return state.draft.files.filter((f) => f.status === 'ready'); }
+
+  // ---- navigation -----------------------------------------------------------
+
+  function go(search, { replace = false } = {}) {
+    const url = `/builders/ai-studio${search ? `?${search}` : ''}`;
+    if (replace) history.replaceState(null, '', url); else history.pushState(null, '', url);
+    render({ focus: true });
+  }
+
+  function stopTimers() { state.timers.forEach((t) => clearInterval(t)); state.timers = []; }
+
+  function focusHead() {
+    const h = page.querySelector('[data-head]');
+    if (h) h.focus({ preventScroll: false });
+  }
+
+  async function render({ focus = false } = {}) {
+    stopTimers();
+    main.removeAttribute('data-making');
+    state.route = lib.routeOf(location.search);
+    main.setAttribute('data-view', state.route.view === 'step' ? state.route.step : state.route.view);
+    if (!state.signedIn) { paintNote('Sign in to make something with AI.'); return; }
+    if (state.off) { paintNote('Making things with AI is not switched on for this project.'); return; }
+    if (state.route.view === 'balance') await paintBalance();
+    else if (state.route.view === 'request') await openRequest(state.route.id);
+    else await paintStep(state.route.step, state.route.from);
+    if (focus) focusHead();
+  }
+
+  function backLink() {
+    return '<a class="st-doc__back ais-back" href="/builders/studio">← Studio</a>';
+  }
+
+  function paintNote(text) {
+    page.innerHTML = `${backLink()}<p class="ais-quiet ais-note" data-head tabindex="-1">${esc(text)}</p>`;
+  }
+
+  // ---- the three steps ------------------------------------------------------
+
+  function stepHead(step) {
+    const marks = lib.stepMarks(step).map((m) => `<span class="ais-mark ais-mark--${m.state}">${esc(m.text)}</span>`).join('');
+    return `<div class="ais-bar">${backLink()}<span class="ais-marks">${marks}</span></div>`;
+  }
+
+  function thumb(f, big) {
+    const cls = `ais-thumb${big ? ' ais-thumb--big' : ''}`;
+    if (lib.isImage(f.content_type) && f.url) return `<img class="${cls}" src="${esc(f.url)}" alt="">`;
+    return `<span class="${cls} ais-thumb--pdf" aria-hidden="true">PDF</span>`;
+  }
+
+  async function paintStep(step, from) {
+    if (from && state.draft.from !== from) await carryFrom(from);
+    const files = readyFiles();
+    if (step !== 'pick' && !files.length) { go('step=pick', { replace: true }); return; }
+    if (step === 'make' && !state.draft.prompt.trim()) { go('step=describe', { replace: true }); return; }
+    if (step === 'pick') paintPick();
+    else if (step === 'describe') paintDescribe();
+    else await paintMake();
+  }
+
+  // "Change files" from a result: that request's uploads, carried by address,
+  // and its words, so the steps open where the artist left them.
+  async function carryFrom(id) {
+    const res = await api.request('GET', `${API}/ai-studio/requests/${id}`);
+    if (!res.ok || !res.data || !res.data.request) return;
+    const r = res.data.request;
+    const prompt = state.draft.from === null && state.draft.prompt ? state.draft.prompt : r.prompt;
+    state.draft = {
+      files: (r.files || []).filter((f) => f.role === 'upload').map((f) => ({
+        id: null, url: f.url, name: f.name, size_bytes: f.size_bytes, content_type: f.content_type, status: 'ready', carried: true,
+      })),
+      prompt: String(prompt || ''),
+      from: id,
+    };
+    saveDraft();
+  }
+
+  function paintPick() {
+    const files = state.draft.files;
+    const rows = files.map((f, i) => {
+      const right = f.status === 'uploading' ? '<span class="ais-dim">uploading…</span>'
+        : f.status === 'error' ? `<span class="ais-err-inline">${esc(f.error || 'could not be sent')}</span>`
+          : `<span class="ais-dim">${esc(lib.sizeText(f.size_bytes))}</span>`;
+      return `<li class="ais-row">${thumb(f)}<span class="ais-grow">${esc(f.name || 'file')}</span>${right}<button type="button" class="ais-remove" data-remove="${i}">remove</button></li>`;
+    }).join('');
+    const ready = readyFiles().length;
+    const uploading = files.some((f) => f.status === 'uploading');
+    page.innerHTML = `${stepHead('pick')}
+      <h1 class="ais-ask" data-head tabindex="-1">What are you starting from?</h1>
+      <div class="ais-drop" id="ais-drop">
+        <span>Drop sketches, pictures or a PDF here, or <button type="button" class="ais-link" id="ais-choose">choose files</button></span>
+        <span class="ais-dim">Up to ${lib.MAX_FILES}. Pictures up to 4 MB, PDFs up to 8 MB.</span>
+      </div>
+      ${rows ? `<ul class="ais-rows">${rows}</ul>` : ''}
+      <div class="ais-go">
+        <button type="button" class="ais-btn" id="ais-next" ${ready && !uploading ? '' : 'disabled'}>Next</button>
+        <span class="ais-faint">${ready ? `${ready} ${ready === 1 ? 'file' : 'files'} ready` : ''}</span>
+      </div>`;
+    page.querySelector('#ais-choose').addEventListener('click', () => fileInput.click());
+    const drop = page.querySelector('#ais-drop');
+    drop.addEventListener('dragover', (ev) => { ev.preventDefault(); drop.classList.add('ais-drop--over'); });
+    drop.addEventListener('dragleave', () => drop.classList.remove('ais-drop--over'));
+    drop.addEventListener('drop', (ev) => {
+      ev.preventDefault();
+      drop.classList.remove('ais-drop--over');
+      addFiles(ev.dataTransfer ? ev.dataTransfer.files : []);
+    });
+    page.querySelectorAll('[data-remove]').forEach((b) => b.addEventListener('click', () => {
+      state.draft.files.splice(Number(b.getAttribute('data-remove')), 1);
+      saveDraft();
+      paintPick();
+    }));
+    page.querySelector('#ais-next').addEventListener('click', () => go('step=describe'));
+  }
+
+  function readBase64(blob) {
+    return new Promise((resolve, reject) => {
+      const r = new FileReader();
+      r.onload = () => resolve(String(r.result).replace(/^data:[^,]*,/, ''));
+      r.onerror = () => reject(new Error('read failed'));
+      r.readAsDataURL(blob);
+    });
+  }
+
+  async function uploadBlob(blob, name, contentType) {
+    const data = await readBase64(blob);
+    const res = await api.request('POST', WRITE_ROUTES.upload(), { body: { name, content_type: contentType, data } });
+    if (!res.ok || !res.data || !res.data.file) {
+      const msg = res.data && res.data.error && res.data.error.message;
+      throw new Error(msg || 'could not be sent');
+    }
+    return res.data.file;
+  }
+
+  function addFiles(list) {
+    for (const file of Array.from(list || [])) {
+      const entry = { id: null, url: '', name: file.name, size_bytes: file.size, content_type: file.type, status: 'uploading' };
+      const no = lib.checkFile(file, state.draft.files.filter((f) => f.status !== 'error').length);
+      if (no) { entry.status = 'error'; entry.error = no; state.draft.files.push(entry); continue; }
+      state.draft.files.push(entry);
+      uploadBlob(file, file.name, file.type).then((f) => {
+        Object.assign(entry, { id: f.id, url: f.url, size_bytes: f.size_bytes, status: 'ready' });
+      }).catch((err) => {
+        Object.assign(entry, { status: 'error', error: err.message });
+      }).finally(() => { saveDraft(); if (state.route.view === 'step' && state.route.step === 'pick') paintPick(); });
+    }
+    if (state.route.view === 'step' && state.route.step === 'pick') paintPick();
+  }
+
+  function paintDescribe() {
+    page.innerHTML = `${stepHead('describe')}
+      <h1 class="ais-ask"><label for="ais-prompt" data-head tabindex="-1">What should it make?</label></h1>
+      <textarea class="ais-field ais-field--tall" id="ais-prompt" maxlength="4000" placeholder="Say what you want, in your own words."></textarea>
+      <p class="ais-faint">Your project's look and words are added for you, so you don't need to describe them.</p>
+      <div class="ais-go">
+        <button type="button" class="ais-btn" id="ais-next">Next</button>
+        <button type="button" class="ais-ghost" id="ais-back">Back</button>
+      </div>`;
+    const box = page.querySelector('#ais-prompt');
+    const next = page.querySelector('#ais-next');
+    box.value = state.draft.prompt;
+    const sync = () => { next.disabled = !box.value.trim(); };
+    sync();
+    box.addEventListener('input', () => { state.draft.prompt = box.value; saveDraft(); sync(); });
+    next.addEventListener('click', () => go('step=make'));
+    page.querySelector('#ais-back').addEventListener('click', () => go('step=pick'));
+  }
+
+  async function loadKeysAndBalance() {
+    const [k, b] = await Promise.all([
+      api.request('GET', `${API}/ai-studio/keys`),
+      api.request('GET', `${API}/ai-studio/balance`),
+    ]);
+    state.keys = k.ok ? k.data : null;
+    state.balance = b.ok ? b.data : null;
+  }
+
+  async function paintMake() {
+    await loadKeysAndBalance();
+    const files = readyFiles();
+    const c = lib.payChoices(state.keys, state.balance);
+    const thumbs = files.slice(0, 3).map((f) => thumb(f)).join('');
+    const ownCard = c.own ? `
+      <button type="button" class="st-action ais-card ais-card--own" data-pay="own">
+        <span class="st-action__label">My own key</span>
+        <span class="ais-card__line">Free here. ${esc(c.own.billedBy)} bills you for it directly.</span>
+        <span class="ais-card__foot">${esc(c.own.name)} key ending ${esc(c.own.last4 || '')}</span>
+      </button>` : '';
+    const balanceCard = c.payments ? `
+      <button type="button" class="st-action ais-card ais-card--ours" data-pay="ours" ${c.short ? 'disabled' : ''}>
+        <span class="st-action__label">My balance</span>
+        <span class="ais-card__line">Usually a few cents. Up to ${esc(c.setAside)} is set aside, and the rest comes back.</span>
+        <span class="ais-card__foot">${esc(c.left)}</span>
+      </button>` : '';
+    let foot = 'You only pay for what it really cost. If it fails, nothing is taken.';
+    let extra = '';
+    if (c.payments && c.short) extra = `<p class="ais-faint">Your balance is under ${esc(c.setAside)}. <a href="/builders/ai-studio?view=balance">Add money</a> to pay this way.</p>`;
+    if (!c.own) extra += `<p class="ais-faint">Have your own OpenRouter or Gemini key? <a href="${SETTINGS_KEYS}">Add it in Settings</a> and make things for free here.</p>`;
+    if (!c.own && !c.payments) foot = 'Paying from a balance is not set up here yet, so add your own key in Settings to make something.';
+    page.innerHTML = `${stepHead('make')}
+      <h1 class="ais-ask" data-head tabindex="-1">How do you want to pay?</h1>
+      <div class="ais-row ais-row--summary">${thumbs}<span class="ais-grow ais-soft">${esc(lib.quoteLine(state.draft.prompt))}</span><a class="ais-link" href="/builders/ai-studio?step=describe" data-nav="step=describe">change</a></div>
+      ${ownCard || balanceCard ? `<div class="ais-cards">${ownCard}${balanceCard}</div>` : ''}
+      <p class="ais-faint">${esc(foot)}</p>
+      ${extra}
+      <p class="ais-err" id="ais-err" role="alert" hidden></p>`;
+    page.querySelectorAll('[data-pay]').forEach((b) => b.addEventListener('click', () => sendRequest(b.getAttribute('data-pay'), state.draft.prompt, readyFiles(), b)));
+    wireNavLinks();
+  }
+
+  // Same-page links move through history, so the steps keep the back button.
+  function wireNavLinks() {
+    page.querySelectorAll('[data-nav]').forEach((a) => a.addEventListener('click', (ev) => {
+      ev.preventDefault();
+      go(a.getAttribute('data-nav'));
+    }));
+  }
+
+  function showError(text) {
+    const el = page.querySelector('#ais-err');
+    if (el) { el.textContent = text; el.hidden = false; } else toast(text);
+  }
+
+  // Sends one request: uploads a copy of each carried file first (a file can
+  // go with one request only), then the request itself, then opens its page.
+  async function sendRequest(payWith, prompt, files, button) {
+    if (state.busy) return;
+    if (!String(prompt || '').trim()) { showError('Say what it should make first.'); return; }
+    state.busy = true;
+    const buttons = page.querySelectorAll('button');
+    buttons.forEach((b) => { b.disabled = true; });
+    if (button) button.setAttribute('aria-busy', 'true');
+    try {
+      const ids = [];
+      for (const f of files) {
+        if (f.id && !f.carried) { ids.push(f.id); continue; }
+        const got = await fetch(f.url, { credentials: 'same-origin' });
+        if (!got.ok) throw new Error(`${f.name || 'A file'} could not be read again. Pick it again.`);
+        const copy = await uploadBlob(await got.blob(), f.name, f.content_type);
+        ids.push(copy.id);
+      }
+      const res = await api.request('POST', WRITE_ROUTES.request(), { body: { prompt: String(prompt).trim(), file_ids: ids, pay_with: payWith } });
+      if (!res.ok || !res.data || !res.data.request) {
+        const msg = res.data && res.data.error && res.data.error.message;
+        throw new Error(msg || 'The request could not be sent. Try again.');
+      }
+      clearDraft();
+      state.busy = false;
+      go(`request=${res.data.request.id}`);
+    } catch (err) {
+      state.busy = false;
+      buttons.forEach((b) => { b.disabled = false; });
+      if (button) button.removeAttribute('aria-busy');
+      showError(err.message);
+    }
+  }
+
+  // ---- a request: waiting, then the result ----------------------------------
+
+  async function fetchRequest(id) {
+    const res = await api.request('GET', `${API}/ai-studio/requests/${id}`);
+    return res.ok && res.data ? res.data.request : null;
+  }
+
+  async function openRequest(id) {
+    const req = await fetchRequest(id);
+    if (!req) { paintNote('That request could not be found.'); return; }
+    state.request = req;
+    state.pick = 0;
+    if (lib.isFinished(req.status)) { await paintResult(req); return; }
+    paintWaiting(req);
+    const opened = Date.now();
+    const started = Date.parse(req.created_at);
+    const base = Number.isFinite(started) && started <= opened ? started : opened;
+    const tick = () => paintWaitingClock(req, (Date.now() - base) / 1000);
+    tick();
+    state.timers.push(setInterval(tick, 1000));
+    state.timers.push(setInterval(async () => {
+      const next = await fetchRequest(id);
+      if (!next || state.route.view !== 'request' || state.route.id !== id) return;
+      Object.assign(req, next);
+      if (lib.isFinished(next.status)) { stopTimers(); main.removeAttribute('data-making'); await paintResult(next); focusHead(); }
+    }, POLL_MS));
+  }
+
+  function paintWaiting(req) {
+    main.setAttribute('data-making', 'on');
+    page.innerHTML = `${backLink()}
+      <div class="ais-wait">
+        <h1 class="ais-clock" data-head tabindex="-1"><span id="ais-clock">0:00</span><span class="ais-sr"> so far</span></h1>
+        <p class="ais-soft">usually done in about a minute</p>
+        <ul class="ais-checks" id="ais-checks" aria-live="polite"></ul>
+        <p class="ais-faint">The lamp stays on until it's done. You can close this page; the result waits in your studio.</p>
+      </div>`;
+  }
+
+  function paintWaitingClock(req, sec) {
+    const clockEl = page.querySelector('#ais-clock');
+    if (clockEl) clockEl.textContent = lib.clock(sec);
+    const list = page.querySelector('#ais-checks');
+    if (!list) return;
+    const uploads = (req.files || []).filter((f) => f.role === 'upload').length;
+    const html = lib.waitSteps(req.status, sec, uploads || 1).map((s) => `<li class="ais-check ais-check--${s.state}"><span class="ais-check__mark" aria-hidden="true">${s.state === 'done' ? '✓' : ''}</span><span>${esc(s.text)}</span>${s.state === 'done' ? '<span class="ais-sr"> (done)</span>' : ''}</li>`).join('');
+    if (list.innerHTML !== html) list.innerHTML = html;
+  }
+
+  async function paintResult(req) {
+    if (!state.balance) await loadKeysAndBalance();
+    const outputs = (req.files || []).filter((f) => f.role === 'output' && lib.isImage(f.content_type));
+    const uploads = (req.files || []).filter((f) => f.role === 'upload');
+    const pick = Math.min(state.pick, Math.max(0, outputs.length - 1));
+    const big = outputs[pick];
+    const thumbs = outputs.length > 1 ? outputs.map((f, i) => `<button type="button" class="ais-pick${i === pick ? ' ais-pick--on' : ''}" data-pick="${i}" aria-label="Picture ${i + 1}" aria-pressed="${i === pick}"><img src="${esc(f.url)}" alt=""></button>`).join('') : '';
+    const rc = lib.receipt(req, state.balance && state.balance.price_multiplier);
+    const receiptHtml = rc.rows.length ? `<div class="ais-receipt">${rc.rows.map(([k, v]) => `<div class="ais-line"><span class="ais-grow">${esc(k)}</span><span>${esc(v)}</span></div>`).join('')}${rc.note ? `<div class="ais-line"><span class="ais-grow ais-faint ais-wrap">${esc(rc.note)}</span></div>` : ''}</div>` : '';
+    const failed = req.status !== 'done';
+    main.setAttribute('data-view', 'result');
+    page.innerHTML = `
+      <h1 class="ais-sr" data-head tabindex="-1">${failed ? 'That did not work' : 'Your result'}</h1>
+      <div class="ais-result">
+        <div class="ais-result__art">
+          ${backLink()}
+          ${big ? `<img class="ais-big" src="${esc(big.url)}" alt="Picture ${pick + 1} made from your request">` : `<div class="ais-big ais-big--none"><span class="ais-faint">${failed ? 'No picture this time.' : 'An answer only, no picture this time.'}</span></div>`}
+          <div class="ais-thumbs">${thumbs}<span class="ais-grow"></span>${big ? `<a class="ais-ghost" href="${esc(big.url)}" download>Save picture</a>` : ''}</div>
+        </div>
+        <div class="ais-result__words">
+          ${failed ? `<p class="ais-err">${esc(req.error || 'It did not work, and nothing was charged.')}</p>` : ''}
+          <div class="ais-reply">${lib.replyHtml(req.reply_md, esc)}</div>
+          <div class="ais-again">
+            <label class="ais-head" for="ais-again">Your request</label>
+            <textarea class="ais-field" id="ais-again" maxlength="4000"></textarea>
+            <p class="ais-faint">${esc(lib.againLine(uploads.length))}</p>
+            <div class="ais-go ais-go--wrap">
+              <button type="button" class="ais-btn" id="ais-remake">Make it again</button>
+              <a class="ais-ghost" href="/builders/ai-studio?step=pick&amp;from=${esc(req.id)}" id="ais-change">Change files</a>
+              <a class="ais-ghost" href="/builders/ai-studio?step=pick" id="ais-new">Start something new</a>
+            </div>
+            <p class="ais-err" id="ais-err" role="alert" hidden></p>
+          </div>
+          ${receiptHtml}
+        </div>
+      </div>`;
+    const box = page.querySelector('#ais-again');
+    box.value = req.prompt || '';
+    page.querySelectorAll('[data-pick]').forEach((b) => b.addEventListener('click', () => { state.pick = Number(b.getAttribute('data-pick')); paintResult(req); }));
+    const carried = uploads.map((f) => ({ id: null, url: f.url, name: f.name, size_bytes: f.size_bytes, content_type: f.content_type, status: 'ready', carried: true }));
+    page.querySelector('#ais-remake').addEventListener('click', (ev) => {
+      sendRequest(req.key_source === 'own' ? 'own' : 'ours', box.value, carried, ev.currentTarget);
+    });
+    page.querySelector('#ais-change').addEventListener('click', (ev) => {
+      ev.preventDefault();
+      state.draft = { files: carried, prompt: box.value, from: req.id };
+      saveDraft();
+      go('step=pick');
+    });
+    page.querySelector('#ais-new').addEventListener('click', (ev) => { ev.preventDefault(); clearDraft(); go('step=pick'); });
+  }
+
+  // ---- the balance ----------------------------------------------------------
+
+  async function paintBalance() {
+    const [b, r] = await Promise.all([
+      api.request('GET', `${API}/ai-studio/balance`),
+      api.request('GET', `${API}/ai-studio/requests`),
+    ]);
+    state.balance = b.ok ? b.data : null;
+    const data = state.balance || {};
+    const prompts = {};
+    for (const q of (r.ok && r.data && r.data.requests) || []) prompts[q.id] = q.prompt;
+    const payments = !!data.balance;
+    const sum = lib.monthSummary(data.ledger || [], new Date());
+    const all = state.route.all;
+    const t = state.topup;
+    const chips = lib.TOPUP_CHOICES.map((n) => `<button type="button" class="ais-chip" data-amount="${n}" aria-pressed="${!t.other && t.amount === n}">$${n}</button>`).join('')
+      + `<button type="button" class="ais-chip" data-amount="other" aria-pressed="${t.other}">other</button>`;
+    const topupHtml = payments ? `
+      <div class="ais-topup">
+        <span class="ais-soft" id="ais-topup-label">Add how much?</span>
+        <div class="ais-chips" role="group" aria-labelledby="ais-topup-label">${chips}</div>
+        ${t.other ? `<label class="ais-other"><span class="ais-faint">Amount in dollars</span><input type="number" id="ais-other" min="5" max="500" step="1" value="${esc(t.amount)}"></label>` : ''}
+        <div class="ais-go"><button type="button" class="ais-btn" id="ais-add">Add $${esc(t.amount)}</button><span class="ais-faint" id="ais-quote"></span></div>
+        <p class="ais-err" id="ais-err" role="alert" hidden></p>
+        ${data.test_mode ? '<p class="ais-faint">Test mode: no real money moves.</p>' : ''}
+      </div>` : '<p class="ais-faint">Paying from a balance is not set up here yet. You can still make things on your own key: <a href="/builders/settings#ai-keys">add it in Settings</a>.</p>';
+    const monthLines = sum.lines.map((l) => `<div class="ais-line"><span class="ais-grow">${esc(l.label)}</span><span class="ais-num ais-tone-${l.tone || 'plain'}">${esc(l.value)}</span></div>`).join('')
+      || '<div class="ais-line"><span class="ais-grow ais-faint">Nothing yet this month.</span></div>';
+    const fmtDate = (s) => { const d = new Date(s); return Number.isNaN(d.getTime()) ? '' : d.toLocaleDateString('en', { month: 'short', day: 'numeric' }); };
+    const allLines = (data.ledger || []).map((row) => {
+      const l = lib.ledgerLine(row, prompts);
+      const what = row.request_id ? `<a href="/builders/ai-studio?request=${esc(row.request_id)}">${esc(l.what)}</a>` : esc(l.what);
+      return `<div class="ais-line"><span class="ais-date">${esc(fmtDate(row.created_at))}</span><span class="ais-grow">${what}</span><span class="ais-faint ais-detail">${esc(l.detail)}</span><span class="ais-num ais-tone-${l.tone || 'plain'}">${esc(l.value)}</span></div>`;
+    }).join('');
+    page.innerHTML = `${backLink()}
+      <div class="ais-balance">
+        ${payments ? `<h1 class="ais-figure" data-head tabindex="-1"><span class="ais-big-num">${esc(lib.balanceUsd(data.balance.available_micro))}</span> <span class="ais-soft">left</span></h1>` : '<h1 class="ais-sr" data-head tabindex="-1">Your AI balance</h1>'}
+        ${topupHtml}
+        <div class="ais-ledger">
+          <span class="ais-head">${esc(sum.month)}</span>
+          ${monthLines}
+          <div class="ais-line"><a class="ais-link" href="/builders/ai-studio?view=balance${all ? '' : '&amp;all=1'}" data-nav="view=balance${all ? '' : '&all=1'}">${all ? 'Show this month only' : 'See every charge and refund →'}</a></div>
+          ${all ? (allLines ? `<div class="ais-all">${allLines}</div>` : '<p class="ais-faint">No charges or refunds yet.</p>') : ''}
+        </div>
+      </div>`;
+    wireNavLinks();
+    if (!payments) return;
+    page.querySelectorAll('[data-amount]').forEach((btn) => btn.addEventListener('click', () => {
+      const v = btn.getAttribute('data-amount');
+      if (v === 'other') { t.other = true; } else { t.other = false; t.amount = Number(v); }
+      paintBalance().then(() => { const o = page.querySelector('#ais-other'); if (o) o.focus(); });
+    }));
+    const other = page.querySelector('#ais-other');
+    if (other) other.addEventListener('change', () => { t.amount = Math.round(Number(other.value) || 0); paintBalance(); });
+    page.querySelector('#ais-add').addEventListener('click', addMoney);
+    quote(t.amount);
+  }
+
+  async function quote(amount) {
+    const el = page.querySelector('#ais-quote');
+    const res = await api.request('GET', `${API}/ai-studio/topup/quote?amount_usd=${encodeURIComponent(amount)}`);
+    if (!el) return;
+    if (!res.ok || !res.data || !res.data.quote) {
+      el.textContent = (res.data && res.data.error && res.data.error.message) || '';
+      const add = page.querySelector('#ais-add');
+      if (add) add.disabled = true;
+      return;
+    }
+    const q = res.data.quote;
+    el.textContent = `${lib.usd(q.credited_micro)} lands in your balance; your card is charged ${lib.usd(q.charge_micro)}.`;
+  }
+
+  async function addMoney(ev) {
+    if (state.busy) return;
+    state.busy = true;
+    const btn = ev.currentTarget;
+    btn.disabled = true;
+    const res = await api.request('POST', WRITE_ROUTES.topup(), { body: { amount_usd: state.topup.amount } });
+    state.busy = false;
+    if (!res.ok) {
+      btn.disabled = false;
+      showError((res.data && res.data.error && res.data.error.message) || 'The money could not be added. Try again.');
+      return;
+    }
+    toast(`Added ${lib.usd(res.data.topup.credited_micro)}.`);
+    await paintBalance();
+  }
+
+  // ---- the sky, and boot ----------------------------------------------------
+
+  function paintSky() {
+    if (studioLib && document.body) document.body.setAttribute('data-sky', studioLib.skyAt(new Date()));
+  }
+
+  fileInput.addEventListener('change', () => { addFiles(fileInput.files); fileInput.value = ''; });
+  window.addEventListener('popstate', () => render({ focus: true }));
+
+  (async () => {
+    paintSky();
+    setInterval(paintSky, 60000);
+    const me = await api.request('GET', `${API}/me`);
+    state.signedIn = !!me.ok;
+    if (state.signedIn) {
+      const status = await api.request('GET', `${API}/ai-studio/status`);
+      state.off = !status.ok;
+    }
+    await render();
+  })();
+})();

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

@@ -0,0 +1,94 @@
+{
+  "_": "The studio's AI pages (task 1004921, goal 1000136), built 1:1 on option C of the AI Studio options canvas plus the owner's addition (change the request on the result and make it again). Against the kit's own stub the page renders its could-not-read states (no ai-studio feeds). TO SEE IT POPULATED, point the kit at the hall-preview harness with the module on: `node scripts/hall-preview/server.js --port 4637 --fixture-me --modules-on ai-studio` then `render.js --base-in http://builders.localhost:4637 --base-out http://builders.localhost:4637`. The harness answers keys, balance, the top-up quote and the request list from the ai-studio__*.json fixtures; a request by id (1002 running, 1003 failed, 1004 own Gemini key, any other the finished result on the balance); an upload, a request and a top-up from its CANNED WRITES; and every file as a stand-in picture. ?from=1001 opens the steps on that request's files and words, which is how the populated steps render without an upload.",
+  "page": "/builders/ai-studio",
+  "surface": "hall-ui",
+  "stub": {
+    "prefix": "/builders/"
+  },
+  "modeQuery": false,
+  "ignoreRequests": [
+    "/api/(gds|bongos)/me$",
+    "/api/(gds|bongos)/me/",
+    "/api/(gds|bongos)/ai-studio/",
+    "/api/(gds|bongos)/core-update"
+  ],
+  "ignoreConsole": [
+    "/api/(gds|bongos)/",
+    "\\b401\\b",
+    "\\b403\\b",
+    "\\b404\\b",
+    "\\b501\\b",
+    "Unauthorized",
+    "Forbidden",
+    "Not Found",
+    "load failed"
+  ],
+  "states": {
+    "pick": {
+      "auth": true,
+      "_": "Step 1: what are you starting from, with the three files of request 1001.",
+      "url": "/builders/ai-studio?step=pick&from=1001",
+      "actions": [["wait", 900]],
+      "expect": { "visible": ["#ais-page h1", ".ais-drop", ".ais-rows"] }
+    },
+    "describe": {
+      "auth": true,
+      "_": "Step 2: what should it make.",
+      "url": "/builders/ai-studio?step=describe&from=1001",
+      "actions": [["wait", 900]],
+      "expect": { "visible": ["#ais-prompt"] }
+    },
+    "make": {
+      "auth": true,
+      "_": "Step 3: how do you want to pay, the own-key card and the balance card.",
+      "url": "/builders/ai-studio?step=make&from=1001",
+      "actions": [["wait", 1200]],
+      "expect": { "visible": [".ais-card--own", ".ais-card--ours"] }
+    },
+    "waiting": {
+      "auth": true,
+      "_": "The waiting page: the clock, the three lines, the lamp on.",
+      "url": "/builders/ai-studio?request=1002",
+      "actions": [["wait", 1500]],
+      "expect": { "visible": ["#ais-clock", "#ais-checks"] }
+    },
+    "result": {
+      "auth": true,
+      "_": "The result on the balance: the picture, the reply, the request to change and make again, the receipt with the provider's cost and our markup apart.",
+      "url": "/builders/ai-studio?request=1001",
+      "actions": [["wait", 1200]],
+      "expect": { "visible": [".ais-big", "#ais-again", "#ais-remake", ".ais-receipt"] }
+    },
+    "result-own": {
+      "auth": true,
+      "_": "A result on the builder's own Gemini key: cost not reported, nothing charged.",
+      "url": "/builders/ai-studio?request=1004",
+      "actions": [["wait", 1200]],
+      "expect": { "visible": [".ais-receipt", "#ais-again"] }
+    },
+    "failed": {
+      "auth": true,
+      "_": "A failed run: the error in words, no receipt, the request to try again.",
+      "url": "/builders/ai-studio?request=1003",
+      "actions": [["wait", 1200]],
+      "expect": { "visible": [".ais-err", "#ais-remake"] }
+    },
+    "balance": {
+      "auth": true,
+      "_": "The balance: what is left, add money with the card charge, this month.",
+      "url": "/builders/ai-studio?view=balance",
+      "actions": [["wait", 1200]],
+      "expect": { "visible": [".ais-big-num", "#ais-add", ".ais-ledger"] }
+    },
+    "balance-all": {
+      "auth": true,
+      "_": "Every charge and refund.",
+      "url": "/builders/ai-studio?view=balance&all=1",
+      "actions": [["wait", 1200]],
+      "expect": { "visible": [".ais-all"] }
+    },
+    "out": {
+      "auth": false
+    }
+  }
+}