Skip to content

AGENTS.md

Latest commit

 

History

History
106 lines (88 loc) · 4.53 KB

AGENTS.md

File metadata and controls

106 lines (88 loc) · 4.53 KB
Raw

AGENTS.md — SVGPathCommander

Project Overview

SVGPathCommander v2.2.0 — TypeScript library for manipulating SVG <path> d attributes. Works in browser and Node.js.

Commands

pnpm install          # Install dependencies
pnpm dev              # Serve docs on localhost:3000
pnpm test             # Run all tests (vitest + happy-dom)
pnpm test-ui          # Run tests with UI
pnpm test -- -t "Test name"    # Run a single test by name
pnpm test -- class.test.ts     # Run a single test file
pnpm lint             # Deno lint + tsc type check
pnpm lint:ts          # Deno lint only
pnpm fix:ts           # Deno lint --fix
pnpm format           # Deno format
pnpm build            # Build with tsdown
pnpm check:ts         # tsc --noEmit (type check only)

Tech Stack

  • Language: TypeScript (strict, ES2020 target, allowImportingTsExtensions)
  • Package manager: pnpm (v10.33.0)
  • Build: tsdown (ESM + UMD outputs)
  • Test: Vitest + happy-dom (Istanbul coverage)
  • Lint/Format: Deno (deno lint, deno fmt)
  • Dependency: @thednp/dommatrix (DOMMatrix shim)

Source Structure (src/)

Directory Purpose
index.ts Main entry — exports SVGPathCommander class + all types
main.ts SVGPathCommander class (core, chainable instance methods)
types.ts TypeScript type definitions (PathCommand, PathSegment, PathArray, etc.)
interface.ts Interfaces (Options, TransformObject, PathBBox, shape attrs)
util.ts Re-export of all static methods (tree-shakeable entry)
convert/ Path format conversion (absolute, relative, curve, string)
parser/ SVG path string tokenizer/scanner
process/ Manipulation algorithms (normalize, optimize, reverse, transform, etc.)
math/ Low-level math (bezier, cubic, quad, line, arc, polygon tools)
morph/ Path morphing (equalize, split, sample, classify, match)
util/ Query helpers (bbox, length, point-at-length, intersection, etc.)
options/ Default configuration

Code Conventions

Imports

  • Use .ts extension on all imports: import { foo } from "./bar.ts"
  • Path alias ~/* maps to src/ (e.g., import SVGPathCommander from '~/index')
  • Group imports: external libs → internal modules → types
  • Use import type for type-only imports

Formatting & Linting

  • No comments unless explicitly asked
  • Run pnpm format then pnpm lint:ts before committing
  • Deno formatter and linter enforced (deno fmt, deno lint)

TypeScript

  • Strict mode enabled — no any, no implicit any
  • noUnusedLocals and noUnusedParameters enforced
  • noImplicitReturns enforced
  • allowImportingTsExtensions — always include .ts in imports
  • Use type aliases for unions, interface for object shapes

Naming Conventions

  • Classes: PascalCase (SVGPathCommander, PathParser)
  • Functions/Methods: camelCase (parsePathString, normalizePath)
  • Types: PascalCase ending in semantic suffix (PathArray, NormalSegment, IteratorCallback)
  • Command types: Suffix with Command/Segment (AbsoluteCommand, MSegment)
  • Constants: camelCase for module-level constants (defaultOptions, distanceEpsilon)
  • Test descriptions: Start with Test (Test init with no parameter)

Error Handling

  • Throw TypeError with descriptive message for invalid inputs
  • Use the shared error prefix from ~/util/error.ts
  • Validate inputs early, fail fast with clear messages
  • Static methods return safe defaults for empty/invalid input (e.g., getPathBBox(''))

Class Design

  • Instance methods are chainable — always return this
  • Expose functionality as both instance methods and static methods
  • Use getters for computed properties (get bbox(), get length())
  • Instance options validated in constructor with fallback to defaultOptions

Testing

  • Tests run with happy-dom (headless browser simulation)
  • Fixtures in test/fixtures/
  • Two test files: test/class.test.ts (instance API), test/static.test.ts (static methods)
  • Tests render actual SVG and verify d attribute output
  • Use vi.waitFor() for async DOM queries (timeout: 200ms)
  • Use expect().to.deep.equal() for object comparison, expect().to.equal() for primitives
  • Coverage provider: Istanbul

Build Outputs

File Description
dist/index.min.js UMD bundle (minified, browser-ready, includes dommatrix)
dist/index.js ESM bundle (tree-shakeable, neutral platform)
dist/util.js Static methods only (tree-shakeable)
dist/index.d.ts Type declarations