Trace — Company & Product Metric Visualizer
Turn metric images and text into traceable company and product data.
Trace turns company financials into the earnings infographics you see go
viral — green for value retained, red for costs, teal for revenue collected —
covering companies from NVIDIA, Apple, and Microsoft to TSMC, LVMH, Tencent,
and SpaceX, across quarterly and annual periods.
▶ Open the live viewer — nothing to install, runs entirely in your browser.
Input a metric asset
Put a PNG or UTF-8 text file in input/pending/ and ask Codex or Claude Code
处理{文件名}. The agent records exact values in an isolated draft, runs the
automatic checks and replies with a review link; run pnpm dev to open it.
Your approval publishes locally; pushing is a separate instruction. Process:
asset workflow (graph);
workbench and concurrent Sessions: local environments.
Highlights
- A large, growing catalog — income-statement datasets for public and
private companies across many periods, plus ARR trend series.
- Traced, not approximated — every chart is hand-authored against a
published reference infographic, then pixel-diffed against it by a
headless-Chromium verifier. The source image is the standard to measure
against, never part of the render.
- Three views — Sankey (the flow diagram), Trend (revenue and metric
charts across periods), and Table (company profile plus the full income
statement).
- Comparison mode — multi-select companies or periods to see Sankeys side
by side, with canvas zoom and a per-node/link metric trend panel.
- Hover analytics — hovering any node or flow shows its share of the
related total, computed consistently across every chart.
- Exports — the current Sankey as SVG or 2× PNG; both tables as CSV.
- Bilingual and themeable — English / 简体中文 app-wide language switch,
light and dark themes, searchable and sortable company/period navigators.
- Zero-backend, works offline — a pure static site with d3 and d3-sankey
vendored locally. Double-click
index.html and it just works.
Quick start
nvm use # Node version matches CI (.nvmrc)
pnpm dev # local review workbench
# open http://127.0.0.1:8000
…or skip the server entirely and double-click index.html — all runtime
dependencies are vendored in vendor/, so the viewer runs offline.
In the viewer: pick a company and period from the left navigator, switch
views with the top Sankey / Trend / Table buttons, and multi-select
companies or periods to enter comparison mode. The toolbar toggles theme and
language and hosts the SVG/PNG/CSV exports. Sankey comparisons normalize the
painted monetary faces to one USD scale; charts with very different
magnitudes may start sub-pixel at fit and can be inspected with comparison
zoom. If any selected record lacks trustworthy geometry or money metadata,
the whole comparison shows a calibration error instead of mixing scales.
Company list sort modes
The sidebar list, Table view, CSV export and localized names read the same
fields for each sort mode. A company without a value for the mode sorts after
those with one; ties fall back to localized name, canonical name, then latest
period.
| sort mode | source fields |
|---|
| Alphabetical | name, or i18n.<language>.displayName (aliases only match financial records) |
| Recently updated | newest data/dataset-file-metadata.js entry of the company's registered datasets (latest Git author time; kept current by the hooks in commit messages, Dataset metadata) |
| Market cap | marketCap.valueUsd, else marketCap.value/currency/unit, normalized to USD with USD_FX_SNAPSHOT (src/trace-domain.js, applied by src/app/financial.js); unsupported currencies count as missing |
| Net profit | latest matching data/income-statements/<company-key>.js record's profit.net.value, converted to USD with the same snapshot |
| Founded date | first four-digit year in founded, ascending |
Add your own company
New companies and periods enter as Sources through the
asset workflow, never as hand-edited adapters. Field
formats are indexed in data/schema.md.
What keeps every chart consistent
- Columns are explicit (
col per node), so the layout follows the
financial narrative — segments → revenue → gross → operating → net —
instead of whatever d3's auto-layering produces.
- Color is semantic and automatic — node color comes from its
type;
link color is a gradient derived from its endpoints. You never pick a link
color by hand.
- Labels can't collide — side labels are de-collided in a second pass, so
even many small terminal nodes (Tax / R&D / SG&A) stay readable.
- Display values are preserved — d3-sankey overwrites node values with
flow sums; the engine keeps the author's reported figure for the label.
- Typography follows content roles — Montserrat for app chrome, Noto Sans
for chart and table text, Roboto for numeric notes and tooltips, shared by
development, verification, production, and standalone builds.
Verification and builds
Every dataset lives under a verification pipeline; the fast gates run in
seconds and are green on any fresh checkout:
pnpm check # syntax sweep, unit tests, manifest/SSOT/i18n/metadata gates
pnpm verify:app # boot-and-click smoke of the viewer in headless Chromium
Per-dataset diagnostics render the pure d3-sankey SVG in headless Chromium,
screenshot it, and compute pixel metrics against the reference image:
pnpm install --frozen-lockfile && pnpm exec playwright install chromium
pnpm verify:dataset -- <dataset-key> # data + i18n + render for one dataset
Two production artifacts, each with its own budget-enforcing verifier:
pnpm build:site && pnpm verify:site # optimized GitHub Pages projection
pnpm build:standalone && pnpm verify:standalone # single self-contained HTML file
The Pages build boots from a light catalog and loads details on demand; see
the runtime data contract. The standalone
build inlines everything into the Git-ignored
output/trace-company-product-metric-visualizer.html. Local output cleanup is
described in artifact retention.
CI (.github/workflows/ci.yml) always runs
pnpm check, plans browser/render gates from the Git diff, and deploys the
verified Pages artifact. docs/ci-verification.zh-CN.md
documents every check.
Contributing a dataset (the fidelity loop)
New datasets follow the workflow above: claim a Source from input/pending/,
author the data SSOTs and dataset adapter, localize fixed-layout text, pass the
automated render gates once per locale, then your review. The rendered output
under comparison is always the SVG produced by SankeyEngine.render() — never
the source PNG or crops of it. Source directories: input/README.md.
The owning documents:
Commit messages follow docs/commit-messages.md.
How it's built
No framework, no bundler at development time: a static shell, ordered classic
scripts, and a hand-rolled d3-sankey engine.
| file | role |
|---|
index.html | static viewer shell and ordered script registration |
src/app.css | viewer layout, controls, sidebar, and responsive styles |
src/app/ | viewer app modules (classic scripts, ordered in index.html, shared top-level scope) |
src/app/dom.js · util.js · dataset-loader.js · hotkeys.js · i18n-runtime.js | DOM refs · generic helpers/formatters · on-demand + company-scope preload Adapter loading, intent prefetch, raster-annotation warm, and retry · modifier-combo shortcut registry · localization caches over SANKEY_I18N |
src/app/state.js · selectors.js · financial.js · chart-theme.js | prefs + mode rules + UI state/scope · display/search derivations · USD/FX totals + company sort values · shared Chart.js theme plus lazy runtime loading |
src/app/shell.js · controls.js | theme/language/sidebar/toolbar chrome · metric/view switching + renderAll() |
src/app/company-panel.js · period-panel.js | company list, sort menu, multi-select · period tree, timeline, multi-select |
src/app/tables.js · trend.js · sankey.js | virtualized tables · revenue trend charts · sankey single/comparison orchestration, fail-closed scale presentation + draw() |
src/app/comparison-zoom.js · comparison-metric-trend.js | comparison canvas zoom gestures with a connected SVG-free browser-geometry resolver · node/link metric trend panel |
src/app/metric-library.js | General observations, source inspection, search and exact JSON export |
src/app/exports.js · main.js | SVG/PNG/CSV downloads · global wiring + boot (loads last) |
src/comparison-scale.js | Deep Comparison Visual Scale Module: validates renderer anchor geometry against Metric SSOT revenue lineage + money dimensions and produces one group-atomic USD normalization plan |
|
Notes
- Figures match their source infographics and are illustrative; verify
against audited filings before relying on any number.
- Icons are Lucide (MIT). Company logos and wordmarks
are trademarks of their respective owners, reproduced only to match the
reference infographics — swap
meta.logoSvg for your own asset.
- d3 (ISC) and d3-sankey (ISC) are the only vendored chart libraries.
