Skip to content

BRIEF.md

Latest commit

 

History

History
154 lines (124 loc) · 7.04 KB

BRIEF.md

File metadata and controls

154 lines (124 loc) · 7.04 KB
Raw

Build: USB Chaos Map & Classification Workflow

Build a single self-contained HTML file that turns observable USB cable tester data into a defensible cable classification, with a live visualization, live standards / power / alt-mode matrices, and a written inference log. Vanilla JS, no backend, no external libraries, no build step.

This is a benchmarking brief. I have a working reference implementation (screenshots attached: usb-chaos-map-*.png). Your job: match or beat it.

1. Tester inputs (left-hand control panel)

Every control below must be wired so that changing it re-runs classification and repaints every tab live. No "click to recalculate" buttons.

Control Values
Host-side connector Type-A, Type-B, Micro-B, Type-C
Device-side connector Type-A, Type-B, Micro-B, Lightning, Type-C
E-Marker detected? Yes / No / Unknown
E-Marker · advertised current 3 A / 5 A / 5 A EPR / n/a
E-Marker · data speed grade USB 2.0 / Gen 1 (5 G) / Gen 2 (10 G) / Gen 2x2 (20 G) / USB4 40 G / USB4 80 G / n/a
End-to-end DC resistance grade < 50 mΩ (S) / < 150 mΩ (A) / < 300 mΩ (B) / > 300 mΩ (F)
Negotiated trigger None / BC 1.2 / PD SPR / PD EPR / PPS / QC 3/4/5
Observed link speed 1.5 M / 12 M / 480 M / 5 G / 10 G / 20 G / 40 G / 80 G
Markings / certification USB-IF / Thunderbolt / PD / None (multi-select)
Cable length meters, numeric input
Active / Optical Passive / Active (re-timer) / Optical (AOC)

Quick-apply presets in the top toolbar:

  • Reset to default
  • "USB4 v2 · 240 W" (everything maxed, certified)
  • "Dumb C-to-C" (unmarked, passive, 1 m)
  • "Export JSON" — copy the full verdict to clipboard

2. Classification output (right panel + Verdict tab)

For every input combination, compute and display:

  • Cable class name — e.g. Baseline C-to-C, C-to-C · USB4 v2 · 80 Gbps, USB 3.2 Gen 2 A↔C, Apple Lightning ↔ Type-C.
  • Max data rate (numeric + label).
  • Max power (W) and band (baseline / spr / epr / apple-2c / legacy).
  • Supported alt modes (possibly zero).
  • Observable set — everything the tester directly reports.
  • Inferred-supported set — things the cable can do given observables.
  • Inferred-unsupported set — things it can't do but the physics allows.
  • Excluded set — logically impossible given the connectors / markings.
  • Inference log — colored entries (GOOD / WARN / BAD / INF) with a short natural-language reason for each rule that fired.

3. Tabs (center panel) — all driven by the same state

  1. Ecosystem Map — radial SVG. Four concentric axes: data ceiling, power ceiling, alt-mode count, certification coverage. Each axis has an outer ring (spec maximum) and an inner filled disk scaled to the inferred ceiling. Spoke labels around the core show the observables (host, device, E-marker state, resistance, trigger, observed link speed, active/passive, length).
  2. Standards Matrix — one row per USB version (USB 1.0, 1.1, 2.0, 3.0 / 3.1 Gen 1 / 3.2 Gen 1, 3.1 Gen 2 / 3.2 Gen 2, 3.2 Gen 2x2, USB4 20, USB4 40, USB4 v2.0 80). Columns: marketing name, signal rate, encoding, year, reachable-by-this-cable ✔/✘.
  3. Power Profile — bar chart from 2.5 W → 240 W with one row per PDO (USB 2.0 default, USB 3.0 default, BC 1.2, USB-C default 15 W, 9 V/3 A, 15 V/3 A, 20 V/3 A, PD SPR 20 V/5 A, PD EPR 28/36/48 V @ 5 A). Each row shows ✔ if within the cable ceiling, ✘ otherwise. Below: contextual notes that change when PPS / QC / EPR is involved.
  4. Alt Modes — table: DP 1.4a, DP 2.1, TB3, TB4, TB5, HDMI (deprecated), MHL (deprecated), VirtualLink (dead), Audio Accessory, Debug. Columns: requires, max bandwidth, supported by this cable ✔/✘, status.
  5. Topology & Roles — host-hub-device tree description, host controller chain (UHCI/OHCI → EHCI → xHCI), OTG / DRD concepts, data role (UFP/DFP/DRD), power role (source/sink/DRP), transfer-type chips (control/bulk/interrupt/iso).
  6. Device Classes — 15+ USB-IF class codes (0x01 Audio, 0x02 CDC, 0x03 HID, 0x06 PTP, 0x07 Printer, 0x08 BOT/UAS, 0x09 Hub, 0x0B CCID, 0x0E UVC, 0x0F Healthcare, 0x11 Billboard, 0xDC Diag, 0xE0 Wireless, 0xFE App-Specific, 0xFF Vendor) with minimum bandwidth column and a reachable-on-this-cable ✔/✘.
  7. Verdict & Log — the full classification report plus the colored inference log.

4. Classification rules the engine must get right

These are the edge cases that separate real implementations from wireframes:

  • Unmarked C-to-C (emarker = No) → USB 2.0 only and 15 W only, regardless of what other cables in the same plug shape can do.
  • A-to-C asymmetric → max 15 W and no Alt Modes. Cables advertising

    3 A on Rp-to-5 V are the out-of-spec ones that famously damaged hosts (Benson Leung, 2015). Surface a WARN.

  • Lightning on either end → USB 2.0 data ceiling, Apple-2C charging (typically ≤ 27 W), no PD negotiation, no USB 3.x, no Alt Modes.
  • Micro-B → USB 2.0 unless the 10-pin SS-Micro-B variant is declared.
  • USB4 40 G passive cable > 0.8 m → out of spec; link drops to 3.2 Gen 2.
  • USB4 v2 · 80 Gbps passive cable → never trains; requires active.
  • PPS @ 5 A requires an E-Marker declaring 5 A. Without one, WARN that PPS is valid only up to 3 A.
  • QC 3/4/5 is proprietary (D+/D- handshake) and cannot coexist with PD BMC on the CC line. Surface a WARN.
  • Observed link speed > inferred ceiling → BAD. Either the E-Marker is lying or the classification is wrong.
  • EPR trigger but cable can't deliver → BAD, with explanation.

5. Visual style

  • Dark cyber/neon. Deep navy/black background, neon accents (cyan #2bd8ff, magenta #ff56e0, green #4dffb0, amber #ffb547, violet #9f8cff, red #ff5f7a).
  • Monospace (JetBrains Mono / SF Mono / ui-monospace) for headers, chips, labels, log entries. Sans-serif for body/subtitle.
  • Generous glow on active elements (SVG drop-shadow + box-shadow).
  • All panels are cards with 1 px dim-blue borders, subtle backdrop-filter blur.

6. Non-negotiables

  • It has to actually render. If the controls are there but the canvas is blank, you have failed. Gemini failed at this.
  • Every control drives every tab, live. No stale panes.
  • Self-contained. One .html file, opens with a double-click, works offline, no CDN, no npm install.
  • Inference must be inspectable. Every WARN / BAD must come with a one-sentence reason, not just a color change.
  • Don't pretend to know what you don't. Where the observables are ambiguous, mark things inferred (cyan) rather than observable (green), and list exclusions explicitly.

7. Nice-to-haves (not required)

  • URL hash reflects state so a configuration can be shared.
  • An "Ambiguity" tab listing inputs that would resolve remaining uncertainty.
  • Keyboard shortcuts for tab switching.
  • Print stylesheet.

8. Output

One file: usb-chaos-map.html. That's the deliverable. No repo, no dependencies, no build.