# Engram

> 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](/r/cn.json): Tailwind-aware class-name merge (clsx + tailwind-merge). `@engram/cn`
- [Engram core](/r/core.json): Framework-neutral Bungie API → component-props mapping, image-ref resolver, enums, and types. Pure TypeScript, usable from any framework. `@engram/core`
- [Token utilities](/r/token-utils.json): Helpers that turn an @engram/core enum value (rarity, element, ammo, class) into its --engram-* CSS-variable reference. `@engram/token-utils`
- [usePanelTransition](/r/use-panel-transition.json): Hook coordinating a Destiny-style directional panel swap (fade + slide out, commit, fade + slide in) for routed views or local tab state. `@engram/use-panel-transition`

### Theme

- [Engram tokens](/r/tokens.json): Destiny FUI palette + rarity/element/class colors as CSS variables (--engram-*), with a Tailwind v4 theme layer. `@engram/tokens`

### Primitives

- [Bungie image](/r/bungie-image.json): Renders a Bungie image, resolving an ImageRef to a URL via @engram/core's configurable image base. `@engram/bungie-image`
- [Button](/r/button.json): A Destiny FUI button: flat, square, tracked-uppercase, with an offset outline ring that fades in on hover and a rhythmic fill pulse. `@engram/button`
- [Chip](/r/chip.json): 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). `@engram/chip`
- [Countdown](/r/countdown.json): A live countdown to a timestamp (vendor/weekly/event resets). `@engram/countdown`
- [Key hint](/r/key-hint.json): A keybind hint — the bordered key chip Destiny shows in nav bars and footers (`[A] Clan`, `[Esc] Dismiss`). `@engram/key-hint`
- [Progress ring](/r/progress-ring.json): A radial completion ring — the round counterpart to a progress bar, for node completion, character level, and compact stat readouts. `@engram/progress-ring`
- [Segmented bar](/r/segmented-bar.json): A segmented progress/stat bar in the Destiny FUI style. `@engram/segmented-bar`

### Layout

- [Band](/r/band.json): 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. `@engram/band`
- [Paged grid](/r/paged-grid.json): 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. `@engram/paged-grid`
- [Panel](/r/panel.json): A Destiny FUI surface: a semi-transparent panel over the canvas, defined by its fill (no outline). `@engram/panel`
- [Title bar](/r/title-bar.json): 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. `@engram/title-bar`

### Icons

- [Ammo icon](/r/ammo-icon.json): Ammo type glyph (primary/special/heavy) in the ammo's token color. `@engram/ammo-icon`
- [Breaker icon](/r/breaker-icon.json): Champion breaker glyph (the real Bungie icon), tinted to currentColor. `@engram/breaker-icon`
- [Class icon](/r/class-icon.json): The Guardian class mark (Titan / Hunter / Warlock), tinted in the class identity color with a soft glow. `@engram/class-icon`
- [Element icon](/r/element-icon.json): The damage element as its real Destiny glyph, masked and tinted in the element color with a soft glow. `@engram/element-icon`
- [Game icon](/r/game-icon.json): The one keyed icon for Destiny's small glyphs — elements, ammo, classes, breakers, weapon silhouettes, activities, currencies, factions: `<GameIcon name="raid" />`. `@engram/game-icon`
- [Weapon icon](/r/weapon-icon.json): 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. `@engram/weapon-icon`

### Items

- [Cost chip](/r/cost-chip.json): A currency/cost token: an amount + its currency icon. Used for vendor costs, build/material requirements, and rewards. `@engram/cost-chip`
- [Item grid](/r/item-grid.json): The fundamental inventory/collection container: a CSS grid that lays out item tiles (passed as `children`). `@engram/item-grid`
- [Item hover card](/r/item-hover-card.json): Reveals an inspect popup for the trigger (e.g. an ItemTile / gear slot) — the in-game "hover gear to inspect" flyout. `@engram/item-hover-card`
- [Item image](/r/item-image.json): 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). `@engram/item-image`
- [Item popup](/r/item-popup.json): 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). `@engram/item-popup`
- [Item popup header](/r/item-popup-header.json): 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. `@engram/item-popup-header`
- [Item stats](/r/item-stats.json): The Destiny stat block: an aligned grid of right-labeled stat rows. `@engram/item-stats`
- [Item tile](/r/item-tile.json): A full item tile: the layered ItemImage with a bottom element+power foot, and the signature Destiny white outline on hover. `@engram/item-tile`
- [Power badge](/r/power-badge.json): The power/light readout: the angular power glyph + the value in gold, with an optional `cap`. `@engram/power-badge`
- [Rarity gem](/r/rarity-gem.json): A small diamond gem in the rarity's token color. `@engram/rarity-gem`
- [Tier watermark](/r/tier-watermark.json): 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. `@engram/tier-watermark`

### Sockets & perks

- [Perk popup](/r/perk-popup.json): The weapon-perk inspect flyout — the in-game trait tooltip, the weapon counterpart to ModPopup. `@engram/perk-popup`
- [Plug](/r/plug.json): 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. `@engram/plug`
- [Plug badge](/r/plug-badge.json): Default rendering of a PlugAnnotation as a small plug overlay: a tier chip, a custom icon, or a gold recommended marker. `@engram/plug-badge`
- [Plug picker](/r/plug-picker.json): A grid of selectable plugs — the picker body for swapping a mod, perk, aspect, or fragment. `@engram/plug-picker`
- [Socket](/r/socket.json): One socket: a perk column (stacked circles) or a mod socket (squares). `@engram/socket`
- [Socket grid](/r/socket-grid.json): 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. `@engram/socket-grid`

### Loadout

- [Ability slot](/r/ability-slot.json): A single subclass/loadout socket — an ability, aspect, fragment, super, or class ability. `@engram/ability-slot`
- [Artifact perk](/r/artifact-perk.json): 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. `@engram/artifact-perk`
- [Energy meter](/r/energy-meter.json): 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. `@engram/energy-meter`
- [Loadout card](/r/loadout-card.json): A compact build summary: the subclass diamond + name, the equipped item tiles, an optional mod row, the stat tiers, and an action footer. `@engram/loadout-card`
- [Mod popup](/r/mod-popup.json): The armor-mod inspect flyout — the in-game mod tooltip, the mod counterpart to PlugPopup. `@engram/mod-popup`
- [Mod slot](/r/mod-slot.json): One armor mod socket: a square plug with its energy-cost pip in the corner, or an empty "+" placeholder. `@engram/mod-slot`
- [Mod tray](/r/mod-tray.json): 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`. `@engram/mod-tray`
- [Plug popup](/r/plug-popup.json): The subclass-plug inspect flyout — the in-game tooltip for abilities, aspects, fragments, supers, and subclasses, the counterpart to ItemPopup for non-gear plugs. `@engram/plug-popup`
- [Slot row](/r/slot-row.json): 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. `@engram/slot-row`
- [Subclass diamond](/r/subclass-diamond.json): 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. `@engram/subclass-diamond`

### Identity & nameplates

- [Character tile](/r/character-tile.json): The character column header — a Nameplate whose headline defaults to the Guardian's class. `@engram/character-tile`
- [Emblem banner](/r/emblem-banner.json): 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. `@engram/emblem-banner`
- [Nameplate](/r/nameplate.json): 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. `@engram/nameplate`
- [Player card](/r/player-card.json): An identity card. The default is a compact tile (square emblem + name + class + rank + stats) for search results and fireteam lists. `@engram/player-card`

### Stats

- [Character stats](/r/character-stats.json): 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). `@engram/character-stats`
- [Stat bar](/r/stat-bar.json): A labeled stat row: name, segmented bar, and value (Destiny stat block). `@engram/stat-bar`
- [Stat card](/r/stat-card.json): A KPI tile: a small label, a big headline value, and an optional period delta (green up / red down). `@engram/stat-card`
- [Stat card grid](/r/stat-card-grid.json): A responsive grid of StatCards with an optional `tabs` slot above for a time-span switch (Daily / Weekly / All-time). `@engram/stat-card-grid`
- [Stat popup](/r/stat-popup.json): 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. `@engram/stat-popup`
- [Stat priority list](/r/stat-priority-list.json): A drag-to-reorder priority list — the stat-priority picker for a build optimizer (drag Resilience above Recovery). `@engram/stat-priority-list`
- [Stat range slider](/r/stat-range-slider.json): A dual-thumb min/max range slider with optional tier ticks — the stat filter for a build optimizer ("Resilience ≥ 60", "Mobility 30–70"). `@engram/stat-range-slider`

### Inventory

- [Bucket column](/r/bucket-column.json): A single inventory bucket: a collapsible labeled header with a capacity counter, an optional equipped slot, and the stored items in an ItemGrid. `@engram/bucket-column`
- [Currency bar](/r/currency-bar.json): 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. `@engram/currency-bar`

### Triumphs

- [Objective progress](/r/objective-progress.json): One objective's progress — the polymorphic readout behind triumphs, quests, bounties, metrics, crafting levels, kill trackers, and deepsight bars. `@engram/objective-progress`
- [Record card](/r/record-card.json): 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. `@engram/record-card`

### Quests

- [Pursuit card](/r/pursuit-card.json): 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. `@engram/pursuit-card`

### Tables

- [Compare cell](/r/compare-cell.json): A stat cell for comparison tables: the value with a thin bar, colored by its `rank` (best = ok/green, worst = bad/red, mid = neutral). `@engram/compare-cell`
- [Data table](/r/data-table.json): The generic data table behind compare, organizer, scoreboards, and leaderboards. `@engram/data-table`

### Crucible

- [Kill tracker](/r/kill-tracker.json): A masterwork/memento kill-tracker readout: a label on the left and the count tucked to the right, with an optional tracker icon. `@engram/kill-tracker`
- [Roll verdict](/r/roll-verdict.json): A curated-roll verdict badge, colored by the status palette. `@engram/roll-verdict`

### Interaction

- [Collapsible section](/r/collapsible-section.json): A titled disclosure: a tracked-uppercase header (with an optional count) that toggles its content. `@engram/collapsible-section`
- [Dnd](/r/dnd.json): A generic drag source: makes its `children` draggable and exposes an opaque `data` payload to drop targets. `@engram/dnd`
- [Filter bar](/r/filter-bar.json): A wrapping row of FilterPills — the active-filters strip above an inventory/collection grid. `@engram/filter-bar`
- [Search input](/r/search-input.json): The search/filter query input shell — a leading magnifier, a clear button, and a `suggestions` dropdown slot revealed on focus. `@engram/search-input`
- [Select](/r/select.json): A styled native select — a square FUI control with a chevron. `@engram/select`
- [Sheet](/r/sheet.json): A drawer/modal that slides from an edge — the mobile inspect backbone (bottom sheet) and side drawer. `@engram/sheet`
- [Tab bar](/r/tab-bar.json): Horizontal tab strip with a bottom hairline (Destiny FUI director nav). `@engram/tab-bar`
- [Tooltip](/r/tooltip.json): The generic hover/focus tooltip — a small bubble of content anchored to a trigger. `@engram/tooltip`

Full per-component API reference: /llms-full.txt