@bongos/core 1.17.0

package/modules/hall-ui/public/box-panel.js

@@ -0,0 +1,423 @@
+// public-builders/box-panel.js — the shared dev-box management panel.
+//
+// One self-serve control surface for a builder's OWN hosted dev box: request
+// (provision), open the in-browser terminal, see connection details, and close
+// the box. It is driven by LIVE SERVER STATE (GET /box/me + GET /box/terminal),
+// repainted on every mount and kept fresh by a single self-rescheduling poll
+// while anything is in flight (provisioning / waking / closing / tunnel warming
+// up). The poll stops once the box settles.
+//
+// It is used in two places (#807 / ADR 0040 — moving box mgmt into Settings):
+//   * the #777 onboarding welcome panel, in browser-only mode → showSsh:false
+//     (online terminal only — a newcomer never sees raw SSH details);
+//   * the Settings page → showSsh:true (both the online terminal AND the SSH
+//     IP + command, so a builder can drive their box however they like).
+//
+// Behaviour is identical in both; the ONLY difference is whether the SSH rows
+// are shown. The terminal credential is a secret returned only to the box's own
+// builder by GET /box/terminal — shown to that builder, never logged.
+//
+// Usage:
+//   const panel = OTBBoxPanel.create({ api: '/api/bongos', showSsh: true, toast });
+//   panel.mount(containerEl);   // injects markup, wires clicks, paints state
+//   panel.refresh();            // repaint from server (e.g. on un-minimise)
+//   panel.stop();               // stop polling (e.g. on dismiss / minimise)
+//
+// The container element should carry the `.setup__box` class for styling. mount
+// is re-entrant: calling it again (e.g. after the host re-renders its DOM)
+// re-binds to the new element and cancels any prior poll.
+
+(function () {
+  'use strict';
+
+  // escapeHtml now comes from the shared window.OTB toolkit (dom-utils.js,
+  // loaded first on every page that mounts this panel). q / getJSON / postJSON
+  // and the injected toast stay local — they carry per-panel behaviour.
+  const { escapeHtml } = window.OTB;
+
+  // ttyd's HTTP-basic username is the fixed `otb` user (box-terminal.service:
+  // --credential "otb:<pass>"); the password is the long hex `credential`.
+  const TERMINAL_USER = 'otb';
+
+  // Terminal URL with the basic-auth userinfo embedded, so "Open online
+  // environment" lands signed-in (browsers honor user:pass@host for top-level
+  // navigation; ttyd auth is plain HTTP basic). The credential is already
+  // displayed in plaintext on this panel, so the href adds no new exposure.
+  function terminalAuthUrl(term) {
+    if (!term || !term.url) return null;
+    if (!term.credential) return term.url;
+    try {
+      const u = new URL(term.url);
+      u.username = TERMINAL_USER;
+      u.password = term.credential;
+      return u.toString();
+    } catch (_) {
+      return term.url;
+    }
+  }
+
+  function create(opts) {
+    opts = opts || {};
+    const API = opts.api || '/api/bongos';
+    // Generated typed client (task 1996 / R09), served as window.BongosClient by
+    // /lib/bongos-client.js. baseUrl:'' passes the full same-origin paths this file
+    // builds through unchanged; result-mode ({ status, ok, data }) preserves control flow 1:1.
+    const api = window.BongosClient.createClient({ baseUrl: '', credentials: 'same-origin', throwOnError: false });
+    const showSsh = !!opts.showSsh;
+    const toast = typeof opts.toast === 'function' ? opts.toast : function () {};
+
+    let root = null;            // the mounted container element
+    let pollTimer = null;       // self-rescheduling refresh timer
+    let termWindow = null;      // handle to the opened terminal tab (to close it)
+    let bound = false;          // whether we've attached our click listener
+
+    const AUTH_REDIRECT = 'redirecting to auth';
+
+    async function getJSON(path) {
+      const res = await api.request('GET', path);
+      if (res.status === 401) { window.location.assign(`${API}/auth/web/start`); throw new Error(AUTH_REDIRECT); }
+      if (!res.ok) throw new Error(`${path} → ${res.status}`);
+      return res.data;
+    }
+    async function postJSON(path) {
+      const res = await api.request('POST', path);
+      if (res.status === 401) { window.location.assign(`${API}/auth/web/start`); throw new Error(AUTH_REDIRECT); }
+      if (!res.ok) {
+        let detail = `${path} → ${res.status}`;
+        try { const j = res.data; detail = j.message || j.detail || j.error || detail; } catch (_) { /* keep default */ }
+        const err = new Error(detail); err.status = res.status; throw err;
+      }
+      return res.data;
+    }
+
+    // ---- DOM helpers (scoped to `root`) ------------------------------------
+    const q = (sel) => (root ? root.querySelector(sel) : null);
+    // NOTE: the `.setup__box-out` (display:flex) and `.setup__btn` (display:
+    // inline-block) rules out-specify the UA `[hidden]{display:none}` rule, so
+    // toggling the `hidden` attribute alone leaves an empty bordered stub / a
+    // stale "Request dev box" button visible. Drive `display` directly to hide.
+    function setOut(html) { const out = q('[data-box-out]'); if (out) { out.hidden = false; out.style.display = ''; out.innerHTML = html; } }
+    function hideOut() { const out = q('[data-box-out]'); if (out) { out.hidden = true; out.style.display = 'none'; out.innerHTML = ''; } }
+    function setRequestBtn(visible, label) {
+      const btn = q('[data-box-request]');
+      if (!btn) return;
+      btn.hidden = !visible;
+      btn.style.display = visible ? '' : 'none';
+      if (visible) { btn.disabled = false; btn.textContent = label || 'Request dev box'; }
+    }
+    function enableOpenBtn(url) {
+      const openBtn = q('[data-box-open]');
+      if (!openBtn) return;
+      if (url) {
+        openBtn.setAttribute('href', url);
+        openBtn.setAttribute('target', '_blank');
+        openBtn.setAttribute('rel', 'noopener noreferrer');
+        openBtn.removeAttribute('aria-disabled');
+      } else {
+        openBtn.removeAttribute('href');
+        openBtn.removeAttribute('target');
+        openBtn.removeAttribute('rel');
+        openBtn.setAttribute('aria-disabled', 'true');
+      }
+    }
+
+    function stopPoll() { if (pollTimer) { clearTimeout(pollTimer); pollTimer = null; } }
+    function schedulePoll(ms) { stopPoll(); pollTimer = setTimeout(() => { refresh(); }, ms || 5000); }
+
+    function closeTermWindow() {
+      if (termWindow && !termWindow.closed) {
+        try { termWindow.close(); } catch (_) { /* cross-origin or already gone */ }
+      }
+      termWindow = null;
+    }
+
+    // One credential/detail row. The value itself is click-to-copy (values are
+    // long) — no separate button.
+    function credRow(label, value) {
+      return `<div class="setup__cred-row">
+        <span class="setup__cred-k">${escapeHtml(label)}</span>
+        <code class="setup__cred-v setup__copy" data-copy="${escapeHtml(value)}" tabindex="0" role="button" title="Click to copy ${escapeHtml(label.toLowerCase())}" aria-label="Copy ${escapeHtml(label.toLowerCase())}">${escapeHtml(value)}</code>
+      </div>`;
+    }
+
+    // The default Close-box control. Clicking it ARMS a confirm step
+    // (armCloseConfirm) instead of closing immediately — task 1459: a fresh box
+    // gets a NEW SSH identity, so a newcomer who hits "Host denied" on reconnect
+    // tends to reflexively close + reopen again, which only rotates the identity
+    // once more and digs the hole deeper. The confirm names the real cure.
+    function closeSectionHtml() {
+      return '<button type="button" class="setup__btn setup__btn--danger" data-box-close>Close box</button>'
+        + '<span class="setup__box-close-hint">Stops and deletes your box. Provision a fresh one anytime.</span>';
+    }
+
+    // The armed confirm: the warning + a real Close + a Keep. The Desktop/"Host
+    // denied" line is phrased conditionally so browser-terminal-only builders
+    // (who never touch SSH host keys) naturally skip it.
+    function closeConfirmHtml() {
+      // .setup__box-close is a flex row; flex-basis:100% puts the warning on its
+      // own line so the two buttons wrap neatly beneath it.
+      return '<p class="setup__box-close-hint" style="flex-basis:100%;margin:0">Closing deletes this box. The fresh one you open next has a '
+        + '<strong>new identity</strong> — so if Claude Desktop then says <strong>&ldquo;Host denied&rdquo;</strong> '
+        + 'or asks for a password, fully quit and reopen Desktop (it re-pins your box automatically) or press '
+        + '<strong>Repair</strong>. Closing and reopening again will <em>not</em> help — it only changes the identity once more.</p>'
+        + '<button type="button" class="setup__btn setup__btn--danger" data-box-close-confirm>Close box</button> '
+        + '<button type="button" class="setup__btn" data-box-close-cancel>Keep box</button>';
+    }
+
+    // Swap the Close-box control between its default and armed states in place.
+    // Both operate on the enclosing .setup__box-close container, so a stray
+    // server repaint (which re-renders the default) just resets to "not armed".
+    function armCloseConfirm(btn) {
+      const wrap = btn.closest('.setup__box-close');
+      if (wrap) wrap.innerHTML = closeConfirmHtml();
+    }
+    function disarmCloseConfirm(btn) {
+      const wrap = btn.closest('.setup__box-close');
+      if (wrap) wrap.innerHTML = closeSectionHtml();
+    }
+
+    // Render the active-box panel. SSH rows (IP + connect command) only appear
+    // when showSsh is true AND the box has an IP — the onboarding panel hides
+    // them so a newcomer sees only the online terminal. The terminal rows show
+    // whenever the tunnel has published a URL. All users get a Close button.
+    function renderBoxActive(box, term, cost) {
+      const parts = ['<p class="setup__box-msg setup__box-msg--ok">Your dev box is ready.</p>'];
+
+      // idea 332 / task 1316 (ADR 0072): flag a box running old code. A box too
+      // old to self-update can't be fixed in place — only a rebuild (Close box →
+      // provision fresh) brings it onto current code. Points at the Close button
+      // below. The server decides `stale` (boxes.computeCodeStaleness).
+      if (box.code && box.code.stale) {
+        parts.push(
+          '<p class="setup__box-msg setup__box-msg--warn">⚠ This box is running <strong>old code</strong>, '
+          + 'which can break art generation and reconnecting. It can\'t update itself — '
+          + 'use <strong>Close box</strong> below, then provision a fresh one to bring it current.</p>'
+        );
+      }
+
+      if (showSsh && box.ip) {
+        parts.push(credRow('IP', box.ip));
+        parts.push(credRow('SSH', `ssh root@${box.ip}`));
+      }
+
+      if (term && term.url) {
+        if (showSsh && box.ip) parts.push('<hr class="setup__divider">');
+        parts.push(credRow('Terminal', term.url));
+        if (term.credential) {
+          parts.push(credRow('Username', TERMINAL_USER));
+          parts.push(credRow('Password', term.credential));
+        }
+        // #893: closing the terminal tab no longer kills the session (it runs in
+        // tmux on the box), and never shut the box down. Say both, so a builder
+        // neither fears losing work nor leaves the box billing thinking it's off.
+        parts.push('<p class="setup__box-close-hint">Closing the terminal tab keeps your session running — reopen to resume right where you left off. To shut the box down, use <strong>Close box</strong> below or type <code>close-box</code> in the terminal.</p>');
+      }
+
+      // #602: the builder's own running container-cost total. Tracked, not
+      // charged in the early stage (mirrors "shipped work isn't paid in real money
+      // yet") — say so plainly so the number doesn't read as a bill.
+      if (cost && Number(cost.total_usd) > 0) {
+        const f = (n) => `$${(Number(n) || 0).toFixed(2)}`;
+        parts.push('<hr class="setup__divider">');
+        parts.push(`<p class="setup__box-cost"><strong>What your box would cost:</strong> ${f(cost.total_usd)} so far `
+          + `<span class="setup__box-cost-detail">(spin-up ${f(cost.spinup_usd)} · compute ${f(cost.compute_usd)} · storage ${f(cost.storage_usd)})</span><br>`
+          + '<span class="setup__box-close-hint">Tracked for transparency — not charged in the early stage.</span></p>');
+      }
+
+      parts.push(`<div class="setup__box-close">${closeSectionHtml()}</div>`);
+
+      return parts.join('\n');
+    }
+
+    // Paint from live server state. Idempotent + safe to call repeatedly. Never
+    // throws into the caller. Stops polling once the element is gone.
+    async function refresh() {
+      if (!root || !document.body.contains(root)) { stopPoll(); return; }
+
+      let me;
+      try { me = await getJSON(`${API}/box/me`); }
+      catch (err) { if (err && err.message === AUTH_REDIRECT) return; stopPoll(); return; }
+      const box = (me && me.box) || {};
+      const intent = me && me.open_intent;
+      const state = box.state || 'none';
+
+      // A close is in flight: the box stays 'active' for up to a minute while
+      // the control-plane runner deprovisions it, so this MUST be checked
+      // BEFORE the active branch — otherwise every poll repaints the full active
+      // panel and wipes the "Closing…" feedback. Close the terminal tab now.
+      if (intent && intent.action === 'deprovision') {
+        closeTermWindow();
+        setRequestBtn(false);
+        enableOpenBtn(null);
+        setOut('<p class="setup__box-msg">Closing your box… (a few seconds)</p>');
+        schedulePoll(4000);
+        return;
+      }
+
+      if (state === 'active') {
+        let term = null;
+        try { term = await getJSON(`${API}/box/terminal`); }
+        catch (err) { if (err && err.message === AUTH_REDIRECT) return; }
+
+        setRequestBtn(false);
+        enableOpenBtn(terminalAuthUrl(term));
+
+        if (term && term.url) {
+          setOut(renderBoxActive(box, term, me && me.cost));
+          stopPoll();
+        } else if (term && term.warming_up) {
+          setOut('<p class="setup__box-msg">Your box is up — waiting for the terminal to come online (a few seconds after boot)…</p>');
+          schedulePoll(5000);
+        } else {
+          // SSH path (or tunnel not yet published). With SSH shown, surface the
+          // details now; either way keep polling so the terminal URL appears
+          // when it publishes.
+          setOut(renderBoxActive(box, null, me && me.cost));
+          if (!box.ip) schedulePoll(5000);
+          else if (!showSsh) schedulePoll(5000); // online-only: still awaiting terminal
+          else stopPoll();
+        }
+        return;
+      }
+      if (intent || state === 'provisioning' || state === 'waking') {
+        setRequestBtn(false);
+        enableOpenBtn(null);
+        setOut('<p class="setup__box-msg">Setting up your box… (about a minute)</p>');
+        schedulePoll(5000);
+        return;
+      }
+      // No open intent and not active/provisioning/waking. Two cases:
+      //   • destroyed → the builder HAD a box that is now gone — they closed it, or
+      //     it was auto-stopped after ~10 min idle, which tears down the tunnel + its
+      //     DNS. Opening the old terminal/sandbox URL then fails with a raw browser
+      //     "can't find the server" error and no explanation (idea #295). Don't leave
+      //     them staring at a bare button: say what happened + offer to turn it back on.
+      //   • none → never had a box (first run). Keep the clean first-run button.
+      closeTermWindow();
+      stopPoll();
+      enableOpenBtn(null);
+      if (state === 'destroyed') {
+        setRequestBtn(true, 'Turn box back on');
+        setOut('<p class="setup__box-msg">Your dev box is stopped — turn it back on below.</p>'
+          + '<p class="setup__box-close-hint">Boxes auto-stop after about 10 minutes idle to save cost '
+          + '(or when you close one). A stopped box has no terminal or live-preview URL, so an old '
+          + 'link will fail to load. Turning it back on takes about a minute. '
+          + '<strong>Anything not committed or shipped on the old box is gone</strong> — commit early next time.</p>'
+          + '<p class="setup__box-close-hint">The box you turn on has a <strong>new identity</strong>. If Claude '
+          + 'Desktop says <strong>&ldquo;Host denied&rdquo;</strong> or asks for a password when reconnecting, fully quit '
+          + 'and reopen Desktop (it re-pins your box automatically) or press <strong>Repair</strong> — do not keep turning '
+          + 'the box off and on, which only changes the identity again.</p>');
+        return;
+      }
+      setRequestBtn(true, 'Request dev box');
+      hideOut();
+    }
+
+    // Request the box (provision), then let refresh paint from server state.
+    async function requestBox() {
+      const btn = q('[data-box-request]');
+      if (btn) { btn.disabled = true; btn.textContent = 'Setting up…'; }
+      try {
+        await postJSON(`${API}/box/ensure`);
+      } catch (err) {
+        if (err && err.message === AUTH_REDIRECT) return;
+        if (btn) { btn.disabled = false; btn.textContent = 'Request dev box'; }
+        setOut(`<p class="setup__box-msg setup__box-msg--err">${escapeHtml(err.message || 'Could not set up your box just now.')} You can also ask in Discord #support.</p>`);
+        return;
+      }
+      refresh();
+    }
+
+    // Enqueue a deprovision intent, then poll until the box is destroyed. Paints
+    // "Closing…" and closes the terminal tab IMMEDIATELY so the action feels
+    // instant — the box stays active for up to a minute while it tears down.
+    async function closeBox() {
+      stopPoll();
+      closeTermWindow();
+      setOut('<p class="setup__box-msg">Closing your box… (a few seconds)</p>');
+      enableOpenBtn(null);
+      setRequestBtn(false);
+      try {
+        await postJSON(`${API}/box/close`);
+      } catch (err) {
+        if (err && err.message === AUTH_REDIRECT) return;
+        setOut(`<p class="setup__box-msg setup__box-msg--err">${escapeHtml(err.message || 'Could not close your box just now.')} You can also ask in Discord #support.</p>`);
+        schedulePoll(1000);
+        return;
+      }
+      refresh();
+    }
+
+    function onClick(e) {
+      if (e.target.closest('[data-box-request]')) { requestBox(); return; }
+      // Close box is a two-step confirm: first click arms (shows the reconnect
+      // warning), then Close box / Keep box. Check the armed buttons before the
+      // bare [data-box-close] so the arming click can't also fire a close.
+      if (e.target.closest('[data-box-close-confirm]')) { closeBox(); return; }
+      if (e.target.closest('[data-box-close-cancel]')) { disarmCloseConfirm(e.target.closest('[data-box-close-cancel]')); return; }
+      if (e.target.closest('[data-box-close]')) { armCloseConfirm(e.target.closest('[data-box-close]')); return; }
+      // Open the in-browser terminal via window.open (NOT a plain target=_blank
+      // nav) so we hold a handle and can close the tab when the box is torn
+      // down. The named target reuses the same tab on re-click.
+      const openBtnEl = e.target.closest('[data-box-open]');
+      if (openBtnEl) {
+        const url = openBtnEl.getAttribute('href');
+        if (url && openBtnEl.getAttribute('aria-disabled') !== 'true') {
+          e.preventDefault();
+          termWindow = window.open(url, 'otb-box-terminal');
+          if (termWindow) { try { termWindow.opener = null; } catch (_) {} }
+        }
+        return;
+      }
+      const copyEl = e.target.closest('.setup__copy[data-copy]');
+      if (copyEl) {
+        const text = copyEl.getAttribute('data-copy') || '';
+        const done = () => {
+          copyEl.classList.add('setup__copy--copied');
+          setTimeout(() => { copyEl.classList.remove('setup__copy--copied'); }, 1200);
+        };
+        if (navigator.clipboard && navigator.clipboard.writeText) {
+          navigator.clipboard.writeText(text).then(done).catch(() => toast('Could not copy — select and copy by hand.'));
+        } else {
+          toast('Copy not supported here — select the value and copy by hand.');
+        }
+        return;
+      }
+    }
+
+    const MARKUP = `
+      <div class="setup__box-btns">
+        <button type="button" class="setup__btn setup__btn--box" data-box-request>Request dev box</button>
+        <a class="setup__btn setup__btn--open" data-box-open aria-disabled="true">Open online environment</a>
+      </div>
+      <div class="setup__box-out" data-box-out hidden></div>`;
+
+    function mount(el) {
+      stopPoll();
+      root = el || null;
+      if (!root) return;
+      root.innerHTML = MARKUP;
+      // The element is freshly re-created by the host on each render, so a new
+      // listener per mount does not stack on a live node. Guard anyway.
+      if (!root._otbBoxBound) {
+        root.addEventListener('click', onClick);
+        // Keyboard activation for the click-to-copy values (role="button").
+        root.addEventListener('keydown', (e) => {
+          if ((e.key === 'Enter' || e.key === ' ') && e.target.closest('.setup__copy[data-copy]')) {
+            e.preventDefault();
+            onClick(e);
+          }
+        });
+        root._otbBoxBound = true;
+      }
+      bound = true;
+      refresh();
+    }
+
+    function stop() { stopPoll(); }
+
+    return { mount, refresh, stop };
+  }
+
+  window.OTBBoxPanel = { create };
+})();

package/modules/hall-ui/public/brand-apply.js

@@ -0,0 +1,117 @@
+// brand-apply.js — apply the instance branding pack to the hall's static markup
+// (R56 task 1195, ADR 0062 §3). The pack is injected synchronously as
+// window.__BRANDING__ by the server (src/bongos/serve-internal.js); this fills the
+// markup that can't read it inline.
+//
+// R56 handles the configurable CURRENCY LABEL: any element carrying
+// `data-currency-label` has its text replaced with branding.currency.label.
+//   <span data-currency-label>drachmae</span>        → the label, lowercase
+//   <span data-currency-label="caps">Drachmae</span> → the label, Capitalized
+// For a label embedded in a phrase (e.g. an <option>), use a template carrying
+// {label} (lowercase) / {Label} (Capitalized) placeholders:
+//   <option data-currency-tmpl="highest {label}">highest drachmae</option>
+// The element's existing text is the no-JS / pre-load fallback. For OTB the
+// configured label IS "drachmae", so nothing visibly changes; a differently
+// branded instance sees its own unit. R57 (task 1196) extends window.__BRANDING__
+// to the full pack and this file grows to apply identity/theme/copy too.
+(function () {
+  'use strict';
+  var brand = (typeof window !== 'undefined' && window.__BRANDING__) || null;
+
+  function capitalize(s) {
+    return s ? s.charAt(0).toUpperCase() + s.slice(1) : s;
+  }
+
+  function applyCurrencyLabels(root) {
+    if (!brand || !brand.currency || !brand.currency.label) return;
+    var label = brand.currency.label;
+    var Label = capitalize(label);
+    var scope = root || document;
+    var nodes = scope.querySelectorAll('[data-currency-label]');
+    for (var i = 0; i < nodes.length; i++) {
+      nodes[i].textContent = nodes[i].getAttribute('data-currency-label') === 'caps' ? Label : label;
+    }
+    var tmpls = scope.querySelectorAll('[data-currency-tmpl]');
+    for (var j = 0; j < tmpls.length; j++) {
+      tmpls[j].textContent = tmpls[j].getAttribute('data-currency-tmpl')
+        .replace(/\{label\}/g, label).replace(/\{Label\}/g, Label);
+    }
+  }
+
+  // BV1.R75 (ADR 0062 §4): drive the hall index page's chrome — <title>, <h1>, and
+  // meta description — from the branding pack so the reskin reaches the browser tab,
+  // not just the page body. copy.hallName is the hall's name ("Builders' Hall");
+  // identity.productName / worldName is the instance ("Off the Boats" / "Amazonprimea").
+  // The static markup is the no-JS / pre-load fallback. SCOPED to the hall index via
+  // the #hall-h1 marker: the other hall pages (sessions/watch/work) carry their own
+  // page-specific titles + headings and must keep them — gating on #hall-h1 leaves
+  // them untouched. Re-skinning those pages' chrome is its own (future) carve.
+  function applyPageChrome() {
+    if (!brand) return;
+    var h1 = document.getElementById('hall-h1');
+    if (!h1) return; // not the hall index — leave this page's chrome alone
+    var hallName = (brand.copy && brand.copy.hallName) || '';
+    var product = (brand.identity && (brand.identity.productName || brand.identity.worldName)) || '';
+    if (hallName) {
+      // Tab title: "<Hall> — <Product>" when both are known, else whichever exists.
+      document.title = product ? hallName + ' — ' + product : hallName;
+      h1.textContent = hallName;
+    }
+    if (product) {
+      var desc = document.querySelector('meta[name="description"]');
+      if (desc) {
+        desc.setAttribute('content',
+          'The builder hub for ' + product + '. Standing, achievements, and work waiting to be claimed.');
+      }
+    }
+  }
+
+  // Expose a tiny accessor so JS-rendered strings can read the label without
+  // re-reading window.__BRANDING__ everywhere (and so a future test can stub it).
+  function currencyLabel(opts) {
+    var label = (brand && brand.currency && brand.currency.label) || 'credits';
+    return opts && opts.caps ? capitalize(label) : label;
+  }
+
+  // task 1957 — a task's drachmae is an ESTIMATE (credits_reward, assigned at
+  // creation) until the task SETTLES. Credits only land at 'confirmed' and
+  // persist through 'shipped'; from that point the real payout is credits_awarded
+  // (the ledger sum the task API surfaces). These helpers centralize the
+  // "estimate vs actual" decision so every task surface renders it identically:
+  // unsettled → the estimate with a "<Currency> Est." label; settled → the actual
+  // ledger payout with a plain "<Currency>" label.
+  function taskSettled(task) {
+    var s = task && task.status;
+    return s === 'confirmed' || s === 'shipped';
+  }
+  function taskCreditValue(task) {
+    if (!task) return null;
+    if (taskSettled(task)) {
+      var awarded = Number(task.credits_awarded);
+      // Settled with a real ledger payout → show it. If a settled task has no
+      // ledger record (0 — legacy pre-ledger tasks, or reward-exempt), fall back
+      // to the estimate rather than showing a misleading "0".
+      if (isFinite(awarded) && awarded > 0) return awarded;
+    }
+    return task.credits_reward;
+  }
+  function taskCreditLabel(task, opts) {
+    var base = currencyLabel(opts);
+    return taskSettled(task) ? base : base + ' Est.';
+  }
+
+  window.OTBBranding = {
+    currencyLabel: currencyLabel,
+    taskSettled: taskSettled,
+    taskCreditValue: taskCreditValue,
+    taskCreditLabel: taskCreditLabel,
+    applyCurrencyLabels: applyCurrencyLabels,
+  };
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', function () { applyCurrencyLabels(document); applyPageChrome(); });
+  } else {
+    applyCurrencyLabels(document);
+    applyPageChrome();
+  }
+})();