synabun 2.0.10 → 2.1.0

package/neural-interface/public/shared/assistant/asst-limit-wait.js

@@ -0,0 +1,294 @@
+// ═══════════════════════════════════════════
+// SynaBun Assistant — waiting for a usage limit to reset
+// ═══════════════════════════════════════════
+// Where a provider's usage limit stopped work (the Assistant's own turn: its
+// error row; a worker: its run card), this card waits with the user: the
+// mascot dozes inside a gold ring that fills toward the reset, a live
+// hh:mm:ss countdown and the local reset time beside it. At zero it wakes
+// ("Usage limit restored") and offers Retry now. With no reset time known it
+// waits with "Reset time unknown" and offers the retry at once. The clock is
+// the shared ticker at 1 fps, only while it counts and only while the card is
+// on the page; under prefers-reduced-motion the mascot is a still and nothing
+// eases. Its sheet is its own (injectLimitWaitStyles), like the rack's.
+
+import * as mascotLib from '../synabun-mascot.js';
+import { isReducedMotion, subscribe } from '../synabun-ticker.js';
+import { limitCountdown, resetMs } from './asst-limit.js';
+
+const RING_R = 24;
+const DAY_MS = 86_400_000;
+
+function el(tag, className, text) {
+  const node = document.createElement(tag);
+  if (className) node.className = className;
+  if (text != null) node.textContent = text;
+  return node;
+}
+
+function reducedMotion() {
+  try { return !!isReducedMotion(); } catch { return !!globalThis.matchMedia?.('(prefers-reduced-motion: reduce)').matches; }
+}
+
+/** The reset as the user's clock reads it: "06:01", or "Fri 06:01" when it is not within the next day. */
+function localTime(ms, now) {
+  const opts = { hour: '2-digit', minute: '2-digit' };
+  if (Math.abs(ms - now) >= DAY_MS || new Date(ms).toDateString() !== new Date(now).toDateString()) opts.weekday = 'short';
+  try { return new Date(ms).toLocaleString([], opts); } catch { return new Date(ms).toISOString().slice(11, 16); }
+}
+
+/**
+ * createLimitWait({ t, resetsAt, since, provider, onRetry, retryLabel, announce(text) })
+ * → { el, get state(), update({ resetsAt, since }), retried(), stale(), destroy() }
+ * `resetsAt`: epoch ms / s or ISO, or null (unknown). `since`: when the wait began (the ring's start).
+ * `provider`: the name in the meta line ("Codex"). `onRetry()`: Retry now; null: no button.
+ */
+export function createLimitWait(opts = {}) {
+  injectLimitWaitStyles();
+  const t = (key, fallback, params) => {
+    const v = typeof opts.t === 'function' ? opts.t(key, fallback, params) : undefined;
+    if (v && v !== key && typeof v === 'string') return v;
+    return params ? String(fallback).replace(/\{(\w+)\}/g, (_, k) => (params[k] != null ? params[k] : `{${k}}`)) : fallback;
+  };
+  let resetsAt = resetMs(opts.resetsAt);
+  let since = Number.isFinite(opts.since) ? opts.since : Date.now();
+  let state = '';
+  let unsub = null;
+  let rig = null;
+  let pose = '';
+  let seenConnected = false;
+  let destroyed = false;
+
+  const card = el('div', 'asst-limit-wait');
+  card.setAttribute('role', 'group');
+  card.innerHTML = `
+    <div class="asst-limit-wait-stage" aria-hidden="true">
+      <svg class="asst-limit-ring" viewBox="0 0 56 56" width="56" height="56" focusable="false">
+        <circle class="asst-limit-ring-track" cx="28" cy="28" r="${RING_R}"></circle>
+        <circle class="asst-limit-ring-fill" cx="28" cy="28" r="${RING_R}" pathLength="100" stroke-dasharray="100" stroke-dashoffset="100"></circle>
+      </svg>
+      <span class="asst-limit-wait-face"></span>
+    </div>
+    <div class="asst-limit-wait-main">
+      <div class="asst-limit-wait-title"></div>
+      <div class="asst-limit-wait-clock" role="timer" aria-live="off"></div>
+      <div class="asst-limit-wait-meta"></div>
+      <div class="asst-limit-wait-actions"></div>
+    </div>
+    <span class="asst-limit-wait-live" role="status" aria-live="polite"></span>`;
+  const $ = (sel) => card.querySelector(sel);
+  const fill = $('.asst-limit-ring-fill');
+  const face = $('.asst-limit-wait-face');
+  const title = $('.asst-limit-wait-title');
+  const clock = $('.asst-limit-wait-clock');
+  const meta = $('.asst-limit-wait-meta');
+  const actions = $('.asst-limit-wait-actions');
+  const live = $('.asst-limit-wait-live');
+
+  let retryBtn = null;
+  if (typeof opts.onRetry === 'function') {
+    retryBtn = el('button', 'asst-btn asst-btn-primary asst-limit-wait-retry');
+    retryBtn.type = 'button';
+    retryBtn.addEventListener('click', () => {
+      if (state !== 'restored' && state !== 'unknown') return;
+      retried();
+      try { opts.onRetry(); } catch { /* the host reports its own failure */ }
+    });
+    actions.appendChild(retryBtn);
+  }
+
+  function setPose(next) {
+    if (pose === next || destroyed) return;
+    pose = next;
+    if (reducedMotion()) {
+      try { rig?.destroy(); } catch { /* gone */ }
+      rig = null;
+      face.innerHTML = mascotLib.mascotSvg({ width: 34, height: 17, className: 'synabun-mascot asst-still' });
+      try { mascotLib.paintMascot(face.firstElementChild, mascotLib.stillFrame(next)); } catch { /* the plain face */ }
+      return;
+    }
+    if (!rig) {
+      face.textContent = '';
+      try { rig = mascotLib.createMascot(face, { width: 34, height: 17, pose: next }); return; } catch { rig = null; }
+    }
+    try { rig?.setPose(next, next === 'success' ? { then: 'idle' } : undefined); } catch { /* keeps its pose */ }
+  }
+
+  function setRing(progress, indeterminate = false) {
+    fill.setAttribute('stroke-dashoffset', String(Math.round((1 - Math.max(0, Math.min(1, progress))) * 1000) / 10));
+    card.classList.toggle('is-indeterminate', indeterminate);
+  }
+
+  function paintMeta(now) {
+    const bits = [];
+    if (opts.provider) bits.push(t('assistant.limitWait.provider', '{provider} usage limit', { provider: opts.provider }));
+    if (resetsAt !== null) bits.push((state === 'restored' || state === 'retried' || (state === 'stale' && resetsAt <= now)) ? t('assistant.limitWait.resetAt', 'reset at {time}', { time: localTime(resetsAt, now) }) : t('assistant.limitWait.resetsAt', 'resets at {time}', { time: localTime(resetsAt, now) }));
+    meta.textContent = bits.join(' · ');
+    meta.hidden = !bits.length;
+  }
+
+  function setState(next, now = Date.now()) {
+    const was = state;
+    state = next;
+    card.dataset.state = next;
+    card.dataset.known = resetsAt === null ? '0' : '1';
+    card.setAttribute('aria-label', next === 'restored' || next === 'retried' ? t('assistant.limitWait.restored', 'Usage limit restored') : t('assistant.limitWait.waiting', 'Waiting for the usage limit to reset'));
+    title.textContent = next === 'restored' || next === 'retried'
+      ? t('assistant.limitWait.restored', 'Usage limit restored')
+      : next === 'stale' && resetsAt !== null && resetsAt <= now ? t('assistant.limitWait.restored', 'Usage limit restored')
+        : t('assistant.limitWait.waiting', 'Waiting for the usage limit to reset');
+    if (next === 'unknown') { clock.textContent = t('assistant.limitWait.unknown', 'Reset time unknown'); clock.classList.add('is-text'); clock.removeAttribute('aria-label'); }
+    if (next === 'restored' || next === 'retried') { clock.textContent = '00:00:00'; clock.classList.remove('is-text'); clock.removeAttribute('aria-label'); }
+    if (retryBtn) {
+      retryBtn.hidden = !(next === 'restored' || next === 'unknown' || next === 'retried');
+      retryBtn.disabled = next === 'retried' || next === 'stale';
+      const label = next === 'retried' ? t('assistant.limitWait.retried', 'Retried')
+        : next === 'unknown' ? (opts.retryLabel || t('assistant.limitWait.tryAgain', 'Try again'))
+          : (opts.retryLabel || t('assistant.limitWait.retry', 'Retry now'));
+      retryBtn.textContent = label;
+    }
+    if (next === 'waiting') { setPose('sleep'); setRing(limitCountdown({ resetsAt, since }, now).progress || 0); }
+    else if (next === 'unknown') { setPose('wait'); setRing(0.18, true); }
+    else if (next === 'restored') { setPose(was === 'waiting' ? 'success' : 'idle'); setRing(1); }
+    else { setPose('idle'); setRing(resetsAt !== null && resetsAt <= now ? 1 : 0); }
+    if (next === 'restored' && was === 'waiting') live.textContent = t('assistant.limitWait.announceRestored', 'The usage limit has reset.');
+    paintMeta(now);
+    syncTicker();
+  }
+
+  function tick(now = Date.now()) {
+    if (destroyed) return;
+    if (card.isConnected) seenConnected = true;
+    else if (seenConnected) { destroy(); return; }
+    if (state !== 'waiting') { syncTicker(); return; }
+    const view = limitCountdown({ resetsAt, since }, now);
+    if (view.done) { setState('restored', now); return; }
+    if (clock.textContent !== view.clock) {
+      clock.textContent = view.clock;
+      clock.classList.remove('is-text');
+      clock.setAttribute('aria-label', t('assistant.limitWait.left', '{clock} left', { clock: view.clock }));
+    }
+    setRing(view.progress);
+  }
+
+  function syncTicker() {
+    const want = state === 'waiting' && !destroyed;
+    if (want && !unsub) { try { unsub = subscribe((now) => tick(typeof now === 'number' && now > 1e12 ? now : Date.now()), { fps: 1 }); } catch { unsub = null; } }
+    else if (!want && unsub) { try { unsub(); } catch { /* gone */ } unsub = null; }
+  }
+
+  function start(now = Date.now()) {
+    if (resetsAt === null) setState('unknown', now);
+    else if (resetsAt <= now) setState('restored', now);
+    else { setState('waiting', now); tick(now); }
+  }
+
+  function retried() {
+    if (state === 'retried' || state === 'stale') return;
+    setState('retried');
+  }
+  function stale() {
+    if (state === 'retried' || state === 'stale') return;
+    setState('stale');
+    if (state === 'stale') {
+      clock.classList.add('is-text');
+      clock.removeAttribute('aria-label');
+      clock.textContent = resetsAt !== null ? localTime(resetsAt, Date.now()) : t('assistant.limitWait.unknown', 'Reset time unknown');
+    }
+  }
+  function destroy() {
+    if (destroyed) return;
+    destroyed = true;
+    if (unsub) { try { unsub(); } catch { /* gone */ } unsub = null; }
+    try { rig?.destroy(); } catch { /* gone */ }
+    rig = null;
+  }
+
+  start();
+  return {
+    el: card,
+    get state() { return state; },
+    get resetsAt() { return resetsAt; },
+    /** A reset time learned later (a structured report): the card counts to it. Ignored once it is settled. */
+    update({ resetsAt: next, since: from } = {}) {
+      if (destroyed || state === 'retried' || state === 'stale') return;
+      const ms = resetMs(next);
+      if (Number.isFinite(from)) since = from;
+      if (ms === null || ms === resetsAt) return;
+      resetsAt = ms;
+      start();
+    },
+    retried,
+    stale,
+    destroy,
+  };
+}
+
+const CSS = `
+  .asst-limit-wait {
+    --lw-tone: var(--asst-brand);
+    display: grid;
+    grid-template-columns: 56px minmax(0, 1fr);
+    align-items: center;
+    gap: 12px;
+    min-width: 0;
+    padding: 12px 14px;
+    border-radius: var(--asst-r-card);
+    background: linear-gradient(135deg, color-mix(in srgb, var(--asst-brand) 8%, transparent), var(--asst-fill-1) 62%);
+    box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--asst-brand) 26%, transparent), var(--asst-card-hi);
+    color: var(--asst-text);
+    font-size: 13px;
+    transition: box-shadow var(--asst-dur-base) var(--asst-ease-standard), background-color var(--asst-dur-base) var(--asst-ease-standard);
+  }
+  .asst-limit-wait:is([data-state="stale"], [data-state="retried"]) {
+    --lw-tone: var(--asst-text-3);
+    background: transparent;
+    box-shadow: inset 0 0 0 1px var(--asst-line);
+  }
+  .asst-limit-wait-stage { position: relative; width: 56px; height: 56px; }
+  .asst-limit-ring { display: block; width: 56px; height: 56px; transform: rotate(-90deg); overflow: visible; }
+  .asst-limit-ring-track { fill: none; stroke: var(--asst-line-2); stroke-width: 3; }
+  .asst-limit-ring-fill {
+    fill: none;
+    stroke: var(--lw-tone);
+    stroke-width: 3;
+    stroke-linecap: round;
+    transform-box: fill-box;
+    transform-origin: center;
+    transition: stroke-dashoffset 1s linear, stroke var(--asst-dur-base) var(--asst-ease-standard);
+  }
+  .asst-limit-wait[data-state="restored"] .asst-limit-ring-fill { filter: drop-shadow(0 0 3px color-mix(in srgb, var(--asst-brand) 55%, transparent)); }
+  .asst-limit-wait.is-indeterminate .asst-limit-ring-fill { stroke-dasharray: 18 82; animation: asst-limit-orbit 2.6s linear infinite; }
+  @keyframes asst-limit-orbit { to { transform: rotate(360deg); } }
+  .asst-limit-wait-face { position: absolute; inset: 0; display: grid; place-items: center; color: var(--lw-tone); line-height: 0; }
+  .asst-limit-wait-face svg { display: block; width: 34px; height: 17px; }
+  .asst-limit-wait-main { display: flex; flex-direction: column; gap: 2px; min-width: 0; }
+  .asst-limit-wait-title { color: var(--asst-text-2); font-size: 12px; font-weight: 500; }
+  .asst-limit-wait[data-state="restored"] .asst-limit-wait-title { color: var(--asst-brand); }
+  .asst-limit-wait-clock { color: var(--asst-text); font-family: var(--asst-mono); font-size: 20px; font-weight: 500; line-height: 1.2; font-variant-numeric: tabular-nums; letter-spacing: .02em; }
+  .asst-limit-wait-clock.is-text { font-family: inherit; font-size: 13px; color: var(--asst-text-2); letter-spacing: 0; }
+  .asst-limit-wait-meta { color: var(--asst-text-3); font-size: 11.5px; overflow-wrap: anywhere; }
+  .asst-limit-wait-actions { display: flex; flex-wrap: wrap; gap: 6px; margin-top: 6px; }
+  .asst-limit-wait-actions:not(:has(> :not([hidden]))) { display: none; }
+  .asst-limit-wait-live { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; }
+  .asst-limit-row .asst-msg-content { width: 100%; }
+  .asst-run .asst-limit-wait { grid-column: 2 / span 2; margin-top: 8px; padding: 10px 12px; }
+  @container asst (max-width: 320px) {
+    .asst-limit-wait { grid-template-columns: 44px minmax(0, 1fr); gap: 10px; padding: 10px; }
+    .asst-limit-wait-stage, .asst-limit-ring { width: 44px; height: 44px; }
+    .asst-limit-wait-face svg { width: 28px; height: 14px; }
+    .asst-limit-wait-clock { font-size: 17px; }
+  }
+  body.ui-interacting .asst-limit-ring-fill { animation-play-state: paused !important; }
+  @media (prefers-reduced-motion: reduce) {
+    .asst-limit-wait, .asst-limit-wait * { animation: none !important; transition: none !important; }
+  }
+`;
+
+/** The card's sheet, once per page. */
+export function injectLimitWaitStyles() {
+  if (typeof document === 'undefined' || document.getElementById('asst-limit-wait-styles')) return;
+  const style = document.createElement('style');
+  style.id = 'asst-limit-wait-styles';
+  style.textContent = CSS;
+  document.head.appendChild(style);
+}

package/neural-interface/public/shared/assistant/asst-limit.js

@@ -0,0 +1,168 @@
+// ═══════════════════════════════════════════
+// SynaBun Assistant — usage limits: is it one, and when does it reset?
+// ═══════════════════════════════════════════
+// A provider that stops a turn on its usage limit says so in words ("You've
+// hit your session limit · resets 5:10am (America/Sao_Paulo)", "try again in
+// 2 hours 3 minutes", "blocked until about 06:01 UTC"). limitFromText reads
+// that message: whether it is a usage limit, and the reset time it names
+// (epoch ms, or null when it names none). The time is read against the moment
+// the message was written (`now`), so a reload draws the same countdown. A
+// structured reset time (the Claude SDK's rate_limit_info, an account's usage
+// window) always wins over the words; this is what is left when there is
+// none. limitCountdown is the waiting card's clock. No imports and no DOM:
+// the dispatcher (lib/assistant-dispatch.js) reads a worker's failure with it.
+
+const LIMIT_RE = /\b(?:usage limit|session limit|weekly limit|daily limit|hourly limit|5-hour limit|rate[- ]limit(?:ed)?|limit reached|limit exceeded|hit (?:your|the) (?:\w+ ){0,2}limit|out of (?:usage|credits|quota)|quota (?:exceeded|reached)|exceeded (?:your |the )?(?:current )?quota|too many requests)\b/i;
+const DAY_MS = 86_400_000;
+const MONTHS = ['jan', 'feb', 'mar', 'apr', 'may', 'jun', 'jul', 'aug', 'sep', 'oct', 'nov', 'dec'];
+const UNIT_MS = { d: DAY_MS, h: 3_600_000, m: 60_000, s: 1000 };
+
+/** The offset of `timeZone` from UTC at the instant `ms` (wall time − UTC), in ms; null for a zone this runtime does not know. */
+function zoneOffset(ms, timeZone) {
+  try {
+    const parts = new Intl.DateTimeFormat('en-US', {
+      timeZone, hourCycle: 'h23', year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', second: '2-digit',
+    }).formatToParts(new Date(ms));
+    const get = (type) => Number(parts.find((p) => p.type === type)?.value);
+    const wall = Date.UTC(get('year'), get('month') - 1, get('day'), get('hour') % 24, get('minute'), get('second'));
+    return Number.isFinite(wall) ? wall - (Math.floor(ms / 1000) * 1000) : null;
+  } catch { return null; }
+}
+
+/** A wall-clock time in `zone` ('UTC', an IANA name, or null for this machine's own) → epoch ms. */
+export function wallTimeToEpoch({ year, month, day, hour, minute = 0 }, zone = null) {
+  if (zone === 'UTC') return Date.UTC(year, month, day, hour, minute);
+  if (zone) {
+    const guess = Date.UTC(year, month, day, hour, minute);
+    const first = zoneOffset(guess, zone);
+    if (first !== null) {
+      const at = guess - first;
+      const second = zoneOffset(at, zone);
+      return second !== null && second !== first ? guess - second : at;
+    }
+  }
+  return new Date(year, month, day, hour, minute).getTime();
+}
+
+/** Year / month / day of the instant `ms` as `zone` sees it. */
+function dateIn(ms, zone) {
+  if (zone === 'UTC') { const d = new Date(ms); return { year: d.getUTCFullYear(), month: d.getUTCMonth(), day: d.getUTCDate() }; }
+  if (zone) {
+    const offset = zoneOffset(ms, zone);
+    if (offset !== null) { const d = new Date(ms + offset); return { year: d.getUTCFullYear(), month: d.getUTCMonth(), day: d.getUTCDate() }; }
+  }
+  const d = new Date(ms);
+  return { year: d.getFullYear(), month: d.getMonth(), day: d.getDate() };
+}
+
+function isZone(name) {
+  if (!name) return false;
+  if (/^(?:utc|gmt|z)$/i.test(name)) return true;
+  try { new Intl.DateTimeFormat('en-US', { timeZone: name }); return true; } catch { return false; }
+}
+
+/** "in 2 hours 3 minutes" / "in 4h 12m" → ms, or null. */
+function relativeMs(text) {
+  const m = /\b(?:in|after|within)\s+(?:about\s+|around\s+|~\s*)?((?:\d+(?:\.\d+)?\s*(?:days?|d|hours?|hrs?|hr|h|minutes?|mins?|min|m|seconds?|secs?|sec|s)\b[\s,]*(?:and\s+)?)+)/i.exec(text);
+  if (!m) return null;
+  let total = 0;
+  for (const part of m[1].matchAll(/(\d+(?:\.\d+)?)\s*(days?|d|hours?|hrs?|hr|h|minutes?|mins?|min|m|seconds?|secs?|sec|s)\b/gi)) {
+    const unit = part[2].toLowerCase();
+    const key = unit.startsWith('d') ? 'd' : unit.startsWith('h') ? 'h' : unit.startsWith('m') ? 'm' : 's';
+    total += Number(part[1]) * UNIT_MS[key];
+  }
+  return total > 0 ? total : null;
+}
+
+/**
+ * A clock time the message names after "resets", "until", "try again at"…: the next such moment
+ * from `now` (today, or tomorrow when it has passed), in the zone it names ("UTC", "(America/Sao_Paulo)")
+ * or this machine's own. A month and day before it ("Oct 23, 5:52 PM") pin the date.
+ */
+function clockTime(text, now) {
+  const re = /\b(?:resets?|reset at|until|till|try again at|again at|available (?:again )?at|back at)\s+(?:on\s+)?(?:at\s+)?(?:about\s+|around\s+|approximately\s+|~\s*)?(?:([A-Za-z]{3,9})\.?\s+(\d{1,2})(?:st|nd|rd|th)?,?\s+(?:(\d{4}),?\s+)?(?:at\s+)?)?(\d{1,2})(?::(\d{2}))?\s*([ap]\.?m\.?)?(?:\s*(?:\(\s*)?(UTC|GMT|Z|[A-Za-z]+\/[A-Za-z_]+(?:\/[A-Za-z_]+)?)(?:\s*\))?)?/gi;
+  for (const m of text.matchAll(re)) {
+    const [, monthName, dayText, yearText, hourText, minuteText, meridiem, zoneText] = m;
+    let hour = Number(hourText);
+    const minute = minuteText ? Number(minuteText) : 0;
+    // "until 3 runs finish" is no time: a clock needs minutes or am / pm.
+    if (!minuteText && !meridiem) continue;
+    if (minute > 59 || hour > 23 || (meridiem && (hour < 1 || hour > 12))) continue;
+    if (meridiem) { const pm = /^p/i.test(meridiem); hour = (hour % 12) + (pm ? 12 : 0); }
+    const zone = zoneText && isZone(zoneText) ? (/^(?:utc|gmt|z)$/i.test(zoneText) ? 'UTC' : zoneText) : null;
+    const monthIndex = monthName ? MONTHS.indexOf(monthName.slice(0, 3).toLowerCase()) : -1;
+    if (monthName && monthIndex >= 0) {
+      const today = dateIn(now, zone);
+      let year = yearText ? Number(yearText) : today.year;
+      let at = wallTimeToEpoch({ year, month: monthIndex, day: Number(dayText), hour, minute }, zone);
+      if (!yearText && at < now - DAY_MS) { year += 1; at = wallTimeToEpoch({ year, month: monthIndex, day: Number(dayText), hour, minute }, zone); }
+      return at;
+    }
+    if (monthName) continue; // a word that is no month ("resets daily 5pm"): try the next match
+    const today = dateIn(now, zone);
+    let at = wallTimeToEpoch({ ...today, hour, minute }, zone);
+    if (at < now - 60_000) {
+      const next = new Date(Date.UTC(today.year, today.month, today.day + 1));
+      at = wallTimeToEpoch({ year: next.getUTCFullYear(), month: next.getUTCMonth(), day: next.getUTCDate(), hour, minute }, zone);
+    }
+    return at;
+  }
+  return null;
+}
+
+/** An instant written out: epoch seconds or ms after "limit reached|" (the Claude CLI's old form), or an ISO timestamp. */
+function absoluteTime(text) {
+  const epoch = /limit reached\|(\d{10,13})\b/i.exec(text);
+  if (epoch) { const n = Number(epoch[1]); return n < 1e12 ? n * 1000 : n; }
+  const isoMatch = /\b(\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)\b/.exec(text);
+  if (isoMatch) { const ms = Date.parse(isoMatch[1].replace(' ', 'T')); if (Number.isFinite(ms)) return ms; }
+  return null;
+}
+
+/**
+ * Is `text` a provider's usage-limit message? → { resetsAt: epoch ms | null } or null.
+ * `now`: when the message was written (its reset time is the next one from then).
+ * A reset time more than a day before `now` or 31 days after it is none.
+ */
+export function limitFromText(text, { now = Date.now() } = {}) {
+  const src = String(text ?? '').replace(/\s+/g, ' ').trim();
+  if (!src || src.length > 4000 || !LIMIT_RE.test(src)) return null;
+  let resetsAt = absoluteTime(src);
+  if (resetsAt === null) { const rel = relativeMs(src); if (rel !== null) resetsAt = now + rel; }
+  if (resetsAt === null) resetsAt = clockTime(src, now);
+  if (resetsAt !== null && (!Number.isFinite(resetsAt) || resetsAt < now - DAY_MS || resetsAt > now + 31 * DAY_MS)) resetsAt = null;
+  return { resetsAt };
+}
+
+/** A reset time in any form the panel meets (epoch s or ms, ISO text) → epoch ms, or null. Seconds below 1e11 (until the year 5138). */
+export function resetMs(value) {
+  if (value === null || value === undefined || value === '') return null;
+  if (typeof value === 'number') return Number.isFinite(value) && value > 0 ? (value < 1e11 ? value * 1000 : value) : null;
+  const n = Number(value);
+  if (Number.isFinite(n) && String(value).trim() !== '') return resetMs(n);
+  const ms = Date.parse(String(value));
+  return Number.isFinite(ms) ? ms : null;
+}
+
+/** ms → "hh:mm:ss" (hours past 99 keep growing), counted up so the last second shows 00:00:01. */
+export function fmtCountdown(ms) {
+  const total = Math.max(0, Math.ceil((Number(ms) || 0) / 1000));
+  const h = Math.floor(total / 3600);
+  const m = Math.floor((total % 3600) / 60);
+  const s = total % 60;
+  return `${String(h).padStart(2, '0')}:${String(m).padStart(2, '0')}:${String(s).padStart(2, '0')}`;
+}
+
+/**
+ * The waiting card's clock at `now`: { known, done, remainingMs, clock, progress }.
+ * `since`: when the wait began (the ring fills from there to `resetsAt`). No reset time: known false.
+ */
+export function limitCountdown({ resetsAt = null, since = null } = {}, now = Date.now()) {
+  const at = resetMs(resetsAt);
+  if (at === null) return { known: false, done: false, remainingMs: null, clock: '', progress: null };
+  const remainingMs = Math.max(0, at - now);
+  const start = Number.isFinite(since) && since < at ? since : Math.min(now, at);
+  const span = Math.max(1, at - start);
+  const progress = remainingMs <= 0 ? 1 : Math.min(1, Math.max(0, 1 - remainingMs / span));
+  return { known: true, done: remainingMs <= 0, remainingMs, clock: fmtCountdown(remainingMs), progress };
+}

package/neural-interface/public/shared/assistant/asst-mascot.js

@@ -3,12 +3,15 @@
 // ═══════════════════════════════════════════
 // The renderer (asst-render.js) owns the rigs and says which one is on screen:
 // the hero (the empty state's character; a send hands it over to the
-// "Thinking" row's at once), the live rack's stage or the "Thinking" row's.
+// "Thinking" row's at once), the face of the newest open card the mascot
+// presents (a follow-ups or question card: asst-ask.js, kind 'card'), the
+// live rack's stage or the "Thinking" row's.
 // This module dresses that one in the panel's own state, above the pose the
 // renderer gives it:
 //
 //   offline         the socket dropped (the Reconnecting banner); one startle on reconnect
-//   blocked         a card waits on you: eyes on it, two pulses, then still
+//   blocked         a card waits on you: eyes on it, two pulses, then still (never on a
+//                   question card's own face, `waits`: that card asks in its own pose)
 //   success, error  once, when a turn that did real work ends (then idle)
 //   watch           while you type: eyes on the caret column, look() at most
 //                   every 120 ms; back 1.5 s after the last key, at once on send
@@ -17,6 +20,12 @@
 //   sleep           the hero only, after 90 s with no input while nothing runs;
 //                   the rig wakes itself on a pointer move or a key
 //
+// present(true) hands the character to a presenter (the Workspace tour,
+// public/shared/tour/): while it lasts the director dresses nothing, never
+// puts the hero to sleep, does not watch the caret and ignores chip
+// attention; present(false) gives it back and the director dresses it again
+// for whatever is true by then.
+//
 // Anything else is the renderer's pose: the hero idles, the "Thinking" row's
 // character thinks, the stage acts out its call. A pose the director sets is
 // held: the renderer leaves it alone until the director lets go and asks it
@@ -67,8 +76,8 @@ export function lookToward(box, point, { horizontal = false } = {}) {
 
 /**
  * createMascotDirector({ getTarget, caret, env })
- * getTarget() → the renderer's visible mascot { kind: 'hero'|'stage'|'working',
- *   rig, el, parked?(), hold(on), restore() } or null; caret() → the caret's
+ * getTarget() → the renderer's visible mascot { kind: 'hero'|'card'|'stage'|'working',
+ *   rig, el, parked?(), waits?, hold(on), restore() } or null; caret() → the caret's
  *   client point or null.
  * Control API: attend(owner, { pose, rectOf, options, open }), leave(owner),
  * controlCommitted({ pose, options, reaction }); type(present, pointOf?) also
@@ -103,13 +112,15 @@ export function createMascotDirector({ getTarget = () => null, caret = () => nul
   let sleepTimer = 0;
   let lastInput = now();
   let stopInput = null;
+  let presenting = false; // a presenter (the tour) owns the character's pose
 
   const safe = (fn) => { try { return fn(); } catch { return undefined; } };
   const boxOf = (t) => safe(() => t.el?.getBoundingClientRect?.()) || null;
 
   function desired(t) {
     if (offline) return { pose: 'offline' };
-    if (blocked) {
+    // A question card's own face is the card that waits: it asks in its own pose (asst-ask.js), never "blocked" at itself.
+    if (blocked && !t.waits) {
       // The card's head (its title and command sit top left), not its centre.
       const card = safe(blocked);
       const point = card && card.width ? { x: card.left + Math.min(card.width * 0.3, 160), y: card.top + Math.min(card.height / 2, 28) } : null;
@@ -133,7 +144,7 @@ export function createMascotDirector({ getTarget = () => null, caret = () => nul
     if (destroyed) return;
     const t = safe(getTarget) || null;
     if (t !== target) {
-      if (target && holding) safe(() => target.hold(false));
+      if (target && holding && !presenting) safe(() => target.hold(false));
       target = t;
       holding = false;
       shown = '';
@@ -141,7 +152,7 @@ export function createMascotDirector({ getTarget = () => null, caret = () => nul
       listenInput();
       armSleep();
     }
-    if (!t) return;
+    if (!t || presenting) return; // a presenter holds the pose: nothing is dressed until it lets go
     const want = desired(t);
     if (!want) {
       if (!holding) return;
@@ -171,7 +182,7 @@ export function createMascotDirector({ getTarget = () => null, caret = () => nul
 
   function canSleep() {
     const t = target;
-    return !destroyed && !!t && t.kind === 'hero' && !safe(() => t.parked?.()) && !turnActive && !typing && !attention?.open && !blocked && !offline && !oneShot;
+    return !destroyed && !presenting && !!t && t.kind === 'hero' && !safe(() => t.parked?.()) && !turnActive && !typing && !attention?.open && !blocked && !offline && !oneShot;
   }
 
   function armSleep() {
@@ -202,7 +213,7 @@ export function createMascotDirector({ getTarget = () => null, caret = () => nul
   function type(present = true, pointOf = null) {
     if (destroyed) return;
     noteInput();
-    if (!present) { stopTyping(); return; }
+    if (!present || presenting) { stopTyping(); return; }
     if (oneShot?.control) dropOneShot(); // a new edit resumes watching after an acknowledgement
     const first = !typing;
     typing = true;
@@ -252,7 +263,7 @@ export function createMascotDirector({ getTarget = () => null, caret = () => nul
     stopTyping,
     /** Chip previews relax after a short dwell; only open menus hold attention and block sleep. */
     attend(owner, spec) {
-      if (destroyed || (attention?.open && attention.owner !== owner && !spec.open)) return;
+      if (destroyed || presenting || (attention?.open && attention.owner !== owner && !spec.open)) return;
       noteInput();
       clearAttention();
       attention = { owner, ...spec };
@@ -272,7 +283,7 @@ export function createMascotDirector({ getTarget = () => null, caret = () => nul
     },
     /** Only acknowledged user commits call this; loads, live updates and keystrokes do not. */
     controlCommitted({ pose, options = {}, reaction = 'nod' }) {
-      if (destroyed) return;
+      if (destroyed || presenting) return;
       const t = safe(getTarget);
       if (!t || t.kind !== 'hero' || safe(() => t.parked?.()) || turnActive || offline || blocked) return;
       stopTyping();
@@ -319,8 +330,34 @@ export function createMascotDirector({ getTarget = () => null, caret = () => nul
     retarget() { apply(); },
     /** The user is here (focus, a click): a sleeping hero wakes, the quiet starts over. */
     touch() { if (!destroyed) noteInput(); },
+    /**
+     * A presenter takes the character (true) or gives it back (false). While on:
+     * no pose, sleep, caret watch, chip attention or acknowledgement from here;
+     * the hold this director had is handed over as it is (the presenter holds it).
+     */
+    present(on) {
+      const next = !!on;
+      if (destroyed || next === presenting) return;
+      presenting = next;
+      if (presenting) {
+        clearAttention();
+        dropOneShot();
+        if (typingTimer) { cancel(typingTimer); typingTimer = 0; }
+        if (lookTimer) { cancel(lookTimer); lookTimer = 0; }
+        typing = false;
+        typingPoint = null;
+        sleeping = false;
+        if (sleepTimer) { cancel(sleepTimer); sleepTimer = 0; }
+        holding = false;
+        shown = '';
+        return;
+      }
+      lastInput = now();
+      apply();
+      armSleep();
+    },
     /** For tests and devtools: what the director holds right now. */
-    state: () => ({ target: target?.kind || null, pose: shown.split('|')[0] || null, typing, attention: attention?.pose || null, menuOpen: !!attention?.open, blocked: !!blocked, offline, sleeping, oneShot: oneShot?.pose || null }),
+    state: () => ({ target: target?.kind || null, presenting, pose: shown.split('|')[0] || null, typing, attention: attention?.pose || null, menuOpen: !!attention?.open, blocked: !!blocked, offline, sleeping, oneShot: oneShot?.pose || null }),
     destroy() {
       if (destroyed) return;
       if (target && holding) safe(() => target.hold(false));

package/neural-interface/public/shared/assistant/asst-menu.js

@@ -17,7 +17,7 @@
 // `footer`: items under the list that stay in view while the list scrolls.
 // Every menu is measured at the width it is shown at, never wider than its box less the margins,
 // and opens where that box has room (the list scrolls inside it). The box is the Assistant
-// panel or root around the anchor, else the window.
+// panel or root around the anchor, else the app frame (app-frame.js; the window on a page without it).
 // `bounds`: an element (or () => DOMRect) to use as that box instead: the menu is then exactly
 // `width` wide (or the box's room) and follows the box on resize.
 // `onEscape`: returns true when it handled Esc (e.g. went back a view): the menu stays open.
@@ -44,6 +44,8 @@
 // any group left empty. The handle's update({ title, items, footer, focus }) redraws
 // an open menu in place (focus: the data-id to land on; the filter's text still applies).
 
+import { frameRect } from '../app-frame.js';
+
 let _open = null;
 let _uid = 0;
 let _lastDown = null;
@@ -290,14 +292,13 @@ const BOUNDED_MIN_WIDTH = 248;
 const MENU_MIN_HEIGHT = 96;
 const BOUNDED_MIN_HEIGHT = 140;
 
-/** The box a menu stays inside: its bounds clipped to the window (the window when it has none). */
+/** The box a menu stays inside: its bounds clipped to the app frame (the frame when it has none). */
 function boundsBox(bounds) {
-  const vw = window.innerWidth;
-  const vh = window.innerHeight;
+  const f = frameRect();
   let r = null;
   try { r = typeof bounds === 'function' ? bounds() : bounds?.getBoundingClientRect?.(); } catch { r = null; }
-  if (!r || !(r.width > 0) || !(r.height > 0)) return { left: 0, top: 0, right: vw, bottom: vh };
-  return { left: Math.max(0, r.left), top: Math.max(0, r.top), right: Math.min(vw, r.right), bottom: Math.min(vh, r.bottom) };
+  if (!r || !(r.width > 0) || !(r.height > 0)) return { left: f.left, top: f.top, right: f.right, bottom: f.bottom };
+  return { left: Math.max(f.left, r.left), top: Math.max(f.top, r.top), right: Math.min(f.right, r.right), bottom: Math.min(f.bottom, r.bottom) };
 }
 
 /** Where a menu without `bounds` stays: the Assistant around its anchor (the sidepanel, or a tab's own root). */