@xpert-ai/plugin-live-dashboard 0.4.0 → 0.5.0

package/dist/lib/editing.d.ts

@@ -6,6 +6,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"]>;
@@ -41,25 +101,25 @@ export declare const updateToolSchema: z.ZodObject<{
         y: z.ZodString;
         color: z.ZodOptional<z.ZodString>;
     }, "strict", z.ZodTypeAny, {
+        title: string;
         type: "bar" | "line" | "area" | "pie" | "scatter";
         id: string;
-        title: string;
         datasetId: string;
         x: string;
         y: string;
         color?: string | undefined;
     }, {
+        title: string;
         type: "bar" | "line" | "area" | "pie" | "scatter";
         id: string;
-        title: string;
         datasetId: string;
         x: string;
         y: string;
         color?: string | undefined;
     }>, "many">, {
+        title: string;
         type: "bar" | "line" | "area" | "pie" | "scatter";
         id: string;
-        title: string;
         datasetId: string;
         x: string;
         y: string;
@@ -71,18 +131,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 +154,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 +179,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;
@@ -124,17 +202,17 @@ export declare const updateToolSchema: z.ZodObject<{
         allowedValues?: (string | number | boolean | null)[] | undefined;
     }[] | undefined;
     charts?: {
+        title: string;
         type: "bar" | "line" | "area" | "pie" | "scatter";
         id: string;
-        title: 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 +224,7 @@ export declare const updateToolSchema: z.ZodObject<{
         controlIds: string[];
         viewIds: string[];
         htmlElementIds: string[];
+        componentIds: string[];
     } | undefined;
     htmlPath?: string | undefined;
 }, {
@@ -153,6 +232,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,10 +245,11 @@ 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<{
     page: z.ZodDefault<z.ZodNumber>;
@@ -217,6 +299,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"]>;
@@ -252,25 +394,25 @@ export declare function createEditingTools(service: DashboardService, scope: Xpe
         y: z.ZodString;
         color: z.ZodOptional<z.ZodString>;
     }, "strict", z.ZodTypeAny, {
+        title: string;
         type: "bar" | "line" | "area" | "pie" | "scatter";
         id: string;
-        title: string;
         datasetId: string;
         x: string;
         y: string;
         color?: string | undefined;
     }, {
+        title: string;
         type: "bar" | "line" | "area" | "pie" | "scatter";
         id: string;
-        title: string;
         datasetId: string;
         x: string;
         y: string;
         color?: string | undefined;
     }>, "many">, {
+        title: string;
         type: "bar" | "line" | "area" | "pie" | "scatter";
         id: string;
-        title: string;
         datasetId: string;
         x: string;
         y: string;
@@ -282,18 +424,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 +447,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 +472,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;
@@ -335,17 +495,17 @@ export declare function createEditingTools(service: DashboardService, scope: Xpe
         allowedValues?: (string | number | boolean | null)[] | undefined;
     }[] | undefined;
     charts?: {
+        title: string;
         type: "bar" | "line" | "area" | "pie" | "scatter";
         id: string;
-        title: 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 +517,7 @@ export declare function createEditingTools(service: DashboardService, scope: Xpe
         controlIds: string[];
         viewIds: string[];
         htmlElementIds: string[];
+        componentIds: string[];
     } | undefined;
     htmlPath?: string | undefined;
 }, {
@@ -364,6 +525,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 +538,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 +546,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;
@@ -390,17 +569,17 @@ export declare function createEditingTools(service: DashboardService, scope: Xpe
         allowedValues?: (string | number | boolean | null)[] | undefined;
     }[] | undefined;
     charts?: {
+        title: string;
         type: "bar" | "line" | "area" | "pie" | "scatter";
         id: string;
-        title: 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 +591,7 @@ export declare function createEditingTools(service: DashboardService, scope: Xpe
         controlIds: string[];
         viewIds: string[];
         htmlElementIds: string[];
+        componentIds: string[];
     } | undefined;
     htmlPath?: string | undefined;
 }, {
@@ -419,6 +599,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 +612,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,7 +23,7 @@ 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) {
     const target = (input, config) => {
@@ -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,6 +116,7 @@ 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));
             const { schema, id, ...update } = manifest;

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}` });
+}

package/dist/lib/html-validation.js

@@ -19,6 +19,7 @@ const promises_1 = require("node:timers/promises");
 const v3_1 = require("zod/v3");
 const plugin_sdk_1 = require("@xpert-ai/plugin-sdk");
 const artifact_document_1 = require("@xpert-ai/plugin-sdk/artifact-document");
+const html_validation_feedback_1 = require("./html-validation-feedback");
 const PLUGIN = '@xpert-ai/plugin-live-dashboard', ACTION = 'live_dashboard.validate-html', POOL = 'sandbox-browser';
 const reportSchema = v3_1.z.object({ ok: v3_1.z.boolean(), errors: v3_1.z.array(v3_1.z.string().max(300)).max(16),
     requestedBindings: v3_1.z.array(v3_1.z.string().max(80)).max(60), renderedTextLength: v3_1.z.number().int().nonnegative() }).strict();
@@ -70,7 +71,7 @@ let HtmlDashboardValidation = class HtmlDashboardValidation {
                     const report = reportSchema.parse(JSON.parse(await redis.get(`${key}:report`) ?? 'null'));
                     finished = true;
                     if (!report.ok)
-                        throw new common_1.BadRequestException(`DASHBOARD_HTML_PREFLIGHT_FAILED: ${JSON.stringify(report.errors)}. Repair the Workspace HTML or include every required previewId, then retry. No dashboard was saved.`);
+                        throw (0, html_validation_feedback_1.htmlPreflightFailure)(manifest, report);
                     return { jobId, requestedBindings: report.requestedBindings, status: 'passed' };
                 }
                 await (0, promises_1.setTimeout)(250);

package/dist/lib/inspection-host.d.ts

@@ -0,0 +1,7 @@
+import { type DashboardComponent } from './dashboard-sources';
+/** One frame generation, one nonce; inspection is UI metadata and grants no query authority. */
+export declare function createDashboardInspector(frame: HTMLIFrameElement, components: DashboardComponent[], onSelect: (id: string | null) => void, onExit: () => void, standard?: boolean): {
+    prefix: string;
+    setEnabled(value: boolean): void;
+    dispose(): void;
+};

package/dist/lib/inspection-host.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDashboardInspector = createDashboardInspector;
+const v3_1 = require("zod/v3");
+const inspection_runtime_1 = require("./inspection-runtime");
+const dashboard_sources_1 = require("./dashboard-sources");
+const message = v3_1.z.discriminatedUnion('type', [
+    v3_1.z.object({ channel: v3_1.z.literal('live-dashboard.inspection'), key: v3_1.z.string(), type: v3_1.z.literal('ready') }).strict(),
+    v3_1.z.object({ channel: v3_1.z.literal('live-dashboard.inspection'), key: v3_1.z.string(), type: v3_1.z.literal('exit') }).strict(),
+    v3_1.z.object({ channel: v3_1.z.literal('live-dashboard.inspection'), key: v3_1.z.string(), type: v3_1.z.literal('selected'), componentId: dashboard_sources_1.componentId.nullable() }).strict()
+]);
+/** One frame generation, one nonce; inspection is UI metadata and grants no query authority. */
+function createDashboardInspector(frame, components, onSelect, onExit, standard = false) {
+    const key = Array.from(crypto.getRandomValues(new Uint8Array(16)), byte => byte.toString(16).padStart(2, '0')).join('');
+    const host = frame.ownerDocument.defaultView;
+    let connected = false, enabled = false, disposed = false;
+    const send = () => {
+        if (connected && !disposed)
+            frame.contentWindow?.postMessage({ channel: 'live-dashboard.inspection', key, type: 'mode', enabled,
+                standard, components: components.map(({ id, elementId }) => ({ id, elementId })) }, '*');
+    };
+    const receive = (event) => {
+        if (disposed || event.source !== frame.contentWindow)
+            return;
+        const parsed = message.safeParse(event.data);
+        if (!parsed.success || parsed.data.key !== key)
+            return;
+        if (parsed.data.type === 'ready') {
+            connected = true;
+            send();
+        }
+        else if (parsed.data.type === 'exit') {
+            enabled = false;
+            onExit();
+        }
+        else {
+            const selected = parsed.data.componentId;
+            if (enabled && (selected === null || components.some(item => item.id === selected)))
+                onSelect(selected);
+        }
+    };
+    host.addEventListener('message', receive);
+    return {
+        prefix: `<script>${inspection_runtime_1.DASHBOARD_INSPECTION_RUNTIME.replace('__INSPECTION_SESSION__', key)}</script>`,
+        setEnabled(value) { enabled = value; send(); },
+        dispose() { enabled = false; send(); disposed = true; host.removeEventListener('message', receive); }
+    };
+}

package/dist/lib/inspection-runtime.d.ts

@@ -0,0 +1,2 @@
+/** Injected into the isolated dashboard only; it never reads or executes query definitions. */
+export declare const DASHBOARD_INSPECTION_RUNTIME: string;