@salesforce/metadata-visualizer-web 1.0.1

package/dist/WebVisualizationEngine.js

@@ -0,0 +1,284 @@
+/**
+ * Copyright (c) 2025, Salesforce, Inc.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ **/
+import { WebviewMessageType, ErrorCategory } from '@salesforce/metadata-core-sdk';
+import { injectBootstrap } from './internal/htmlPipeline.js';
+import { inlineAssets } from './internal/assetInliner.js';
+import { BROWSER_IFRAME_BOOTSTRAP } from './internal/constants.js';
+/**
+ * Browser/HTTP platform adapter for the visualization framework.
+ * Provides methods to generate self-contained HTML bundles and parse metadata
+ * for embedding in iframes. All methods are safe to call concurrently.
+ */
+export class WebVisualizationEngine {
+    /**
+     * Construct an engine.
+     *
+     * **Use `createWebVisualizationEngine()` instead.** This constructor is exposed
+     * only for the factory and internal tests, and it asserts an ownership contract
+     * that is easy to misuse:
+     *
+     * - The injected `framework` (and its `ErrorManager`) is **owned** by the
+     *   resulting engine. Calling `dispose()` tears it down — including any error
+     *   listeners registered by other code on the same instance.
+     * - Therefore the framework must be dedicated to this engine. Sharing one
+     *   `VisualizationEngine` between a `WebVisualizationEngine` and another
+     *   adapter (e.g. the VS Code adapter) will break the other adapter when this
+     *   engine is disposed.
+     *
+     * @internal
+     */
+    constructor(deps) {
+        /** Tracks whether dispose() has been called to prevent use-after-dispose */
+        this.disposed = false;
+        /** Per-file monotonic counter for fileId. Date.now() collides under sub-ms concurrent calls. */
+        this.fileIdCounters = new Map();
+        this.framework = deps.framework;
+        this.pluginManager = deps.pluginManager;
+        this.assetReader = deps.pluginAssetReader;
+    }
+    /**
+     * Generate a complete HTML bundle for a plugin's visualization UI.
+     * Returns a self-contained HTML file with all assets (JS, CSS, platform styles) inlined,
+     * ready to be embedded in an iframe. No metadata parsing occurs — this generates the static UI shell.
+     *
+     * @param pluginId - ID of the registered plugin to generate bundle for
+     * @returns Object containing the bundle (null if failed) and error (null if successful)
+     *
+     * @example
+     * ```typescript
+     * const { bundle, error } = await engine.visualizeMetadata('flexipage-visualizer');
+     * if (error) {
+     *   console.error('Bundle generation failed:', error.message);
+     *   res.status(error.category === 'Configuration' ? 404 : 500).json({ error: error.message });
+     * } else if (bundle) {
+     *   res.type(bundle.contentType).send(bundle.body);
+     * }
+     * ```
+     */
+    async visualizeMetadata(pluginId) {
+        this.assertNotDisposed();
+        // Fail fast on invalid plugin IDs to avoid downstream errors
+        if (!pluginId || pluginId.trim().length === 0) {
+            return {
+                bundle: null,
+                error: {
+                    message: 'pluginId is null or empty',
+                    category: ErrorCategory.Validation,
+                },
+            };
+        }
+        // Verify plugin is registered before attempting asset read
+        if (!this.requireKnownPlugin(pluginId)) {
+            return {
+                bundle: null,
+                error: {
+                    message: `No plugin found for pluginId: ${pluginId}`,
+                    category: ErrorCategory.Configuration,
+                },
+            };
+        }
+        try {
+            // Build self-contained HTML bundle: inline all assets to eliminate external requests
+            let html = await this.assetReader.readPluginIndexHtml(pluginId);
+            const platformCss = await this.assetReader.readDesignSystemCss();
+            html = await inlineAssets(html, pluginId, this.assetReader, platformCss);
+            // Bootstrap script enables host-plugin postMessage communication
+            html = injectBootstrap(html, BROWSER_IFRAME_BOOTSTRAP);
+            return {
+                bundle: {
+                    contentType: 'text/html; charset=utf-8',
+                    body: html,
+                    // Bundle is the static plugin UI shell only (no per-user / per-org data —
+                    // that flows separately via getParsedMetadata + postMessage). The shell is
+                    // an immutable build artifact keyed by pluginId, safe to share across users
+                    // and cache for a day. `immutable` lets clients skip revalidation entirely.
+                    cacheControl: 'public, max-age=86400, immutable',
+                },
+                error: null,
+            };
+        }
+        catch (err) {
+            // Asset reading or inlining failed (missing plugin files, corrupt assets, etc.)
+            return {
+                bundle: null,
+                error: {
+                    message: err instanceof Error ? err.message : 'Failed to generate bundle',
+                    category: ErrorCategory.Runtime,
+                    context: { pluginId: pluginId },
+                    stackTrace: err instanceof Error ? err.stack : undefined,
+                },
+            };
+        }
+    }
+    /**
+     * Parse a metadata file and return the visualization outcome.
+     * Finds the appropriate plugin by file pattern, parses the file, and returns structured data.
+     * Handles error capturing for concurrent-safe execution (multiple calls won't interfere).
+     *
+     * @param metadataFilePath - Path to the metadata file to parse
+     * @returns VisualizeOutcome containing either parsed result or error
+     *
+     * @example
+     * ```typescript
+     * const outcome = await engine.getParsedMetadata('force-app/main/default/flexipages/Home.flexipage');
+     * if (outcome.error) {
+     *   console.error('Parse failed:', outcome.error.message);
+     * } else {
+     *   console.log('Parsed data:', outcome.result.data);
+     * }
+     * ```
+     */
+    async getParsedMetadata(metadataFilePath) {
+        this.assertNotDisposed();
+        // Fail fast on invalid paths to avoid downstream parsing errors
+        if (!metadataFilePath || metadataFilePath.trim().length === 0) {
+            return {
+                result: null,
+                error: {
+                    message: 'Invalid file path',
+                    category: ErrorCategory.Validation,
+                },
+            };
+        }
+        const errorManager = this.framework.getErrorManager();
+        const invocationId = globalThis.crypto.randomUUID();
+        let captured = null;
+        // Per-invocation filter ensures this listener only sees errors reported by
+        // our own visualize() call, even when other requests run concurrently.
+        const unsubscribe = errorManager.onErrorReported((err) => {
+            captured = err;
+        }, { invocationId });
+        try {
+            const result = await this.framework.visualize(metadataFilePath, invocationId);
+            return {
+                result,
+                error: result ? null : captured,
+            };
+        }
+        finally {
+            unsubscribe();
+        }
+    }
+    /**
+     * Parse metadata and generate an update message for posting to an existing plugin iframe.
+     * Use this when file content changes and you need to push updates to a loaded iframe
+     * without regenerating the entire bundle. Plugins receive updates via onDataUpdate().
+     *
+     * @param metadataFilePath - Path to the metadata file to parse
+     * @returns Object containing error (if any) and pluginDataUpdateMessage (null if parsing failed)
+     *
+     * @example
+     * ```typescript
+     * // File watcher integration
+     * watcher.on('change', async (filePath) => {
+     *   const { error, pluginDataUpdateMessage } = await engine.getUpdatedParsedMetadata(filePath);
+     *   if (pluginDataUpdateMessage) {
+     *     iframeWindow.postMessage(pluginDataUpdateMessage, '*');
+     *   }
+     * });
+     * ```
+     */
+    async getUpdatedParsedMetadata(metadataFilePath) {
+        this.assertNotDisposed();
+        // Delegates to getParsedMetadata for validation and parsing, then wraps result as update message
+        const outcome = await this.getParsedMetadata(metadataFilePath);
+        const pluginDataUpdateMessage = this.createDataUpdateMessage(outcome);
+        return { error: outcome.error, pluginDataUpdateMessage };
+    }
+    /**
+     * Release all resources held by the engine.
+     * After calling this method, the engine instance should not be used.
+     * Safe to call multiple times (idempotent).
+     *
+     * **Disposes the underlying framework.** The engine takes ownership of the
+     * `VisualizationEngine` passed to its constructor (or built by the factory),
+     * including its `ErrorManager`. Do not share that framework with another
+     * adapter — it will be torn down here.
+     *
+     * @example
+     * ```typescript
+     * process.on('SIGTERM', () => {
+     *   engine.dispose();
+     *   process.exit(0);
+     * });
+     * ```
+     */
+    dispose() {
+        if (this.disposed) {
+            return;
+        }
+        this.disposed = true;
+        this.fileIdCounters.clear();
+        // Framework owns the ErrorManager and disposes it as part of framework.dispose().
+        this.framework.dispose();
+    }
+    /**
+     * Create a PLUGIN_DATA_UPDATE message for posting to a loaded plugin iframe.
+     * Per-file monotonic counter guarantees a unique, ordered fileId per update,
+     * even under sub-millisecond concurrent calls (Date.now() can collide).
+     *
+     * @param outcome - Visualization outcome with parsed data
+     * @returns Message ready to be posted via iframe.contentWindow.postMessage(), or null if parsing failed
+     */
+    createDataUpdateMessage(outcome) {
+        if (!outcome.result) {
+            return null;
+        }
+        // Extract filename from full path (plugins often display just the filename, not full path)
+        const fileName = outcome.result.filePath.split('/').pop() || outcome.result.filePath;
+        const nextSeq = (this.fileIdCounters.get(outcome.result.filePath) ?? 0) + 1;
+        this.fileIdCounters.set(outcome.result.filePath, nextSeq);
+        return {
+            type: WebviewMessageType.PLUGIN_DATA_UPDATE,
+            payload: {
+                data: outcome.result.data,
+                context: {
+                    filePath: outcome.result.filePath,
+                    fileName: fileName,
+                },
+                fileId: `${outcome.result.filePath}@${nextSeq}`,
+            },
+        };
+    }
+    /**
+     * Find the registered plugin that handles a given file.
+     * Matches file against plugin patterns (e.g., *.flexipage, *.object, *-meta.xml).
+     *
+     * @param metadataFile - Filename (e.g., 'Home.flexipage') or full path to match
+     * @returns PluginInfo if a matching plugin is found, null otherwise
+     */
+    getPlugin(metadataFile) {
+        const match = this.pluginManager.findVisualizerPluginForFile(metadataFile);
+        return match ? toPluginInfo(match.metadata) : null;
+    }
+    /**
+     * Verify a plugin is registered before attempting to use it.
+     * Prevents asset read failures for non-existent plugins.
+     */
+    requireKnownPlugin(pluginId) {
+        return this.pluginManager.getAllVisualizerPlugins().some((p) => p.metadata.id === pluginId);
+    }
+    /** Guards against use-after-dispose by throwing an error */
+    assertNotDisposed() {
+        if (this.disposed) {
+            throw new Error('WebVisualizationEngine has been disposed');
+        }
+    }
+}
+/**
+ * Convert framework plugin metadata to web adapter's PluginInfo format.
+ * Renames 'name' to 'displayName' for consistency with HTTP API conventions.
+ */
+function toPluginInfo(meta) {
+    return {
+        id: meta.id,
+        displayName: meta.name,
+        filePatterns: meta.filePatterns ?? [],
+        priority: meta.priority,
+    };
+}
+//# sourceMappingURL=WebVisualizationEngine.js.map

package/dist/WebVisualizationEngine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebVisualizationEngine.js","sourceRoot":"","sources":["../src/WebVisualizationEngine.ts"],"names":[],"mappings":"AAAA;;;;;IAKI;AAGJ,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAElF,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AAmBnE;;;;GAIG;AACH,MAAM,OAAO,sBAAsB;IASjC;;;;;;;;;;;;;;;;OAgBG;IACH,YAAY,IAAgC;QAtB5C,4EAA4E;QACpE,aAAQ,GAAG,KAAK,CAAC;QACzB,gGAAgG;QAC/E,mBAAc,GAAG,IAAI,GAAG,EAAkB,CAAC;QAoB1D,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QAChC,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,aAAa,CAAC;QACxC,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,iBAAiB,CAAC;IAC5C,CAAC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,KAAK,CAAC,iBAAiB,CAAC,QAAgB;QAItC,IAAI,CAAC,iBAAiB,EAAE,CAAC;QAEzB,6DAA6D;QAC7D,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC9C,OAAO;gBACL,MAAM,EAAE,IAAI;gBACZ,KAAK,EAAE;oBACL,OAAO,EAAE,2BAA2B;oBACpC,QAAQ,EAAE,aAAa,CAAC,UAAU;iBACnC;aACF,CAAC;QACJ,CAAC;QAED,2DAA2D;QAC3D,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC,QAAQ,CAAC,EAAE,CAAC;YACvC,OAAO;gBACL,MAAM,EAAE,IAAI;gBACZ,KAAK,EAAE;oBACL,OAAO,EAAE,iCAAiC,QAAQ,EAAE;oBACpD,QAAQ,EAAE,aAAa,CAAC,aAAa;iBACtC;aACF,CAAC;QACJ,CAAC;QACD,IAAI,CAAC;YACH,qFAAqF;YACrF,IAAI,IAAI,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC;YAChE,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,mBAAmB,EAAE,CAAC;YACjE,IAAI,GAAG,MAAM,YAAY,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;YACzE,iEAAiE;YACjE,IAAI,GAAG,eAAe,CAAC,IAAI,EAAE,wBAAwB,CAAC,CAAC;YAEvD,OAAO;gBACL,MAAM,EAAE;oBACN,WAAW,EAAE,0BAA0B;oBACvC,IAAI,EAAE,IAAI;oBACV,0EAA0E;oBAC1E,2EAA2E;oBAC3E,4EAA4E;oBAC5E,4EAA4E;oBAC5E,YAAY,EAAE,kCAAkC;iBACjD;gBACD,KAAK,EAAE,IAAI;aACZ,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,gFAAgF;YAChF,OAAO;gBACL,MAAM,EAAE,IAAI;gBACZ,KAAK,EAAE;oBACL,OAAO,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,2BAA2B;oBACzE,QAAQ,EAAE,aAAa,CAAC,OAAO;oBAC/B,OAAO,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE;oBAC/B,UAAU,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS;iBACzD;aACF,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,KAAK,CAAC,iBAAiB,CAAC,gBAAwB;QAC9C,IAAI,CAAC,iBAAiB,EAAE,CAAC;QAEzB,gEAAgE;QAChE,IAAI,CAAC,gBAAgB,IAAI,gBAAgB,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC9D,OAAO;gBACL,MAAM,EAAE,IAAI;gBACZ,KAAK,EAAE;oBACL,OAAO,EAAE,mBAAmB;oBAC5B,QAAQ,EAAE,aAAa,CAAC,UAAU;iBACnC;aACF,CAAC;QACJ,CAAC;QAED,MAAM,YAAY,GAAG,IAAI,CAAC,SAAS,CAAC,eAAe,EAAE,CAAC;QACtD,MAAM,YAAY,GAChB,UACD,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;QACtB,IAAI,QAAQ,GAAuB,IAAI,CAAC;QAExC,2EAA2E;QAC3E,uEAAuE;QACvE,MAAM,WAAW,GAAG,YAAY,CAAC,eAAe,CAC9C,CAAC,GAAgB,EAAE,EAAE;YACnB,QAAQ,GAAG,GAAG,CAAC;QACjB,CAAC,EACD,EAAE,YAAY,EAAE,CACjB,CAAC;QAEF,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,gBAAgB,EAAE,YAAY,CAAC,CAAC;YAE9E,OAAO;gBACL,MAAM;gBACN,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ;aAChC,CAAC;QACJ,CAAC;gBAAS,CAAC;YACT,WAAW,EAAE,CAAC;QAChB,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,KAAK,CAAC,wBAAwB,CAAC,gBAAwB;QAIrD,IAAI,CAAC,iBAAiB,EAAE,CAAC;QAEzB,iGAAiG;QACjG,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,iBAAiB,CAAC,gBAAgB,CAAC,CAAC;QAC/D,MAAM,uBAAuB,GAAG,IAAI,CAAC,uBAAuB,CAAC,OAAO,CAAC,CAAC;QACtE,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,uBAAuB,EAAE,CAAC;IAC3D,CAAC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO;QACL,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,OAAO;QACT,CAAC;QACD,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACrB,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE,CAAC;QAC5B,kFAAkF;QAClF,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC;IAC3B,CAAC;IAED;;;;;;;OAOG;IACK,uBAAuB,CAAC,OAAyB;QACvD,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;YACpB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,2FAA2F;QAC3F,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC;QACrF,MAAM,OAAO,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;QAC5E,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC1D,OAAO;YACL,IAAI,EAAE,kBAAkB,CAAC,kBAAkB;YAC3C,OAAO,EAAE;gBACP,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,IAAI;gBACzB,OAAO,EAAE;oBACP,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,QAAQ;oBACjC,QAAQ,EAAE,QAAQ;iBACnB;gBACD,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,IAAI,OAAO,EAAE;aAChD;SACF,CAAC;IACJ,CAAC;IAED;;;;;;OAMG;IACH,SAAS,CAAC,YAAoB;QAC5B,MAAM,KAAK,GAAG,IAAI,CAAC,aAAa,CAAC,2BAA2B,CAAC,YAAY,CAAC,CAAC;QAC3E,OAAO,KAAK,CAAC,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACrD,CAAC;IAED;;;OAGG;IACK,kBAAkB,CAAC,QAAgB;QACzC,OAAO,IAAI,CAAC,aAAa,CAAC,uBAAuB,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,KAAK,QAAQ,CAAC,CAAC;IAC9F,CAAC;IAED,4DAA4D;IACpD,iBAAiB;QACvB,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;QAC9D,CAAC;IACH,CAAC;CACF;AAED;;;GAGG;AACH,SAAS,YAAY,CAAC,IAKrB;IACC,OAAO;QACL,EAAE,EAAE,IAAI,CAAC,EAAE;QACX,WAAW,EAAE,IAAI,CAAC,IAAI;QACtB,YAAY,EAAE,IAAI,CAAC,YAAY,IAAI,EAAE;QACrC,QAAQ,EAAE,IAAI,CAAC,QAAQ;KACxB,CAAC;AACJ,CAAC"}

package/dist/createWebVisualizationEngine.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Copyright (c) 2025, Salesforce, Inc.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ **/
+import { WebVisualizationEngine } from './WebVisualizationEngine.js';
+import type { WebAdapterOptions } from './types/WebAdapterOptions.js';
+/**
+ * Build a fully-initialized `WebVisualizationEngine`. This is the only
+ * public construction path — `WebVisualizationEngine`'s own constructor
+ * is internal so we can ensure plugin loading completes before the engine
+ * is handed to the consumer.
+ *
+ * Wiring details (host-invisible):
+ *   - The host's `IFileSystem` is wrapped in a `CompositeFileSystem` that
+ *     routes paths under the adapter's bundled-plugins root to a Node fs
+ *     reader, and everything else to the host. This lets the framework's
+ *     existing `visualize(filePath)` HTML render reach plugin index.html
+ *     without ever asking the host's filesystem for paths the host
+ *     doesn't know about.
+ *   - Plugin assets are read via `BundledPluginAssetReader` — used by
+ *     `getPluginIndexHtml` and `getPluginAsset`. The composite filesystem
+ *     covers the framework's internal flow.
+ */
+export declare function createWebVisualizationEngine(opts: WebAdapterOptions): Promise<WebVisualizationEngine>;
+//# sourceMappingURL=createWebVisualizationEngine.d.ts.map

package/dist/createWebVisualizationEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createWebVisualizationEngine.d.ts","sourceRoot":"","sources":["../src/createWebVisualizationEngine.ts"],"names":[],"mappings":"AAAA;;;;;IAKI;AAaJ,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAEtE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,4BAA4B,CAChD,IAAI,EAAE,iBAAiB,GACtB,OAAO,CAAC,sBAAsB,CAAC,CA2BjC"}

package/dist/createWebVisualizationEngine.js

@@ -0,0 +1,91 @@
+/**
+ * Copyright (c) 2025, Salesforce, Inc.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ **/
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { LogLevel, NoOpTelemetry, } from '@salesforce/metadata-core-sdk';
+import { PluginManager, VisualizationEngine } from '@salesforce/metadata-visualizer-core';
+import { BundledPluginAssetReader } from './pluginAssets/BundledPluginAssetReader.js';
+import { createCompositeFileSystem } from './internal/CompositeFileSystem.js';
+import { WebVisualizationEngine } from './WebVisualizationEngine.js';
+/**
+ * Build a fully-initialized `WebVisualizationEngine`. This is the only
+ * public construction path — `WebVisualizationEngine`'s own constructor
+ * is internal so we can ensure plugin loading completes before the engine
+ * is handed to the consumer.
+ *
+ * Wiring details (host-invisible):
+ *   - The host's `IFileSystem` is wrapped in a `CompositeFileSystem` that
+ *     routes paths under the adapter's bundled-plugins root to a Node fs
+ *     reader, and everything else to the host. This lets the framework's
+ *     existing `visualize(filePath)` HTML render reach plugin index.html
+ *     without ever asking the host's filesystem for paths the host
+ *     doesn't know about.
+ *   - Plugin assets are read via `BundledPluginAssetReader` — used by
+ *     `getPluginIndexHtml` and `getPluginAsset`. The composite filesystem
+ *     covers the framework's internal flow.
+ */
+export async function createWebVisualizationEngine(opts) {
+    const bundledPluginsRoot = resolveBundledPluginsRoot();
+    const composite = createCompositeFileSystem(opts.fileSystem, resolveBundledRoot());
+    const platformContext = {
+        fileSystem: composite,
+        logger: new NoOpLogger(),
+        telemetry: opts.telemetry ?? new NoOpTelemetry(),
+        // Framework constructs `<reactBuildsBasePath>/<pluginId>/ui/index.html`
+        // and reads through `fileSystem`. With the composite in place, those
+        // reads land on the adapter's bundled assets without the host's IFS
+        // ever seeing them.
+        reactBuildsBasePath: bundledPluginsRoot,
+    };
+    const pluginManager = new PluginManager(platformContext);
+    await pluginManager.loadPlugins();
+    const framework = new VisualizationEngine(platformContext, pluginManager);
+    const pluginAssetReader = new BundledPluginAssetReader(resolveBundledRoot());
+    return new WebVisualizationEngine({
+        framework,
+        pluginManager,
+        pluginAssetReader,
+    });
+}
+/**
+ * Resolve the adapter's own `dist/` directory at runtime. After the build
+ * step, this is `<package>/dist/`, which contains `plugins/...` and
+ * `design-system/platform.css`.
+ */
+function resolveBundledRoot() {
+    return path.dirname(fileURLToPath(import.meta.url));
+}
+/** Resolve the bundled plugins root (`<dist>/plugins`). */
+function resolveBundledPluginsRoot() {
+    return path.join(resolveBundledRoot(), 'plugins');
+}
+/**
+ * Default no-op `ILogger` for when the consumer doesn't supply one. Kept
+ * inline rather than re-exported from the package surface — consumers
+ * either provide their own logger or get silence.
+ */
+class NoOpLogger {
+    constructor() {
+        this.level = LogLevel.Info;
+    }
+    debug() { }
+    info() { }
+    warn() { }
+    error() { }
+    success() { }
+    log() { }
+    setLevel(level) {
+        this.level = level;
+    }
+    getLevel() {
+        return this.level;
+    }
+    createChild() {
+        return this;
+    }
+}
+//# sourceMappingURL=createWebVisualizationEngine.js.map

package/dist/createWebVisualizationEngine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createWebVisualizationEngine.js","sourceRoot":"","sources":["../src/createWebVisualizationEngine.ts"],"names":[],"mappings":"AAAA;;;;;IAKI;AAEJ,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAEL,QAAQ,EAER,aAAa,GACd,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAC1F,OAAO,EAAE,wBAAwB,EAAE,MAAM,4CAA4C,CAAC;AACtF,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAGrE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAChD,IAAuB;IAEvB,MAAM,kBAAkB,GAAG,yBAAyB,EAAE,CAAC;IAEvD,MAAM,SAAS,GAAG,yBAAyB,CAAC,IAAI,CAAC,UAAU,EAAE,kBAAkB,EAAE,CAAC,CAAC;IAEnF,MAAM,eAAe,GAAqB;QACxC,UAAU,EAAE,SAAS;QACrB,MAAM,EAAE,IAAI,UAAU,EAAE;QACxB,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,IAAI,aAAa,EAAE;QAChD,wEAAwE;QACxE,qEAAqE;QACrE,oEAAoE;QACpE,oBAAoB;QACpB,mBAAmB,EAAE,kBAAkB;KACxC,CAAC;IAEF,MAAM,aAAa,GAAG,IAAI,aAAa,CAAC,eAAe,CAAC,CAAC;IACzD,MAAM,aAAa,CAAC,WAAW,EAAE,CAAC;IAElC,MAAM,SAAS,GAAG,IAAI,mBAAmB,CAAC,eAAe,EAAE,aAAa,CAAC,CAAC;IAC1E,MAAM,iBAAiB,GAAG,IAAI,wBAAwB,CAAC,kBAAkB,EAAE,CAAC,CAAC;IAE7E,OAAO,IAAI,sBAAsB,CAAC;QAChC,SAAS;QACT,aAAa;QACb,iBAAiB;KAClB,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,SAAS,kBAAkB;IACzB,OAAO,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AACtD,CAAC;AAED,2DAA2D;AAC3D,SAAS,yBAAyB;IAChC,OAAO,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE,EAAE,SAAS,CAAC,CAAC;AACpD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU;IAAhB;QACU,UAAK,GAAa,QAAQ,CAAC,IAAI,CAAC;IAgB1C,CAAC;IAfC,KAAK,KAAU,CAAC;IAChB,IAAI,KAAU,CAAC;IACf,IAAI,KAAU,CAAC;IACf,KAAK,KAAU,CAAC;IAChB,OAAO,KAAU,CAAC;IAClB,GAAG,KAAU,CAAC;IACd,QAAQ,CAAC,KAAe;QACtB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;IACD,QAAQ;QACN,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IACD,WAAW;QACT,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}