Skip to content

AGENTS.md

Latest commit

 

History

History
109 lines (83 loc) · 6.16 KB

AGENTS.md

File metadata and controls

109 lines (83 loc) · 6.16 KB

Repository Guidelines

Project Structure & Module Organization

  • src/ holds the library source. Public exports are in src/index.ts and the main module lives in src/Mnemonic/ (provider.tsx, use.ts, codecs.ts, types.ts, json-schema.ts, schema.ts).
  • Build outputs are emitted to dist/ (published via package.json files). Rebuild dist/ after source changes (npm run build) before consumers can see them.
  • Configuration lives at the repo root: tsconfig.json, tsup.config.ts, vitest.config.ts, vitest.setup.ts.
  • website/ contains the Docusaurus documentation site with its own package.json. API reference is auto-generated from TypeDoc. Deployed to GitHub Pages via .github/workflows/deploy-docs.yml.
  • README.md contains the public usage example.

Build, Test, and Development Commands

  • npm run build builds the package with tsup into dist/.
  • npm run dev runs tsup --watch for continuous builds.
  • npm run test runs the Vitest test suite once.
  • npm run test:watch runs Vitest in watch mode.
  • npm run lint runs TypeScript type-checking with tsc --noEmit.
  • npm run format formats all files with Prettier.
  • npm run format:check checks formatting without writing.
  • npm run docs generates API documentation with TypeDoc into docs/.
  • npm run docs:watch runs TypeDoc in watch mode for live preview.
  • npm run docs:site builds the Docusaurus documentation site (website/build/).
  • npm run docs:site:start starts the Docusaurus dev server for live editing.

Coding Style & Naming Conventions

  • TypeScript, ES modules ("type": "module").
  • Indentation: 4 spaces. Prefer explicit types on public APIs in src/index.ts and src/Mnemonic/ exports.
  • File naming: lower-case with .ts/.tsx; React hooks use use*.ts (example: use.ts).
  • Keep exports centralized in src/index.ts.

Testing Guidelines

  • Test runner: Vitest (vitest.config.ts, vitest.setup.ts).
  • Place tests alongside source or in src/ with .test.ts/.test.tsx suffixes.
  • Run all tests with npm run test and focus during development with npm run test:watch.

Commit & Pull Request Guidelines

  • No commit history exists yet. Use clear, imperative messages (e.g., Add Mnemonic headers).
  • PRs should include a concise summary, testing notes (npm run test/npm run lint), and screenshots for UI changes.

Release & Publishing

  • Releases are handled by GitHub Actions on tagged releases. Tag format: vX.Y.Z (example: v0.1.0).

react-mnemonic Persistence Guardrails

This file is generated by scripts/generate-agent-instructions.mjs. Edit website/docs/ai/* and run npm run docs:ai instead of editing this file directly.

Quick Rules

  • useMnemonicKey(...) must run inside a MnemonicProvider.
  • Use useMnemonicKeyOptional(...) from react-mnemonic/optional only when a reusable component may render without a provider and should degrade to local in-memory state instead of crashing.
  • Prefer useMnemonicKey(...) over raw localStorage for durable app or UI state. Use raw storage only in adapters, tests, or low-level library internals.
  • Every stored key is namespaced as ${namespace}.${key} in the underlying storage backend.
  • defaultValue is required and defines the fallback when a key is absent or invalid.
  • set(next) persists a new value for the key.
  • reset() persists defaultValue again.
  • remove() deletes the key entirely, so the next read falls back to defaultValue.
  • Use set(null) when "cleared" is a durable state that must survive reload.
  • Do not persist access tokens, refresh tokens, raw session IDs, or other auth credentials as durable UI state.
  • Auth-scoped durable state should use a user-aware namespace and be cleared on logout or expiry.
  • For multi-step wizards, persist user-authored draft values and derive completion from them; keep active step, validation errors, and submit-in-flight state ephemeral unless resume-on-reload is an explicit feature.
  • For shopping carts, persist canonical line items and quantities; derive subtotal and item count instead of storing them, and treat empty-cart semantics separately from remove().
  • SSR is safe by default: the server renders defaultValue unless you opt into ssr.serverValue.
  • Schema migrations handle structural version upgrades. reconcile(...) handles conditional read-time policy rewrites.
  • StorageLike is intentionally synchronous in beta 1.
  • Consumer code should import published values and types from react-mnemonic, not internal paths or local ambient shims.

Durable State Checklist

  1. Should this survive reload, or is it only runtime UI state?
  2. Is null meaningfully different from a missing key?
  3. Should other tabs stay in sync?
  4. Is SSR involved, and if so should the server render defaultValue, ssr.serverValue, or delay hydration?
  5. Is schema evolution likely enough to justify a versioned schema and migration path now?

Canonical Recipes

  • Theme Preference With Cross-Tab Sync
  • Saved Filters With Durable Clear Intent
  • Dismissible Announcement UI
  • Durable Draft Content With Ephemeral Form Metadata
  • Optional Persistence For Component Libraries
  • Schema Upgrade With Migration Plus Reconciliation
  • SSR Placeholder For Theme
  • Auth-Aware Durable State With Automatic Cleanup
  • Multi-Step Wizard With Durable Draft And Ephemeral Navigation
  • Shopping Cart With Canonical Line Items And Derived Totals

Canonical Docs

Maintenance

  • Treat website/docs/ai/* as the canonical source.
  • Run npm run docs:ai after changing canonical AI docs.
  • Run npm run ai:check to verify generated instruction packs and retrieval artifacts are in sync.