yakpanel-core/YakPanel-server/frontend/node_modules/svg-path-commander/AGENTS.md

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