@svgsketch/cli 0.6.1 → 0.7.0

package/README.md

@@ -71,8 +71,85 @@ An encrypted file opens with `--password`, or without it when its password only
 Transcoder diagnostics print to stderr as `severity: pdf:code: message` and `severity: illustrator:code: message` lines beside the ingest diagnostics.
 `--fail-on-warnings` counts them along with the ingest warnings.
 
+## Inspect, recolor, and tokenize
+
+These commands accept SVG, `.svgs`, Illustrator, PDF, and EPS through the same importer as `convert`.
+Recoloring and token conversion are free features.
+
+```bash
+svgsketch colors poster.svg --json --report colors.json
+svgsketch recolor poster.svg -o teal.svg --replace '#2563eb=#0f766e'
+svgsketch recolor design.svgs -o edited.svgs --replace-token brand='#0f766e'
+svgsketch recolor design.svgs --select SHAPE_ID --hue-shift 30 --dry-run --json
+svgsketch tokenize poster.svg -o tokens.svgs --prefix poster
+svgsketch tokenize poster.svg -o tokens.svg --prefix poster --color-output compatible
+```
+
+`colors` lists groups, token identities, native locations, eligibility, exclusions, and outside consumers.
+`--replace` addresses an absolute literal-color group, independently of token groups with the same color.
+`--replace-token` addresses a case-sensitive document token name without `--`.
+Both preserve each source occurrence's alpha.
+Transforms run before explicit replacements, followed by optional token conversion.
+
+Repeat `--select` to restrict the request to native IDs from the inventory.
+Document edits default to `--sharing shared`; selection edits default to `--sharing fork`.
+Reference closure discovers dependencies without granting permission to edit outside the selection.
+Use `--sharing shared` deliberately when outside consumers should change too.
+
+| Option                                                    | Behavior                                                                      |
+| --------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `--grouping exact\|similar`, `--jnd 0.5..10`              | Exact by default; Similar defaults to 1 JND (deltaEOK 0.02).                  |
+| `--hue-shift`, `--chroma-scale`, `--lightness-shift`      | Existing OKLCH adjustments, taking finite numbers.                            |
+| `--grayscale`, `--invert-lightness`                       | Existing core color transforms.                                               |
+| `--notation preserve\|hex\|oklch`, `--gamut source\|srgb` | Preserve source notation and gamut by default.                                |
+| `--include REASON`                                        | Explicitly include a supported soft exclusion; never bypasses core preflight. |
+| `tokenize --prefix NAME`, `--no-reuse`                    | Shared token naming and equivalent-definition reuse rules.                    |
+| `--dry-run`, `--json`, `--report PATH`                    | Preflight without writing artwork, or produce a versioned machine report.     |
+| `--fail-on-warnings`                                      | For these new mutation commands, fail before writing artwork.                 |
+| `--color-output authored\|compatible\|resolved`           | Shared SVG output conversion; default authored.                               |
+
+Mutation commands require `-o` unless using `--dry-run`.
+Output must be `.svgs` or `.svg`, must differ from input/report/recipe files, and is written atomically after preflight.
+Native output retains token IDs and metadata; SVG retains the supported recoverable token declarations and generated fallbacks.
+Invalid requests, stale recipes, refusals, and strict-warning failures leave existing artwork output untouched.
+Diagnostics use stderr, keeping `--json` stdout parseable.
+Machine reports describe inventory, allocations, impact, and diagnostics; they are not executable serialized plans.
+The `changed` field describes the planned snapshot difference, while `written` reports whether artwork was written and `warningsAsFailure` identifies strict-warning rejection.
+
+Advanced requests use `--request recipe.json`, exclusively with respect to recolor behavior flags.
+The version-1 recipe has `version`, optional `sourceFingerprint`, `inventoryOptions`, and `request`.
+The request accepts the serializable core `RecolorRequest` fields, with replacement colors written as strings.
+Inventory options accept `scope`, `grouping`, and the existing concrete analysis `colorScheme`.
+Group-addressed replacements or conversion names/group IDs require the fingerprint from `colors --json` for the same input and inventory options.
+A supplied fingerprint must always match.
+Re-inspect changed artwork instead of moving old group choices onto new groups.
+
+```json
+{
+  "version": 1,
+  "inventoryOptions": {},
+  "request": { "transform": { "hueShift": 30 } }
+}
+```
+
+Scripts, raster pixels, masks, opaque data, uncertain consumers, and unsupported sources retain the core exclusions and refusals.
+Authored CSS remains authored when its effect cannot be proved.
+Tokens retain one default value; a separate light/dark token system is deferred.
+
 ## Render diagnostics
 
+`render` and `convert` accept `--color-output authored|compatible|resolved`, defaulting to `authored`.
+Authored SVG retains themeable tokens with derived use-site fallbacks.
+Compatible output adds legacy sRGB floors while retaining variable expressions.
+Resolved output bakes supported static colors for consumers that do not evaluate CSS variables.
+Uncertain and animated sites remain authored with their dependencies and warnings; imports are never fetched.
+Overrides share core name/type validation, and invalid overrides leave an existing output file unchanged.
+
+```bash
+svgsketch render design.svgs -o portable.svg --color-output compatible
+svgsketch render design.svgs -o static.svg --color-output resolved --var brand=#2255cc
+```
+
 `import`, `convert`, `render`, and `codegen` report machine-readable diagnostics as `warning:` / `error:` lines on stderr.
 Import diagnostics also include their stable diagnostic code.
 Malformed SVG never produces a partial `.svgs` file.

package/dist/index.d.ts

@@ -1 +1,28 @@
 #!/usr/bin/env node
+import { HistorySnapshot, IngestDiagnostic, ForeignImportReport } from '@svgsketch/core';
+
+type ArtboardSelection = 'all' | number[];
+declare const TEXT_MODES: readonly ["editable", "outline"];
+declare const HIDDEN_LAYER_MODES: readonly ["import", "skip"];
+interface ForeignImportOptions {
+    artboards?: ArtboardSelection;
+    text?: (typeof TEXT_MODES)[number];
+    hiddenLayers?: (typeof HIDDEN_LAYER_MODES)[number];
+    password?: string;
+}
+interface LoadedDocument {
+    snapshot: HistorySnapshot;
+    /** Every diagnostic the load produced, already printed to stderr. */
+    diagnostics: readonly IngestDiagnostic[];
+    producerDiagnostics?: readonly {
+        readonly code: string;
+        readonly message: string;
+        readonly severity: string;
+    }[];
+    /** Warnings counted for `--fail-on-warnings`, including transcoder warnings. */
+    warningCount: number;
+    /** Set when the input was an Illustrator or PDF document. */
+    report: ForeignImportReport | null;
+}
+
+export type { ForeignImportOptions, LoadedDocument };