@taylorwong/ichartjs 2.0.5 → 2.0.6

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 2.0.6 - 2026-09-18
+
+- Added compact per-chart visual settings with explicit default font sizing, capability-aware visibility toggles, bilingual labels, and theme-aware hamburger icon contrast.
+- Added shared page-level preferences with localStorage persistence and Agent JSON patch support through the Preferences API and Playground settings page.
+- Synchronized Runtime, Playground, package metadata, release-pinned installation guidance, and roadmap status for the `v2.0.6` release.
+
 ## 2.0.5 - 2026-09-18
 
 - Hardened JSON, SVG, PNG, and JPEG export contracts with deterministic type errors, JSON output representations, and an explicit optional Node `canvas` path through `exportAsync()`.

package/README.md

@@ -31,6 +31,7 @@ getCapabilities
 | Coding Agent integration | [`docs/agent/coding-agent-integration.md`](docs/agent/coding-agent-integration.md) |
 | Frontend integration | [`docs/agent/frontend-integration.md`](docs/agent/frontend-integration.md) |
 | Visual style and themes | [`docs/agent/theme-guide.md`](docs/agent/theme-guide.md) |
+| Chart and page preferences | [`docs/agent/theme-guide.md`](docs/agent/theme-guide.md#chart-and-page-preferences) |
 | Official Agent Skill for Codex and WorkBuddy | [`skills/ichartjs/SKILL.md`](skills/ichartjs/SKILL.md) |
 
 ### Install
@@ -39,7 +40,7 @@ getCapabilities
 npm install @taylorwong/ichartjs@^2
 ```
 
-As a fallback for environments without npm access, install directly from GitHub: `npm install github:wanghetommy/ichartjs#v2.0.5`.
+As a fallback for environments without npm access, install directly from GitHub: `npm install github:wanghetommy/ichartjs#v2.0.6`.
 
 ### Optional Agent Skill
 
@@ -49,13 +50,19 @@ The runtime API remains the source of truth; the Skill only teaches and orchestr
 https://github.com/wanghetommy/ichartjs/tree/master/skills/ichartjs
 ```
 
-From a repository checkout, install it into Codex with:
+Install the latest Skill with the standard Agent Skills CLI:
 
 ```bash
-cp -R skills/ichartjs "${CODEX_HOME:-$HOME/.codex}/skills/"
+npx skills add wanghetommy/ichartjs --skill ichartjs
 ```
 
-WorkBuddy users can import or register the same `skills/ichartjs` folder through the host's Skill interface. Package consumers can copy it from `node_modules/@taylorwong/ichartjs/skills/ichartjs` into their Agent host's Skill directory. After installation, invoke it as `$ichartjs` when the host supports named Skill invocation, or select the `ichartjs` Skill in the host UI.
+For a non-interactive global Codex installation:
+
+```bash
+npx skills add wanghetommy/ichartjs --skill ichartjs --agent codex --global --yes
+```
+
+For a release-pinned installation, use `npx skills add https://github.com/wanghetommy/ichartjs/tree/v2.0.6/skills/ichartjs --agent codex --global --yes`. WorkBuddy users can import the same tagged `skills/ichartjs` URL through the host's Skill interface; do not assume a `--agent workbuddy` adapter unless the installed CLI declares it. Package consumers can still copy `node_modules/@taylorwong/ichartjs/skills/ichartjs` as a manual fallback. After installation, invoke `$ichartjs` when named Skill invocation is supported, or select `ichartjs` in the host UI.
 
 ### Agent workflow
 

package/docs/agent/coding-agent-integration.md

@@ -27,12 +27,16 @@ npm install
 npm run playground
 ```
 
-The same official Skill can be imported by Codex, WorkBuddy, and other Agent Skills-compatible hosts from `skills/ichartjs`. Install it into Codex from a repository checkout with:
+Install the official Skill with the standard Agent Skills CLI:
 
 ```bash
-cp -R skills/ichartjs "${CODEX_HOME:-$HOME/.codex}/skills/"
+npx skills add wanghetommy/ichartjs --skill ichartjs
 ```
 
+For global non-interactive Codex setup, append `--agent codex --global --yes`. To pin the released workflow, install `https://github.com/wanghetommy/ichartjs/tree/v2.0.6/skills/ichartjs`. WorkBuddy can import that tagged directory through its Skill interface; only use a host-specific `--agent` value when the installed CLI declares it.
+
+Verify discovery with `npx skills add wanghetommy/ichartjs --list`; the result should include `ichartjs`.
+
 ## Agent Request Pattern
 
 A useful request is explicit about data, intent, output, and acceptance:

package/docs/agent/development/iteration-11.md

@@ -0,0 +1,44 @@
+# Iteration 11 — Chart Preferences and Agent Adjustments
+
+Iteration 11A–11D adds a small, allowlisted preference layer for visual configuration. It does not add chart types or change data encoding behavior. The same contract powers per-chart settings, page-wide defaults, browser persistence, and Agent conversational adjustments.
+
+## 11A — Preferences Contract
+
+- Add `createPreferencesStore()`, `normalizePreferences()`, `mergePreferences()`, and `validatePreferences()`.
+- Keep the public fields limited to theme mode/preset/palette, typography scale, density, legend/labels/grid visibility, branding, and motion.
+- Resolve precedence as defaults → global page preferences → chart preferences → temporary Agent patch.
+- Keep preference state separate from business data and provide structured change events with `source`, `scope`, and persistence status.
+- Fall back to memory in Node/SSR and support browser `localStorage` or a host storage adapter explicitly.
+
+## 11B — Per-Chart Settings
+
+- Add `Chart#getPreferences()`, `Chart#setPreferences()`, and `Chart#resetPreferences()`.
+- Add the optional `mountChartSettings()` browser UI with an accessible settings button in the chart container's top-right corner.
+- Limit the per-chart menu to high-frequency theme, palette, font-scale, and capability-supported visibility controls; keep advanced and global controls on a dedicated page outside the chart popover.
+- Keep the settings DOM outside SVG/Canvas so it is not included in PNG/SVG exports.
+- Apply changes without recreating the Chart instance and preserve explicit chart colors/background/padding overrides.
+
+## 11C — Global Page Configuration
+
+- Allow one `PreferencesStore` to be shared by all charts on a page.
+- Support global and chart scopes with chart-specific inheritance and reset behavior.
+- Persist only the versioned preference document, never business rows or credentials.
+- Expose the effective preferences in `chart.getState()` and the capabilities manifest.
+
+## 11D — Agent and Playground Integration
+
+- Let an Agent apply a validated visual patch with `chart.setPreferences(patch, { source: 'agent' })`.
+- Keep Agent updates and UI updates on the same `preferenceschange` event path.
+- Add `preferences-lab.html` and settings controls to the Complete Gallery for browser acceptance.
+- Document conversational examples such as “use dashboard style, status colors, larger labels, and hide the grid.”
+
+## Acceptance
+
+- `npm run agent:check` passes.
+- Preferences work in headless memory mode and browser `localStorage` mode.
+- Global updates reach all charts sharing a store; chart updates remain isolated.
+- Invalid preference patches return structured validation details and do not mutate state.
+- Preview pages:
+  - `http://localhost:3000/playground/preferences-lab.html`
+  - `http://localhost:3000/playground/project-gallery.html`
+- No new chart type, data transform, or export format is introduced.

package/docs/agent/development/roadmap.md

@@ -1,6 +1,6 @@
 # iChart.js 2.0 Roadmap
 
-> Roadmap baseline: 2026-09-14. Current release status: `v2.0.4` is published and `v2.0.5` is prepared as the Iteration 10A export-contract and usage-guidance patch release. Geographic charts and 3D rendering remain out of scope until explicitly reintroduced.
+> Roadmap baseline: 2026-09-14. Current release status: `v2.0.6` is prepared from the completed Iteration 11 visual preference work. Geographic charts and 3D rendering remain out of scope until explicitly reintroduced.
 
 ## Current Status
 
@@ -12,7 +12,8 @@
 - Iteration 7 local runtime and browser acceptance are complete for foundational composition, Heatmap, and Radar; physical-device checks remain host integration evidence.
 - Iteration 8A–8D is complete and accepted in automated tests, Chromium, Firefox 144, WebKit 26, native Safari 26.6.2, and a 390 px touch viewport. Physical iOS/Android and representative release-host measurements remain post-release host/device follow-up. No new public chart type was introduced.
 - Iteration 9A–9D implemented the lightweight visual style system, adaptive theme planning, runtime switching, renderer integration, and bilingual Agent guidance without adding a chart type; these capabilities remain in the `2.0.x` line.
-- Iteration 10A Export Contract Hardening is implemented on `develop`: export representations and type errors are deterministic, optional Node raster export uses `exportAsync()`, Canvas/SVG paint semantics are aligned, and the playground server has safer port/path handling. No chart behavior or public chart type was added.
+- Iteration 10A Export Contract Hardening was implemented and released in `v2.0.5`: export representations and type errors are deterministic, optional Node raster export uses `exportAsync()`, Canvas/SVG paint semantics are aligned, and the playground server has safer port/path handling. No chart behavior or public chart type was added.
+- Iteration 11 visual preference controls are included in the `v2.0.6` release: compact per-chart settings, capability-aware visibility controls, theme-aware icon contrast, explicit font-size defaults, shared page preferences, and Agent-adjustable global settings.
 - The original `2.0.0` readiness record is historical and superseded by the published `2.0.x` releases. Current release checks are defined by `docs/agent/development/release-sop.md`.
 
 ## Iteration 4 — Agent Data Contract and Business Editing
@@ -248,6 +249,29 @@ The following remain deferred beyond this roadmap baseline:
 
 They should only be scheduled after the core runtime, diagram model, and project analytics contracts are stable.
 
+## Iteration 11 — Chart Preferences and Agent Adjustments
+
+### Goal
+
+Allow users and Agents to adjust a chart's visual presentation after creation through one small, auditable contract. The detailed 11A–11D plan is in `docs/agent/development/iteration-11.md`.
+
+### Tasks
+
+1. Add allowlisted preferences for theme, typography scale, density, components, branding, and motion.
+2. Support chart-scoped and page-global inheritance through an explicit Preferences Store.
+3. Persist only versioned preference state through browser `localStorage` or a host adapter.
+4. Add an optional accessible settings button outside the SVG/Canvas export surface.
+5. Let Agents apply natural-language intent as a validated preference patch with source and scope metadata.
+6. Add Playground and bilingual guidance for UI and Agent adjustment workflows.
+
+### Verification
+
+- Global changes reach all charts sharing a store; chart overrides remain isolated.
+- UI, Agent, and host code use the same `preferenceschange` event path.
+- Invalid patches do not mutate preferences or business data.
+- Settings UI is excluded from SVG, PNG, and JSON chart exports.
+- `npm run agent:check`, `git diff --check`, and `http://localhost:3000/playground/preferences-lab.html` acceptance pass.
+
 ## Recommended Execution Order
 
 1. Finish Iteration 3 browser acceptance.
@@ -257,4 +281,5 @@ They should only be scheduled after the core runtime, diagram model, and project
 5. Execute Iteration 7 foundations before considering additional specialized chart types.
 6. Execute Iteration 8 to complete existing chart behavior, Agent adaptation, and the 2.0 release gates.
 7. Execute Iteration 9 to standardize adaptive visual styling without expanding chart count.
-8. Re-evaluate geographic and 3D scope only after usage data confirms demand.
+8. Execute Iteration 11 to add post-creation chart and page preferences without expanding chart count.
+9. Re-evaluate geographic and 3D scope only after usage data confirms demand.

package/docs/agent/frontend-integration.md

@@ -10,7 +10,7 @@ This is the production component path. For one-off files or Agent-led repository
 npm install @taylorwong/ichartjs@^2
 ```
 
-For environments without npm registry access, install from GitHub as a fallback: `npm install github:wanghetommy/ichartjs#v2.0.5`.
+For environments without npm registry access, install from GitHub as a fallback: `npm install github:wanghetommy/ichartjs#v2.0.6`.
 
 Use the package through a bundler or another environment that resolves npm ESM imports:
 

package/docs/agent/theme-guide.md

@@ -57,3 +57,34 @@ Built-in modes expose text, muted text, axis, grid, focus, selection, missing-va
 
 Preview and acceptance: `http://localhost:3000/playground/theme-gallery.html`.
 
+## Chart and Page Preferences
+
+Use preferences for visual adjustments that a user or Agent may change after the chart has been created. Keep business data, encodings, and chart selection outside this surface.
+
+```js
+import { createChart, createPreferencesStore, mountChartSettings } from '@taylorwong/ichartjs';
+
+const pagePreferences = createPreferencesStore({
+  storage: 'localStorage',
+  storageKey: 'my-app:chart-preferences'
+});
+const chart = createChart({
+  chartId: 'revenue',
+  container: '#revenue',
+  type: 'line',
+  data: { values: rows },
+  preferences: pagePreferences
+});
+mountChartSettings(chart, { locale: 'en' });
+
+// The same operation can come from an Agent conversation.
+chart.setPreferences({
+  theme: { preset: 'dashboard', palette: 'status' },
+  typography: { scale: 1.15 },
+  components: { grid: false }
+}, { source: 'agent' });
+```
+
+The optional per-chart menu uses a compact hamburger icon and intentionally exposes only high-frequency controls: theme mode, palette, font scale, and supported legend/label/grid visibility. Capability checks hide controls that do not apply to the current chart. Changes apply immediately and the UI supports `en`, `zh-CN`, and automatic document-language detection.
+
+Keep low-frequency and page-wide controls in a dedicated settings surface outside the chart popover. Share one store across the page, and call `store.setGlobal()` or `chart.setPreferences(patch, { scope: 'global' })`. The full surface may expose preset, density, branding, and other allowlisted preferences without overloading every chart. The store uses memory in Node/SSR unless `localStorage` or a host adapter is explicitly selected. Preview the quick menu in `http://localhost:3000/playground/project-gallery.html` and the full page at `http://localhost:3000/playground/preferences-lab.html`.

package/docs/agent/usage-scenarios.md

@@ -35,6 +35,22 @@ The Skill is not a second renderer or service. A Skill-enabled Agent still needs
 
 JSON is the machine-readable source of truth. SVG and PNG/JPEG are presentation artifacts. Code is the integration artifact. An interactive page is the product artifact.
 
+## Visual Preferences: UI and Agent
+
+For post-creation visual adjustments, share a `createPreferencesStore()` with the page's charts. Use `storage: 'localStorage'` only in a browser when the host wants preferences to survive refreshes. `mountChartSettings(chart)` adds an optional accessible quick-settings button outside the export surface; keep the full page-level settings surface as a separate host route.
+
+The host or Agent can use the same patch contract:
+
+```js
+chart.setPreferences({
+  theme: { preset: 'dashboard', palette: 'status' },
+  typography: { scale: 1.15 },
+  components: { grid: false }
+}, { source: 'agent' });
+```
+
+Keep the quick menu limited to theme, palette, font scale, and capability-supported visibility toggles. Use `scope: 'global'` for a page-wide update, the default chart scope for a single chart, and `chart.getState().preferences` for an auditable effective result. Preview both layers at `http://localhost:3000/playground/project-gallery.html` and `http://localhost:3000/playground/preferences-lab.html`.
+
 ## Scenario 1: Integrate into a Web Project
 
 Install the runtime in the host application:
@@ -90,7 +106,28 @@ For a consumer project, return that project's own development URL.
 
 ## Scenario 3: Use the Official Skill
 
-Install or select `skills/ichartjs` in Codex, WorkBuddy, or another Agent Skills-compatible host. Then ask:
+Install the latest Skill with the standard Agent Skills CLI:
+
+```bash
+npx skills add wanghetommy/ichartjs --skill ichartjs
+```
+
+Install globally for Codex without prompts:
+
+```bash
+npx skills add wanghetommy/ichartjs --skill ichartjs --agent codex --global --yes
+```
+
+For reproducible installation, pin the released Skill directory:
+
+```bash
+npx skills add https://github.com/wanghetommy/ichartjs/tree/v2.0.6/skills/ichartjs \
+  --agent codex --global --yes
+```
+
+WorkBuddy users can import the same tagged GitHub directory through the host's Skill interface. Do not assume that `--agent workbuddy` exists unless the installed Skills CLI lists that adapter. A manual copy from `node_modules/@taylorwong/ichartjs/skills/ichartjs` remains a fallback for hosts with custom Skill directories.
+
+After installation or selection, ask:
 
 ```text
 Use the iChart.js Skill. Read this dataset, create a project Burndown,

package/docs/agent/zh-CN/coding-agent-integration.md

@@ -16,12 +16,16 @@ npm install @taylorwong/ichartjs@^2
 
 npm Registry 中无作用域的 `ichartjs` 是安全占位包，并非本项目。正式包名是 `@taylorwong/ichartjs`，优先从 npm 安装。
 
-Codex、WorkBuddy 和其他兼容 Agent Skills 的宿主可共同使用 `skills/ichartjs`。从仓库检出目录安装到 Codex：
+使用标准 Agent Skills CLI 安装官方 Skill：
 
 ```bash
-cp -R skills/ichartjs "${CODEX_HOME:-$HOME/.codex}/skills/"
+npx skills add wanghetommy/ichartjs --skill ichartjs
 ```
 
+Codex 全局无交互安装可追加 `--agent codex --global --yes`。需要固定发布版本时，安装 `https://github.com/wanghetommy/ichartjs/tree/v2.0.6/skills/ichartjs`。WorkBuddy 可通过自身 Skill 界面导入该带 Tag 的目录；只有当前 CLI 明确声明对应适配器时才使用宿主专用 `--agent` 参数。
+
+使用 `npx skills add wanghetommy/ichartjs --list` 验证发现结果，其中应包含 `ichartjs`。
+
 推荐请求：
 
 ```text

package/docs/agent/zh-CN/frontend-integration.md

@@ -6,7 +6,7 @@ iChart.js 应作为普通 JavaScript UI 组件运行在浏览器应用中。数
 npm install @taylorwong/ichartjs@^2
 ```
 
-无法访问 npm Registry 的环境请用 GitHub 源作为后备：`npm install github:wanghetommy/ichartjs#v2.0.5`。
+无法访问 npm Registry 的环境请用 GitHub 源作为后备：`npm install github:wanghetommy/ichartjs#v2.0.6`。
 
 ```js
 import { createChart } from '@taylorwong/ichartjs';

package/docs/agent/zh-CN/theme-guide.md

@@ -48,3 +48,34 @@ const resolved = chart.getTheme();
 
 预览与验收：`http://localhost:3000/playground/theme-gallery.html`。
 
+## 单图表与页面级偏好
+
+偏好用于图表创建后的视觉调整，适合用户操作和 Agent 对话调整。业务数据、编码和图表类型不应放进这个配置面。
+
+```js
+import { createChart, createPreferencesStore, mountChartSettings } from '@taylorwong/ichartjs';
+
+const pagePreferences = createPreferencesStore({
+  storage: 'localStorage',
+  storageKey: 'my-app:chart-preferences'
+});
+const chart = createChart({
+  chartId: 'revenue',
+  container: '#revenue',
+  type: 'line',
+  data: { values: rows },
+  preferences: pagePreferences
+});
+mountChartSettings(chart, { locale: 'zh-CN' });
+
+// Agent 对话也使用同一套 API。
+chart.setPreferences({
+  theme: { preset: 'dashboard', palette: 'status' },
+  typography: { scale: 1.15 },
+  components: { grid: false }
+}, { source: 'agent' });
+```
+
+单图表快捷菜单使用紧凑的汉堡图标，只保留高频操作：主题模式、配色、字号，以及当前图表真正支持的图例、数据标签和网格线。能力检测会自动隐藏无效设置；修改即时生效，并支持 `zh-CN`、`en` 和按文档语言自动识别。
+
+低频选项和页面级配置应放在图表弹出菜单之外的独立设置页。页面内图表共享同一个 store，并使用 `store.setGlobal()` 或 `chart.setPreferences(patch, { scope: 'global' })` 更新全局。完整设置页可提供 preset、密度、署名等白名单能力，而不挤占每张图表。Node/SSR 默认使用内存，浏览器需要显式选择 `localStorage` 或宿主存储适配器。快捷菜单验收地址：`http://localhost:3000/playground/project-gallery.html`；完整页面设置验收地址：`http://localhost:3000/playground/preferences-lab.html`。

package/docs/agent/zh-CN/usage-scenarios.md

@@ -35,6 +35,22 @@ Skill 不是第二套渲染器，也不是服务端。使用 Skill 的 Agent 仍
 
 JSON 是机器可读的事实来源；SVG 和 PNG/JPEG 是视觉交付物；代码是集成交付物；交互页面是产品交付物。
 
+## 视觉偏好：界面与 Agent
+
+图表创建后需要调整视觉样式时，可让页面图表共享 `createPreferencesStore()`。浏览器中只有在宿主希望刷新后保留配置时，才显式使用 `storage: 'localStorage'`。`mountChartSettings(chart)` 会在导出区域之外增加可访问的快捷设置按钮；完整的页面级设置中心应作为宿主的独立路由。
+
+宿主交互和 Agent 对话使用同一个 patch 合约：
+
+```js
+chart.setPreferences({
+  theme: { preset: 'dashboard', palette: 'status' },
+  typography: { scale: 1.15 },
+  components: { grid: false }
+}, { source: 'agent' });
+```
+
+快捷菜单只保留主题、配色、字号和当前图表支持的显示开关。使用 `scope: 'global'` 修改页面全部图表；默认只修改当前图表；使用 `chart.getState().preferences` 获取可审计的最终配置。两层体验可在 `http://localhost:3000/playground/project-gallery.html` 和 `http://localhost:3000/playground/preferences-lab.html` 验收。
+
 ## 场景一：集成到 Web 项目
 
 在宿主项目中安装 Runtime：
@@ -85,7 +101,28 @@ Agent 应返回：
 
 ## 场景三：作为官方 Skill 使用
 
-在 Codex、WorkBuddy 或其他支持 Agent Skills 的宿主中安装或选择 `skills/ichartjs`：
+使用标准 Agent Skills CLI 安装最新版：
+
+```bash
+npx skills add wanghetommy/ichartjs --skill ichartjs
+```
+
+无交互地全局安装到 Codex：
+
+```bash
+npx skills add wanghetommy/ichartjs --skill ichartjs --agent codex --global --yes
+```
+
+需要固定发布版本时，直接安装已发布的 Skill 目录：
+
+```bash
+npx skills add https://github.com/wanghetommy/ichartjs/tree/v2.0.6/skills/ichartjs \
+  --agent codex --global --yes
+```
+
+WorkBuddy 用户可以通过宿主的 Skill 界面导入同一个带 Tag 的 GitHub 目录。在当前 Skills CLI 没有明确声明适配器时，不要假设存在 `--agent workbuddy`。具有自定义 Skill 目录的宿主仍可从 `node_modules/@taylorwong/ichartjs/skills/ichartjs` 手动复制。
+
+安装或选择 `ichartjs` 后可以这样提问：
 
 ```text
 使用 iChart.js Skill。读取这份数据，生成项目 Burndown，校验 Spec，

package/docs/manifests/capabilities.json

@@ -59,7 +59,15 @@
   "projectIntelligenceDemo": "playground/project-intelligence.html",
   "foundationalGallery": "playground/foundational-gallery.html",
   "themeGallery": "playground/theme-gallery.html",
+  "preferencesLab": "playground/preferences-lab.html",
   "themeGuide": "docs/agent/theme-guide.md",
+  "preferences": {
+    "version": "1.0",
+    "scopes": ["global", "chart"],
+    "persistence": ["memory", "localStorage", "adapter"],
+    "agentAdjustable": true,
+    "interactiveSettingsUI": true
+  },
   "styleSystem": {
     "modes": ["auto", "light", "dark", "contrast"],
     "presets": ["auto", "analysis", "dashboard", "report", "presentation", "project", "diagram"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taylorwong/ichartjs",
-  "version": "2.0.5",
+  "version": "2.0.6",
   "description": "Agent-first, renderer-independent charting and project visualization runtime",
   "type": "module",
   "main": "./src/index.mjs",

package/skills/ichartjs/SKILL.md

@@ -7,7 +7,7 @@ description: Plan, validate, render, explain, and safely edit iChart.js visualiz
 
 Use the public Agent contract as the source of truth. Do not infer capabilities from renderer internals or duplicate chart-selection logic in generated code.
 
-Read [`docs/agent/usage-scenarios.md`](../../docs/agent/usage-scenarios.md) when the request is ambiguous about whether the output should be a live project component, a Coding Agent change, a Skill-generated artifact, or a scheduled report.
+Read the [usage scenarios](https://github.com/wanghetommy/ichartjs/blob/master/docs/agent/usage-scenarios.md) when the request is ambiguous about whether the output should be a live project component, a Coding Agent change, a Skill-generated artifact, or a scheduled report.
 
 ## Source and Runtime Setup
 
@@ -15,6 +15,14 @@ Read [`docs/agent/usage-scenarios.md`](../../docs/agent/usage-scenarios.md) when
 - Official Skill source: `https://github.com/wanghetommy/ichartjs/tree/master/skills/ichartjs`
 - Supported Skill hosts include Codex, WorkBuddy, and other Agent Skills-compatible environments.
 
+Recommended installation:
+
+```bash
+npx skills add wanghetommy/ichartjs --skill ichartjs
+```
+
+Use `--agent codex --global --yes` for global non-interactive Codex installation. Use the tagged directory `https://github.com/wanghetommy/ichartjs/tree/v2.0.6/skills/ichartjs` when reproducibility matters. WorkBuddy can import the same directory through its Skill interface; do not assume a `--agent workbuddy` adapter unless the installed CLI declares it.
+
 The Skill is a workflow adapter, not the chart runtime. If the current JavaScript or TypeScript project does not already depend on iChart.js, install the matching runtime from GitHub:
 
 ```bash
@@ -54,7 +62,7 @@ Route by requested output:
 - For Flow or Swimlane, preserve node, edge, lane, group, and port IDs; use diagram recipes and validated edit commands.
 - For business edits, preview first, preserve the preview ID and revision, require confirmation when declared, then commit or reject atomically.
 - For browser deliverables, start `npm run playground` and return the exact maintained Playground URL.
-- Release workflow (npm publish + develop→master merge) is **AUTHOR ONLY**. Read the release SOP in [`docs/agent/development/release-sop.md`](../../docs/agent/development/release-sop.md). Never initiate any release step unless the author explicitly instructs.
+- Release workflow (npm publish + develop→master merge) is **AUTHOR ONLY**. Read the [release SOP](https://github.com/wanghetommy/ichartjs/blob/master/docs/agent/development/release-sop.md). Never initiate any release step unless the author explicitly instructs.
 
 ## Guardrails
 

package/src/capabilities.mjs

@@ -184,6 +184,15 @@ export function getCapabilities() {
     data: ['normalize', 'inspect', 'filter', 'sort', 'groupBy', 'sum', 'average', 'topN', 'percentage', 'bin'],
     themes: [...styleCapabilities.modes],
     styleSystem: JSON.parse(JSON.stringify(styleCapabilities)),
+    preferences: {
+      version: '1.0',
+      scopes: ['global', 'chart'],
+      persistence: ['memory', 'localStorage', 'adapter'],
+      fields: ['theme', 'typography.scale', 'density', 'components.legend', 'components.labels', 'components.grid', 'branding.enabled', 'motion'],
+      agentAdjustable: true,
+      interactiveSettingsUI: true,
+      precedence: ['defaults', 'global', 'chart', 'temporary-agent-patch']
+    },
     plugins: true,
     branding: { defaultEnabled: true, signature: 'Powered by iChart.js', options: [{ name: 'enabled', type: 'boolean', default: true }] },
   };

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 };
@@ -178,12 +181,23 @@ function renderRasterWithCanvas(createCanvas, spec, scene, rasterType, as) {
 
 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();
@@ -198,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;
@@ -299,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(); }
@@ -567,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); }
@@ -579,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.5', 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;
+}

package/types/index.d.ts

@@ -3,20 +3,28 @@ export type ChartType = 'line' | 'area' | 'bar' | 'column' | 'pie' | 'scatter' |
 export type ThemeMode = 'auto' | 'light' | 'dark' | 'contrast';
 export type ThemePreset = 'auto' | 'analysis' | 'dashboard' | 'report' | 'presentation' | 'project' | 'diagram';
 export type ThemePalette = 'auto' | 'categorical' | 'sequential' | 'diverging' | 'status';
+export type PreferenceTriState = 'auto' | boolean;
+export type PreferenceDensity = 'compact' | 'comfortable' | 'spacious';
+export type PreferenceMotion = 'auto' | 'full' | 'reduced' | 'off';
 export type ExportKind = 'json' | 'svg' | 'png' | 'jpeg' | 'jpg' | 'image/png' | 'image/jpeg' | 'image/svg+xml' | 'application/json';
 export type ExportAs = 'string' | 'dataurl' | 'blob' | 'object';
 export interface ExportError { valid: false; code: string; rasterCode?: string; message?: string; suggestion?: string; [key: string]: unknown }
 export interface ThemeConfig { mode?: ThemeMode; preset?: ThemePreset; palette?: ThemePalette; tokens?: Record<string, unknown>; branding?: boolean | { enabled?: boolean; [key: string]: unknown }; [key: string]: unknown; }
+export interface ChartPreferences { version: '1.0'; theme: { mode: ThemeMode | null; preset: ThemePreset | null; palette: ThemePalette | null }; typography: { scale: number }; density: PreferenceDensity; components: { legend: PreferenceTriState; labels: PreferenceTriState; grid: PreferenceTriState }; branding: { enabled: PreferenceTriState }; motion: PreferenceMotion; }
+export type ChartPreferencesPatch = Partial<Omit<ChartPreferences, 'version'>> & { version?: '1.0'; theme?: Partial<ChartPreferences['theme']>; typography?: Partial<ChartPreferences['typography']>; components?: Partial<ChartPreferences['components']>; branding?: Partial<ChartPreferences['branding']> };
+export interface PreferencesStoreState { version: '1.0'; global: ChartPreferences; charts: Record<string, ChartPreferencesPatch>; }
+export interface PreferencesStore { version: '1.0'; storageKey: string; storage: 'localStorage' | 'memory'; getState(): PreferencesStoreState; getGlobal(): ChartPreferences; getChart(chartId: string): ChartPreferencesPatch; getEffective(chartId?: string | null): ChartPreferences; setGlobal(patch: ChartPreferencesPatch, options?: { source?: string; persist?: boolean }): ChartPreferences; setChart(chartId: string, patch: ChartPreferencesPatch, options?: { source?: string; persist?: boolean }): ChartPreferences; reset(options?: { scope?: 'all' | 'global' | 'chart'; chartId?: string; source?: string; persist?: boolean }): ChartPreferences; subscribe(listener: (event: { type: 'change'; scope: string; chartId: string | null; source: string; persisted: boolean; preferences: ChartPreferences; state: PreferencesStoreState }) => void): () => void; persist(): boolean; }
+export interface PreferencesStorage { getItem(key: string): string | null; setItem(key: string, value: string): void; removeItem?(key: string): void; }
 export interface StyleRecommendation { version: '1.0'; preset: Exclude<ThemePreset, 'auto'>; mode: ThemeMode; resolvedMode: Exclude<ThemeMode, 'auto'>; palette: Exclude<ThemePalette, 'auto'>; reasons: string[]; warnings: Diagnostic[]; userOverride: boolean; }
 export interface ResolvedTheme extends ThemeConfig { name: string; resolvedMode: Exclude<ThemeMode, 'auto'>; background: string; surface: string; text: string; muted: string; axis: string; grid: string; border: string; focus: string; selection: string; colors: string[]; palettes: Record<string, unknown>; status: Record<string, string>; typography: Record<string, { size: number; weight: number; lineHeight: number; font: string }>; layout: Record<string, unknown>; marks: Record<string, unknown>; reasons: string[]; warnings: Diagnostic[]; }
 export interface Diagnostic { code: string; path?: string; message: string; expected?: unknown; suggestion?: string; [key: string]: unknown; }
 export interface DataFieldInfo { name: string; type: 'quantitative' | 'temporal' | 'category' | 'unknown'; role: 'identifier' | 'measure' | 'temporal-dimension' | 'dimension'; unit: string | null; cardinality: number; validCount: number; nullCount: number; min?: number; max?: number; temporalMin?: string; temporalMax?: string; }
 export interface DataInspection { version: '1.0'; rows: number; fields: DataFieldInfo[]; dimensions: string[]; measures: string[]; temporalFields: string[]; missingValueCount: number; warnings: Diagnostic[]; }
 export interface ChartCapability { type: ChartType; family: string; intents: string[]; required: string[]; optional: string[]; dataShapes: string[]; interactions: string[]; features: Record<string, 'supported' | 'not-applicable' | 'degraded'>; renderers: Array<'canvas' | 'svg'>; exports: string[]; limits: Record<string, number>; }
-export interface RuntimeCapabilities { version: '2.0'; contractVersion: '1.0'; chartTypes: ChartType[]; charts: Record<ChartType, ChartCapability>; intents: string[]; renderers: Array<'canvas' | 'svg'>; interactions: string[]; exports: Array<'png' | 'svg' | 'json' | 'jpeg'>; styleSystem: { modes: ThemeMode[]; presets: ThemePreset[]; palettes: ThemePalette[]; switchable: boolean; automatic: boolean; [key: string]: unknown }; headless: { preview?: boolean; json: boolean; svg: boolean; png: boolean | string }; export: { types: string[]; mime: Record<string, string>; browser: Record<string, boolean>; headless: Record<string, string | boolean>; methods: string[]; options: Record<string, unknown>; branding: Record<string, unknown> }; branding: { defaultEnabled: boolean; signature: string; options: Record<string, unknown> }; [key: string]: unknown; }
+export interface RuntimeCapabilities { version: '2.0'; contractVersion: '1.0'; chartTypes: ChartType[]; charts: Record<ChartType, ChartCapability>; intents: string[]; renderers: Array<'canvas' | 'svg'>; interactions: string[]; exports: Array<'png' | 'svg' | 'json' | 'jpeg'>; styleSystem: { modes: ThemeMode[]; presets: ThemePreset[]; palettes: ThemePalette[]; switchable: boolean; automatic: boolean; [key: string]: unknown }; preferences?: { version: '1.0'; scopes: string[]; persistence: string[]; fields: string[]; agentAdjustable: boolean; interactiveSettingsUI: boolean; precedence: string[] }; headless: { preview?: boolean; json: boolean; svg: boolean; png: boolean | string }; export: { types: string[]; mime: Record<string, string>; browser: Record<string, boolean>; headless: Record<string, string | boolean>; methods: string[]; options: Record<string, unknown>; branding: Record<string, unknown> }; branding: { defaultEnabled: boolean; signature: string; options: Record<string, unknown> }; [key: string]: unknown; }
 export interface ChartPlan { version: '1.0'; intent: string; primary: ChartType; alternatives: ChartType[]; confidence: number; reasons: string[]; requiredFields: string[]; suggestedEncodings: { dimension: string | null; measure: string | null; secondaryMeasure: string | null }; assumptions: string[]; warnings: Diagnostic[]; unsupportedRequests: string[]; nextActions: string[]; capability: ChartCapability; styleRecommendation: StyleRecommendation; data: DataInspection; }
 export interface ChartExplanation { version: '1.0'; type: ChartType; family: string; purpose: string; renderer: Renderer; dataCount: number; encodings: Record<string, string | string[]>; transforms: string[]; interactions: string[]; assumptions: string[]; warnings: Diagnostic[]; style: Partial<StyleRecommendation> & { name?: string }; lineage: { recordIds: string[]; sourcePreserved: boolean }; accessibility: { enabled: boolean; summary: string }; }
-export interface ChartSpec { type: ChartType; renderer?: Renderer; container?: string | Element; width?: number; height?: number; data?: Array<Record<string, unknown>> | { values?: Array<Record<string, unknown>>; [key: string]: unknown }; encoding?: Record<string, unknown>; title?: { text?: string; subtitle?: string }; legend?: { visible?: boolean; position?: string }; grid?: { visible?: boolean; color?: string }; labels?: { enabled?: boolean; format?: string | Record<string, unknown>; color?: string; font?: string }; interaction?: Record<string, boolean>; accessibility?: { enabled?: boolean; description?: string }; branding?: boolean | { enabled?: boolean }; theme?: ThemeMode | ThemePreset | ThemeConfig | ResolvedTheme; [key: string]: unknown; }
+export interface ChartSpec { type: ChartType; renderer?: Renderer; container?: string | Element; chartId?: string; width?: number; height?: number; data?: Array<Record<string, unknown>> | { values?: Array<Record<string, unknown>>; [key: string]: unknown }; encoding?: Record<string, unknown>; title?: { text?: string; subtitle?: string }; legend?: { visible?: boolean; position?: string }; grid?: { visible?: boolean; color?: string }; labels?: { enabled?: boolean; format?: string | Record<string, unknown>; color?: string; font?: string }; interaction?: Record<string, boolean>; accessibility?: { enabled?: boolean; description?: string }; branding?: boolean | { enabled?: boolean }; theme?: ThemeMode | ThemePreset | ThemeConfig | ResolvedTheme; preferences?: ChartPreferencesPatch | PreferencesStore; preferencesStore?: PreferencesStore; [key: string]: unknown; }
 export interface BinTransform { type: 'bin'; field: string; output?: string; thresholds?: number; step?: number; extent?: [number, number]; }
 export interface RadarIndicator { name: string; field: string; min?: number; max?: number; }
 export type BusinessFieldType = 'string' | 'number' | 'boolean' | 'date' | 'enum' | 'array' | 'object';
@@ -46,6 +54,9 @@ export interface Chart {
   setData(data: Array<Record<string, unknown>>): this;
   setTheme(theme?: ChartSpec['theme']): this;
   getTheme(): ResolvedTheme;
+  getPreferences(): ChartPreferences;
+  setPreferences(patch?: ChartPreferencesPatch, options?: { scope?: 'chart' | 'global'; source?: string; persist?: boolean }): this;
+  resetPreferences(options?: { scope?: 'all' | 'global' | 'chart'; source?: string; persist?: boolean }): this;
   resize(width?: number, height?: number): this;
   resetZoom(): this;
   zoomTo(view: Record<string, number>): this;
@@ -87,6 +98,13 @@ export interface Chart {
 }
 
 export function createChart(spec: ChartSpec): Chart;
+export const defaultPreferences: ChartPreferences;
+export function createPreferencesStore(options?: { storage?: 'localStorage' | 'memory' | PreferencesStorage; storageKey?: string; global?: ChartPreferencesPatch; charts?: Record<string, ChartPreferencesPatch> }): PreferencesStore;
+export function normalizePreferences(input?: ChartPreferencesPatch, options?: { partial?: boolean }): ChartPreferences;
+export function mergePreferences(...values: ChartPreferencesPatch[]): ChartPreferences;
+export function mergeThemePreference(theme: ChartSpec['theme'], preferenceTheme?: Partial<ChartPreferences['theme']>): ChartSpec['theme'];
+export function applyPreferencesToSpec(spec: ChartSpec, preferences?: ChartPreferencesPatch): ChartSpec;
+export function mountChartSettings(chart: Chart, options?: { container?: Element; locale?: 'auto' | 'zh-CN' | 'en'; title?: string }): { valid: true; element: Element; locale: 'zh-CN' | 'en'; destroy(): void } | { valid: false; code: string; message: string };
 export function normalizeSpec(spec: Partial<ChartSpec>): ChartSpec;
 export function validateSpec(spec: Partial<ChartSpec>): { valid: boolean; errors: Diagnostic[]; warnings: Diagnostic[]; normalizations: Diagnostic[]; spec: ChartSpec };
 export function normalizeData(input: unknown): { rows: Array<Record<string, unknown>>; fields: DataFieldInfo[]; warnings: Diagnostic[] };