@chartguard/runtime-echarts 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ChartGuard contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,27 @@
-# Temporary Holding Version
+# @chartguard/runtime-echarts
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A safe `setOption` for Apache ECharts: the option is checked as the call will apply it to this chart, then set. Nothing is patched; call it instead of `chart.setOption`.
+
+**Status:** pre-release (0.x). Coverage is partial, and the API and settings may still change between minor versions.
+
+```sh
+npm install @chartguard/runtime-echarts
+```
+
+```ts
+import * as echarts from "echarts";
+import { setOption } from "@chartguard/runtime-echarts";
+
+const chart = echarts.init(element);
+setOption(chart, option, undefined, { options: { libraryVersion: echarts.version } });
+setOption(chart, { series: [{ data: next }] }); // a merge update: checked against the series it merges into
+```
+
+- **A fresh option** (the chart has none yet, `notMerge`, or `replaceMerge` naming `series`) needs a `type` on every series: echarts drops one without it ("Unknown series"); ChartGuard reports `CFG_REQUIRED $.series[i].type`.
+- **A merge update** may leave the type out: when its series name no `id` or `name`, each one is checked as the type of the series it merges into, matched by position as echarts matches it (an entry that is not an object takes no series), and one beyond the chart's series is reported (echarts drops it). A disposed chart sets nothing: nothing is claimed about what it would drop. What the chart holds is read once per call. What an update leaves out (the axes it does not repeat) is not a finding; a rule about it is reported as unresolved.
+- `checkOption(chart, option, settings?)` gives the same result without setting anything.
+- **What is registered**: pass the namespace you call `use` on (`{ echarts }`, from `echarts/core`). Each call then reads what it has registered: a series or component that is not registered is a confirmed `CFG_UNREGISTERED` error (echarts would drop it or throw). `registriesOf(echarts)` gives the same context for your own validation.
+- **Reporting**: `onResult(result, { fresh })` receives every result; without it, a result with confirmed errors is written with `console.warn`. **Blocking**: `{ block: true }` does not set an invalid option.
+- Pass `libraryVersion: echarts.version`: an ECharts instance does not say which version it is. `validator` replaces the shipped schema (for example `withExtensions([...])` from `@chartguard/config-echarts`).
+
+The option you pass is never changed and its getters are never run.

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+/** Never monkey-patches global APIs. Caller owns the original factory and side effects. */
+export declare const validateBeforeCreate: import("@chartguard/core").ValidateBeforeCreate;
+export { type EChartsRuntime, registriesOf } from './registries.js';
+export type { EChartsInstance, SetOptionGuard, SetOptionSettings } from './set-option.js';
+export { checkOption, setOption } from './set-option.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,2FAA2F;AAC3F,eAAO,MAAM,oBAAoB,iDAAkD,CAAC;AAEpF,OAAO,EAAE,KAAK,cAAc,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpE,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAC1F,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+import { validate } from '@chartguard/config-echarts';
+import { createValidateBeforeCreate } from '@chartguard/core';
+/** Never monkey-patches global APIs. Caller owns the original factory and side effects. */
+export const validateBeforeCreate = createValidateBeforeCreate('echarts', validate);
+export { registriesOf } from './registries.js';
+export { checkOption, setOption } from './set-option.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AACtD,OAAO,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AAE9D,2FAA2F;AAC3F,MAAM,CAAC,MAAM,oBAAoB,GAAG,0BAA0B,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;AAEpF,OAAO,EAAuB,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/registries.d.ts

@@ -0,0 +1,14 @@
+import { type RegistryContext } from '@chartguard/core';
+/** The part of the `echarts` (or `echarts/core`) namespace the registry context is read from. */
+export interface EChartsRuntime {
+    readonly ComponentModel?: unknown;
+}
+/**
+ * The registry context of a live ECharts (CG-04-05): every series and component class it has
+ * registered now, as echarts names them (`series.bar`, `dataZoom.slider`, `grid`), read through its
+ * own class registry (`ComponentModel.getAllClassMainTypes`/`getClassesByMainType`, echarts@6.1.0
+ * `lib/util/clazz.js`). Pass the namespace the application calls `use` on (`echarts/core`), or the
+ * full `echarts`. A namespace without that registry gives no context, so no claim.
+ */
+export declare function registriesOf(echarts: EChartsRuntime): Readonly<Record<string, RegistryContext>>;
+//# sourceMappingURL=registries.d.ts.map

package/dist/registries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registries.d.ts","sourceRoot":"","sources":["../src/registries.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAErE,iGAAiG;AACjG,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;CAClC;AAiBD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,cAAc,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAa/F"}

package/dist/registries.js

@@ -0,0 +1,35 @@
+import { isContainer } from '@chartguard/core';
+/**
+ * A property of the runtime, read as the runtime exposes it: a bundler's module namespace exports
+ * are getters (esbuild `__export`), so reading only data properties would find no registry. This is
+ * the library, never the caller's option, whose getters are never run.
+ */
+const read = (value, key) => isContainer(value) || typeof value === 'function' ? value[key] : undefined;
+const listerOf = (model, key) => {
+    const method = read(model, key);
+    return typeof method === 'function' ? method : undefined;
+};
+/**
+ * The registry context of a live ECharts (CG-04-05): every series and component class it has
+ * registered now, as echarts names them (`series.bar`, `dataZoom.slider`, `grid`), read through its
+ * own class registry (`ComponentModel.getAllClassMainTypes`/`getClassesByMainType`, echarts@6.1.0
+ * `lib/util/clazz.js`). Pass the namespace the application calls `use` on (`echarts/core`), or the
+ * full `echarts`. A namespace without that registry gives no context, so no claim.
+ */
+export function registriesOf(echarts) {
+    const model = read(echarts, 'ComponentModel');
+    const mainTypes = listerOf(model, 'getAllClassMainTypes');
+    const classes = listerOf(model, 'getClassesByMainType');
+    if (mainTypes === undefined || classes === undefined)
+        return {};
+    const listed = mainTypes();
+    if (!Array.isArray(listed))
+        return {};
+    const types = listed.flatMap((mainType) => {
+        const found = typeof mainType === 'string' ? classes(mainType) : undefined;
+        return Array.isArray(found) ? found.map((item) => read(item, 'type')) : [];
+    });
+    const names = types.filter((type) => typeof type === 'string');
+    return { echarts: { names: [...new Set(names)].sort(), complete: true } };
+}
+//# sourceMappingURL=registries.js.map

package/dist/registries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registries.js","sourceRoot":"","sources":["../src/registries.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAwB,MAAM,kBAAkB,CAAC;AAOrE;;;;GAIG;AACH,MAAM,IAAI,GAAG,CAAC,KAAc,EAAE,GAAW,EAAW,EAAE,CACrD,WAAW,CAAC,KAAK,CAAC,IAAI,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAE,KAAiC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAIzG,MAAM,QAAQ,GAAG,CAAC,KAAc,EAAE,GAAW,EAAsB,EAAE;IACpE,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAChC,OAAO,OAAO,MAAM,KAAK,UAAU,CAAC,CAAC,CAAE,MAAiB,CAAC,CAAC,CAAC,SAAS,CAAC;AACtE,CAAC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,OAAuB;IACnD,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,EAAE,gBAAgB,CAAC,CAAC;IAC9C,MAAM,SAAS,GAAG,QAAQ,CAAC,KAAK,EAAE,sBAAsB,CAAC,CAAC;IAC1D,MAAM,OAAO,GAAG,QAAQ,CAAC,KAAK,EAAE,sBAAsB,CAAC,CAAC;IACxD,IAAI,SAAS,KAAK,SAAS,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IAChE,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;IAC3B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,OAAO,EAAE,CAAC;IACtC,MAAM,KAAK,GAAI,MAAoB,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,EAAE;QACxD,MAAM,KAAK,GAAG,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAC3E,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAE,KAAmB,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3F,CAAC,CAAC,CAAC;IACH,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAkB,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC;IAC/E,OAAO,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,CAAC;AAC3E,CAAC"}

package/dist/set-option.d.ts

@@ -0,0 +1,40 @@
+import { type ConfigValidator, type ValidationOptions, type ValidationResult } from '@chartguard/core';
+import { type EChartsRuntime } from './registries.js';
+/** What `chart.setOption` takes besides the option: `notMerge` as a boolean, or the settings object. */
+export type SetOptionSettings = boolean | {
+    readonly notMerge?: boolean;
+    readonly replaceMerge?: string | readonly string[];
+    readonly lazyUpdate?: boolean;
+    readonly silent?: boolean;
+};
+/** The part of an ECharts instance this path uses. */
+export interface EChartsInstance {
+    setOption(option: unknown, settings?: unknown): void;
+    getOption(): unknown;
+}
+/** How `setOption` and `checkOption` validate: the validator, its options, the runtime and where results go. */
+export interface SetOptionGuard {
+    /** Replaces the shipped `validate`, e.g. `withExtensions([...])`. */
+    readonly validator?: ConfigValidator;
+    /** Passed to every validation: `libraryVersion: echarts.version`, `registries`. */
+    readonly options?: ValidationOptions;
+    /**
+     * The namespace the chart's runtime registers on (`echarts/core` after `use`, or `echarts`): what it
+     * has registered is read on every call (`registriesOf`). A registry id named in `options` wins.
+     */
+    readonly echarts?: EChartsRuntime;
+    /** Receives every result; without it, a result with confirmed errors is written with `console.warn`. */
+    readonly onResult?: (result: ValidationResult, event: {
+        readonly fresh: boolean;
+    }) => void;
+    /** An invalid option is not set: the chart keeps what it has. */
+    readonly block?: boolean;
+}
+/** The option as `chart.setOption(option, settings)` would apply it, validated; nothing is set. */
+export declare function checkOption(chart: EChartsInstance, option: unknown, settings?: SetOptionSettings, guard?: SetOptionGuard): ValidationResult;
+/**
+ * The safe `setOption` path (CG-04-03): the option is validated as the call applies it to this chart,
+ * reported, then set with its settings unless `block` and invalid. Nothing is patched.
+ */
+export declare function setOption(chart: EChartsInstance, option: unknown, settings?: SetOptionSettings, guard?: SetOptionGuard): ValidationResult;
+//# sourceMappingURL=set-option.d.ts.map

package/dist/set-option.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"set-option.d.ts","sourceRoot":"","sources":["../src/set-option.ts"],"names":[],"mappings":"AACA,OAAO,EACN,KAAK,eAAe,EAMpB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,KAAK,cAAc,EAAgB,MAAM,iBAAiB,CAAC;AAEpE,wGAAwG;AACxG,MAAM,MAAM,iBAAiB,GAC1B,OAAO,GACP;IACA,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IACnD,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAEL,sDAAsD;AACtD,MAAM,WAAW,eAAe;IAC/B,SAAS,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACrD,SAAS,IAAI,OAAO,CAAC;CACrB;AAED,gHAAgH;AAChH,MAAM,WAAW,cAAc;IAC9B,qEAAqE;IACrE,QAAQ,CAAC,SAAS,CAAC,EAAE,eAAe,CAAC;IACrC,mFAAmF;IACnF,QAAQ,CAAC,OAAO,CAAC,EAAE,iBAAiB,CAAC;IACrC;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC;IAClC,wGAAwG;IACxG,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,gBAAgB,EAAE,KAAK,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC;IAC3F,iEAAiE;IACjE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CACzB;AAyKD,mGAAmG;AACnG,wBAAgB,WAAW,CAC1B,KAAK,EAAE,eAAe,EACtB,MAAM,EAAE,OAAO,EACf,QAAQ,CAAC,EAAE,iBAAiB,EAC5B,KAAK,GAAE,cAAmB,GACxB,gBAAgB,CAElB;AAED;;;GAGG;AACH,wBAAgB,SAAS,CACxB,KAAK,EAAE,eAAe,EACtB,MAAM,EAAE,OAAO,EACf,QAAQ,CAAC,EAAE,iBAAiB,EAC5B,KAAK,GAAE,cAAmB,GACxB,gBAAgB,CAMlB"}

package/dist/set-option.js

@@ -0,0 +1,162 @@
+import { validate } from '@chartguard/config-echarts';
+import { isContainer, isRecord, ownDataProperty, result } from '@chartguard/core';
+import { registriesOf } from './registries.js';
+const own = (value, key) => {
+    if (!isContainer(value))
+        return undefined;
+    const entry = ownDataProperty(value, key);
+    return entry.found ? entry.value : undefined;
+};
+/**
+ * Whether the call sets the series afresh: the chart holds no option yet (`held` is what
+ * `getOption()` returned), `notMerge`, or `replaceMerge` naming `series`. Then echarts looks every
+ * series up by its own `type`.
+ */
+function isFresh(held, settings) {
+    if (held === undefined || settings === true)
+        return true;
+    if (!isRecord(settings))
+        return false;
+    const replaced = settings.replaceMerge;
+    const names = Array.isArray(replaced) ? replaced : [replaced];
+    return settings.notMerge === true || names.includes('series');
+}
+/** A series list as items with their paths: `series: […]` or a single `series: {…}`. */
+function itemsAt(series, path) {
+    if (Array.isArray(series))
+        return series.map((item, index) => ({ item, path: `${path}[${String(index)}]` }));
+    return series === undefined ? [] : [{ item: series, path }];
+}
+/** An item without its own `type` (an accessor is not known, so it claims nothing). */
+const untyped = (item) => isRecord(item) && !Object.hasOwn(item, 'type');
+/**
+ * echarts drops a series it cannot find a model for by type ("Unknown series", `SOURCES` in
+ * sources.ts): an untyped item of a fresh option, or of a merge beyond the
+ * series the chart has when the update names none by `id` or `name`.
+ */
+function dropped(path) {
+    return {
+        code: 'CFG_REQUIRED',
+        severity: 'error',
+        confidence: 'certain',
+        path: `${path}.type`,
+        message: 'This series has no type and no series to merge into: echarts drops it ("Unknown series").'
+    };
+}
+/** The series the chart holds, in order (`held` is what `getOption()` returned). */
+function heldSeries(held) {
+    const series = own(held, 'series');
+    return Array.isArray(series) ? series : [];
+}
+/** A merge without `id` or `name`: items merge into the chart's series by position. */
+const byIndex = (items) => items.every(({ item }) => own(item, 'id') === undefined && own(item, 'name') === undefined);
+/** echarts' `isObject`: what a component list keeps; anything else it sets to `null` and skips. */
+const isObjectLike = (value) => typeof value === 'function' || (typeof value === 'object' && value !== null);
+/** A component echarts made for itself (`isComponentIdInternal`): a merge by position never lands on it. */
+const isInternal = (series) => {
+    const id = own(series, 'id');
+    return (typeof id === 'string' || typeof id === 'number') && String(id).startsWith('\0_ec_\0');
+};
+/**
+ * For each item of the update, the held series it merges into, as echarts maps by position
+ * (`mappingByIndex`, `SOURCES` in sources.ts): each item takes the first series no item took
+ * yet that is not internal; an item that is not an object takes none; past the held series
+ * an item is new (`undefined`). K3.
+ */
+function slots(items, held) {
+    const taken = new Set();
+    return items.map((item) => {
+        if (!isObjectLike(item))
+            return undefined;
+        const free = held.findIndex((series, index) => !taken.has(index) && !isInternal(series));
+        if (free === -1)
+            return undefined;
+        taken.add(free);
+        return free;
+    });
+}
+/** The option as the merge applies it: each untyped item with the type of the series it merges into. */
+function merged(option, types) {
+    const series = own(option, 'series');
+    if (!Array.isArray(series) || !isRecord(option))
+        return option;
+    const typed = series.map((item, index) => {
+        const type = types[index];
+        if (!untyped(item) || typeof type !== 'string' || !isRecord(item))
+            return item;
+        return Object.defineProperties({}, { ...Object.getOwnPropertyDescriptors(item), type: { value: type, enumerable: true } });
+    });
+    return Object.defineProperties({}, { ...Object.getOwnPropertyDescriptors(option), series: { value: typed, enumerable: true } });
+}
+/** A merge by position: the update typed as it merges, and the untyped items that land on no series. */
+function mergeByIndex(option, series, held) {
+    const existing = heldSeries(held);
+    const landing = slots(series.map(({ item }) => item), existing);
+    const types = landing.map((slot) => (slot === undefined ? undefined : own(existing[slot], 'type')));
+    const missing = series
+        .filter(({ item }, index) => untyped(item) && landing[index] === undefined)
+        .map(({ path }) => dropped(path));
+    return { view: merged(option, types), missing };
+}
+/** The guard's options with the registry context of `guard.echarts`, read now. */
+function optionsOf({ options, echarts }) {
+    if (echarts === undefined)
+        return options;
+    const registries = { ...registriesOf(echarts), ...options?.registries };
+    return Object.keys(registries).length === 0 ? options : { ...options, registries };
+}
+function warn(checked) {
+    if (checked.valid)
+        return;
+    const listed = checked.diagnostics
+        .filter(({ severity }) => severity === 'error')
+        .map(({ path, message }) => `${path} (${message})`)
+        .join('; ');
+    console.warn(`ChartGuard: ${checked.library} option invalid: ${listed}`);
+}
+/**
+ * The option as the call applies it to a chart holding `held` (what `getOption()` returned, read
+ * once: it clones the whole option, K5), validated. A disposed chart (`null`) sets nothing: the
+ * option is checked as a partial one, with no claim about what the chart would drop (K4).
+ */
+function inspect(held, option, settings, guard) {
+    const validator = guard.validator ?? validate;
+    const options = optionsOf(guard);
+    const fresh = held !== null && isFresh(held, settings);
+    const series = itemsAt(own(option, 'series'), '$.series');
+    const based = itemsAt(own(own(option, 'baseOption'), 'series'), '$.baseOption.series');
+    let view = option;
+    let missing = [];
+    if (fresh)
+        missing = [...series, ...based].filter(({ item }) => untyped(item)).map(({ path }) => dropped(path));
+    else if (held !== null && byIndex(series))
+        ({ view, missing } = mergeByIndex(option, series, held));
+    // A merge update is partial by design: what it leaves out, the chart already has.
+    const checked = validator(view, fresh ? options : { ...options, incomplete: true });
+    return {
+        checked: {
+            ...checked,
+            ...result(checked.library, checked.schemaVersion, checked.coverage, [...checked.diagnostics, ...missing])
+        },
+        fresh
+    };
+}
+/** The option as `chart.setOption(option, settings)` would apply it, validated; nothing is set. */
+export function checkOption(chart, option, settings, guard = {}) {
+    return inspect(chart.getOption(), option, settings, guard).checked;
+}
+/**
+ * The safe `setOption` path (CG-04-03): the option is validated as the call applies it to this chart,
+ * reported, then set with its settings unless `block` and invalid. Nothing is patched.
+ */
+export function setOption(chart, option, settings, guard = {}) {
+    const { checked, fresh } = inspect(chart.getOption(), option, settings, guard);
+    if (guard.onResult === undefined)
+        warn(checked);
+    else
+        guard.onResult(checked, { fresh });
+    if (guard.block !== true || checked.valid)
+        chart.setOption(option, settings);
+    return checked;
+}
+//# sourceMappingURL=set-option.js.map

package/dist/set-option.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"set-option.js","sourceRoot":"","sources":["../src/set-option.ts"],"names":[],"mappings":"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"}

package/dist/sources.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The ECharts behaviour the wrapper rests on, each a pointer into the pinned echarts checked by a test
+ * (E37): a series whose type has no registered model is dropped ("Unknown series", `dropped` in
+ * set-option.ts); a merge maps items to the held series by position (`mappingByIndex`): an item that is
+ * not an object is set to `null` and takes none, and an internal series is skipped (`slots`); a fresh
+ * option (`replaceAll`) or a `replaceMerge` of `series` merges no item into a held series (`isFresh`).
+ */
+export declare const SOURCES: readonly ["echarts@6.1.0 lib/model/Global.js:303 error(\"Unknown series \" + subType);", "echarts@6.1.0 lib/model/Global.js:261 !oldCmptList ? 'replaceAll' : replaceMergeMainTypeMap && replaceMergeMainTypeMap.get(mainType) ? 'replaceMerge' : 'normalMerge';", "echarts@6.1.0 lib/util/model.js:156 if (!isObject(cmptOption)) {", "echarts@6.1.0 lib/util/model.js:270 // In mode \"replaceMerge\", here no not-mapped-non-internal-existing.", "echarts@6.1.0 lib/util/model.js:252 function mappingByIndex(result, newCmptOptions, brandNew) {", "echarts@6.1.0 lib/util/model.js:269 ) && (resultItem.newOption || isComponentIdInternal(resultItem.existing) ||", "echarts@6.1.0 lib/util/model.js:402 return cmptOption && cmptOption.id != null && makeComparableKey(cmptOption.id).indexOf(INTERNAL_COMPONENT_ID_PREFIX) === 0;"];
+//# sourceMappingURL=sources.d.ts.map

package/dist/sources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sources.d.ts","sourceRoot":"","sources":["../src/sources.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,+yBAQV,CAAC"}

package/dist/sources.js

@@ -0,0 +1,17 @@
+/**
+ * The ECharts behaviour the wrapper rests on, each a pointer into the pinned echarts checked by a test
+ * (E37): a series whose type has no registered model is dropped ("Unknown series", `dropped` in
+ * set-option.ts); a merge maps items to the held series by position (`mappingByIndex`): an item that is
+ * not an object is set to `null` and takes none, and an internal series is skipped (`slots`); a fresh
+ * option (`replaceAll`) or a `replaceMerge` of `series` merges no item into a held series (`isFresh`).
+ */
+export const SOURCES = [
+    'echarts@6.1.0 lib/model/Global.js:303 error("Unknown series " + subType);',
+    "echarts@6.1.0 lib/model/Global.js:261 !oldCmptList ? 'replaceAll' : replaceMergeMainTypeMap && replaceMergeMainTypeMap.get(mainType) ? 'replaceMerge' : 'normalMerge';",
+    'echarts@6.1.0 lib/util/model.js:156 if (!isObject(cmptOption)) {',
+    'echarts@6.1.0 lib/util/model.js:270 // In mode "replaceMerge", here no not-mapped-non-internal-existing.',
+    'echarts@6.1.0 lib/util/model.js:252 function mappingByIndex(result, newCmptOptions, brandNew) {',
+    'echarts@6.1.0 lib/util/model.js:269 ) && (resultItem.newOption || isComponentIdInternal(resultItem.existing) ||',
+    'echarts@6.1.0 lib/util/model.js:402 return cmptOption && cmptOption.id != null && makeComparableKey(cmptOption.id).indexOf(INTERNAL_COMPONENT_ID_PREFIX) === 0;'
+];
+//# sourceMappingURL=sources.js.map

package/dist/sources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sources.js","sourceRoot":"","sources":["../src/sources.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG;IACtB,2EAA2E;IAC3E,wKAAwK;IACxK,kEAAkE;IAClE,0GAA0G;IAC1G,iGAAiG;IACjG,iHAAiH;IACjH,iKAAiK;CACxJ,CAAC"}

package/package.json

@@ -1,6 +1,48 @@
 {
-  "name": "@chartguard/runtime-echarts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@chartguard/runtime-echarts",
+	"version": "0.1.1",
+	"description": "Optional opt-in runtime validation wrapper for echarts",
+	"type": "module",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/dovicsin/chartguard.git",
+		"directory": "packages/integrations/echarts-runtime"
+	},
+	"sideEffects": false,
+	"engines": {
+		"node": ">=22.12.0"
+	},
+	"files": [
+		"dist/",
+		"README.md"
+	],
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		}
+	},
+	"scripts": {
+		"build": "tsc -b",
+		"test": "node --test tests/*.test.mjs"
+	},
+	"dependencies": {
+		"@chartguard/core": "0.1.1",
+		"@chartguard/config-echarts": "0.1.1"
+	},
+	"peerDependencies": {
+		"echarts": "^6.1.0"
+	},
+	"peerDependenciesMeta": {
+		"echarts": {
+			"optional": false
+		}
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}