@ggts-sh/svelte 0.43.0

package/dist/coord/CoordTransform.svelte.d.ts

@@ -0,0 +1,9 @@
+/**
+   * <CoordTransform> — declaration-only post-stat coordinate transform for
+   * <GGPlot> (#659 slice 5). Accepts the same options as `coordTransform(…)`.
+   * Emits NO markup.
+   */
+import { type CoordTransformOptions } from "@ggts-sh/spec";
+declare const CoordTransform: import("svelte").Component<CoordTransformOptions, {}, "">;
+type CoordTransform = ReturnType<typeof CoordTransform>;
+export default CoordTransform;

package/dist/data/index.d.ts

@@ -0,0 +1 @@
+export * from "@ggts-sh/core/data";

package/dist/data/index.js

@@ -0,0 +1,2 @@
+// Compatibility subpath; the teaching data has one framework-neutral home.
+export * from "@ggts-sh/core/data";

package/dist/diagnostics/composition.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Plot-level composition advisories (ADR 0013 / #659).
+ *
+ * Sibling union to InteractionDiagnostic and DeprecationDiagnostic, delivered
+ * through the existing `ondiagnostic` channel as PlotDiagnostic.
+ *
+ * Three families:
+ * - keyed MERGE, scales (`kind: "scale"`): duplicate aesthetic channels after
+ *   shallow per-key merge → `DUPLICATE_SCALE_CHANNEL`
+ * - keyed MERGE, everything else (`kind: "labs" | "guides" | "legend"`, #659
+ *   slice 6): duplicate keys in the same shallow merge → `DUPLICATE_MERGE_KEY`
+ * - REPLACE (`kind: "coord" | "facet" | "theme"`): two children of the same
+ *   kind → one silently wins → `DUPLICATE_PLOT_LAYER`
+ *
+ * The scale family keeps its own code rather than folding into
+ * DUPLICATE_MERGE_KEY: it shipped in 0.11.0, its `channel` field and its
+ * spelling-alias suggestion are scale-specific, and renaming a live advisory
+ * code would break consumer `switch`es for no behavioural gain.
+ *
+ * Kind sets and doc anchors come from GRAMMAR_FAMILIES (#785).
+ */
+import { type MergeByKeyKind, type ReplaceKind } from "../layers/grammar-families.js";
+import type { PlotLayerLike } from "../layers/types.js";
+export type CompositionDiagnosticCode = "DUPLICATE_SCALE_CHANNEL" | "DUPLICATE_MERGE_KEY" | "DUPLICATE_PLOT_LAYER";
+/**
+ * `suggestions` and `docUrl` are NOT optional: both sibling members of
+ * PlotDiagnostic (InteractionDiagnostic, DeprecationDiagnostic) carry them, so
+ * a consumer rendering `d.docUrl` / `d.suggestions` over the union must not
+ * break on this variant. An advisory whose whole job is "your chart is
+ * silently wrong" is also the last place to omit the fix link.
+ */
+export interface DuplicateScaleChannelDiagnostic {
+    readonly severity: "advisory";
+    readonly code: "DUPLICATE_SCALE_CHANNEL";
+    readonly message: string;
+    readonly channel: string;
+    readonly kind: "scale";
+    readonly suggestions: ReadonlyArray<string>;
+    readonly docUrl: string;
+}
+/** Keyed-MERGE families other than scales (#659 slice 6 / #785). */
+export type DuplicateMergeKeyKind = MergeByKeyKind;
+/**
+ * Two children of one keyed-MERGE family wrote the same key. Unlike the
+ * REPLACE families nothing is wholesale lost — only that one key, where the
+ * later child's value silently overwrites the earlier one's.
+ */
+export interface DuplicateMergeKeyDiagnostic {
+    readonly severity: "advisory";
+    readonly code: "DUPLICATE_MERGE_KEY";
+    readonly message: string;
+    readonly kind: DuplicateMergeKeyKind;
+    /** The colliding key: a labs/legend option name, or a guides channel. */
+    readonly key: string;
+    readonly suggestions: ReadonlyArray<string>;
+    readonly docUrl: string;
+}
+export type DuplicatePlotLayerKind = ReplaceKind;
+export interface DuplicatePlotLayerDiagnostic {
+    readonly severity: "advisory";
+    readonly code: "DUPLICATE_PLOT_LAYER";
+    readonly message: string;
+    readonly kind: DuplicatePlotLayerKind;
+    readonly suggestions: ReadonlyArray<string>;
+    readonly docUrl: string;
+}
+export type CompositionDiagnostic = DuplicateScaleChannelDiagnostic | DuplicateMergeKeyDiagnostic | DuplicatePlotLayerDiagnostic;
+export declare function isCompositionDiagnostic(d: {
+    readonly code: string;
+}): d is CompositionDiagnostic;
+/** Narrow to the scale variant so `.channel` consumers stay type-safe. */
+export declare function isDuplicateScaleChannelDiagnostic(d: CompositionDiagnostic | {
+    readonly code: string;
+}): d is DuplicateScaleChannelDiagnostic;
+/** Narrow to the non-scale keyed-MERGE variant so `.key` consumers stay safe. */
+export declare function isDuplicateMergeKeyDiagnostic(d: CompositionDiagnostic | {
+    readonly code: string;
+}): d is DuplicateMergeKeyDiagnostic;
+/** Narrow to the REPLACE-family plot-layer variant. */
+export declare function isDuplicatePlotLayerDiagnostic(d: CompositionDiagnostic | {
+    readonly code: string;
+}): d is DuplicatePlotLayerDiagnostic;
+/**
+ * Frozen catalog entry for composition codes. Per-emission fields are filled
+ * by {@link duplicateScaleChannelDiagnostic} / {@link duplicatePlotLayerDiagnostic}.
+ */
+export declare const COMPOSITION_DIAGNOSTIC_CATALOG: Readonly<Record<CompositionDiagnosticCode, Pick<CompositionDiagnostic, "severity" | "code"> & {
+    readonly messageTemplate: (subject: string) => string;
+}>>;
+/** Build a fully-populated duplicate-channel advisory. */
+export declare function duplicateScaleChannelDiagnostic(channel: string): DuplicateScaleChannelDiagnostic;
+/** Build a fully-populated duplicate merge-key advisory (labs/guides/legend). */
+export declare function duplicateMergeKeyDiagnostic(kind: DuplicateMergeKeyKind, key: string): DuplicateMergeKeyDiagnostic;
+/** Build a fully-populated duplicate REPLACE-family plot-layer advisory. */
+export declare function duplicatePlotLayerDiagnostic(kind: DuplicatePlotLayerKind): DuplicatePlotLayerDiagnostic;
+/**
+ * Scan plot layers for composition collisions (duplicate scale channels,
+ * keyed-MERGE key collisions, REPLACE multi-children). Pure — safe to call
+ * from a `$derived` that only re-reads `registry.layers`.
+ *
+ * Emission order: scale channels, then MERGE_KEY_EMIT_ORDER, then
+ * REPLACE_EMIT_ORDER. Mark layers are ignored.
+ */
+export declare function collectCompositionDiagnostics(layers: readonly PlotLayerLike[]): CompositionDiagnostic[];
+/**
+ * Once-per-instance advisory dedup key for composition diagnostics.
+ * Shape matches the assembly deliveredAdvisories Set:
+ * - scale: `${code}:${channel}`
+ * - merge-key: `${code}:${kind}:${key}`
+ * - replace: `${code}:${kind}`
+ */
+export declare function compositionAdvisoryDedupKey(diagnostic: CompositionDiagnostic): string;

package/dist/diagnostics/composition.js

@@ -0,0 +1,203 @@
+/**
+ * Plot-level composition advisories (ADR 0013 / #659).
+ *
+ * Sibling union to InteractionDiagnostic and DeprecationDiagnostic, delivered
+ * through the existing `ondiagnostic` channel as PlotDiagnostic.
+ *
+ * Three families:
+ * - keyed MERGE, scales (`kind: "scale"`): duplicate aesthetic channels after
+ *   shallow per-key merge → `DUPLICATE_SCALE_CHANNEL`
+ * - keyed MERGE, everything else (`kind: "labs" | "guides" | "legend"`, #659
+ *   slice 6): duplicate keys in the same shallow merge → `DUPLICATE_MERGE_KEY`
+ * - REPLACE (`kind: "coord" | "facet" | "theme"`): two children of the same
+ *   kind → one silently wins → `DUPLICATE_PLOT_LAYER`
+ *
+ * The scale family keeps its own code rather than folding into
+ * DUPLICATE_MERGE_KEY: it shipped in 0.11.0, its `channel` field and its
+ * spelling-alias suggestion are scale-specific, and renaming a live advisory
+ * code would break consumer `switch`es for no behavioural gain.
+ *
+ * Kind sets and doc anchors come from GRAMMAR_FAMILIES (#785).
+ */
+import { GRAMMAR_FAMILIES, MERGE_KEY_EMIT_ORDER, REPLACE_EMIT_ORDER, grammarDocUrl, } from "../layers/grammar-families.js";
+export function isCompositionDiagnostic(d) {
+    return (d.code === "DUPLICATE_SCALE_CHANNEL" ||
+        d.code === "DUPLICATE_MERGE_KEY" ||
+        d.code === "DUPLICATE_PLOT_LAYER");
+}
+/** Narrow to the scale variant so `.channel` consumers stay type-safe. */
+export function isDuplicateScaleChannelDiagnostic(d) {
+    return d.code === "DUPLICATE_SCALE_CHANNEL";
+}
+/** Narrow to the non-scale keyed-MERGE variant so `.key` consumers stay safe. */
+export function isDuplicateMergeKeyDiagnostic(d) {
+    return d.code === "DUPLICATE_MERGE_KEY";
+}
+/** Narrow to the REPLACE-family plot-layer variant. */
+export function isDuplicatePlotLayerDiagnostic(d) {
+    return d.code === "DUPLICATE_PLOT_LAYER";
+}
+function mergeKeyNoun(kind) {
+    return GRAMMAR_FAMILIES[kind].mergeKeyNoun ?? "key";
+}
+function mergeKeyChild(kind) {
+    return GRAMMAR_FAMILIES[kind].mergeKeyChild ?? `<${kind}>`;
+}
+/**
+ * Frozen catalog entry for composition codes. Per-emission fields are filled
+ * by {@link duplicateScaleChannelDiagnostic} / {@link duplicatePlotLayerDiagnostic}.
+ */
+export const COMPOSITION_DIAGNOSTIC_CATALOG = Object.freeze({
+    DUPLICATE_SCALE_CHANNEL: {
+        severity: "advisory",
+        code: "DUPLICATE_SCALE_CHANNEL",
+        messageTemplate: (channel) => `Multiple scale children configure channel "${channel}"; later children overwrite earlier ones.`,
+    },
+    DUPLICATE_MERGE_KEY: {
+        severity: "advisory",
+        code: "DUPLICATE_MERGE_KEY",
+        messageTemplate: (key) => `Multiple children set "${key}"; later children overwrite earlier ones.`,
+    },
+    DUPLICATE_PLOT_LAYER: {
+        severity: "advisory",
+        code: "DUPLICATE_PLOT_LAYER",
+        messageTemplate: (kind) => `Multiple ${kind} children are registered; the last one replaces earlier ones.`,
+    },
+});
+/** Build a fully-populated duplicate-channel advisory. */
+export function duplicateScaleChannelDiagnostic(channel) {
+    const entry = COMPOSITION_DIAGNOSTIC_CATALOG.DUPLICATE_SCALE_CHANNEL;
+    return {
+        severity: entry.severity,
+        code: "DUPLICATE_SCALE_CHANNEL",
+        message: entry.messageTemplate(channel),
+        channel,
+        kind: "scale",
+        suggestions: [
+            `Keep one scale child per channel — remove all but the intended "${channel}" scale`,
+            `British and American spellings write the same channel: <ScaleColorDiscrete/> and <ScaleColourContinuous/> both configure "color"`,
+        ],
+        docUrl: grammarDocUrl("scale"),
+    };
+}
+/** Build a fully-populated duplicate merge-key advisory (labs/guides/legend). */
+export function duplicateMergeKeyDiagnostic(kind, key) {
+    const entry = COMPOSITION_DIAGNOSTIC_CATALOG.DUPLICATE_MERGE_KEY;
+    const noun = mergeKeyNoun(kind);
+    const child = mergeKeyChild(kind);
+    return {
+        severity: entry.severity,
+        code: "DUPLICATE_MERGE_KEY",
+        message: entry.messageTemplate(key),
+        kind,
+        key,
+        suggestions: [
+            `Set the ${noun} "${key}" on exactly one ${child} child`,
+            `${kind} is a MERGE family: siblings that touch different ${noun}s all survive — only "${key}" is overwritten`,
+        ],
+        docUrl: grammarDocUrl(kind),
+    };
+}
+/** Build a fully-populated duplicate REPLACE-family plot-layer advisory. */
+export function duplicatePlotLayerDiagnostic(kind) {
+    const entry = COMPOSITION_DIAGNOSTIC_CATALOG.DUPLICATE_PLOT_LAYER;
+    const shell = kind === "theme" ? "Theme" : kind === "coord" ? "Coord" : kind === "facet" ? "Facet" : kind;
+    return {
+        severity: entry.severity,
+        code: "DUPLICATE_PLOT_LAYER",
+        message: entry.messageTemplate(kind),
+        kind,
+        suggestions: [
+            `Keep one <${shell}*> child — remove earlier ${kind} children so the intended one is the only registration`,
+            `${kind} is a REPLACE family: the last child fully replaces earlier ones (and any ${kind} prop)`,
+        ],
+        docUrl: grammarDocUrl(kind),
+    };
+}
+function isMergeKeyLayer(layer) {
+    return MERGE_KEY_EMIT_ORDER.includes(layer.kind);
+}
+function isReplaceLayer(layer) {
+    return REPLACE_EMIT_ORDER.includes(layer.kind);
+}
+/**
+ * Scan plot layers for composition collisions (duplicate scale channels,
+ * keyed-MERGE key collisions, REPLACE multi-children). Pure — safe to call
+ * from a `$derived` that only re-reads `registry.layers`.
+ *
+ * Emission order: scale channels, then MERGE_KEY_EMIT_ORDER, then
+ * REPLACE_EMIT_ORDER. Mark layers are ignored.
+ */
+export function collectCompositionDiagnostics(layers) {
+    const list = [];
+    const seenChannels = new Set();
+    const duplicateChannels = new Set();
+    // Kind membership and emit order come from GRAMMAR_FAMILIES (#785).
+    // Scales keep their own advisory code (0.11.0 surface); labs/guides/legend
+    // share DUPLICATE_MERGE_KEY.
+    const mergeSeen = Object.fromEntries(MERGE_KEY_EMIT_ORDER.map((k) => [k, new Set()]));
+    const mergeDuplicates = Object.fromEntries(MERGE_KEY_EMIT_ORDER.map((k) => [k, new Set()]));
+    const replaceCounts = Object.fromEntries(REPLACE_EMIT_ORDER.map((k) => [k, 0]));
+    for (const layer of layers) {
+        if (layer.kind === "scale") {
+            for (const channel of Object.keys(layer.value)) {
+                if (seenChannels.has(channel)) {
+                    duplicateChannels.add(channel);
+                }
+                else {
+                    seenChannels.add(channel);
+                }
+            }
+            continue;
+        }
+        if (isMergeKeyLayer(layer)) {
+            const kind = layer.kind;
+            for (const key of Object.keys(layer.value)) {
+                if (mergeSeen[kind].has(key)) {
+                    mergeDuplicates[kind].add(key);
+                }
+                else {
+                    mergeSeen[kind].add(key);
+                }
+            }
+            continue;
+        }
+        if (isReplaceLayer(layer)) {
+            replaceCounts[layer.kind] += 1;
+        }
+    }
+    for (const channel of duplicateChannels) {
+        list.push(duplicateScaleChannelDiagnostic(channel));
+    }
+    for (const kind of MERGE_KEY_EMIT_ORDER) {
+        for (const key of mergeDuplicates[kind]) {
+            list.push(duplicateMergeKeyDiagnostic(kind, key));
+        }
+    }
+    for (const kind of REPLACE_EMIT_ORDER) {
+        if (replaceCounts[kind] > 1) {
+            list.push(duplicatePlotLayerDiagnostic(kind));
+        }
+    }
+    return list;
+}
+/**
+ * Once-per-instance advisory dedup key for composition diagnostics.
+ * Shape matches the assembly deliveredAdvisories Set:
+ * - scale: `${code}:${channel}`
+ * - merge-key: `${code}:${kind}:${key}`
+ * - replace: `${code}:${kind}`
+ */
+export function compositionAdvisoryDedupKey(diagnostic) {
+    if (isDuplicateScaleChannelDiagnostic(diagnostic)) {
+        return `${diagnostic.code}:${diagnostic.channel}`;
+    }
+    if (isDuplicateMergeKeyDiagnostic(diagnostic)) {
+        return `${diagnostic.code}:${diagnostic.kind}:${diagnostic.key}`;
+    }
+    if (isDuplicatePlotLayerDiagnostic(diagnostic)) {
+        return `${diagnostic.code}:${diagnostic.kind}`;
+    }
+    // Exhaustiveness: CompositionDiagnostic has only the three variants above.
+    return ((x) => x)(diagnostic);
+}

package/dist/diagnostics/deprecation.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Plot-level deprecation advisories (ADR 0013).
+ *
+ * Sibling union to InteractionDiagnostic, delivered through the existing
+ * `ondiagnostic` channel as PlotDiagnostic. One code (`DEPRECATED_PLOT_PROP`)
+ * covers every deprecated grammar prop — `prop` carries the name.
+ *
+ * Runtime emission left in 0.13.0 (#704) when the seven grammar props were
+ * removed. Types + catalog + builder stay for union typing, upgrade-guide
+ * anchors, and codemod consumers. Discriminate with
+ * `d.code === "DEPRECATED_PLOT_PROP"` (no type-guard export).
+ *
+ * Deliberately NOT merged into INTERACTION_DIAGNOSTIC_CATALOG / the
+ * interaction-reference guide page: a deprecated grammar prop is not an
+ * interaction concern, and migration guidance belongs on /guide/upgrading
+ * (docUrl below). Omitting it from the interaction catalog is a decision,
+ * not an oversight.
+ */
+import type { InteractionDiagnostic } from "../interaction/interaction-diagnostics.js";
+import type { CompositionDiagnostic } from "./composition.js";
+export type DeprecationDiagnosticCode = "DEPRECATED_PLOT_PROP";
+export interface DeprecationDiagnostic {
+    readonly severity: "advisory";
+    readonly code: DeprecationDiagnosticCode;
+    readonly message: string;
+    readonly prop: string;
+    readonly since: string;
+    readonly removeIn: string;
+    readonly suggestions: ReadonlyArray<string>;
+    readonly docUrl: string;
+}
+/**
+ * Union of every diagnostic the plot may deliver through `ondiagnostic`.
+ * Interaction capability/key/lineage checks, grammar-prop deprecations, and
+ * composition collisions (duplicate scale channels). Additive: handlers
+ * annotated `PlotDiagnostic` (the 0.11 form) remain valid. Exhaustive
+ * `switch` on `.code` needs arms for `DUPLICATE_SCALE_CHANNEL` and
+ * `DUPLICATE_PLOT_LAYER`.
+ */
+export type PlotDiagnostic = InteractionDiagnostic | DeprecationDiagnostic | CompositionDiagnostic;
+/**
+ * Frozen catalog entry for the single deprecation code. Message / prop /
+ * since / removeIn / docUrl are filled per emission by
+ * {@link deprecatedPropDiagnostic}.
+ */
+export declare const DEPRECATION_DIAGNOSTIC_CATALOG: Readonly<Record<DeprecationDiagnosticCode, Pick<DeprecationDiagnostic, "severity" | "code"> & {
+    readonly messageTemplate: (prop: string, since: string, removeIn: string) => string;
+}>>;
+export type DeprecatedPropDiagnosticInput = {
+    readonly prop: string;
+    readonly since: string;
+    readonly removeIn: string;
+    readonly suggestions: ReadonlyArray<string>;
+    /** Heading anchor on /guide/upgrading (without the leading `#`). */
+    readonly anchor: string;
+};
+/** Build a fully-populated deprecation advisory for one prop. */
+export declare function deprecatedPropDiagnostic(input: DeprecatedPropDiagnosticInput): DeprecationDiagnostic;

package/dist/diagnostics/deprecation.js

@@ -0,0 +1,27 @@
+const GUIDE_UPGRADING = "https://ggts.sh/guide/upgrading";
+/**
+ * Frozen catalog entry for the single deprecation code. Message / prop /
+ * since / removeIn / docUrl are filled per emission by
+ * {@link deprecatedPropDiagnostic}.
+ */
+export const DEPRECATION_DIAGNOSTIC_CATALOG = Object.freeze({
+    DEPRECATED_PLOT_PROP: {
+        severity: "advisory",
+        code: "DEPRECATED_PLOT_PROP",
+        messageTemplate: (prop, since, removeIn) => `GGPlot prop "${prop}" is deprecated since ${since} and will be removed in ${removeIn}. Prefer the matching declaration-only child layer.`,
+    },
+});
+/** Build a fully-populated deprecation advisory for one prop. */
+export function deprecatedPropDiagnostic(input) {
+    const entry = DEPRECATION_DIAGNOSTIC_CATALOG.DEPRECATED_PLOT_PROP;
+    return {
+        severity: entry.severity,
+        code: entry.code,
+        message: entry.messageTemplate(input.prop, input.since, input.removeIn),
+        prop: input.prop,
+        since: input.since,
+        removeIn: input.removeIn,
+        suggestions: input.suggestions,
+        docUrl: `${GUIDE_UPGRADING}#${input.anchor}`,
+    };
+}

package/dist/diagnostics/plot-engine-diagnostics.svelte.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Plot-engine diagnostic orchestration — config delivery plus the once-only
+ * advisory effects (wiring, multi-Inspect, dropped identity, deprecations,
+ * composition, inspect-geom, high-cardinality) and the chrome re-delivery
+ * effects.
+ *
+ * Extraction contract (S5): inputs are lazy getters / stable service refs over
+ * the engine's live deriveds — never snapshots. `deliverDiagnostic` is one
+ * stable closure per engine (shared dedup Set included), so late
+ * registrations (chrome re-delivery, semantic-keys) deliver through the same
+ * sink.
+ *
+ * Call `createPlotEngineDiagnostics` synchronously while `createPlotEngine`
+ * runs during component init: every `$effect` here must land in the component
+ * effect tree. Runtime-gated advisories (inspect-geom, high-cardinality) and
+ * the chrome re-delivery effects register later via the register* functions —
+ * still during init, at the engine's original registration positions.
+ */
+import type { PortableSpec } from "@ggts-sh/spec";
+import { type PlotDiagnostic } from "./deprecation.js";
+import type { LayerRegistry } from "../geoms/registry.svelte.js";
+import { type ResolvedInteractionConfig } from "../interaction/interaction.js";
+import type { CapabilityResolution } from "../interaction/capability-resolution.svelte.js";
+import { type EnginePlotProps } from "../plot-props.js";
+import type { PlotChromeState } from "../chrome/chrome-state.svelte.js";
+import type { PlotRuntime } from "../runtime/runtime.svelte.js";
+/**
+ * Inputs: live props proxy + registry (reactive reads) and the engine's
+ * capability-resolution / interaction-config accessors.
+ */
+export type PlotEngineDiagnosticsInput = {
+    readonly props: EnginePlotProps;
+    readonly registry: LayerRegistry;
+    readonly interactionConfig: () => ResolvedInteractionConfig;
+    readonly capabilityResolution: CapabilityResolution;
+};
+export declare function createPlotEngineDiagnostics(input: PlotEngineDiagnosticsInput): {
+    deliverDiagnostic: (diagnostic: PlotDiagnostic) => void;
+    registerChromeDiagnostics: (chrome: PlotChromeState) => void;
+    registerInspectDiagnostics: (opts: {
+        assembled: () => PortableSpec | null;
+        model: () => PlotRuntime["model"];
+    }) => void;
+};

package/dist/diagnostics/plot-engine-diagnostics.svelte.js

@@ -0,0 +1,193 @@
+import { collectCompositionDiagnostics, compositionAdvisoryDedupKey, } from "./composition.js";
+import { deprecatedPropDiagnostic } from "./deprecation.js";
+import { discreteColorFillDomainSizes, inspectAxisOnBarColDiagnostics, inspectAxisOnDistributionDiagnostics, inspectHighCardinalityDiagnostics, layerGeomsFromSpecLayers, } from "../interaction/interaction.js";
+import { droppedInspectIdentityDiagnostics, duplicateInspectCapabilityDiagnostics, } from "../interaction/resolve-inspect-capability.js";
+import { collectWiringDiagnostics } from "../interaction/wiring-advisories.js";
+import { readLegacyPlotKey, readLegacyPlotLegendFilter, readLegacyPlotLegendFocus, } from "../plot-props.js";
+export function createPlotEngineDiagnostics(input) {
+    const capabilityResolution = input.capabilityResolution;
+    function deliverDiagnostic(diagnostic) {
+        const ondiagnostic = input.props.ondiagnostic;
+        ondiagnostic?.(diagnostic);
+        const nodeEnvironment = globalThis.process
+            ?.env?.NODE_ENV;
+        if (nodeEnvironment !== "production" && ondiagnostic === undefined)
+            console.warn(`[ggts:${diagnostic.code}] ${diagnostic.message}`);
+    }
+    $effect(() => {
+        for (const diagnostic of input.interactionConfig().diagnostics)
+            deliverDiagnostic(diagnostic);
+    });
+    // Wiring advisories (ADR 0013 audit): prop combinations that silently do
+    // nothing. Unlike config diagnostics (re-delivered per recompute), these
+    // fire once per prop per plot instance — a later capability toggle must
+    // not re-advise. Pure collect lives in wiring-advisories.ts; snapshot is
+    // taken inside this derived so late-bound handlers still recompute.
+    // capabilities.inspect is resolved (prop + <Inspect> children), not raw prop.
+    const wiringDiagnostics = $derived.by(() => {
+        const capabilities = capabilityResolution.caps();
+        // legendFocus "requested" is the GuideLegend/child (or deprecated prop)
+        // opt-in — not the post-key-check resolved config — so keyless focus does
+        // not double-advise HANDLER_WITHOUT_CAPABILITY + LEGEND_REQUIRES_KEY.
+        return collectWiringDiagnostics({
+            interactionScope: input.props.interactionScope,
+            interaction: input.props.interaction,
+            handlers: {
+                oninspect: input.props.oninspect,
+                onselect: input.props.onselect,
+                onzoom: input.props.onzoom,
+                onlegendfocus: input.props.onlegendfocus,
+                onlegendfilter: input.props.onlegendfilter,
+            },
+            capabilities: {
+                inspect: capabilities.inspect,
+                select: capabilities.select,
+                zoom: capabilities.zoom,
+                legendFocus: capabilityResolution.legendFocus().requested,
+                // legendFilter "requested" is GuideLegend/child (or deprecated prop)
+                // opt-in — not resolveCapabilities(plot prop alone).
+                legendFilter: capabilityResolution.legendFilter().requested,
+            },
+        });
+    });
+    // Shared once-per-dedup-key Set for wiring + multi-Inspect + deprecations +
+    // composition + inspect-geom. Each deliverAdvisoriesOnce call registers ONE
+    // $effect; call order below is the registration (and first-flush delivery)
+    // order. Re-delivering effects (config diagnostics above, chrome
+    // re-delivery via registerChromeDiagnostics) stay outside this helper by
+    // design.
+    const deliveredAdvisories = new Set();
+    function deliverAdvisoriesOnce(get, dedupKeyOf = (diagnostic) => `${diagnostic.code}:${diagnostic.prop}`) {
+        $effect(() => {
+            for (const diagnostic of get()) {
+                const dedupKey = dedupKeyOf(diagnostic);
+                if (deliveredAdvisories.has(dedupKey))
+                    continue;
+                deliveredAdvisories.add(dedupKey);
+                deliverDiagnostic(diagnostic);
+            }
+        });
+    }
+    deliverAdvisoriesOnce(() => wiringDiagnostics);
+    // Multiple <Inspect> children: last wins; advisory once per mount.
+    const multiInspectDiagnostics = $derived.by(() => duplicateInspectCapabilityDiagnostics(capabilityResolution.inspect().multiChild));
+    deliverAdvisoriesOnce(() => multiInspectDiagnostics);
+    // <Inspect> replaced an inspect prop that named `identity`: rows silently
+    // fell back to id column / row index before #1305's follow-up.
+    const droppedIdentityDiagnostics = $derived.by(() => droppedInspectIdentityDiagnostics(capabilityResolution.inspect().droppedPropIdentity));
+    deliverAdvisoriesOnce(() => droppedIdentityDiagnostics);
+    // Deprecated plot-level key → Inspect / Select / controller identity.
+    const deprecatedKeyDiagnostics = $derived.by(() => {
+        const plotProp = readLegacyPlotKey(input.props);
+        if (plotProp === undefined)
+            return [];
+        return [
+            deprecatedPropDiagnostic({
+                prop: "key",
+                since: "0.21.0",
+                removeIn: "0.22.0",
+                suggestions: [
+                    'Use <Inspect identity="year" /> (or inspect={{ identity: "year" }})',
+                    'Use select={{ type: "point", identity: "year" }} when selection owns the key',
+                    'Use createPlotInteraction({ identity: "year" }) for linked controllers',
+                ],
+                anchor: "row-identity-on-interaction",
+            }),
+        ];
+    });
+    deliverAdvisoriesOnce(() => deprecatedKeyDiagnostics);
+    // Deprecated plot-level legendFocus → GuideLegend.focus (one minor window).
+    const deprecatedLegendFocusDiagnostics = $derived.by(() => {
+        const plotProp = readLegacyPlotLegendFocus(input.props);
+        if (plotProp === undefined || plotProp === false)
+            return [];
+        return [
+            deprecatedPropDiagnostic({
+                prop: "legendFocus",
+                since: "0.19.0",
+                removeIn: "0.20.0",
+                suggestions: [
+                    'Use <GuideLegend channel="color" focus /> (or the aesthetic that owns the discrete legend)',
+                    "focus={{ preview: false }} on GuideLegend replaces legendFocus={{ preview: false }}",
+                ],
+                anchor: "legend-focus-on-guidelegend",
+            }),
+        ];
+    });
+    deliverAdvisoriesOnce(() => deprecatedLegendFocusDiagnostics);
+    // Deprecated plot-level legendFilter → GuideLegend.filter (one minor window).
+    const deprecatedLegendFilterDiagnostics = $derived.by(() => {
+        const plotProp = readLegacyPlotLegendFilter(input.props);
+        if (plotProp === undefined || plotProp === false)
+            return [];
+        return [
+            deprecatedPropDiagnostic({
+                prop: "legendFilter",
+                since: "0.19.0",
+                removeIn: "0.20.0",
+                suggestions: [
+                    'Use <GuideLegend channel="color" filter /> (or the aesthetic that owns the discrete legend)',
+                    'filter={{ mode: "include", multiple: false }} on GuideLegend replaces legendFilter={{ … }}',
+                ],
+                anchor: "legend-filter-on-guidelegend",
+            }),
+        ];
+    });
+    deliverAdvisoriesOnce(() => deprecatedLegendFilterDiagnostics);
+    // Composition advisories (#659 slices 3+5+6): pure collect over
+    // registry.layers. Last child still wins (shallow merge / last write);
+    // delivery is once-per-dedup-key via compositionAdvisoryDedupKey.
+    const compositionDiagnostics = $derived.by(() => collectCompositionDiagnostics(input.registry.layers));
+    deliverAdvisoriesOnce(() => compositionDiagnostics, compositionAdvisoryDedupKey);
+    // Chrome area-scale / legend diagnostics re-deliver per recompute (outside
+    // the once-only helper by design). Register after chromeState exists.
+    function registerChromeDiagnostics(chrome) {
+        $effect(() => {
+            for (const diagnostic of chrome.areaScaleDiagnostics)
+                deliverDiagnostic(diagnostic);
+        });
+        $effect(() => {
+            for (const diagnostic of chrome.legendDiagnostics)
+                deliverDiagnostic(diagnostic);
+        });
+    }
+    // Runtime-gated inspect advisories — register after the plot runtime exists
+    // (trained scales gate both). Still during init, at the engine's original
+    // registration position.
+    function registerInspectDiagnostics(opts) {
+        // Inspect axis guides that fight bar/col geometry (or bisect on-bar labels)
+        // and freescrolling guides through distribution/interval band geoms (#1528).
+        // After runtime so trained scales gate interval-geom advisories (continuous
+        // shared-x line+errorbar with mode="x" stays silent). Mode x/xy still fire
+        // under coord_flip (#1409): the band-axis guide remains.
+        const inspectGeomDiagnostics = $derived.by(() => {
+            const mode = input.interactionConfig().inspect?.mode;
+            if (mode === undefined)
+                return [];
+            const geoms = layerGeomsFromSpecLayers(opts.assembled()?.layers);
+            const scales = opts.model()?.scales;
+            const discreteBandAxis = scales !== undefined && (scales.x.type === "band" || scales.y.type === "band");
+            return [
+                ...inspectAxisOnBarColDiagnostics(mode, geoms),
+                ...inspectAxisOnDistributionDiagnostics(mode, geoms, { discreteBandAxis }),
+            ];
+        });
+        deliverAdvisoriesOnce(() => inspectGeomDiagnostics);
+        // High-cardinality discrete color/fill + inspect: default tooltip policy
+        // advisory (#1274). Needs trained scales (runtime.model); once-per-channel.
+        const inspectHighCardinality = $derived.by(() => {
+            // Resolved inspect is null when off (never undefined) — see normalizeInteractionConfig.
+            if (input.interactionConfig().inspect === null)
+                return [];
+            const model = opts.model();
+            if (model === null)
+                return [];
+            return inspectHighCardinalityDiagnostics({
+                inspectEnabled: true,
+                domainSizes: discreteColorFillDomainSizes(model.scales),
+            });
+        });
+        deliverAdvisoriesOnce(() => inspectHighCardinality);
+    }
+    return { deliverDiagnostic, registerChromeDiagnostics, registerInspectDiagnostics };
+}