@taylorwong/ichartjs 2.0.4 → 2.0.6

package/src/index.mjs

@@ -20,11 +20,14 @@ import { diagramLayoutModes, edgeRoutingModes, normalizeDiagramSpec, validateDia
 import { normalizeProjectCalendar, applyWorkingCalendar, normalizeDependencies, analyzeSchedule, analyzeBurndownSeries, analyzeCapacity, buildCapacityView, buildCumulativeFlowSeries, buildVelocitySeries, buildReleaseForecast, buildRiskMatrixSeries, buildIssueAgingSeries } from './project-analytics.mjs';
 import { normalizeLinkedFilters, normalizeLinkedSelection, filterProjectRows, createLinkedProjectState, linkedRecordId } from './project-linking.mjs';
 import { explainChart, getCapabilities as discoverCapabilities, getChartCapability, planChart } from './capabilities.mjs';
+import { applyPreferencesToSpec, createPreferencesStore, defaultPreferences, mergePreferences, mergeThemePreference, normalizePreferences } from './preferences.mjs';
+import { mountChartSettings } from './preferences-ui.mjs';
 
 import { isDiagram, paintSelection, diagramPointer, diagramKeyboard } from './diagram-interaction.mjs';
 
 function resolveContainer(container) { return typeof container === 'string' ? document.querySelector(container) : container; }
 function clone(value) { return value == null ? value : JSON.parse(JSON.stringify(value)); }
+function isPreferencesStore(value) { return Boolean(value && typeof value.getEffective === 'function' && typeof value.setChart === 'function' && typeof value.subscribe === 'function'); }
 export function resolveZoomWindow(count, current, factor) {
   const total = Math.max(0, Math.round(Number(count) || 0));
   if (total <= 1) return { start: 0, end: total };
@@ -54,6 +57,12 @@ function _svgStyleFontParts(raw = '') {
     .trim();
   return { size, weight, family };
 }
+const NO_PAINT_TOKENS = new Set(['none', 'transparent', '']);
+function hasPaint(style, key) {
+  const value = style?.[key];
+  if (value == null) return false;
+  return typeof value !== 'string' || !NO_PAINT_TOKENS.has(value.trim().toLowerCase());
+}
 function sceneToSvgString(scene, spec = {}) {
   const w = Number(scene?.width ?? spec?.width ?? 640);
   const h = Number(scene?.height ?? spec?.height ?? 360);
@@ -114,9 +123,10 @@ function sceneToSvgString(scene, spec = {}) {
     } else {
       tag = 'g';
     }
-    if (node.type === 'path' && !s.fill) attrs.push(`fill="none"`);
-    else if (s.fill) attrs.push(`fill="${_svgEscape(s.fill, 'attr')}"`);
-    if (s.stroke) attrs.push(`stroke="${_svgEscape(s.stroke, 'attr')}"`);
+    if (['path', 'circle', 'rect', 'arc'].includes(node.type)) attrs.push(`fill="${hasPaint(s, 'fill') ? _svgEscape(s.fill, 'attr') : 'none'}"`);
+    else if (node.type === 'text') attrs.push(`fill="${hasPaint(s, 'fill') ? _svgEscape(s.fill, 'attr') : '#0f172a'}"`);
+    if (hasPaint(s, 'stroke')) attrs.push(`stroke="${_svgEscape(s.stroke, 'attr')}"`);
+    else if (s.stroke != null) attrs.push('stroke="none"');
     if (s.strokeWidth) attrs.push(`stroke-width="${s.strokeWidth}"`);
     if (s.opacity != null) {
       const opacity = (node.highlighted || node.selected) ? 1 : s.opacity;
@@ -145,15 +155,49 @@ function sceneToSvgString(scene, spec = {}) {
   lines.push(`</svg>`);
   return lines.join('\n');
 }
+function exportError(code, message, suggestion, extra = {}) { return { valid: false, code, message, suggestion, ...extra }; }
+function dataUrlToBlob(dataUrl, mime) {
+  if (typeof Blob === 'undefined') return exportError('BLOB_HEADLESS', 'Blob is not available in this runtime.', 'Use as=dataurl or as=string.');
+  const comma = dataUrl.indexOf(',');
+  if (comma < 0) return exportError('EXPORT_UNSUPPORTED', 'The renderer returned an invalid data URL.', 'Use chart.export({ type: "svg" }) and inspect the returned string.');
+  const header = dataUrl.slice(0, comma), payload = dataUrl.slice(comma + 1);
+  const bytes = /;base64$/i.test(header)
+    ? Uint8Array.from(atob(payload), value => value.charCodeAt(0))
+    : new TextEncoder().encode(decodeURIComponent(payload));
+  return new Blob([bytes], { type: mime });
+}
+function canvasFactoryFromModule(module) { return module?.createCanvas || module?.default?.createCanvas || null; }
+function renderRasterWithCanvas(createCanvas, spec, scene, rasterType, as) {
+  const canvas = createCanvas(spec.width, spec.height), renderer = new CanvasRenderer({ ...spec });
+  renderer.canvas = canvas;
+  renderer.ctx = canvas.getContext('2d');
+  if (!renderer.ctx) return exportError('HEADLESS_EXPORT_UNSUPPORTED', 'The optional canvas package did not provide a 2D context.', 'Install a supported canvas implementation or use SVG export.');
+  renderer.resize(spec.width, spec.height);
+  renderer.render(scene);
+  const dataUrl = renderer.exportImage(rasterType);
+  if (as === 'blob') return dataUrlToBlob(dataUrl, rasterType);
+  return dataUrl;
+}
 
 export class Chart {
   constructor(input = {}) {
-    const result = validateSpec(input);
+    const specInput = { ...input };
+    delete specInput.preferences;
+    delete specInput.preferencesStore;
+    delete specInput.chartId;
+    const result = validateSpec(specInput);
     if (!result.valid) { const error = new Error(result.errors.map(item => item.message).join(' ')); error.details = result.errors; throw error; }
     this._specDiagnostics = { warnings: result.warnings, normalizations: result.normalizations };
+    this.chartId = input.chartId ?? input.id ?? null;
+    this._preferencesStore = isPreferencesStore(input.preferencesStore) ? input.preferencesStore : isPreferencesStore(input.preferences) ? input.preferences : null;
+    this._localPreferences = this._preferencesStore ? null : normalizePreferences(input.preferences || {});
+    delete result.spec.preferences;
+    delete result.spec.preferencesStore;
+    delete result.spec.chartId;
     this._themeInput = input.theme ?? 'auto';
     this._styleOverrides = { colors: input.colors !== undefined, background: input.background !== undefined, padding: input.padding !== undefined };
     this.spec = result.spec;
+    this._preferenceBase = Object.fromEntries(['legend', 'labels', 'grid', 'branding', 'padding'].map(key => [key, clone(this.spec[key])]));
     this._resolveStyle();
     this.container = typeof document === 'undefined' ? null : resolveContainer(this.spec.container);
     this.listeners = new Map();
@@ -168,12 +212,26 @@ export class Chart {
     this._observeResize();
     this._observeColorScheme();
     this.render();
+    this._preferencesSnapshot = JSON.stringify(this.getPreferences());
+    if (this._preferencesStore) this._preferencesUnsubscribe = this._preferencesStore.subscribe(event => {
+      const next = this._preferencesStore.getEffective(this.chartId);
+      const serialized = JSON.stringify(next);
+      if (serialized === this._preferencesSnapshot) return;
+      this._preferencesSnapshot = serialized;
+      this._resolveStyle();
+      this.render();
+      this.emit('preferenceschange', { chart: this, preferences: clone(next), source: event.source, scope: event.scope, persisted: event.persisted });
+    });
   }
   _resolveStyle() {
-    this.spec.theme = resolveTheme(this._themeInput, this.spec);
+    ['legend', 'labels', 'grid', 'branding'].forEach(key => { this.spec[key] = clone(this._preferenceBase[key]); });
+    if (this._styleOverrides.padding) this.spec.padding = clone(this._preferenceBase.padding);
+    const preferences = this.getPreferences();
+    this.spec.theme = resolveTheme(mergeThemePreference(this._themeInput, preferences.theme), this.spec);
     if (!this._styleOverrides.colors) this.spec.colors = [...this.spec.theme.colors];
     if (!this._styleOverrides.background) this.spec.background = this.spec.theme.background;
     if (!this._styleOverrides.padding) this.spec.padding = clone(this.spec.theme.layout.padding);
+    this.spec = applyPreferencesToSpec(this.spec, preferences);
   }
   _observeColorScheme() {
     if (typeof matchMedia !== 'function') return;
@@ -269,13 +327,16 @@ export class Chart {
   on(type, listener) { if (!this.listeners.has(type)) this.listeners.set(type, new Set()); this.listeners.get(type).add(listener); return this; }
   off(type, listener) { this.listeners.get(type)?.delete(listener); return this; }
   emit(type, event) { this.listeners.get(type)?.forEach(listener => listener(event)); }
-  update(next = {}) { this._editor.invalidate(); if (next.theme !== undefined) this._themeInput = next.theme; ['colors', 'background', 'padding'].forEach(key => { if (next[key] !== undefined) this._styleOverrides[key] = true; }); this.spec = normalizeSpec({ ...this.spec, ...next, theme: this._themeInput, data: next.data === undefined ? this.spec.data : next.data }); this._resolveStyle(); return this.render(); }
+  update(next = {}) { this._editor.invalidate(); const { preferences, preferencesStore, chartId, ...specUpdate } = next || {}; if (preferences !== undefined) this.setPreferences(preferences); if (specUpdate.theme !== undefined) this._themeInput = specUpdate.theme; ['colors', 'background', 'padding'].forEach(key => { if (specUpdate[key] !== undefined) this._styleOverrides[key] = true; }); this.spec = normalizeSpec({ ...this.spec, ...specUpdate, theme: this._themeInput, data: specUpdate.data === undefined ? this.spec.data : specUpdate.data }); ['legend', 'labels', 'grid', 'branding', 'padding'].forEach(key => { if (specUpdate[key] !== undefined) this._preferenceBase[key] = clone(this.spec[key]); }); this._resolveStyle(); return this.render(); }
   setData(data) { this._editor.invalidate(); this.spec = normalizeSpec({ ...this.spec, theme: this._themeInput, data: { values: data } }); this._resolveStyle(); return this.render(); }
   setTheme(theme = 'auto') { this._themeInput = theme; this._resolveStyle(); this.render(); this.emit('themechange', { chart: this, theme: this.getTheme(), source: 'user' }); return this; }
   getTheme() { return clone(this.spec.theme); }
+  getPreferences() { return this._preferencesStore ? this._preferencesStore.getEffective(this.chartId) : clone(this._localPreferences || defaultPreferences); }
+  setPreferences(patch = {}, options = {}) { if (this._preferencesStore) { const scope = options.scope === 'global' ? 'global' : 'chart'; if (scope === 'global') this._preferencesStore.setGlobal(patch, { ...options, source: options.source || 'user' }); else this._preferencesStore.setChart(this.chartId || 'default', patch, { ...options, source: options.source || 'user' }); return this; } this._localPreferences = mergePreferences(this._localPreferences, patch); this._preferencesSnapshot = JSON.stringify(this._localPreferences); this._resolveStyle(); this.render(); this.emit('preferenceschange', { chart: this, preferences: this.getPreferences(), source: options.source || 'user', scope: 'chart', persisted: false }); return this; }
+  resetPreferences(options = {}) { if (this._preferencesStore) { this._preferencesStore.reset({ ...options, scope: options.scope || 'chart', chartId: this.chartId || 'default' }); return this; } this._localPreferences = normalizePreferences({}); this._preferencesSnapshot = JSON.stringify(this._localPreferences); this._resolveStyle(); this.render(); this.emit('preferenceschange', { chart: this, preferences: this.getPreferences(), source: options.source || 'user', scope: 'chart', persisted: false }); return this; }
   resize(width = this.spec.width, height = this.spec.height) { this.spec.width = width; this.spec.height = height; this.render(); this.emit('resize', { chart: this, width, height }); return this; }
   getSpec() { return JSON.parse(JSON.stringify(this.spec)); }
-  getState() { const brandingSignature = discoverCapabilities().branding.signature; return { renderer: this.renderer.constructor.name, width: this.spec.width, height: this.spec.height, dataCount: this.model.data.rows.length, selected: [...this._selected.values()], revision: this._revision, history: this._history.state(), view: clone(this.spec.view || null), style: clone({ name: this.spec.theme.name, mode: this.spec.theme.mode, resolvedMode: this.spec.theme.resolvedMode, preset: this.spec.theme.preset, palette: this.spec.theme.palette, reasons: this.spec.theme.reasons }), branding: { enabled: Boolean(this.spec.branding?.enabled), signature: brandingSignature, text: this.spec.branding?.enabled === true ? brandingSignature : null }, warnings: clone([...(this._specDiagnostics?.warnings || []), ...(this.model.data?.warnings || []), ...(this.spec.theme?.warnings || [])]), assumptions: clone(this.model.data?.assumptions || []), normalizations: clone(this._specDiagnostics?.normalizations || []), collapsedGroups: this.getCollapsedGroupIds(), clipboard: { nodes: this._clipboard?.nodes?.length || 0, edges: this._clipboard?.edges?.length || 0 }, projectAnalytics: clone(this.model.state?.projectAnalytics || null), linked: clone(this.model.state?.linked || null) }; }
+  getState() { const brandingSignature = discoverCapabilities().branding.signature; return { renderer: this.renderer.constructor.name, width: this.spec.width, height: this.spec.height, dataCount: this.model.data.rows.length, selected: [...this._selected.values()], revision: this._revision, history: this._history.state(), view: clone(this.spec.view || null), style: clone({ name: this.spec.theme.name, mode: this.spec.theme.mode, resolvedMode: this.spec.theme.resolvedMode, preset: this.spec.theme.preset, palette: this.spec.theme.palette, reasons: this.spec.theme.reasons }), preferences: this.getPreferences(), branding: { enabled: Boolean(this.spec.branding?.enabled), signature: brandingSignature, text: this.spec.branding?.enabled === true ? brandingSignature : null }, warnings: clone([...(this._specDiagnostics?.warnings || []), ...(this.model.data?.warnings || []), ...(this.spec.theme?.warnings || [])]), assumptions: clone(this.model.data?.assumptions || []), normalizations: clone(this._specDiagnostics?.normalizations || []), collapsedGroups: this.getCollapsedGroupIds(), clipboard: { nodes: this._clipboard?.nodes?.length || 0, edges: this._clipboard?.edges?.length || 0 }, projectAnalytics: clone(this.model.state?.projectAnalytics || null), linked: clone(this.model.state?.linked || null) }; }
   getProjectAnalytics() { return clone(this.model.state?.projectAnalytics || null); }
   getLinkedState() { return clone(this.model.state?.linked || null); }
   setLinkedFilters(filters = {}) { this.spec.project = { ...(this.spec.project || {}), linked: { ...(this.spec.project?.linked || {}), filters: normalizeLinkedFilters(filters) } }; this.emit('linkedstatechange', { chart: this, linked: this.spec.project.linked }); return this.render(); }
@@ -368,7 +429,11 @@ export class Chart {
     if (this.renderer instanceof SVGRenderer) {
       if (wantsSvg) {
         const headlessEnv = typeof document === 'undefined' || typeof XMLSerializer === 'undefined';
-        const string = headlessEnv ? sceneToSvgString(this.model.scene, this.spec) : this.renderer.exportString();
+        const string = headlessEnv
+          ? sceneToSvgString(this.model.scene, this.spec)
+          : this.renderer.container
+            ? this.renderer.exportString()
+            : (() => { const renderer = new SVGRenderer(this.spec); renderer.resize(this.spec.width, this.spec.height); renderer.render(this.model.scene); return renderer.exportString(); })();
         return `data:image/svg+xml;charset=utf-8,${encodeURIComponent(string)}`;
       }
       if (typeof document !== 'undefined') {
@@ -382,19 +447,17 @@ export class Chart {
       }
       return { valid: false, code: 'HEADLESS_EXPORT_UNSUPPORTED', rasterCode: 'RASTER_EXPORT_UNSUPPORTED', message: `SVG renderer raster ('${type}') in headless requires npm i canvas, or fall back to chart.export({type:"svg"}).`, suggestion: 'Use chart.export({type:"svg"}) for headless, or render with { renderer: "canvas" }.' };
     }
-    if (this.renderer instanceof CanvasRenderer && typeof this.renderer.exportImage === 'function') return this.renderer.exportImage(type);
-    return { valid: false, code: 'EXPORT_UNSUPPORTED', message: `toDataURL('${type}') is not supported with renderer ${this.renderer?.constructor?.name || 'unknown'}.`, suggestion: 'Mount the chart to a DOM container, or switch renderer=canvas for PNG export.' };
+    if (this.renderer instanceof CanvasRenderer && typeof this.renderer.exportImage === 'function' && this.renderer.canvas) return this.renderer.exportImage(type);
+    return exportError(typeof document === 'undefined' ? 'HEADLESS_EXPORT_UNSUPPORTED' : 'EXPORT_UNSUPPORTED', `toDataURL('${type}') is not available because the renderer has no canvas surface.`, 'Mount the chart in a browser or use chart.export({ type: "svg" }).');
   }
   toBlob(type = 'image/png') {
     if (typeof document === 'undefined') return { valid: false, code: 'BLOB_HEADLESS', message: 'toBlob() requires a browser document. Use toDataURL() or export({type:"svg"}) in headless.', suggestion: 'Use chart.export({type:"svg"}) or chart.toDataURL() which both return strings usable in headless.' };
-    const url = this.toDataURL(type);
+    let url;
+    try { url = this.toDataURL(type); } catch (error) { return exportError('EXPORT_UNSUPPORTED', String(error?.message || error), 'Use chart.export({ type: "svg" }) or mount a supported renderer.'); }
     if (!url || typeof url !== 'string') return { valid: false, code: 'EXPORT_UNSUPPORTED', message: "Couldn't produce a data URL for export.", suggestion: (url && url.message) || url };
-    const mime = type.includes('svg') ? 'image/svg+xml' : /^image\//i.test(type) ? type : 'image/png';
-    const comma = url.indexOf(',');
-    const base64 = comma >= 0 && /;base64$/i.test(url.slice(0, comma));
-    const payload = comma >= 0 ? url.slice(comma + 1) : url;
-    const bytes = base64 ? Uint8Array.from(atob(payload), c => c.charCodeAt(0)) : (new TextEncoder()).encode(decodeURIComponent(payload));
-    return new Blob([bytes], { type: mime });
+    const normalizedType = String(type).toLowerCase();
+    const mime = normalizedType.includes('svg') ? 'image/svg+xml' : /^image\//i.test(normalizedType) ? normalizedType : 'image/png';
+    return dataUrlToBlob(url, mime);
   }
   export(options = {}) {
     const rawType = String(options.type || (this.renderer instanceof CanvasRenderer ? 'image/png' : 'image/svg+xml')).toLowerCase();
@@ -406,9 +469,15 @@ export class Chart {
       return 'auto';
     };
     const kind = normalizeType(rawType);
+    if (kind === 'auto') return exportError('EXPORT_TYPE_UNSUPPORTED', `Unknown export type: ${rawType}`, 'Use png, svg, jpeg, or json.');
     if (kind === 'json') {
       const payload = { version: '2.0', spec: this.getSpec(), state: this.getState() };
-      return options.as === 'object' ? payload : JSON.stringify(payload, null, 2);
+      const json = JSON.stringify(payload, null, 2);
+      if (!options.as || options.as === 'string') return json;
+      if (options.as === 'object') return payload;
+      if (options.as === 'dataurl') return `data:application/json;charset=utf-8,${encodeURIComponent(json)}`;
+      if (options.as === 'blob') return dataUrlToBlob(`data:application/json;charset=utf-8,${encodeURIComponent(json)}`, 'application/json');
+      return exportError('EXPORT_TYPE_UNSUPPORTED', `Unsupported JSON export format: ${options.as}`, 'Use string, dataurl, blob, or object.');
     }
     if (kind === 'svg') {
       const svgRendererReady = this.renderer instanceof SVGRenderer && this.renderer.container;
@@ -457,34 +526,7 @@ export class Chart {
       }
       return dataUrl;
     }
-    if (this.renderer instanceof SVGRenderer) {
-      try {
-        const c = require('canvas');
-        if (c && c.createCanvas) {
-          const cv = c.createCanvas(this.spec.width, this.spec.height);
-          const r = new CanvasRenderer({ ...this.spec });
-          r.canvas = cv; r.ctx = cv.getContext('2d'); r.resize(this.spec.width, this.spec.height); r.render(this.model.scene);
-          const out = r.exportImage(rasterType);
-          return options.as === 'blob' ? (typeof Blob !== 'undefined' ? new Blob([Uint8Array.from(atob(out.slice(out.indexOf(',') + 1)), x => x.charCodeAt(0))], { type: rasterType }) : out) : out;
-        }
-      } catch (_) { /* ignore */ }
-      return { valid: false, code: 'HEADLESS_EXPORT_UNSUPPORTED', rasterCode: 'RASTER_EXPORT_UNSUPPORTED', message: `Raster export (${rasterType}) with SVG renderer in headless requires npm i canvas.`, suggestion: 'Install the `canvas` package, or fall back to chart.export({type:"svg"}) which works browser+headless with zero dependencies.' };
-    }
-    const canvasUnavailable = { valid: false, code: 'HEADLESS_EXPORT_UNSUPPORTED', rasterCode: 'RASTER_EXPORT_UNSUPPORTED', message: `Raster export (${rasterType}) requires a mounted CanvasRenderer with a real canvas element.`, suggestion: 'Mount the chart with { renderer: "canvas", container: "#id" } in a browser, or fall back to chart.export({type:"svg"}) which works browser+headless.' };
-    if (typeof document === 'undefined') {
-      try {
-        const c = require('canvas');
-        if (c && c.createCanvas) {
-          const cv = c.createCanvas(this.spec.width, this.spec.height);
-          const r = new CanvasRenderer({ ...this.spec });
-          r.canvas = cv; r.ctx = cv.getContext('2d'); r.resize(this.spec.width, this.spec.height); r.render(this.model.scene);
-          const out = r.exportImage(rasterType);
-          return options.as === 'blob' ? (typeof Blob !== 'undefined' ? new Blob([Uint8Array.from(atob(out.slice(out.indexOf(',') + 1)), x => x.charCodeAt(0))], { type: rasterType }) : out) : out;
-        }
-      } catch (_) { /* ignore: continue to structured error */ }
-      return { ...canvasUnavailable, headless: true, note: 'In Node headless, run `npm i canvas` and ensure createCanvas() is available, or use chart.export({type:"svg"}).' };
-    }
-    return canvasUnavailable;
+    return exportError('HEADLESS_EXPORT_UNSUPPORTED', `Raster export (${rasterType}) requires a mounted CanvasRenderer or the async optional canvas adapter.`, 'Use chart.exportAsync({ type: "png" }) with the optional canvas package, or fall back to chart.export({ type: "svg" }).', { rasterCode: 'RASTER_EXPORT_UNSUPPORTED' });
   }
   async exportAsync(options = {}) {
     const rawType = String(options.type || (this.renderer instanceof CanvasRenderer ? 'image/png' : 'image/svg+xml')).toLowerCase();
@@ -496,12 +538,21 @@ export class Chart {
       return 'auto';
     };
     const kind = normalizeType(rawType);
-    if (kind === 'json' || kind === 'svg' || kind === 'png' || kind === 'jpeg') {
-      const out = this.export(options);
-      if (out && typeof out === 'object' && out.valid === false) return Promise.reject(out);
-      return Promise.resolve(out);
+    if (kind === 'auto') return exportError('EXPORT_TYPE_UNSUPPORTED', `Unknown export type: ${rawType}`, 'Use png, svg, jpeg, or json.');
+    if (kind === 'png' || kind === 'jpeg') {
+      const direct = this.export(options);
+      if (!(direct && typeof direct === 'object' && direct.code === 'HEADLESS_EXPORT_UNSUPPORTED')) return direct;
+      try {
+        const moduleName = 'canvas';
+        const module = await import(moduleName);
+        const createCanvas = canvasFactoryFromModule(module);
+        if (!createCanvas) return direct;
+        return renderRasterWithCanvas(createCanvas, this.spec, this.model.scene, kind === 'jpeg' ? 'image/jpeg' : 'image/png', options.as);
+      } catch {
+        return direct;
+      }
     }
-    return Promise.reject({ valid: false, code: 'EXPORT_TYPE_UNSUPPORTED', message: `Unknown export type: ${rawType}`, suggestion: 'Use png, svg, jpeg, or json.' });
+    return this.export(options);
   }
   _safeFilename(prefix = 'ichart') {
     const sanitize = s => String(s == null ? '' : s).replace(/[\\/:*?"<>|\s]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40) || prefix;
@@ -547,7 +598,7 @@ export class Chart {
       return { valid: false, code: 'DOWNLOAD_FAILED', message: String(err && err.message || err), suggestion: 'Try chart.export() and write the result manually.' };
     }
   }
-  destroy() { if (this._resizeObserver) this._resizeObserver.disconnect(); this._colorSchemeQuery?.removeEventListener?.('change', this._colorSchemeHandler); if (this._eventsBound) { const { target, handler, start, move, end, leave, touchStart, touchMove, touchEnd, wheel } = this._eventsBound; target.removeEventListener('mousemove', handler); target.removeEventListener('click', handler); target.removeEventListener('pointerdown', start); target.removeEventListener('pointermove', move); target.removeEventListener('pointerup', end); target.removeEventListener('pointercancel', end); target.removeEventListener('pointerleave', leave); target.removeEventListener('touchstart', touchStart); target.removeEventListener('touchmove', touchMove); target.removeEventListener('touchend', touchEnd); target.removeEventListener('wheel', wheel); } const target = this.renderer.svg || this.renderer.canvas; if (this._keyboardHandler) target?.removeEventListener('keydown', this._keyboardHandler); this._tooltip?.remove(); this.plugins.destroy(); this.renderer.destroy(); this.listeners.clear(); this._eventsBound = null; this._selected.clear(); this._clipboard = { nodes: [], edges: [] }; }
+  destroy() { this._preferencesUnsubscribe?.(); if (this._resizeObserver) this._resizeObserver.disconnect(); this._colorSchemeQuery?.removeEventListener?.('change', this._colorSchemeHandler); if (this._eventsBound) { const { target, handler, start, move, end, leave, touchStart, touchMove, touchEnd, wheel } = this._eventsBound; target.removeEventListener('mousemove', handler); target.removeEventListener('click', handler); target.removeEventListener('pointerdown', start); target.removeEventListener('pointermove', move); target.removeEventListener('pointerup', end); target.removeEventListener('pointercancel', end); target.removeEventListener('pointerleave', leave); target.removeEventListener('touchstart', touchStart); target.removeEventListener('touchmove', touchMove); target.removeEventListener('touchend', touchEnd); target.removeEventListener('wheel', wheel); } const target = this.renderer.svg || this.renderer.canvas; if (this._keyboardHandler) target?.removeEventListener('keydown', this._keyboardHandler); this._tooltip?.remove(); this.plugins.destroy(); this.renderer.destroy(); this.listeners.clear(); this._eventsBound = null; this._selected.clear(); this._clipboard = { nodes: [], edges: [] }; }
 }
 
 export function createChart(spec) { return new Chart(spec); }
@@ -559,4 +610,5 @@ export { normalizeProjectCalendar, applyWorkingCalendar, normalizeDependencies,
 export { normalizeLinkedFilters, normalizeLinkedSelection, filterProjectRows, createLinkedProjectState, linkedRecordId };
 
 export { contrastRatio, planStyle, resolveTheme, styleCapabilities, themeModes, themePalettes, themePresets, validateThemeContrast, annotationPlugin, dataZoomPlugin, dataLabelsPlugin, accessibilityPlugin };
-export const iChart = { version: '2.0.4', createChart, inspectData, normalizeData, binData, applyTransforms, normalizeSpec, validateSpec, data, getCapabilities, getChartCapability, planChart, recommend, explainChart, contrastRatio, planStyle, resolveTheme, styleCapabilities, themeModes, themePalettes, themePresets, validateThemeContrast, annotationPlugin, dataZoomPlugin, dataLabelsPlugin, accessibilityPlugin, getBusinessSchema, inspectDataSchema, validateData, getEditCapabilities, validateEdit, previewEdit, commitPreview, validateRecipe, normalizeProjectCalendar, applyWorkingCalendar, normalizeDependencies, analyzeSchedule, analyzeBurndownSeries, analyzeCapacity, buildCapacityView, buildCumulativeFlowSeries, buildVelocitySeries, buildReleaseForecast, buildRiskMatrixSeries, buildIssueAgingSeries, normalizeLinkedFilters, normalizeLinkedSelection, filterProjectRows, createLinkedProjectState, linkedRecordId };
+export { applyPreferencesToSpec, createPreferencesStore, defaultPreferences, mergePreferences, mergeThemePreference, mountChartSettings, normalizePreferences };
+export const iChart = { version: '2.0.6', createChart, inspectData, normalizeData, binData, applyTransforms, normalizeSpec, validateSpec, data, getCapabilities, getChartCapability, planChart, recommend, explainChart, contrastRatio, planStyle, resolveTheme, styleCapabilities, themeModes, themePalettes, themePresets, validateThemeContrast, createPreferencesStore, defaultPreferences, normalizePreferences, mergePreferences, applyPreferencesToSpec, mountChartSettings, annotationPlugin, dataZoomPlugin, dataLabelsPlugin, accessibilityPlugin, getBusinessSchema, inspectDataSchema, validateData, getEditCapabilities, validateEdit, previewEdit, commitPreview, validateRecipe, normalizeProjectCalendar, applyWorkingCalendar, normalizeDependencies, analyzeSchedule, analyzeBurndownSeries, analyzeCapacity, buildCapacityView, buildCumulativeFlowSeries, buildVelocitySeries, buildReleaseForecast, buildRiskMatrixSeries, buildIssueAgingSeries, normalizeLinkedFilters, normalizeLinkedSelection, filterProjectRows, createLinkedProjectState, linkedRecordId };

package/src/preferences-ui.mjs

@@ -0,0 +1,86 @@
+/**
+ * Optional, framework-neutral quick settings popover for browser hosts.
+ * It stays outside the SVG/Canvas surface and is never part of exports.
+ */
+import { getChartCapability } from './capabilities.mjs';
+import { contrastRatio, themeModes, themePalettes } from './theme.mjs';
+
+const styleId = 'ichart-preferences-ui-style';
+const messages = {
+  'zh-CN': {
+    title: '图表快捷设置', mode: '主题', palette: '配色', scale: '字号', automatic: '自动', defaultSize: '默认', small: '小', large: '大', extraLarge: '特大', legend: '图例', labels: '数据标签', grid: '网格线'
+  },
+  en: {
+    title: 'Chart quick settings', mode: 'Theme', palette: 'Palette', scale: 'Font size', automatic: 'Auto', defaultSize: 'Default', small: 'Small', large: 'Large', extraLarge: 'Extra large', legend: 'Legend', labels: 'Data labels', grid: 'Grid lines'
+  }
+};
+
+function option(label, value) { return `<option value="${value}">${label}</option>`; }
+function safe(value) { return value == null ? '' : String(value); }
+function localeKey(locale) {
+  const requested = locale && locale !== 'auto' ? locale : document.documentElement.lang || navigator.language || 'en';
+  const normalized = String(requested).toLowerCase();
+  if (normalized === 'zh' || normalized.startsWith('zh-')) return 'zh-CN';
+  if (normalized === 'en' || normalized.startsWith('en-')) return 'en';
+  return 'en';
+}
+
+function ensureStyle() {
+  if (typeof document === 'undefined' || document.getElementById(styleId)) return;
+  const style = document.createElement('style');
+  style.id = styleId;
+  style.textContent = `.ichart-preferences{position:absolute;top:8px;right:8px;left:8px;height:32px;z-index:20;pointer-events:none;font:12px/1.4 system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;color:#172033}.ichart-preferences__button{position:absolute;top:0;right:0;display:grid;place-items:center;width:32px;height:32px;min-width:32px;min-height:32px;border:0;background:transparent;color:var(--ichart-preferences-icon-color,#172033);border-radius:7px;padding:0;pointer-events:auto;cursor:pointer;font-size:22px;line-height:1;text-shadow:0 1px 2px #0004}.ichart-preferences__panel{display:none;position:absolute;top:38px;right:0;width:min(320px,100%);padding:12px;border:0;border-radius:10px;background:#fff;pointer-events:auto;box-shadow:0 12px 30px #1720332b}.ichart-preferences[data-open="true"] .ichart-preferences__panel{display:block}.ichart-preferences__grid{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:8px}.ichart-preferences__field{display:grid;min-width:0;gap:3px;margin:0}.ichart-preferences__field>span{color:#475467}.ichart-preferences__field select{width:100%;min-width:0;height:32px;border:1px solid #c5cfdb;border-radius:6px;padding:4px 7px;background:#fff;color:inherit}.ichart-preferences__toggles{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:6px;margin-top:8px;padding-top:8px;border-top:1px solid #e2e8f0}.ichart-preferences__toggle{display:flex;align-items:center;justify-content:center;gap:5px;min-height:32px;padding:5px 6px;color:#344054;cursor:pointer}.ichart-preferences__toggle input{width:auto;min-height:auto;margin:0;accent-color:#2563eb}@media(max-width:420px){.ichart-preferences__panel{width:min(288px,100%)}.ichart-preferences__grid,.ichart-preferences__toggles{grid-template-columns:1fr}.ichart-preferences__toggle{justify-content:flex-start}}`;
+  document.head.appendChild(style);
+}
+
+export function mountChartSettings(chart, { container = chart?.container, locale = 'auto', title } = {}) {
+  if (typeof document === 'undefined' || !chart || !container) return { valid: false, code: 'PREFERENCES_UI_UNAVAILABLE', message: 'Chart settings require a browser container.' };
+  ensureStyle();
+  const text = messages[localeKey(locale)], accessibleTitle = title || text.title, host = container;
+  const capability = getChartCapability(chart.getSpec().type), supported = name => capability?.features?.[name] === 'supported';
+  const visibleComponents = ['legend', 'labels', 'grid'].filter(supported);
+  if (getComputedStyle(host).position === 'static') host.style.position = 'relative';
+  const root = document.createElement('div');
+  root.className = 'ichart-preferences';
+  root.dataset.open = 'false';
+  const componentMarkup = visibleComponents.map(name => `<label class="ichart-preferences__toggle"><input type="checkbox" data-key="${name}"><span>${text[name]}</span></label>`).join('');
+  root.innerHTML = `<button class="ichart-preferences__button" type="button" aria-expanded="false"><span aria-hidden="true">≡</span></button><div class="ichart-preferences__panel" role="dialog"><div class="ichart-preferences__grid"><label class="ichart-preferences__field"><span>${text.mode}</span><select data-key="mode">${themeModes.map(value => option(value === 'auto' ? text.automatic : value, value)).join('')}</select></label><label class="ichart-preferences__field"><span>${text.palette}</span><select data-key="palette">${themePalettes.map(value => option(value === 'auto' ? text.automatic : value, value)).join('')}</select></label><label class="ichart-preferences__field"><span>${text.scale}</span><select data-key="scale">${option(text.defaultSize, '1')}${option(text.small, '0.85')}${option(text.large, '1.15')}${option(text.extraLarge, '1.3')}</select></label></div>${componentMarkup ? `<div class="ichart-preferences__toggles">${componentMarkup}</div>` : ''}</div>`;
+  const button = root.querySelector('.ichart-preferences__button'), panel = root.querySelector('.ichart-preferences__panel');
+  button.setAttribute('aria-label', accessibleTitle); button.title = accessibleTitle; panel.setAttribute('aria-label', accessibleTitle);
+  host.appendChild(root);
+  const values = key => root.querySelector(`[data-key="${key}"]`);
+  const readField = key => {
+    const control = values(key), value = control?.type === 'checkbox' ? control.checked : control?.value;
+    if (['mode', 'palette'].includes(key)) return { theme: { [key]: value === 'auto' ? null : value } };
+    if (key === 'scale') return { typography: { scale: Number(value) } };
+    if (visibleComponents.includes(key)) return { components: { [key]: Boolean(value) } };
+    return {};
+  };
+  const sync = () => {
+    const prefs = chart.getPreferences(), spec = chart.getSpec(), set = (key, value) => { if (values(key)) values(key).value = safe(value); };
+    set('mode', prefs.theme?.mode || 'auto'); set('palette', prefs.theme?.palette || 'auto');
+    const scaleControl = values('scale'), scale = Number(prefs.typography?.scale || 1), scaleValue = String(scale);
+    scaleControl.querySelector('option[data-current]')?.remove();
+    if (![...scaleControl.options].some(currentOption => currentOption.value === scaleValue)) { const currentOption = document.createElement('option'); currentOption.value = scaleValue; currentOption.textContent = `${Math.round(scale * 100)}%`; currentOption.dataset.current = 'true'; scaleControl.appendChild(currentOption); }
+    scaleControl.value = scaleValue;
+    if (values('legend')) values('legend').checked = spec.legend?.visible !== false;
+    if (values('labels')) values('labels').checked = Boolean(spec.labels?.enabled);
+    if (values('grid')) values('grid').checked = spec.grid?.visible !== false;
+  };
+  const close = () => { root.dataset.open = 'false'; button.setAttribute('aria-expanded', 'false'); };
+  const updateIconColor = () => { const theme = chart.getTheme(), background = chart.getSpec().background || theme.background, darkRatio = contrastRatio('#172033', background), lightRatio = contrastRatio('#ffffff', background), color = darkRatio == null || lightRatio == null ? theme.text || '#172033' : darkRatio >= lightRatio ? '#172033' : '#ffffff'; button.style.setProperty('--ichart-preferences-icon-color', color); };
+  const onPreferencesChange = () => { sync(); updateIconColor(); };
+  const applyField = key => { try { chart.setPreferences(readField(key), { source: 'ui' }); } catch {} };
+  const onToggle = () => { const open = root.dataset.open !== 'true'; root.dataset.open = String(open); button.setAttribute('aria-expanded', String(open)); if (open) sync(); };
+  const onDocumentPointer = event => { if (!root.contains(event.target)) close(); };
+  const onDocumentKey = event => { if (event.key === 'Escape') { close(); button.focus(); } };
+  button.addEventListener('click', onToggle);
+  root.querySelectorAll('select,input[data-key]').forEach(control => control.addEventListener('change', () => applyField(control.dataset.key)));
+  document.addEventListener('pointerdown', onDocumentPointer);
+  document.addEventListener('keydown', onDocumentKey);
+  chart.on('preferenceschange', onPreferencesChange);
+  chart.on('themechange', updateIconColor);
+  sync();
+  updateIconColor();
+  return { valid: true, element: root, locale: localeKey(locale), destroy() { chart.off('preferenceschange', onPreferencesChange); chart.off('themechange', updateIconColor); document.removeEventListener('pointerdown', onDocumentPointer); document.removeEventListener('keydown', onDocumentKey); root.remove(); } };
+}

package/src/preferences.mjs

@@ -0,0 +1,194 @@
+/**
+ * Small, renderer-neutral preference contract shared by the Chart API,
+ * interactive settings UI, and Agent integrations.
+ */
+import { themeModes, themePalettes, themePresets } from './theme.mjs';
+
+export const preferenceVersion = '1.0';
+export const preferenceDensities = ['compact', 'comfortable', 'spacious'];
+export const preferenceTriStates = ['auto', true, false];
+export const preferenceMotions = ['auto', 'full', 'reduced', 'off'];
+
+export const defaultPreferences = Object.freeze({
+  version: preferenceVersion,
+  theme: Object.freeze({ mode: null, preset: null, palette: null }),
+  typography: Object.freeze({ scale: 1 }),
+  density: 'comfortable',
+  components: Object.freeze({ legend: 'auto', labels: 'auto', grid: 'auto' }),
+  branding: Object.freeze({ enabled: 'auto' }),
+  motion: 'auto'
+});
+
+function clone(value) { return value == null ? value : JSON.parse(JSON.stringify(value)); }
+
+function merge(base, extra) {
+  const result = clone(base) || {};
+  Object.entries(extra || {}).forEach(([key, value]) => {
+    if (value && typeof value === 'object' && !Array.isArray(value) && result[key] && typeof result[key] === 'object' && !Array.isArray(result[key])) result[key] = merge(result[key], value);
+    else if (value !== undefined) result[key] = clone(value);
+  });
+  return result;
+}
+
+function isPlainObject(value) { return Boolean(value) && typeof value === 'object' && !Array.isArray(value); }
+
+function diagnostic(code, path, message, expected, suggestion) {
+  return { code, path, message, ...(expected === undefined ? {} : { expected }), ...(suggestion ? { suggestion } : {}) };
+}
+
+export function validatePreferences(input = {}, { partial = true } = {}) {
+  const errors = [];
+  if (!isPlainObject(input)) return { valid: false, errors: [diagnostic('INVALID_PREFERENCES', '', 'Preferences must be an object.', 'an object', 'Pass a preferences object.')], value: clone(defaultPreferences) };
+  const theme = input.theme;
+  if (theme !== undefined) {
+    if (!isPlainObject(theme)) errors.push(diagnostic('INVALID_PREFERENCE_THEME', 'theme', 'Preferences theme must be an object.', 'an object'));
+    else {
+      if (theme.mode !== undefined && theme.mode !== null && !themeModes.includes(theme.mode)) errors.push(diagnostic('INVALID_PREFERENCE_THEME_MODE', 'theme.mode', `Unsupported preference theme mode: ${theme.mode}.`, themeModes));
+      if (theme.preset !== undefined && theme.preset !== null && !themePresets.includes(theme.preset)) errors.push(diagnostic('INVALID_PREFERENCE_THEME_PRESET', 'theme.preset', `Unsupported preference theme preset: ${theme.preset}.`, themePresets));
+      if (theme.palette !== undefined && theme.palette !== null && !themePalettes.includes(theme.palette)) errors.push(diagnostic('INVALID_PREFERENCE_THEME_PALETTE', 'theme.palette', `Unsupported preference theme palette: ${theme.palette}.`, themePalettes));
+    }
+  }
+  const scale = input.typography?.scale;
+  if (scale !== undefined && (!(Number.isFinite(Number(scale))) || Number(scale) < 0.75 || Number(scale) > 1.5)) errors.push(diagnostic('INVALID_PREFERENCE_SCALE', 'typography.scale', 'Typography scale must be between 0.75 and 1.5.', '0.75..1.5', 'Use 1 for the default size.'));
+  if (input.density !== undefined && !preferenceDensities.includes(input.density)) errors.push(diagnostic('INVALID_PREFERENCE_DENSITY', 'density', `Unsupported density: ${input.density}.`, preferenceDensities));
+  ['legend', 'labels', 'grid'].forEach(name => {
+    const value = input.components?.[name];
+    if (value !== undefined && !preferenceTriStates.includes(value)) errors.push(diagnostic('INVALID_PREFERENCE_COMPONENT', `components.${name}`, `${name} must be auto, true, or false.`, preferenceTriStates));
+  });
+  if (input.branding?.enabled !== undefined && !preferenceTriStates.includes(input.branding.enabled)) errors.push(diagnostic('INVALID_PREFERENCE_BRANDING', 'branding.enabled', 'branding.enabled must be auto, true, or false.', preferenceTriStates));
+  if (input.motion !== undefined && !preferenceMotions.includes(input.motion)) errors.push(diagnostic('INVALID_PREFERENCE_MOTION', 'motion', `Unsupported motion preference: ${input.motion}.`, preferenceMotions));
+  if (!partial && input.version !== undefined && input.version !== preferenceVersion) errors.push(diagnostic('UNSUPPORTED_PREFERENCE_VERSION', 'version', `Unsupported preference version: ${input.version}.`, preferenceVersion));
+  return { valid: errors.length === 0, errors, value: normalizePreferences(input, { partial }) };
+}
+
+export function normalizePreferences(input = {}, { partial = false } = {}) {
+  const source = isPlainObject(input) ? input : {};
+  const normalized = partial ? {} : clone(defaultPreferences);
+  if (source.theme && isPlainObject(source.theme)) {
+    normalized.theme = merge(normalized.theme || {}, {
+      mode: source.theme.mode === undefined ? (partial ? undefined : null) : source.theme.mode,
+      preset: source.theme.preset === undefined ? (partial ? undefined : null) : source.theme.preset,
+      palette: source.theme.palette === undefined ? (partial ? undefined : null) : source.theme.palette
+    });
+  }
+  if (source.typography && isPlainObject(source.typography) && source.typography.scale !== undefined) normalized.typography = merge(normalized.typography || {}, { scale: Number(source.typography.scale) });
+  if (source.density !== undefined) normalized.density = source.density;
+  if (source.components && isPlainObject(source.components)) normalized.components = merge(normalized.components || {}, Object.fromEntries(['legend', 'labels', 'grid'].filter(name => source.components[name] !== undefined).map(name => [name, source.components[name]])));
+  if (source.branding && isPlainObject(source.branding) && source.branding.enabled !== undefined) normalized.branding = merge(normalized.branding || {}, { enabled: source.branding.enabled });
+  if (source.motion !== undefined) normalized.motion = source.motion;
+  normalized.version = preferenceVersion;
+  return normalized;
+}
+
+export function mergePreferences(...values) {
+  return normalizePreferences(values.reduce((result, value) => merge(result, normalizePreferences(value, { partial: true })), {}));
+}
+
+function resolveStorage(storage) {
+  if (storage && typeof storage.getItem === 'function' && typeof storage.setItem === 'function') return storage;
+  if (storage === 'localStorage' && typeof globalThis !== 'undefined' && globalThis.localStorage) return globalThis.localStorage;
+  return null;
+}
+
+function readState(storage, key) {
+  if (!storage) return null;
+  try {
+    const parsed = JSON.parse(storage.getItem(key) || 'null');
+    if (!isPlainObject(parsed)) return null;
+    return { version: preferenceVersion, global: normalizePreferences(parsed.global), charts: isPlainObject(parsed.charts) ? Object.fromEntries(Object.entries(parsed.charts).map(([id, value]) => [id, normalizePreferences(value, { partial: true })])) : {} };
+  } catch { return null; }
+}
+
+export function createPreferencesStore(options = {}) {
+  const storage = resolveStorage(options.storage);
+  const storageKey = options.storageKey || 'ichartjs:preferences:v1';
+  const loaded = readState(storage, storageKey);
+  let state = loaded || {
+    version: preferenceVersion,
+    global: normalizePreferences(options.global || {}),
+    charts: Object.fromEntries(Object.entries(options.charts || {}).map(([id, value]) => [id, normalizePreferences(value, { partial: true })]))
+  };
+  const listeners = new Set();
+  const persist = () => {
+    if (!storage) return false;
+    try { storage.setItem(storageKey, JSON.stringify(state)); return true; } catch { return false; }
+  };
+  const snapshot = () => clone(state);
+  const notify = (scope, chartId, source, persisted) => {
+    const payload = { type: 'change', scope, chartId: chartId || null, source: source || 'user', persisted, preferences: chartId ? getEffective(chartId) : clone(state.global), state: snapshot() };
+    listeners.forEach(listener => listener(payload));
+  };
+  const getGlobal = () => clone(state.global);
+  const getChart = chartId => clone(state.charts[String(chartId)] || {});
+  const getEffective = chartId => mergePreferences(defaultPreferences, state.global, chartId == null ? {} : state.charts[String(chartId)] || {});
+  const update = (scope, chartId, patch, { source = 'user', persist: shouldPersist = true } = {}) => {
+    const checked = validatePreferences(patch, { partial: true });
+    if (!checked.valid) { const error = new Error(checked.errors.map(item => item.message).join(' ')); error.code = 'INVALID_PREFERENCES'; error.details = checked.errors; throw error; }
+    if (scope === 'global') state.global = mergePreferences(state.global, patch);
+    else {
+      const key = String(chartId || 'default');
+      state.charts[key] = merge(state.charts[key] || {}, checked.value);
+    }
+    const persisted = shouldPersist ? persist() : false;
+    notify(scope, chartId, source, persisted);
+    return scope === 'global' ? getGlobal() : getEffective(chartId);
+  };
+  return {
+    version: preferenceVersion,
+    storageKey,
+    getState: snapshot,
+    getGlobal,
+    getChart,
+    getEffective,
+    setGlobal(patch, options = {}) { return update('global', null, patch, options); },
+    setChart(chartId, patch, options = {}) { return update('chart', chartId, patch, options); },
+    reset({ scope = 'all', chartId, persist: shouldPersist = true, source = 'user' } = {}) {
+      if (scope === 'all' || scope === 'global') state.global = normalizePreferences({});
+      if (scope === 'all') state.charts = {};
+      if (scope === 'chart' && chartId != null) delete state.charts[String(chartId)];
+      const persisted = shouldPersist ? persist() : false;
+      notify(scope, chartId, source, persisted);
+      return chartId != null ? getEffective(chartId) : getGlobal();
+    },
+    subscribe(listener) { listeners.add(listener); return () => listeners.delete(listener); },
+    persist,
+    storage: storage ? 'localStorage' : 'memory'
+  };
+}
+
+export function mergeThemePreference(theme, preferenceTheme = {}) {
+  const patch = Object.fromEntries(['mode', 'preset', 'palette'].filter(key => preferenceTheme?.[key] != null).map(key => [key, preferenceTheme[key]]));
+  if (!Object.keys(patch).length) return theme;
+  if (typeof theme === 'string') {
+    const base = themeModes.includes(theme) ? { mode: theme } : themePresets.includes(theme) ? { preset: theme } : {};
+    return { ...base, ...patch };
+  }
+  return { ...(isPlainObject(theme) ? theme : {}), ...patch };
+}
+
+function scaledFont(font, scale) {
+  return String(font || '').replace(/(\d+(?:\.\d+)?)px/, (_, value) => `${Number((Number(value) * scale).toFixed(2))}px`);
+}
+
+export function applyPreferencesToSpec(spec, preferences = {}) {
+  const result = clone(spec) || {};
+  const prefs = mergePreferences(preferences);
+  result.theme = clone(result.theme) || {};
+  const scale = prefs.typography.scale;
+  if (scale !== 1 && result.theme.typography) {
+    result.theme.typography = Object.fromEntries(Object.entries(result.theme.typography).map(([key, value]) => [key, { ...value, size: Number((Number(value.size) * scale).toFixed(2)), font: scaledFont(value.font, scale) }]));
+  }
+  if (prefs.density !== 'comfortable') {
+    const factor = prefs.density === 'compact' ? 0.82 : 1.2;
+    const padding = result.theme.layout?.padding || result.padding;
+    if (padding) result.padding = Object.fromEntries(Object.entries(padding).map(([key, value]) => [key, Math.max(0, Math.round(Number(value) * factor))]));
+    if (result.theme.layout) result.theme.layout = { ...result.theme.layout, density: prefs.density, spacing: Number((Number(result.theme.layout.spacing || 8) * factor).toFixed(2)) };
+  }
+  const component = (path, value) => value === 'auto' ? undefined : value;
+  const legend = component('legend', prefs.components.legend), labels = component('labels', prefs.components.labels), grid = component('grid', prefs.components.grid);
+  if (legend !== undefined) result.legend = { ...(result.legend || {}), visible: legend };
+  if (labels !== undefined) result.labels = { ...(result.labels || {}), enabled: labels };
+  if (grid !== undefined) result.grid = { ...(result.grid || {}), visible: grid };
+  if (prefs.branding.enabled !== 'auto') result.branding = { ...(result.branding || {}), enabled: prefs.branding.enabled };
+  return result;
+}