@svgsketch/core 8.0.0 → 10.0.0

package/README.md

@@ -25,6 +25,37 @@ const svg = doc.toSVG(); // rendered SVG string
 const svgs = doc.toJSON(); // canonical `.svgs` document
 ```
 
+## Inspect and recolor artwork
+
+```ts
+import { DocumentBuilder, Rectangle, cssColorKey } from '@svgsketch/core';
+
+const doc = new DocumentBuilder().add(new Rectangle(0, 0, 80, 60).fill('#2563eb'));
+const inventory = doc.collectColorInventory();
+const blue = cssColorKey('#2563eb', { includeAlpha: false });
+const group = inventory.groups.find((g) => g.kind === 'color' && g.originalColors.includes(blue!))!;
+doc
+  .recolor({ replacements: { [group.id]: '#0f766e' } }, { inventory })
+  .tokenizeColors({ prefix: 'poster' });
+const svg = doc.toSVG();
+```
+
+`recolor()` and `tokenizeColors()` are fluent and throw `RecolorError` on refusal without changing the builder.
+Their `WithDiagnostics` variants return the existing `RecolorApplicationOutcome` with diagnostics, impact, and an optional refusal.
+`SdkRecolorOptions` accepts an existing in-memory inventory, fresh `inventoryOptions`, and `planningOptions` such as an identity allocator.
+An inventory belongs to its source snapshot and analysis context; recollect it after editing the document.
+Inventories and returned outcomes remain detached from later mutable builder edits.
+Selection scope defaults to forking, document scope to shared editing, and source alpha is preserved.
+
+The pure `findSamePaintColorMatches(snapshot, request, options?)` query matches effective fill or stroke by canonical base color, independently of token identity and opacity.
+Supply native seed and candidate IDs explicitly.
+Its immutable result includes matches, color keys, skipped-site reasons, and serializable diagnostics.
+Container seeds expand to paintable descendants; reusable instances match only when their paint is uniform.
+Gradients, mixed paint, animation, and uncertain consumers are skipped rather than approximated.
+
+The existing pure analysis, inventory, planning, and application APIs remain available for callers that manage snapshots directly.
+Schema 39, collaboration protocol 16, and single-value tokens are unchanged.
+
 ## What it includes
 
 | Module     | Exports                                                                                            |
@@ -53,7 +84,7 @@ designed for:
 {
   "schemaVersion": 1,
   "documentMetadata": {/* title, author, license, … */},
-  "templateVariables": [/* { name, type, defaultValue, … } */],
+  "templateVariables": [/* { id, name, type, defaultValue, ... } */],
   "viewboxes": [/* { id, x, y, width, height } */],
   "guides": [/* { id, orientation, position, … } */],
   "measurements": [/* dimensioning annotations */],
@@ -139,6 +170,19 @@ Two complementary mechanisms for parameterizing documents:
 
 ### Round-trip fidelity
 
+SVG token output uses a direct document-root stylesheet with `@layer svgsketch.tokens` and `:where(svg:root)`.
+This default replaces the legacy `:root, svg` contract, preventing host-page declaration leaks.
+Inline copies retain defaults through derived fallbacks and may inherit independently themed host values.
+The live editor requests an explicit document-layer host target.
+Recognized current, legacy, compatible, and merged SVGSketch blocks recover names, defaults, and inferred token types on SVG import; native metadata remains `.svgs` information.
+
+`renderToSvg(snapshot, { colorOutput: 'compatible' | 'resolved', colorScheme: 'light' | 'dark' })` selects portable output; the defaults are authored/light.
+`applyColorOutputWithDiagnostics(svg, { mode: 'resolved' })` exposes pure source conversion with warnings for preserved uncertain sites.
+`applyTemplateVariableFallbacksWithDiagnostics`, `buildRenderPlanWithDiagnostics`, `analyzeTemplateVariables`, and shared validation helpers support deferred consumers and token editors.
+Token names are decoded CSS identifiers without `--`; color defaults accept unresolved CSS color expressions and number defaults require finite unitless literals.
+Free-form string stamping uses carrier-aware escaping, and executable/structural substitutions are refused.
+See the [Phase 5 contract](../../docs/architecture/recolor-phase-5.md) for recovery, output boundaries, and compatibility details.
+
 The format guarantees that for any valid snapshot `s`:
 
 ```ts
@@ -199,5 +243,6 @@ const svg = renderToSvg(resolved);
 
 The companion `@svgsketch/cli` package exposes `svgsketch validate`,
 `svgsketch render`, `svgsketch info`, `svgsketch vars`, and
-`svgsketch codegen` commands that operate on `.svgs` files headlessly —
-suitable for CI/CD pipelines.
+`svgsketch codegen` commands that operate on `.svgs` files headlessly.
+Its `colors`, `recolor`, and `tokenize` commands inspect and rewrite SVG, native, Illustrator, PDF, and EPS inputs through the same inventory and planner, with dry-run reports and atomic native/SVG output.
+These commands are suitable for CI/CD pipelines.