Initial Commit

openspec/archive/2026-04-25-enterprise-compress-svg/proposal.md

@@ -0,0 +1,217 @@
+# OpenSpec Change: enterprise-compress-svg
+
+- **Change ID**: enterprise-compress-svg
+- **Package**: `@suaveplan/compress-svg`
+- **Category**: universal
+- **Target path**: `universal/compression/compress-svg`
+- **Status**: PROPOSED
+- **Date**: 2026-04-24
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/compress-svg.md`
+
+---
+
+## Summary
+
+Deliver `@suaveplan/compress-svg` on the genesis branch from scratch at enterprise quality. The package provides SVG optimisation and minification: whitespace removal, redundant attribute stripping, path data precision reduction, element collapsing, ID mangling, viewBox normalisation, inline style to attribute conversion, and SVGO-compatible plugin pipeline. Pure TypeScript, runs in Bun/Node/browser, operates on SVG string input/output.
+
+---
+
+## Current-state audit (genesis)
+
+The package does not exist on genesis yet — this is a fresh build. No prior source, no test results, no coverage data. The main-branch package had 99.31% coverage.
+
+---
+
+## Available workspace deps on genesis
+
+| Package | Role |
+|---|---|
+| `@suaveplan/error` (`workspace:^`) | Base class for `SvgCompressError`; `SVG_COMPRESS.*` codes |
+| `@suaveplan/types` (`workspace:^`) | `LoggerLike` |
+| `zod` (`catalog:forms`) | Zod schemas for all public option types |
+| `@opentelemetry/api` (`catalog:observability`) | Spans + counters |
+
+Dev deps: `vitest`, `@vitest/coverage-istanbul`, `fast-check`, `mitata` (all `catalog:testing`).
+
+---
+
+## Public API
+
+### Core types
+
+```ts
+class SvgCompressError extends SuaveplanError
+
+interface SvgPlugin {
+  name: string
+  apply(node: SvgNode, options: SvgPluginOptions): SvgNode | null
+}
+
+interface SvgNode {
+  type: 'element' | 'text' | 'comment' | 'cdata' | 'doctype'
+  name?: string
+  attributes?: Record<string, string>
+  children?: SvgNode[]
+  value?: string
+}
+
+interface CompressOptions {
+  plugins?: SvgPlugin[]          // default: standard plugin set
+  floatPrecision?: number        // decimal places for path coords; default: 3
+  transformPrecision?: number    // default: 5
+  multipass?: boolean            // default: true; run until stable
+  removeComments?: boolean       // default: true
+  removeMetadata?: boolean       // default: true
+  removeDoctype?: boolean        // default: true
+  collapseGroups?: boolean       // default: true
+  mergeStyles?: boolean          // default: true
+  mangleIds?: boolean            // default: false
+}
+
+interface CompressResult {
+  data: string                   // optimised SVG string
+  originalSize: number           // bytes
+  compressedSize: number         // bytes
+  ratio: number                  // compressedSize / originalSize
+  passCount: number              // multipass iterations used
+}
+
+function compressSvg(svg: string, options?: CompressOptions): CompressResult
+function parseSvg(svg: string): SvgNode
+function serializeSvg(node: SvgNode): string
+
+// Built-in plugins (each independently importable)
+const removeComments: SvgPlugin
+const removeMetadata: SvgPlugin
+const removeDoctype: SvgPlugin
+const collapseGroups: SvgPlugin
+const cleanupAttrs: SvgPlugin
+const convertColors: SvgPlugin
+const convertPathData: SvgPlugin
+const convertTransforms: SvgPlugin
+const mergeStyles: SvgPlugin
+const inlineStyles: SvgPlugin
+const removeUnusedDefs: SvgPlugin
+const mangleIds: SvgPlugin
+```
+
+### Presets
+
+```ts
+const PRESET_DEFAULT: SvgPlugin[]    // removeComments + metadata + doctype + collapseGroups + cleanupAttrs + convertPathData
+const PRESET_SAFE: SvgPlugin[]       // PRESET_DEFAULT minus id-mangling and transform conversion
+const PRESET_AGGRESSIVE: SvgPlugin[] // all plugins enabled
+```
+
+### Error codes
+
+```ts
+type SvgCompressErrorCode =
+  | 'SVG_COMPRESS_PARSE_FAILED'
+  | 'SVG_COMPRESS_INVALID_SVG'
+  | 'SVG_COMPRESS_PLUGIN_FAILED'
+
+const SVG_COMPRESS_ERROR_METADATA: Readonly<Record<SvgCompressErrorCode, CodeMetadata>>
+function registerSvgCompressErrorCodes(): void
+```
+
+### Zod schemas
+
+```ts
+CompressOptionsSchema
+CompressResultSchema
+```
+
+---
+
+## New additions for genesis
+
+1. **Streaming-safe parser** — lightweight push-parser (no DOMParser dependency) operating on string; SAX-like for large SVGs.
+2. **Plugin pipeline** — each plugin receives and returns an `SvgNode` tree; returning `null` removes the node. Plugins compose cleanly via standard array.
+3. **Multipass loop** — runs plugins until the serialised output reaches a stable size (or `multipass: false`).
+4. **OTel instrumentation** — span `svg.compress`, counter `svg_compress_total`, histogram `svg_compress_duration_ms` + `svg_compress_ratio`.
+5. **Property-based tests** — compression idempotency (compress twice = same output), `parseSvg` ↔ `serializeSvg` round-trip, ratio always ≤ 1 for any valid SVG.
+6. **Benchmark suite** — `compressSvg` on 10 kB SVG icon, 100 kB complex illustration, 1 MB map SVG.
+
+---
+
+## File layout
+
+```text
+universal/compression/compress-svg/
+  package.json
+  tsconfig.json
+  vitest.config.ts
+  src/
+    index.ts
+    error-codes.ts
+    constants/
+      index.ts
+    types/
+      common.ts
+      common.md
+    core/
+      compress-svg/
+        compress-svg.ts
+        compress-svg.md
+        compress-svg.types.ts
+        compress-svg.test.ts
+        index.ts
+    parser/
+      svg-parser/
+        svg-parser.ts
+        svg-parser.md
+        svg-parser.test.ts
+        index.ts
+    plugins/
+      remove-comments/
+        remove-comments.ts
+        remove-comments.md
+        remove-comments.test.ts
+        index.ts
+      remove-metadata/
+        remove-metadata.ts
+        remove-metadata.md
+        remove-metadata.test.ts
+        index.ts
+      collapse-groups/
+        collapse-groups.ts
+        collapse-groups.md
+        collapse-groups.test.ts
+        index.ts
+      cleanup-attrs/
+        cleanup-attrs.ts
+        cleanup-attrs.md
+        cleanup-attrs.test.ts
+        index.ts
+      convert-path-data/
+        convert-path-data.ts
+        convert-path-data.md
+        convert-path-data.test.ts
+        index.ts
+      convert-transforms/
+        convert-transforms.ts
+        convert-transforms.md
+        convert-transforms.test.ts
+        index.ts
+      mangle-ids/
+        mangle-ids.ts
+        mangle-ids.md
+        mangle-ids.test.ts
+        index.ts
+    presets/
+      index.ts
+    __benchmarks__/
+      compress-svg.bench.ts
+  tests/
+    integration.test.ts
+    property.test.ts
+```
+
+---
+
+## Impact
+
+**Downstream**: build pipeline tools, `@suaveplan/packer`, any SVG-heavy asset pipelines.
+**Breaking changes**: none — fresh build.
+**Prerequisites**: `@suaveplan/error`, `@suaveplan/types` published to Verdaccio.