frames

Imported from zentryHQ/zframes (packages/frames/AGENTS.md). Install upstream with npx skills add zentryHQ/zframes --skill frames. Copyright stays with the author.

@zframes/frames

The frame components. Each frame = a Zod meta (in schemas/<family>.ts) + a component (its own .tsx) + an entry in allFrames (index.ts). Schemas are read by generating agents; components render data through shared primitives.

Cardinal rule: don't hand-roll — route through the shared primitive

These frames are meant to read as one system, not a pile of one-offs. Every recurring concern — number formatting, gain/loss color, type scale, loading/empty, scroll, list rows — already has exactly one home. Before you write a compact-$ formatter, a #hex, a text-[…], or a custom spinner, import the primitive instead. New divergence is the regression this package was harmonized to remove.

Read the JSDoc on the primitive before using it — each says exactly when to reach for it vs. a sibling.

./metals-shared's windowing/thinning/rebasing helpers (sliceYears, downsample, toChartData, timeframeFor, rebaseToPct, pctChange) are generic SeriesPoint[] maths that merely live in that module for historical reasons — the FRED/Zillow/FHFA frames import them directly rather than re-deriving them. Its metals-specific helpers (fix days, troy ounces, formatFixPrice) are not for general use.

Deliberate exceptions — leave these alone

These intentionally don't go through the generic primitives; don't "harmonize" them away: fear-greed mood ramp, treemap palette, BTC orange, holiday amber (market-hours), and the clock/countdown clamp() type (their own container-query scale, not metric-*).

Adding a frame

Per-frame metadata lives in four lists that must stay in lockstep — registry-parity.test.ts fails the build if they drift, and a missing loader/meta makes the frame vanish at runtime as an "Unknown frame" card:

1. schemas/<family>.ts — add the meta via defineFrameMeta, in the file for its category (one per FRAME_CATEGORIES family, 14 of them; crypto.ts is the largest, shared.ts holds the common field helpers). The thin schemas.ts barrel re-exports them all, so nothing else needs touching. Set label (required — the human display name; it's the card's default title when an instance sets no title, plus the editor-palette / catalogue name. Use Title Case with real acronyms, e.g. "OI by Strike", "BTC Fees" — not the raw frame-id). Set category (one of FRAME_CATEGORIES' keys in @zframes/core — required; groups the editor palette and the AI catalogue) and give every field a .describe() (read by catalogueForAI). React-free — no component imports. Then add the meta to allFrameMetas (every renderable frame; the runtime registry's source), and — only if the generating agent should be able to pick it — also to frameMetas (the curated AI catalogue; games/journal/tools/layout frames are deliberately omitted). Set layout — all four bounds. { w, h, minW, minH, maxW?, maxH? }: the span the frame is added at, and the floor and ceiling the editor's resize handles enforce. Guess it to start, then measure it:

   pnpm --filter @zframes/storybook build
   PROBE_FRAMES=<your-frame> pnpm frames:size:probe   # 96 spans, clipping/legibility/ink
   pnpm frames:meta
   SHEET_FRAMES=<your-frame> pnpm frames:size:sheet   # the envelope's corners, as a PNG to look at

   Omit maxW/maxH when the frame genuinely scales — that means unbounded, and is not the same as 12. tests/frame-layout-bounds.test.ts fails the build if a frame ships without a floor or with an incoherent envelope.

   Then check both Storybook stories: AllSizes must look right at every span, and OutOfBounds — one step under each floor, one step over each ceiling — must fail gracefully. A cell there that looks perfectly fine means the bound is too strict; a cell that slices content in half means the frame, not the bound, still needs work.

2. New <frame>.tsx — import the meta, build the component using the primitives above, export const xFrame = defineFrame({ ...xMeta, component: X }).

3. index.ts — add xFrame to allFrames (for hosts that register eagerly). And lazy.ts — add "<name>": { load: () => import("./<name>").then((m) => m.xFrame) } (set titleIcon: true if the module exports one). This is the per-frame chunk the runtime lazy-loads; a missing entry = the frame silently won't render.

4. pnpm typecheck && pnpm lint && pnpm test from the repo root before committing — the parity test confirms allFrameMetas ≡ lazy.ts loaders.

Footguns

• An absent figure is greyed, and a non-finite one never prints. Every formatter in ./format returns ABSENT (one em dash) for NaN/Infinity, and changeColor returns currentColor rather than loss-red — NaN >= 0 is false, so the plain comparison painted every failed computation in a confident red. The placeholder itself must not sit in the figure's ink: pass absent to the shared head/stat/row rather than writing a bare "—", because a dash set in metric-xl text-strong reads as a value. Ink is split OUT of the size class in both card-header.tsx and stat.tsx for this reason: two ink utilities on one element let the stylesheet's order decide the winner, not the caller.
• A matrix cell's figure is gated on width AND height. Route it through cellLabelFits (./ui); tests/heatmap-label-fit.test.ts fails the build if a frame importing HeatmapChart doesn't. A heatmap packs rows far tighter than columns — 20 years of monthly returns leaves ~11px a row — so a width-only guard prints every figure clipped top and bottom, and nothing errors: the renderer has no idea what the cell was meant to say. Axis labels are the chart's job and thin themselves on both axes (packages/charts/src/heatmap-chart); a frame-owned strip aligned under the grid (e.g. metal-seasonality's per-month averages) must measure its own column width and shorten or hide its figures — a row of +… is noise, not data.
• A wrong layout bound fails nothing. The CSS-grid renderer ignores layout entirely — it is the editor's resize envelope and the generating agent's sizing hint. So a floor set too low renders happily with the chart squeezed under its axis, and a missing ceiling renders one number in an acre of empty card. Both read as design mistakes, never as errors, which is why the bounds are measured (.github/scripts/frame-size-probe.ts) rather than eyeballed.
• A shared primitive that renders money resolves the currency ITSELF. Never give one an optional formatter prop defaulting to a USD helper: MoverRow did, two of its three consumers passed nothing, and those cards quoted dollars on a baht board where the $ lived in the primitive's default — invisible to the source grep built to catch exactly that. tests/currency-coverage.test.ts pins it.
• A frame whose figures aren't convertible market money declares usdOnly: true on its meta — US-macro series, SEC figures as filed, user-typed numbers. That flag is the single source of truth for the carve-out: tests/currency-coverage.test.ts derives its exemptions from it (a frame using formatPrice without it fails the build, and a flag on a frame that converts fails too), the editor greys out the card's Display-currency control and says why, and catalogueForAI surfaces it so the generating agent doesn't set a per-card currency that would be inert.
• Money on market data goes through useMoney(), not formatPrice. A card can be denominated in any of the 146 CURRENCY_CODES (dashboard currency.code, or a per-card override), and tests/currency-coverage.test.ts fails the build if a frame touches formatPrice/formatCompactUsd without declaring usdOnly (above). The plain $ helpers are only for US-macro series, SEC figures as reported, and user-typed numbers. The hook is only callable from a component: for a nested React component (treemap Leaf, heatmap Cell) call useMoney() inside it — before any early return; for a D3 render callback that is NOT a component (formatTitle, formatValue), call the hook in the frame and let the closure capture money (see market-bubbles), or pass it down as a prop (see order-book-depth).
• A time-series chart renders through TimeSeriesChart AND sets annotatable: true on its meta. A card's events (its own dated markers) reach the chart only through that wrapper, and the meta flag is what makes the editor offer the Events panel + tells the AI catalogue the frame accepts markers. tests/chart-events-coverage.test.ts fails the build if either drifts — a chart that quietly opted out looks identical to a card nobody annotated, so nobody would catch it in review.
• A frame that can source from two exchanges needs source plumbed all the way through. Add source: sourceField() to its schema AND pass config.source into the hook — capability routing is first-match, so without it the frame silently keeps reading the default provider. Remember symbols are source-native (xyz:TSLA exists only on Hyperliquid; Bitkub lists bare tickers) and quote-stream is Hyperliquid-only.
• src/schemas/ is the single source of truth for frame metadata and must stay React-free — the CLI, catalogue export, and the /zframes skill import it without charts/liveline/CSS.
• Frame chrome (card, title, hover, source link) is the renderer's job (@zframes/core FrameContent + injected .zf-* CSS). A frame styles only its interior.
• The package also re-exports AssetLogo/assetLogoUrl/tickerOf (keyless CDN logos + HIP-3 prefix stripping) for hosts.
• Keyless only, stocks-first — see the repo root ../../AGENTS.md for project-wide scope and commands.

Where the size bounds come from

The envelope is measured, not guessed, and it is surfaced in three places a wrong value shows up: catalogueForAI (so the generating agent sizes cards correctly), each explorer catalogue card, and zframes lint (which reports a board card sitting outside it). tests/frame-layout-bounds.test.ts pins 1 ≤ min ≤ default ≤ max plus "no shipped board sits outside its frames' bounds".

The numbers come from .github/scripts/frame-size-probe.ts, which mounts each frame once and resizes it through all 96 spans (rewriting --zf-col-span/--zf-row-span), recording clipped content, labels hitting their ellipsis, chart boxes below legibility, visible list rows, and the "ink" fraction of the card that actually paints. derive-frame-bounds.ts turns that matrix into bounds and frame-size-sheet.ts renders the envelope's corners as a contact sheet to check by eye.

Two things you do NOT have to touch

• No Storybook edit needed. A Default/AllVariants/AllSizes/OutOfBounds/States/Live story set auto-generates per frame (see apps/storybook/AGENTS.md).
• No hand-kept frame list anywhere. For the live, grouped list of which family holds which frames, read it from the source: the editor palette or catalogueForAI (@zframes/core), both driven off FRAME_CATEGORIES + the registry.