@lumel/ai-schema-host 1.0.0

package/README.md

@@ -0,0 +1,51 @@
+# @lumel/ai-schema-host
+
+Standalone, dependency-free package that hosts the **AI chart-schema contracts**
+and a **curated schema-knowledge JSON** used by Lumel AI agents (generators,
+validators, resolvers) across visuals.
+
+This package was extracted from `@lumel/ap-core`'s `src/ai/schema/types.ts` so
+that any client (chart packages, agent runtimes, devtools, copilots, tests) can
+depend only on a small, stable contract.
+
+## Install
+
+```bash
+yarn add @lumel/ai-schema-host
+```
+
+## Usage
+
+```ts
+import {
+    ChartSchema,
+    SCHEMA_VERSION,
+    AI_SCHEMA_KNOWLEDGE,
+} from '@lumel/ai-schema-host';
+
+const schema: ChartSchema = {
+    schemaVersion: SCHEMA_VERSION,
+    axis: { x: { enabled: true, label: { bold: true } } },
+};
+
+// Index-ready knowledge documents (one per schema section) for the
+// Azure AI Search knowledge base / LLM prompts / devtools.
+const axisDoc = AI_SCHEMA_KNOWLEDGE.find((d) => d.id === 'fabric-chart-axis');
+console.log(axisDoc?.schemaJson, axisDoc?.updatePatterns);
+```
+
+## What's inside
+
+| File                  | Purpose                                                                   |
+| --------------------- | ------------------------------------------------------------------------- |
+| `src/types.ts`        | Public schema contracts: `ChartSchema`, `AxisGroupSchema`, `IKbDocument`. |
+| `src/knowledge.json`  | Index-ready knowledge: array of section documents (build + edit + notes)  |
+| `src/index.ts`        | Barrel exports                                                            |
+
+## Build
+
+```bash
+yarn build         # types + JS
+yarn dev           # watch mode
+yarn clean         # remove dist
+```

package/dist/compiler/AISchemaCompiler.d.ts

@@ -0,0 +1,42 @@
+import knowledge from '../knowledge.json';
+import type { EVisualType, IAISchemaCompiler, IAISchemaCompileInput, IAISchemaApplyResult, IAISchemaValidationResult } from '@lumel/visual-host';
+import { EVisualStateSchemaType, TVisualStateSchema } from '../schemaTypes/AiSchema.type';
+/** Shape of the curated, machine-readable schema knowledge JSON. */
+export type TAiSchemaKnowledge = typeof knowledge;
+/**
+ * Strictly-typed, injectable compiler base for a single visual's AI schema.
+ */
+export declare abstract class AISchemaCompiler<TSchema extends TVisualStateSchema = TVisualStateSchema> implements IAISchemaCompiler<TSchema, TAiSchemaKnowledge> {
+    /** The visual type this compiler targets. */
+    abstract readonly visualType: EVisualType;
+    /** The visual-state schema discriminator this compiler owns. */
+    abstract readonly schemaType: EVisualStateSchemaType;
+    /**
+     * Compile and apply a strictly-typed schema to the live visual.
+     *
+     * Template method: validates the input via {@link validateSchema}, delegates
+     * the visual-specific apply to {@link applySchema}, then wraps the resolved
+     * schema in a deterministic {@link IAISchemaApplyResult}. Subclasses may
+     * override and call `super.compileSchema(input)` to extend this pipeline.
+     */
+    compileSchema(input: IAISchemaCompileInput<TSchema>): Promise<IAISchemaApplyResult<TSchema>>;
+    /**
+     * Visual-specific apply. Implementations mutate the live visual store and
+     * return the resolved schema. Invoked by {@link compileSchema}.
+     */
+    protected abstract applySchema(input: IAISchemaCompileInput<TSchema>): Promise<TSchema>;
+    /** Read and return the visual's current schema. */
+    abstract generateSchema(): Promise<TSchema>;
+    /**
+     * Validate the schema before apply. Each visual must implement this —
+     * validation is visual-specific (e.g. a chart checks whether the requested
+     * axis configuration is supported for the current chart type).
+     *
+     * Return `{ ok: true, issues: [] }` if the schema is valid. Return
+     * `{ ok: false, issues: [...] }` to block apply and surface the issues to
+     * the fabric caller.
+     */
+    abstract validateSchema(schema: TSchema): IAISchemaValidationResult;
+    /** Curated, machine-readable schema knowledge for LLM prompts. */
+    getKnowledge(): TAiSchemaKnowledge;
+}

package/dist/compiler/AISchemaCompiler.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "AISchemaCompiler", {
+    enumerable: true,
+    get: function() {
+        return AISchemaCompiler;
+    }
+});
+const _knowledgejson = /*#__PURE__*/ _interop_require_default(require("../knowledge.json"));
+function _interop_require_default(obj) {
+    return obj && obj.__esModule ? obj : {
+        default: obj
+    };
+}
+class AISchemaCompiler {
+    /**
+     * Compile and apply a strictly-typed schema to the live visual.
+     *
+     * Template method: validates the input via {@link validateSchema}, delegates
+     * the visual-specific apply to {@link applySchema}, then wraps the resolved
+     * schema in a deterministic {@link IAISchemaApplyResult}. Subclasses may
+     * override and call `super.compileSchema(input)` to extend this pipeline.
+     */ async compileSchema(input) {
+        const validation = this.validateSchema(input.schema);
+        if (!validation.ok) {
+            return {
+                ok: false,
+                feedback: {
+                    tone: 'error',
+                    message: 'Schema validation failed.'
+                },
+                schema: input.schema,
+                issues: validation.issues
+            };
+        }
+        try {
+            const schema = await this.applySchema(input);
+            return {
+                ok: true,
+                feedback: {
+                    tone: 'success',
+                    message: 'Schema applied.'
+                },
+                schema,
+                issues: []
+            };
+        } catch (err) {
+            const message = err?.message ?? 'Schema apply failed.';
+            return {
+                ok: false,
+                feedback: {
+                    tone: 'error',
+                    message
+                },
+                schema: input.schema,
+                issues: [
+                    {
+                        path: '',
+                        message
+                    }
+                ]
+            };
+        }
+    }
+    /** Curated, machine-readable schema knowledge for LLM prompts. */ getKnowledge() {
+        return _knowledgejson.default;
+    }
+}

package/dist/compiler/types.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The injection contract lives in `@lumel/visual-host` so the visual host has no
+ * dependency on this package. It is re-exported here so fabric-side consumers of
+ * `@lumel/ai-schema-host` get the strict compiler surface from one place.
+ */
+export type { IAISchemaCompiler, IAISchemaCompileInput, IAISchemaApplyResult, IAISchemaValidationResult, IAISchemaIssue, IAISchemaFeedback, } from '@lumel/visual-host';

package/dist/compiler/types.js

@@ -0,0 +1,8 @@
+/**
+ * The injection contract lives in `@lumel/visual-host` so the visual host has no
+ * dependency on this package. It is re-exported here so fabric-side consumers of
+ * `@lumel/ai-schema-host` get the strict compiler surface from one place.
+ */ "use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export * from './types';
+import type { TKbDocumentList } from './types';
+/** Index-ready curated schema knowledge: one document per schema section. */
+export declare const AI_SCHEMA_KNOWLEDGE: TKbDocumentList;
+export * from './schemaTypes/AiSchema.type';
+export type { IChartSchema } from './schemaTypes/visualStateSchema/ChartSchema/chartSchema.type';
+export type { IMatrixSchema } from './schemaTypes/visualStateSchema/MatrixSchema/matrixSchema.type';
+export type { ISuperFiltersSchema } from './schemaTypes/visualStateSchema/SuperFilter/SuperFilterSchema.type';
+export type { ISecondaryVisualsSchema } from './schemaTypes/visualStateSchema/SecondaryVisual/SecondaryVisualSchema.type';
+export * from './compiler/types';
+export { AISchemaCompiler } from './compiler/AISchemaCompiler';
+export type { TAiSchemaKnowledge } from './compiler/AISchemaCompiler';

package/dist/index.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get AISchemaCompiler () {
+        return _AISchemaCompiler.AISchemaCompiler;
+    },
+    get AI_SCHEMA_KNOWLEDGE () {
+        return AI_SCHEMA_KNOWLEDGE;
+    }
+});
+_export_star(require("./types"), exports);
+const _knowledgejson = /*#__PURE__*/ _interop_require_default(require("./knowledge.json"));
+_export_star(require("./schemaTypes/AiSchema.type"), exports);
+_export_star(require("./compiler/types"), exports);
+const _AISchemaCompiler = require("./compiler/AISchemaCompiler");
+function _export_star(from, to) {
+    Object.keys(from).forEach(function(k) {
+        if (k !== "default" && !Object.prototype.hasOwnProperty.call(to, k)) {
+            Object.defineProperty(to, k, {
+                enumerable: true,
+                get: function() {
+                    return from[k];
+                }
+            });
+        }
+    });
+    return from;
+}
+function _interop_require_default(obj) {
+    return obj && obj.__esModule ? obj : {
+        default: obj
+    };
+}
+const AI_SCHEMA_KNOWLEDGE = _knowledgejson.default;

package/dist/knowledge.json

@@ -0,0 +1,470 @@
+[
+    {
+        "id": "fabric-base-theme",
+        "scope": "base",
+        "visualType": "COMMON",
+        "sectionKey": "theme",
+        "propertyName": "themeSchema",
+        "affectedVisualTypes": ["dashboard", "report", "page"],
+        "title": "Base Theme",
+        "description": "Top-level dashboard/report theme. Sets the global look (light, dark, IBCS, color-blind, etc.) that every visual inherits unless it overrides locally. Lives on baseSchema.themeSchema.name.",
+        "structureNote": "BATCH = replace. themeSchema is a single object { name }. Send the whole themeSchema object when changing the theme. updatePatterns are NON-EXHAUSTIVE examples showing patch SHAPE only — copy the structure/nesting, not the literal values; any key in schemaJson is editable the same way.",
+        "schemaJson": {
+            "name": {
+                "type": "enum",
+                "default": "DEFAULT",
+                "options": ["LIGHT", "DARK", "DEFAULT", "MIDNIGHT", "IBCS", "COLOR_BLIND_LIGHT", "COLOR_BLIND_DARK", "INFORIVER", "CUSTOM"],
+                "description": "Global theme applied to the whole layout. IBCS enables IBCS-standard styling for all charts."
+            }
+        },
+        "updatePatterns": {
+            "setDarkTheme": {
+                "intent": "Switch the dashboard to a dark theme",
+                "patch": { "name": "DARK" }
+            },
+            "setIbcsTheme": {
+                "intent": "Apply IBCS standard styling to the whole report",
+                "patch": { "name": "IBCS" }
+            }
+        }
+    },
+    {
+        "id": "fabric-base-canvas",
+        "scope": "base",
+        "visualType": "COMMON",
+        "sectionKey": "canvas",
+        "propertyName": "canvasSchema",
+        "affectedVisualTypes": ["dashboard", "report", "page"],
+        "title": "Base Canvas",
+        "description": "Dashboard/report-wide canvas: background and global typography defaults that visuals inherit. Lives on baseSchema.canvasSchema.",
+        "structureNote": "BATCH = replace. Re-send the full canvasSchema slice you are changing; preserve sibling keys (background, font). updatePatterns are NON-EXHAUSTIVE examples showing patch SHAPE only — copy the structure/nesting, not the literal values; any key in schemaJson is editable the same way.",
+        "schemaJson": {
+            "background": {
+                "type": "hex-color",
+                "default": "#ffffff",
+                "description": "CSS color of the canvas background behind all visuals."
+            },
+            "font": {
+                "_description": "Global typography defaults inherited by visuals.",
+                "family": { "type": "string", "default": "Segoe UI", "description": "CSS font-family stack for the layout." },
+                "size": { "type": "number", "default": 12, "description": "Base font size (px)." },
+                "color": { "type": "hex-color", "default": "#333333", "description": "Base text color." },
+                "responsive": { "type": "boolean", "default": true, "description": "Scale fonts responsively with the layout size." },
+                "autoColor": { "type": "boolean", "default": false, "description": "Auto-pick text color for contrast against the background." }
+            }
+        },
+        "updatePatterns": {
+            "setBackground": {
+                "intent": "Set the canvas background color",
+                "patch": { "background": "#f5f5f5" }
+            },
+            "setBaseFont": {
+                "intent": "Change the global font family and size (values illustrative)",
+                "patch": { "font": { "family": "Arial", "size": 14 } }
+            }
+        }
+    },
+    {
+        "id": "fabric-base-visualGroupMap",
+        "scope": "base",
+        "visualType": "COMMON",
+        "sectionKey": "visualGroupMap",
+        "propertyName": "visualGroupMap",
+        "affectedVisualTypes": ["dashboard", "report", "page"],
+        "title": "Visual Group Map",
+        "description": "Map of group elements that bundle visuals together for collective layout, visibility and rotation. Keyed by group element id on baseSchema.visualGroupMap.",
+        "structureNote": "BATCH = replace. Each entry is keyed by group id. Send the full group entry when updating; do not drop sibling group entries. updatePatterns are NON-EXHAUSTIVE examples showing patch SHAPE only — copy the structure/nesting, not the literal values; any key in schemaJson is editable the same way.",
+        "schemaJson": {
+            "<groupId>": {
+                "name": { "type": "string", "default": "", "description": "Display name of the group." },
+                "isHidden": { "type": "boolean", "default": false, "description": "Hide the entire group and its visuals." },
+                "isExpanded": { "type": "boolean", "default": true, "description": "Whether the group is expanded in the layout tree." },
+                "shallowDelete": { "type": "boolean", "default": false, "description": "Soft-delete marker; keeps the group entry but removes it from render." },
+                "dimensionConfig": {
+                    "_description": "Sizing behavior of the group container (see visual.dimensionConfig).",
+                    "type": "object"
+                },
+                "rotation": {
+                    "_description": "Group rotation transform.",
+                    "isEnabled": { "type": "boolean", "default": false, "description": "Enable rotation for the group." },
+                    "transform": { "type": "number", "default": 0, "description": "Rotation angle in degrees." },
+                    "center": { "type": "object", "default": null, "description": "Optional rotation center { x, y }." }
+                }
+            }
+        },
+        "updatePatterns": {
+            "hideGroup": {
+                "intent": "Hide a visual group",
+                "patch": { "<groupId>": { "isHidden": true } }
+            },
+            "renameGroup": {
+                "intent": "Rename a visual group",
+                "patch": { "<groupId>": { "name": "KPIs" } }
+            }
+        }
+    },
+    {
+        "id": "fabric-visual-dimension",
+        "scope": "visual",
+        "visualType": "COMMON",
+        "sectionKey": "dimension",
+        "propertyName": "dimension",
+        "affectedVisualTypes": ["chart", "matrix", "superFilter", "secondaryVisual"],
+        "title": "Visual Dimension",
+        "description": "Rendered pixel size of a single visual. Lives on the visual envelope as dimension { width, height }.",
+        "structureNote": "BATCH = replace. Send both width and height together when resizing. updatePatterns are NON-EXHAUSTIVE examples showing patch SHAPE only — copy the structure/nesting, not the literal values; any key in schemaJson is editable the same way.",
+        "schemaJson": {
+            "width": { "type": "number", "default": 400, "description": "Rendered width of the visual in px." },
+            "height": { "type": "number", "default": 300, "description": "Rendered height of the visual in px." }
+        },
+        "updatePatterns": {
+            "resize": {
+                "intent": "Resize the visual (values illustrative)",
+                "patch": { "width": 600, "height": 360 }
+            }
+        }
+    },
+    {
+        "id": "fabric-visual-dimensionConfig",
+        "scope": "visual",
+        "visualType": "COMMON",
+        "sectionKey": "dimensionConfig",
+        "propertyName": "dimensionConfig",
+        "affectedVisualTypes": ["chart", "matrix", "superFilter", "secondaryVisual"],
+        "title": "Visual Dimension Config",
+        "description": "Controls how a visual sizes itself: fixed pixels vs filling available space, fill proportion, and min/max bounds.",
+        "structureNote": "BATCH = replace. Preserve dimensionType, fillProportion, widthMinMax and heightMinMax keys when patching. updatePatterns are NON-EXHAUSTIVE examples showing patch SHAPE only — copy the structure/nesting, not the literal values; any key in schemaJson is editable the same way.",
+        "schemaJson": {
+            "dimensionType": {
+                "_description": "Whether each axis is a fixed size or fills available space.",
+                "widthType": { "type": "enum", "default": "fixed", "options": ["fixed", "fill"], "description": "Width sizing mode." },
+                "heightType": { "type": "enum", "default": "fixed", "options": ["fixed", "fill"], "description": "Height sizing mode." }
+            },
+            "fillProportion": { "type": "number", "default": 1, "description": "Relative share of space when using fill mode." },
+            "widthMinMax": {
+                "_description": "Optional width bounds.",
+                "isEnabled": { "type": "boolean", "default": false, "description": "Enable width min/max clamping." },
+                "min": { "type": "number | null", "default": null, "description": "Minimum width (px)." },
+                "max": { "type": "number | null", "default": null, "description": "Maximum width (px)." }
+            },
+            "heightMinMax": {
+                "_description": "Optional height bounds.",
+                "isEnabled": { "type": "boolean", "default": false, "description": "Enable height min/max clamping." },
+                "min": { "type": "number | null", "default": null, "description": "Minimum height (px)." },
+                "max": { "type": "number | null", "default": null, "description": "Maximum height (px)." }
+            }
+        },
+        "updatePatterns": {
+            "fillWidth": {
+                "intent": "Make the visual fill the available width",
+                "patch": { "dimensionType": { "widthType": "fill" } }
+            }
+        }
+    },
+    {
+        "id": "fabric-visual-position",
+        "scope": "visual",
+        "visualType": "COMMON",
+        "sectionKey": "position",
+        "propertyName": "position",
+        "affectedVisualTypes": ["chart", "matrix", "superFilter", "secondaryVisual"],
+        "title": "Visual Position",
+        "description": "Top-left placement of a visual on the canvas. Lives on the visual envelope as position { x, y }.",
+        "structureNote": "BATCH = replace. Send both x and y together when moving. updatePatterns are NON-EXHAUSTIVE examples showing patch SHAPE only — copy the structure/nesting, not the literal values; any key in schemaJson is editable the same way.",
+        "schemaJson": {
+            "x": { "type": "number", "default": 0, "description": "X offset (px) of the visual's top-left corner." },
+            "y": { "type": "number", "default": 0, "description": "Y offset (px) of the visual's top-left corner." }
+        },
+        "updatePatterns": {
+            "move": {
+                "intent": "Move the visual to a new position (values illustrative)",
+                "patch": { "x": 120, "y": 80 }
+            }
+        }
+    },
+    {
+        "id": "fabric-visual-styles",
+        "scope": "visual",
+        "visualType": "COMMON",
+        "sectionKey": "styles",
+        "propertyName": "styles",
+        "affectedVisualTypes": ["chart", "matrix", "superFilter", "secondaryVisual"],
+        "title": "Visual Element Styles",
+        "description": "Container styling for a visual element: background, border, shadow, corner radius, padding and rotation. These wrap the visual regardless of its inner content.",
+        "structureNote": "BATCH = replace. Each style group (background, border, shadow, cornerRadius, padding, rotation) is its own object; preserve the groups you are not changing. updatePatterns are NON-EXHAUSTIVE examples showing patch SHAPE only — copy the structure/nesting, not the literal values; any key in schemaJson is editable the same way.",
+        "schemaJson": {
+            "background": {
+                "_description": "Container background fill.",
+                "color": { "type": "hex-color", "default": "#ffffff", "description": "Background color." },
+                "image": { "type": "string | null", "default": null, "description": "Optional background image url." },
+                "fillMode": { "type": "enum", "default": "fill", "options": ["fill", "fit", "stretch", "tile"], "description": "How a background image fills the container." },
+                "opacity": { "type": "number", "default": 100, "description": "Background opacity (0-100)." }
+            },
+            "border": {
+                "_description": "Container border.",
+                "isEnabled": { "type": "boolean", "default": false, "description": "Show the border." },
+                "width": { "type": "number", "default": 1, "description": "Border width (px)." },
+                "color": { "type": "hex-color", "default": "#cccccc", "description": "Border color." },
+                "side": { "type": "enum", "default": "all", "options": ["all", "top", "right", "bottom", "left"], "description": "Which side(s) the border applies to." }
+            },
+            "shadow": {
+                "_description": "Drop shadow around the container.",
+                "isEnabled": { "type": "boolean", "default": false, "description": "Show the shadow." },
+                "color": { "type": "hex-color", "default": "#00000033", "description": "Shadow color." },
+                "blur": { "type": "number", "default": 4, "description": "Shadow blur radius (px)." },
+                "distance": { "type": "number", "default": 2, "description": "Shadow offset distance (px)." },
+                "angle": { "type": "number", "default": 90, "description": "Shadow direction angle (degrees)." },
+                "opacity": { "type": "number", "default": 100, "description": "Shadow opacity (0-100)." }
+            },
+            "cornerRadius": {
+                "_description": "Rounded corners of the container.",
+                "isCustomCornerRadius": { "type": "boolean", "default": false, "description": "Use per-corner radii instead of a single value." },
+                "radiusTopLeft": { "type": "number", "default": 0, "description": "Top-left corner radius (px)." },
+                "radiusTopRight": { "type": "number", "default": 0, "description": "Top-right corner radius (px)." },
+                "radiusBottomLeft": { "type": "number", "default": 0, "description": "Bottom-left corner radius (px)." },
+                "radiusBottomRight": { "type": "number", "default": 0, "description": "Bottom-right corner radius (px)." }
+            },
+            "padding": {
+                "_description": "Inner padding of the container.",
+                "leftPadding": { "type": "number", "default": 0, "description": "Left padding (px)." },
+                "rightPadding": { "type": "number", "default": 0, "description": "Right padding (px)." },
+                "topPadding": { "type": "number", "default": 0, "description": "Top padding (px)." },
+                "bottomPadding": { "type": "number", "default": 0, "description": "Bottom padding (px)." }
+            },
+            "rotation": {
+                "_description": "Container rotation transform.",
+                "isEnabled": { "type": "boolean", "default": false, "description": "Enable rotation." },
+                "transform": { "type": "number", "default": 0, "description": "Rotation angle (degrees)." }
+            }
+        },
+        "updatePatterns": {
+            "addBorder": {
+                "intent": "Add a visible border around the visual",
+                "patch": { "border": { "isEnabled": true, "width": 1, "color": "#cccccc" } }
+            },
+            "roundCorners": {
+                "intent": "Round the corners of the visual",
+                "patch": { "cornerRadius": { "radiusTopLeft": 8, "radiusTopRight": 8, "radiusBottomLeft": 8, "radiusBottomRight": 8 } }
+            }
+        }
+    },
+    {
+        "id": "fabric-visual-pivotAssignment",
+        "scope": "visual",
+        "visualType": "COMMON",
+        "sectionKey": "pivotAssignment",
+        "propertyName": "pivotAssignment",
+        "affectedVisualTypes": ["chart", "matrix", "superFilter"],
+        "title": "Pivot Assignment",
+        "description": "Binds a semantic-model field to a visual bucket (axis, AC, PY, PL, FC, etc.) and configures aggregation. This is how data fields land in the visual's data slots.",
+        "structureNote": "BATCH = replace. Each assignment maps one field to one bucket. bucketId must be a valid bucket for the chart template; never invent bucketIds. updatePatterns are NON-EXHAUSTIVE examples showing patch SHAPE only — copy the structure/nesting, not the literal values; any key in schemaJson is editable the same way.",
+        "schemaJson": {
+            "id": { "type": "string", "default": "", "description": "Unique assignment id." },
+            "sourceId": { "type": "string", "default": "", "description": "Field id from the semantic model catalog." },
+            "name": { "type": "string", "default": "", "description": "Field display name." },
+            "columnName": { "type": "string", "default": "", "description": "Underlying column name." },
+            "bucketId": { "type": "string", "default": "", "description": "Target visual bucket, e.g. axis, AC, PY, PL, FC, BP." },
+            "order": { "type": "number", "default": 0, "description": "Order of the field within the bucket." },
+            "dataType": { "type": "enum", "default": "string", "options": ["string", "number", "date", "boolean"], "description": "Column data type." },
+            "aggregationType": {
+                "type": "enum",
+                "default": "SUM",
+                "options": ["SUM", "AVERAGE", "MIN", "MAX", "COUNT", "DISTINCT_COUNT", "NONE"],
+                "description": "Aggregation applied to a measure field."
+            },
+            "formatString": { "type": "string | null", "default": null, "description": "Display format string for the field." },
+            "customName": { "type": "string | null", "default": null, "description": "Optional override label for the field." }
+        },
+        "updatePatterns": {
+            "changeAggregation": {
+                "intent": "Change a measure's aggregation to average",
+                "patch": { "aggregationType": "AVERAGE" }
+            },
+            "renameField": {
+                "intent": "Give a field a custom display name",
+                "patch": { "customName": "Net Revenue" }
+            }
+        }
+    },
+    {
+        "id": "fabric-visual-filterAssignments",
+        "scope": "visual",
+        "visualType": "COMMON",
+        "sectionKey": "filterAssignments",
+        "propertyName": "filterAssignments",
+        "affectedVisualTypes": ["chart", "matrix", "superFilter"],
+        "title": "Filter Assignments",
+        "description": "Super-filter configuration attached to a visual: which filter rules and pivot assignments scope the visual's data.",
+        "structureNote": "BATCH = replace. Preserve filter rule structure; send the full filter slice when editing. updatePatterns are NON-EXHAUSTIVE examples showing patch SHAPE only — copy the structure/nesting, not the literal values; any key in schemaJson is editable the same way.",
+        "schemaJson": {
+            "id": { "type": "string", "default": "", "description": "Filter id." },
+            "filterLevel": { "type": "enum", "default": "visual", "options": ["visual", "page", "report"], "description": "Scope at which the filter applies." },
+            "isDefault": { "type": "boolean", "default": false, "description": "Whether this is a default filter." },
+            "isDeleted": { "type": "boolean", "default": false, "description": "Soft-delete marker." },
+            "configuration": { "type": "object", "default": null, "description": "Filter rule definition (operator, values)." },
+            "pivotAssignments": { "type": "array", "default": [], "description": "Fields the filter is bound to." }
+        },
+        "updatePatterns": {
+            "disableFilter": {
+                "intent": "Remove a filter from the visual",
+                "patch": { "isDeleted": true }
+            }
+        }
+    },
+    {
+        "id": "fabric-chart-axis",
+        "scope": "visual",
+        "visualType": "CHART",
+        "sectionKey": "axis",
+        "propertyName": "axis",
+        "affectedVisualTypes": ["bar", "column", "line", "area", "combo", "waterfall", "scatter", "bubble"],
+        "title": "Chart Axis Configuration",
+        "description": "Controls the chart axes: x (category), y (primary value), y2 (secondary/dual value) and yMeasures (per-measure value axes keyed by multiple-axis id). Each axis has enabled, label, title and gridLine groups. Not applicable to pie/donut/treemap/funnel/sankey/gantt.",
+        "structureNote": "BATCH = replace. y-axis title color/size/bold/italic are NOT read from title.* — they route to the matching series label; only title.show + x-axis title.text apply directly. Re-send the full axis slice you change and preserve sibling axes. updatePatterns are NON-EXHAUSTIVE examples showing patch SHAPE only — copy the structure/nesting, not the literal values; any key in schemaJson is editable the same way.",
+        "schemaJson": {
+            "x": {
+                "_description": "Category axis.",
+                "enabled": { "type": "boolean", "default": true, "description": "Show or hide the entire x-axis." },
+                "display": { "type": "enum", "default": "scaleBand", "options": ["off", "yAxis", "scaleBand", "individualScaling"], "description": "Axis render mode." },
+                "label": {
+                    "_description": "Tick / category label styling.",
+                    "show": { "type": "boolean", "default": true, "description": "Show category labels." },
+                    "fontSize": { "type": "number", "default": null, "description": "Label font size (px)." },
+                    "bold": { "type": "boolean", "default": false, "description": "Bold labels." },
+                    "italic": { "type": "boolean", "default": false, "description": "Italic labels." },
+                    "color": { "type": "hex-color", "default": "#333333", "description": "Label text color." }
+                },
+                "title": {
+                    "_description": "Axis title text + styling.",
+                    "show": { "type": "boolean", "default": true, "description": "Show the axis title." },
+                    "text": { "type": "string", "default": "", "description": "Axis title text (x-axis applies directly)." },
+                    "fontSize": { "type": "number", "default": null, "description": "Title font size (px)." },
+                    "bold": { "type": "boolean", "default": false, "description": "Bold title." },
+                    "italic": { "type": "boolean", "default": false, "description": "Italic title." },
+                    "color": { "type": "hex-color", "default": "#333333", "description": "Title text color." }
+                },
+                "gridLine": {
+                    "_description": "Major gridline visibility, color and width.",
+                    "show": { "type": "boolean", "default": true, "description": "Show gridlines." },
+                    "color": { "type": "hex-color", "default": "#cccccc", "description": "Gridline color." },
+                    "width": { "type": "number", "default": 1, "description": "Gridline width (px)." }
+                }
+            },
+            "y": {
+                "_description": "Primary value axis. Same field groups as x. Note y-title style routes to series labels.",
+                "enabled": { "type": "boolean", "default": true, "description": "Show or hide the primary y-axis." },
+                "display": { "type": "enum", "default": "scaleBand", "options": ["off", "yAxis", "scaleBand", "individualScaling"], "description": "Axis render mode." },
+                "label": { "type": "object", "description": "Same label group as x.label." },
+                "title": { "type": "object", "description": "Same title group as x.title; only show applies directly, style routes to series label." },
+                "gridLine": { "type": "object", "description": "Same gridLine group as x.gridLine." }
+            },
+            "y2": {
+                "_description": "Secondary (dual) value axis. Same structure as y.",
+                "enabled": { "type": "boolean", "default": false, "description": "Show or hide the secondary y-axis." }
+            },
+            "yMeasures": {
+                "_description": "Per-measure value axes keyed by multipleYAxis id. Each value has the same structure as a single axis.",
+                "<multipleYAxisId>": { "type": "object", "description": "Axis config for one measure (label/title/gridLine)." }
+            }
+        },
+        "updatePatterns": {
+            "enableXAxisBoldLabels": {
+                "intent": "Enable the x-axis and bold its labels",
+                "patch": { "x": { "enabled": true, "label": { "bold": true } } }
+            },
+            "styleYTitle": {
+                "intent": "Color the primary y-axis title and set its size (routes to series labels; values illustrative)",
+                "patch": { "y": { "title": { "color": "#ff0000", "fontSize": 14 } } }
+            },
+            "stylePerMeasureAxis": {
+                "intent": "Style a per-measure y-axis label",
+                "patch": { "yMeasures": { "<multipleYAxisId>": { "label": { "color": "#333333" } } } }
+            },
+            "hideXGridLines": {
+                "intent": "Hide the x-axis grid lines",
+                "patch": { "x": { "gridLine": { "show": false } } }
+            }
+        }
+    },
+    {
+        "id": "fabric-chart-canvas",
+        "scope": "visual",
+        "visualType": "CHART",
+        "sectionKey": "canvas",
+        "propertyName": "canvas",
+        "affectedVisualTypes": ["bar", "column", "line", "area", "combo", "pie", "donut", "treemap", "funnel"],
+        "title": "Chart Canvas",
+        "description": "Chart-level canvas controls: chart theme, background color and typography. Overrides the inherited base canvas for this chart only.",
+        "structureNote": "BATCH = replace. Preserve sibling keys (theme, background, font) when patching. Changing theme resets measuresStyle to that theme's defaults. updatePatterns are NON-EXHAUSTIVE examples showing patch SHAPE only — copy the structure/nesting, not the literal values; any key in schemaJson is editable the same way.",
+        "schemaJson": {
+            "theme": {
+                "type": "enum",
+                "default": "ibcs",
+                "options": ["ibcs", "default", "ocean", "spring", "autumn", "grayscale"],
+                "description": "Active color theme. ibcs = IBCS standard black/gray palette (AC=black, PY=gray). Changing theme resets measuresStyle to theme defaults."
+            },
+            "background": { "type": "hex-color", "default": "#ffffff", "description": "Chart canvas background color." },
+            "font": {
+                "_description": "Chart typography.",
+                "family": { "type": "string", "default": "Segoe UI", "description": "Font family stack." },
+                "size": { "type": "number", "default": 12, "description": "Font size (px)." },
+                "color": { "type": "hex-color", "default": "#333333", "description": "Text color." },
+                "responsive": { "type": "boolean", "default": true, "description": "Scale fonts responsively." },
+                "autoColor": { "type": "boolean", "default": false, "description": "Auto-pick text color for contrast." }
+            }
+        },
+        "updatePatterns": {
+            "setChartTheme": {
+                "intent": "Switch the chart color theme (e.g. to ocean)",
+                "patch": { "theme": "ocean" }
+            },
+            "setChartBackground": {
+                "intent": "Set the chart background color",
+                "patch": { "background": "#fafafa" }
+            },
+            "setChartFont": {
+                "intent": "Change the chart font (values illustrative)",
+                "patch": { "font": { "family": "Arial", "size": 13 } }
+            }
+        }
+    },
+    {
+        "id": "fabric-matrix-placeholder",
+        "scope": "visual",
+        "visualType": "MATRIX",
+        "sectionKey": "matrix",
+        "propertyName": "matrixSchema",
+        "affectedVisualTypes": ["matrix"],
+        "title": "Matrix Visual State (pending)",
+        "description": "Placeholder for the matrix visual-state schema. The matrix schema is not yet defined; no editable visual-state properties are available here yet.",
+        "structureNote": "Schema pending. Do not emit patches for matrix visual-state until this section gains fields.",
+        "schemaJson": {},
+        "updatePatterns": {}
+    },
+    {
+        "id": "fabric-superFilter-placeholder",
+        "scope": "visual",
+        "visualType": "SUPER_FILTER",
+        "sectionKey": "superFilter",
+        "propertyName": "superFiltersSchema",
+        "affectedVisualTypes": ["superFilter"],
+        "title": "Super Filter Visual State (pending)",
+        "description": "Placeholder for the super-filter visual-state schema. The schema is not yet defined; no editable visual-state properties are available here yet.",
+        "structureNote": "Schema pending. Do not emit patches for super-filter visual-state until this section gains fields.",
+        "schemaJson": {},
+        "updatePatterns": {}
+    },
+    {
+        "id": "fabric-secondaryVisual-placeholder",
+        "scope": "visual",
+        "visualType": "SECONDARY_VISUAL",
+        "sectionKey": "secondaryVisual",
+        "propertyName": "secondaryVisualsSchema",
+        "affectedVisualTypes": ["secondaryVisual"],
+        "title": "Secondary Visual State (pending)",
+        "description": "Placeholder for the secondary-visual visual-state schema. The schema is not yet defined; no editable visual-state properties are available here yet.",
+        "structureNote": "Schema pending. Do not emit patches for secondary-visual visual-state until this section gains fields.",
+        "schemaJson": {},
+        "updatePatterns": {}
+    }
+]

package/dist/schemaTypes/AiSchema.type.d.ts

@@ -0,0 +1,37 @@
+import { IMatrixSchema } from './visualStateSchema/MatrixSchema/matrixSchema.type';
+import { ISecondaryVisualsSchema } from './visualStateSchema/SecondaryVisual/SecondaryVisualSchema.type';
+import { ISuperFiltersSchema } from './visualStateSchema/SuperFilter/SuperFilterSchema.type';
+import { IChartSchema } from './visualStateSchema/ChartSchema/chartSchema.type';
+import type { EThemeType, EVisualType, IGroupElement, IPivotAssignment, ISuperFilter, IVisualDimension, IVisualDimensionConfig, IVisualElementStyles, IVisualPosition } from '@lumel/visual-host';
+export type TVisualStateSchema = IMatrixSchema | IChartSchema | ISuperFiltersSchema | ISecondaryVisualsSchema;
+export declare enum EVisualStateSchemaType {
+    CHART = "CHART",
+    MATRIX = "MATRIX",
+    SUPER_FILTER = "SUPER_FILTER",
+    SECONDARY_VISUAL = "SECONDARY_VISUAL"
+}
+export interface IVisualSchema {
+    chartType?: string;
+    visualId?: string;
+    dimensionConfig?: IVisualDimensionConfig;
+    dimension?: IVisualDimension;
+    position?: IVisualPosition;
+    styles?: IVisualElementStyles;
+    filterAssignments?: Partial<ISuperFilter>;
+    pivotAssignment?: Partial<IPivotAssignment>;
+    visualType?: EVisualType;
+    visualStateSchema?: TVisualStateSchema;
+}
+export type TVisualGroupMap = Record<TGroupElementId, IGroupElement>;
+export type TGroupElementId = string;
+export interface IThemeSchema {
+    name?: EThemeType;
+}
+export interface IAiPlanningSchema {
+    baseSchema: {
+        themeSchema?: IThemeSchema;
+        canvasSchema?: unknown;
+        visualGroupMap?: TVisualGroupMap;
+    };
+    visualSchema?: IVisualSchema[];
+}

package/dist/schemaTypes/AiSchema.type.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "EVisualStateSchemaType", {
+    enumerable: true,
+    get: function() {
+        return EVisualStateSchemaType;
+    }
+});
+var EVisualStateSchemaType = /*#__PURE__*/ function(EVisualStateSchemaType) {
+    EVisualStateSchemaType["CHART"] = "CHART";
+    EVisualStateSchemaType["MATRIX"] = "MATRIX";
+    EVisualStateSchemaType["SUPER_FILTER"] = "SUPER_FILTER";
+    EVisualStateSchemaType["SECONDARY_VISUAL"] = "SECONDARY_VISUAL";
+    return EVisualStateSchemaType;
+}({});

package/dist/schemaTypes/visualStateSchema/ChartSchema/chartSchema.type.d.ts

@@ -0,0 +1,53 @@
+export type TChartTheme = string;
+export interface AxisLabelSchema {
+    show?: boolean;
+    fontSize?: number;
+    bold?: boolean;
+    italic?: boolean;
+    color?: string;
+}
+export interface AxisTitleSchema {
+    show?: boolean;
+    text?: string;
+    fontSize?: number;
+    bold?: boolean;
+    italic?: boolean;
+    color?: string;
+}
+export interface AxisGridLineSchema {
+    show?: boolean;
+    color?: string;
+    width?: number;
+}
+export type TYAxisDisplayType = 'off' | 'yAxis' | 'scaleBand' | 'individualScaling';
+export interface AxisSchema {
+    enabled?: boolean;
+    /** Y-axis rendering mode. Applies to `axis.y` and `axis.yMeasures.*` only. */
+    display?: TYAxisDisplayType;
+    label?: AxisLabelSchema;
+    title?: AxisTitleSchema;
+    gridLine?: AxisGridLineSchema;
+}
+export interface AxisGroupSchema {
+    x?: AxisSchema;
+    y?: AxisSchema;
+    y2?: AxisSchema;
+    yMeasures?: Record<string, AxisSchema>;
+}
+export interface CanvasFontSchema {
+    family?: string;
+    size?: number;
+    color?: string;
+    responsive?: boolean;
+    autoColor?: boolean;
+}
+export interface CanvasSchema {
+    theme?: TChartTheme;
+    background?: string;
+    font?: CanvasFontSchema;
+}
+export interface IChartSchema {
+    schemaVersion?: number;
+    axis?: AxisGroupSchema;
+    canvas?: CanvasSchema;
+}

package/dist/schemaTypes/visualStateSchema/ChartSchema/chartSchema.type.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});

package/dist/schemaTypes/visualStateSchema/MatrixSchema/matrixSchema.type.d.ts

@@ -0,0 +1,2 @@
+export interface IMatrixSchema {
+}

package/dist/schemaTypes/visualStateSchema/MatrixSchema/matrixSchema.type.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});

package/dist/schemaTypes/visualStateSchema/SecondaryVisual/SecondaryVisualSchema.type.d.ts

@@ -0,0 +1,2 @@
+export interface ISecondaryVisualsSchema {
+}

package/dist/schemaTypes/visualStateSchema/SecondaryVisual/SecondaryVisualSchema.type.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});

package/dist/schemaTypes/visualStateSchema/SuperFilter/SuperFilterSchema.type.d.ts

@@ -0,0 +1,2 @@
+export interface ISuperFiltersSchema {
+}

package/dist/schemaTypes/visualStateSchema/SuperFilter/SuperFilterSchema.type.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});

package/dist/types.d.ts

@@ -0,0 +1,82 @@
+export declare const SCHEMA_VERSION = 1;
+export type TChartTheme = string;
+export interface AxisLabelSchema {
+    show?: boolean;
+    fontSize?: number;
+    bold?: boolean;
+    italic?: boolean;
+    color?: string;
+}
+export interface AxisTitleSchema {
+    show?: boolean;
+    text?: string;
+    fontSize?: number;
+    bold?: boolean;
+    italic?: boolean;
+    color?: string;
+}
+export interface AxisGridLineSchema {
+    show?: boolean;
+    color?: string;
+    width?: number;
+}
+export interface AxisSchema {
+    enabled?: boolean;
+    label?: AxisLabelSchema;
+    title?: AxisTitleSchema;
+    gridLine?: AxisGridLineSchema;
+}
+export interface AxisGroupSchema {
+    x?: AxisSchema;
+    y?: AxisSchema;
+    y2?: AxisSchema;
+    yMeasures?: Record<string, AxisSchema>;
+}
+export interface CanvasFontSchema {
+    family?: string;
+    size?: number;
+    color?: string;
+    responsive?: boolean;
+    autoColor?: boolean;
+}
+export interface CanvasSchema {
+    theme?: TChartTheme;
+    background?: string;
+    font?: CanvasFontSchema;
+}
+export interface ChartSchema {
+    schemaVersion?: number;
+    axis?: AxisGroupSchema;
+    canvas?: CanvasSchema;
+}
+export type SchemaConcern = 'axis' | 'canvas';
+export declare const SCHEMA_CONCERNS: readonly SchemaConcern[];
+export interface SchemaOperation {
+    /** Dotted path into a {@link ChartSchema}, e.g. `axis.x.enabled`. */
+    path: string;
+    value: unknown;
+}
+export interface SchemaOperationList {
+    schemaVersion?: number;
+    operations: SchemaOperation[];
+}
+export type TKbScope = 'base' | 'visual';
+export type TKbVisualType = 'COMMON' | 'CHART' | 'MATRIX' | 'SUPER_FILTER' | 'SECONDARY_VISUAL';
+export interface IKbUpdatePattern {
+    intent: string;
+    patch: Record<string, unknown>;
+}
+export interface IKbDocument {
+    id: string;
+    scope: TKbScope;
+    visualType: TKbVisualType;
+    sectionKey: string;
+    propertyName: string;
+    affectedVisualTypes: string[];
+    title: string;
+    description: string;
+    structureNote: string;
+    schemaJson: Record<string, unknown>;
+    updatePatterns: Record<string, IKbUpdatePattern>;
+}
+export type TKbDocumentList = IKbDocument[];

package/dist/types.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get SCHEMA_CONCERNS () {
+        return SCHEMA_CONCERNS;
+    },
+    get SCHEMA_VERSION () {
+        return SCHEMA_VERSION;
+    }
+});
+const SCHEMA_VERSION = 1;
+const SCHEMA_CONCERNS = [
+    'canvas',
+    'axis'
+];

package/package.json

@@ -0,0 +1,37 @@
+{
+    "name": "@lumel/ai-schema-host",
+    "description": "AI schema contracts and curated schema-knowledge for Lumel chart agents",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "version": "1.0.0",
+    "files": [
+        "dist"
+    ],
+    "publishConfig": {
+        "access": "public",
+        "registry": "https://registry.npmjs.org/"
+    },
+    "scripts": {
+        "dev": "swc src -d dist --watch --strip-leading-paths --source-maps true --copy-files --config-file .swcrc",
+        "build:ts": "swc src -d dist --strip-leading-paths --copy-files --config-file .prod.swcrc",
+        "build:ts:debug": "swc src -d dist --strip-leading-paths --source-maps true --copy-files --config-file .swcrc",
+        "build:types": "tsc --emitDeclarationOnly",
+        "types:only": "yarn run clean && tsc --emitDeclarationOnly",
+        "build": "yarn run clean && yarn run build:types && yarn run build:ts",
+        "build:debug": "yarn run clean && yarn run build:types && yarn run build:ts:debug",
+        "build:packages": "yarn run build",
+        "clean": "rimraf dist"
+    },
+    "author": "Lumel",
+    "license": "ISC",
+    "peerDependencies": {
+        "@lumel/visual-host": "*"
+    },
+    "devDependencies": {
+        "@lumel/visual-host": "workspace:*",
+        "@swc/cli": "^0.5.0",
+        "@swc/core": "^1.7.23",
+        "rimraf": "^6.0.1",
+        "typescript": "^5.5.4"
+    }
+}