@xpert-ai/plugin-live-dashboard 0.4.1 → 0.6.0

package/dist/lib/editing.d.ts

@@ -1,3 +1,4 @@
+import type { DashboardSaveRequests } from './save-requests';
 import { z } from 'zod/v3';
 import type { AnalyticsBinding, XpertResolvedViewHostContext } from '@xpert-ai/contracts';
 import { type IAgentMiddlewareContext } from '@xpert-ai/plugin-sdk';
@@ -6,6 +7,66 @@ import { DashboardService } from './dashboard.service';
 import { type DashboardSelection } from './editing-session';
 export { dashboardSelectionSchema, dashboardContextSchema } from './editing-session';
 export declare const updateToolSchema: z.ZodObject<{
+    sourceMetadata: z.ZodOptional<z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodObject<{
+        bindingId: z.ZodString;
+        title: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        bindingId: string;
+        title: string;
+        description?: string | undefined;
+    }, {
+        bindingId: string;
+        title: string;
+        description?: string | undefined;
+    }>, "many">, {
+        bindingId: string;
+        title: string;
+        description?: string | undefined;
+    }[], unknown>>>;
+    components: z.ZodOptional<z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        elementId: z.ZodString;
+        title: z.ZodString;
+        kind: z.ZodEnum<["metric", "chart", "table", "filter", "text"]>;
+        sources: z.ZodArray<z.ZodObject<{
+            bindingId: z.ZodString;
+            fieldIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        }, "strict", z.ZodTypeAny, {
+            bindingId: string;
+            fieldIds?: string[] | undefined;
+        }, {
+            bindingId: string;
+            fieldIds?: string[] | undefined;
+        }>, "many">;
+    }, "strict", z.ZodTypeAny, {
+        title: string;
+        id: string;
+        elementId: string;
+        kind: "filter" | "metric" | "chart" | "table" | "text";
+        sources: {
+            bindingId: string;
+            fieldIds?: string[] | undefined;
+        }[];
+    }, {
+        title: string;
+        id: string;
+        elementId: string;
+        kind: "filter" | "metric" | "chart" | "table" | "text";
+        sources: {
+            bindingId: string;
+            fieldIds?: string[] | undefined;
+        }[];
+    }>, "many">, {
+        title: string;
+        id: string;
+        elementId: string;
+        kind: "filter" | "metric" | "chart" | "table" | "text";
+        sources: {
+            bindingId: string;
+            fieldIds?: string[] | undefined;
+        }[];
+    }[], unknown>>>;
     controls: z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodObject<{
         controlId: z.ZodString;
         type: z.ZodEnum<["string", "number", "boolean", "date"]>;
@@ -42,24 +103,24 @@ export declare const updateToolSchema: z.ZodObject<{
         color: z.ZodOptional<z.ZodString>;
     }, "strict", z.ZodTypeAny, {
         type: "bar" | "line" | "area" | "pie" | "scatter";
-        id: string;
         title: string;
+        id: string;
         datasetId: string;
         x: string;
         y: string;
         color?: string | undefined;
     }, {
         type: "bar" | "line" | "area" | "pie" | "scatter";
-        id: string;
         title: string;
+        id: string;
         datasetId: string;
         x: string;
         y: string;
         color?: string | undefined;
     }>, "many">, {
         type: "bar" | "line" | "area" | "pie" | "scatter";
-        id: string;
         title: string;
+        id: string;
         datasetId: string;
         x: string;
         y: string;
@@ -71,18 +132,18 @@ export declare const updateToolSchema: z.ZodObject<{
         datasetId: z.ZodString;
         fields: z.ZodArray<z.ZodString, "many">;
     }, "strict", z.ZodTypeAny, {
-        id: string;
         title: string;
+        id: string;
         datasetId: string;
         fields: string[];
     }, {
-        id: string;
         title: string;
+        id: string;
         datasetId: string;
         fields: string[];
     }>, "many">, {
-        id: string;
         title: string;
+        id: string;
         datasetId: string;
         fields: string[];
     }[], unknown>>;
@@ -94,16 +155,19 @@ export declare const updateToolSchema: z.ZodObject<{
         controlIds: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
         viewIds: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
         htmlElementIds: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        componentIds: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     }, "strict", z.ZodTypeAny, {
         bindingIds: string[];
         controlIds: string[];
         viewIds: string[];
         htmlElementIds: string[];
+        componentIds: string[];
     }, {
         bindingIds?: string[] | undefined;
         controlIds?: string[] | undefined;
         viewIds?: string[] | undefined;
         htmlElementIds?: string[] | undefined;
+        componentIds?: string[] | undefined;
     }>>;
     title: z.ZodString;
     editId: z.ZodString;
@@ -116,6 +180,21 @@ export declare const updateToolSchema: z.ZodObject<{
     expectedRevision: number;
     expectedCurrentVersionId: string | null;
     editId: string;
+    sourceMetadata?: {
+        bindingId: string;
+        title: string;
+        description?: string | undefined;
+    }[] | undefined;
+    components?: {
+        title: string;
+        id: string;
+        elementId: string;
+        kind: "filter" | "metric" | "chart" | "table" | "text";
+        sources: {
+            bindingId: string;
+            fieldIds?: string[] | undefined;
+        }[];
+    }[] | undefined;
     controls?: {
         type: "string" | "number" | "boolean" | "date";
         controlId: string;
@@ -125,16 +204,16 @@ export declare const updateToolSchema: z.ZodObject<{
     }[] | undefined;
     charts?: {
         type: "bar" | "line" | "area" | "pie" | "scatter";
-        id: string;
         title: string;
+        id: string;
         datasetId: string;
         x: string;
         y: string;
         color?: string | undefined;
     }[] | undefined;
     tables?: {
-        id: string;
         title: string;
+        id: string;
         datasetId: string;
         fields: string[];
     }[] | undefined;
@@ -146,6 +225,7 @@ export declare const updateToolSchema: z.ZodObject<{
         controlIds: string[];
         viewIds: string[];
         htmlElementIds: string[];
+        componentIds: string[];
     } | undefined;
     htmlPath?: string | undefined;
 }, {
@@ -153,6 +233,8 @@ export declare const updateToolSchema: z.ZodObject<{
     expectedRevision: number;
     expectedCurrentVersionId: string | null;
     editId: string;
+    sourceMetadata?: unknown;
+    components?: unknown;
     controls?: unknown;
     charts?: unknown;
     tables?: unknown;
@@ -164,12 +246,13 @@ export declare const updateToolSchema: z.ZodObject<{
         controlIds?: string[] | undefined;
         viewIds?: string[] | undefined;
         htmlElementIds?: string[] | undefined;
+        componentIds?: string[] | undefined;
     } | undefined;
     htmlPath?: string | undefined;
 }>;
-export declare const EDITING_GUIDANCE = "Opening or reading a dashboard does not modify it. A selection_required result is normal: show its message to the user and wait for an explicit selection; do not retry, infer a target from history, or create a replacement. Do not save an unchanged editing copy or reopen/update merely to confirm a successful save; use the mutation receipt. For existing dashboards, call dashboard_open first and inspect presentation.type. For standard dashboards, update definition fields directly: a rename needs only title, editId, expectedRevision and expectedCurrentVersionId. No HTML file exists; omit htmlPath and libraries. For HTML dashboards only, open prepares a unique editing copy at htmlPath. Read with sandbox_read_file. If a long HTML line is truncated, do not repeat the same read: use dashboard_read_html with editId and follow nextOffset until null to inspect the saved source, then apply exact replacements to htmlPath. Never replace a file with a truncated preview. Edit with sandbox_edit_file/multi_edit_file (sandbox_write_file is create-only), then call dashboard_update with that exact htmlPath and read revisions. If the user requests a rename, include the new title in this same update; editing the HTML heading alone does not rename the Artifact. Save each batch automatically without human confirmation. Files are not dashboard saves. Preserve Binding semantics, stable component IDs and dependency locks unless requested. Update arrays upsert by ID, preserving omitted components; removals must name explicitly requested deletions. HTML updates retain existing element IDs. For new HTML, assign stable IDs to every KPI, chart, detail table and filter. Read and patch the current file instead of rebuilding unrelated sections. On conflict retain the editing file, open the latest draft and reconcile; never silently overwrite. Historical versions are read-only references. All Agent saves are drafts; only the Workbench human publish action creates formal versions. Read the live-dashboard skill for the complete workflow.";
+export declare const EDITING_GUIDANCE = "Opening or reading a dashboard does not modify it. A selection_required result is normal: show its message to the user and wait for an explicit selection; do not retry, infer a target from history, or create a replacement. Do not save an unchanged editing copy or reopen/update merely to confirm a successful save; use the mutation receipt. For existing dashboards, call dashboard_open first and inspect presentation.type. For standard dashboards, update definition fields directly: a rename needs only title, editId, expectedRevision and expectedCurrentVersionId. No HTML file exists; omit htmlPath and libraries. For HTML dashboards only, open prepares a unique editing copy at htmlPath. Read with sandbox_read_file. If a long HTML line is truncated, do not repeat the same read: use dashboard_read_html with editId and follow nextOffset until null to inspect the saved source, then apply exact replacements to htmlPath. Never replace a file with a truncated preview. Edit with sandbox_edit_file/multi_edit_file (sandbox_write_file is create-only), then call dashboard_update with that exact htmlPath and read revisions. If the user requests a rename, include the new title in this same update; editing the HTML heading alone does not rename the Artifact. Save each batch automatically without human confirmation. Files are not dashboard saves. Preserve Binding semantics, stable component IDs and dependency locks unless requested. To add filters to an existing Binding, copy its complete dashboard_open.bindings[] entry, retain binding.id and existing parameters[].controlId, and call dashboard_preview_binding after changing payload/parameters/defaults. Binding ID is independent of output.datasetId; simplified dashboard_preview derives the ID from datasetId and can accidentally add a new Binding instead of updating the old one. Use the stable Binding ID in HTML query/subscribe calls. Submit every intended changed/new Binding previewId and matching controls with htmlPath in the same dashboard_update. Update arrays upsert by ID, preserving omitted components; removals must name explicitly requested deletions. On preflight failure, compare expected/requested Binding IDs, repair the HTML or previews, and retain all intended previewIds, controls, title and htmlPath when retrying. Dropping previewIds does not register new HTML queries. Do not remove an existing Binding merely to suppress validation. HTML updates retain existing element IDs. For new HTML, assign stable IDs to every KPI, chart, detail table and filter. Read and patch the current file instead of rebuilding unrelated sections. On conflict retain the editing file, open the latest draft and reconcile; never silently overwrite. Historical versions are read-only references. All Agent saves are drafts; only the Workbench human publish action creates formal versions. Read the live-dashboard skill for the complete workflow.";
 /** Run-local read receipts carry planning versions; authorization and CAS remain in the domain service. */
-export declare function createEditingTools(service: DashboardService, scope: XpertResolvedViewHostContext, context: IAgentMiddlewareContext, resolvePreviews: (ids: string[]) => AnalyticsBinding[], validateFinal: (manifest: DashboardManifest, requirePreviews: boolean, changedBindingIds?: string[]) => void, onOpen?: (path: string, artifactId: string) => void, currentTarget?: (config: unknown) => DashboardSelection | null | undefined): (import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+export declare function createEditingTools(service: DashboardService, scope: XpertResolvedViewHostContext, context: IAgentMiddlewareContext, resolvePreviews: (ids: string[]) => AnalyticsBinding[], validateFinal: (manifest: DashboardManifest, requirePreviews: boolean, changedBindingIds?: string[]) => void, onOpen?: (path: string, artifactId: string) => void, currentTarget?: (config: unknown) => DashboardSelection | null | undefined, saveRequests?: DashboardSaveRequests): (import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
     page: z.ZodDefault<z.ZodNumber>;
 }, "strict", z.ZodTypeAny, {
     page: number;
@@ -217,6 +300,66 @@ export declare function createEditingTools(service: DashboardService, scope: Xpe
 }, {
     artifactId?: string | undefined;
 }, string> | import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+    sourceMetadata: z.ZodOptional<z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodObject<{
+        bindingId: z.ZodString;
+        title: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        bindingId: string;
+        title: string;
+        description?: string | undefined;
+    }, {
+        bindingId: string;
+        title: string;
+        description?: string | undefined;
+    }>, "many">, {
+        bindingId: string;
+        title: string;
+        description?: string | undefined;
+    }[], unknown>>>;
+    components: z.ZodOptional<z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        elementId: z.ZodString;
+        title: z.ZodString;
+        kind: z.ZodEnum<["metric", "chart", "table", "filter", "text"]>;
+        sources: z.ZodArray<z.ZodObject<{
+            bindingId: z.ZodString;
+            fieldIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        }, "strict", z.ZodTypeAny, {
+            bindingId: string;
+            fieldIds?: string[] | undefined;
+        }, {
+            bindingId: string;
+            fieldIds?: string[] | undefined;
+        }>, "many">;
+    }, "strict", z.ZodTypeAny, {
+        title: string;
+        id: string;
+        elementId: string;
+        kind: "filter" | "metric" | "chart" | "table" | "text";
+        sources: {
+            bindingId: string;
+            fieldIds?: string[] | undefined;
+        }[];
+    }, {
+        title: string;
+        id: string;
+        elementId: string;
+        kind: "filter" | "metric" | "chart" | "table" | "text";
+        sources: {
+            bindingId: string;
+            fieldIds?: string[] | undefined;
+        }[];
+    }>, "many">, {
+        title: string;
+        id: string;
+        elementId: string;
+        kind: "filter" | "metric" | "chart" | "table" | "text";
+        sources: {
+            bindingId: string;
+            fieldIds?: string[] | undefined;
+        }[];
+    }[], unknown>>>;
     controls: z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodObject<{
         controlId: z.ZodString;
         type: z.ZodEnum<["string", "number", "boolean", "date"]>;
@@ -253,24 +396,24 @@ export declare function createEditingTools(service: DashboardService, scope: Xpe
         color: z.ZodOptional<z.ZodString>;
     }, "strict", z.ZodTypeAny, {
         type: "bar" | "line" | "area" | "pie" | "scatter";
-        id: string;
         title: string;
+        id: string;
         datasetId: string;
         x: string;
         y: string;
         color?: string | undefined;
     }, {
         type: "bar" | "line" | "area" | "pie" | "scatter";
-        id: string;
         title: string;
+        id: string;
         datasetId: string;
         x: string;
         y: string;
         color?: string | undefined;
     }>, "many">, {
         type: "bar" | "line" | "area" | "pie" | "scatter";
-        id: string;
         title: string;
+        id: string;
         datasetId: string;
         x: string;
         y: string;
@@ -282,18 +425,18 @@ export declare function createEditingTools(service: DashboardService, scope: Xpe
         datasetId: z.ZodString;
         fields: z.ZodArray<z.ZodString, "many">;
     }, "strict", z.ZodTypeAny, {
-        id: string;
         title: string;
+        id: string;
         datasetId: string;
         fields: string[];
     }, {
-        id: string;
         title: string;
+        id: string;
         datasetId: string;
         fields: string[];
     }>, "many">, {
-        id: string;
         title: string;
+        id: string;
         datasetId: string;
         fields: string[];
     }[], unknown>>;
@@ -305,16 +448,19 @@ export declare function createEditingTools(service: DashboardService, scope: Xpe
         controlIds: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
         viewIds: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
         htmlElementIds: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        componentIds: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     }, "strict", z.ZodTypeAny, {
         bindingIds: string[];
         controlIds: string[];
         viewIds: string[];
         htmlElementIds: string[];
+        componentIds: string[];
     }, {
         bindingIds?: string[] | undefined;
         controlIds?: string[] | undefined;
         viewIds?: string[] | undefined;
         htmlElementIds?: string[] | undefined;
+        componentIds?: string[] | undefined;
     }>>;
     title: z.ZodString;
     editId: z.ZodString;
@@ -327,6 +473,21 @@ export declare function createEditingTools(service: DashboardService, scope: Xpe
     expectedRevision: number;
     expectedCurrentVersionId: string | null;
     editId: string;
+    sourceMetadata?: {
+        bindingId: string;
+        title: string;
+        description?: string | undefined;
+    }[] | undefined;
+    components?: {
+        title: string;
+        id: string;
+        elementId: string;
+        kind: "filter" | "metric" | "chart" | "table" | "text";
+        sources: {
+            bindingId: string;
+            fieldIds?: string[] | undefined;
+        }[];
+    }[] | undefined;
     controls?: {
         type: "string" | "number" | "boolean" | "date";
         controlId: string;
@@ -336,16 +497,16 @@ export declare function createEditingTools(service: DashboardService, scope: Xpe
     }[] | undefined;
     charts?: {
         type: "bar" | "line" | "area" | "pie" | "scatter";
-        id: string;
         title: string;
+        id: string;
         datasetId: string;
         x: string;
         y: string;
         color?: string | undefined;
     }[] | undefined;
     tables?: {
-        id: string;
         title: string;
+        id: string;
         datasetId: string;
         fields: string[];
     }[] | undefined;
@@ -357,6 +518,7 @@ export declare function createEditingTools(service: DashboardService, scope: Xpe
         controlIds: string[];
         viewIds: string[];
         htmlElementIds: string[];
+        componentIds: string[];
     } | undefined;
     htmlPath?: string | undefined;
 }, {
@@ -364,6 +526,8 @@ export declare function createEditingTools(service: DashboardService, scope: Xpe
     expectedRevision: number;
     expectedCurrentVersionId: string | null;
     editId: string;
+    sourceMetadata?: unknown;
+    components?: unknown;
     controls?: unknown;
     charts?: unknown;
     tables?: unknown;
@@ -375,6 +539,7 @@ export declare function createEditingTools(service: DashboardService, scope: Xpe
         controlIds?: string[] | undefined;
         viewIds?: string[] | undefined;
         htmlElementIds?: string[] | undefined;
+        componentIds?: string[] | undefined;
     } | undefined;
     htmlPath?: string | undefined;
 }>, {
@@ -382,6 +547,21 @@ export declare function createEditingTools(service: DashboardService, scope: Xpe
     expectedRevision: number;
     expectedCurrentVersionId: string | null;
     editId: string;
+    sourceMetadata?: {
+        bindingId: string;
+        title: string;
+        description?: string | undefined;
+    }[] | undefined;
+    components?: {
+        title: string;
+        id: string;
+        elementId: string;
+        kind: "filter" | "metric" | "chart" | "table" | "text";
+        sources: {
+            bindingId: string;
+            fieldIds?: string[] | undefined;
+        }[];
+    }[] | undefined;
     controls?: {
         type: "string" | "number" | "boolean" | "date";
         controlId: string;
@@ -391,16 +571,16 @@ export declare function createEditingTools(service: DashboardService, scope: Xpe
     }[] | undefined;
     charts?: {
         type: "bar" | "line" | "area" | "pie" | "scatter";
-        id: string;
         title: string;
+        id: string;
         datasetId: string;
         x: string;
         y: string;
         color?: string | undefined;
     }[] | undefined;
     tables?: {
-        id: string;
         title: string;
+        id: string;
         datasetId: string;
         fields: string[];
     }[] | undefined;
@@ -412,6 +592,7 @@ export declare function createEditingTools(service: DashboardService, scope: Xpe
         controlIds: string[];
         viewIds: string[];
         htmlElementIds: string[];
+        componentIds: string[];
     } | undefined;
     htmlPath?: string | undefined;
 }, {
@@ -419,6 +600,8 @@ export declare function createEditingTools(service: DashboardService, scope: Xpe
     expectedRevision: number;
     expectedCurrentVersionId: string | null;
     editId: string;
+    sourceMetadata?: unknown;
+    components?: unknown;
     controls?: unknown;
     charts?: unknown;
     tables?: unknown;
@@ -430,6 +613,7 @@ export declare function createEditingTools(service: DashboardService, scope: Xpe
         controlIds?: string[] | undefined;
         viewIds?: string[] | undefined;
         htmlElementIds?: string[] | undefined;
+        componentIds?: string[] | undefined;
     } | undefined;
     htmlPath?: string | undefined;
 }, string>)[];

package/dist/lib/editing.js

@@ -23,9 +23,9 @@ exports.updateToolSchema = agent_schema_1.createToolSchema.omit({ creationIntent
     libraries: document_libraries_1.libraryRequestsSchema.optional().describe('Omit to preserve the saved dependency versions. Supply the complete desired library IDs to explicitly add, remove or upgrade bundled libraries.') }).strict();
 const readHtmlSchema = v3_1.z.object({ editId: v3_1.z.string().uuid(), versionId: v3_1.z.string().uuid().optional().describe('Only for historical inspection; copy readVersionId from dashboard_open.'), offset: v3_1.z.number().int().min(0).max(300000).default(0),
     length: v3_1.z.number().int().min(1).max(24000).default(16000) }).strict();
-exports.EDITING_GUIDANCE = `Opening or reading a dashboard does not modify it. A selection_required result is normal: show its message to the user and wait for an explicit selection; do not retry, infer a target from history, or create a replacement. Do not save an unchanged editing copy or reopen/update merely to confirm a successful save; use the mutation receipt. For existing dashboards, call dashboard_open first and inspect presentation.type. For standard dashboards, update definition fields directly: a rename needs only title, editId, expectedRevision and expectedCurrentVersionId. No HTML file exists; omit htmlPath and libraries. For HTML dashboards only, open prepares a unique editing copy at htmlPath. Read with sandbox_read_file. If a long HTML line is truncated, do not repeat the same read: use dashboard_read_html with editId and follow nextOffset until null to inspect the saved source, then apply exact replacements to htmlPath. Never replace a file with a truncated preview. Edit with sandbox_edit_file/multi_edit_file (sandbox_write_file is create-only), then call dashboard_update with that exact htmlPath and read revisions. If the user requests a rename, include the new title in this same update; editing the HTML heading alone does not rename the Artifact. Save each batch automatically without human confirmation. Files are not dashboard saves. Preserve Binding semantics, stable component IDs and dependency locks unless requested. Update arrays upsert by ID, preserving omitted components; removals must name explicitly requested deletions. HTML updates retain existing element IDs. For new HTML, assign stable IDs to every KPI, chart, detail table and filter. Read and patch the current file instead of rebuilding unrelated sections. On conflict retain the editing file, open the latest draft and reconcile; never silently overwrite. Historical versions are read-only references. All Agent saves are drafts; only the Workbench human publish action creates formal versions. Read the live-dashboard skill for the complete workflow.`;
+exports.EDITING_GUIDANCE = `Opening or reading a dashboard does not modify it. A selection_required result is normal: show its message to the user and wait for an explicit selection; do not retry, infer a target from history, or create a replacement. Do not save an unchanged editing copy or reopen/update merely to confirm a successful save; use the mutation receipt. For existing dashboards, call dashboard_open first and inspect presentation.type. For standard dashboards, update definition fields directly: a rename needs only title, editId, expectedRevision and expectedCurrentVersionId. No HTML file exists; omit htmlPath and libraries. For HTML dashboards only, open prepares a unique editing copy at htmlPath. Read with sandbox_read_file. If a long HTML line is truncated, do not repeat the same read: use dashboard_read_html with editId and follow nextOffset until null to inspect the saved source, then apply exact replacements to htmlPath. Never replace a file with a truncated preview. Edit with sandbox_edit_file/multi_edit_file (sandbox_write_file is create-only), then call dashboard_update with that exact htmlPath and read revisions. If the user requests a rename, include the new title in this same update; editing the HTML heading alone does not rename the Artifact. Save each batch automatically without human confirmation. Files are not dashboard saves. Preserve Binding semantics, stable component IDs and dependency locks unless requested. To add filters to an existing Binding, copy its complete dashboard_open.bindings[] entry, retain binding.id and existing parameters[].controlId, and call dashboard_preview_binding after changing payload/parameters/defaults. Binding ID is independent of output.datasetId; simplified dashboard_preview derives the ID from datasetId and can accidentally add a new Binding instead of updating the old one. Use the stable Binding ID in HTML query/subscribe calls. Submit every intended changed/new Binding previewId and matching controls with htmlPath in the same dashboard_update. Update arrays upsert by ID, preserving omitted components; removals must name explicitly requested deletions. On preflight failure, compare expected/requested Binding IDs, repair the HTML or previews, and retain all intended previewIds, controls, title and htmlPath when retrying. Dropping previewIds does not register new HTML queries. Do not remove an existing Binding merely to suppress validation. HTML updates retain existing element IDs. For new HTML, assign stable IDs to every KPI, chart, detail table and filter. Read and patch the current file instead of rebuilding unrelated sections. On conflict retain the editing file, open the latest draft and reconcile; never silently overwrite. Historical versions are read-only references. All Agent saves are drafts; only the Workbench human publish action creates formal versions. Read the live-dashboard skill for the complete workflow.`;
 /** Run-local read receipts carry planning versions; authorization and CAS remain in the domain service. */
-function createEditingTools(service, scope, context, resolvePreviews, validateFinal, onOpen = () => undefined, currentTarget = editing_session_1.selectionFromConfig) {
+function createEditingTools(service, scope, context, resolvePreviews, validateFinal, onOpen = () => undefined, currentTarget = editing_session_1.selectionFromConfig, saveRequests) {
     const target = (input, config) => {
         const selected = currentTarget(config);
         if (input.artifactId)
@@ -61,7 +61,7 @@ function createEditingTools(service, scope, context, resolvePreviews, validateFi
                     : { state: 'published', versionNumber: saved.versionNumber ?? 0, versionId: resolved.versionId }) }, config);
             return JSON.stringify({ resourceCard, editId, expectedCurrentVersionId: saved.baseVersionId ?? saved.versionId ?? null, ...(resolved.versionId ? { readVersionId: resolved.versionId } : {}), expectedRevision: saved.draftRevision ?? 0, state: saved.isDraft ? 'draft' : 'published', artifactId: saved.artifactId, versionId: saved.versionId, versionNumber: saved.versionNumber,
                 ...definition, presentation: presentation ? { type: 'html', characters: presentation.html.length, dependencies: presentation.dependencies ?? [] } : { type: 'standard' },
-                ...(resolved.versionId ? { next: 'Read-only published version. To edit, select the working draft in the Workbench version selector or explicitly open this Artifact without a versionId, then use its current draft revision. Publication requires a separate human action.' } : htmlPath ? { htmlPath, saveArguments: { editId, expectedRevision: saved.draftRevision ?? 0, expectedCurrentVersionId: saved.baseVersionId ?? saved.versionId ?? null, title: saved.manifest.title, htmlPath }, editingFile: { path: htmlPath, exists: true, hasUnsavedChanges: false, writeMode: 'edit_existing', read: { tool: 'sandbox_read_file', arguments: { file_path: htmlPath } } }, next: 'Opening only prepared a copy; it did not change the dashboard and requires no save. Call dashboard_update only after applying requested changes. Copy saveArguments, replacing title with the requested new name when renaming. expectedCurrentVersionId must remain actual JSON null or the returned UUID; never a string such as None. When repairing a failed update, retain all intended changes instead of dropping title. The editing file already exists: do not use sandbox_write_file on it. When renaming, include title and htmlPath together in one dashboard_update. A private editing copy is ready. Read it with sandbox_read_file. If long lines are truncated, use dashboard_read_html with editId and follow nextOffset until null instead of retrying file reads. This fallback reads the saved source; apply changes to htmlPath and never write a truncated preview. Edit with sandbox_edit_file/multi_edit_file, then save using dashboard_update with this htmlPath and the returned revisions. File edits alone do not save the dashboard.' } : !presentation ? { next: 'Standard dashboard: update definition fields directly. A rename requires only title plus editId, expectedRevision and expectedCurrentVersionId. No HTML editing file exists; omit htmlPath and libraries unless intentionally converting to HTML.' } : {}) });
+                ...(resolved.versionId ? { next: 'Read-only published version. To edit, select the working draft in the Workbench version selector or explicitly open this Artifact without a versionId, then use its current draft revision. Publication requires a separate human action.' } : htmlPath ? { htmlPath, saveArguments: { editId, expectedRevision: saved.draftRevision ?? 0, expectedCurrentVersionId: saved.baseVersionId ?? saved.versionId ?? null, title: saved.manifest.title, htmlPath }, editingFile: { path: htmlPath, exists: true, hasUnsavedChanges: false, writeMode: 'edit_existing', read: { tool: 'sandbox_read_file', arguments: { file_path: htmlPath } } }, next: 'Opening only prepared a copy; it did not change the dashboard and requires no save. Call dashboard_update only after applying requested changes. Copy saveArguments, replacing title with the requested new name when renaming. expectedCurrentVersionId must remain actual JSON null or the returned UUID; never a string such as None. When repairing a failed update, retain all intended previewIds, controls, title and htmlPath. For changed bindings, copy bindings[] and preserve binding.id via dashboard_preview_binding; omitted bindings remain saved. The editing file already exists: do not use sandbox_write_file on it. When renaming, include title and htmlPath together in one dashboard_update. A private editing copy is ready. Read it with sandbox_read_file. If long lines are truncated, use dashboard_read_html with editId and follow nextOffset until null instead of retrying file reads. This fallback reads the saved source; apply changes to htmlPath and never write a truncated preview. Edit with sandbox_edit_file/multi_edit_file, then save using dashboard_update with this htmlPath and the returned revisions. File edits alone do not save the dashboard.' } : !presentation ? { next: 'Standard dashboard: update definition fields directly. A rename requires only title plus editId, expectedRevision and expectedCurrentVersionId. No HTML editing file exists; omit htmlPath and libraries unless intentionally converting to HTML.' } : {}) });
         }, { name: 'dashboard_open', description: 'Read one authorized saved dashboard and obtain its stable editId and current draft revision. For a current HTML dashboard also prepares a unique Workspace editing copy without changing the Artifact. Historical versions remain read-only. Omit artifactId only for the selected Workbench dashboard.',
             schema: targetSchema, verboseParsingErrors: true, metadata: { toolName: { en_US: 'Read dashboard for editing', zh_Hans: '读取看板以继续修改' } } }),
         (0, tools_1.tool)(async (input) => {
@@ -89,6 +89,8 @@ function createEditingTools(service, scope, context, resolvePreviews, validateFi
             const changedBindings = previewIds ? resolvePreviews(previewIds) : undefined;
             const bindings = (0, editing_patch_1.upsertComponents)(saved.manifest.bindings, changedBindings, item => item.id, removals?.bindingIds);
             const controls = (0, editing_patch_1.upsertComponents)(saved.manifest.controls, changes.controls, item => item.controlId, removals?.controlIds);
+            const sourceMetadata = (0, editing_patch_1.upsertComponents)(saved.manifest.sourceMetadata ?? [], changes.sourceMetadata, item => item.bindingId, removals?.bindingIds.filter(id => saved.manifest.sourceMetadata?.some(item => item.bindingId === id)));
+            const components = (0, editing_patch_1.upsertComponents)(saved.manifest.components ?? [], changes.components, item => item.id, removals?.componentIds);
             if (removals?.viewIds.some(id => ![...saved.manifest.charts, ...saved.manifest.tables].some(view => view.id === id)))
                 throw new Error('DASHBOARD_REMOVAL_INVALID: copy existing view IDs');
             const charts = (0, editing_patch_1.upsertComponents)(saved.manifest.charts, changes.charts, item => item.id, removals?.viewIds.filter(id => saved.manifest.charts.some(item => item.id === id)));
@@ -114,8 +116,13 @@ function createEditingTools(service, scope, context, resolvePreviews, validateFi
             }
             (0, editing_patch_1.assertHtmlPreserved)(saved.manifest.presentation, presentation, removals?.htmlElementIds);
             const manifest = dashboard_schema_1.dashboardSchema.parse({ ...saved.manifest, ...changes, bindings, controls, charts, tables,
+                ...(sourceMetadata.length || saved.manifest.sourceMetadata ? { sourceMetadata } : {}), ...(components.length || saved.manifest.components ? { components } : {}),
                 ...(presentation ? { presentation } : {}) });
             validateFinal(manifest, previewIds !== undefined, changedBindings?.map(item => item.id));
+            if (saveRequests && manifest.bindings.length > 8) {
+                const key = (0, node_crypto_1.createHash)('sha256').update(JSON.stringify([editId, expectedRevision, expectedCurrentVersionId, manifest, sourceFile])).digest('hex');
+                return JSON.stringify(await saveRequests.submit(scope, manifest, expectedCurrentVersionId, expectedRevision, key, sourceFile));
+            }
             const { schema, id, ...update } = manifest;
             const result = await service.update(scope, editId, expectedRevision, update, expectedCurrentVersionId);
             const resourceCard = await (0, resource_card_1.emitDashboardCard)(scope, { ...result, state: 'draft', revision: result.draftRevision }, config);

package/dist/lib/filter-evidence.d.ts

@@ -1,6 +1,34 @@
 import { z } from 'zod/v3';
 import type { AnalyticsBinding, AnalyticsValue, XpertResolvedViewHostContext } from '@xpert-ai/contracts';
 import type { DashboardService } from './dashboard.service';
+export declare const filterTestSchema: z.ZodObject<{
+    previewId: z.ZodString;
+    controls: z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>, Record<string, string | number | boolean | null>, unknown>;
+    expectations: z.ZodEffects<z.ZodArray<z.ZodObject<{
+        fieldId: z.ZodString;
+        oneOf: z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>, "many">;
+    }, "strict", z.ZodTypeAny, {
+        fieldId: string;
+        oneOf: (string | number | boolean | null)[];
+    }, {
+        fieldId: string;
+        oneOf: (string | number | boolean | null)[];
+    }>, "many">, {
+        fieldId: string;
+        oneOf: (string | number | boolean | null)[];
+    }[], unknown>;
+}, "strict", z.ZodTypeAny, {
+    controls: Record<string, string | number | boolean | null>;
+    previewId: string;
+    expectations: {
+        fieldId: string;
+        oneOf: (string | number | boolean | null)[];
+    }[];
+}, {
+    previewId: string;
+    controls?: unknown;
+    expectations?: unknown;
+}>;
 /** Model quality evidence, not authorization: every query still goes through Analytics. */
 export declare function createFilterEvidence(service: DashboardService, scope: XpertResolvedViewHostContext, previews: Map<string, AnalyticsBinding>): {
     requirements(binding: AnalyticsBinding, previewId: string, rows: Record<string, AnalyticsValue>[]): {

package/dist/lib/filter-evidence.js

@@ -1,11 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.filterTestSchema = void 0;
 exports.createFilterEvidence = createFilterEvidence;
 const tools_1 = require("@langchain/core/tools");
 const v3_1 = require("zod/v3");
 const plugin_sdk_1 = require("@xpert-ai/plugin-sdk");
 const scalar = v3_1.z.union([v3_1.z.string().max(4000), v3_1.z.number().finite(), v3_1.z.boolean(), v3_1.z.null()]);
-const schema = v3_1.z.object({ previewId: v3_1.z.string().min(1),
+exports.filterTestSchema = v3_1.z.object({ previewId: v3_1.z.string().min(1),
     controls: (0, plugin_sdk_1.jsonEncodedSchema)(v3_1.z.record(scalar)),
     expectations: (0, plugin_sdk_1.jsonEncodedSchema)(v3_1.z.array(v3_1.z.object({ fieldId: v3_1.z.string().min(1), oneOf: v3_1.z.array(scalar).min(1).max(100) }).strict()).min(1).max(24))
 }).strict();
@@ -55,6 +56,6 @@ function createFilterEvidence(service, scope, previews) {
             checked.set(input.previewId, controls);
             return JSON.stringify({ previewId: input.previewId, passed: true, checkedControls: [...controls], remainingControls: required(binding, input.previewId).map(parameter => parameter.controlId), rows: dataset.rows.slice(0, 20), completeness: dataset.completeness });
         }, { name: 'dashboard_test_filter', description: 'Verify a previewed Binding with concrete filter values and expected field values. For a nullable dimension selector, test a real non-null value and expect every row of the matching field to equal it before saving. Does not change defaults. A failed check must be repaired before create/update.',
-            schema, verboseParsingErrors: true, metadata: { toolName: { en_US: 'Verify filter results', zh_Hans: '验证筛选结果' } } })
+            schema: exports.filterTestSchema, verboseParsingErrors: true, metadata: { toolName: { en_US: 'Verify filter results', zh_Hans: '验证筛选结果' } } })
     };
 }

package/dist/lib/html-guidance.d.ts

@@ -1 +1,2 @@
 export declare const HTML_DASHBOARD_GUIDANCE = "For free-layout HTML dashboards, read the installed live-dashboard skill's references/html-runtime.md through read_skill_file, relative to its SKILL.md path in the skill catalog. Create/edit the HTML with SandboxFile; then dashboard_create_html or dashboard_update validates and saves it. Do not use generic present_files to save or preview a live dashboard. Its preview belongs to the Live dashboards Workbench. Call dashboard_libraries for packaged ECharts/Three.js. Network access is temporarily unrestricted for functional acceptance. CDN scripts/styles/fonts, CSS imports, external images and fetch/XHR are available under browser CORS and mixed-content rules. Tailwind CDN is supported; do not remove styling to avoid network validation. Platform business data remains declarative Binding queries through window.xpertLiveArtifact; never embed credentials. The page MUST declare const live = window.xpertLiveArtifact in its script (live is not a host global), register live.subscribe(bindingId, render), await live.ready(), and invoke live.query(bindingId, typedControls) for initial data and filter changes. window.__datasets and window.__refresh are not platform APIs and are never populated by the host. Read the runtime reference and its html-lifecycle.md example before writing HTML; preserve that lifecycle while freely changing the layout. Use one complete Dataset for KPI, trend and details when they share the same metric and filters; do not create a redundant unfiltered total Binding. Never let filtered and unfiltered subscriptions both write the same KPI: a refresh would race and overwrite the selected-region total. Distinct global totals need distinct, clearly labeled elements. Native data selects require data-dashboard-control=\"<controlId>\"; purely visual selects use data-dashboard-presentation. A data filter must query, not only filter cached browser rows. bindSelect controls ONE binding only. For a shared dimension filter across multiple bindings, follow the skill custom-select example and query every affected binding with the same typed controls; matching control IDs do not broadcast automatically. bindSelect derives options from Dataset fields and is only for dimension filters. Fixed query enums (days, page size, granularity) need options from parameter.allowedValues and a typed change listener calling live.query; never use date rows as numeric day-count options.";
+export declare const HTML_QUERY_ROUNDS = "For a filter shared by multiple Bindings use await live.queryMany(affectedBindingIds, typedControls); render explicit failures from the returned {datasets, failures}. Successful subscriptions are delivered together after that round settles. Individual live.query calls retain independent delivery for legacy pages.";

package/dist/lib/html-guidance.js

@@ -1,4 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HTML_DASHBOARD_GUIDANCE = void 0;
+exports.HTML_QUERY_ROUNDS = exports.HTML_DASHBOARD_GUIDANCE = void 0;
 exports.HTML_DASHBOARD_GUIDANCE = `For free-layout HTML dashboards, read the installed live-dashboard skill's references/html-runtime.md through read_skill_file, relative to its SKILL.md path in the skill catalog. Create/edit the HTML with SandboxFile; then dashboard_create_html or dashboard_update validates and saves it. Do not use generic present_files to save or preview a live dashboard. Its preview belongs to the Live dashboards Workbench. Call dashboard_libraries for packaged ECharts/Three.js. Network access is temporarily unrestricted for functional acceptance. CDN scripts/styles/fonts, CSS imports, external images and fetch/XHR are available under browser CORS and mixed-content rules. Tailwind CDN is supported; do not remove styling to avoid network validation. Platform business data remains declarative Binding queries through window.xpertLiveArtifact; never embed credentials. The page MUST declare const live = window.xpertLiveArtifact in its script (live is not a host global), register live.subscribe(bindingId, render), await live.ready(), and invoke live.query(bindingId, typedControls) for initial data and filter changes. window.__datasets and window.__refresh are not platform APIs and are never populated by the host. Read the runtime reference and its html-lifecycle.md example before writing HTML; preserve that lifecycle while freely changing the layout. Use one complete Dataset for KPI, trend and details when they share the same metric and filters; do not create a redundant unfiltered total Binding. Never let filtered and unfiltered subscriptions both write the same KPI: a refresh would race and overwrite the selected-region total. Distinct global totals need distinct, clearly labeled elements. Native data selects require data-dashboard-control="<controlId>"; purely visual selects use data-dashboard-presentation. A data filter must query, not only filter cached browser rows. bindSelect controls ONE binding only. For a shared dimension filter across multiple bindings, follow the skill custom-select example and query every affected binding with the same typed controls; matching control IDs do not broadcast automatically. bindSelect derives options from Dataset fields and is only for dimension filters. Fixed query enums (days, page size, granularity) need options from parameter.allowedValues and a typed change listener calling live.query; never use date rows as numeric day-count options.`;
+exports.HTML_QUERY_ROUNDS = 'For a filter shared by multiple Bindings use await live.queryMany(affectedBindingIds, typedControls); render explicit failures from the returned {datasets, failures}. Successful subscriptions are delivered together after that round settles. Individual live.query calls retain independent delivery for legacy pages.';

package/dist/lib/html-validation-feedback.d.ts

@@ -0,0 +1,7 @@
+import { BadRequestException } from '@nestjs/common';
+import type { DashboardManifest } from './dashboard.schema';
+/** Report only binding identities observed by validation, never query payloads or returned rows. */
+export declare function htmlPreflightFailure(manifest: DashboardManifest, report: {
+    errors: string[];
+    requestedBindings: string[];
+}): BadRequestException;

package/dist/lib/html-validation-feedback.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.htmlPreflightFailure = htmlPreflightFailure;
+const common_1 = require("@nestjs/common");
+/** Report only binding identities observed by validation, never query payloads or returned rows. */
+function htmlPreflightFailure(manifest, report) {
+    const expectedBindingIds = manifest.bindings.map(binding => binding.id);
+    const requestedBindingIds = [...new Set(report.requestedBindings)];
+    const expected = new Set(expectedBindingIds), requested = new Set(requestedBindingIds);
+    const bindingDiagnostics = {
+        expectedBindingIds, requestedBindingIds,
+        missingQueryBindingIds: expectedBindingIds.filter(id => !requested.has(id)),
+        unexpectedQueryBindingIds: requestedBindingIds.filter(id => !expected.has(id))
+    };
+    const repair = 'Compare the candidate manifest Binding IDs with the HTML query/subscribe IDs. Requested IDs are observed calls, not a static list of every HTML reference. For an existing Binding, preserve dashboard_open.bindings[].id and preview its complete edited Binding with dashboard_preview_binding. Include all intended current-run previewIds, controls and htmlPath together in dashboard_update; omitted components remain saved. Add new Bindings only for new data needs; remove existing ones only for explicitly requested deletions. Repair other reported page errors before retrying. No dashboard was saved.';
+    // Some tool hosts retain only Error.message, so keep the bounded identity diagnostics there too.
+    return new common_1.BadRequestException({ code: 'DASHBOARD_HTML_PREFLIGHT_FAILED', errors: report.errors,
+        bindingDiagnostics, message: `DASHBOARD_HTML_PREFLIGHT_FAILED: ${JSON.stringify(report.errors)}. Binding diagnostics: ${JSON.stringify(bindingDiagnostics)}. ${repair}` });
+}