vizmatic 0.1.34 → 0.1.35

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/PROMPT.md CHANGED
@@ -258,7 +258,7 @@ Frame helpers:
258
258
 
259
259
  - `defineIllustration(build, defaultTheme?)`: `build: (c: ThemeColors) => ReactElement`, `defaultTheme?: ThemeMode = "dark"`. Returns `{ create(theme), default }`.
260
260
  - `Canvas`: `children?`, `c`, `padding?: number = 40`, `justify?: "center" | "flex-start" | "space-between" | "space-around" = "center"`, `background?: string`. Default root background is alpha-transparent during PNG/SVG rendering.
261
- - `Scene`: `c`, `children`, `title?`, `subtitle?`, `padding?: number = 40`, `gap?: number = 24`, `justify?: Canvas.justify = "flex-start"`, `align?: FlexAlign = "stretch"`, `contentWidth?: number | string = "100%"`, `background?`, `contentStyle?: React.CSSProperties`. Title/subtitle are optional and the title bar is omitted when no title is provided. Use `background={c.bg}` for an opaque theme frame.
261
+ - `Scene`: `c`, `children`, `title?`, `subtitle?`, `padding?: number = 40`, `gap?: number = 24`, `justify?: "center" | "flex-start" | "space-between" | "space-around" = "flex-start"`, `align?: FlexAlign = "stretch"`, `contentWidth?: number | string = "100%"`, `background?`, `contentStyle?: React.CSSProperties`. Title/subtitle are optional and the title bar is omitted when no title is provided. Use `background={c.bg}` for an opaque theme frame.
262
262
  - `TitleBar`: `title`, `subtitle?`, `c`.
263
263
 
264
264
  Layout primitives:
@@ -359,12 +359,20 @@ Theme and render APIs:
359
359
 
360
360
  - `getThemeColors(mode, preset?)`: `mode: ThemeMode`; `preset?: "default" | "engineering"`. Use `engineering` for flat technical-blog figures with a light gray palette, left-aligned black titles, pastel nodes, thin neutral connectors, compact corners, no shadows, Inter labels, and JetBrains Mono annotations. In a bare frame, set `preset = "engineering";` before the JSX. Add `background={c.bg}` to `Scene` for an opaque light gray canvas; omit it for alpha transparency.
361
361
  - `getToneColor(tone, c)`, `getToneFill(tone, c)`, `getToneGradient(tone)`, `getColor(name, c?)`, `getGradient(name)`, `heatColor(value)`.
362
+ - `getReadableColor(name, c)`: returns the semantic color variant with greatest contrast against `c.bgCard`.
363
+ - `getReadableToneColor(tone, c, background?)`: maps a tone to a readable semantic color and falls back to readable foreground text when contrast is below 4.5:1. `background` defaults to `c.bgCard`.
364
+ - `getReadableTextColor(background, c)`: parses solid or alpha CSS colors and chooses a theme foreground meeting 4.5:1 contrast when possible.
365
+ - `createPlotArea(width, height, margin)`: returns `PlotArea` geometry with inner width and height clamped to at least one pixel.
362
366
  - `renderToPng(element, options, createFn?, theme?)`: `element`, `options: RenderOptions`, `createFn?: (theme: "dark" | "light") => ReactNode`, `theme?: "dark" | "light"`.
363
367
  - `renderToPngWithOutput(...)`: same arguments as `renderToPng`; returns logical `width` / `height` and physical `pixelWidth` / `pixelHeight`.
364
368
  - `Watermark`: JSX marker component for frame-module exports. Props are `WatermarkOptions` plus `children?: ReactNode`; children become the complete watermark body.
365
369
  - `WatermarkInput`: `boolean | string | WatermarkOptions | ReactElement<WatermarkElementProps>`. `true` uses Vizmatic defaults. A string sets the watermark text. A React element can be `<Watermark>...</Watermark>` or any custom element.
366
370
  - `WatermarkImageOptions`: `src`, `width?: number`, `height?: number`, `alt?: string`. Programmatic `src` should be a URL or data URI. CLI `--watermark-image` accepts URL, data URI, or local path.
367
371
  - `WatermarkOptions`: `text?: string | false`, `image?: string | WatermarkImageOptions`, `icon?: ReactNode | string | false`, `element?: ReactNode`, `position?: "top-left" | "top-right" | "bottom-left" | "bottom-right" = "top-right"`, `opacity?: number`, `color?: string`.
372
+ - `normalizeWatermark(input)`: converts boolean, string, object, or React-element `WatermarkInput` to `WatermarkOptions | undefined`.
373
+ - `wrapWithBrand(element, width, height, theme?, label?)`: compatibility wrapper around `wrapWithWatermark`; theme defaults to `"dark"` and label defaults to `"Vizmatic"`.
374
+ - `getFonts()`: lazily loads and caches bundled Satori font data for advanced integrations.
375
+ - `loadAdditionalAsset(code, segment)`: Satori missing-glyph callback; resolves emoji segments to Twemoji data URIs and returns an empty font list for other codes.
368
376
  - `RenderOptions`: `width`, `height`, `outputPath`, `background?: "transparent" | "theme" | CSS color = "transparent"`, `theme?: "dark" | "light" = "dark"` for direct-render watermark defaults, `watermark?: WatermarkInput`, `brand?: boolean | string` as a compatibility alias, `crop?: boolean | "height" | "both" = true`, `scale?: number = 2`. Default autocrop retains 24 source pixels around detected content. Use `crop: "height"` when host layouts require stable width but should still trim extra vertical whitespace.
369
377
  - `renderToBuffer(element, width, height, options?)`: `options` supports `background?`, `theme?`, `watermark?`, `brand?`, `scale?`.
370
378
  - `renderToSvg(element, width, height, options?)`: `options` supports `background?`, `theme?`, `watermark?`, `brand?`.
package/README.md CHANGED
@@ -20,7 +20,7 @@
20
20
 
21
21
  <p align="center">
22
22
  <a href="https://bvolpato.github.io/vizmatic/">Website</a> ·
23
- <a href="https://bvolpato.github.io/vizmatic/#playground">Playground</a> ·
23
+ <a href="https://bvolpato.github.io/vizmatic/playground.html">Playground</a> ·
24
24
  <a href="examples">Examples</a> ·
25
25
  <a href="PROMPT.md">Agent Prompt</a> ·
26
26
  <a href="#api">API</a>
@@ -200,7 +200,7 @@ Vizmatic provides reusable layout, diagram, and chart primitives:
200
200
  <img src="https://bvolpato.github.io/vizmatic/assets/examples/presentation-frame_dark.png" alt="Presentation frame" width="380" />
201
201
  </p>
202
202
 
203
- More examples live in [`examples/`](examples) and on the [website](https://bvolpato.github.io/vizmatic/). [`PROMPT.md`](PROMPT.md) contains the full install, syntax, component, and verification reference for coding agents.
203
+ More examples live in [`examples/`](examples). The website has a searchable [component catalog](https://bvolpato.github.io/vizmatic/components.html) with a rendered preview and source for every public component. [`PROMPT.md`](PROMPT.md) contains the full install, syntax, component, and verification reference for coding agents.
204
204
 
205
205
  ## Repository checks
206
206
 
@@ -211,8 +211,9 @@ Generated examples and website files are committed. CI fails when a build change
211
211
  | `pnpm lint` | TypeScript coverage plus GitHub Actions validation with actionlint |
212
212
  | `pnpm test` | Render pipeline behavior, watermark options, and output validation |
213
213
  | `pnpm render:examples` | Dark/light PNGs, animated GIFs, source snippets, and website HTML |
214
+ | `pnpm check:examples` | Every example renders in both themes without errors or visual warnings |
214
215
  | `pnpm docs:check` | Local asset references, `PROMPT.md` sync, source modal themes, and homepage affordances |
215
- | `pnpm deps:check` | npm audit plus package tarball contents before release |
216
+ | `pnpm deps:check` | npm audit plus package tarball contents, size, and file-count budgets before release |
216
217
  | `./test.sh` drift check | Confirms render and docs commands leave no uncommitted output |
217
218
 
218
219
  Run the full local gate:
@@ -227,6 +228,8 @@ Vizmatic uses `react` for JSX frames, `satori` for layout, `@resvg/resvg-js` for
227
228
 
228
229
  Published packages include Inter, JetBrains Mono, Noto Sans, Noto Sans Math, and Twemoji SVGs under `assets/`, so normal CLI rendering does not fetch them at runtime. Set `VIZMATIC_FONT_DIR` or `VIZMATIC_ASSET_DIR` to use other local assets. Set `VIZMATIC_DISABLE_NETWORK=1` or `VIZMATIC_OFFLINE=1` to disable public fallbacks.
229
230
 
231
+ The complete Twemoji set is intentionally bundled so arbitrary emoji render offline. `pnpm deps:check` keeps that tradeoff bounded: the package must stay below 3.25 MB compressed, 12.5 MB unpacked, and 4,000 files.
232
+
230
233
  ## API
231
234
 
232
235
  ### Themes
@@ -372,11 +375,17 @@ Set `x` and `y` on every node for normalized manual positioning. Mixed coordinat
372
375
  | `renderToSvg` | Render SVG markup directly. |
373
376
  | `Watermark` | JSX marker component for expressive frame-module watermarks. |
374
377
  | `wrapWithWatermark` | Add optional watermark text, image/icon, custom element, and position to a frame. |
378
+ | `normalizeWatermark` | Normalize boolean, string, object, or React-element watermark input to `WatermarkOptions`. |
379
+ | `wrapWithBrand` | Compatibility wrapper for adding a text watermark through `wrapWithWatermark`. |
380
+ | `getFonts` | Load and cache bundled Satori font data for advanced renderer integrations. |
381
+ | `loadAdditionalAsset` | Resolve Satori missing-glyph requests, including bundled or cached Twemoji assets. |
375
382
  | `detectBackgroundColor` | Find dominant transparent/background color for cropping. |
376
383
  | `detectContentBounds` | Compute non-background bounds for autocrop. |
377
384
  | `cropPixels` | Crop raw pixel buffers. |
378
385
  | `detectOverflow` | Fail frames that clip content at canvas edges. |
379
386
 
387
+ Theme and chart helpers are public for custom primitives: `getReadableColor(name, c)` selects the highest-contrast semantic variant, `getReadableToneColor(tone, c, background?)` adapts tone text to a background, and `getReadableTextColor(background, c)` chooses a foreground meeting 4.5:1 contrast when possible. `createPlotArea(width, height, margin)` returns clamped chart geometry for custom axes and marks.
388
+
380
389
  ### Rendering
381
390
 
382
391
  ```ts
package/dist/cli.js CHANGED
@@ -97,6 +97,9 @@ __export(index_exports, {
97
97
  getColor: () => getColor,
98
98
  getFonts: () => getFonts,
99
99
  getGradient: () => getGradient,
100
+ getReadableColor: () => getReadableColor,
101
+ getReadableTextColor: () => getReadableTextColor,
102
+ getReadableToneColor: () => getReadableToneColor,
100
103
  getStyles: () => getStyles,
101
104
  getThemeColors: () => getThemeColors,
102
105
  getToneColor: () => getToneColor,
@@ -120,6 +123,7 @@ __export(index_exports, {
120
123
  });
121
124
 
122
125
  // src/theme.ts
126
+ import parseCssColor from "parse-css-color";
123
127
  var darkColors = {
124
128
  // Canvas backgrounds
125
129
  bg: "#151620",
@@ -162,7 +166,7 @@ var darkColors = {
162
166
  // Text
163
167
  textPrimary: "#f1f5f9",
164
168
  textSecondary: "#94a3b8",
165
- textMuted: "#64748b",
169
+ textMuted: "#8493a8",
166
170
  textOnColor: "#ffffff",
167
171
  // Borders
168
172
  border: "#334155",
@@ -204,7 +208,7 @@ var lightColors = {
204
208
  // Text
205
209
  textPrimary: "#0f172a",
206
210
  textSecondary: "#475569",
207
- textMuted: "#94a3b8",
211
+ textMuted: "#5b677a",
208
212
  textOnColor: "#ffffff",
209
213
  // Borders
210
214
  border: "#e2e8f0",
@@ -318,6 +322,24 @@ function getToneColor(tone, c) {
318
322
  dark: c.textSecondary
319
323
  }[tone];
320
324
  }
325
+ function getReadableToneColor(tone, c, background = c.bgCard) {
326
+ const semanticColor = {
327
+ blue: "secondary",
328
+ purple: "primary",
329
+ green: "positive",
330
+ warm: "warning",
331
+ cyan: "info",
332
+ pink: "accent",
333
+ red: "critical",
334
+ critical: "critical",
335
+ neutral: "neutral",
336
+ sunset: "warning",
337
+ ocean: "info",
338
+ dark: "neutral"
339
+ };
340
+ const color = getReadableColor(semanticColor[tone], c);
341
+ return colorContrast(color, background, c.bgCard) >= 4.5 ? color : getReadableTextColor(background, c);
342
+ }
321
343
  function getToneFill(tone, c) {
322
344
  if (c.preset !== "engineering") return `${getToneColor(tone, c)}16`;
323
345
  return {
@@ -415,6 +437,77 @@ function getColor(name, c) {
415
437
  if (c) return c[name];
416
438
  return colors[name];
417
439
  }
440
+ function getReadableColor(name, c) {
441
+ const variants = {
442
+ primary: [c.primaryLight, c.primary, c.primaryDark],
443
+ secondary: [c.secondaryLight, c.secondary, c.secondaryDark],
444
+ positive: [c.positiveLight, c.positive, c.positiveDark],
445
+ warning: [c.warningLight, c.warning, c.warningDark],
446
+ critical: [c.criticalLight, c.critical, c.criticalDark],
447
+ info: [c.infoLight, c.info, c.infoDark],
448
+ accent: [c.accentLight, c.accent, "#be185d"],
449
+ neutral: [c.textSecondary, c.neutralLight, c.neutral, c.neutralDark]
450
+ };
451
+ return variants[name].reduce((best, candidate) => colorContrast(candidate, c.bgCard) > colorContrast(best, c.bgCard) ? candidate : best);
452
+ }
453
+ function parseColor(color) {
454
+ const parsed = parseCssColor(color);
455
+ if (!parsed || parsed.values.length < 3) return void 0;
456
+ if (parsed.type !== "hsl") {
457
+ return {
458
+ channels: [parsed.values[0] ?? 0, parsed.values[1] ?? 0, parsed.values[2] ?? 0],
459
+ alpha: parsed.alpha
460
+ };
461
+ }
462
+ const hue = ((parsed.values[0] ?? 0) % 360 + 360) % 360;
463
+ const saturation = (parsed.values[1] ?? 0) / 100;
464
+ const lightness = (parsed.values[2] ?? 0) / 100;
465
+ const chroma = (1 - Math.abs(2 * lightness - 1)) * saturation;
466
+ const segment = hue / 60;
467
+ const intermediate = chroma * (1 - Math.abs(segment % 2 - 1));
468
+ let channels;
469
+ if (segment < 1) channels = [chroma, intermediate, 0];
470
+ else if (segment < 2) channels = [intermediate, chroma, 0];
471
+ else if (segment < 3) channels = [0, chroma, intermediate];
472
+ else if (segment < 4) channels = [0, intermediate, chroma];
473
+ else if (segment < 5) channels = [intermediate, 0, chroma];
474
+ else channels = [chroma, 0, intermediate];
475
+ const offset = lightness - chroma / 2;
476
+ return {
477
+ channels: channels.map((channel) => Math.round((channel + offset) * 255)),
478
+ alpha: parsed.alpha
479
+ };
480
+ }
481
+ function colorLuminance(color, backdrop) {
482
+ const parsed = parseColor(color);
483
+ if (!parsed) return void 0;
484
+ let channels = parsed.channels;
485
+ if (parsed.alpha < 1) {
486
+ const backdropColor = backdrop ? parseColor(backdrop) : void 0;
487
+ if (!backdropColor) return void 0;
488
+ channels = channels.map((channel, index) => Math.round(
489
+ channel * parsed.alpha + backdropColor.channels[index] * (1 - parsed.alpha)
490
+ ));
491
+ }
492
+ const [r, g, b] = channels.map((channel) => {
493
+ const normalized = channel / 255;
494
+ return normalized <= 0.04045 ? normalized / 12.92 : ((normalized + 0.055) / 1.055) ** 2.4;
495
+ });
496
+ return 0.2126 * r + 0.7152 * g + 0.0722 * b;
497
+ }
498
+ function colorContrast(left, right, rightBackdrop) {
499
+ const leftLuminance = colorLuminance(left);
500
+ const rightLuminance = colorLuminance(right, rightBackdrop);
501
+ if (leftLuminance == null || rightLuminance == null) return 0;
502
+ return (Math.max(leftLuminance, rightLuminance) + 0.05) / (Math.min(leftLuminance, rightLuminance) + 0.05);
503
+ }
504
+ function getReadableTextColor(background, c) {
505
+ if (colorLuminance(background, c.bgCard) == null) return c.textPrimary;
506
+ const candidates = [c.textPrimary, c.textOnColor, c.bg, "#000000"];
507
+ const readable = candidates.find((candidate) => colorContrast(candidate, background, c.bgCard) >= 4.5);
508
+ if (readable) return readable;
509
+ return candidates.reduce((best, candidate) => colorContrast(candidate, background, c.bgCard) > colorContrast(best, background, c.bgCard) ? candidate : best);
510
+ }
418
511
  function getGradient(name) {
419
512
  const map = {
420
513
  primary: gradients.purple,
@@ -1087,6 +1180,7 @@ function Box({
1087
1180
  }) {
1088
1181
  const solidColor = getColor(color, c);
1089
1182
  const gradientBg = getGradient(color);
1183
+ const solidTextColor = getReadableTextColor(solidColor, c);
1090
1184
  const style = {
1091
1185
  display: "flex",
1092
1186
  flexDirection: "column",
@@ -1118,7 +1212,7 @@ function Box({
1118
1212
  style: {
1119
1213
  fontSize,
1120
1214
  fontWeight: 700,
1121
- color: outlined ? solidColor : c.textOnColor,
1215
+ color: outlined ? solidColor : gradient ? c.textOnColor : solidTextColor,
1122
1216
  fontFamily: c.fontSans,
1123
1217
  textAlign: "center",
1124
1218
  lineHeight: 1.3
@@ -1128,7 +1222,7 @@ function Box({
1128
1222
  style: {
1129
1223
  fontSize: fontSize - 2,
1130
1224
  fontWeight: 400,
1131
- color: outlined ? c.textMuted : `${c.textOnColor}b3`,
1225
+ color: outlined ? c.textMuted : gradient ? `${c.textOnColor}b3` : solidTextColor,
1132
1226
  fontFamily: c.fontMono,
1133
1227
  textAlign: "center"
1134
1228
  }
@@ -1525,7 +1619,7 @@ function ValuePill({
1525
1619
  width = 112,
1526
1620
  math = false
1527
1621
  }) {
1528
- const accent = getToneColor(tone, c);
1622
+ const accent = getReadableToneColor(tone, c);
1529
1623
  return Card({
1530
1624
  c,
1531
1625
  tone,
@@ -1579,7 +1673,7 @@ function EquationCard({
1579
1673
  math = false,
1580
1674
  align = "left"
1581
1675
  }) {
1582
- const accent = getToneColor(tone, c);
1676
+ const accent = getReadableToneColor(tone, c);
1583
1677
  const textAlign = align;
1584
1678
  return Card({
1585
1679
  c,
@@ -1646,6 +1740,7 @@ function BadgePill({
1646
1740
  math = false
1647
1741
  }) {
1648
1742
  const accent = getToneColor(tone, c);
1743
+ const accentText = getReadableToneColor(tone, c);
1649
1744
  const engineering = c.preset === "engineering";
1650
1745
  return React3.createElement("div", {
1651
1746
  style: {
@@ -1659,7 +1754,7 @@ function BadgePill({
1659
1754
  borderRadius: engineering ? Math.min(radius, 5) : radius,
1660
1755
  ...engineering ? { backgroundColor: getToneFill(tone, c) } : filled ? { backgroundImage: getToneGradient(tone) } : { backgroundColor: `${accent}18` },
1661
1756
  border: `1px solid ${engineering ? accent : filled ? `${accent}00` : `${accent}55`}`,
1662
- color: engineering ? c.textPrimary : filled ? c.textOnColor : accent,
1757
+ color: engineering ? c.textPrimary : filled ? c.textOnColor : accentText,
1663
1758
  fontSize,
1664
1759
  fontWeight: 800,
1665
1760
  lineHeight: 1,
@@ -1748,6 +1843,7 @@ function StepCard({
1748
1843
  math = false
1749
1844
  }) {
1750
1845
  const accent = getToneColor(tone, c);
1846
+ const accentText = getReadableToneColor(tone, c);
1751
1847
  const engineering = c.preset === "engineering";
1752
1848
  const textAlign = align;
1753
1849
  return Card({
@@ -1788,7 +1884,7 @@ function StepCard({
1788
1884
  style: {
1789
1885
  ...typography.label,
1790
1886
  fontFamily: c.fontSans,
1791
- color: engineering ? c.textPrimary : accent,
1887
+ color: engineering ? c.textPrimary : accentText,
1792
1888
  fontWeight: 700,
1793
1889
  lineHeight: 1.15,
1794
1890
  ...textFitStyle(textAlign)
@@ -1825,6 +1921,7 @@ function MetricCard({
1825
1921
  valueColor
1826
1922
  }) {
1827
1923
  const accent = getToneColor(tone, c);
1924
+ const accentText = getReadableToneColor(tone, c);
1828
1925
  const textAlign = align;
1829
1926
  return Card({
1830
1927
  c,
@@ -1852,7 +1949,7 @@ function MetricCard({
1852
1949
  style: {
1853
1950
  fontSize: 11,
1854
1951
  fontWeight: 800,
1855
- color: accent,
1952
+ color: accentText,
1856
1953
  fontFamily: c.fontSans,
1857
1954
  lineHeight: 1.1,
1858
1955
  ...textFitStyle(textAlign)
@@ -1897,6 +1994,7 @@ function ProgressRow({
1897
1994
  fontSize = 11
1898
1995
  }) {
1899
1996
  const accent = muted ? c.textMuted : getToneColor(tone, c);
1997
+ const accentText = muted ? c.textMuted : getReadableToneColor(tone, c);
1900
1998
  const pct = Math.round(Math.max(0, Math.min(1, value)) * 100);
1901
1999
  return React4.createElement(
1902
2000
  "div",
@@ -1943,7 +2041,7 @@ function ProgressRow({
1943
2041
  React4.createElement("div", {
1944
2042
  style: {
1945
2043
  width: valueWidth,
1946
- color: accent,
2044
+ color: accentText,
1947
2045
  fontSize,
1948
2046
  fontWeight: 800,
1949
2047
  fontFamily: "JetBrains Mono",
@@ -2029,7 +2127,7 @@ function MiniBarChart({
2029
2127
  ...compactChildren([
2030
2128
  showValues && React4.createElement("div", {
2031
2129
  style: {
2032
- color: getToneColor(tone, c),
2130
+ color: getReadableToneColor(tone, c),
2033
2131
  fontFamily: "JetBrains Mono",
2034
2132
  fontSize,
2035
2133
  fontWeight: 800,
@@ -2108,6 +2206,7 @@ function Tile({
2108
2206
  math = false
2109
2207
  }) {
2110
2208
  const accent = getToneColor(tone, c);
2209
+ const accentText = getReadableToneColor(tone, c);
2111
2210
  const textAlign = align;
2112
2211
  const crossAlign = align === "center" ? "center" : "flex-start";
2113
2212
  const detailLines = (lines ?? []).map((line, index) => React4.createElement(
@@ -2175,7 +2274,7 @@ function Tile({
2175
2274
  React4.createElement("div", {
2176
2275
  style: {
2177
2276
  ...typography.label,
2178
- color: accent,
2277
+ color: accentText,
2179
2278
  fontWeight: 800,
2180
2279
  lineHeight: 1.15,
2181
2280
  textAlign
@@ -2265,7 +2364,8 @@ function CodeBlock({
2265
2364
  const lineElements = lines.map((line, index) => {
2266
2365
  const spec = isCodeLineSpec(line) ? line : { text: line };
2267
2366
  const accent = spec.tone ? getToneColor(spec.tone, c) : void 0;
2268
- const textColor = spec.dim ? c.textMuted : accent ?? c.textSecondary;
2367
+ const accentText = spec.tone ? getReadableToneColor(spec.tone, c) : void 0;
2368
+ const textColor = spec.dim ? c.textMuted : accentText ?? c.textSecondary;
2269
2369
  return React4.createElement(
2270
2370
  "div",
2271
2371
  {
@@ -2299,7 +2399,7 @@ function CodeBlock({
2299
2399
  style: {
2300
2400
  display: "flex",
2301
2401
  flexShrink: 0,
2302
- color: accent ?? c.textMuted,
2402
+ color: accentText ?? c.textMuted,
2303
2403
  fontFamily: "JetBrains Mono",
2304
2404
  fontWeight: 800,
2305
2405
  fontSize,
@@ -2476,7 +2576,7 @@ function KeyValueList({
2476
2576
  math = false
2477
2577
  }) {
2478
2578
  const rowElements = rows.map((row, index) => {
2479
- const accent = row.tone ? getToneColor(row.tone, c) : void 0;
2579
+ const accent = row.tone ? getReadableToneColor(row.tone, c) : void 0;
2480
2580
  const isLast = index === rows.length - 1;
2481
2581
  const valueMono = row.valueMono ?? true;
2482
2582
  return React4.createElement(
@@ -2566,7 +2666,7 @@ function WindowFrame({
2566
2666
  }) {
2567
2667
  const isTerminal = variant === "terminal";
2568
2668
  const surface = background ?? (isTerminal ? c.bgSubtle : c.bgCard);
2569
- const accent = getToneColor(tone, c);
2669
+ const titleColor = isTerminal ? getReadableToneColor(tone, c, c.bgHover) : c.textSecondary;
2570
2670
  const trafficDot = (color, key) => React4.createElement("span", {
2571
2671
  key,
2572
2672
  style: { display: "flex", width: 10, height: 10, borderRadius: 999, backgroundColor: color }
@@ -2616,7 +2716,7 @@ function WindowFrame({
2616
2716
  display: "flex",
2617
2717
  flex: 1,
2618
2718
  justifyContent: dots ? "center" : "flex-start",
2619
- color: isTerminal ? accent : c.textSecondary,
2719
+ color: titleColor,
2620
2720
  fontFamily: isTerminal ? "JetBrains Mono" : "Inter",
2621
2721
  fontSize: 12,
2622
2722
  fontWeight: 700,
@@ -2690,7 +2790,9 @@ function StatusRow({
2690
2790
  width,
2691
2791
  math = false
2692
2792
  }) {
2693
- const accent = getToneColor(tone ?? statusTones[status], c);
2793
+ const resolvedTone = tone ?? statusTones[status];
2794
+ const accent = getToneColor(resolvedTone, c);
2795
+ const accentText = getReadableToneColor(resolvedTone, c);
2694
2796
  const glyph = statusGlyphs[status];
2695
2797
  const marker = React5.createElement("div", {
2696
2798
  style: {
@@ -2703,7 +2805,7 @@ function StatusRow({
2703
2805
  borderRadius: 999,
2704
2806
  backgroundColor: status === "dot" ? accent : `${accent}26`,
2705
2807
  border: `1px solid ${accent}`,
2706
- color: accent,
2808
+ color: accentText,
2707
2809
  fontFamily: "Inter",
2708
2810
  fontSize: status === "warn" || status === "info" ? 12 : 11,
2709
2811
  fontWeight: 900,
@@ -2773,7 +2875,9 @@ function StatusList({
2773
2875
  });
2774
2876
  }
2775
2877
  function renderTimelineCard(event, c, math, width) {
2776
- const accent = getToneColor(event.tone ?? statusTones[event.status ?? "dot"], c);
2878
+ const resolvedTone = event.tone ?? statusTones[event.status ?? "dot"];
2879
+ const accent = getToneColor(resolvedTone, c);
2880
+ const accentText = getReadableToneColor(resolvedTone, c);
2777
2881
  const resolvedWidth = event.width ?? width;
2778
2882
  return React5.createElement(
2779
2883
  "div",
@@ -2796,7 +2900,7 @@ function renderTimelineCard(event, c, math, width) {
2796
2900
  event.time != null && React5.createElement("div", {
2797
2901
  style: {
2798
2902
  display: "flex",
2799
- color: accent,
2903
+ color: accentText,
2800
2904
  fontFamily: "JetBrains Mono",
2801
2905
  fontSize: 11,
2802
2906
  fontWeight: 900,
@@ -3175,7 +3279,7 @@ function LayeredNetwork({
3175
3279
  }
3176
3280
  }, formatMathText(text));
3177
3281
  const titleElements = nodeLayout.map(
3178
- (layer) => label(`title-${layer.title}`, layer.title, layer.x, 20, 120, getToneColor(layer.tone, c), 16, 900)
3282
+ (layer) => label(`title-${layer.title}`, layer.title, layer.x, 20, 120, getReadableToneColor(layer.tone, c), 16, 900)
3179
3283
  );
3180
3284
  const nodeElements = nodeLayout.flatMap(
3181
3285
  (layer, layerIndex) => layer.ys.flatMap((y, nodeIndex) => {
@@ -3210,7 +3314,7 @@ function LayeredNetwork({
3210
3314
  alignItems: "center",
3211
3315
  justifyContent: "center",
3212
3316
  backgroundColor: color,
3213
- color: c.textOnColor,
3317
+ color: getReadableTextColor(color, c),
3214
3318
  border: active ? `3px solid ${c.warningLight}` : `1.5px solid ${color}`,
3215
3319
  boxSizing: "border-box",
3216
3320
  boxShadow: active ? `0 0 16px ${c.warningLight}70` : `0 8px 14px ${c.shadow}`,
@@ -3613,7 +3717,7 @@ function GraphDiagram({
3613
3717
  borderRadius: c.preset === "engineering" ? 0 : 999,
3614
3718
  backgroundColor: c.preset === "engineering" ? c.bg : c.bgCard,
3615
3719
  border: c.preset === "engineering" ? "none" : `1px solid ${c.borderSubtle}`,
3616
- color: edge.muted ? c.textMuted : c.preset === "engineering" ? c.textSecondary : edge.color,
3720
+ color: edge.muted ? c.textMuted : c.preset === "engineering" ? c.textSecondary : getReadableToneColor(edge.tone ?? "blue", c),
3617
3721
  fontFamily: c.fontMono,
3618
3722
  fontSize: 11,
3619
3723
  fontWeight: c.preset === "engineering" ? 400 : 800,
@@ -3628,6 +3732,7 @@ function GraphDiagram({
3628
3732
  ] : []),
3629
3733
  ...Array.from(layout.values()).map((node) => {
3630
3734
  const accent = node.muted ? c.textMuted : getToneColor(node.tone ?? "blue", c);
3735
+ const accentText = node.muted ? c.textMuted : getReadableToneColor(node.tone ?? "blue", c);
3631
3736
  return React6.createElement(
3632
3737
  "div",
3633
3738
  {
@@ -3650,7 +3755,7 @@ function GraphDiagram({
3650
3755
  border: `${c.preset === "engineering" ? 1.25 : 1.5}px solid ${node.muted ? c.borderLight : `${accent}${c.preset === "engineering" ? "" : "88"}`}`,
3651
3756
  ...!node.muted && c.preset !== "engineering" ? { boxShadow: `0 8px 18px ${c.shadow}` } : {},
3652
3757
  opacity: node.muted ? 0.62 : 1,
3653
- color: c.preset === "engineering" ? c.textPrimary : accent,
3758
+ color: c.preset === "engineering" ? c.textPrimary : accentText,
3654
3759
  textAlign: "center"
3655
3760
  }
3656
3761
  },
@@ -3826,6 +3931,7 @@ function TreeDiagram({
3826
3931
  })),
3827
3932
  ...positioned.map((node) => {
3828
3933
  const accent = node.muted ? c.textMuted : getToneColor(node.tone ?? "blue", c);
3934
+ const accentText = node.muted ? c.textMuted : getReadableToneColor(node.tone ?? "blue", c);
3829
3935
  return React6.createElement(
3830
3936
  "div",
3831
3937
  {
@@ -3848,13 +3954,13 @@ function TreeDiagram({
3848
3954
  border: `1.5px solid ${node.muted ? c.borderLight : `${accent}88`}`,
3849
3955
  ...!node.muted ? { boxShadow: `0 8px 18px ${c.shadow}` } : {},
3850
3956
  opacity: node.muted ? 0.62 : 1,
3851
- color: accent,
3957
+ color: accentText,
3852
3958
  textAlign: "center"
3853
3959
  }
3854
3960
  },
3855
3961
  React6.createElement("div", {
3856
3962
  style: {
3857
- color: accent,
3963
+ color: accentText,
3858
3964
  fontFamily: "Inter",
3859
3965
  fontSize: 13,
3860
3966
  fontWeight: 900,
@@ -3893,6 +3999,7 @@ function CalloutCard({
3893
3999
  align = "center"
3894
4000
  }) {
3895
4001
  const accent = getToneColor(tone, c);
4002
+ const accentText = getReadableToneColor(tone, c);
3896
4003
  const engineering = c.preset === "engineering";
3897
4004
  const textAlign = align;
3898
4005
  return React6.createElement(
@@ -3919,7 +4026,7 @@ function CalloutCard({
3919
4026
  style: {
3920
4027
  ...typography.small,
3921
4028
  ...titleFontSize != null ? { fontSize: titleFontSize } : {},
3922
- color: engineering ? c.textPrimary : filled ? c.textOnColor : accent,
4029
+ color: engineering ? c.textPrimary : filled ? c.textOnColor : accentText,
3923
4030
  fontFamily: c.fontSans,
3924
4031
  fontWeight: 900,
3925
4032
  lineHeight: 1.2,
@@ -4096,8 +4203,9 @@ function Matrix({
4096
4203
  fontFamily: "JetBrains Mono"
4097
4204
  }
4098
4205
  }, rowLabels[ri]),
4099
- ...row.map(
4100
- (value, ci) => React7.createElement("div", {
4206
+ ...row.map((value, ci) => {
4207
+ const backgroundColor = colorize ? cellColor(value) : c.bgCard;
4208
+ return React7.createElement("div", {
4101
4209
  key: `cell-${ri}-${ci}`,
4102
4210
  style: {
4103
4211
  width: resolvedCellWidth,
@@ -4105,15 +4213,15 @@ function Matrix({
4105
4213
  display: "flex",
4106
4214
  alignItems: "center",
4107
4215
  justifyContent: "center",
4108
- backgroundColor: colorize ? cellColor(value) : c.bgCard,
4216
+ backgroundColor,
4109
4217
  borderRadius: 6,
4110
4218
  fontSize: 11,
4111
4219
  fontWeight: 600,
4112
- color: !colorize ? c.textPrimary : colorScale === "strength" && value < 0.34 ? c.textSecondary : c.textOnColor,
4220
+ color: colorize ? getReadableTextColor(backgroundColor, c) : c.textPrimary,
4113
4221
  fontFamily: "JetBrains Mono"
4114
4222
  }
4115
- }, labels?.[ri]?.[ci] ?? formatValue(value))
4116
- )
4223
+ }, labels?.[ri]?.[ci] ?? formatValue(value));
4224
+ })
4117
4225
  )
4118
4226
  )
4119
4227
  )
@@ -4261,7 +4369,7 @@ function TiledMatrix({
4261
4369
  ...compactChildren([
4262
4370
  title && React7.createElement("div", {
4263
4371
  style: {
4264
- color: muted ? c.textMuted : baseAccent,
4372
+ color: muted ? c.textMuted : getReadableToneColor(tone, c),
4265
4373
  fontFamily: "Inter",
4266
4374
  fontSize: 13,
4267
4375
  fontWeight: 900,
@@ -4362,6 +4470,7 @@ function Grid({
4362
4470
  const cellStyle = (cell, rowIndex, colIndex) => {
4363
4471
  const config = isGridCell(cell) ? cell : {};
4364
4472
  const toneColor = config.tone ? getToneColor(config.tone, c) : void 0;
4473
+ const toneTextColor = config.tone ? getReadableToneColor(config.tone, c) : void 0;
4365
4474
  const isHeader = rowIndex < headerRows || colIndex < headerCols;
4366
4475
  return {
4367
4476
  width: cellWidth,
@@ -4372,7 +4481,7 @@ function Grid({
4372
4481
  borderRadius: radius,
4373
4482
  backgroundColor: config.backgroundColor ?? (toneColor ? `${toneColor}22` : isHeader ? c.bgSubtle : c.bgHover),
4374
4483
  border: `1px solid ${config.borderColor ?? (toneColor ? `${toneColor}55` : c.borderSubtle)}`,
4375
- color: config.color ?? (toneColor ?? (isHeader ? c.textPrimary : c.textSecondary)),
4484
+ color: config.color ?? (toneTextColor ?? (isHeader ? c.textPrimary : c.textSecondary)),
4376
4485
  ...config.opacity !== void 0 ? { opacity: config.opacity } : {},
4377
4486
  fontFamily: "JetBrains Mono",
4378
4487
  fontSize,
@@ -4631,8 +4740,9 @@ function isColorName(value) {
4631
4740
  return chartPalette.includes(value) || value === "neutral";
4632
4741
  }
4633
4742
  function chartColor(color, c, index = 0) {
4634
- if (!color) return getColor(chartPalette[index % chartPalette.length], c);
4635
- return isColorName(color) ? getColor(color, c) : color;
4743
+ const resolved = color ?? chartPalette[index % chartPalette.length];
4744
+ if (!isColorName(resolved)) return resolved;
4745
+ return getReadableColor(resolved, c);
4636
4746
  }
4637
4747
  function formatChartValue(value, format = "decimal") {
4638
4748
  if (typeof format === "function") return format(value);
@@ -5109,7 +5219,7 @@ function StackedBar({
5109
5219
  segmentWidth >= 64 && React8.createElement("span", {
5110
5220
  style: {
5111
5221
  ...typography.small,
5112
- color: c.textOnColor,
5222
+ color: getReadableTextColor(color, c),
5113
5223
  fontWeight: 900,
5114
5224
  whiteSpace: "nowrap"
5115
5225
  }
@@ -5722,7 +5832,7 @@ function IntervalPlot({
5722
5832
  });
5723
5833
  }
5724
5834
  function Badge({ label, c, color = "primary" }) {
5725
- const solidColor = getColor(color, c);
5835
+ const solidColor = getReadableColor(color, c);
5726
5836
  return React9.createElement("div", {
5727
5837
  style: {
5728
5838
  display: "flex",
@@ -5739,7 +5849,7 @@ function Badge({ label, c, color = "primary" }) {
5739
5849
  }
5740
5850
  }, label);
5741
5851
  }
5742
- function DotPoint({ x, y, label, color, size = 12, labelOffset }) {
5852
+ function DotPoint({ x, y, label, color, c, size = 12, labelOffset }) {
5743
5853
  const offX = labelOffset?.x ?? 0;
5744
5854
  const offY = labelOffset?.y ?? -22;
5745
5855
  return [
@@ -5767,7 +5877,7 @@ function DotPoint({ x, y, label, color, size = 12, labelOffset }) {
5767
5877
  top: y + offY,
5768
5878
  fontSize: 13,
5769
5879
  fontWeight: 600,
5770
- color,
5880
+ color: c.textPrimary,
5771
5881
  fontFamily: "JetBrains Mono",
5772
5882
  textAlign: "center",
5773
5883
  width: 60
@@ -6575,7 +6685,7 @@ import { Resvg as Resvg2 } from "@resvg/resvg-js";
6575
6685
  import { mkdir as mkdir2, writeFile as writeFile2 } from "fs/promises";
6576
6686
  import { dirname as dirname2 } from "path";
6577
6687
  import * as gifenc from "gifenc";
6578
- import parseCssColor from "parse-css-color";
6688
+ import parseCssColor2 from "parse-css-color";
6579
6689
  function resolveGifenc(api) {
6580
6690
  if (typeof api.GIFEncoder === "function" && typeof api.applyPalette === "function" && typeof api.quantize === "function") {
6581
6691
  return api;
@@ -6644,7 +6754,7 @@ function hslToRgb(hue, saturation, lightness) {
6644
6754
  }
6645
6755
  function colorForBackground(background, theme) {
6646
6756
  const value = background === "theme" ? getThemeColors(theme).bg : background;
6647
- const parsed = parseCssColor(value);
6757
+ const parsed = parseCssColor2(value);
6648
6758
  if (!parsed) throw new Error(`Invalid animation background color: ${value}`);
6649
6759
  const [r, g, b] = parsed.type === "hsl" ? hslToRgb(parsed.values[0], parsed.values[1], parsed.values[2]) : [parsed.values[0], parsed.values[1], parsed.values[2]];
6650
6760
  return { r, g, b, a: Math.round(parsed.alpha * 255) };
@@ -6880,7 +6990,7 @@ function findBareRootJsxStart(source) {
6880
6990
  }
6881
6991
 
6882
6992
  // src/diagnostics.ts
6883
- import parseCssColor2 from "parse-css-color";
6993
+ import parseCssColor3 from "parse-css-color";
6884
6994
  import { Children, isValidElement } from "react";
6885
6995
  var MAX_CONTRAST_NODES = 5e3;
6886
6996
  var MAX_DIAGNOSTICS_PER_RULE = 12;
@@ -6904,7 +7014,7 @@ function hslToRgb2(hue, saturation, lightness) {
6904
7014
  }
6905
7015
  function colorFromCss(value) {
6906
7016
  if (typeof value !== "string") return void 0;
6907
- const parsed = parseCssColor2(value);
7017
+ const parsed = parseCssColor3(value);
6908
7018
  if (!parsed || parsed.values.length < 3 || parsed.alpha < 0.95) return void 0;
6909
7019
  const [r, g, b] = parsed.type === "hsl" ? hslToRgb2(parsed.values[0] ?? 0, parsed.values[1] ?? 0, parsed.values[2] ?? 0) : [parsed.values[0] ?? 0, parsed.values[1] ?? 0, parsed.values[2] ?? 0];
6910
7020
  return {
@@ -6980,7 +7090,9 @@ function analyzeContrast(element, theme, trustedComponents = /* @__PURE__ */ new
6980
7090
  }
6981
7091
  const props = node.props;
6982
7092
  const style = typeof node.type === "string" ? styleRecord(props.style) : {};
6983
- const background = colorFromCss(style.backgroundColor) ?? colorFromCss(style.background) ?? inherited.background;
7093
+ const backgroundImage = typeof style.backgroundImage === "string" ? style.backgroundImage.trim().toLowerCase() : "";
7094
+ const hasUnresolvedBackground = backgroundImage !== "" && backgroundImage !== "none" || typeof style.background === "string" && style.background.includes("gradient(");
7095
+ const background = hasUnresolvedBackground ? void 0 : colorFromCss(style.backgroundColor) ?? colorFromCss(style.background) ?? inherited.background;
6984
7096
  const color = colorFromCss(style.color) ?? inherited.color;
6985
7097
  const fontSize = fontSizePixels(style.fontSize, inherited.fontSize);
6986
7098
  const fontWeight = numericFontWeight(style.fontWeight) ?? inherited.fontWeight;