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

package/dist/lib/editing-session.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dashboardStateSchema = exports.dashboardContextSchema = exports.dashboardSelectionSchema = void 0;
+exports.editingSession = editingSession;
+exports.selectionFromContext = selectionFromContext;
+exports.selectionFromConfig = selectionFromConfig;
+const v3_1 = require("zod/v3");
+exports.dashboardSelectionSchema = v3_1.z.object({ schemaVersion: v3_1.z.literal(1), artifactId: v3_1.z.string().uuid(),
+    versionId: v3_1.z.string().uuid().optional(), draftRevision: v3_1.z.number().int().positive().optional() }).strict();
+const newSelection = v3_1.z.object({ schemaVersion: v3_1.z.literal(1), mode: v3_1.z.literal('new') }).strict();
+exports.dashboardContextSchema = v3_1.z.object({ live_dashboard: v3_1.z.union([exports.dashboardSelectionSchema, newSelection]).nullable().optional() });
+exports.dashboardStateSchema = v3_1.z.object({ dashboardEditing: v3_1.z.object({
+        scope: v3_1.z.string(), target: exports.dashboardSelectionSchema.nullable()
+    }).nullable().optional() });
+/** Checkpoints belong to an actor and conversation. Copied state must never choose another user's target. */
+function editingSession(context) {
+    const scope = JSON.stringify([context.tenantId, context.organizationId, context.userId, context.xpertId,
+        context.projectId, context.conversationId, context.threadId, context.agentKey]);
+    let active = null;
+    let initialized = false;
+    return {
+        current: () => active,
+        resolve(config) { return initialized ? active : selectionFromConfig(config) ?? active; },
+        restore(state, requestContext) {
+            const persisted = exports.dashboardStateSchema.safeParse(state);
+            const selected = selectionFromContext(requestContext);
+            active = selected !== undefined ? selected : persisted.success && persisted.data.dashboardEditing?.scope === scope
+                ? persisted.data.dashboardEditing.target : null;
+            initialized = true;
+            return { dashboardEditing: { scope, target: active } };
+        },
+        select(target) { active = target; initialized = true; return { dashboardEditing: { scope, target } }; }
+    };
+}
+function selectionFromContext(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const parsed = exports.dashboardContextSchema.safeParse(value);
+    if (!parsed.success)
+        throw new Error('DASHBOARD_SELECTION_INVALID: select the dashboard again before editing');
+    if (parsed.data.live_dashboard === undefined)
+        return undefined;
+    const selected = parsed.data.live_dashboard;
+    return selected && 'artifactId' in selected ? selected : null;
+}
+function selectionFromConfig(value) {
+    const config = v3_1.z.object({ context: v3_1.z.unknown(),
+        configurable: v3_1.z.object({ context: v3_1.z.unknown() }).optional() }).safeParse(value);
+    if (!config.success)
+        return undefined;
+    const primary = selectionFromContext(config.data.context);
+    return primary !== undefined ? primary : selectionFromContext(config.data.configurable?.context);
+}

package/dist/lib/editing.d.ts

@@ -3,56 +3,9 @@ import type { AnalyticsBinding, XpertResolvedViewHostContext } from '@xpert-ai/c
 import { type IAgentMiddlewareContext } from '@xpert-ai/plugin-sdk';
 import { type DashboardManifest } from './dashboard.schema';
 import { DashboardService } from './dashboard.service';
-export declare const dashboardSelectionSchema: z.ZodObject<{
-    schemaVersion: z.ZodLiteral<1>;
-    artifactId: z.ZodString;
-    versionId: z.ZodOptional<z.ZodString>;
-    draftRevision: z.ZodOptional<z.ZodNumber>;
-}, "strict", z.ZodTypeAny, {
-    artifactId: string;
-    schemaVersion: 1;
-    versionId?: string | undefined;
-    draftRevision?: number | undefined;
-}, {
-    artifactId: string;
-    schemaVersion: 1;
-    versionId?: string | undefined;
-    draftRevision?: number | undefined;
-}>;
-export declare const dashboardContextSchema: z.ZodObject<{
-    live_dashboard: z.ZodOptional<z.ZodNullable<z.ZodObject<{
-        schemaVersion: z.ZodLiteral<1>;
-        artifactId: z.ZodString;
-        versionId: z.ZodOptional<z.ZodString>;
-        draftRevision: z.ZodOptional<z.ZodNumber>;
-    }, "strict", z.ZodTypeAny, {
-        artifactId: string;
-        schemaVersion: 1;
-        versionId?: string | undefined;
-        draftRevision?: number | undefined;
-    }, {
-        artifactId: string;
-        schemaVersion: 1;
-        versionId?: string | undefined;
-        draftRevision?: number | undefined;
-    }>>>;
-}, "strip", z.ZodTypeAny, {
-    live_dashboard?: {
-        artifactId: string;
-        schemaVersion: 1;
-        versionId?: string | undefined;
-        draftRevision?: number | undefined;
-    } | null | undefined;
-}, {
-    live_dashboard?: {
-        artifactId: string;
-        schemaVersion: 1;
-        versionId?: string | undefined;
-        draftRevision?: number | undefined;
-    } | null | undefined;
-}>;
+import { type DashboardSelection } from './editing-session';
+export { dashboardSelectionSchema, dashboardContextSchema } from './editing-session';
 export declare const updateToolSchema: z.ZodObject<{
-    supersedesPaths: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>>;
     controls: z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodObject<{
         controlId: z.ZodString;
         type: z.ZodEnum<["string", "number", "boolean", "date"]>;
@@ -133,14 +86,31 @@ export declare const updateToolSchema: z.ZodObject<{
         datasetId: string;
         fields: string[];
     }[], unknown>>;
+    supersedesPaths: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>>;
     previewIds: z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], unknown>>;
 } & {
+    removals: z.ZodOptional<z.ZodObject<{
+        bindingIds: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        controlIds: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        viewIds: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        htmlElementIds: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        bindingIds: string[];
+        controlIds: string[];
+        viewIds: string[];
+        htmlElementIds: string[];
+    }, {
+        bindingIds?: string[] | undefined;
+        controlIds?: string[] | undefined;
+        viewIds?: string[] | undefined;
+        htmlElementIds?: string[] | undefined;
+    }>>;
     title: z.ZodString;
     editId: z.ZodString;
     expectedRevision: z.ZodNumber;
     expectedCurrentVersionId: z.ZodNullable<z.ZodString>;
     htmlPath: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>;
-    libraries: z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodEnum<["echarts", "three"]>, "many">, ("echarts" | "three")[], ("echarts" | "three")[]>>;
+    libraries: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodEnum<["echarts", "three", "trend-workspace", "profit-atlas", "customer-brief"]>, "many">, ("echarts" | "three" | "trend-workspace" | "profit-atlas" | "customer-brief")[], ("echarts" | "three" | "trend-workspace" | "profit-atlas" | "customer-brief")[]>, ("echarts" | "three" | "trend-workspace" | "profit-atlas" | "customer-brief")[], ("echarts" | "three" | "trend-workspace" | "profit-atlas" | "customer-brief")[]>>;
 }, "strict", z.ZodTypeAny, {
     title: string;
     expectedRevision: number;
@@ -170,7 +140,13 @@ export declare const updateToolSchema: z.ZodObject<{
     }[] | undefined;
     supersedesPaths?: string[] | undefined;
     previewIds?: string[] | undefined;
-    libraries?: ("echarts" | "three")[] | undefined;
+    libraries?: ("echarts" | "three" | "trend-workspace" | "profit-atlas" | "customer-brief")[] | undefined;
+    removals?: {
+        bindingIds: string[];
+        controlIds: string[];
+        viewIds: string[];
+        htmlElementIds: string[];
+    } | undefined;
     htmlPath?: string | undefined;
 }, {
     title: string;
@@ -182,12 +158,28 @@ export declare const updateToolSchema: z.ZodObject<{
     tables?: unknown;
     supersedesPaths?: string[] | undefined;
     previewIds?: unknown;
-    libraries?: ("echarts" | "three")[] | undefined;
+    libraries?: ("echarts" | "three" | "trend-workspace" | "profit-atlas" | "customer-brief")[] | undefined;
+    removals?: {
+        bindingIds?: string[] | undefined;
+        controlIds?: string[] | undefined;
+        viewIds?: string[] | undefined;
+        htmlElementIds?: string[] | undefined;
+    } | undefined;
     htmlPath?: string | undefined;
 }>;
-export declare const EDITING_GUIDANCE = "Opening or reading a dashboard does not modify it. 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; 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 and dependency locks unless requested. 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. 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.";
 /** 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) => void, onOpen?: (path: string, artifactId: string) => void): (import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>, {}, {}, string> | 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): (import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+    page: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    page: number;
+}, {
+    page?: number | undefined;
+}>, {
+    page: number;
+}, {
+    page?: number | undefined;
+}, string> | import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
     editId: z.ZodString;
     versionId: z.ZodOptional<z.ZodString>;
     offset: z.ZodDefault<z.ZodNumber>;
@@ -225,7 +217,6 @@ export declare function createEditingTools(service: DashboardService, scope: Xpe
 }, {
     artifactId?: string | undefined;
 }, string> | import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
-    supersedesPaths: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>>;
     controls: z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodObject<{
         controlId: z.ZodString;
         type: z.ZodEnum<["string", "number", "boolean", "date"]>;
@@ -306,14 +297,31 @@ export declare function createEditingTools(service: DashboardService, scope: Xpe
         datasetId: string;
         fields: string[];
     }[], unknown>>;
+    supersedesPaths: z.ZodOptional<z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>>;
     previewIds: z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], unknown>>;
 } & {
+    removals: z.ZodOptional<z.ZodObject<{
+        bindingIds: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        controlIds: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        viewIds: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        htmlElementIds: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        bindingIds: string[];
+        controlIds: string[];
+        viewIds: string[];
+        htmlElementIds: string[];
+    }, {
+        bindingIds?: string[] | undefined;
+        controlIds?: string[] | undefined;
+        viewIds?: string[] | undefined;
+        htmlElementIds?: string[] | undefined;
+    }>>;
     title: z.ZodString;
     editId: z.ZodString;
     expectedRevision: z.ZodNumber;
     expectedCurrentVersionId: z.ZodNullable<z.ZodString>;
     htmlPath: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>;
-    libraries: z.ZodOptional<z.ZodEffects<z.ZodArray<z.ZodEnum<["echarts", "three"]>, "many">, ("echarts" | "three")[], ("echarts" | "three")[]>>;
+    libraries: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodEnum<["echarts", "three", "trend-workspace", "profit-atlas", "customer-brief"]>, "many">, ("echarts" | "three" | "trend-workspace" | "profit-atlas" | "customer-brief")[], ("echarts" | "three" | "trend-workspace" | "profit-atlas" | "customer-brief")[]>, ("echarts" | "three" | "trend-workspace" | "profit-atlas" | "customer-brief")[], ("echarts" | "three" | "trend-workspace" | "profit-atlas" | "customer-brief")[]>>;
 }, "strict", z.ZodTypeAny, {
     title: string;
     expectedRevision: number;
@@ -343,7 +351,13 @@ export declare function createEditingTools(service: DashboardService, scope: Xpe
     }[] | undefined;
     supersedesPaths?: string[] | undefined;
     previewIds?: string[] | undefined;
-    libraries?: ("echarts" | "three")[] | undefined;
+    libraries?: ("echarts" | "three" | "trend-workspace" | "profit-atlas" | "customer-brief")[] | undefined;
+    removals?: {
+        bindingIds: string[];
+        controlIds: string[];
+        viewIds: string[];
+        htmlElementIds: string[];
+    } | undefined;
     htmlPath?: string | undefined;
 }, {
     title: string;
@@ -355,7 +369,13 @@ export declare function createEditingTools(service: DashboardService, scope: Xpe
     tables?: unknown;
     supersedesPaths?: string[] | undefined;
     previewIds?: unknown;
-    libraries?: ("echarts" | "three")[] | undefined;
+    libraries?: ("echarts" | "three" | "trend-workspace" | "profit-atlas" | "customer-brief")[] | undefined;
+    removals?: {
+        bindingIds?: string[] | undefined;
+        controlIds?: string[] | undefined;
+        viewIds?: string[] | undefined;
+        htmlElementIds?: string[] | undefined;
+    } | undefined;
     htmlPath?: string | undefined;
 }>, {
     title: string;
@@ -386,7 +406,13 @@ export declare function createEditingTools(service: DashboardService, scope: Xpe
     }[] | undefined;
     supersedesPaths?: string[] | undefined;
     previewIds?: string[] | undefined;
-    libraries?: ("echarts" | "three")[] | undefined;
+    libraries?: ("echarts" | "three" | "trend-workspace" | "profit-atlas" | "customer-brief")[] | undefined;
+    removals?: {
+        bindingIds: string[];
+        controlIds: string[];
+        viewIds: string[];
+        htmlElementIds: string[];
+    } | undefined;
     htmlPath?: string | undefined;
 }, {
     title: string;
@@ -398,6 +424,12 @@ export declare function createEditingTools(service: DashboardService, scope: Xpe
     tables?: unknown;
     supersedesPaths?: string[] | undefined;
     previewIds?: unknown;
-    libraries?: ("echarts" | "three")[] | undefined;
+    libraries?: ("echarts" | "three" | "trend-workspace" | "profit-atlas" | "customer-brief")[] | undefined;
+    removals?: {
+        bindingIds?: string[] | undefined;
+        controlIds?: string[] | undefined;
+        viewIds?: string[] | undefined;
+        htmlElementIds?: string[] | undefined;
+    } | undefined;
     htmlPath?: string | undefined;
 }, string>)[];

package/dist/lib/editing.js

@@ -11,36 +11,39 @@ const agent_schema_1 = require("./agent.schema");
 const dashboard_schema_1 = require("./dashboard.schema");
 const document_libraries_1 = require("./document-libraries");
 const resource_card_1 = require("./resource-card");
-exports.dashboardSelectionSchema = v3_1.z.object({ schemaVersion: v3_1.z.literal(1), artifactId: v3_1.z.string().uuid(), versionId: v3_1.z.string().uuid().optional(), draftRevision: v3_1.z.number().int().positive().optional() }).strict();
-exports.dashboardContextSchema = v3_1.z.object({ live_dashboard: exports.dashboardSelectionSchema.nullable().optional() });
-const configSchema = v3_1.z.object({ context: exports.dashboardContextSchema.optional(), configurable: v3_1.z.object({ context: exports.dashboardContextSchema.optional() }).optional() });
+const editing_session_1 = require("./editing-session");
+const editing_patch_1 = require("./editing-patch");
+const editing_feedback_1 = require("./editing-feedback");
+var editing_session_2 = require("./editing-session");
+Object.defineProperty(exports, "dashboardSelectionSchema", { enumerable: true, get: function () { return editing_session_2.dashboardSelectionSchema; } });
+Object.defineProperty(exports, "dashboardContextSchema", { enumerable: true, get: function () { return editing_session_2.dashboardContextSchema; } });
 const targetSchema = v3_1.z.object({ artifactId: v3_1.z.string().uuid().optional().describe('From dashboard_list or a saved receipt. Omit only for the current Workbench selection.'),
     versionId: v3_1.z.string().uuid().optional().describe('Exact historical version when requested. Otherwise open the selected or current version.') }).strict();
-exports.updateToolSchema = agent_schema_1.createToolSchema.partial().extend({ title: agent_schema_1.createToolSchema.shape.title.describe('Required saved Artifact title. Use the requested new title when renaming; otherwise copy the current title from dashboard_open. Submit it together with htmlPath when changing the page.'), editId: v3_1.z.string().uuid().describe("Stable Artifact ID returned by dashboard_open"), expectedRevision: v3_1.z.number().int().nonnegative().describe('Copy the current draft revision returned by dashboard_open.'), expectedCurrentVersionId: v3_1.z.string().uuid({ message: 'Copy the exact UUID from dashboard_open, or use JSON null when no formal version exists. Never use the strings None, null or an empty string.' }).nullable().describe('Copy dashboard_open.expectedCurrentVersionId exactly: UUID or actual JSON null. Never the strings None/null. Keep all requested changes (including title) when correcting another field.'), htmlPath: agent_schema_1.htmlPathSchema.optional(),
+exports.updateToolSchema = agent_schema_1.createToolSchema.omit({ creationIntent: true }).partial().extend({ removals: editing_patch_1.removalsSchema, title: agent_schema_1.createToolSchema.shape.title.describe('Required saved Artifact title. Use the requested new title when renaming; otherwise copy the current title from dashboard_open. Submit it together with htmlPath when changing the page.'), editId: v3_1.z.string().uuid().describe("Stable Artifact ID returned by dashboard_open"), expectedRevision: v3_1.z.number().int().nonnegative().describe('Copy the current draft revision returned by dashboard_open.'), expectedCurrentVersionId: v3_1.z.string().uuid({ message: 'Copy the exact UUID from dashboard_open, or use JSON null when no formal version exists. Never use the strings None, null or an empty string.' }).nullable().describe('Copy dashboard_open.expectedCurrentVersionId exactly: UUID or actual JSON null. Never the strings None/null. Keep all requested changes (including title) when correcting another field.'), htmlPath: agent_schema_1.htmlPathSchema.optional(),
     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. 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; 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 and dependency locks unless requested. 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. 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.`;
 /** Run-local read receipts carry planning versions; authorization and CAS remain in the domain service. */
-function createEditingTools(service, scope, context, resolvePreviews, validateFinal, onOpen = () => undefined) {
+function createEditingTools(service, scope, context, resolvePreviews, validateFinal, onOpen = () => undefined, currentTarget = editing_session_1.selectionFromConfig) {
     const target = (input, config) => {
-        const parsed = configSchema.safeParse(config);
-        // LangGraph can provide a top-level execution context alongside the request context.
-        // An unrelated (or schema-stripped empty) execution context must not mask the selection.
-        const selected = parsed.success ? parsed.data.context?.live_dashboard !== undefined
-            ? parsed.data.context.live_dashboard : parsed.data.configurable?.context?.live_dashboard : undefined;
+        const selected = currentTarget(config);
         if (input.artifactId)
             return { artifactId: input.artifactId, versionId: input.versionId };
         if (!selected)
-            throw new Error('DASHBOARD_TARGET_REQUIRED: select a dashboard in Workbench or use dashboard_list and provide its artifactId');
-        return { artifactId: selected.artifactId, versionId: input.versionId };
+            return null;
+        return { artifactId: selected.artifactId,
+            versionId: input.versionId ?? (selected.draftRevision === undefined ? selected.versionId : undefined) };
     };
     return [
-        (0, tools_1.tool)(async () => JSON.stringify({ dashboards: await service.list(scope) }), { name: 'dashboard_list',
-            description: 'List saved dashboards in the current authorized host. Use returned IDs to open one; do not infer a target from recency.',
-            schema: v3_1.z.object({}).strict(), verboseParsingErrors: true, metadata: { toolName: { en_US: 'List saved dashboards', zh_Hans: '查找已保存看板' } } }),
+        (0, tools_1.tool)(async ({ page }) => { const result = await service.listPage(scope, page, 50); return JSON.stringify({ dashboards: result.items, page: result.page, hasMore: result.hasMore }); }, { name: 'dashboard_list',
+            description: 'List saved dashboards in the current authorized host. Follow page and hasMore for the full list. Use returned IDs to open one; do not infer a target from recency.',
+            schema: v3_1.z.object({ page: v3_1.z.number().int().positive().default(1) }).strict(), verboseParsingErrors: true, metadata: { toolName: { en_US: 'List saved dashboards', zh_Hans: '查找已保存看板' } } }),
         (0, tools_1.tool)(async (input, config) => {
-            const resolved = target(input, config), saved = await service.open(scope, resolved.artifactId, resolved.versionId);
+            const resolved = target(input, config);
+            if (!resolved)
+                return JSON.stringify((0, editing_feedback_1.dashboardSelectionRequired)(config));
+            const saved = await service.open(scope, resolved.artifactId, resolved.versionId);
             const editId = saved.artifactId;
             const { presentation, schema, id, ...definition } = saved.manifest;
             let htmlPath;
@@ -58,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' },
-                ...(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, 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 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.' } : {}) });
         }, { 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) => {
@@ -75,13 +78,21 @@ function createEditingTools(service, scope, context, resolvePreviews, validateFi
             schema: readHtmlSchema, verboseParsingErrors: true, metadata: { toolName: { en_US: 'Read dashboard HTML', zh_Hans: '读取看板页面源码' } } }),
         (0, tools_1.tool)(async (input, config) => {
             const resolved = target(input, config);
+            if (!resolved)
+                return JSON.stringify((0, editing_feedback_1.dashboardSelectionRequired)(config));
             return JSON.stringify({ artifactId: resolved.artifactId, versions: await service.history(scope, resolved.artifactId) });
         }, { name: 'dashboard_history', description: 'List immutable versions of an authorized dashboard. Open a returned version to inspect it; history does not change the current version.',
             schema: targetSchema.omit({ versionId: true }), verboseParsingErrors: true, metadata: { toolName: { en_US: 'Read dashboard history', zh_Hans: '查看看板版本历史' } } }),
         (0, tools_1.tool)(async (input, config) => {
             const saved = await service.open(scope, input.editId);
-            const { editId, expectedRevision, expectedCurrentVersionId, htmlPath, previewIds, libraries, ...changes } = input;
-            const bindings = previewIds ? resolvePreviews(previewIds) : saved.manifest.bindings;
+            const { editId, expectedRevision, expectedCurrentVersionId, htmlPath, previewIds, libraries, removals, ...changes } = input;
+            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);
+            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)));
+            const tables = (0, editing_patch_1.upsertComponents)(saved.manifest.tables, changes.tables, item => item.id, removals?.viewIds.filter(id => saved.manifest.tables.some(item => item.id === id)));
             let presentation = saved.manifest.presentation;
             let sourceFile;
             if (htmlPath) {
@@ -101,14 +112,15 @@ function createEditingTools(service, scope, context, resolvePreviews, validateFi
                     throw new Error('DASHBOARD_HTML_REQUIRED');
                 presentation = { ...presentation, dependencies: await (0, document_libraries_1.libraryLocks)(libraries) };
             }
-            const manifest = dashboard_schema_1.dashboardSchema.parse({ ...saved.manifest, ...changes, bindings,
-                ...(presentation ? { presentation, charts: changes.charts ?? [], tables: changes.tables ?? [] } : {}) });
-            validateFinal(manifest, previewIds !== undefined);
+            (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,
+                ...(presentation ? { presentation } : {}) });
+            validateFinal(manifest, previewIds !== undefined, changedBindings?.map(item => item.id));
             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);
             return JSON.stringify({ dashboard: result, resourceCard, ...(sourceFile ? { sourceFile } : {}) });
-        }, { name: 'dashboard_update', description: 'Update the opened dashboard in place, preserving its Artifact ID and version history. Supply stable editId and expectedRevision from dashboard_open, the explicit current or requested title, plus only other changed fields. Saves a persistent draft; does not publish. For an HTML rename, send title and htmlPath together; HTML headings do not rename the Artifact. htmlPath replaces the page; omitted previewIds preserves bindings, while supplied previewIds replaces the complete set with successful fresh previews. Conflicting edits fail instead of overwriting.',
+        }, { name: 'dashboard_update', description: 'Update the opened dashboard in place, preserving its Artifact ID and version history. Supply stable editId and expectedRevision from dashboard_open, the explicit current or requested title, plus only other changed fields. Saves a persistent draft; does not publish. For an HTML rename, send title and htmlPath together; HTML headings do not rename the Artifact. htmlPath replaces the page; omitted previewIds preserves bindings, while supplied previewIds upserts changed bindings by stable ID. Controls/charts/tables also upsert by ID. Use removals only for explicitly requested deletions. Preserve HTML IDs unless their removal is requested. Conflicting edits fail instead of overwriting.',
             schema: exports.updateToolSchema, verboseParsingErrors: true, metadata: { toolName: { en_US: 'Save dashboard changes', zh_Hans: '保存看板修改' } } })
     ];
 }

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

@@ -1 +1 @@
-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 and the allowed HTTPS origins for online scripts, stylesheets and fonts. Tailwind CDN is supported through script src; pin a version when possible. Online resource failures must be repaired before saving. Do not add online URLs to the packaged libraries array; all data access remains declarative Binding queries through window.xpertLiveArtifact. 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_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.";

package/dist/lib/html-guidance.js

@@ -1,4 +1,4 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 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 and the allowed HTTPS origins for online scripts, stylesheets and fonts. Tailwind CDN is supported through script src; pin a version when possible. Online resource failures must be repaired before saving. Do not add online URLs to the packaged libraries array; all data access remains declarative Binding queries through window.xpertLiveArtifact. 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_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.`;