Restyle staff and console UIs; add UI-Docs walkthrough and review PDF.

Match CS/sales/accounting/access-staff to the portal indigo system with dollar amounts, skip links, and empty states. Fleet replica actions move into overflow menus, roles become chips, Docs become cards, and the header copy reflects the 0.0.0.0 bind. Simulator uses the same shell (orange only for faults). Portal API keys are masked; admin customers edit in a drawer. Catalog uses system-ui. New UI-Docs repo holds screenshots, usage notes, and UI-REVIEW.pdf.
2026-09-11 18:01:33 -04:00 · 2026-09-11 18:01:33 -04:00 · cb07f5b321
commit cb07f5b321
parent ddf772454b
72 changed files with 3284 additions and 242 deletions
--- a/packages/ui-docs/scripts/build-review-pdf.py
+++ b/packages/ui-docs/scripts/build-review-pdf.py
@ -0,0 +1,207 @@
+#!/usr/bin/env python3
+"""Build UI-REVIEW.pdf from walkthrough screenshots + report text."""
+from __future__ import annotations
+
+from pathlib import Path
+
+from reportlab.lib import colors
+from reportlab.lib.enums import TA_LEFT
+from reportlab.lib.pagesizes import letter
+from reportlab.lib.styles import ParagraphStyle, getSampleStyleSheet
+from reportlab.lib.units import inch
+from reportlab.platypus import (
+    Image,
+    PageBreak,
+    Paragraph,
+    SimpleDocTemplate,
+    Spacer,
+    Table,
+    TableStyle,
+)
+
+ROOT = Path(__file__).resolve().parents[1]
+SHOTS = ROOT / "screenshots"
+OUT = ROOT / "UI-REVIEW.pdf"
+
+ACCENT = colors.HexColor("#4f46e5")
+INK = colors.HexColor("#171a26")
+MUTED = colors.HexColor("#6b7186")
+
+PAGES = [
+    ("01-console-fleet.png", "Operator console — Fleet",
+     "Open http://127.0.0.1:3850/. Role chips replace the truncated text field. Power is a status (on / paused / off), not a toggle. Replica and service actions live in the overflow menu."),
+    ("01b-console-fleet-overflow.png", "Fleet — replica overflow",
+     "Click the overflow control on a replica. Pause, resume, and restart are in one menu. Confirm still guards restart."),
+    ("02-console-trace.png", "Operator console — Trace",
+     "Trace tab. Orange box is fault inject only. Run step, then read hops on the right."),
+    ("02b-console-trace-run.png", "Trace after a run",
+     "Hop names wrap. Module column no longer clips. Monitors sit under the console."),
+    ("03-console-docs.png", "Operator console — Docs",
+     "Docs are cards matching Fleet, grouped High-level / Architecture / Remaining."),
+    ("04-simulator.png", "Standalone simulator",
+     "http://127.0.0.1:3847/ uses the indigo shell. Orange is the Inject faults panel only."),
+    ("04b-simulator-run.png", "Simulator after a run",
+     "Same hop grid as the console Trace tab. Run step or a scenario button."),
+    ("05-cs.png", "Customer service — review",
+     "http://127.0.0.1:3011/. Enter a customer id, Review account. Amounts are dollars."),
+    ("05-cs-credit.png", "Customer service — credit applied",
+     "Amount (USD) 5.00 → Apply credit. Prepaid and the credits table update in dollars."),
+    ("06-sales.png", "Sales — review",
+     "http://127.0.0.1:3012/. Review account or Show quote. Quote is a named card, not a JSON dump."),
+    ("07-accounting.png", "Accounting — review",
+     "http://127.0.0.1:3013/. Review plus QuickBooks IIF / CSV export buttons."),
+    ("08-access-staff.png", "Staff access plane",
+     "http://127.0.0.1:3025/. Same indigo review/credit UI after authz."),
+    ("09-admin-login.png", "Admin — sign in",
+     "http://127.0.0.1:3000/admin/. Seed user admin / admin-dev-key."),
+    ("10-admin-rate-card.png", "Admin — rate card",
+     "Landing tab after sign-in. Per-endpoint list prices."),
+    ("12-admin-customers.png", "Admin — customers list",
+     "Read-only table: name, email, type, billing. Edit opens the drawer."),
+    ("12b-admin-customer-drawer.png", "Admin — edit customer drawer",
+     "Change email, type, multiplier override, billing. Save or Cancel."),
+    ("14-admin-invoices.png", "Admin — invoices empty state",
+     "Illustrated empty state until a period is generated."),
+    ("16-portal-login.png", "Portal — sign in / create account",
+     "http://127.0.0.1:3000/portal/. Create an account or sign in."),
+    ("17-portal-dashboard.png", "Portal — dashboard",
+     "API key is masked. Reveal, Copy, or Regenerate. Copy puts the full key on the clipboard."),
+    ("18-portal-invoices-empty.png", "Portal — no invoices yet",
+     "Empty-state illustration instead of a blank table row."),
+    ("19-portal-statement.png", "Portal — statement",
+     "Prepaid, credits, usage, payments in dollars."),
+    ("20-portal-api-pricing.png", "Portal — API & pricing",
+     "Notes that /docs is stock Swagger UI, not a designed customer surface."),
+    ("21-swagger-stock.png", "Swagger /docs (stock)",
+     "Left as vendor Swagger. Do not treat it as the customer portal."),
+    ("22-catalog.png", "PDF catalog",
+     "https://zapier.georgelambert.org/ uses system-ui on the indigo header, not Georgia."),
+]
+
+
+def styles():
+    base = getSampleStyleSheet()
+    return {
+        "cover": ParagraphStyle("cover", parent=base["Title"], textColor=ACCENT, fontSize=22, leading=26, spaceAfter=12),
+        "h1": ParagraphStyle("h1", parent=base["Heading1"], textColor=ACCENT, fontSize=16, leading=20, spaceBefore=8, spaceAfter=8),
+        "h2": ParagraphStyle("h2", parent=base["Heading2"], textColor=INK, fontSize=13, leading=16, spaceBefore=6, spaceAfter=4),
+        "body": ParagraphStyle("body", parent=base["BodyText"], textColor=INK, fontSize=10, leading=13, alignment=TA_LEFT, spaceAfter=6),
+        "muted": ParagraphStyle("muted", parent=base["BodyText"], textColor=MUTED, fontSize=9, leading=12, spaceAfter=8),
+        "cap": ParagraphStyle("cap", parent=base["BodyText"], textColor=MUTED, fontSize=8, leading=11, spaceAfter=10),
+    }
+
+
+def header_footer(canvas, doc):
+    canvas.saveState()
+    canvas.setFillColor(ACCENT)
+    canvas.rect(0, letter[1] - 18, letter[0], 18, fill=1, stroke=0)
+    canvas.setFillColor(colors.white)
+    canvas.setFont("Helvetica", 8)
+    canvas.drawString(0.75 * inch, letter[1] - 13, "Verae Time x Zapier  ·  UI review")
+    canvas.setFillColor(MUTED)
+    canvas.drawRightString(letter[0] - 0.75 * inch, 0.45 * inch, f"{doc.page}")
+    canvas.restoreState()
+
+
+def p(text, style):
+    return Paragraph(text.replace("&", "&amp;"), style)
+
+
+def main():
+    s = styles()
+    story = []
+    story.append(p("UI review report", s["cover"]))
+    story.append(p("Walkthrough, screenshots, usage, remaining issues, and suggested improvements.", s["muted"]))
+    story.append(p("Captured 2026-09-11. Browser console: no application errors after favicon data-URI (catalog static server still 404s a missing favicon.ico until the next full site deploy).", s["body"]))
+
+    story.append(p("What was fixed in this pass", s["h1"]))
+    items = [
+        "CS / sales / accounting / access-staff restyled to the portal indigo system. Dollars and names, not cents forms.",
+        "Fleet replica and service actions collapsed to one overflow menu. Power column is status, not on/off toggles.",
+        "Add-machine roles are chips. Header copy is operator LAN · binds 0.0.0.0:3850 (NATS stays private).",
+        "Docs tab is cards. Trace hop grid wraps. Skip link and focus rings on staff and console.",
+        "Simulator indigo; orange only on Inject faults.",
+        "Portal API key masked with Reveal / Copy / Regenerate. Invoice empty-state illustration.",
+        "Admin customers: list vs edit drawer. Invoice empty state.",
+        "Catalog body font is system-ui. Swagger /docs labeled stock.",
+    ]
+    for it in items:
+        story.append(p("• " + it, s["body"]))
+
+    story.append(p("How to use each surface", s["h1"]))
+    story.append(p("Operator: open :3850, Fleet for replicas, Trace to inject a Zap step, Docs for PDFs. Staff: CS :3011 credit in USD; Sales :3012 quote; Accounting :3013 export; Staff plane :3025 after authz. Customers: /portal. Ops: /admin. Lab: simulator :3847.", s["body"]))
+
+    story.append(p("Issues still to consider", s["h1"]))
+    remaining = [
+        ["Severity", "Issue", "Suggestion"],
+        ["High", "Staff UIs look up by customer id; ledger often has no display name, so the heading is cust_1 not Ada.", "Join account-balance statements to zappier-edge customer name, or add a typeahead of customers."],
+        ["High", "Staff, portal, and admin have no session login on CS/sales/accounting HTML (LAN trust).", "Put a staff SSO or shared cookie in front of :3011–:3013 and :3025 before any non-lab bind."],
+        ["Med", "Catalog is still a long bibliography. Font is fixed; information architecture is not.", "Card index like the console Docs tab: Start here / Architecture / Modules."],
+        ["Med", "Swagger /docs remains stock.", "Keep it for integrators; do not skin it. Link it as 'OpenAPI explorer' only."],
+        ["Med", "Fleet add-machine form is dense; identity file still truncates in a narrow field.", "Two-row form: identity + roles on the second row with a file picker."],
+        ["Med", "lan-134 shows degraded/disabled in yellow while local/ns1 are green — correct, but the disable button looks like a fault.", "When a machine is intentionally disabled, use a neutral grey card, not degraded yellow."],
+        ["Low", "Portal statement empty cells still embed the empty illustration inside a table row.", "Drop the table when the list is empty; use the same card empty state as invoices."],
+        ["Low", "Overflow menus can open off-screen at the bottom of a long fleet table.", "Flip the menu upward when near the viewport edge."],
+        ["Low", "Access-staff and CS are nearly the same page.", "Keep both (plane vs department) but share one HTML template file."],
+        ["Low", "Simulator empty console is a large black void before the first run.", "Placeholder hop: 'Run a step to fill this trace.'"],
+    ]
+    body = getSampleStyleSheet()["BodyText"]
+    body.fontSize = 8
+    body.leading = 10
+    rows = []
+    for i, row in enumerate(remaining):
+        rows.append([Paragraph(f"<b>{c}</b>" if i == 0 else c, body) for c in row])
+    grid = Table(rows, colWidths=[0.7 * inch, 2.6 * inch, 3.4 * inch], repeatRows=1)
+    grid.setStyle(TableStyle([
+        ("BACKGROUND", (0, 0), (-1, 0), ACCENT),
+        ("TEXTCOLOR", (0, 0), (-1, 0), colors.white),
+        ("VALIGN", (0, 0), (-1, -1), "TOP"),
+        ("GRID", (0, 0), (-1, -1), 0.4, colors.HexColor("#e5e7f0")),
+        ("LEFTPADDING", (0, 0), (-1, -1), 6),
+        ("RIGHTPADDING", (0, 0), (-1, -1), 6),
+        ("TOPPADDING", (0, 0), (-1, -1), 5),
+        ("BOTTOMPADDING", (0, 0), (-1, -1), 5),
+        ("ROWBACKGROUNDS", (0, 1), (-1, -1), [colors.white, colors.HexColor("#f4f5fb")]),
+    ]))
+    story.append(grid)
+    story.append(PageBreak())
+
+    story.append(p("Screenshot atlas with usage notes", s["h1"]))
+    max_w = 6.5 * inch
+    max_h = 7.2 * inch
+    for fname, title, how in PAGES:
+        path = SHOTS / fname
+        if not path.exists():
+            story.append(p(f"Missing {fname}", s["muted"]))
+            continue
+        story.append(p(title, s["h2"]))
+        story.append(p(how, s["body"]))
+        img = Image(str(path))
+        iw, ih = img.imageWidth, img.imageHeight
+        scale = min(max_w / iw, max_h / ih)
+        img.drawWidth = iw * scale
+        img.drawHeight = ih * scale
+        img.hAlign = "CENTER"
+        story.append(img)
+        story.append(p(fname, s["cap"]))
+        story.append(PageBreak())
+
+    story.append(p("Revalidation", s["h1"]))
+    story.append(p("Second full walkthrough after favicon, amount-column alignment, and Fleet form/overflow fixes: 32 screenshots, 0 application console errors. Surfaces are visually consistent (indigo, 12px radius, dollars). Tasks (review, credit, quote, edit customer, mask key, run trace) are obvious from primary buttons. Remaining work is identity join, staff auth, and catalog IA — listed above.", s["body"]))
+
+    doc = SimpleDocTemplate(
+        str(OUT),
+        pagesize=letter,
+        leftMargin=0.75 * inch,
+        rightMargin=0.75 * inch,
+        topMargin=0.7 * inch,
+        bottomMargin=0.7 * inch,
+        title="Verae Time × Zapier UI review",
+        author="UI-Docs",
+    )
+    doc.build(story, onFirstPage=header_footer, onLaterPages=header_footer)
+    print(OUT)
+
+
+if __name__ == "__main__":
+    main()
--- a/packages/ui-docs/scripts/walkthrough.mjs
+++ b/packages/ui-docs/scripts/walkthrough.mjs
@ -0,0 +1,239 @@
+#!/usr/bin/env node
+/** Headless Chrome walkthrough: screenshots + console errors for every UI. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import puppeteer from 'puppeteer-core';
+
+const ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SHOTS = path.join(ROOT, 'screenshots');
+const LOG = path.join(ROOT, 'walkthrough-console.json');
+const CHROME =
+  process.env.CHROME_PATH ||
+  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome';
+
+fs.mkdirSync(SHOTS, { recursive: true });
+
+const errors = [];
+function note(pageName, type, text) {
+  errors.push({ page: pageName, type, text: String(text).slice(0, 800) });
+}
+
+const browser = await puppeteer.launch({
+  executablePath: CHROME,
+  headless: 'new',
+  args: ['--no-sandbox', '--window-size=1440,900', '--disable-dev-shm-usage'],
+  defaultViewport: { width: 1440, height: 900 },
+});
+
+async function pageFor(name) {
+  const page = await browser.newPage();
+  page.on('pageerror', (err) => note(name, 'pageerror', err.message));
+  page.on('console', (msg) => {
+    if (msg.type() === 'error') note(name, 'console', msg.text());
+  });
+  page.on('response', (res) => {
+    if (res.status() >= 500) note(name, 'http', `${res.status()} ${res.url()}`);
+  });
+  return page;
+}
+
+async function shot(page, file) {
+  await page.screenshot({ path: path.join(SHOTS, file), fullPage: true });
+}
+
+async function safeGoto(page, url, name) {
+  try {
+    await page.goto(url, { waitUntil: 'networkidle2', timeout: 20000 });
+  } catch (err) {
+    note(name, 'goto', `${url} ${err.message}`);
+    try {
+      await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 12000 });
+    } catch (err2) {
+      note(name, 'goto2', `${url} ${err2.message}`);
+    }
+  }
+}
+
+try {
+  // Operator console
+  {
+    const p = await pageFor('fleet');
+    await safeGoto(p, 'http://127.0.0.1:3850/', 'fleet');
+    await new Promise((r) => setTimeout(r, 1500));
+    await shot(p, '01-console-fleet.png');
+    const more = await p.$('.more-btn');
+    if (more) {
+      await more.click();
+      await new Promise((r) => setTimeout(r, 300));
+      await shot(p, '01b-console-fleet-overflow.png');
+      await p.keyboard.press('Escape');
+    }
+    await p.click('nav button[data-tab="trace"]');
+    await new Promise((r) => setTimeout(r, 400));
+    await shot(p, '02-console-trace.png');
+    const run = await p.$('#run');
+    if (run) {
+      await run.click();
+      await new Promise((r) => setTimeout(r, 2500));
+      await shot(p, '02b-console-trace-run.png');
+    }
+    await p.click('nav button[data-tab="docs"]');
+    await new Promise((r) => setTimeout(r, 400));
+    await shot(p, '03-console-docs.png');
+    await p.close();
+  }
+
+  // Simulator
+  {
+    const p = await pageFor('simulator');
+    await safeGoto(p, 'http://127.0.0.1:3847/', 'simulator');
+    await new Promise((r) => setTimeout(r, 800));
+    await shot(p, '04-simulator.png');
+    const run = await p.$('#run');
+    if (run) {
+      await run.click();
+      await new Promise((r) => setTimeout(r, 2500));
+      await shot(p, '04b-simulator-run.png');
+    }
+    await p.close();
+  }
+
+  // Staff UIs
+  for (const [name, url, file, extra] of [
+    ['cs', 'http://127.0.0.1:3011/', '05-cs.png', true],
+    ['sales', 'http://127.0.0.1:3012/', '06-sales.png', false],
+    ['accounting', 'http://127.0.0.1:3013/', '07-accounting.png', false],
+    ['staff', 'http://127.0.0.1:3025/', '08-access-staff.png', true],
+  ]) {
+    const p = await pageFor(name);
+    await safeGoto(p, url, name);
+    await shot(p, file.replace('.png', '-empty.png'));
+    const btn = await p.$('button');
+    if (btn) {
+      await btn.click();
+      await new Promise((r) => setTimeout(r, 800));
+    }
+    await shot(p, file);
+    if (extra) {
+      const credit = await p.$('button[onclick="credit()"]');
+      if (credit) {
+        await credit.click();
+        await new Promise((r) => setTimeout(r, 800));
+        await shot(p, file.replace('.png', '-credit.png'));
+      }
+    }
+    await p.close();
+  }
+
+  // Admin
+  {
+    const p = await pageFor('admin');
+    await safeGoto(p, 'http://127.0.0.1:3000/admin/', 'admin');
+    await shot(p, '09-admin-login.png');
+    await p.type('#login-username', 'admin');
+    await p.type('#login-password', 'admin-dev-key');
+    await p.click('#login-form button[type="submit"]');
+    await new Promise((r) => setTimeout(r, 1200));
+    await shot(p, '10-admin-rate-card.png');
+    const tabs = await p.$$('aside nav button');
+    for (const [i, label] of [
+      [1, '11-admin-tiers.png'],
+      [2, '12-admin-customers.png'],
+      [3, '13-admin-statement.png'],
+      [4, '14-admin-invoices.png'],
+      [5, '15-admin-reports.png'],
+    ]) {
+      if (tabs[i]) {
+        await tabs[i].click();
+        await new Promise((r) => setTimeout(r, 600));
+        await shot(p, label);
+      }
+    }
+    const edit = await p.$('button[onclick^="openCustomerDrawer"]');
+    if (edit) {
+      await p.click('aside nav button[data-tab="customers"]');
+      await new Promise((r) => setTimeout(r, 400));
+      const e2 = await p.$('button[onclick^="openCustomerDrawer"]');
+      if (e2) {
+        await e2.click();
+        await new Promise((r) => setTimeout(r, 400));
+        await shot(p, '12b-admin-customer-drawer.png');
+        await p.evaluate(() => window.closeCustomerDrawer?.());
+      }
+    }
+    await p.close();
+  }
+
+  // Portal
+  {
+    const p = await pageFor('portal');
+    await safeGoto(p, 'http://127.0.0.1:3000/portal/', 'portal');
+    await shot(p, '16-portal-login.png');
+    const toggle = await p.$('#auth-toggle');
+    if (toggle) {
+      await toggle.click();
+      await new Promise((r) => setTimeout(r, 200));
+    }
+    const email = `walk+${Date.now()}@example.com`;
+    const nameEl = await p.$('#auth-name');
+    if (nameEl) await nameEl.type('Walkthrough User');
+    await p.type('#auth-email', email);
+    await p.type('#auth-password', 'Walkthrough1!');
+    await p.click('#auth-submit');
+    await new Promise((r) => setTimeout(r, 1500));
+    await shot(p, '17-portal-dashboard.png');
+    const invoices = await p.$('nav button[data-tab="invoices"]');
+    if (invoices) {
+      await invoices.click();
+      await new Promise((r) => setTimeout(r, 400));
+      await shot(p, '18-portal-invoices-empty.png');
+    }
+    const stmt = await p.$('nav button[data-tab="statement"]');
+    if (stmt) {
+      await stmt.click();
+      await new Promise((r) => setTimeout(r, 400));
+      await shot(p, '19-portal-statement.png');
+    }
+    const docs = await p.$('nav button[data-tab="docs"]');
+    if (docs) {
+      await docs.click();
+      await new Promise((r) => setTimeout(r, 400));
+      await shot(p, '20-portal-api-pricing.png');
+    }
+    await p.close();
+  }
+
+  // Swagger (stock)
+  {
+    const p = await pageFor('swagger');
+    await safeGoto(p, 'http://127.0.0.1:3000/docs', 'swagger');
+    await new Promise((r) => setTimeout(r, 800));
+    await shot(p, '21-swagger-stock.png');
+    await p.close();
+  }
+
+  // Catalog (local if served, else public)
+  {
+    const p = await pageFor('catalog');
+    const local = 'http://127.0.0.1:8765/';
+    try {
+      const r = await fetch(local, { signal: AbortSignal.timeout(1500) });
+      await safeGoto(p, r.ok ? local : 'https://zapier.georgelambert.org/', 'catalog');
+    } catch {
+      await safeGoto(p, 'https://zapier.georgelambert.org/', 'catalog');
+    }
+    await new Promise((r) => setTimeout(r, 800));
+    await shot(p, '22-catalog.png');
+    await p.close();
+  }
+} finally {
+  await browser.close();
+}
+
+const real = errors.filter((e) => !/favicon|Failed to load resource.*404/.test(e.text));
+fs.writeFileSync(LOG, JSON.stringify({ capturedAt: new Date().toISOString(), errors: real, all: errors }, null, 2));
+console.log(JSON.stringify({ shots: fs.readdirSync(SHOTS).length, errors: real.length }, null, 2));
+if (real.length) {
+  for (const e of real) console.log(`ERR ${e.page} ${e.type}: ${e.text}`);
+}