Flame Graph

npx shadcn@latest add https://ui.zyeon.ai/r/flame-graph.json

Build a React + TypeScript + Tailwind "FlameGraph" card in plain positioned DOM
(no charting library — every frame has to be a real focusable element, and a
canvas cannot be one) with zod for the contract, lucide-react for the state
icons, and the shadcn Input primitive for the search field.

Contract
- One zod schema is the source of truth, and the props are z.infer of it plus the
  render knobs — never a parallel hand-written interface:
    { status: "loading" | "empty" | "error" | "ready";
      title: string; rootLabel?: string; unit?: string;
      frames: FlameGraphFrame[] }
  FlameGraphFrame = { id, label, total, self?, category?, children? }. It is
  recursive, so the interface is written by hand and the schema is a z.lazy()
  annotated z.ZodType<FlameGraphFrame> — TypeScript cannot infer a type defined
  in terms of itself.
- The payload is NESTED, not flat with a parent pointer, because the order of
  `children` is load-bearing: the horizontal order of a row is the call order.
  Never re-sort children. Sorting them is exactly what turns this chart into an
  area-by-value treemap.
- `id` is unique among SIBLINGS only — a frame is addressed by the path of ids
  that reaches it, which is also its React key and its search key.
- `total` is inclusive time (this frame plus everything it called) and is the
  only quantity the geometry uses. `self` is optional and a CROSS-CHECK ONLY:
  the drawn self time is always total minus the sum of the children, because
  that gap is the only thing the picture can mean.
- `unit` omitted means the numbers are milliseconds and print on a µs / ms / s
  ladder; supply one ("samples", "KB", "allocations") and they print compactly
  with the noun appended. Values are plain numbers, never Date objects: the
  component never reads a clock, so the server and the browser render
  byte-identical markup.
- Render knobs on top of the contract: description; maxDepth (12, clamped 2–40);
  rowHeight (22 px, clamped 16–44); orientation "flame" | "icicle"; pruneBelow
  (0.002, clamped 0–0.05); locale ("en-US"); formatValue?; query? /
  defaultQuery / onQueryChange? (optional-controlled); onZoom?; onSelect?;
  onRetry?; className. forwardRef to the root div, rest props spread.

Behavior
- Four first-class branches on `status`, not an afterthought `&&`. loading → a
  pyramid of pulsing bars on the same row grid as the real graph, aria-hidden,
  plus one sr-only role=status line; empty → icon and a sentence; error →
  message plus a "Try again" button ONLY when `onRetry` is passed; ready → the
  graph. A `status: "ready"` that yields nothing paintable renders its own
  one-line notice rather than a blank stage.
- Normalisation, before any width exists. Build one tree under a SYNTHETIC base
  bar whose total is the sum of the roots — it is the 100% reference and the
  thing you press to leave a zoom, so it is synthesised even when the payload
  has exactly one root. Then, per frame:
    * total not finite, zero or negative → dropped and counted (a zero-width bar
      is not a smaller truth, it is an invisible one);
    * self = max(0, total − Σ children.total);
    * Σ children.total > total → the trace is inconsistent: the children are
      normalised onto the parent's span at layout time so nothing ever paints
      outside its caller, and the frame is counted;
    * a supplied `self` that disagrees with the geometric self by more than 1%
      of the frame → counted.
  Every count lands in the footnote. Silently shrinking a profile is how a flame
  graph starts disagreeing with the trace it came from.
- Structural refusal. Two siblings sharing an id, or a frame linked inside
  itself (possible when the tree is assembled in memory rather than parsed),
  take the error branch with a named message. The first would make a branch
  unreachable, the second hangs every walk — both are silent from the outside.
- Layout maths, all in fractions of the current view, so nothing is ever
  measured:
    * the zoom target is row 0 at width 1;
    * a child's width = parent's drawn width × child.total ÷ max(parent.total,
      Σ children.total). Widths therefore compose exactly the way the times do:
      a row can never be wider than the frame it stands on;
    * the uncovered remainder at the right of a bar IS that frame's self time —
      it must stay unclaimed;
    * when the children overflow, the last one is snapped to the parent's right
      edge so accumulating floats cannot open a seam;
    * share of the profile = node.total ÷ base bar total, computed against the
      whole profile so the number survives a zoom.
- Width floor. A frame narrower than `pruneBelow` of the current view is
  sub-pixel; it and its subtree are not drawn and are counted in the footnote.
  Nothing is floored upward to rescue it — width taken to make one bar visible
  comes out of its siblings, and a row that no longer sums to its parent is not
  a profile any more. Zooming into its caller re-normalises the fractions and it
  reappears; say so in the footnote so the reader knows the way in.
- Row budget. Rows drawn = min(maxDepth, levels in the zoom target). Any drawn
  frame holding callees that are not on screen — past the row budget, or lost to
  the width floor, even one of them — gets a 2 px marked edge on its outer side
  and still opens on click. That edge is the only thing telling a reader which
  bar to zoom into, so it is set for a single missing callee, not just for a
  whole missing level.
- Zoom. Activating any frame zooms to it: it becomes the full-width row 0 and
  the ancestors move into the breadcrumb. Activating the base bar gives up one
  level, since it is already the whole view. The zoom path is resolved against
  the current tree on every render, so swapping `frames` can never strand the
  view inside a stack that no longer exists — the chain stops at the last id
  that still resolves.
- Search runs over the WHOLE profile, not the current view, so a hit three zooms
  away is still counted. Matched frames keep full colour and take an outline;
  everything else drops to 30% opacity. The matched share sums only the
  TOP-MOST hits: a match inside a match is already inside that total, and adding
  it again is how a "matched %" quietly passes 100. The readout names the count,
  the share, and how many matches are outside the current zoom.
- Keyboard map. The graph is ONE tab stop (roving tabindex); the search field
  and the breadcrumb buttons are their own.
    ← / →      previous / next bar in the same row, wrapping at the ends
    ↑ / ↓      change level, following the picture: in "flame" up is toward the
               callee, in "icicle" up is toward the caller
    Home/End   first / last bar of the row
    Enter/Sp   zoom into the bar — handled by the browser, because these are real
               buttons; do NOT also handle them in keydown or every press zooms
               twice
    Backspace  out one level
    Escape     reset the zoom; when nothing is zoomed, let it bubble so a
               surrounding dialog or drawer can still close on it
  Escape inside the search field clears the field and stops there.
  preventDefault fires only for keys that were actually handled, so arrowing
  never eats the page's own scrolling on keys this graph ignores.
- Pointer. Hover and focus feed one readout and one tint; the tint also lights
  the active bar's callers, so the call path is readable at a glance. A pointer
  leaving restores the tint to the focused bar only when focus is still inside,
  otherwise it clears — `focusedKey` outlives a blur to keep the tab stop where
  the reader left it, and restoring it unguarded would light a bar that is
  neither hovered nor focused. Double clicks are dropped with `event.detail > 1`:
  the second zoom would land on whatever the re-render moved under the pointer.
- Focus is never dropped. Every zoom unmounts the bar (or the breadcrumb button)
  that caused it, so focus is handed to the new base bar from an effect keyed on
  a zoom COUNTER — not on the layout, so re-laying out for any other reason never
  steals focus. Clearing the search unmounts the clear button, so the input is
  read and focused inside that same handler while it is still mounted. Nothing is
  ever left on <body>, and no control is ever natively disabled.
- Cleanup: there is nothing to cancel, by design. Widths are percentages of the
  container, so the graph reflows on resize without a ResizeObserver; there are
  no timers, no rAF, no window listeners. The only effect is the focus handoff.

Rendering & styling
- Semantic tokens only: bg-card / text-card-foreground for the panel, bg-muted
  for the stage, border, text-muted-foreground, text-destructive, ring, and
  var(--chart-1..5) for the bars. No hex, no rgb(), no oklch() literals.
- A bar is its token mixed INTO the surface —
  color-mix(in oklab, var(--chart-N) X%, var(--card)) with X = 32 at rest, 48 on
  the active call path, 66 for the active bar. The raw token is tuned to sit just
  over 3:1 against the card, which is a fill contrast, not a text one, and every
  bar here carries text; mixing toward the surface keeps var(--foreground)
  readable on all five hues in both themes.
- The colour slot is FNV-1a over category ?? label, so the same function is the
  same colour everywhere it appears down a stack and a whole category can be
  recoloured with one field. Colour never encodes magnitude — width does, and a
  hash collision only means two names share a hue, which is what the original
  flamegraph.pl does on purpose.
- Matched frames take an inline OUTLINE, not a ring: the focus ring is a
  box-shadow, and an inline box-shadow would paint over it. The focus ring is
  inset, so a bar flush against the clipped edge of the stage is not half painted
  away, and it raises z-index so a neighbour cannot overprint it.
- Labels are dropped below 1.2% of the view (a bar that narrow cannot hold one
  glyph) and the browser truncates the rest — no text is measured, so there is
  no measurement to invalidate.
- Motion is opacity only, with motion-reduce:transition-none, and the skeleton
  pulse carries motion-reduce:animate-none. With motion off the graph is fully
  functional: nothing is revealed by an animation.
- Accessibility: the stage is role=group with the keyboard map in its aria-label
  and an sr-only summary as aria-describedby; each bar is a real button whose
  aria-label states name, total, self, share of the profile, depth, how many
  frames it contains and what activating it does; the visible readout is
  aria-hidden because the focused bar already says every word of it; the search
  result count sits in a role=status paragraph that is ALWAYS mounted, since a
  live region has to exist before its text changes; and an sr-only table lists
  the 20 heaviest frames by self time. Put sr-only on a DIV wrapping that table,
  never on the table itself — CSS width is only a lower bound for a table box, so
  width:1px does not hold one back and a narrow viewport picks up hundreds of px
  of horizontal scroll.

Customization levers
- Density: rowHeight 16–44 px and maxDepth 2–40 are the two dials that decide how
  much profile fits in a card; 18/8 is a sidebar, 26/20 is a full-page profiler.
- Orientation: "flame" (base at the bottom, classic) vs "icicle" (base at the
  top, DevTools-style). The arrow keys follow whichever you pick.
- Width floor: raise pruneBelow to 0.005 for a calmer picture on huge profiles,
  drop it to 0 to draw every frame however thin — the footnote text adapts.
- Palette: swap the five entries of FRAME_TOKENS, or change the 32 / 48 / 66 mix
  triple for a flatter or punchier card. Give frames a `category` to colour by
  layer (app / node_modules / gc) instead of by name.
- Ordering: children are drawn in call order by design. If your profiler merges
  samples and the order is meaningless, sort them by label in one place —
  buildFlameTree's child loop — and say so in the caption, because a reader will
  otherwise read the order as time.
- Search: matching is one substring test in the `matches` memo; swap it for a
  regex, a fuzzy match or a category filter there and nothing else changes. Pass
  `query` to drive it from a page-level search box and hide the built-in field.
- Numbers: formatValue for bytes, cycles or a currency; `unit` for the noun;
  `locale` for the grouping.
- Disclosure: TOP_FRAME_ROWS sizes the screen-reader table, and lifting that
  table out of sr-only turns it into a visible "heaviest by self time" list — the
  most requested companion to a flame graph.
- Wiring: onZoom (path of ids), onSelect (the built node) and onRetry are the
  consumer's business; the component never navigates or refetches on its own.