crd-ui: Instructions file for Codex

Agent guide for crd-ui

crd-ui is a framework-agnostic credit/debit card visualization library: a zero-dependency vanilla core with React, Vue and Svelte adapters published as subpaths of a single npm package. Library docs in markdown: https://crd-ui.juanda.co/llms-full.txt (also in packages/crd-ui/llms.txt).

Monorepo map (pnpm workspaces)

• packages/crd-ui — the published package.
  • src/brands.ts / src/format.ts — brand detection and number/expiry/cvc formatting.
  • src/card.ts — the core renderer (createCard): owns the DOM, flip choreography, magic focus ring, variant classes.
  • src/react.tsx, src/vue.ts, src/svelte/Card.svelte — framework adapters.
  • styles/crd-ui.css — all visuals: brand themes, variants, animations.
  • tests/ — Vitest (jsdom). Svelte tests use the .svelte.test.ts suffix (runes).
• website/ — Astro one-pager (crd-ui.juanda.co). Deploys to Vercel on push to main.
  • src/lib/snippets.ts + src/lib/api.ts — single source of truth for docs: both the HTML page and /llms-full.txt (src/lib/docs-md.ts) render from them.
• examples/playground — Vite+React dev playground.
• starters/react-checkout (Vite, opened from StackBlitz) and starters/nextjs-checkout (App Router, local use only — Next.js doesn't render inside StackBlitz) — standalone checkout starters sharing the same form. Outside the pnpm workspace on purpose: they install crd-ui from npm like a real user would. Bump their crd-ui range after a breaking release, and keep the two forms in sync.

Commands

pnpm install
pnpm test                    # vitest for packages/crd-ui (59+ tests)
pnpm build                   # tsup: ESM+CJS+d.ts, plus dist/svelte copy
pnpm --filter website dev    # docs site on :4321
pnpm --filter website build

This machine uses pnpm only (npm is disabled and forwards to pnpm).

Architecture rules

• The core owns the DOM. Adapters are thin controlled wrappers: render an empty container, createCard on mount, forward props with card.update(), destroy() on unmount. Never manipulate card internals from an adapter.
• placeholders, locale and logos are creation-time options — not updatable.
• The Svelte adapter ships as source (dist/svelte/Card.svelte with handwritten index.d.ts); its import of the core is relative and extensionless on purpose so it resolves both from src/ (tests) and dist/.
• React/Vue/Svelte are optional peerDependencies — the core must keep zero runtime dependencies.