suaveplan/openspec/changes/compress-svg-completion/tasks.md

Tasks — Compress-SVG completion

Every checkbox MUST reflect work actually done in this change. Do not retroactively tick. The seven gaps closed here were never claimed by an earlier change; this is the first ticket that touches them.

0. Pre-flight (non-negotiable)

• 0.1 Confirm clean working tree (git status reports nothing) and no in-flight worktrees with uncommitted work (git worktree list then git status in each)
• 0.2 If any worktrees exist under .claude/worktrees/, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (git worktree remove) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
• 0.3 Confirm the package set in MANIFEST.md matches find packages -maxdepth 3 -name package.json count. Drift here means a prior change archived without regenerating the manifest.

Audit Note (2026-05-02)

Status: DEFERRED. packages/docs/compress-svg/src/ only contains __benchmarks__, constants, core, parser, plugins, presets, types plus error-codes.ts. None of the seven gaps are filled: no optimizer/ (SvgOptimizer), no structural/, no deduplicator/, no path-tokenizer/, no archive/ (SvgPacker / SvgUnpacker / SvgArchiveBuilder), no browser/ unpacker, no cli.ts bin entry. This is a substantial migration estimated at ~6 000+ source lines verbatim; 0% is done.

1. Spec authoring

• 1.1 Read ../suaveplan/packages/universal/compress-svg/src end-to-end (no dedicated enterprise/compress-svg.md exists)
• 1.2 Read openspec/specs/compress-svg/spec.md (does not exist yet — create on archive)
• 1.3 Read openspec/AGENTS.md Sections 0a (parity), 13 (verification), 14 (archival), 14a (affected dependents)
• 1.4 Draft proposal.md from openspec/templates/proposal.md
• 1.5 Fill in ## Source mapping table — every requirement cites a line range OR appears in the "no source line" table with justification
• 1.6 Draft specs/compress-svg/spec.md from openspec/templates/spec-delta.md covering all seven ADDED Requirements
• 1.7 Every requirement in the spec delta carries a **Verified by:** line naming concrete it(...) titles
• 1.8 openspec change validate compress-svg-completion exits with no errors

2. SvgOptimizer façade

• 2.1 Port optimizer/SvgOptimizer.ts (L1-L483) and optimizer/SvgOptimizer.types.ts into packages/docs/compress-svg/src/optimizer/svg-optimizer.ts
• 2.2 Define CompressorAdapter interface and ship a Node adapter (binds zlib) and a browser adapter (binds CompressionStream)
• 2.3 Wire the optimizer to the existing plugin pipeline (core/compress-svg); accept a SvgOptimizerConfig selecting plugins, presets, and the dictionary/structural/dedup pre-passes
• 2.4 Emit OTel histogram compress_svg.optimizer.duration_ms and counter compress_svg.optimizer.bytes_saved
• 2.5 Throw COMPRESS_SVG.OPTIMIZER_PIPELINE_FAILED when any selected plugin throws; chain the cause
• 2.6 Sibling .md (≥200 words, basic + advanced examples)

3. SvgStructuralOptimizer

• 3.1 Port structural/SvgStructuralOptimizer.ts (L1-L458) and its .types.ts into packages/docs/compress-svg/src/structural/svg-structural-optimizer.ts
• 3.2 Implement four rules: flatten single-child <g>; collapse identical attribute sets; hoist common attributes to a parent <g>; merge consecutive <path> elements with identical fill/stroke/style
• 3.3 Return a StructuralOptimizationResult with per-rule counts; expose each rule as a configurable boolean on StructuralOptimizerConfig
• 3.4 Throw COMPRESS_SVG.STRUCTURAL_INVALID_TREE on parser-rejectable input
• 3.5 Sibling .md

4. SvgDeduplicator

• 4.1 Port deduplicator/SvgDeduplicator.ts (L1-L398) into packages/docs/compress-svg/src/deduplicator/svg-deduplicator.ts
• 4.2 Replace node:crypto.createHash('sha256') with @suaveplan/crypto-hash sha256 for browser/server parity
• 4.3 Hoist a <defs> block at the document root with <symbol id="dedup-{shortHash}"> for each duplicate; replace duplicates with <use href="#dedup-{shortHash}"/>
• 4.4 Return a DeduplicationReport (candidatesScanned, duplicatesFound, bytesSaved, symbolMap)
• 4.5 Throw COMPRESS_SVG.DEDUPE_HASH_COLLISION when two distinct subtrees produce the same short hash (extremely rare; guarded for safety)
• 4.6 Sibling .md

5. PathTokenizer

• 5.1 Port PathTokenizer.ts (L1-L559) into packages/docs/compress-svg/src/path-tokenizer/path-tokenizer.ts
• 5.2 Export tokenizePath(d): PathToken[] and formatTokens(tokens: PathToken[]): string; round-trip property test on 10 000 random valid paths
• 5.3 Throw COMPRESS_SVG.PATH_TOKEN_PARSE_FAILED on malformed d strings; carry the byte offset of the first invalid character
• 5.4 Sibling .md

6. Binary archive (SvgPacker / SvgUnpacker)

• 6.1 Port SvgPacker.ts (L1-L2931) into packages/docs/compress-svg/src/archive/svg-packer.ts
• 6.2 Port archive/SvgArchiveBuilder.ts (L1-L177) and archive/SvgArchiveUnpacker.ts (L1-L182) into packages/docs/compress-svg/src/archive/svg-archive-{builder,unpacker}.ts
• 6.3 Preserve the legacy on-disk layout byte-for-byte (version header, manifest table, content-addressed payload table, checksum trailer)
• 6.4 Throw COMPRESS_SVG.ARCHIVE_VERSION_MISMATCH, COMPRESS_SVG.ARCHIVE_CHECKSUM_FAILED, COMPRESS_SVG.ARCHIVE_PAYLOAD_NOT_FOUND at the right call sites
• 6.5 Round-trip property test: pack a directory of N SVGs → unpack → byte-equal originals
• 6.6 Sibling .md for each implementation file

7. Browser unpacker

• 7.1 Port browser/SvgArchiveUnpackerBrowser.ts (L1-L440) and browser/SvgUnpackerBrowser.ts (L1-L1152) into packages/docs/compress-svg/src/browser/
• 7.2 Replace every Buffer, node:fs, node:zlib, node:crypto import with Web-Streams / globalThis.crypto equivalents
• 7.3 Static import scan in test asserts no Node-only API on the ./browser subpath
• 7.4 Throw COMPRESS_SVG.BROWSER_UNSUPPORTED_ENVIRONMENT when globalThis.crypto?.subtle or CompressionStream is missing
• 7.5 Sibling .md for each implementation file

8. CLI bin

• 8.1 Port cli.ts (L1-L271) into packages/docs/compress-svg/src/cli/cli.ts
• 8.2 Wire bin field in package.json: "suaveplan-svg-optimize": "./dist/cli/cli.js"
• 8.3 Build the CLI atop @suaveplan/cli (argument parser, command router, output formatter, spinner, JSON reporter)
• 8.4 Flags: --in <glob>, --out <dir>, --preset <name>, --archive <path>, --dedupe, --structural, --dry-run, --quiet, --json
• 8.5 Throw COMPRESS_SVG.CLI_INVALID_GLOB when no files match --in; exit code 2 (POSIX EX_USAGE)
• 8.6 Sibling .md

9. Error codes

• 9.1 Register COMPRESS_SVG.* codes in error-codes.ts: OPTIMIZER_PIPELINE_FAILED, STRUCTURAL_INVALID_TREE, DEDUPE_HASH_COLLISION, PATH_TOKEN_PARSE_FAILED, ARCHIVE_VERSION_MISMATCH, ARCHIVE_CHECKSUM_FAILED, ARCHIVE_PAYLOAD_NOT_FOUND, BROWSER_UNSUPPORTED_ENVIRONMENT, CLI_INVALID_GLOB
• 9.2 Every code thrown by at least one production path; no orphan codes

10. Subpath exports

• 10.1 package.json exports map gains ./optimizer, ./structural, ./deduplicator, ./path-tokenizer, ./archive, ./browser, ./cli
• 10.2 Each subpath is tree-shakeable ("sideEffects": false already set; verify by build artefact size)
• 10.3 tests/dep-graph.test.ts pins the subpath surface

11. Tests

• 11.1 src/optimizer/svg-optimizer.test.ts — pipeline orchestration, plugin selection, OptimizationResult shape, batch mode
• 11.2 src/optimizer/svg-optimizer.spec-conformance.test.ts — injectable CompressorAdapter round-trip; pipeline-failed error code; OTel histogram emitted
• 11.3 src/structural/svg-structural-optimizer.test.ts — every rule observable; per-rule counter accuracy
• 11.4 src/structural/svg-structural-optimizer.spec-conformance.test.ts — invalid-tree error code
• 11.5 src/deduplicator/svg-deduplicator.test.ts — cross-file dedup, <symbol>/<use> emission
• 11.6 src/deduplicator/svg-deduplicator.spec-conformance.test.ts — DeduplicationReport shape; injected hash honoured; collision error code
• 11.7 src/path-tokenizer/path-tokenizer.test.ts — every SVG path command; round-trip property test on 10 000 random paths
• 11.8 src/path-tokenizer/path-tokenizer.spec-conformance.test.ts — malformed-path error code; absolute/relative flag preserved
• 11.9 src/archive/svg-packer.test.ts — binary header, manifest, payload table, content-addressed dedup, version round-trip
• 11.10 src/archive/svg-packer.spec-conformance.test.ts — version-mismatch / checksum-failed / payload-not-found error codes
• 11.11 src/browser/svg-unpacker-browser.test.ts — browser unpacker round-trip with the same fixtures as the Node unpacker
• 11.12 src/browser/svg-unpacker-browser.spec-conformance.test.ts — static-import scan asserts no Node API; missing-globalThis.crypto error path
• 11.13 src/cli/cli.test.ts — argument parsing, glob expansion, in-place vs out-dir vs archive modes, dry-run, JSON reporter
• 11.14 src/cli/cli.spec-conformance.test.ts — invalid-glob error code; POSIX exit codes
• 11.15 tests/dep-graph.test.ts — subpath exports resolve, no Node API on ./browser
• 11.16 Every it(...) carries { timeout: 5000 } (or 30000 for archive round-trip tests)

12. Documentation

• 12.1 Sibling .md for every implementation .ts (≥200 words, basic + advanced examples, full API reference)
• 12.2 README links every co-located .md under ## Modules
• 12.3 Update CLAUDE.md compress-svg package listing to reflect the restored surface

13. Pre-archive verification (the 5-gate triple)

• 13.1 bun run check — Biome 0/0/0 across the monorepo
• 13.2 bunx turbo lint typecheck test --filter=@suaveplan/compress-svg — green
• 13.3 bunx turbo test:coverage --filter=@suaveplan/compress-svg — 100/100/100/100
• 13.4 bun scripts/openspec-conformance.ts @suaveplan/compress-svg — exit 0, no error findings
• 13.5 bunx turbo build --filter=@suaveplan/compress-svg — green

14. Pre-archive 7-row checklist (AGENTS.md Section 13)

• 14.1 Generics threaded; expectTypeOf assertions on OptimizationResult, DeduplicationReport, StructuralOptimizationResult, PathToken[]
• 14.2 Zod schemas wired at every declared boundary (SvgOptimizerConfig, StructuralOptimizerConfig, DeduplicationConfig, SvgArchiveManifest, CLI args)
• 14.3 Every COMPRESS_SVG.* code thrown by at least one production path; no orphans
• 14.4 Strict-mode behaviors tested both on and off (e.g. dedupe: true vs false; archive with vs without checksum)
• 14.5 OTel histograms / counters asserted with a real in-memory MeterProvider
• 14.6 Lifecycle dedup tested where claimed: SvgDeduplicator idempotent on identical input; SvgPacker archive output stable byte-for-byte across runs (deterministic)
• 14.7 No retroactive tick — every box above reflects work done in this change

15. Archive

• 15.1 Fold spec delta into openspec/specs/compress-svg/spec.md (creating the file)
• 15.2 Move openspec/changes/compress-svg-completion/ → openspec/archive/<yyyy-mm-dd>-compress-svg-completion/
• 15.3 Refresh MANIFEST.md if the package's exports list materially changed
• 15.4 Update STATUS.md if the package was previously listed as Pending