@etiquekit/etq 1.0.12 → 1.0.14

package/packages/control/src/projection/timeline-preview.ts

@@ -0,0 +1,539 @@
+import { applyTimelineDeepLink, type TimelineFeedItem, type TimelineItemType, type TimelineView } from './timeline';
+
+export const TIMELINE_PREVIEW_ALLOWED_METHODS = ['GET', 'HEAD', 'OPTIONS'] as const;
+
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+function titleCase(value: string): string {
+  return value.charAt(0).toUpperCase() + value.slice(1);
+}
+
+function itemBadge(itemType: TimelineItemType): string {
+  switch (itemType) {
+    case 'task_card':
+      return 'TASK';
+    case 'return':
+      return 'RETURN';
+    case 'receipt':
+      return 'RECEIPT';
+    case 'decision':
+      return 'DECISION';
+    case 'chatter':
+      return 'CHATTER';
+  }
+}
+
+function itemTone(itemType: TimelineItemType): string {
+  switch (itemType) {
+    case 'task_card':
+      return 'task';
+    case 'return':
+      return 'return';
+    case 'receipt':
+      return 'receipt';
+    case 'decision':
+      return 'decision';
+    case 'chatter':
+      return 'chatter';
+  }
+}
+
+function sourceRef(item: TimelineFeedItem): string {
+  return item.source.event_ref ?? item.source.packet_ref ?? 'unsequenced';
+}
+
+function participants(item: TimelineFeedItem): string {
+  const parts = [
+    item.actor_seat_id ? `from ${item.actor_seat_id}` : null,
+    item.seat_id ? `seat ${item.seat_id}` : null,
+    item.operator_principal ? `operator ${item.operator_principal}` : null,
+  ].filter((part): part is string => Boolean(part));
+  return parts.length > 0 ? parts.join(' / ') : 'seat unresolved';
+}
+
+function chip(label: string, value: string | null, className = ''): string {
+  return value ? `<span class="chip ${escapeHtml(className)}"><strong>${escapeHtml(label)}</strong>${escapeHtml(value)}</span>` : '';
+}
+
+function renderSections(item: TimelineFeedItem): string {
+  return `<div class="sections" role="tablist" aria-label="Card sections">
+    ${item.display.sections.map((section, index) => `<section class="card-section" role="tabpanel" aria-labelledby="${escapeHtml(item.item_id)}-tab-${index}">
+      <button id="${escapeHtml(item.item_id)}-tab-${index}" type="button" class="section-tab">${escapeHtml(section.label)}</button>
+      <p>${escapeHtml(section.body)}</p>
+    </section>`).join('\n')}
+  </div>`;
+}
+
+function renderItem(item: TimelineFeedItem): string {
+  const tone = itemTone(item.item_type);
+  const seqAnchor = item.source.seq === null ? escapeHtml(item.item_id) : `seq-${String(item.source.seq)}`;
+  return `<article id="${seqAnchor}" class="feed-item ${tone}" data-item-type="${escapeHtml(item.item_type)}" data-thread-id="${escapeHtml(item.thread.thread_id)}" data-depth="${String(item.thread.depth)}">
+    <div class="item-head">
+      <span class="badge ${tone}">${escapeHtml(itemBadge(item.item_type))}</span>
+      <time>${escapeHtml(item.created_at ?? 'time unknown')}</time>
+    </div>
+    <div class="chips" aria-label="Timeline metadata">
+      ${chip('seat', item.display.seat_badge, 'seat')}
+      ${chip('role', item.display.role_chip, 'role')}
+      ${chip('lane', item.display.lane_chip, 'lane')}
+      ${chip('verdict', item.display.verdict_pill, 'verdict-pill')}
+      ${chip('status', item.display.status_subtitle, 'status')}
+      ${item.display.topic_chips.map((topic) => chip('topic', topic, 'topic')).join('')}
+      ${item.requires_ack === true ? '<span class="chip ack"><strong>ack</strong>requires_ack</span>' : ''}
+    </div>
+    <h2>${escapeHtml(item.title)}</h2>
+    <p class="body">${escapeHtml(item.body)}</p>
+    ${renderSections(item)}
+    <dl>
+      <div><dt>Source</dt><dd><code>${escapeHtml(sourceRef(item))}</code></dd></div>
+      <div><dt>Participants</dt><dd>${escapeHtml(participants(item))}</dd></div>
+      ${item.lane ? `<div><dt>Lane</dt><dd><code>${escapeHtml(item.lane)}</code></dd></div>` : ''}
+      <div><dt>Thread</dt><dd><code>${escapeHtml(item.thread.thread_id)}</code> - ${String(item.thread.thread_item_count)} item${item.thread.thread_item_count === 1 ? '' : 's'}</dd></div>
+      <div><dt>Authority</dt><dd>projection only; cannot execute, write back, grant, close, merge, or sign</dd></div>
+    </dl>
+  </article>`;
+}
+
+function renderThreadIndex(view: TimelineView): string {
+  if (view.feed.threads.length === 0) return '<section class="empty">No threads found for this scope.</section>';
+  return `<ol class="thread-index">
+    ${view.feed.threads.map((thread) => `<li>
+      <a href="#${escapeHtml(thread.latest_seq === null ? thread.item_ids[0] : `seq-${thread.latest_seq}`)}">${escapeHtml(thread.title)}</a>
+      <span>${String(thread.item_count)} items</span>
+    </li>`).join('\n')}
+  </ol>`;
+}
+
+function renderCuratorPortal(view: TimelineView): string {
+  const seats = view.curator_portal.health_board.seats.length > 0
+    ? view.curator_portal.health_board.seats.map((seat) => `<tr>
+      <td><code>${escapeHtml(seat.seat_id)}</code></td>
+      <td>${escapeHtml(seat.lifecycle_state)}</td>
+      <td>${seat.ready ? 'ready' : 'not ready'}</td>
+      <td>${escapeHtml(seat.source)}</td>
+      <td><code>${escapeHtml(seat.sentinel_state_ref)}</code></td>
+    </tr>`).join('\n')
+    : '<tr><td colspan="5">No seats in this projection.</td></tr>';
+  const queue = view.curator_portal.promotion_queue.items.length > 0
+    ? view.curator_portal.promotion_queue.items.map((item) => `<li><code>${escapeHtml(item.source_ref)}</code> ${escapeHtml(item.reason)} ${item.next_owner ? `- next ${escapeHtml(item.next_owner)}` : ''}</li>`).join('\n')
+    : '<li>No display-only queue items.</li>';
+  return `<section class="curator" aria-label="Curator Portal">
+    <div class="section-title">
+      <h2>Curator Portal</h2>
+      <span>display-only</span>
+    </div>
+    <div class="curator-grid">
+      <section>
+        <h3>Health board</h3>
+        <table>
+          <thead><tr><th>Seat</th><th>Lifecycle</th><th>Ready</th><th>Source</th><th>Sentinel</th></tr></thead>
+          <tbody>${seats}</tbody>
+        </table>
+      </section>
+      <section>
+        <h3>Digest view</h3>
+        <dl>
+          <div><dt>Threads</dt><dd>${String(view.curator_portal.digest_view.threads)}</dd></div>
+          <div><dt>Requires ack</dt><dd>${String(view.curator_portal.digest_view.requires_ack)}</dd></div>
+          <div><dt>Tasks</dt><dd>${String(view.curator_portal.digest_view.items_by_type.task_card)}</dd></div>
+          <div><dt>Returns</dt><dd>${String(view.curator_portal.digest_view.items_by_type.return)}</dd></div>
+        </dl>
+      </section>
+      <section>
+        <h3>Promotion queue</h3>
+        <p>Display-only; cannot promote, grant, close, merge, execute, or write back.</p>
+        <ul>${queue}</ul>
+      </section>
+    </div>
+  </section>`;
+}
+
+export function renderTimelinePreviewHtml(view: TimelineView): string {
+  const items = view.feed.items.length > 0
+    ? view.feed.items.map((item) => renderItem(item)).join('\n')
+    : '<section class="empty">No timeline items found for this scope.</section>';
+  const selected = view.feed.deep_link.item_id ? `Selected ${view.feed.deep_link.event_ref ?? view.feed.deep_link.item_id}` : 'No deep link selected';
+  const scopeLabel = titleCase(view.scope);
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Etiquette Timeline Preview</title>
+  <style>
+    :root {
+      color-scheme: light;
+      --ink: #172026;
+      --muted: #5d6973;
+      --line: #d7dee5;
+      --surface: #ffffff;
+      --page: #f6f7f8;
+      --teal: #0f766e;
+      --amber: #a15c00;
+      --red: #b42318;
+      --blue: #2563eb;
+      --violet: #6d28d9;
+    }
+    * { box-sizing: border-box; }
+    body {
+      margin: 0;
+      font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      color: var(--ink);
+      background: var(--page);
+    }
+    main { width: min(1120px, calc(100% - 32px)); margin: 0 auto; padding: 24px 0 40px; }
+    header {
+      display: grid;
+      grid-template-columns: minmax(0, 1fr) auto;
+      gap: 16px;
+      align-items: end;
+      padding: 18px 0 16px;
+      border-bottom: 1px solid var(--line);
+    }
+    h1 { margin: 0; font-size: 28px; line-height: 1.15; letter-spacing: 0; }
+    .subhead { margin: 6px 0 0; color: var(--muted); line-height: 1.45; }
+    .scope {
+      display: inline-flex;
+      align-items: center;
+      min-height: 32px;
+      padding: 6px 10px;
+      border-radius: 8px;
+      background: #e6f4f1;
+      color: #075e57;
+      font-weight: 700;
+      white-space: nowrap;
+    }
+    .summary {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
+      gap: 10px;
+      margin: 18px 0;
+    }
+    .metric {
+      background: var(--surface);
+      border: 1px solid var(--line);
+      border-radius: 8px;
+      padding: 12px;
+      min-width: 0;
+    }
+    .metric span { display: block; color: var(--muted); font-size: 12px; }
+    .metric strong { display: block; margin-top: 4px; font-size: 18px; overflow-wrap: anywhere; }
+    .boundary {
+      display: grid;
+      gap: 8px;
+      margin: 18px 0;
+      padding: 14px;
+      border: 1px solid #f0c36d;
+      border-left: 4px solid var(--amber);
+      border-radius: 8px;
+      background: #fff8eb;
+    }
+    .boundary strong { color: #7a4100; }
+    .view-controls {
+      display: flex;
+      flex-wrap: wrap;
+      align-items: center;
+      justify-content: space-between;
+      gap: 10px;
+      margin: 18px 0 10px;
+    }
+    .toggle {
+      display: inline-flex;
+      overflow: hidden;
+      border: 1px solid var(--line);
+      border-radius: 8px;
+      background: var(--surface);
+    }
+    .toggle a {
+      min-height: 34px;
+      padding: 8px 12px;
+      border-right: 1px solid var(--line);
+      color: var(--ink);
+      text-decoration: none;
+      font-weight: 700;
+    }
+    .toggle a:last-child { border-right: 0; }
+    .toggle a[aria-current="true"] { background: #e6f4f1; color: #075e57; }
+    .thread-index {
+      display: grid;
+      gap: 8px;
+      margin: 0 0 18px;
+      padding: 0;
+      list-style: none;
+    }
+    .thread-index li {
+      display: flex;
+      gap: 10px;
+      justify-content: space-between;
+      padding: 10px 12px;
+      border: 1px solid var(--line);
+      border-radius: 8px;
+      background: var(--surface);
+    }
+    .thread-index a { color: var(--blue); font-weight: 700; overflow-wrap: anywhere; }
+    .feed { display: grid; gap: 12px; margin-top: 18px; }
+    .feed-item {
+      background: var(--surface);
+      border: 1px solid var(--line);
+      border-left: 4px solid var(--teal);
+      border-radius: 8px;
+      padding: 14px;
+    }
+    .feed-item.return { border-left-color: var(--blue); }
+    .feed-item.receipt { border-left-color: var(--violet); }
+    .feed-item.decision { border-left-color: var(--red); }
+    .feed-item.chatter { border-left-color: #64748b; }
+    .item-head { display: flex; gap: 10px; align-items: center; justify-content: space-between; }
+    .badge {
+      display: inline-flex;
+      min-height: 24px;
+      align-items: center;
+      padding: 3px 8px;
+      border-radius: 6px;
+      background: #e6f4f1;
+      color: #075e57;
+      font-size: 12px;
+      font-weight: 800;
+    }
+    .badge.return { background: #eaf1ff; color: #1d4ed8; }
+    .badge.receipt { background: #f1eafe; color: #5b21b6; }
+    .badge.decision { background: #feeceb; color: #991b1b; }
+    .badge.chatter { background: #eef2f5; color: #475569; }
+    .chips {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 6px;
+      margin-top: 10px;
+    }
+    .chip {
+      display: inline-flex;
+      gap: 6px;
+      align-items: center;
+      min-height: 24px;
+      padding: 3px 8px;
+      border: 1px solid #d5dde6;
+      border-radius: 999px;
+      background: #f8fafc;
+      color: #334155;
+      font-size: 12px;
+    }
+    .chip strong { color: #64748b; font-weight: 800; }
+    .chip.verdict-pill { border-color: #bfd1ff; background: #eaf1ff; color: #1d4ed8; }
+    .chip.ack { border-color: #f5c2c0; background: #feeceb; color: #991b1b; }
+    time { color: var(--muted); font-size: 12px; text-align: right; }
+    h2 { margin: 10px 0 6px; font-size: 17px; letter-spacing: 0; line-height: 1.25; }
+    .body { margin: 0 0 12px; color: #334155; overflow-wrap: anywhere; }
+    .sections {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(210px, 1fr));
+      gap: 8px;
+      margin: 12px 0;
+    }
+    .card-section {
+      padding: 8px;
+      border: 1px solid var(--line);
+      border-radius: 8px;
+      background: #fbfcfd;
+    }
+    .section-tab {
+      border: 0;
+      padding: 0;
+      background: transparent;
+      color: var(--ink);
+      font-weight: 800;
+      text-align: left;
+    }
+    .card-section p { margin: 6px 0 0; color: var(--muted); font-size: 13px; line-height: 1.35; }
+    dl {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
+      gap: 8px 14px;
+      margin: 0;
+    }
+    dl div { min-width: 0; }
+    dt { color: var(--muted); font-size: 12px; }
+    dd { margin: 2px 0 0; overflow-wrap: anywhere; }
+    code {
+      padding: 2px 5px;
+      border-radius: 4px;
+      background: #eef2f5;
+      color: #263238;
+      font-size: 12px;
+    }
+    .empty {
+      padding: 20px;
+      border: 1px solid var(--line);
+      border-radius: 8px;
+      background: var(--surface);
+      color: var(--muted);
+    }
+    .curator {
+      margin-top: 22px;
+      padding-top: 18px;
+      border-top: 1px solid var(--line);
+    }
+    .section-title {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: 12px;
+      margin-bottom: 10px;
+    }
+    .section-title h2 { margin: 0; }
+    .section-title span {
+      padding: 4px 8px;
+      border-radius: 999px;
+      background: #eef2f5;
+      color: #475569;
+      font-size: 12px;
+      font-weight: 800;
+    }
+    .curator-grid {
+      display: grid;
+      grid-template-columns: minmax(0, 1.4fr) minmax(220px, .8fr);
+      gap: 12px;
+    }
+    .curator-grid section {
+      min-width: 0;
+      padding: 12px;
+      border: 1px solid var(--line);
+      border-radius: 8px;
+      background: var(--surface);
+    }
+    .curator-grid section:first-child { grid-row: span 2; }
+    .curator h3 { margin: 0 0 8px; font-size: 16px; }
+    table {
+      width: 100%;
+      border-collapse: collapse;
+      font-size: 13px;
+    }
+    th, td {
+      padding: 7px 6px;
+      border-bottom: 1px solid var(--line);
+      text-align: left;
+      vertical-align: top;
+      overflow-wrap: anywhere;
+    }
+    th { color: var(--muted); font-size: 12px; }
+    ul { margin: 8px 0 0; padding-left: 18px; }
+    @media (max-width: 640px) {
+      main { width: min(100% - 20px, 1120px); padding-top: 12px; }
+      header { grid-template-columns: 1fr; align-items: start; }
+      .scope { justify-self: start; }
+      .item-head { align-items: flex-start; flex-direction: column; }
+      time { text-align: left; }
+      .curator-grid { grid-template-columns: 1fr; }
+    }
+  </style>
+</head>
+<body data-authority="projection-only" data-ledger-write-path="false">
+  <main>
+    <header>
+      <div>
+        <h1>Etiquette Timeline Preview</h1>
+        <p class="subhead">Read-only loopback panel over the existing timeline projection.</p>
+      </div>
+      <span class="scope">${escapeHtml(scopeLabel)}</span>
+    </header>
+    <section class="summary" aria-label="Projection summary">
+      <div class="metric"><span>Schema</span><strong>${escapeHtml(view.schema)}</strong></div>
+      <div class="metric"><span>Items</span><strong>${String(view.feed.items_matched)}</strong></div>
+      <div class="metric"><span>Source</span><strong>${escapeHtml(view.source.projection_schema)}</strong></div>
+      <div class="metric"><span>Watermark</span><strong>${escapeHtml(view.watermark.latest_event_ref)}</strong></div>
+      <div class="metric"><span>Commit</span><strong>${escapeHtml(view.watermark.commit_sha)}</strong></div>
+      <div class="metric"><span>Event log hash</span><strong>${escapeHtml(view.watermark.event_log_hash)}</strong></div>
+    </section>
+    <section class="boundary">
+      <strong>Boundary</strong>
+      <span>${escapeHtml(view.boundary)}</span>
+      <span>GET/HEAD/OPTIONS only; no hosted backend, no auth provider, no impersonation, no execution, no write-back.</span>
+    </section>
+    <section class="view-controls" aria-label="Feed modes">
+      <nav class="toggle" aria-label="Timeline display modes">
+        <a href="#stream" aria-current="true">Stream</a>
+        <a href="#threads">Thread</a>
+      </nav>
+      <span>${escapeHtml(selected)}</span>
+    </section>
+    <section id="threads" aria-label="Thread index">
+      ${renderThreadIndex(view)}
+    </section>
+    <section id="stream" class="feed" aria-label="Timeline feed">
+      ${items}
+    </section>
+    ${renderCuratorPortal(view)}
+  </main>
+</body>
+</html>`;
+}
+
+function previewHeaders(contentType: string): Headers {
+  return new Headers({
+    'allow': TIMELINE_PREVIEW_ALLOWED_METHODS.join(', '),
+    'cache-control': 'no-store',
+    'content-type': contentType,
+    'x-etiquette-authority': 'projection-only',
+    'x-etiquette-ledger-write-path': 'false',
+  });
+}
+
+function emptyIfHead(request: Request, body: string): string | null {
+  return request.method === 'HEAD' ? null : body;
+}
+
+export async function timelinePreviewResponseForRequest(
+  request: Request,
+  buildView: () => Promise<TimelineView>,
+): Promise<Response> {
+  if (request.method === 'OPTIONS') {
+    return new Response(null, { status: 204, headers: previewHeaders('text/plain; charset=utf-8') });
+  }
+  if (request.method !== 'GET' && request.method !== 'HEAD') {
+    return Response.json(
+      {
+        error: 'method_not_allowed',
+        allowed_methods: TIMELINE_PREVIEW_ALLOWED_METHODS,
+        authority_boundary: {
+          request_can_write_ledger: false,
+          request_can_execute: false,
+          request_can_grant: false,
+        },
+      },
+      { status: 405, headers: previewHeaders('application/json; charset=utf-8') },
+    );
+  }
+
+  const url = new URL(request.url);
+  const requestedSeq = Number.parseInt(url.searchParams.get('seq') ?? '', 10);
+  const selectSeq = Number.isFinite(requestedSeq) ? requestedSeq : null;
+  if (url.pathname === '/api/timeline') {
+    const view = applyTimelineDeepLink(await buildView(), selectSeq);
+    return new Response(emptyIfHead(request, JSON.stringify(view, null, 2)), {
+      headers: previewHeaders('application/json; charset=utf-8'),
+    });
+  }
+  if (url.pathname === '/' || url.pathname === '/index.html') {
+    const view = applyTimelineDeepLink(await buildView(), selectSeq);
+    return new Response(emptyIfHead(request, renderTimelinePreviewHtml(view)), {
+      headers: previewHeaders('text/html; charset=utf-8'),
+    });
+  }
+  return Response.json(
+    {
+      error: 'not_found',
+      authority_boundary: {
+        request_can_write_ledger: false,
+        request_can_execute: false,
+        request_can_grant: false,
+      },
+    },
+    { status: 404, headers: previewHeaders('application/json; charset=utf-8') },
+  );
+}