quiver: Instructions file for Codex

Quiver — AI agent context

This file is the single source of truth for AI assistants working in this repo. CLAUDE.md imports it for Claude Code; Codex and other AGENTS.md-aware tools read it directly. Edit conventions here, not in CLAUDE.md.

Quiver is an Arrow.js starter template with file-based routing, layouts, reactive state, composables, and a full testing setup. Stack: Arrow.js · Vite · Tailwind CSS v4 · Vitest · Playwright. The router is built on the Navigation API (modern browsers only).

---

Folder structure

src/
├── framework/       # Router, DI, store, app bootstrap — edit with care
├── pages/           # File-based routes — add your pages here
├── layouts/         # Page wrapper layouts — add layouts here
├── components/      # Reusable UI components — add components here
├── state/           # Global reactive state modules — add stores here
├── composables/     # Reusable logic functions — add composables here
├── utils/           # Pure helper functions (hmrState)
└── main.js          # App entry point — provide() global DI keys here

tests/
├── framework/       # Unit tests for framework utilities (Vitest)
├── composables/     # Unit tests for composables (Vitest)
└── e2e/             # End-to-end tests (Playwright)

---

Commands

bun run dev           # Start Vite dev server
bun run test              # Run unit tests once
bun run test:watch    # Run unit tests in watch mode
bun run test:e2e      # Run E2E tests (Playwright)
bun run typecheck     # Type-check src/ via JSDoc (tsc --noEmit, checkJs)
bun run build         # Production build
bun run docs:dev      # Start docs site locally
bun run docs:build    # Build docs site

Always run bun run typecheck && bun run test && bun run test:e2e before completing a task.

Types

The codebase is plain JavaScript typed via JSDoc, checked by tsc under checkJs + strict (see jsconfig.json). CI enforces a clean bun run typecheck. When adding code:

• Annotate exported functions with @param/@returns; use @typedef for shared shapes and @template for generics
• Reuse existing typedefs via import syntax: /** @typedef {import('../state/userState.js').User} User */
• Prefer a JSDoc cast /** @type {X} */ (expr) over restructuring code to satisfy the checker
• Do not convert files to TypeScript — the plain-JS + JSDoc setup is deliberate