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

package/dist/lib/dashboard.service.d.ts

@@ -2,6 +2,7 @@ import type { AnalyticsValue, AnalyticsDiscoveryRequest, AnalyticsQueryRequest,
 import { type RuntimeCapabilityRegistry } from '@xpert-ai/plugin-sdk';
 import { type DashboardManifest, type DashboardChanges } from './dashboard.schema';
 import { HtmlDashboardValidation } from './html-validation';
+import type { DashboardAccess, DashboardMode } from './project';
 export declare const PLUGIN_NAME = "@xpert-ai/plugin-live-dashboard";
 export declare class DashboardService {
     private readonly runtime;
@@ -19,6 +20,37 @@ export declare class DashboardService {
         versionNumber: number | undefined;
         updatedAt: string | Date | undefined;
     }[]>;
+    access(context: XpertResolvedViewHostContext): Promise<DashboardAccess>;
+    listPage(context: XpertResolvedViewHostContext, page?: number, pageSize?: number): Promise<{
+        page: number;
+        pageSize: number;
+        hasMore: boolean;
+        items: {
+            title: string | null | undefined;
+            draftRevision?: number | undefined;
+            canDelete: boolean;
+            artifactId: string;
+            versionId: string | null | undefined;
+            versionNumber: number | undefined;
+            updatedAt: string | Date | undefined;
+        }[];
+    }>;
+    searchPage(context: XpertResolvedViewHostContext, input: {
+        search: string;
+        page: number;
+    }): Promise<{
+        items: {
+            title: string | null | undefined;
+            draftRevision?: number | undefined;
+            canDelete: boolean;
+            artifactId: string;
+            versionId: string | null | undefined;
+            versionNumber: number | undefined;
+            updatedAt: string | Date | undefined;
+        }[];
+        page: number;
+        hasMore: boolean;
+    }>;
     trash(context: XpertResolvedViewHostContext, artifactId: string, expectedRevision: number): Promise<{
         artifactId: string;
     }>;
@@ -30,7 +62,7 @@ export declare class DashboardService {
         status: "draft";
         title: string;
     }>;
-    open(context: XpertResolvedViewHostContext, artifactId: string, versionId?: string, draftRevision?: number): Promise<{
+    open(context: XpertResolvedViewHostContext, artifactId: string, versionId?: string, draftRevision?: number, mode?: DashboardMode): Promise<{
         manifest: {
             schema: "xpert.live-dashboard";
             id: string;
@@ -64,6 +96,7 @@ export declare class DashboardService {
                 dependencies?: import("@xpert-ai/plugin-sdk/artifact-document").ArtifactDocumentDependencyLock[] | undefined;
             } | undefined;
         };
+        contentHash: string;
         draftId?: string | undefined;
         draftRevision?: number | undefined;
         baseVersionId?: string | null | undefined;
@@ -75,7 +108,7 @@ export declare class DashboardService {
         versionNumber: number | undefined;
     }>;
     /** Trusted View transport only. Agent read tools receive locks, never megabytes of library code. */
-    openDocument(context: XpertResolvedViewHostContext, artifactId: string, versionId?: string, draftRevision?: number): Promise<{
+    openDocument(context: XpertResolvedViewHostContext, artifactId: string, versionId?: string, draftRevision?: number, mode?: DashboardMode): Promise<{
         manifest: {
             schema: "xpert.live-dashboard";
             id: string;
@@ -110,6 +143,7 @@ export declare class DashboardService {
             } | undefined;
         };
         dependencies: import("@xpert-ai/plugin-sdk/artifact-document").ArtifactDocumentDependencyAsset[];
+        contentHash: string;
         draftId?: string | undefined;
         draftRevision?: number | undefined;
         baseVersionId?: string | null | undefined;
@@ -142,6 +176,8 @@ export declare class DashboardService {
         versionNumber: number;
         title: string | null | undefined;
     }>;
+    validatePublication(context: XpertResolvedViewHostContext, artifactId: string, expectedRevision: number, expectedCurrentVersionId: string | null): Promise<void>;
+    private publishDraft;
     query(context: XpertResolvedViewHostContext, artifactId: string, versionId: string | undefined, controls: Record<string, AnalyticsValue>, draftRevision?: number): Promise<{
         payload?: {
             ok: boolean;
@@ -237,6 +273,7 @@ export declare class DashboardService {
                 dependencies?: import("@xpert-ai/plugin-sdk/artifact-document").ArtifactDocumentDependencyLock[] | undefined;
             } | undefined;
         };
+        contentHash: string;
         draftId?: string | undefined;
         draftRevision?: number | undefined;
         baseVersionId?: string | null | undefined;

package/dist/lib/dashboard.service.js

@@ -32,23 +32,49 @@ let DashboardService = class DashboardService {
         this.runtime = runtime;
         this.htmlValidation = htmlValidation;
     }
-    sources(context) { return this.runtime.require(plugin_sdk_1.AnalyticsRuntimeCapability).list(actor(context)); }
-    discover(context, input) { return this.runtime.require(plugin_sdk_1.AnalyticsRuntimeCapability).discover(actor(context), input); }
+    async sources(context) { await this.authorizeProject(context); return this.runtime.require(plugin_sdk_1.AnalyticsRuntimeCapability).list(actor(context)); }
+    async discover(context, input) { await this.authorizeProject(context); return this.runtime.require(plugin_sdk_1.AnalyticsRuntimeCapability).discover(actor(context), input); }
     async preview(context, input) {
+        await this.authorizeProject(context);
         const dataset = await this.runtime.require(plugin_sdk_1.AnalyticsRuntimeCapability).query(actor(context), input);
         await this.probeControls(context, input.binding, input.controls ?? {});
         return dataset;
     }
     async list(context) {
+        return (await this.listPage(context)).items;
+    }
+    async access(context) {
         const access = await this.authorizeProject(context);
-        const result = await this.runtime.require(plugin_sdk_1.ArtifactsRuntimeCapability).listArtifacts({ pluginName: exports.PLUGIN_NAME, resourceType: RESOURCE_TYPE, resourceIdPrefix: hostPrefix(context), status: 'active', pageSize: 100, includeCurrentVersion: true });
+        return { project: !!projectId(context), archived: access?.archived ?? false,
+            canReadDraft: !access || access.role !== 'member', canEdit: !access || !access.archived && access.role !== 'member',
+            canManage: !access || !access.archived && access.canManage };
+    }
+    async listPage(context, page = 1, pageSize = 50) {
+        const access = await this.access(context);
+        if (!Number.isSafeInteger(page) || page < 1 || !Number.isSafeInteger(pageSize) || pageSize < 1 || pageSize > 100)
+            throw new common_1.BadRequestException('DASHBOARD_INVALID_CURSOR');
+        const result = await this.runtime.require(plugin_sdk_1.ArtifactsRuntimeCapability).listArtifacts({ pluginName: exports.PLUGIN_NAME, resourceType: RESOURCE_TYPE, resourceIdPrefix: hostPrefix(context), status: 'active', page, pageSize, includeCurrentVersion: true });
         const items = result.items.filter((item) => item.resourceId.startsWith(hostPrefix(context)) && (item.userId === context.userId || !item.userId && item.projectId === projectId(context)));
-        const drafts = new Map((await this.runtime.require(plugin_sdk_1.ArtifactDraftsRuntimeCapability).list(items.map(item => item.id))).map(draft => [draft.artifactId, draft]));
-        return items.map(item => {
-            const draft = drafts.get(item.id);
-            return { ...summary(item), canDelete: !!draft && (!projectId(context) || access?.canManage === true),
-                ...(draft ? { title: draft.title ?? item.title, draftRevision: draft.revision } : {}) };
-        });
+        const drafts = new Map((access.canReadDraft ? await this.runtime.require(plugin_sdk_1.ArtifactDraftsRuntimeCapability).list(items.map(item => item.id)) : []).map(draft => [draft.artifactId, draft]));
+        return { page, pageSize, hasMore: page * pageSize < result.total, items: items.filter(item => access.canReadDraft || !!item.currentVersionId).map(item => {
+                const draft = drafts.get(item.id);
+                return { ...summary(item), canDelete: !!draft && access.canManage,
+                    ...(draft ? { title: draft.title ?? item.title, draftRevision: draft.revision } : {}) };
+            }) };
+    }
+    async searchPage(context, input) {
+        // Search the authorized display titles, including editor drafts. Filtering a stored
+        // Artifact title in the host would miss renamed drafts or expose them to members.
+        const pageSize = 20, offset = (input.page - 1) * pageSize;
+        const search = input.search.trim().toLocaleLowerCase();
+        const matches = [];
+        for (let page = 1;; page++) {
+            const batch = await this.listPage(context, page, 100);
+            matches.push(...batch.items.filter(item => `${item.title ?? ''} ${item.artifactId}`.toLocaleLowerCase().includes(search)));
+            if (!batch.hasMore || matches.length > offset + pageSize)
+                break;
+        }
+        return { items: matches.slice(offset, offset + pageSize), page: input.page, hasMore: matches.length > offset + pageSize };
     }
     async trash(context, artifactId, expectedRevision) {
         await this.authorizeProject(context, 'manage');
@@ -88,38 +114,30 @@ let DashboardService = class DashboardService {
         for (const binding of parsed.bindings)
             await this.probeControls(context, binding, Object.fromEntries(parsed.controls.filter((control) => control.defaultValue !== undefined).map((control) => [control.controlId, control.defaultValue ?? null])));
         const htmlValidation = await this.htmlValidation.validate(context, parsed, preview, dependencies);
-        const artifact = existing ?? await artifacts.createArtifact({ source, kind: 'file', title: parsed.title,
+        const artifact = existing ?? await artifacts.createArtifact({ source, type: { pluginName: exports.PLUGIN_NAME, resourceType: RESOURCE_TYPE }, kind: 'file', title: parsed.title,
             scope: { ...scopedActor, ...(projectId(context) ? { projectId: projectId(context), userId: null } : { xpertId: context.hostId }) } });
-        const files = this.runtime.require(plugin_sdk_1.WorkspaceFilesRuntimeCapability);
-        const project = projectId(context);
-        // Shared definitions live in the Project volume; private legacy dashboards retain their user volume.
-        const privateScope = { tenantId: scopedActor.tenantId, userId: scopedActor.userId, catalog: 'users' };
-        const reference = project
-            ? (await files.writeRuntimeBuffer({ tenantId: scopedActor.tenantId, userId: scopedActor.userId,
-                catalog: 'projects', scopeId: project, projectId: project, buffer, originalName: 'dashboard.json',
-                fileName: `${digest}.json`, folder: `.xpert/live-dashboards/${parsed.id}`, mimeType: MIME_TYPE })).reference
-            : await files.uploadBuffer({ ...privateScope, buffer, originalName: 'dashboard.json', fileName: `${digest}.json`,
-                folder: `live-dashboards/${parsed.id}`, mimeType: MIME_TYPE }).then(file => ({
-                source: 'platform.workspace.files', ...privateScope, filePath: file.filePath, workspacePath: file.workspacePath
-            }));
+        const reference = await this.runtime.require(plugin_sdk_1.ArtifactContentRuntimeCapability).write({ artifactId: artifact.id, buffer });
         const result = await this.runtime.require(plugin_sdk_1.ArtifactDraftsRuntimeCapability).save({ artifactId: artifact.id, expectedRevision,
             expectedCurrentVersionId: expectedVersionId, mimeType: MIME_TYPE, title: parsed.title, fileName: 'dashboard.json', sha256: digest,
             ...(htmlValidation ? { metadata: { htmlValidation } } : {}), workspaceFileRef: reference });
         return { artifactId: artifact.id, draftId: result.id, draftRevision: result.revision, baseVersionId: result.baseVersionId, status: 'draft', title: parsed.title };
     }
-    async open(context, artifactId, versionId, draftRevision) {
-        const { dependencies, ...saved } = await this.openDocument(context, artifactId, versionId, draftRevision);
+    async open(context, artifactId, versionId, draftRevision, mode = 'draft') {
+        const { dependencies, ...saved } = await this.openDocument(context, artifactId, versionId, draftRevision, mode);
         return saved;
     }
     /** Trusted View transport only. Agent read tools receive locks, never megabytes of library code. */
-    async openDocument(context, artifactId, versionId, draftRevision) {
-        await this.authorizeProject(context);
+    async openDocument(context, artifactId, versionId, draftRevision, mode = 'draft') {
+        const access = await this.access(context);
+        const readDraft = draftRevision !== undefined || !versionId && mode === 'draft';
+        if (readDraft && !access.canReadDraft)
+            throw new common_1.ForbiddenException('DASHBOARD_DRAFT_ACCESS_DENIED');
         const artifacts = this.runtime.require(plugin_sdk_1.ArtifactsRuntimeCapability);
         const artifact = await artifacts.getArtifact(artifactId);
         assertOwned(context, artifact);
         if (artifact.status !== 'active')
             throw new common_1.ForbiddenException('DASHBOARD_ARCHIVED');
-        const draft = !versionId || draftRevision !== undefined ? await this.runtime.require(plugin_sdk_1.ArtifactDraftsRuntimeCapability).get(artifactId) : null;
+        const draft = readDraft ? await this.runtime.require(plugin_sdk_1.ArtifactDraftsRuntimeCapability).get(artifactId) : null;
         if (draftRevision !== undefined && draft?.revision !== draftRevision)
             throw new common_1.ConflictException('DASHBOARD_DRAFT_CONFLICT');
         const version = draft ?? (versionId ? (await artifacts.listArtifactVersions({ artifactId, status: 'active' })).find((item) => item.id === versionId) : artifact.currentVersion);
@@ -135,7 +153,7 @@ let DashboardService = class DashboardService {
             throw new common_1.BadRequestException('DASHBOARD_IDENTITY_MISMATCH');
         return { ...summary(artifact, 'versionNumber' in version ? version : undefined),
             ...(draft ? { draftId: draft.id, draftRevision: draft.revision, baseVersionId: draft.baseVersionId,
-                isDraft: draft.revision !== draft.publishedRevision, title: draft.title, updatedAt: draft.updatedAt } : {}), manifest, dependencies };
+                isDraft: draft.revision !== draft.publishedRevision, title: draft.title, updatedAt: draft.updatedAt } : {}), manifest, dependencies, contentHash: version.sha256 };
     }
     async history(context, artifactId) {
         await this.authorizeProject(context);
@@ -156,6 +174,9 @@ let DashboardService = class DashboardService {
     }
     async publish(context, artifactId, expectedRevision, expectedCurrentVersionId) {
         await this.authorizeProject(context, 'manage');
+        return this.publishDraft(context, artifactId, expectedRevision, expectedCurrentVersionId);
+    }
+    async validatePublication(context, artifactId, expectedRevision, expectedCurrentVersionId) {
         const saved = await this.open(context, artifactId, undefined, expectedRevision);
         if (!saved.manifest.bindings.length)
             throw new common_1.BadRequestException('DASHBOARD_CONFIGURE_BEFORE_PUBLISHING');
@@ -167,6 +188,9 @@ let DashboardService = class DashboardService {
         }
         // Revalidate current source access and bindings before publishing the exact reviewed bytes.
         await this.execute(context, saved.manifest, {});
+    }
+    async publishDraft(context, artifactId, expectedRevision, expectedCurrentVersionId) {
+        await this.validatePublication(context, artifactId, expectedRevision, expectedCurrentVersionId);
         const version = await this.runtime.require(plugin_sdk_1.ArtifactDraftsRuntimeCapability).publish({ artifactId, expectedRevision, expectedCurrentVersionId });
         return { artifactId, versionId: version.id, versionNumber: version.versionNumber, title: version.title };
     }

package/dist/lib/document-libraries.d.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod/v3';
 import { type ArtifactDocumentDependencyAsset, type ArtifactDocumentDependencyLock } from '@xpert-ai/plugin-sdk/artifact-document';
 /** The plugin owns its catalog. The platform owns verification and isolated execution. */
-export declare const libraryRequestsSchema: z.ZodEffects<z.ZodArray<z.ZodEnum<["echarts", "three"]>, "many">, ("echarts" | "three")[], ("echarts" | "three")[]>;
+export declare const libraryRequestsSchema: 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")[]>;
 export type LibraryRequests = z.output<typeof libraryRequestsSchema>;
 export declare function bundledLibraries(): Promise<ArtifactDocumentDependencyAsset[]>;
 export declare function libraryLocks(ids: LibraryRequests): Promise<ArtifactDocumentDependencyLock[]>;

package/dist/lib/document-libraries.js

@@ -9,8 +9,9 @@ const node_path_1 = require("node:path");
 const v3_1 = require("zod/v3");
 const artifact_document_1 = require("@xpert-ai/plugin-sdk/artifact-document");
 /** The plugin owns its catalog. The platform owns verification and isolated execution. */
-exports.libraryRequestsSchema = v3_1.z.array(v3_1.z.enum(['echarts', 'three'])).max(2)
-    .refine(ids => new Set(ids).size === ids.length, 'Duplicate library');
+exports.libraryRequestsSchema = v3_1.z.array(v3_1.z.enum(['echarts', 'three', 'trend-workspace', 'profit-atlas', 'customer-brief'])).max(3)
+    .refine(ids => new Set(ids).size === ids.length, 'Duplicate library')
+    .refine(ids => ids.filter(id => ['trend-workspace', 'profit-atlas', 'customer-brief'].includes(id)).length <= 1, 'Choose one dashboard visual theme');
 async function bundledLibraries() {
     return (0, artifact_document_1.verifyArtifactDocumentDependencies)(JSON.parse(await (0, promises_1.readFile)((0, node_path_1.join)(__dirname, '../libraries/catalog.json'), 'utf8')));
 }

package/dist/lib/document-network.d.ts

@@ -1,3 +1,3 @@
 import type { ArtifactDocumentNetworkPolicy } from '@xpert-ai/plugin-sdk/artifact-document';
-/** Trusted plugin policy, shared by the displayed document and browser preflight. */
+/** Temporary functional acceptance policy, shared by preview and viewing. */
 export declare const DASHBOARD_NETWORK_POLICY: ArtifactDocumentNetworkPolicy;

package/dist/lib/document-network.js

@@ -1,9 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DASHBOARD_NETWORK_POLICY = void 0;
-/** Trusted plugin policy, shared by the displayed document and browser preflight. */
-exports.DASHBOARD_NETWORK_POLICY = {
-    scripts: ['https://cdn.tailwindcss.com', 'https://cdn.jsdelivr.net', 'https://cdnjs.cloudflare.com', 'https://unpkg.com'],
-    styles: ['https://cdn.jsdelivr.net', 'https://cdnjs.cloudflare.com', 'https://unpkg.com', 'https://fonts.googleapis.com'],
-    fonts: ['https://cdn.jsdelivr.net', 'https://cdnjs.cloudflare.com', 'https://unpkg.com', 'https://fonts.gstatic.com']
-};
+/** Temporary functional acceptance policy, shared by preview and viewing. */
+exports.DASHBOARD_NETWORK_POLICY = { mode: 'unrestricted' };

package/dist/lib/editing-feedback.d.ts

@@ -0,0 +1,5 @@
+/** Missing selection is a normal interaction outcome; no Artifact operation is attempted. */
+export declare function dashboardSelectionRequired(config: unknown): {
+    status: "selection_required";
+    message: "Please select a dashboard to edit first." | "请先选择要编辑的看板" | "請先選擇要編輯的看板";
+};

package/dist/lib/editing-feedback.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dashboardSelectionRequired = dashboardSelectionRequired;
+const plugin_sdk_1 = require("@xpert-ai/plugin-sdk");
+const v3_1 = require("zod/v3");
+const messages = {
+    en: 'Please select a dashboard to edit first.',
+    'zh-Hans': '请先选择要编辑的看板',
+    'zh-Hant': '請先選擇要編輯的看板'
+};
+const languageConfig = v3_1.z.object({ configurable: v3_1.z.object({ language: v3_1.z.string().optional() }).optional() });
+/** Missing selection is a normal interaction outcome; no Artifact operation is attempted. */
+function dashboardSelectionRequired(config) {
+    const parsed = languageConfig.safeParse(config);
+    const language = (parsed.success ? parsed.data.configurable?.language : undefined) ?? plugin_sdk_1.RequestContext.getLanguageCode();
+    const locale = language.toLowerCase().replaceAll('_', '-');
+    const key = ['zh-hant', 'zh-tw', 'zh-hk', 'zh-mo'].includes(locale) ? 'zh-Hant' : locale === 'zh' || locale.startsWith('zh-') ? 'zh-Hans' : 'en';
+    return { status: 'selection_required', message: messages[key] };
+}

package/dist/lib/editing-patch.d.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod/v3';
+import type { DashboardManifest } from './dashboard.schema';
+export declare const removalsSchema: 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;
+}>>;
+export declare function upsertComponents<T>(existing: T[], changes: T[] | undefined, id: (item: T) => string, removed?: string[]): T[];
+export declare function htmlElementIds(html: string): Set<string>;
+/** IDs are an explicit preservation contract, not a semantic comparison of arbitrary HTML. */
+export declare function assertHtmlPreserved(previous: DashboardManifest['presentation'], next: DashboardManifest['presentation'], removed?: string[]): void;

package/dist/lib/editing-patch.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.removalsSchema = void 0;
+exports.upsertComponents = upsertComponents;
+exports.htmlElementIds = htmlElementIds;
+exports.assertHtmlPreserved = assertHtmlPreserved;
+const parse5_1 = require("parse5");
+const v3_1 = require("zod/v3");
+exports.removalsSchema = v3_1.z.object({
+    bindingIds: v3_1.z.array(v3_1.z.string()).max(8).default([]), controlIds: v3_1.z.array(v3_1.z.string()).max(24).default([]),
+    viewIds: v3_1.z.array(v3_1.z.string()).max(40).default([]), htmlElementIds: v3_1.z.array(v3_1.z.string()).max(500).default([])
+}).strict().optional().describe('Only explicitly requested removals. Arrays of changed components otherwise upsert by stable ID and preserve omitted components.');
+function upsertComponents(existing, changes, id, removed = []) {
+    if (new Set(changes?.map(id)).size !== (changes?.length ?? 0))
+        throw new Error('DASHBOARD_DUPLICATE_COMPONENT');
+    if (removed.some(key => !existing.some(item => id(item) === key) || changes?.some(item => id(item) === key)))
+        throw new Error('DASHBOARD_REMOVAL_INVALID: copy existing IDs and do not also update a removed component');
+    const next = new Map(existing.filter(item => !removed.includes(id(item))).map(item => [id(item), item]));
+    for (const item of changes ?? [])
+        next.set(id(item), item);
+    return [...next.values()];
+}
+function htmlElementIds(html) {
+    const ids = new Set();
+    const visit = (node) => {
+        if ('attrs' in node)
+            for (const attr of node.attrs)
+                if (attr.name === 'id' && attr.value)
+                    ids.add(attr.value);
+        if ('childNodes' in node)
+            node.childNodes.forEach(visit);
+        if ('content' in node)
+            visit(node.content);
+    };
+    visit((0, parse5_1.parse)(html));
+    return ids;
+}
+/** IDs are an explicit preservation contract, not a semantic comparison of arbitrary HTML. */
+function assertHtmlPreserved(previous, next, removed = []) {
+    if (!previous || !next || previous.html === next.html)
+        return;
+    const before = htmlElementIds(previous.html), after = htmlElementIds(next.html);
+    const missing = [...before].filter(id => !after.has(id) && !removed.includes(id));
+    if (missing.length)
+        throw new Error(`DASHBOARD_COMPONENT_REMOVAL_REQUIRED: preserve existing HTML IDs or explicitly declare user-requested removals: ${JSON.stringify(missing)}. Your editing file is retained.`);
+}

package/dist/lib/editing-session.d.ts

@@ -0,0 +1,167 @@
+import { z } from 'zod/v3';
+import type { IAgentMiddlewareContext } from '@xpert-ai/plugin-sdk';
+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.ZodUnion<[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;
+    }>, z.ZodObject<{
+        schemaVersion: z.ZodLiteral<1>;
+        mode: z.ZodLiteral<"new">;
+    }, "strict", z.ZodTypeAny, {
+        mode: "new";
+        schemaVersion: 1;
+    }, {
+        mode: "new";
+        schemaVersion: 1;
+    }>]>>>;
+}, "strip", z.ZodTypeAny, {
+    live_dashboard?: {
+        artifactId: string;
+        schemaVersion: 1;
+        versionId?: string | undefined;
+        draftRevision?: number | undefined;
+    } | {
+        mode: "new";
+        schemaVersion: 1;
+    } | null | undefined;
+}, {
+    live_dashboard?: {
+        artifactId: string;
+        schemaVersion: 1;
+        versionId?: string | undefined;
+        draftRevision?: number | undefined;
+    } | {
+        mode: "new";
+        schemaVersion: 1;
+    } | null | undefined;
+}>;
+export type DashboardSelection = z.infer<typeof dashboardSelectionSchema>;
+export declare const dashboardStateSchema: z.ZodObject<{
+    dashboardEditing: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        scope: z.ZodString;
+        target: 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, {
+        target: {
+            artifactId: string;
+            schemaVersion: 1;
+            versionId?: string | undefined;
+            draftRevision?: number | undefined;
+        } | null;
+        scope: string;
+    }, {
+        target: {
+            artifactId: string;
+            schemaVersion: 1;
+            versionId?: string | undefined;
+            draftRevision?: number | undefined;
+        } | null;
+        scope: string;
+    }>>>;
+}, "strip", z.ZodTypeAny, {
+    dashboardEditing?: {
+        target: {
+            artifactId: string;
+            schemaVersion: 1;
+            versionId?: string | undefined;
+            draftRevision?: number | undefined;
+        } | null;
+        scope: string;
+    } | null | undefined;
+}, {
+    dashboardEditing?: {
+        target: {
+            artifactId: string;
+            schemaVersion: 1;
+            versionId?: string | undefined;
+            draftRevision?: number | undefined;
+        } | null;
+        scope: string;
+    } | null | undefined;
+}>;
+/** Checkpoints belong to an actor and conversation. Copied state must never choose another user's target. */
+export declare function editingSession(context: IAgentMiddlewareContext): {
+    current: () => {
+        artifactId: string;
+        schemaVersion: 1;
+        versionId?: string | undefined;
+        draftRevision?: number | undefined;
+    } | null;
+    resolve(config: unknown): {
+        artifactId: string;
+        schemaVersion: 1;
+        versionId?: string | undefined;
+        draftRevision?: number | undefined;
+    } | null;
+    restore(state: unknown, requestContext: unknown): {
+        dashboardEditing: {
+            scope: string;
+            target: {
+                artifactId: string;
+                schemaVersion: 1;
+                versionId?: string | undefined;
+                draftRevision?: number | undefined;
+            } | null;
+        };
+    };
+    select(target: DashboardSelection | null): {
+        dashboardEditing: {
+            scope: string;
+            target: {
+                artifactId: string;
+                schemaVersion: 1;
+                versionId?: string | undefined;
+                draftRevision?: number | undefined;
+            } | null;
+        };
+    };
+};
+export declare function selectionFromContext(value: unknown): DashboardSelection | null | undefined;
+export declare function selectionFromConfig(value: unknown): {
+    artifactId: string;
+    schemaVersion: 1;
+    versionId?: string | undefined;
+    draftRevision?: number | undefined;
+} | null | undefined;

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