# ns-ui — AI-agent quickstart

ns-ui is a personal React/Next.js component registry: 50 self-contained,
dependency-light components (a Geist-dark "core" set + a deliberately flashy "loud" set).
Every component installs as plain source you own — no runtime package, no MCP server.

Install directly, zero config:
  npx shadcn add https://design.helpmarq.com/r/<name>.json

This drops component.tsx into your project (components/ui/<name>.tsx) and pulls its npm
deps via shadcn. No account, no API key.

Requirements before you use any of these:
- Colors MUST come from CSS custom properties already in scope: --background --foreground
  --muted --border --accent. Never hardcode hex — these components are light/dark
  theme-reactive only if those tokens exist in the host app's globals.css.
- Peer deps: react 19+, Tailwind CSS v4 (components are styled entirely with Tailwind
  utility classes — no shipped CSS file). Fonts assumed Geist Sans / Geist Mono (components
  inherit font-family, they don't set it). Per-component npm deps listed below as "deps".

Full behavioral detail (long form, one paragraph per component): https://design.helpmarq.com/llms-full.txt

Each block below:
  ## <name>  [collection]
  <title> — <one-line purpose>
  use when: <selection guidance — the problem it solves, not a restatement of the title>
  props: <condensed public prop signature: name, type, optionality, default, purpose>
  deps: <npm dependencies beyond react>
  install: npx shadcn add https://design.helpmarq.com/r/<name>.json

## ascii-dither-media  [core]
ASCII Dither Media — Luminance-to-glyph canvas renderer: ASCII, Bayer-dither, and dot-matrix modes w…
use when: a background/ambient layer (ascii, dither, canvas).
props:
  mode?: Mode = "ascii"
  src?: string
  cellSize?: number = 14
  cursorRadius?: number = 140
  className?: string
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/ascii-dither-media.json

## cardio-baseline  [core]
Cardio Baseline — Text whose baseline is a live EKG trace: each beat fires a QRS spike that trave…
use when: text with a live EKG baseline — each beat's QRS spike throws every glyph up the waveform before it spring-settles flat, firable imperatively via a ref for real events (deploys, messages); use for a heartbeat/pulse motif, not a generic reveal.
props:
  children?: string = "SYSTEMS NOMINAL"
  bpm?: number = 50
  className?: string
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/cardio-baseline.json

## caustic-coverflow  [core]
Caustic Coverflow — 3D coverflow gallery whose frosted-glass cards run a live caustic-light simulat…
use when: a gallery (coverflow, 3d, canvas).
props:
  items?: CausticCoverflowItem[] = DEFAULT_ITEMS
  initialIndex?: number
  cardWidth?: number = 264
  cardHeight?: number = 330
  className?: string
  aria-label?: string = "Coverflow gallery"
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/caustic-coverflow.json

## caustic-select  [core]
Caustic Select — Single-select whose frosted-glass trigger and listbox sit over drifting caustic…
use when: a select control (listbox, form, canvas).
props:
  options?: CausticSelectOption[] = DEFAULT_OPTIONS
  value?: string
  defaultValue?: string
  onValueChange?: (value: string) => void
  label?: string = "Region"
  placeholder?: string = "Select a region"
  disabled?: boolean = false
  name?: string
  className?: string
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/caustic-select.json

## chronicle-bar  [core]
Chronicle Bar — Determinate progress bar whose leading edge narrates each phase in typed mono,…
use when: a progress indicator (loader, typography, mono).
props:
  value?: number = 0
  phases?: ChroniclePhase[] = DEFAULT_PHASES
  className?: string
  aria-label?: string = "Progress"
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/chronicle-bar.json

## cipher-reel-otp  [core]
Cipher Reel OTP — 6-box code entry where each box is a tiny slot-machine cipher reel: keystrokes…
use when: an OTP/verification-code input (input, form, canvas).
props:
  length?: number = 6
  label?: string = "Verification code"
  helperText?: string
  error?: boolean = false
  errorMessage?: string = "That code didn't m…
  disabled?: boolean = false
  autoFocus?: boolean = false
  onChange?: (code: string) => void
  onComplete?: (code: string) => void
  className?: string
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/cipher-reel-otp.json

## counterpoise-tiers  [core]
Counterpoise Tiers — Pricing section rendered as a literal balance scale: two tier cards hang as pan…
use when: a pricing table (canvas, physics, spring).
props:
  left?: CounterpoiseTier = STARTER
  right?: CounterpoiseTier = PRO
  annualMultiplier?: number = 0.8
  className?: string
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/counterpoise-tiers.json

## crack-compare  [core]
Crack Compare — Before/after comparison slider whose divider is a living Voronoi crack seam — f…
use when: a comparison view (slider, before after, voronoi).
props:
  before?: ReactNode = <div className="h-f…
  after?: ReactNode = <div className="h-f…
  initial?: number = 0.5
  seedCount?: number = 140
  jag?: number = 18
  spawnVelocity?: number = 600
  label?: string = "Comparison positio…
  onChange?: (value: number) => void
  className?: string
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/crack-compare.json

## decrypt-text  [core]
Decrypt Text — Scramble-to-decode text reveal with left-to-right character locking.
use when: the classic scramble-to-decode reveal — monospace glyphs churn and lock into the final string left to right; use for a one-shot on-mount/on-trigger reveal, not a persistent cursor-driven effect.
props:
  text: string
  delay?: number = 150
  stagger?: number = 55
  ambient?: number = 0
  className?: string
  replayKey?: number = 0
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/decrypt-text.json

## drape-menu  [core]
Drape Menu — Dropdown whose panel is a live verlet cloth pinned to the trigger — it falls an…
use when: a menu (dropdown, cloth, physics).
props:
  label?: string = "Workspace"
  items?: DrapeMenuItem[] = DEFAULT_ITEMS
  onSelect?: (id: string) => void
  minWidth?: number = 264
  className?: string
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/drape-menu.json

## dynamic-weight-text  [core]
Dynamic Weight Text — Letters morph variable-font weight by cursor proximity — pure typography intera…
use when: letters continuously morph variable-font weight by cursor proximity — pure typography, no particles/canvas/color, no discrete reveal moment; use for an ambient, subtle hover-driven headline.
props:
  text: string
  minWeight?: number = 300
  maxWeight?: number = 800
  sigma?: number = 90
  className?: string
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/dynamic-weight-text.json

## fling-segment  [core]
Fling Segment — Segmented control with a visibly grabbable pill (grip dots, hover lift) — fling…
use when: an interactive control (form, segmented, physics).
props:
  options?: FlingSegmentOption[] = DEFAULT_OPTIONS
  value?: string
  defaultValue?: string
  onValueChange?: (value: string) => void
  introFling?: boolean = false
  className?: string
  aria-label?: string = "View"
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/fling-segment.json

## flock-stack  [core]
Flock Stack — Avatar stack that mills as a live boids flock and resolves into the classic ove…
use when: an avatar (boids, physics, hover).
props:
  members?: FlockMember[] = DEFAULT_MEMBERS
  overflow?: number = 3
  avatarSize?: number = 28
  className?: string = "h-[120px]"
  aria-label?: string
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/flock-stack.json

## frostbite-switch  [core]
Frostbite Switch — iOS-style switch whose OFF state freezes over: seeded dendritic frost feathers…
use when: a toggle switch (toggle, canvas, particles).
props:
  checked?: boolean
  defaultChecked?: boolean = false
  onCheckedChange?: (checked: boolean) => void
  disabled?: boolean = false
  className?: string
  aria-label?: string = "Toggle"
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/frostbite-switch.json

## glass-button  [core]
Glass Button — Liquid-glass button with translucent blurred surface and press states.
use when: the default general-purpose button — translucent liquid-glass surface with hover lift and press states; use for any ordinary CTA, not a destructive action needing deliberate confirmation.
props: (extends ButtonHTMLAttributes<HTMLButtonElement>)
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/glass-button.json

## glass-panel  [core]
Glass Panel — Container-level liquid glass: blur, saturation, noise grain, specular rim, grad…
use when: a card (surface, glass, container).
props: (extends HTMLAttributes<HTMLDivElement>)
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/glass-panel.json

## heatwave-ledger  [core]
Heatwave Ledger — Dense ops table where rows above a heat threshold shimmer like air over asphalt…
use when: a table (data viz, svg filter, displacement).
props:
  rows?: LedgerRow[] = DEFAULT_ROWS
  threshold?: number = 70
  title?: string = "Server load — last…
  timestamp?: string = "updated 09:41:07 U…
  className?: string
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/heatwave-ledger.json

## hold-to-confirm  [core]
Hold to Confirm — Press-and-hold destructive action — monochrome ink pours up from the press poin…
use when: a press-and-hold DESTRUCTIVE confirm — ink pours up from the press point and recoils if released early; use whenever an action needs deliberate hold-to-confirm, not a plain single-tap button.
props:
  children: ReactNode
  confirmedLabel?: ReactNode = "Done"
  holdMs?: number = 1200
  onConfirm?: () => void
  className?: string
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/hold-to-confirm.json

## ligature-melt  [core]
Ligature Melt — Headline whose glyphs liquefy near the cursor — an SVG gooey filter fuses neigh…
use when: glyphs liquefy and fuse into gooey ligatures near the cursor via an SVG filter, drifting even at rest and springing apart on leave; use for a squishy, organic headline, not a legibility-first reveal.
props:
  text?: string = "SURFACE TENSION"
  sigma?: number = 70
  swell?: number = 0.35
  pull?: number = 6
  blur?: number = 6
  className?: string
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/ligature-melt.json

## lodestone-hero  [core]
Lodestone Hero — Full-bleed hero where the headline exists twice: crisp DOM type above, and bene…
use when: a hero whose headline exists twice — crisp DOM type over a Canvas 2D field of iron-filing strokes that bend toward the cursor and snap toward the CTA on hover; zero deps, best when the headline itself should feel physically alive.
props:
  eyebrow?: string = "FIELD-ALIGNED INFR…
  headlineLines?: string[] = ["Every signal bend…
  subcopy?: string = "Lodestone routes t…
  primaryCta?: { label: string; href: string } = { label: "Deploy th…
  secondaryCta?: { label: string; href: string } = { label: "Read the…
  stats?: { value: string; label: string }[] = [ { value: "12ms",…
  maskFilings?: number = 1800
  ambientFilings?: number = 600
  className?: string
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/lodestone-hero.json

## loupe-slider  [core]
Loupe Slider — Slider read through a circular magnifying loupe riding the thumb: the tick bene…
use when: a slider read through a circular magnifying loupe that rides the thumb, sharpening the tick beneath it while the rest of the scale stays soft-focus; use for precise value-reading (audio scrub, zoom level), not a destructive confirm gesture.
props:
  value?: number
  defaultValue?: number = 50
  min?: number = 0
  max?: number = 100
  step?: number = 1
  tickStep?: number
  majorEvery?: number = 5
  formatLabel?: (v: number) => string
  formatValue?: (v: number) => string
  onValueChange?: (v: number) => void
  className?: string
  aria-label?: string = "Value"
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/loupe-slider.json

## magnetic-dock  [core]
Magnetic Dock — Cursor-proximity magnification row with Gaussian falloff — macOS-dock physics f…
use when: a macOS-dock-style row that magnifies items under cursor proximity with Gaussian falloff; use for an icon/action dock or nav row, not for showing scroll/read position through a document.
props:
  children: ReactNode
  gain?: number = 0.55
  sigma?: number = 80
  lift?: number = 16
  className?: string
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/magnetic-dock.json

## mercury-minimap  [core]
Mercury Minimap — TOC minimap where scroll progress is a column of liquid mercury — a gooey SVG b…
use when: a scroll-position TOC/minimap where a gooey mercury blob climbs a rail and absorbs section ticks as you scroll; use to show progress through a long document, not for magnifying items in an icon row.
props:
  sections?: MinimapSection[]
  selector?: string = "section[id]"
  offset?: number = 0.35
  stiffness?: number = 120
  damping?: number = 20
  className?: string
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/mercury-minimap.json

## moire-dial  [core]
Moire Dial — Weighted rotary knob tuned like a radio: counter-rotating line gratings shimmer…
use when: a rotary value dial (canvas, moire, knob).
props:
  message?: string = "SIGNAL"
  pitch?: number = 6
  gear?: number = 0.15
  initialAngle?: number = -132
  friction?: number = 3.5
  fieldHeight?: number = 224
  className?: string
  aria-label?: string = "Moire tuning dial"
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/moire-dial.json

## needle-stepper  [core]
Needle Stepper — Bounded numeric stepper with a large mono value readout, prominent -/+ buttons,…
use when: a numeric stepper (spinbutton, input, canvas).
props:
  value?: number
  defaultValue?: number = 20
  min?: number = 0
  max?: number = 100
  step?: number = 1
  label?: string = "Value"
  unit?: string
  onValueChange?: (value: number) => void
  disabled?: boolean = false
  className?: string
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/needle-stepper.json

## particle-hero  [core]
Particle Hero — Full-viewport hero with a cursor-reactive WebGL particle field and staggered te…
use when: a hero with a real WebGL particle field the cursor repels — an elastic void that trails the pointer — plus staggered text reveal; the only hero in this set with npm deps (three, @react-three/fiber, motion), so pick it when true GPU depth is worth the heavier install.
props:
  eyebrow?: string = "ns-ui"
  headline?: string = "Interfaces with gr…
  subline?: string = "A registry of comp…
  cta?: string = "Browse components"
  ctaHref?: string
  onCtaClick?: () => void
deps: three, @react-three/fiber, motion
install: npx shadcn add https://design.helpmarq.com/r/particle-hero.json

## particle-tunnel-scrub  [core]
Particle Tunnel Scrub — Scroll scrubs a camera through a monochrome point tunnel — velocity stretches d…
use when: scroll flies a camera through a 3D particle tunnel with velocity-streaked dots and mono labels snapping into focus at fixed depths; use for a flythrough narrative, not a content-crossfade story or an instrument/HUD readout.
props:
  labels?: string[] = ["01 SIGNAL", "02 N…
  pointCount?: number = 3000
  className?: string
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/particle-tunnel-scrub.json

## respire-field  [core]
Respire Field — Text input whose focus ring is a living membrane: a noise-displaced canvas loop…
use when: a general-purpose text input whose focus ring is a breathing membrane that pulses per keystroke and constricts on error; use for any field needing organic focus/validation feedback, not specifically passwords.
props:
  error?: boolean = false
  exhaleKey?: number = 0
  className?: string
  (extends Omit<InputHTMLAttributes<HTMLInputElement>, "className">)
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/respire-field.json

## ripple-unfold  [core]
Ripple Unfold — Media reveal driven by a height-field water sim: a ripple front sweeps from the…
use when: media display (canvas, reveal, wave sim).
props:
  src?: string
  tileSize?: number = 32
  threshold?: number = 0.12
  refraction?: number = 6
  impulse?: number = 0.35
  className?: string = "aspect-[16/10]"
  aria-label?: string = "Media revealed by…
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/ripple-unfold.json

## rule-sparkline  [core]
Rule Sparkline — Inline KPI sparkline grown over an elementary cellular-automaton texture — the…
use when: a sparkline (canvas, data viz, cellular automaton).
props:
  data?: number[] = DEFAULT_DATA
  cellSize?: number = 3
  entranceMs?: number = 900
  strokeWidth?: number = 1.5
  formatValue?: (value: number, index: number) => string = defaultFormat
  className?: string = "h-14"
  aria-label?: string = "KPI sparkline"
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/rule-sparkline.json

## scan-sweep-stats  [core]
Scan Sweep Stats — Dashboard KPI grid under an observatory radar: a 1px accent arm sweeps the pane…
use when: a KPI stat tile (canvas, radar, sweep).
props:
  stats?: ScanStat[] = DEFAULT_STATS
  title?: string = "Network observator…
  degPerSec?: number = 30
  wedgeDeg?: number = 24
  toleranceDeg?: number = 2
  className?: string
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/scan-sweep-stats.json

## scroll-caliper  [core]
Scroll Caliper — A vernier caliper pinned to a scroll container's edge whose spring-damped jaws…
use when: a vernier-caliper HUD pinned to a scroll container's edge that measures the active section with a live px/percent readout; use as a scroll-position instrument, not a narrative or a 3D flythrough.
props:
  children?: ReactNode
  sectionSelector?: string = "[data-section]"
  jawStiffness?: number = 120
  jawDamping?: number = 0.9
  needleStiffness?: number = 90
  needleDamping?: number = 0.55
  className?: string = "h-[480px]"
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/scroll-caliper.json

## sediment-stack  [core]
Sediment Stack — Toast stack with real gravity — notifications thud into a jostling heap, errors…
use when: a toast/notification stack (notification, physics, gravity).
props:
  duration?: number = 6000
  gravity?: number = 1800
  restitution?: number = 0.15
  initial?: SedimentToastInput[]
  className?: string = "h-96"
  aria-label?: string = "Notifications"
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/sediment-stack.json

## signal-terrain  [core]
Signal Terrain — Unknown-Pleasures ridgeline chart whose live history recedes into scrolling amb…
use when: an Unknown-Pleasures ridgeline chart where live history recedes into scrolling noise terrain, dented by the cursor; use for a live/ambient data feed with a generative-landscape feel, not when trend direction is the point.
props:
  series?: number[] = EMPTY
  cols?: number = 96
  rows?: number = 40
  ambientAmplitude?: number = 18
  dataAmplitude?: number = 68
  glideMs?: number = 600
  dentSigma?: number = 90
  dentDepth?: number = 26
  className?: string = "h-96"
  aria-label?: string = "Live signal terrai…
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/signal-terrain.json

## slide-to-shatter  [core]
Slide to Shatter — Frosted-glass confirm slider where drag distance drives Voronoi crack density —…
use when: a frosted-glass CONFIRM slider — drag distance grows Voronoi cracks that heal if you stop early, and shatter into glass shards on full travel; use for a destructive confirm action, not a plain value-reading input.
props:
  label?: string = "SLIDE TO CONFIRM"
  confirmedLabel?: string = "CONFIRMED"
  width?: number = 320
  height?: number = 56
  shardCount?: number = 48
  onConfirm?: () => void
  resetKey?: number = 0
  className?: string
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/slide-to-shatter.json

## solargraph-hero  [core]
Solargraph Hero — Hero card whose canvas behaves like a long-exposure photograph: cursor movement…
use when: a hero whose canvas behaves like a long-exposure photograph — cursor movement burns light trails that persist and decay over ~4s, building an ambient light-painting rather than reacting live; zero deps, best for a quieter, card-style hero.
props:
  children?: ReactNode
  halfLifeMs?: number = 4000
  maxStrokeAlpha?: number = 0.35
  intro?: boolean = true
  className?: string
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/solargraph-hero.json

## strandline  [core]
Strandline — Changelog timeline drawn as a beach strand: each release arrives as a foam cres…
use when: a timeline (canvas, changelog, wave).
props:
  events?: StrandlineEvent[] = DEFAULT_EVENTS
  autoplay?: number = 3
  className?: string = "h-80"
  aria-label?: string = "Release timeline s…
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/strandline.json

## terminator-date-field  [core]
Terminator Date Field — Masked date input whose popover calendar doubles as a moon-phase almanac: every…
use when: a date picker (input, calendar, canvas).
props:
  value?: Date | null
  defaultValue?: Date | null = null
  onValueChange?: (date: Date) => void
  label?: string = "Date"
  disabled?: boolean = false
  className?: string
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/terminator-date-field.json

## tide-gauge-password  [core]
Tide Gauge Password — Password field with a canvas water tank behind the masked text: entropy raises…
use when: a password field specifically — a canvas water tank behind the masked text where entropy raises the tide and keystrokes slosh a real wave; use when strength itself should be legible, not for general text input.
props:
  label?: string = "Password"
  name?: string = "password"
  placeholder?: string
  defaultValue?: string
  value?: string
  onValueChange?: (value: string) => void
  autoComplete?: string = "new-password"
  required?: boolean = false
  disabled?: boolean = false
  className?: string
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/tide-gauge-password.json

## updraft-dropzone  [core]
Updraft Dropzone — File dropzone as a thermal field: dragging spawns rising accent convection wisp…
use when: a drag-and-drop upload zone (file upload, form, canvas).
props:
  defaultFiles?: { name: string; size: number; type: string }[] = []
  accept?: string[] = []
  maxSizeBytes?: number = 8 * 1024 * 1024
  onFilesChange?: (files: UpdraftFile[]) => void
  className?: string
  aria-label?: string = "Upload files"
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/updraft-dropzone.json

## vapor-countdown  [core]
Vapor Countdown — Live countdown where each digit change is a phase transition: the outgoing digi…
use when: a countdown timer (canvas, particles, typography).
props:
  targetDate?: Date | string | number
  labels?: readonly [string, string, string] | null = DEFAULT_LABELS
  className?: string
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/vapor-countdown.json

## warp-lattice  [core]
Warp Lattice — Card grid on a magnetized hairline lattice — the cursor bends the grid lines an…
use when: cards (canvas, grid, cursor).
props:
  labels?: string[] = DEFAULT_LABELS
  cell?: number = 32
  sampleStep?: number = 8
  sigma?: number = 140
  peakBend?: number = 22
  cursorLerp?: number = 0.14
  className?: string = "min-h-[520px]"
  aria-label?: string = "Card grid on a cur…
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/warp-lattice.json

## aurora-flow-chart  [loud]
Aurora Flow Chart — Area chart whose fill is a live aurora curtain — series values drive curtain he…
use when: an area chart whose fill is a live aurora curtain — height tracks values, hue tracks trend direction (cool falling, warm rising); use when trend direction itself is the story and you need a real tooltip/axis, not an ambient backdrop.
props:
  data?: AuroraPoint[] = DEFAULT_DATA
  height?: number = 300
  yTicks?: number = 4
  glideMs?: number = 600
  formatValue?: (v: number) => string = defaultFormat
  showLegend?: boolean = true
  className?: string
  aria-label?: string = "Aurora flow chart"
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/aurora-flow-chart.json

## core-sample-scroll  [loud]
Core Sample Scroll — Pinned scroll story — the viewport becomes a geological core cross-section and…
use when: a pinned scroll story where the viewport becomes a geological core sample and a drill bit descends through strata as DOM content panels crossfade per band; use for a long-form narrative with distinct content sections, not an abstract flythrough or a real-image reveal.
props:
  bands?: CoreSampleBand[] = DEFAULT_BANDS
  totalDepth?: number = 128
  trackVh?: number = 250
  className?: string
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/core-sample-scroll.json

## erosion-trail  [loud]
Erosion Trail — The cursor is a river — dragging across a live topographic map carves a channel…
use when: a generative terrain surface (topographic, cursor, canvas).
props:
  gridSize?: number = 96
  contourStep?: number = 0.08
  brushSigma?: number = 28
  carveRate?: number = 0.9
  healTau?: number = 2.2
  showReadout?: boolean = true
  className?: string = "h-96"
  aria-label?: string = "Topographic map —…
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/erosion-trail.json

## event-horizon-command  [loud]
Event Horizon Command — Cmd-K palette where fuzzy-match results orbit the input as label pills — orbita…
use when: a command palette (cmd k, orbit, physics).
props:
  commands?: CommandItem[] = DEFAULT_COMMANDS
  placeholder?: string = "Type a command"
  defaultOpen?: boolean = true
  closeOnSelect?: boolean = false
  onSelect?: (item: CommandItem) => void
  onOpenChange?: (open: boolean) => void
  autoTypeQuery?: string
  autoTypeLoopMs?: number = 6000
  className?: string = "h-[560px]"
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/event-horizon-command.json

## frost-scrub  [loud]
Frost Scrub — Scroll-scrubbed defroster — a pinned full-bleed image behind rippled shower gla…
use when: a pinned scroll-scrubbed WebGL shader that anneals a full-bleed image from frosted shower glass to clarity as you scroll; use to reveal a real photo/image, not an abstract or generative scene.
props:
  src?: string
  alt?: string = "Image annealing fr…
  caption?: string = "SCROLL TO ANNEAL"
  maxOffset?: number = 42
  frostRadius?: number = 10
  dispersion?: number = 0.012
  className?: string
  onProgress?: (p: number) => void
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/frost-scrub.json

## knockout-404  [loud]
Knockout 404 — 404 numerals rendered as literal absence — destination-out punches the glyphs t…
use when: a 404/error page (typography, negative space, canvas).
props:
  glyph?: string = "404"
  message?: string = "This page drifted…
  primaryLabel?: string = "Take me home"
  primaryHref?: string = "/"
  secondaryLabel?: string = "Contact support"
  secondaryHref?: string = "#support"
  className?: string
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/knockout-404.json

## prism-drag-split  [loud]
Prism Drag Split — A frosted prism strip rides the cursor across a headline, magnifying the text b…
use when: a frosted prism strip rides the cursor across a headline, magnifying it and tearing it into velocity-driven RGB channel slices that snap back with overshoot; use for a glitchy, chromatic-aberration headline moment, not a soft/organic one.
props:
  text?: string = "REFRACTION"
  stripWidth?: number = 120
  stiffness?: number = 300
  damping?: number = 24
  mass?: number = 1
  dispersionGain?: number = 0.018
  maxDispersion?: number = 14
  magnify?: number = 1.06
  className?: string
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/prism-drag-split.json

## singularity-text  [loud]
Singularity Text — Headline as a monochrome particle cloud — the cursor is a gravity well that eat…
use when: a hero built from ONLY a headline, no surrounding CTA/copy layout — rendered as a particle cloud the cursor pulls into an orbiting accretion ring and releases to spring back into type; zero deps, use when the headline alone should be the whole scene.
props:
  text?: string = "SINGULARITY"
  gravity?: number = 4_000_000
  captureRadius?: number = 180
  springK?: number = 90
  damping?: number = 0.55
  className?: string
deps: (none)
install: npx shadcn add https://design.helpmarq.com/r/singularity-text.json