@oar-sh/oar 0.9.0

package/server/public/app/plan-usage-view.mjs

@@ -0,0 +1,307 @@
+/**
+ * Renders the plan-usage ("Check Usage") modal body from the multi-provider
+ * payload `/api/usage` returns.
+ *
+ * Plan-first by design: subscription credits, limits and resets lead, and the
+ * token/cost diagnostics sit in collapsed sections underneath. Kept DOM-free so
+ * it can be unit tested directly, mirroring `context-usage-view.mjs` — whose
+ * bar/table vocabulary this deliberately reuses so the two modals look related.
+ */
+
+import { escapeHtml } from './context-usage-view.mjs';
+
+// Null-prototype so an unrecognized `status`/`source` can only ever miss —
+// a plain literal would resolve keys like `constructor` off the prototype and
+// stringify a function into a badge.
+const STATUS_BADGES = Object.freeze(Object.assign(Object.create(null), {
+  ok: null,
+  partial: 'Partial',
+  unavailable: 'Unavailable',
+  'not-configured': 'Not configured',
+  error: 'Error',
+}));
+
+const SOURCE_LABELS = Object.freeze(Object.assign(Object.create(null), {
+  live: 'Live',
+  cache: 'Cached',
+  worker: 'From last turn',
+  manual: 'Estimated',
+}));
+
+/** Short tab captions; the card keeps the long label ("GitHub Copilot"). */
+const TAB_LABELS = Object.freeze(Object.assign(Object.create(null), {
+  github: 'Copilot',
+  claude: 'Claude',
+  cursor: 'Cursor',
+  grok: 'Grok',
+}));
+
+// The composer speaks 'github'/'openai'/… while the usage report keys Copilot as
+// 'github'; fold the spellings that mean the same provider onto one id so a
+// session's provider can be matched against a card.
+const PROVIDER_ALIASES = Object.freeze(Object.assign(Object.create(null), {
+  copilot: 'github',
+  'github-copilot': 'github',
+  'copilot-github': 'github',
+}));
+
+/** @returns {string} the canonical usage-card id for a provider spelling. */
+export function normalizeUsageProvider(value) {
+  const key = String(value ?? '').trim().toLowerCase();
+  if (!key) return '';
+  return PROVIDER_ALIASES[key] || key;
+}
+
+/**
+ * Which tab opens selected: the requested provider when it has a card (so a
+ * Claude session lands on Claude), otherwise the first card — 'openai' sessions
+ * have no card of their own and must not open onto an empty modal.
+ */
+export function resolveActiveUsageProvider(providers, activeProvider = '') {
+  const ids = (Array.isArray(providers) ? providers : [])
+    .filter(Boolean)
+    .map((card) => normalizeUsageProvider(card.provider));
+  const wanted = normalizeUsageProvider(activeProvider);
+  if (wanted && ids.includes(wanted)) return wanted;
+  return ids[0] || '';
+}
+
+function toNullableNumber(value) {
+  if (value === null || value === undefined || value === '') return null;
+  const n = Number(value);
+  return Number.isFinite(n) ? n : null;
+}
+
+/** Green → amber → red, matching the composer's context-usage indicator ramp. */
+export function utilizationColor(utilization) {
+  const value = toNullableNumber(utilization);
+  if (value === null) return '#6e7681';
+  if (value >= 90) return '#f85149';
+  if (value >= 75) return '#e3b341';
+  if (value >= 50) return '#d29922';
+  return '#3fb950';
+}
+
+export function formatAmount(value, unit) {
+  const n = toNullableNumber(value);
+  if (n === null) return null;
+  if (unit === 'usd') {
+    const rounded = Math.round(n * 100) / 100;
+    return `${rounded < 0 ? '-' : ''}$${Math.abs(rounded).toFixed(2)}`;
+  }
+  if (unit === 'percent') return `${Math.round(n * 10) / 10}%`;
+  const abs = Math.abs(n);
+  if (abs >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+  if (abs >= 10_000) return `${(n / 1000).toFixed(1)}k`;
+  return String(Math.round(n * 100) / 100);
+}
+
+export function formatResetCountdown(resetAt, now = new Date()) {
+  if (!resetAt) return null;
+  const target = new Date(resetAt);
+  if (Number.isNaN(target.getTime())) return null;
+  const reference = now instanceof Date && !Number.isNaN(now.getTime()) ? now : new Date();
+  const diffMs = target.getTime() - reference.getTime();
+  if (diffMs <= 0) return 'resets now';
+  const minutes = Math.floor(diffMs / 60000);
+  if (minutes < 60) return `resets in ${Math.max(1, minutes)} min`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) {
+    const remainderMinutes = minutes % 60;
+    return remainderMinutes ? `resets in ${hours} h ${remainderMinutes} min` : `resets in ${hours} h`;
+  }
+  const days = Math.floor(hours / 24);
+  if (days <= 14) {
+    const remainderHours = hours % 24;
+    return remainderHours ? `resets in ${days} d ${remainderHours} h` : `resets in ${days} d`;
+  }
+  return `resets ${target.toISOString().slice(0, 10)}`;
+}
+
+/**
+ * The headline under a meter label: what is left, out of what, and how it was
+ * derived. Providers that only report a percentage get just the percentage.
+ */
+export function meterSummaryText(meter) {
+  if (!meter || typeof meter !== 'object') return '';
+  if (meter.unlimited) return 'Unlimited';
+  const unit = meter.unit || 'credits';
+  const used = formatAmount(meter.used, unit);
+  const allowance = formatAmount(meter.allowance, unit);
+  const remaining = formatAmount(meter.remaining, unit);
+  const utilization = toNullableNumber(meter.utilization);
+
+  if (allowance !== null && used !== null) {
+    const parts = [`${used} of ${allowance} used`];
+    if (remaining !== null) {
+      const remainingNumber = toNullableNumber(meter.remaining);
+      // Overage reads as a magnitude ("9989 over"), not a signed value.
+      parts.push(remainingNumber < 0
+        ? `${formatAmount(Math.abs(remainingNumber), unit)} over`
+        : `${remaining} left`);
+    }
+    return parts.join(' · ');
+  }
+  if (remaining !== null && allowance !== null) return `${remaining} of ${allowance} left`;
+  if (used !== null) return `${used} used`;
+  if (utilization !== null) return `${Math.round(utilization * 10) / 10}% used`;
+  return '';
+}
+
+function renderMeter(meter, now) {
+  const utilization = toNullableNumber(meter.utilization);
+  const width = meter.unlimited ? 100 : Math.max(0, Math.min(100, utilization ?? 0));
+  const color = meter.unlimited ? '#3fb950' : utilizationColor(utilization);
+  const summary = meterSummaryText(meter);
+  const countdown = formatResetCountdown(meter.resetAt, now);
+  const percentLabel = meter.unlimited
+    ? '∞'
+    : (utilization === null ? '—' : `${Math.round(utilization)}%`);
+  const flags = [
+    meter.estimated ? '<span class="plan-usage-flag">estimated</span>' : '',
+  ].filter(Boolean).join('');
+  const meta = [summary, countdown].filter(Boolean).join(' · ');
+
+  return `
+    <div class="plan-usage-meter plan-usage-meter-${escapeHtml(meter.emphasis || 'primary')}" data-meter-id="${escapeHtml(meter.id)}">
+      <div class="plan-usage-meter-head">
+        <span class="plan-usage-meter-label">${escapeHtml(meter.label)}${flags}</span>
+        <span class="plan-usage-meter-pct">${escapeHtml(percentLabel)}</span>
+      </div>
+      <div class="plan-usage-bar" role="img" aria-label="${escapeHtml(`${meter.label}: ${percentLabel} used`)}">
+        <span class="plan-usage-bar-fill${utilization === null && !meter.unlimited ? ' plan-usage-bar-unknown' : ''}" style="width:${width}%;background:${color}"></span>
+      </div>
+      ${meta ? `<div class="plan-usage-meter-meta">${escapeHtml(meta)}</div>` : ''}
+      ${meter.note ? `<div class="plan-usage-meter-note">${escapeHtml(meter.note)}</div>` : ''}
+    </div>
+  `;
+}
+
+function renderDetailSection(section) {
+  const rows = section.rows.map((row) => `
+    <tr>
+      <td class="plan-usage-detail-label">${escapeHtml(row.label)}${row.hint ? `<span class="plan-usage-detail-hint">${escapeHtml(row.hint)}</span>` : ''}</td>
+      <td class="plan-usage-detail-value">${escapeHtml(row.value)}</td>
+    </tr>
+  `).join('');
+  return `
+    <details class="plan-usage-details" data-section-id="${escapeHtml(section.id)}">
+      <summary>${escapeHtml(section.label)}</summary>
+      ${section.note ? `<div class="plan-usage-detail-note">${escapeHtml(section.note)}</div>` : ''}
+      <table class="plan-usage-detail-table"><tbody>${rows}</tbody></table>
+    </details>
+  `;
+}
+
+/**
+ * The signed-in account under the card title. Three distinct states, because
+ * "we could not ask" must not be drawn as "you are logged out": no `account`
+ * key renders nothing at all, `{loggedIn:false}` says so, anything else shows
+ * whatever identity we have.
+ */
+function renderAccountLine(account) {
+  if (!account || typeof account !== 'object') return '';
+  if (account.loggedIn === false) {
+    return '<span class="plan-usage-account plan-usage-account-signed-out">Not logged in</span>';
+  }
+  const parts = [account.email, account.plan]
+    .map((value) => String(value ?? '').trim())
+    .filter(Boolean);
+  if (!parts.length) {
+    return account.loggedIn === true
+      ? '<span class="plan-usage-account">Logged in</span>'
+      : '';
+  }
+  return `<span class="plan-usage-account">${parts.map(escapeHtml).join(' · ')}</span>`;
+}
+
+function renderCard(card, now, { active = true } = {}) {
+  const meters = Array.isArray(card.meters) ? card.meters : [];
+  const details = Array.isArray(card.details) ? card.details : [];
+  const links = Array.isArray(card.links) ? card.links : [];
+
+  const statusBadge = STATUS_BADGES[card.status];
+  const sourceBadge = SOURCE_LABELS[card.source];
+  const badges = [
+    card.planName ? `<span class="plan-usage-badge plan-usage-badge-plan">${escapeHtml(card.planName)}</span>` : '',
+    statusBadge ? `<span class="plan-usage-badge plan-usage-badge-status">${escapeHtml(statusBadge)}</span>` : '',
+    sourceBadge ? `<span class="plan-usage-badge">${escapeHtml(sourceBadge)}</span>` : '',
+  ].filter(Boolean).join('');
+
+  const primary = meters.filter((meter) => meter.emphasis !== 'secondary');
+  const secondary = meters.filter((meter) => meter.emphasis === 'secondary');
+
+  const metersHtml = meters.length
+    ? `${primary.map((meter) => renderMeter(meter, now)).join('')}${
+      secondary.length
+        ? `<div class="plan-usage-secondary">${secondary.map((meter) => renderMeter(meter, now)).join('')}</div>`
+        : ''
+    }`
+    : '';
+
+  const capturedLabel = card.capturedAt
+    ? `Updated ${escapeHtml(String(card.capturedAt).replace('T', ' ').slice(0, 16))} UTC`
+    : '';
+
+  const panelId = normalizeUsageProvider(card.provider);
+  return `
+    <section class="plan-usage-card plan-usage-card-${escapeHtml(card.provider)}" data-provider="${escapeHtml(card.provider)}" data-usage-panel="${escapeHtml(panelId)}" data-status="${escapeHtml(card.status)}" role="tabpanel" id="plan-usage-panel-${escapeHtml(panelId)}" aria-labelledby="plan-usage-tab-${escapeHtml(panelId)}" tabindex="0"${active ? '' : ' hidden'}>
+      <header class="plan-usage-card-head">
+        <span class="plan-usage-card-titles">
+          <span class="plan-usage-card-title">${escapeHtml(card.label)}</span>
+          ${renderAccountLine(card.account)}
+        </span>
+        <span class="plan-usage-badges">${badges}</span>
+      </header>
+      ${card.message ? `<div class="plan-usage-message">${escapeHtml(card.message)}</div>` : ''}
+      ${metersHtml}
+      ${details.map(renderDetailSection).join('')}
+      <div class="plan-usage-card-foot">
+        ${capturedLabel ? `<span class="plan-usage-captured">${capturedLabel}</span>` : ''}
+        ${links.map((link) => `<a class="plan-usage-link" href="${escapeHtml(link.url)}" target="_blank" rel="noopener noreferrer">${escapeHtml(link.label)}</a>`).join('')}
+      </div>
+    </section>
+  `;
+}
+
+function renderTab(card, activeProvider) {
+  const id = normalizeUsageProvider(card.provider);
+  const active = id === activeProvider;
+  const label = TAB_LABELS[id] || card.label || id;
+  return `<button type="button" class="plan-usage-tab${active ? ' active' : ''}" role="tab" id="plan-usage-tab-${escapeHtml(id)}" aria-controls="plan-usage-panel-${escapeHtml(id)}" aria-selected="${active ? 'true' : 'false'}" tabindex="${active ? '0' : '-1'}" data-usage-tab="${escapeHtml(id)}">${escapeHtml(label)}</button>`;
+}
+
+/**
+ * @param {object|null} report the `/api/usage` payload
+ * @param {object} [options]
+ * @param {Date} [options.now] injectable clock so countdowns are testable
+ * @param {string} [options.activeProvider] the session's provider; selects its
+ *   tab when that provider has a card
+ * @returns {string} modal body HTML, or '' when there is nothing to render
+ */
+export function renderPlanUsageHtml(report, { now = new Date(), activeProvider = '' } = {}) {
+  const providers = Array.isArray(report?.providers) ? report.providers.filter(Boolean) : [];
+  if (!providers.length) return '';
+  const active = resolveActiveUsageProvider(providers, activeProvider);
+  const tabs = providers.map((card) => renderTab(card, active)).join('');
+  const cards = providers
+    .map((card) => renderCard(card, now, { active: normalizeUsageProvider(card.provider) === active }))
+    .join('');
+  return `<div class="plan-usage"><div class="plan-usage-tab-strip" role="tablist" aria-label="Usage providers">${tabs}</div>${cards}</div>`;
+}
+
+/** Subtitle for the modal header: the healthiest available "what matters now" line. */
+export function planUsageSubtitle(report) {
+  const providers = Array.isArray(report?.providers) ? report.providers.filter(Boolean) : [];
+  if (!providers.length) return 'No usage data available';
+  const available = providers.filter((card) => Array.isArray(card.meters) && card.meters.length);
+  if (!available.length) return 'No plan limits reported yet';
+  const soonest = available
+    .flatMap((card) => card.meters.map((meter) => meter.resetAt))
+    .filter(Boolean)
+    .sort()[0];
+  const countdown = formatResetCountdown(soonest);
+  return countdown
+    ? `${available.length} provider${available.length === 1 ? '' : 's'} reporting · next reset ${countdown.replace(/^resets /, '')}`
+    : `${available.length} provider${available.length === 1 ? '' : 's'} reporting`;
+}

package/server/public/app/preview-cards.mjs

@@ -0,0 +1,273 @@
+// Preview cards: live dev servers published through the preview lane. Fed by
+// the `previews` socket event (REPLACE semantics for the whole set, since the
+// registry is relay-owned and global) and by the conversation payload's
+// `previews` on reload.
+//
+// The same row builder serves both surfaces: the composer's background-task
+// panel (this conversation's previews, beside the Bash task running the dev
+// server) and the settings modal's "Live previews" list (every session's).
+// Previews never expire, so the settings list is the one place that can always
+// close a link left behind in a conversation you have moved on from.
+
+import { apiFetch } from './api-client.js';
+
+let previews = [];
+const closesInFlight = new Set();
+const subscribers = new Set();
+
+export function subscribePreviews(callback) {
+  if (typeof callback !== 'function') return () => {};
+  subscribers.add(callback);
+  return () => subscribers.delete(callback);
+}
+
+function notify() {
+  for (const callback of subscribers) {
+    try { callback(previews); } catch {}
+  }
+}
+
+function normalizePreview(entry) {
+  if (!entry || typeof entry !== 'object') return null;
+  const token = String(entry.token || '').trim();
+  if (!token) return null;
+  return {
+    token,
+    conversationId: String(entry.conversationId || '').trim() || null,
+    label: String(entry.label || '').trim() || 'Preview',
+    targetHost: String(entry.targetHost || '').trim(),
+    targetPort: Number(entry.targetPort) || null,
+    url: String(entry.url || '').trim(),
+    basePath: String(entry.basePath || '').trim(),
+    createdAt: Number(entry.createdAt) || null,
+    // null = not probed yet; the badge stays absent rather than guessing.
+    online: entry.online === true ? true : (entry.online === false ? false : null),
+  };
+}
+
+export function setPreviews(nextPreviews) {
+  previews = (Array.isArray(nextPreviews) ? nextPreviews : [])
+    .map(normalizePreview)
+    .filter(Boolean);
+  notify();
+}
+
+// The conversation payload only carries that conversation's previews, so it
+// merges into the global set rather than replacing it — otherwise opening a
+// conversation would erase every other session's cards until the next socket
+// event.
+export function mergeConversationPreviews(conversationId, conversationPreviews) {
+  const id = String(conversationId || '').trim();
+  if (!id) return;
+  const incoming = (Array.isArray(conversationPreviews) ? conversationPreviews : [])
+    .map(normalizePreview)
+    .filter(Boolean);
+  previews = previews.filter((entry) => entry.conversationId !== id).concat(incoming);
+  notify();
+}
+
+export function getPreviews() {
+  return previews;
+}
+
+export function getPreviewsForConversation(conversationId) {
+  const id = String(conversationId || '').trim();
+  if (!id) return [];
+  return previews.filter((entry) => entry.conversationId === id);
+}
+
+export async function closePreview(token) {
+  const id = String(token || '').trim();
+  if (!id || closesInFlight.has(id)) return;
+  closesInFlight.add(id);
+  notify();
+  try {
+    // apiFetch resolves to null on a network error or a non-2xx status rather
+    // than throwing, so success has to be checked, not assumed: a card removed
+    // on a failed DELETE would hide a link that is still publicly live.
+    const response = await apiFetch(`/api/previews/${encodeURIComponent(id)}`, { method: 'DELETE' });
+    if (response?.ok === true) {
+      // Optimistic removal: the socket event will confirm, but the card should
+      // not linger while the round trip completes.
+      previews = previews.filter((entry) => entry.token !== id);
+    }
+  } catch {
+    // Left in place on failure so the user can retry rather than lose the link.
+  } finally {
+    closesInFlight.delete(id);
+    notify();
+  }
+}
+
+async function copyPreviewUrl(url, button) {
+  try {
+    await navigator.clipboard.writeText(url);
+    const previousText = button.textContent;
+    button.textContent = 'Copied';
+    setTimeout(() => { button.textContent = previousText; }, 1500);
+  } catch {
+    button.textContent = 'Copy failed';
+  }
+}
+
+function previewDetail(preview, { withConversation = false } = {}) {
+  const parts = [];
+  if (preview.targetPort) parts.push(`:${preview.targetPort}`);
+  if (preview.online === false) parts.push('offline — dev server not responding');
+  if (withConversation && preview.conversationId) {
+    parts.push(`session ${preview.conversationId.slice(0, 8)}`);
+  }
+  return parts.join(' · ');
+}
+
+/**
+ * One preview row. Built with createElement/textContent throughout: a label is
+ * agent-supplied text and must never be able to execute as markup.
+ */
+export function buildPreviewRow(preview, { withConversation = false } = {}) {
+  const row = document.createElement('div');
+  row.className = 'preview-row';
+  row.dataset.token = preview.token;
+  if (preview.online === false) row.classList.add('preview-row-offline');
+
+  const icon = document.createElement('span');
+  icon.className = 'preview-icon';
+  icon.textContent = '🌐';
+  icon.title = 'Preview server';
+  row.appendChild(icon);
+
+  const main = document.createElement('span');
+  main.className = 'preview-main';
+  row.appendChild(main);
+
+  const label = document.createElement('span');
+  label.className = 'preview-label';
+  label.textContent = preview.label;
+  main.appendChild(label);
+
+  const detailText = previewDetail(preview, { withConversation });
+  if (detailText) {
+    const detail = document.createElement('span');
+    detail.className = 'preview-detail';
+    detail.textContent = detailText;
+    main.appendChild(detail);
+  }
+
+  // The link is public: anyone who has it reaches the dev server without
+  // logging in, so the card says so rather than leaving it to be discovered.
+  const warning = document.createElement('span');
+  warning.className = 'preview-warning';
+  warning.textContent = 'public link — anyone with the URL can reach this app';
+  main.appendChild(warning);
+
+  const side = document.createElement('span');
+  side.className = 'preview-side';
+  row.appendChild(side);
+
+  if (preview.online !== null) {
+    const badge = document.createElement('span');
+    badge.className = preview.online
+      ? 'preview-badge preview-badge-online'
+      : 'preview-badge preview-badge-offline';
+    badge.textContent = preview.online ? 'online' : 'offline';
+    side.appendChild(badge);
+  }
+
+  const actions = document.createElement('span');
+  actions.className = 'preview-actions';
+  side.appendChild(actions);
+
+  const open = document.createElement('a');
+  open.className = 'preview-open';
+  open.href = preview.url;
+  open.target = '_blank';
+  // noopener/noreferrer: the preview is a different origin running app code we
+  // do not control, and it has no business holding a handle on this window.
+  open.rel = 'noopener noreferrer';
+  open.textContent = 'Open';
+  actions.appendChild(open);
+
+  const copy = document.createElement('button');
+  copy.type = 'button';
+  copy.className = 'preview-copy';
+  copy.textContent = 'Copy link';
+  copy.addEventListener('click', (event) => {
+    event.preventDefault();
+    void copyPreviewUrl(preview.url, copy);
+  });
+  actions.appendChild(copy);
+
+  const closing = closesInFlight.has(preview.token);
+  const close = document.createElement('button');
+  close.type = 'button';
+  close.className = 'preview-close';
+  close.disabled = closing;
+  close.textContent = closing ? 'Closing…' : 'Close';
+  close.addEventListener('click', (event) => {
+    event.preventDefault();
+    void closePreview(preview.token);
+  });
+  actions.appendChild(close);
+
+  return row;
+}
+
+/**
+ * Transcript card for a preview published during a turn. Renders from the
+ * persisted snapshot (the registry may be long gone), overlaying live state
+ * from the current store: a token still registered gets a working row, a
+ * vanished one keeps the label but drops the dead link for a `closed` badge.
+ */
+export function buildTranscriptPreviewCard(snapshot) {
+  const preview = normalizePreview(snapshot);
+  if (!preview) return null;
+  const live = previews.some((entry) => entry.token === preview.token);
+
+  const card = document.createElement('div');
+  card.className = live ? 'msg-preview-card' : 'msg-preview-card msg-preview-card-closed';
+
+  const icon = document.createElement('span');
+  icon.className = 'preview-icon';
+  icon.textContent = '🌐';
+  card.appendChild(icon);
+
+  const label = document.createElement('span');
+  label.className = 'preview-label';
+  label.textContent = preview.label;
+  card.appendChild(label);
+
+  if (live) {
+    const open = document.createElement('a');
+    open.className = 'preview-open';
+    open.href = preview.url;
+    open.target = '_blank';
+    open.rel = 'noopener noreferrer';
+    open.textContent = 'Open';
+    card.appendChild(open);
+
+    const copy = document.createElement('button');
+    copy.type = 'button';
+    copy.className = 'preview-copy';
+    copy.textContent = 'Copy link';
+    copy.addEventListener('click', (event) => {
+      event.preventDefault();
+      void copyPreviewUrl(preview.url, copy);
+    });
+    card.appendChild(copy);
+  } else {
+    const badge = document.createElement('span');
+    badge.className = 'preview-badge preview-badge-offline';
+    badge.textContent = 'closed';
+    card.appendChild(badge);
+  }
+  return card;
+}
+
+export function renderPreviewRowsInto(container, rows, options = {}) {
+  if (!container) return 0;
+  container.textContent = '';
+  for (const preview of rows) {
+    container.appendChild(buildPreviewRow(preview, options));
+  }
+  return rows.length;
+}

package/server/public/app/preview-command.mjs

@@ -0,0 +1,103 @@
+// The /preview composer command: publish a port or directory, list, or close —
+// entirely client-side against the relay API, so it works identically on every
+// provider and never costs an agent turn. Mirrors the /compact intercept in
+// conversation-view.js: parsed before anything is queued, unknown syntax falls
+// through to a help line, never to the model.
+
+import { apiFetch } from './api-client.js';
+
+export const PREVIEW_COMMAND_HELP =
+  'Usage: /preview <port> [label] · /preview <dir> [label] · /preview list · /preview close [token-prefix]';
+
+/**
+ * Returns null when the text is not a /preview command at all (the composer
+ * sends it as a normal message); otherwise a parsed command, with unparseable
+ * input mapped to {kind:'help'} so it never reaches the model by accident.
+ */
+export function parsePreviewCommand(text) {
+  const trimmed = String(text || '').trim();
+  if (!/^\/preview(\s|$)/i.test(trimmed)) return null;
+  const rest = trimmed.replace(/^\/preview\s*/i, '').trim();
+  if (!rest) return { kind: 'help' };
+
+  const [first, ...restParts] = rest.split(/\s+/);
+  const remainder = restParts.join(' ').trim();
+
+  if (/^list$/i.test(first)) return { kind: 'list' };
+  if (/^close$/i.test(first)) {
+    const prefix = remainder.toLowerCase();
+    if (prefix && !/^[0-9a-f]{4,32}$/.test(prefix)) return { kind: 'help' };
+    return { kind: 'close', tokenPrefix: prefix || null };
+  }
+  if (/^\d+$/.test(first)) {
+    const port = Number(first);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) return { kind: 'help' };
+    return { kind: 'create-port', port, label: remainder || null };
+  }
+  // Anything path-shaped is a static preview. Windows drive letters ("C:\x")
+  // and dotted relatives all land here; the server does the real validation.
+  return { kind: 'create-dir', dir: first, label: remainder || null };
+}
+
+async function closeByPrefix(tokenPrefix, conversationId) {
+  const listed = await apiFetch(`/api/previews${tokenPrefix ? '' : `?conversationId=${encodeURIComponent(conversationId || '')}`}`);
+  const previews = listed?.previews || [];
+  const matches = tokenPrefix
+    ? previews.filter((entry) => String(entry.token || '').startsWith(tokenPrefix))
+    : previews;
+  if (matches.length === 0) {
+    return { ok: false, notice: tokenPrefix ? `No preview matches "${tokenPrefix}".` : 'No live previews in this conversation.' };
+  }
+  if (matches.length > 1) {
+    const names = matches.map((entry) => `${entry.token.slice(0, 8)} (${entry.label})`).join(', ');
+    return { ok: false, notice: `Ambiguous — matches: ${names}. Use a longer prefix.` };
+  }
+  const closed = await apiFetch(`/api/previews/${encodeURIComponent(matches[0].token)}`, { method: 'DELETE' });
+  if (closed?.ok !== true) return { ok: false, notice: 'Close failed — the preview may already be gone.' };
+  return { ok: true, notice: `Preview closed: ${matches[0].label}` };
+}
+
+/**
+ * Executes a parsed command. Returns `{ ok, notice }`; the caller renders the
+ * notice. Creation results also surface as panel cards via the `previews`
+ * socket event, so the notice only needs to carry the URL once.
+ */
+export async function runPreviewCommand(parsed, { conversationId = '' } = {}) {
+  if (!parsed || parsed.kind === 'help') return { ok: true, notice: PREVIEW_COMMAND_HELP };
+
+  try {
+    if (parsed.kind === 'list') {
+      const listed = await apiFetch('/api/previews');
+      if (!listed) return { ok: false, notice: 'Could not reach the relay.' };
+      if (listed.enabled !== true) return { ok: false, notice: 'The preview lane is disabled on this relay.' };
+      const previews = listed.previews || [];
+      if (!previews.length) return { ok: true, notice: 'No live previews.' };
+      const lines = previews.map((entry) => {
+        const target = entry.mode === 'static' ? entry.rootDir : `:${entry.targetPort}`;
+        const state = entry.online === false ? ' — offline' : '';
+        return `${entry.token.slice(0, 8)} · ${entry.label} (${target})${state} → ${entry.url}`;
+      });
+      return { ok: true, notice: lines.join('\n') };
+    }
+
+    if (parsed.kind === 'close') {
+      return await closeByPrefix(parsed.tokenPrefix, conversationId);
+    }
+
+    const body = {
+      conversationId: conversationId || undefined,
+      label: parsed.label || undefined,
+      ...(parsed.kind === 'create-port' ? { port: parsed.port } : { dir: parsed.dir }),
+    };
+    const created = await apiFetch('/api/previews', { method: 'POST', body: JSON.stringify(body) });
+    if (created?.ok !== true) {
+      // apiFetch swallows the response body on non-2xx, so the specific server
+      // error (bad port, jail refusal, lane disabled) is not recoverable here;
+      // point at the panel where the states are visible instead.
+      return { ok: false, notice: 'Preview failed — check the port/path, or whether the preview lane is enabled (Settings → Live previews).' };
+    }
+    return { ok: true, notice: `Preview published: ${created.url}` };
+  } catch {
+    return { ok: false, notice: 'Preview command failed — could not reach the relay.' };
+  }
+}