# Engram — full API reference

> A Destiny 2 (Bungie FUI) React component library, distributed as a shadcn registry and built for AI-agent consumption.

Engram renders real Destiny data — item tiles, socket/perk grids, nameplates, loadouts, triumphs, scoreboards — in the in-game visual language. Components are framework-React; the data mapping (`@engram/core`) and color tokens (`@engram/tokens`) are framework-neutral. You own the code: `shadcn add` copies a component's source into your repo to read and edit directly.

## Setup

Add the `@engram` namespace to your `components.json`, then install components by name:

```json
"registries": {
  "@engram": "https://engram.starside.ai/r/{name}.json"
}
```

```bash
npx shadcn@latest add @engram/item-tile
```

Components depend on the `tokens` theme (the `--engram-*` CSS variables) and on `@engram/core` (npm). Both are pulled in automatically. An agent can also browse/search/install via the shadcn MCP server pointed at this registry.

## Extension model

Every component is extensible four ways, in increasing escape-hatch order: (1) **edit the copied source** directly; (2) **`asChild`** (Radix Slot) to swap the rendered element; (3) the typed **`annotations`** prop for curated data (roll verdict, tags, per-plug tier/label/recommended) which Engram renders with default styles; (4) **slot / render-prop** props for arbitrary content. The typed annotations layer is implemented on top of the same slots — one render path, two ergonomics.

## Components

### Core & libs

#### cn() helper (`@engram/cn`)

Tailwind-aware class-name merge (clsx + tailwind-merge).

- Install: `npx shadcn@latest add @engram/cn`
- Registry item: /r/cn.json
- npm dependencies: clsx, tailwind-merge

#### Engram core (`@engram/core`)

Framework-neutral Bungie API → component-props mapping, image-ref resolver, enums, and types. Pure TypeScript, usable from any framework.

- Install: `npx shadcn@latest add @engram/core`
- Registry item: /r/core.json

#### Token utilities (`@engram/token-utils`)

Helpers that turn an @engram/core enum value (rarity, element, ammo, class) into its --engram-* CSS-variable reference.

- Install: `npx shadcn@latest add @engram/token-utils`
- Registry item: /r/token-utils.json
- npm dependencies: @engram/core

#### usePanelTransition (`@engram/use-panel-transition`)

Hook coordinating a Destiny-style directional panel swap (fade + slide out, commit, fade + slide in) for routed views or local tab state.

- Install: `npx shadcn@latest add @engram/use-panel-transition`
- Registry item: /r/use-panel-transition.json

### Theme

#### Engram tokens (`@engram/tokens`)

Destiny FUI palette + rarity/element/class colors as CSS variables (--engram-*), with a Tailwind v4 theme layer.

- Install: `npx shadcn@latest add @engram/tokens`
- Registry item: /r/tokens.json

### Primitives

#### Bungie image (`@engram/bungie-image`)

Renders a Bungie image, resolving an ImageRef to a URL via @engram/core's configurable image base.

- Install: `npx shadcn@latest add @engram/bungie-image`
- Registry item: /r/bungie-image.json
- npm dependencies: @engram/core
- Registry dependencies: @engram/cn, @engram/tokens

Props (`BungieImage`):

- `src` (`ImageRef | string`, required) — An Engram ImageRef (relative path + base) or an already-resolved URL.
- `alt` (`string`) — Alt text; falls back to the ImageRef's alt, then empty.
- `imageBase` (`string`) — Override the configured image base for this image only.

#### Button (`@engram/button`)

A Destiny FUI button: flat, square, tracked-uppercase, with an offset outline ring that fades in on hover and a rhythmic fill pulse.

- Install: `npx shadcn@latest add @engram/button`
- Registry item: /r/button.json
- npm dependencies: @radix-ui/react-slot, class-variance-authority
- Registry dependencies: @engram/cn, @engram/tokens

Props (`Button`):

- `asChild` (`boolean`, default `false`) — Render as the child element (Radix Slot), e.g. to wrap a Next.js Link.

#### Chip (`@engram/chip`)

A small tracked-uppercase label/badge — the general badge/pill primitive. `tone` (or a `color` override) carries the meaning; `variant` picks the treatment: tinted (soft), bordered (outline), or filled (solid).

- Install: `npx shadcn@latest add @engram/chip`
- Registry item: /r/chip.json
- Registry dependencies: @engram/cn, @engram/tokens

Props (`Chip`):

- `tone` (`ChipTone`, default `"neutral"`) — Semantic tone — carries the meaning color.
- `variant` (`ChipVariant`, default `"soft"`) — soft = tinted fill (default) · outline = bordered · solid = filled.
- `size` (`ChipSize`, default `"md"`)
- `color` (`string`) — Override the tone with any CSS color (e.g. an element/rarity token var).

#### Countdown (`@engram/countdown`)

A live countdown to a timestamp (vendor/weekly/event resets).

- Install: `npx shadcn@latest add @engram/countdown`
- Registry item: /r/countdown.json
- Registry dependencies: @engram/cn, @engram/tokens

Props (`Countdown`):

- `until` (`Date | number`, required) — Target time — a Date or epoch milliseconds.
- `format` (`(msRemaining: number) => string`, default `formatDuration`) — Format remaining ms → string. Default: compact "2d 4h" / "12m 30s".
- `expiredLabel` (`string`, default `"—"`) — Shown once the target has passed. Default "—".
- `onElapsed` (`() => void`) — Fired once when the timer crosses zero.
- `className` (`string`)

#### Key hint (`@engram/key-hint`)

A keybind hint — the bordered key chip Destiny shows in nav bars and footers (`[A] Clan`, `[Esc] Dismiss`).

- Install: `npx shadcn@latest add @engram/key-hint`
- Registry item: /r/key-hint.json
- Registry dependencies: @engram/cn, @engram/tokens

Props (`KeyHint`):

- `children` (`ReactNode`, required) — The key glyph (e.g. "A", "Esc", "F1").
- `label` (`ReactNode`) — Optional action label shown after the key (e.g. "Dismiss").

#### Progress ring (`@engram/progress-ring`)

A radial completion ring — the round counterpart to a progress bar, for node completion, character level, and compact stat readouts.

- Install: `npx shadcn@latest add @engram/progress-ring`
- Registry item: /r/progress-ring.json
- Registry dependencies: @engram/cn, @engram/tokens

Props (`ProgressRing`):

- `value` (`number`, required)
- `max` (`number`, default `100`)
- `size` (`number`, default `36`) — Diameter in px.
- `thickness` (`number`, default `4`) — Ring stroke width in px.
- `color` (`string`, default `"var(--engram-accent)"`) — Fill color (any CSS color, e.g. a token var).
- `trackColor` (`string`, default `"var(--engram-raised-2)"`) — Track (unfilled) color.
- `children` (`ReactNode`) — Center content (e.g. a count or completion fraction).
- `label` (`string`) — Accessible label.
- `className` (`string`)

#### Segmented bar (`@engram/segmented-bar`)

A segmented progress/stat bar in the Destiny FUI style.

- Install: `npx shadcn@latest add @engram/segmented-bar`
- Registry item: /r/segmented-bar.json
- Registry dependencies: @engram/cn, @engram/tokens

Props (`SegmentedBar`):

- `value` (`number`, required)
- `max` (`number`, default `100`)
- `segments` (`number`) — Optional number of segments; renders dividing ticks when set.
- `color` (`string`, default `"var(--engram-accent-2)"`) — Fill color (any CSS color, e.g. a token var).
- `glow` (`boolean`, default `true`) — Glow the fill (Destiny stat/health bars glow in their color).

### Layout

#### Band (`@engram/band`)

A section band: a flat raised bar with a left accent edge, an uppercase tracked title, and an optional right-aligned count — Destiny's in-game content-section divider.

- Install: `npx shadcn@latest add @engram/band`
- Registry item: /r/band.json
- Registry dependencies: @engram/cn, @engram/tokens

Props (`Band`):

- `title` (`ReactNode`, required)
- `count` (`ReactNode`) — Right-aligned count / hint (e.g. "04" or `<><b>3</b> / 3</>`).
- `accent` (`string`) — Left-edge accent color. Defaults to the accent token; pass a team/faction color for scoreboard sections (e.g. `var(--engram-class-titan)` red).

#### Paged grid (`@engram/paged-grid`)

A paginated grid (the in-game Triumphs / Collections / vault pager): the page of cells flanked by full-height previous/next arrow bars, with page-indicator segments below and a fade+slide in the travel direction on change.

- Install: `npx shadcn@latest add @engram/paged-grid`
- Registry item: /r/paged-grid.json
- Registry dependencies: @engram/cn, @engram/tokens

Props (`PagedGrid`):

- `items` (`T[]`, required)
- `renderItem` (`(item: T, index: number) => ReactNode`, required)
- `itemKey` (`(item: T, index: number) => string`, required) — Stable key per item.
- `columns` (`number`, default `2`) — Columns on `sm`+ (mobile is always a single column). Default 2.
- `rows` (`number`, default `5`) — Rows per page — page size is `columns × rows`. Default 5.
- `gap` (`number`, default `8`) — Gap between cells (px). Default 8.
- `cellWidth` (`number`) — Fixed cell width (px). When set, columns are sized to the cell instead of stretching to fill the row, and the packed grid is centered — keeping fixed-size content (e.g. item tiles) tight at every breakpoint. Omit for the default fluid columns.
- `minRowHeight` (`number`) — Reserve `rows × minRowHeight` so partial last pages keep the page height.
- `label` (`string`, default `"Paged grid"`) — Accessible label for the paged region.
- `className` (`string`)

#### Panel (`@engram/panel`)

A Destiny FUI surface: a semi-transparent panel over the canvas, defined by its fill (no outline).

- Install: `npx shadcn@latest add @engram/panel`
- Registry item: /r/panel.json
- npm dependencies: class-variance-authority
- Registry dependencies: @engram/cn, @engram/tokens

#### Title bar (`@engram/title-bar`)

The FUI title bar: a leading flag glyph, an uppercase tracked title, and an optional right-aligned count, on a subtle left-lit gradient with a fading underline — Destiny's in-game panel header.

- Install: `npx shadcn@latest add @engram/title-bar`
- Registry item: /r/title-bar.json
- Registry dependencies: @engram/cn, @engram/tokens

Props (`TitleBar`):

- `title` (`ReactNode`, required)
- `count` (`ReactNode`) — Right-aligned count / hint (e.g. "04 / 10").
- `flag` (`ReactNode`, default `"▸"`) — Leading flag glyph. Pass `null` to hide it.

### Icons

#### Ammo icon (`@engram/ammo-icon`)

Ammo type glyph (primary/special/heavy) in the ammo's token color.

- Install: `npx shadcn@latest add @engram/ammo-icon`
- Registry item: /r/ammo-icon.json
- npm dependencies: @engram/core
- Registry dependencies: @engram/cn, @engram/token-utils, @engram/tokens

Props (`AmmoIcon`):

- `ammo` (`AmmoType`, required)
- `size` (`number`, default `16`) — Pixel size (square footprint; the brick is letterboxed inside).

#### Breaker icon (`@engram/breaker-icon`)

Champion breaker glyph (the real Bungie icon), tinted to currentColor.

- Install: `npx shadcn@latest add @engram/breaker-icon`
- Registry item: /r/breaker-icon.json
- npm dependencies: @engram/core
- Registry dependencies: @engram/cn, @engram/tokens

Props (`BreakerIcon`):

- `breaker` (`BreakerType`, required)
- `size` (`number`, default `16`) — Pixel size.

#### Class icon (`@engram/class-icon`)

The Guardian class mark (Titan / Hunter / Warlock), tinted in the class identity color with a soft glow.

- Install: `npx shadcn@latest add @engram/class-icon`
- Registry item: /r/class-icon.json
- npm dependencies: @engram/core
- Registry dependencies: @engram/cn, @engram/token-utils, @engram/tokens

Props (`ClassIcon`):

- `class` (`GuardianClass`, required)
- `size` (`number`, default `20`) — Pixel size.
- `color` (`string`) — Override the class color (defaults to the class identity token).

#### Element icon (`@engram/element-icon`)

The damage element as its real Destiny glyph, masked and tinted in the element color with a soft glow.

- Install: `npx shadcn@latest add @engram/element-icon`
- Registry item: /r/element-icon.json
- npm dependencies: @engram/core
- Registry dependencies: @engram/cn, @engram/token-utils, @engram/tokens

Props (`ElementIcon`):

- `element` (`ElementType`, required)
- `icon` (`ImageRef`) — Override the default manifest glyph (e.g. a resolved subclass icon).
- `size` (`number`, default `20`) — Pixel size.

#### Game icon (`@engram/game-icon`)

The one keyed icon for Destiny's small glyphs — elements, ammo, classes, breakers, weapon silhouettes, activities, currencies, factions: `<GameIcon name="raid" />`.

- Install: `npx shadcn@latest add @engram/game-icon`
- Registry item: /r/game-icon.json
- npm dependencies: @engram/core
- Registry dependencies: @engram/bungie-image, @engram/cn, @engram/tokens

Props (`GameIcon`):

- `name` (`GameIconName`) — Registry key, e.g. `"arc"`, `"raid"`, `"glimmer"`, `"auto-rifle"`.
- `icon` (`ImageRef`) — Escape hatch: any manifest definition's icon (displayProperties.icon) rendered as-is — for defs outside the curated registry.
- `label` (`string`) — Accessible label; defaults to the registry entry's label. Required with the raw `icon` escape hatch.
- `showLabel` (`boolean`, default `false`) — Render the label as a visible caption beside the icon.
- `size` (`number`, default `20`) — Pixel height (vector glyphs keep their aspect; art is square).

#### Weapon icon (`@engram/weapon-icon`)

A weapon-type silhouette glyph (Auto Rifle, Rocket Launcher, Sword, …), tinted to currentColor — the icon-font glyphs the game shows in tooltips and "Works best with" lines.

- Install: `npx shadcn@latest add @engram/weapon-icon`
- Registry item: /r/weapon-icon.json
- npm dependencies: @engram/core
- Registry dependencies: @engram/cn, @engram/tokens

Props (`WeaponIcon`):

- `type` (`WeaponGlyphType`) — The weapon-type glyph to draw. Omit and pass `name` to map from a Bungie display name ("Rocket Launcher").
- `name` (`string`) — Bungie weapon-type display name — resolved via weaponGlyphFromName. Renders nothing when neither `type` nor a known `name` is given.
- `size` (`number`, default `16`) — Pixel height; width follows each glyph's aspect ratio (they're wide).

### Items

#### Cost chip (`@engram/cost-chip`)

A currency/cost token: an amount + its currency icon. Used for vendor costs, build/material requirements, and rewards.

- Install: `npx shadcn@latest add @engram/cost-chip`
- Registry item: /r/cost-chip.json
- npm dependencies: @engram/core
- Registry dependencies: @engram/bungie-image, @engram/cn, @engram/tokens

Props (`CostChip`):

- `size` (`number`, default `16`) — Icon size in px.
- `className` (`string`)
- `icon` (`ImageRef`) — Currency or item icon.
- `amount` (`number`, required) — Quantity.
- `name` (`string`) — Currency / item name (accessibility + tooltip).
- `affordable` (`boolean`, default `true`) — Whether the player can afford it — dims/flags when false.

#### Item grid (`@engram/item-grid`)

The fundamental inventory/collection container: a CSS grid that lays out item tiles (passed as `children`).

- Install: `npx shadcn@latest add @engram/item-grid`
- Registry item: /r/item-grid.json
- Registry dependencies: @engram/cn, @engram/tokens

Props (`ItemGrid`):

- `columns` (`number`) — Fixed number of columns. Omit for a responsive auto-fill grid that packs as many `min`-wide tiles per row as fit (the default inventory behavior).
- `min` (`number`, default `48`) — Min tile width (px) for the responsive auto-fill grid. Default 48.
- `gap` (`number`, default `4`) — Gap between tiles (px). Default 4.

#### Item hover card (`@engram/item-hover-card`)

Reveals an inspect popup for the trigger (e.g. an ItemTile / gear slot) — the in-game "hover gear to inspect" flyout.

- Install: `npx shadcn@latest add @engram/item-hover-card`
- Registry item: /r/item-hover-card.json
- Registry dependencies: @engram/cn, @engram/tokens

Props (`ItemHoverCard`):

- `children` (`ReactNode`, required) — The trigger — typically an / gear slot.
- `popup` (`ReactNode`, required) — The inspect content shown on hover/click — typically an .
- `openDelay` (`number`, default `90`) — ms before the cursor-following preview opens on hover/focus.
- `closeDelay` (`number`, default `140`) — ms before the preview closes after the pointer leaves.
- `as` (`"button" | "span"`, default `"button"`) — Trigger element. Use `"span"` when the children are themselves interactive (e.g. an button) so the wrapper doesn't nest a `<button>` in a `<button>`; the child's own focus/click bubble up. Defaults to `"button"` (focusable on its own, for non-interactive children like a tile).
- `anchor` (`"cursor" | "panel"`, default `"cursor"`) — Where the preview is placed. - `"cursor"` (default): follows the cursor on hover, pins beside the trigger on click — the top-level item inspect behaviour. - `"panel"`: a secondary inspect nested *inside* an already-pinned panel (e.g. a mod within an ). It sits beside the whole panel (left/right), stays non-interactive, and never dismisses the parent pin — so sweeping across the mods just swaps the side popup.
- `className` (`string`)

#### Item image (`@engram/item-image`)

The layered Destiny item square: rarity-colored base, the item art, the season/tier watermark assembly (TierWatermark), the intrinsic glyph, then state chrome (masterwork frame + glow, crafted marker).

- Install: `npx shadcn@latest add @engram/item-image`
- Registry item: /r/item-image.json
- npm dependencies: @engram/core
- Registry dependencies: @engram/bungie-image, @engram/cn, @engram/tier-watermark, @engram/token-utils, @engram/tokens

Props (`ItemImage`):

- `icon` (`ImageRef`, required)
- `rarity` (`Rarity`, required)
- `watermark` (`ImageRef`) — Clean season glyph (secondaryBackground) for the tier-watermark assembly.
- `tier` (`number`) — Gear tier (1–5) — drives the diamond count.
- `intrinsicIcon` (`ImageRef`) — Intrinsic glyph — weapon frame or armor archetype — shown top-right.
- `masterwork` (`boolean`)
- `crafted` (`boolean`) — A crafted ("Shaped") weapon — the red crafted glyph, bottom-left.
- `deepsight` (`boolean`) — Deepsight Resonance — the red border + rising glow.
- `size` (`number`, default `48`) — Pixel size (square).

#### Item popup (`@engram/item-popup`)

The item inspect flyout — a dark glass panel modeled on the in-game tooltip: a rarity header band, a damage-type + power/ammo readout, flavor, an optional kill tracker, the stat block, the intrinsic frame row, a perk band (`children`, e.g. a `SocketGrid`), and an action `footer` (e.g. Apply).

- Install: `npx shadcn@latest add @engram/item-popup`
- Registry item: /r/item-popup.json
- npm dependencies: @engram/core
- Registry dependencies: @engram/ammo-icon, @engram/breaker-icon, @engram/bungie-image, @engram/chip, @engram/cn, @engram/element-icon, @engram/item-hover-card, @engram/item-popup-header, @engram/item-stats, @engram/panel, @engram/roll-verdict, @engram/token-utils, @engram/tokens

Props (`ItemPopup`):

- `header` (`HeaderData`, required)
- `seasonIcon` (`ImageRef`) — Season watermark shown in the header's tier strip (matches the tile).
- `archetype` (`{ name: string; icon?: ImageRef }`) — New-armor archetype (Brawler/Paragon/…) shown beside the power readout.
- `stats` (`StatProps[]`)
- `frame` (`WeaponFrameRef`) — Intrinsic frame row (weapons).
- `tracker` (`ItemTracker`) — Kill / usage tracker row.
- `annotations` (`ItemAnnotations`) — Typed curated-roll annotations — verdict + tags.
- `children` (`ReactNode`) — Perk / socket content (e.g. a `SocketGrid`).
- `footer` (`ReactNode`) — Action buttons (e.g. Apply / Compare).
- `className` (`string`)

#### Item popup header (`@engram/item-popup-header`)

The rarity-gradient header band: name on top, type + rarity on the lower line, and a top-right tier strip (TierWatermark) with the season glyph flush in the corner — the same assembly the item tile composites.

- Install: `npx shadcn@latest add @engram/item-popup-header`
- Registry item: /r/item-popup-header.json
- npm dependencies: @engram/core
- Registry dependencies: @engram/cn, @engram/tier-watermark, @engram/tokens

Props (`ItemPopupHeader`):

- `name` (`string`, required)
- `typeName` (`string`)
- `rarity` (`Rarity`, required)
- `seasonIcon` (`ImageRef`) — Clean season crest shown top-right.
- `tier` (`number`) — Gear tier (1–5) — rendered as diamonds top-right.
- `masterwork` (`boolean`) — Masterworked — shows a bright gold top edge (same gold for all rarities).

#### Item stats (`@engram/item-stats`)

The Destiny stat block: an aligned grid of right-labeled stat rows.

- Install: `npx shadcn@latest add @engram/item-stats`
- Registry item: /r/item-stats.json
- npm dependencies: @engram/core
- Registry dependencies: @engram/cn, @engram/segmented-bar, @engram/tokens

Props (`ItemStats`):

- `className` (`string`)
- `color` (`string`, default `BAR_COLOR`) — Bar fill color (any CSS color / token var).
- `stats` (`StatProps[]`, required)
- `total` (`number`) — Show a summed "Total" row beneath the stats (armor).

#### Item tile (`@engram/item-tile`)

A full item tile: the layered ItemImage with a bottom element+power foot, and the signature Destiny white outline on hover.

- Install: `npx shadcn@latest add @engram/item-tile`
- Registry item: /r/item-tile.json
- npm dependencies: @engram/core
- Registry dependencies: @engram/cn, @engram/element-icon, @engram/item-image, @engram/tokens

Props (`ItemTile`):

- `size` (`number`, default `48`) — Pixel size (square).
- `topLeft` (`ReactNode`) — Status badge composited into the top-left corner (e.g. a tag dot).
- `topRight` (`ReactNode`) — Status badge in the top-right corner (e.g. lock / tracked / "new").
- `bottomLeft` (`ReactNode`) — Status badge in the bottom-left corner (the foot holds element+power).
- `progress` (`number`) — Completion progress 0–1 — a thin bar pinned across the bottom edge.
- `progressColor` (`string`, default `"var(--engram-accent)"`) — Color for the progress bar fill. Defaults to the accent token.
- `icon` (`ImageRef`, required)
- `name` (`string`, required)
- `rarity` (`Rarity`, required)
- `watermark` (`ImageRef`) — Season watermark / crest glyph.
- `tier` (`number`) — Gear tier (1–5) — rendered as tier-1 diamonds.
- `intrinsicIcon` (`ImageRef`) — Intrinsic glyph — weapon frame or armor archetype — shown top-right.
- `masterwork` (`boolean`) — Masterworked — the bright gold frame + glow.
- `crafted` (`boolean`) — A crafted ("Shaped") weapon — shows the red crafted glyph in the bottom-left corner (no border).
- `deepsight` (`boolean`) — Deepsight Resonance — an extractable red-border weapon; draws the red frame + rising red glow. Distinct from .
- `power` (`number`) — Power / light level.
- `ammo` (`AmmoType`)
- `element` (`ElementType`)

#### Power badge (`@engram/power-badge`)

The power/light readout: the angular power glyph + the value in gold, with an optional `cap`.

- Install: `npx shadcn@latest add @engram/power-badge`
- Registry item: /r/power-badge.json
- Registry dependencies: @engram/cn, @engram/tokens

Props (`PowerBadge`):

- `power` (`number`, required) — The power / light value.
- `cap` (`number`) — The current power cap; when reached the badge reads as maxed (glows).
- `color` (`string`, default `"var(--engram-gold)"`) — Number color. Defaults to the gold power token.
- `size` (`number`, default `18`) — Pixel font size for the number.

#### Rarity gem (`@engram/rarity-gem`)

A small diamond gem in the rarity's token color.

- Install: `npx shadcn@latest add @engram/rarity-gem`
- Registry item: /r/rarity-gem.json
- npm dependencies: @engram/core
- Registry dependencies: @engram/cn, @engram/token-utils, @engram/tokens

Props (`RarityGem`):

- `rarity` (`Rarity`, required)
- `size` (`number`, default `12`) — Pixel size.

#### Tier watermark (`@engram/tier-watermark`)

The season/tier corner assembly shared by the item tile and the inspect popup header: a soft scrim, the season crest, and a colored diamond per gear tier — the diamonds and gradient are drawn in CSS (no baked-in Bungie asset margins), so the whole stack aligns precisely.

- Install: `npx shadcn@latest add @engram/tier-watermark`
- Registry item: /r/tier-watermark.json
- npm dependencies: @engram/core
- Registry dependencies: @engram/bungie-image, @engram/cn, @engram/tokens

Props (`TierWatermark`):

- `seasonIcon` (`ImageRef`) — Clean season glyph (`DestinyIconDefinition.secondaryBackground`).
- `tier` (`number`, default `0`) — Gear tier (1–5). Drawn as that many diamonds — gold at tier 5, light blue/purple below; tier 1 (and untiered) shows none.
- `corner` (`"top-left" | "top-right"`, default `"top-left"`) — Corner the crest + diamonds sit in. Default top-left.
- `glyphSize` (`number`, default `16`) — Season crest width, px.
- `diamondSize` (`number`, default `5`) — Diamond edge length, px.
- `scrimWidth` (`number`, default `32`) — Width of the top-to-bottom scrim strip down the crest's column, px.
- `crestGap` (`number`, default `3`) — Gap between the crest and the diamonds, px.
- `diamondGap` (`number`, default `4`) — Gap between adjacent diamonds, px. Scaled down with the tile so a full 5-diamond stack never runs off the bottom edge on small tiles.
- `className` (`string`)

### Sockets & perks

#### Perk popup (`@engram/perk-popup`)

The weapon-perk inspect flyout — the in-game trait tooltip, the weapon counterpart to ModPopup.

- Install: `npx shadcn@latest add @engram/perk-popup`
- Registry item: /r/perk-popup.json
- npm dependencies: @engram/core
- Registry dependencies: @engram/cn, @engram/panel, @engram/tokens

Props (`PerkPopup`):

- `footer` (`ReactNode`) — Action buttons (e.g. a Select button).
- `className` (`string`)
- `name` (`string`, required)
- `subtitle` (`string`) — Perk category line, e.g. "Trait", "Enhanced Trait", "Barrel", "Magazine", "Origin Trait".
- `enhanced` (`boolean`) — An enhanced trait — shows the gold ▲ beside the subtitle and tints it gold.
- `description` (`string`) — The perk's effect description.
- `enhancement` (`string`) — For enhanced traits: the bonus the enhancement adds — the gold "⬆ ENHANCEMENT" block (e.g. "Improves ability energy gains.").

#### Plug (`@engram/plug`)

A single socket plug — a perk circle or a mod square. A selected perk gets the in-game azure fill (blue→gold when enhanced, with the gold ▲ badge); a selected mod keeps the bright ring.

- Install: `npx shadcn@latest add @engram/plug`
- Registry item: /r/plug.json
- npm dependencies: @engram/core
- Registry dependencies: @engram/bungie-image, @engram/cn, @engram/tokens

Props (`Plug`):

- `kind` (`"perk" | "mod"`, default `"perk"`) — Perks render as circles, mods as squares.
- `size` (`number`, default `36`) — Pixel size.
- `badge` (`ReactNode`) — Overlay slot (e.g. a curated-roll badge) — the extension hook.
- `hash` (`number`, required) — Plug item hash.
- `name` (`string`, required)
- `icon` (`ImageRef`)
- `enabled` (`boolean`) — Whether the plug is currently active/usable.
- `selected` (`boolean`) — Whether this plug is the one currently inserted in the socket.
- `enhanced` (`boolean`) — An enhanced weapon trait — renders the gold ▲ badge and the blue→gold enhanced fill (the in-game "this perk is enhanced" treatment).
- `backing` (`boolean`) — Render a neutral gray card backing behind the icon — for plugs whose art has a transparent background (e.g. armor tuning mods) that would otherwise look inconsistent beside mods that bake their own gray card.

#### Plug badge (`@engram/plug-badge`)

Default rendering of a PlugAnnotation as a small plug overlay: a tier chip, a custom icon, or a gold recommended marker.

- Install: `npx shadcn@latest add @engram/plug-badge`
- Registry item: /r/plug-badge.json
- npm dependencies: @engram/core
- Registry dependencies: @engram/bungie-image, @engram/cn, @engram/tokens

Props (`PlugBadge`):

- `annotation` (`PlugAnnotation`, required)
- `className` (`string`)

#### Plug picker (`@engram/plug-picker`)

A grid of selectable plugs — the picker body for swapping a mod, perk, aspect, or fragment.

- Install: `npx shadcn@latest add @engram/plug-picker`
- Registry item: /r/plug-picker.json
- npm dependencies: @engram/core
- Registry dependencies: @engram/cn, @engram/item-grid, @engram/mod-slot, @engram/plug, @engram/tokens

Props (`PlugPicker`):

- `options` (`PlugPickerOption[]`, required)
- `selected` (`number`) — Hash of the currently selected plug.
- `onSelect` (`(option: PlugPickerOption) => void`)
- `groupBy` (`(option: PlugPickerOption) => string | undefined`) — Group options under headers (defaults to each option's `group`).
- `kind` (`"perk" | "mod"`, default `"mod"`) — Perks render as circles, mods as squares.
- `size` (`number`, default `48`) — Pixel size per option.

#### Socket (`@engram/socket`)

One socket: a perk column (stacked circles) or a mod socket (squares).

- Install: `npx shadcn@latest add @engram/socket`
- Registry item: /r/socket.json
- npm dependencies: @engram/core
- Registry dependencies: @engram/cn, @engram/item-hover-card, @engram/plug, @engram/plug-badge, @engram/tokens

Props (`Socket`):

- `className` (`string`)
- `plugSize` (`number`) — Pixel size for this socket's plugs.
- `annotations` (`Record<number, PlugAnnotation>`) — Typed curated-roll annotations keyed by plug hash (rendered as default badges).
- `renderBadge` (`(plug: PlugData) => ReactNode`) — Fully override the badge for a plug (takes precedence over `annotations`).
- `onPlugClick` (`(plug: PlugData) => void`) — Called when a plug is clicked.
- `plugPopup` (`(plug: PlugData) => ReactNode`) — A plug's inspect popup (e.g. a ). When it returns a node, the plug reveals it on hover beside the parent inspect panel — the in-game "hover a mod to read it" detail. Return `null` for plugs with no inspect.
- `index` (`number`, required) — Socket index on the item.
- `kind` (`"perk" | "mod"`, required) — Perk columns render as circles; mod sockets render as squares.
- `plugs` (`PlugProps[]`, required)

#### Socket grid (`@engram/socket-grid`)

The socket layout: perk sockets as side-by-side columns of circles, then mod sockets as a row of squares — the Destiny weapon perk/mod grid.

- Install: `npx shadcn@latest add @engram/socket-grid`
- Registry item: /r/socket-grid.json
- npm dependencies: @engram/core
- Registry dependencies: @engram/cn, @engram/socket, @engram/tokens

Props (`SocketGrid`):

- `className` (`string`)
- `annotations` (`Record<number, PlugAnnotation>`) — Typed curated-roll annotations keyed by plug hash (rendered as default badges).
- `renderBadge` (`(plug: PlugData) => ReactNode`) — Fully override the badge for a plug (takes precedence over `annotations`).
- `onPlugClick` (`(plug: PlugData) => void`) — Called when a plug is clicked.
- `plugPopup` (`(plug: PlugData) => ReactNode`) — A plug's inspect popup (e.g. a ), revealed on hover beside the parent inspect panel. Return `null` for plugs with no inspect.
- `sockets` (`SocketProps[]`, required)

### Loadout

#### Ability slot (`@engram/ability-slot`)

A single subclass/loadout socket — an ability, aspect, fragment, super, or class ability.

- Install: `npx shadcn@latest add @engram/ability-slot`
- Registry item: /r/ability-slot.json
- npm dependencies: @engram/core
- Registry dependencies: @engram/bungie-image, @engram/cn, @engram/item-hover-card, @engram/tokens

Props (`AbilitySlot`):

- `plug` (`PlugProps`) — The slotted ability/aspect/fragment; omit for an empty slot.
- `empty` (`boolean`, default `false`) — Force the empty placeholder even without a plug.
- `onPick` (`() => void`) — Fired when the slot is clicked (open a picker).
- `popup` (`ReactNode`) — Inspect content shown on hover (e.g. a ). When set, the slot becomes the trigger of an .
- `kind` (`AbilityKind`, default `"ability"`) — What this slot holds (used for the accessible label).
- `shape` (`AbilityShape`, default `"square"`) — Socket shape. Square (default) holds the square ability/aspect/fragment art cleanly; `round` is for subclass nodes whose icon art is circular-friendly (square art would be cropped to the circle).
- `size` (`number`, default `44`) — Pixel size.
- `selected` (`boolean`, default `false`) — Highlight as selected.

#### Artifact perk (`@engram/artifact-perk`)

A seasonal-artifact perk tile — one square cell of the in-game artifact grid: teal-filled when the perk is active, teal-outlined when it's unlocked but unpicked, and dimmed while its tier is still locked.

- Install: `npx shadcn@latest add @engram/artifact-perk`
- Registry item: /r/artifact-perk.json
- npm dependencies: @engram/core
- Registry dependencies: @engram/bungie-image, @engram/cn, @engram/item-hover-card, @engram/tokens

Props (`ArtifactPerk`):

- `icon` (`ImageRef`) — The perk glyph (the perk item definition's icon).
- `name` (`string`, required) — Perk name — the accessible label.
- `state` (`ArtifactPerkState`, default `"unlocked"`) — `active` = picked (teal fill), `unlocked` = available (teal outline), `locked` = not yet reachable (dimmed).
- `size` (`number`, default `48`) — Pixel size (square).
- `popup` (`ReactNode`) — Inspect content revealed on hover (e.g. a ).
- `onPick` (`() => void`) — Fired on click (toggle/pick the perk).

#### Energy meter (`@engram/energy-meter`)

The armor energy capacity readout: a row of pips where `used` are filled, the rest of `total` are empty sockets, and any headroom up to `max` shows as faint upgrade ghosts.

- Install: `npx shadcn@latest add @engram/energy-meter`
- Registry item: /r/energy-meter.json
- Registry dependencies: @engram/cn, @engram/tokens

Props (`EnergyMeter`):

- `used` (`number`, required) — Energy points spent (filled pips).
- `total` (`number`, required) — Current capacity (filled + empty pips).
- `max` (`number`) — Upgradeable ceiling — pips between `total` and `max` render as faint ghosts to show remaining headroom. Defaults to `total` (no ghosts).
- `size` (`number`, default `10`) — Pip diameter (px). Default 10.
- `color` (`string`, default `"var(--engram-accent)"`) — Pip fill color (the energy affinity). Defaults to the accent token.

#### Loadout card (`@engram/loadout-card`)

A compact build summary: the subclass diamond + name, the equipped item tiles, an optional mod row, the stat tiers, and an action footer.

- Install: `npx shadcn@latest add @engram/loadout-card`
- Registry item: /r/loadout-card.json
- npm dependencies: @engram/core
- Registry dependencies: @engram/character-stats, @engram/cn, @engram/item-tile, @engram/plug, @engram/subclass-diamond, @engram/tokens

Props (`LoadoutCard`):

- `name` (`ReactNode`) — Build name / title.
- `subclass` (`LoadoutSubclass`) — Subclass shown as a diamond beside the name.
- `items` (`ItemTileData[]`) — Equipped weapons + armor as tiles.
- `mods` (`PlugProps[]`) — Mod icons shown in a compact row.
- `stats` (`CharacterStatItem[]`) — Stat block (tiers).
- `footer` (`ReactNode`) — Action row (Equip / Share / Edit).

#### Mod popup (`@engram/mod-popup`)

The armor-mod inspect flyout — the in-game mod tooltip, the mod counterpart to PlugPopup.

- Install: `npx shadcn@latest add @engram/mod-popup`
- Registry item: /r/mod-popup.json
- npm dependencies: @engram/core
- Registry dependencies: @engram/bungie-image, @engram/cn, @engram/panel, @engram/tokens

Props (`ModPopup`):

- `footer` (`ReactNode`) — Action buttons (e.g. an Equip / Insert button).
- `className` (`string`)
- `name` (`string`, required)
- `subtitle` (`string`) — Mod category, e.g. "General Armor Mod", "Chest Armor Mod".
- `energyCost` (`number`) — Armor energy cost.
- `energyIcon` (`ImageRef`) — The energy-cost glyph (the "hammer") shown beside the cost — the "Any Energy Type Cost" stat icon. Falls back to a gold pip when omitted.
- `icon` (`ImageRef`) — The mod's icon — shown beside its effect description.
- `stats` (`ModStat[]`) — Stat bonuses, e.g. +10 Super.
- `description` (`string`) — Effect description.
- `note` (`string`) — Info note (the ⓘ line) — e.g. stacking / diminishing-returns text.

#### Mod slot (`@engram/mod-slot`)

One armor mod socket: a square plug with its energy-cost pip in the corner, or an empty "+" placeholder.

- Install: `npx shadcn@latest add @engram/mod-slot`
- Registry item: /r/mod-slot.json
- npm dependencies: @engram/core
- Registry dependencies: @engram/bungie-image, @engram/cn, @engram/item-hover-card, @engram/tokens

Props (`ModSlot`):

- `plug` (`PlugProps`) — The inserted armor mod; omit for an empty socket.
- `energyCost` (`number`) — Energy cost — shown as a small pip in the corner.
- `empty` (`boolean`, default `false`) — Force the empty placeholder.
- `onPick` (`() => void`) — Fired when the socket is clicked (open the plug picker).
- `popup` (`ReactNode`) — Inspect content shown on hover (e.g. a ). When set, the socket becomes the trigger of an .
- `size` (`number`, default `44`) — Pixel size.
- `selected` (`boolean`, default `false`)

#### Mod tray (`@engram/mod-tray`)

A row of ModSlots with an energy-budget meter — the armor mod loadout for one piece. `used` defaults to the summed energy costs; the meter turns over-budget red when the slots exceed `capacity`.

- Install: `npx shadcn@latest add @engram/mod-tray`
- Registry item: /r/mod-tray.json
- npm dependencies: @engram/core
- Registry dependencies: @engram/cn, @engram/energy-meter, @engram/mod-slot, @engram/tokens

Props (`ModTray`):

- `slots` (`ModTraySlot[]`, required) — The mod sockets in this tray.
- `capacity` (`number`, required) — Total energy capacity of the armor piece.
- `used` (`number`) — Energy spent; defaults to the sum of the slots' energy costs.
- `size` (`number`, default `44`) — Pixel size per socket.
- `onPick` (`(index: number) => void`) — Fired with the socket index when a socket is clicked.
- `popup` (`(plug: PlugProps, index: number) => ReactNode`) — Inspect content for a filled socket (e.g. a ), shown on hover — wires each socket to an .

#### Plug popup (`@engram/plug-popup`)

The subclass-plug inspect flyout — the in-game tooltip for abilities, aspects, fragments, supers, and subclasses, the counterpart to ItemPopup for non-gear plugs.

- Install: `npx shadcn@latest add @engram/plug-popup`
- Registry item: /r/plug-popup.json
- npm dependencies: @engram/core
- Registry dependencies: @engram/bungie-image, @engram/cn, @engram/element-icon, @engram/key-hint, @engram/panel, @engram/token-utils, @engram/tokens, @engram/weapon-icon

Props (`PlugPopup`):

- `footer` (`ReactNode`) — Action buttons (e.g. an Apply button).
- `className` (`string`)
- `name` (`string`, required)
- `subtitle` (`string`) — Plug category line, e.g. "Arc Grenade", "Arc Aspect", "Void Fragment".
- `element` (`ElementType`) — Subclass element — tints the header band and the highlighted keywords.
- `banner` (`ImageRef`) — Wide banner art beneath the header — the plug's `secondaryIcon` (a ~525×150 image). Note: subclass plugs have no `screenshot` (Bungie only sets that for equippable gear); `secondaryIcon` is the field that carries this art.
- `flavor` (`string`) — Italic flavor line (aspects usually have one).
- `description` (`string`) — Body description. Terms listed in `keywords` are tinted within it.
- `keywords` (`string[]`) — Plain terms within `description` to tint in the element/accent color (e.g. element words like "Solar", or any emphasis that needs no definition).
- `definitions` (`PlugKeyword[]`) — Mechanic keyword definitions rolled into the popup — the in-game ancillary panel (icon + name + effect), e.g. Scorch / Ignition / Bolt Charge / Jolted. Their names are also tinted where they appear in `description`.
- `fragmentSlots` (`number`) — Aspects only: number of fragment slots → that many diamond pips.
- `meta` (`PlugMetaRow[]`) — Foot meta rows, e.g. "Binds to:" + keybind, "Base Cooldown:" + "2:32".

#### Slot row (`@engram/slot-row`)

A fixed-count row of AbilitySlots — the aspect or fragment block of a subclass, where the subclass fixes how many slots exist and some may be empty.

- Install: `npx shadcn@latest add @engram/slot-row`
- Registry item: /r/slot-row.json
- npm dependencies: @engram/core
- Registry dependencies: @engram/ability-slot, @engram/cn, @engram/tokens

Props (`SlotRow`):

- `count` (`number`, required) — Total slots to render (fixed by the subclass — e.g. 2 aspects, 4 fragments).
- `slots` (`(PlugProps | null | undefined)[]`, default `[]`) — Filled slots; positions past the array render empty.
- `kind` (`AbilityKind`, default `"fragment"`) — What these slots hold.
- `size` (`number`, default `40`) — Pixel size per slot.
- `onPick` (`(index: number) => void`) — Fired with the slot index when a slot is clicked.
- `popup` (`(plug: PlugProps, index: number) => ReactNode`) — Inspect content for a filled slot (e.g. a ), shown on hover — wires each slot to an .

#### Subclass diamond (`@engram/subclass-diamond`)

The signature subclass node: a 45°-rotated diamond frame tinted by its damage type, with the subclass icon upright inside and an optional super overlay.

- Install: `npx shadcn@latest add @engram/subclass-diamond`
- Registry item: /r/subclass-diamond.json
- npm dependencies: @engram/core
- Registry dependencies: @engram/bungie-image, @engram/cn, @engram/item-hover-card, @engram/token-utils, @engram/tokens

Props (`SubclassDiamond`):

- `icon` (`ImageRef`) — Subclass icon (rendered upright inside the diamond).
- `element` (`ElementType`) — Damage type — tints the diamond frame + glow.
- `super` (`ImageRef`) — Super icon overlaid in the corner.
- `popup` (`ReactNode`) — Inspect content shown on hover (e.g. a ). When set, the diamond becomes the trigger of an .
- `size` (`number`, default `56`) — Pixel size of the bounding box.
- `selected` (`boolean`, default `false`) — Highlight as the active subclass.

### Identity & nameplates

#### Character tile (`@engram/character-tile`)

The character column header — a Nameplate whose headline defaults to the Guardian's class.

- Install: `npx shadcn@latest add @engram/character-tile`
- Registry item: /r/character-tile.json
- npm dependencies: @engram/core
- Registry dependencies: @engram/cn, @engram/nameplate, @engram/tokens

Props (`CharacterTile`):

- `emblem` (`EmblemRef`, required)
- `class` (`GuardianClass`) — Guardian class — the headline defaults to its name.
- `name` (`string`) — Headline override (defaults to the class name).
- `title` (`string`) — Equipped Seal title (gold) — shown on the secondary line.
- `subtitle` (`string`) — Secondary descriptor (race). Power is NOT repeated here — it has its own slot.
- `power` (`number`)
- `height` (`number`, default `72`) — Pixel height. Default 72.

#### Emblem banner (`@engram/emblem-banner`)

The wide emblem banner (DIM model): the emblem's secondary banner art fills the tile (which Nameplate caps to the banner's aspect ratio) under a left→ right dark gradient so overlaid text stays legible. `children` render over the banner.

- Install: `npx shadcn@latest add @engram/emblem-banner`
- Registry item: /r/emblem-banner.json
- npm dependencies: @engram/core
- Registry dependencies: @engram/cn, @engram/tokens

Props (`EmblemBanner`):

- `emblem` (`EmblemRef`, required)
- `height` (`number`, default `84`) — Pixel height.

#### Nameplate (`@engram/nameplate`)

A character/player nameplate (DIM model): the emblem banner sized to its own aspect ratio, with the name + subtitle over the dark band and a small gold power readout tucked into the top-right corner.

- Install: `npx shadcn@latest add @engram/nameplate`
- Registry item: /r/nameplate.json
- npm dependencies: @engram/core
- Registry dependencies: @engram/emblem-banner, @engram/tokens

Props (`Nameplate`):

- `height` (`number`, default `84`) — Pixel height.
- `name` (`string`, required)
- `emblem` (`EmblemRef`, required)
- `class` (`GuardianClass`)
- `subtitle` (`string`) — Secondary line under the name (e.g. the race, "Exo"). Falls back to the class name when omitted.
- `title` (`string`) — Equipped Seal title (e.g. "Conqueror") — shown in gold before the subtitle.
- `power` (`number`)

#### Player card (`@engram/player-card`)

An identity card. The default is a compact tile (square emblem + name + class + rank + stats) for search results and fireteam lists.

- Install: `npx shadcn@latest add @engram/player-card`
- Registry item: /r/player-card.json
- npm dependencies: @engram/core
- Registry dependencies: @engram/bungie-image, @engram/class-icon, @engram/cn, @engram/emblem-banner, @engram/power-badge, @engram/tokens

Props (`PlayerCard`):

- `name` (`string`, required)
- `emblem` (`EmblemRef`, required)
- `class` (`GuardianClass`) — Guardian class — shows the class glyph beside the name.
- `subtitle` (`ReactNode`) — Secondary line (Bungie code "#1234", platform, last-seen…).
- `rank` (`ReactNode`) — Right-aligned slot — a rank/glory badge, fireteam role, or action.
- `stats` (`ReactNode`) — Stats row rendered along the bottom (e.g. K/D, wins).
- `banner` (`boolean`, default `false`) — Use the wide emblem-banner art as the row background (the in-game PGCR / scoreboard / fireteam row) instead of the small square icon.
- `power` (`number`) — Light level shown as a gold ◆ readout (banner rows).
- `accent` (`string`, default `"var(--engram-accent)"`) — Accent color for the banner's bottom progress edge (team/emblem color).
- `progress` (`number`) — Banner fill 0–1 — the thin progress edge under the name.
- `height` (`number`, default `56`) — Pixel height of the banner row. Default 56.

### Stats

#### Character stats (`@engram/character-stats`)

The in-game character stat panel: one row per stat — just the stat glyph and a large value, no bars or labels (Destiny shows the six as icon + number).

- Install: `npx shadcn@latest add @engram/character-stats`
- Registry item: /r/character-stats.json
- npm dependencies: @engram/core
- Registry dependencies: @engram/bungie-image, @engram/cn, @engram/item-hover-card, @engram/stat-popup, @engram/tokens

Props (`CharacterStats`):

- `stats` (`CharacterStatItem[]`, required)
- `iconSide` (`"left" | "right"`, default `"right"`) — Which side the stat glyph sits on. `"right"` = value then glyph — the in-game character sheet (default). `"left"` = glyph then value — the subclass screen.
- `footer` (`ReactNode`) — Content below a hairline divider — e.g. the equipped subclass emblem or ability-cooldown readouts, as on the in-game panel.
- `className` (`string`)

#### Stat bar (`@engram/stat-bar`)

A labeled stat row: name, segmented bar, and value (Destiny stat block).

- Install: `npx shadcn@latest add @engram/stat-bar`
- Registry item: /r/stat-bar.json
- npm dependencies: @engram/core
- Registry dependencies: @engram/cn, @engram/segmented-bar, @engram/tokens

Props (`StatBar`):

- `stat` (`StatProps`, required)
- `max` (`number`) — Bar maximum; defaults to the stat's max, then 100.
- `color` (`string`, default `"var(--engram-bar)"`) — Fill color (any CSS color, e.g. a token var). Defaults to a light fill.
- `className` (`string`)

#### Stat card (`@engram/stat-card`)

A KPI tile: a small label, a big headline value, and an optional period delta (green up / red down).

- Install: `npx shadcn@latest add @engram/stat-card`
- Registry item: /r/stat-card.json
- Registry dependencies: @engram/cn, @engram/tokens

Props (`StatCard`):

- `label` (`ReactNode`, required) — What the number measures (e.g. "K/D", "Win Rate", "Kills").
- `value` (`ReactNode`, required) — The headline value (pre-formatted).
- `delta` (`number`) — Signed change vs the prior period — colored up=ok / down=bad with an arrow.
- `deltaSuffix` (`string`, default `""`) — Unit appended to the delta (e.g. "%").
- `icon` (`ReactNode`) — Small icon/glyph in the corner.
- `tone` (`StatCardTone`, default `"neutral"`) — Color the headline value. Default neutral.

#### Stat card grid (`@engram/stat-card-grid`)

A responsive grid of StatCards with an optional `tabs` slot above for a time-span switch (Daily / Weekly / All-time).

- Install: `npx shadcn@latest add @engram/stat-card-grid`
- Registry item: /r/stat-card-grid.json
- Registry dependencies: @engram/cn, @engram/tokens

Props (`StatCardGrid`):

- `tabs` (`ReactNode`) — A control rendered above the grid — typically a time-span .
- `min` (`number`, default `140`) — Min card width for the responsive auto-fill grid (px). Default 140.
- `gap` (`number`, default `8`) — Gap between cards (px). Default 8.
- `children` (`ReactNode`, required) — The s.

#### Stat popup (`@engram/stat-popup`)

The character-stat inspect tooltip — the in-game flyout for the six stats (Weapons/Health/Class/Grenade/Super/Melee): a black header band (stat glyph, large name, "Character Stat" caption), the stat's description, labeled effect readouts ("Health Per Orb" / "+62.3"), the gold "Enhanced Benefit" section that unlocks above 100, and a value/max progress footer with a threshold tick at 100.

- Install: `npx shadcn@latest add @engram/stat-popup`
- Registry item: /r/stat-popup.json
- npm dependencies: @engram/core
- Registry dependencies: @engram/bungie-image, @engram/cn, @engram/panel, @engram/tokens

Props (`StatPopup`):

- `className` (`string`)
- `name` (`string`, required)
- `subtitle` (`string`, default `"Character Stat"`) — Header caption under the name (e.g. "Character Stat", the default).
- `icon` (`ImageRef`) — The stat glyph — the DestinyStatDefinition icon.
- `description` (`string`) — What the stat does — the stat definition's description.
- `rows` (`StatPopupRow[]`) — Labeled effect readouts computed from the stat value, e.g. "Health Per Orb" + "+62.3".
- `enhanced` (`{ /** Section heading (defaults to "Enhanced Benefit"). */ heading?: string; description: string; /** Unlock condition line, e.g. "Activates above Stat Level 100." */ activation?: string; /** Effect readouts for points 101-200, present once the stat is above * 100 (e.g. "Melee Damage (PvE)" + "+15%"). */ rows?: StatPopupRow[]; }`) — The above-100 benefit section.
- `value` (`number`, required) — Current stat value — fills the footer bar.
- `max` (`number`, default `200`) — Footer bar maximum (defaults to 200, the in-game cap). A threshold tick marks 100 — where the enhanced benefit activates.

#### Stat priority list (`@engram/stat-priority-list`)

A drag-to-reorder priority list — the stat-priority picker for a build optimizer (drag Resilience above Recovery).

- Install: `npx shadcn@latest add @engram/stat-priority-list`
- Registry item: /r/stat-priority-list.json
- Registry dependencies: @engram/cn, @engram/dnd, @engram/tokens

Props (`StatPriorityList`):

- `order` (`T[]`, required) — The ordered items (highest priority first).
- `onReorder` (`(next: T[]) => void`, required) — Fired with the reordered array after a drag-drop.
- `renderItem` (`(item: T, index: number) => ReactNode`, required) — Render the row content for an item.
- `itemKey` (`(item: T) => string`, default `(item) => String(item)`) — Stable key per item. Defaults to String(item).
- `className` (`string`)

#### Stat range slider (`@engram/stat-range-slider`)

A dual-thumb min/max range slider with optional tier ticks — the stat filter for a build optimizer ("Resilience ≥ 60", "Mobility 30–70").

- Install: `npx shadcn@latest add @engram/stat-range-slider`
- Registry item: /r/stat-range-slider.json
- Registry dependencies: @engram/cn, @engram/tokens

Props (`StatRangeSlider`):

- `min` (`number`, default `0`) — Track minimum. Default 0.
- `max` (`number`, default `100`) — Track maximum. Default 100.
- `value` (`[number, number]`, required) — The selected [low, high] bounds.
- `step` (`number`, default `1`) — Step between values. Default 1.
- `tiers` (`number`) — Tier breakpoint spacing — draws ticks every `tiers` units (e.g. 10).
- `onChange` (`(value: [number, number]) => void`)
- `label` (`ReactNode`) — Row label shown above the track.
- `className` (`string`)

### Inventory

#### Bucket column (`@engram/bucket-column`)

A single inventory bucket: a collapsible labeled header with a capacity counter, an optional equipped slot, and the stored items in an ItemGrid.

- Install: `npx shadcn@latest add @engram/bucket-column`
- Registry item: /r/bucket-column.json
- Registry dependencies: @engram/cn, @engram/collapsible-section, @engram/item-grid, @engram/tokens

Props (`BucketColumn`):

- `title` (`ReactNode`, required) — Bucket name (e.g. "Kinetic Weapons", "Helmet").
- `equipped` (`ReactNode`) — The equipped item, rendered above the stored grid.
- `count` (`number`) — Stored item count (the filled slots).
- `capacity` (`number`) — Bucket capacity — shown as `count / capacity`; turns "bad" when over.
- `collapsible` (`boolean`, default `true`) — Whether the column collapses. Default true.
- `defaultOpen` (`boolean`, default `true`) — Initial open state when collapsible. Default true.
- `columns` (`number`) — Grid columns (passthrough to ).
- `min` (`number`) — Responsive min tile width (passthrough to ).
- `gap` (`number`) — Grid gap (passthrough to ).
- `children` (`ReactNode`) — The stored item tiles.
- `className` (`string`)

#### Currency bar (`@engram/currency-bar`)

A row of account currencies/materials — the header strip showing Glimmer, Bright Dust, mats, etc. A thin wrapper that lays CostChips in a wrapping row; the consumer supplies the values from the profile's currency components.

- Install: `npx shadcn@latest add @engram/currency-bar`
- Registry item: /r/currency-bar.json
- npm dependencies: @engram/core
- Registry dependencies: @engram/cn, @engram/cost-chip, @engram/tokens

Props (`CurrencyBar`):

- `currencies` (`CostProps[]`, required) — The currencies/materials to display (Glimmer, Legendary Shards, …).
- `size` (`number`, default `16`) — Icon size for each chip (px).

### Triumphs

#### Objective progress (`@engram/objective-progress`)

One objective's progress — the polymorphic readout behind triumphs, quests, bounties, metrics, crafting levels, kill trackers, and deepsight bars.

- Install: `npx shadcn@latest add @engram/objective-progress`
- Registry item: /r/objective-progress.json
- npm dependencies: @engram/core
- Registry dependencies: @engram/cn, @engram/segmented-bar, @engram/tokens

Props (`ObjectiveProgress`):

- `className` (`string`)
- `color` (`string`) — Fill color for the bar/pips. Defaults to the neutral bar color (in-progress) / gold (done). Pass `var(--engram-progress)` for the magenta seal progress.
- `formatValue` (`(n: number) => string`) — Format the numeric value/target (e.g. dates for countdown, thousands).
- `value` (`number`, required) — Current progress.
- `completionValue` (`number`) — Target value for completion (omit for open-ended counters).
- `complete` (`boolean`) — Explicit completion; defaults to `value >= completionValue`.
- `style` (`ObjectiveStyle`, default `"bar"`) — How to render the value (maps from DestinyUnlockValueUIStyle).
- `label` (`string`) — Short objective description.

#### Record card (`@engram/record-card`)

A triumph / record card (the in-game Triumphs & Seals grid): a circular record icon + title, a divider, an objective description, a right-aligned reward or completion check, and a thin progress edge — continuous or `steps` segments.

- Install: `npx shadcn@latest add @engram/record-card`
- Registry item: /r/record-card.json
- npm dependencies: @engram/core
- Registry dependencies: @engram/bungie-image, @engram/cn, @engram/tokens

Props (`RecordCard`):

- `title` (`ReactNode`, required)
- `description` (`ReactNode`) — The objective summary line.
- `icon` (`ImageRef`) — Triumph/record icon (rendered in a circular frame, in-game style).
- `complete` (`boolean`, default `false`) — Completed → gold check + gold-tinted card and a gold (full) progress edge.
- `progress` (`number`) — Progress 0–1 for the bottom edge. Omit for a boolean triumph (no bar). White-ish while in progress, gold when `complete`.
- `steps` (`number`) — Discrete part count — when set, the bottom edge renders as `steps` segments (e.g. "collect all 7") instead of a continuous bar.
- `reward` (`ReactNode`) — Right-aligned reward / score slot (overrides the completion check).

### Quests

#### Pursuit card (`@engram/pursuit-card`)

A quest / bounty pursuit card (the in-game Quests list): a square pursuit icon, the title + step description, an optional reward, and a thin step-progress edge. `tracked` gives it the green pinned-quest highlight.

- Install: `npx shadcn@latest add @engram/pursuit-card`
- Registry item: /r/pursuit-card.json
- npm dependencies: @engram/core
- Registry dependencies: @engram/bungie-image, @engram/cn, @engram/tokens

Props (`PursuitCard`):

- `title` (`ReactNode`, required)
- `description` (`ReactNode`) — Quest/bounty step summary (truncates to two lines).
- `icon` (`ImageRef`) — Pursuit icon (square, framed — the in-game quest/bounty icon).
- `tracked` (`boolean`, default `false`) — Pinned/tracked → green highlight border + a tracked marker.
- `progress` (`number`) — Step progress 0–1 — the thin bar along the bottom edge.
- `expiry` (`ReactNode`) — Time-left / expiry readout (bounties).
- `reward` (`ReactNode`) — Right-aligned reward icon slot.

### Tables

#### Compare cell (`@engram/compare-cell`)

A stat cell for comparison tables: the value with a thin bar, colored by its `rank` (best = ok/green, worst = bad/red, mid = neutral).

- Install: `npx shadcn@latest add @engram/compare-cell`
- Registry item: /r/compare-cell.json
- Registry dependencies: @engram/cn, @engram/segmented-bar, @engram/tokens

Props (`CompareCell`):

- `value` (`number`, required)
- `max` (`number`, default `100`) — Bar maximum (the stat's ceiling). Default 100.
- `rank` (`CompareRank`, default `"mid"`) — Standing among the compared rows — colors the value + bar.
- `barless` (`boolean`, default `false`) — Hide the bar and show just the colored number.

#### Data table (`@engram/data-table`)

The generic data table behind compare, organizer, scoreboards, and leaderboards.

- Install: `npx shadcn@latest add @engram/data-table`
- Registry item: /r/data-table.json
- Registry dependencies: @engram/cn, @engram/tokens

Props (`DataTable`):

- `columns` (`DataTableColumn<Row>[]`, required)
- `rows` (`Row[]`, required)
- `rowKey` (`(row: Row, index: number) => string`, required) — Stable row id (also the selection key).
- `sort` (`SortState`) — Controlled sort; omit to let the table manage it.
- `defaultSort` (`SortState`) — Initial sort when uncontrolled.
- `onSortChange` (`(sort: SortState) => void`)
- `selection` (`Set<string>`) — Controlled multi-selection (set of row keys); omit to manage internally.
- `onSelectionChange` (`(selection: Set<string>) => void`)
- `selectable` (`boolean`, default `false`) — Show the leading select-checkbox column.
- `sticky` (`boolean`, default `false`) — Stick the header to the top on scroll.
- `heat` (`boolean`, default `false`) — Tint cells by each column's `heat` accessor (best/worst shading).
- `onRowClick` (`(row: Row) => void`)
- `empty` (`ReactNode`) — Empty-state content when there are no rows.
- `className` (`string`)

### Crucible

#### Kill tracker (`@engram/kill-tracker`)

A masterwork/memento kill-tracker readout: a label on the left and the count tucked to the right, with an optional tracker icon.

- Install: `npx shadcn@latest add @engram/kill-tracker`
- Registry item: /r/kill-tracker.json
- npm dependencies: @engram/core
- Registry dependencies: @engram/bungie-image, @engram/cn, @engram/tokens

Props (`KillTracker`):

- `label` (`string`, required) — What's being counted (e.g. "Enemies Defeated", "Crucible Kills").
- `value` (`string | number`, required) — The running total.
- `icon` (`ImageRef`) — Optional tracker/memento icon shown before the label.

#### Roll verdict (`@engram/roll-verdict`)

A curated-roll verdict badge, colored by the status palette.

- Install: `npx shadcn@latest add @engram/roll-verdict`
- Registry item: /r/roll-verdict.json
- npm dependencies: @engram/core
- Registry dependencies: @engram/cn, @engram/tokens

### Interaction

#### Collapsible section (`@engram/collapsible-section`)

A titled disclosure: a tracked-uppercase header (with an optional count) that toggles its content.

- Install: `npx shadcn@latest add @engram/collapsible-section`
- Registry item: /r/collapsible-section.json
- Registry dependencies: @engram/cn, @engram/tokens

Props (`CollapsibleSection`):

- `title` (`ReactNode`, required) — Section heading.
- `count` (`ReactNode`) — Right-aligned count / summary (e.g. item count).
- `defaultOpen` (`boolean`, default `true`) — Initial open state when uncontrolled.
- `open` (`boolean`) — Controlled open state.
- `onOpenChange` (`(open: boolean) => void`)
- `children` (`ReactNode`, required)
- `className` (`string`)

#### Dnd (`@engram/dnd`)

A generic drag source: makes its `children` draggable and exposes an opaque `data` payload to drop targets.

- Install: `npx shadcn@latest add @engram/dnd`
- Registry item: /r/dnd.json
- Registry dependencies: @engram/cn, @engram/tokens

#### Filter bar (`@engram/filter-bar`)

A wrapping row of FilterPills — the active-filters strip above an inventory/collection grid.

- Install: `npx shadcn@latest add @engram/filter-bar`
- Registry item: /r/filter-bar.json
- Registry dependencies: @engram/chip, @engram/cn, @engram/tokens

Props (`FilterBar`):

- `onClear` (`() => void`) — Optional "clear all" handler; renders a trailing clear button.

#### Search input (`@engram/search-input`)

The search/filter query input shell — a leading magnifier, a clear button, and a `suggestions` dropdown slot revealed on focus.

- Install: `npx shadcn@latest add @engram/search-input`
- Registry item: /r/search-input.json
- Registry dependencies: @engram/cn, @engram/tokens

Props (`SearchInput`):

- `value` (`string`, required) — Current query text (controlled).
- `onValueChange` (`(value: string) => void`) — Fired on every keystroke with the new text.
- `onClear` (`() => void`) — Fired when the clear (×) button is pressed; falls back to onValueChange("").
- `suggestions` (`ReactNode`) — Suggestion/autocomplete content shown in a dropdown while focused. Engram renders the input shell and the panel; the consumer owns the query grammar and what goes in here.
- `className` (`string`)

#### Select (`@engram/select`)

A styled native select — a square FUI control with a chevron.

- Install: `npx shadcn@latest add @engram/select`
- Registry item: /r/select.json
- Registry dependencies: @engram/cn, @engram/tokens

Props (`Select`):

- `options` (`SelectOption[]`) — Options to render (alternative to passing <option> children).
- `children` (`ReactNode`)

#### Sheet (`@engram/sheet`)

A drawer/modal that slides from an edge — the mobile inspect backbone (bottom sheet) and side drawer.

- Install: `npx shadcn@latest add @engram/sheet`
- Registry item: /r/sheet.json
- Registry dependencies: @engram/cn, @engram/tokens

Props (`Sheet`):

- `open` (`boolean`, required)
- `onClose` (`() => void`, required)
- `side` (`SheetSide`, default `"bottom"`) — Edge the sheet slides from. Default bottom (the mobile inspect pattern).
- `children` (`ReactNode`, required)
- `label` (`string`) — Accessible label for the dialog.
- `className` (`string`)

#### Tab bar (`@engram/tab-bar`)

Horizontal tab strip with a bottom hairline (Destiny FUI director nav).

- Install: `npx shadcn@latest add @engram/tab-bar`
- Registry item: /r/tab-bar.json
- Registry dependencies: @engram/cn, @engram/tokens

#### Tooltip (`@engram/tooltip`)

The generic hover/focus tooltip — a small bubble of content anchored to a trigger.

- Install: `npx shadcn@latest add @engram/tooltip`
- Registry item: /r/tooltip.json
- Registry dependencies: @engram/cn, @engram/tokens

Props (`Tooltip`):

- `children` (`ReactNode`, required) — The trigger element.
- `content` (`ReactNode`, required) — Tooltip content (text or rich nodes).
- `placement` (`TooltipPlacement`, default `"top"`)
- `className` (`string`) — Class for the wrapper.
- `contentClassName` (`string`) — Class for the tooltip bubble.