test-card/AGENTS.md

AGENTS

This file orients coding agents for the test-card repo. Stack: SvelteKit + Vite + TypeScript + Vitest + ESLint + Prettier. Package scripts are in package.json at repo root.

Repository layout

• src/ SvelteKit app source.
• src/routes/ route and load files.
• src/lib/ shared code exposed via $lib.
• tests/ Vitest tests and helpers.
• av-sync/ small Vite + Svelte app for AV sync tools.
• assets/ generated assets (see npm run generate-assets).
• tests/output/ visual regression artifacts (baseline/current/diff).

Setup

• Use the existing package manager for scripts; root scripts assume npm.
• Install deps with npm install if needed.
• Do not add new dependencies without explicit permission.

Common commands

• Dev server: npm run dev.
• Build: npm run build.
• Preview build: npm run preview.
• Typecheck: npm run check.
• Typecheck (watch): npm run check:watch.
• Lint: npm run lint.
• Format: npm run format.
• Generate assets: npm run generate-assets.
• AV sync dev server: npm run av:dev (runs inside av-sync/).
• AV render video: npm run av:render:video -- <args>.
• AV render audio: npm run av:render:audio.

Tests

• Test runner: Vitest (no test script defined).
• Run all tests once: npx vitest --run.
• Run all tests in watch mode: npx vitest.
• Run a single file: npx vitest --run tests/test-card.test.ts.
• Run a single test by name: npx vitest --run -t "matches baseline".
• Filter by file and name: npx vitest --run tests/test-card.test.ts -t "matches baseline".

Visual regression test notes

• The test starts its own dev server on port 5888.
• It uses Puppeteer; first run creates tests/output/testcard-baseline.png.
• If the baseline changes on purpose, delete the baseline and rerun.
• Diffs are written to tests/output/testcard-diff.png when mismatches exist.

Formatting

• Prettier is the source of truth.
• Tabs for indentation (useTabs: true).
• Single quotes (singleQuote: true).
• No trailing commas (trailingComma: none).
• Max line width 100 (printWidth: 100).
• Svelte files use the Svelte parser.

Linting

• ESLint with TypeScript + Svelte recommended rules and Prettier.
• ESLint ignores av-sync/** and all *.js files.
• Prefer fixing lint at the source rather than disabling rules.

TypeScript and SvelteKit

• tsconfig.json is strict; keep types accurate.
• Prefer type imports: import type { Foo } from '...'.
• Keep export const config in SvelteKit route files.
• Use +page.ts/+layout.ts conventions and $types imports.
• Use $lib alias for shared code inside src/lib/.
• Keep server-only logic in *.server.ts or server load functions.

Import style

• Order imports: external packages, internal $lib or alias, relative paths.
• Separate type-only imports from runtime imports when it improves clarity.
• Avoid deep relative paths when $lib can be used.
• Keep named imports sorted when it improves readability.

Naming conventions

• Components: PascalCase.svelte.
• Functions/variables: camelCase.
• Constants: UPPER_SNAKE_CASE for true constants.
• Routes: use SvelteKit folder conventions; keep names short and descriptive.
• Files: favor kebab-case for non-component utilities.

Code structure

• Use const by default; let only when reassigned.
• Prefer async/await over .then() chains.
• Keep functions small and focused; extract helpers to src/lib/.
• Keep Svelte components thin; move heavy logic to modules.

Error handling

• Throw Error objects with clear messages.
• Catch errors only when you can add context or recover.
• Avoid silent failures; log or rethrow with added context.
• For async utilities, reject with Error (not strings).

Testing style

• Use Vitest describe/it/expect.
• Keep tests deterministic; avoid time-based flakiness.
• Store artifacts under tests/output/ only.
• Use helper functions in tests/utils.ts for shared setup.

Styling and UI

• This project uses Svelte; prefer local component styles.
• Keep global styles minimal and intentional.
• If editing fonts or assets, ensure they remain licensed in dependencies.

Configuration files

• vite.config.ts defines the @assets alias and inlang plugin.
• svelte.config.js uses the static adapter.
• Keep config changes minimal and documented in code when needed.

Dependency policy

• Do not add, remove, or upgrade deps without explicit permission.
• If you want a new dependency, explain why and ask first.

Cursor/Copilot rules

• No .cursor/rules/, .cursorrules, or .github/copilot-instructions.md found.

Agent workflow tips

• Prefer small, focused edits with Prettier-friendly formatting.
• Run npm run lint and npx vitest --run for changes touching logic.
• For UI-only tweaks, at least run npm run lint.
• For config changes, run npm run check.
• For AV sync changes, validate via npm run av:dev.

When adding new files

• Follow the existing folder structure and naming conventions.
• Update tests if behavior changes.
• Avoid introducing new top-level folders without discussion.

Logging

• Use debug for structured logs in Node utilities.
• Avoid noisy console.log in production code.

Performance

• Avoid unnecessary re-renders in Svelte components.
• Prefer derived values over repeated computation.

Accessibility

• Keep semantic HTML in Svelte templates.
• Ensure interactive elements are keyboard reachable.

Data and assets

• Generated assets live under assets/generated/.
• Do not edit generated assets by hand.

Build output

• npm run build uses Vite and SvelteKit static adapter.
• npm run preview serves the build for verification.

Notes

• Keep this file updated when commands or conventions change.