npm - @framers/agentos-ext-widget-generator - Versions diffs - 1.0.0 - Mend

@framers/agentos-ext-widget-generator 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (29) hide show

package/LICENSE +23 -0
package/dist/WidgetFileManager.d.ts +132 -0
package/dist/WidgetFileManager.d.ts.map +1 -0
package/dist/WidgetFileManager.js +178 -0
package/dist/WidgetFileManager.js.map +1 -0
package/dist/WidgetWrapper.d.ts +65 -0
package/dist/WidgetWrapper.d.ts.map +1 -0
package/dist/WidgetWrapper.js +117 -0
package/dist/WidgetWrapper.js.map +1 -0
package/dist/index.d.ts +58 -0
package/dist/index.d.ts.map +1 -0
package/dist/index.js +64 -0
package/dist/index.js.map +1 -0
package/dist/tools/generateWidget.d.ts +78 -0
package/dist/tools/generateWidget.d.ts.map +1 -0
package/dist/tools/generateWidget.js +144 -0
package/dist/tools/generateWidget.js.map +1 -0
package/dist/types.d.ts +42 -0
package/dist/types.d.ts.map +1 -0
package/dist/types.js +8 -0
package/dist/types.js.map +1 -0
package/manifest.json +26 -0
package/package.json +65 -0
package/src/WidgetFileManager.ts +222 -0
package/src/WidgetWrapper.ts +134 -0
package/src/index.ts +91 -0
package/src/tools/generateWidget.ts +178 -0
package/src/types.ts +50 -0
package/tsconfig.json +22 -0

package/LICENSE ADDED Viewed

@@ -0,0 +1,23 @@
+MIT License
+Copyright (c) 2025 Framers
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/WidgetFileManager.d.ts ADDED Viewed

@@ -0,0 +1,132 @@
+/**
+ * @module WidgetFileManager
+ *
+ * Manages the local widgets directory for generated HTML widgets. Provides
+ * methods to save widget HTML to disk, list existing widgets, delete files,
+ * resolve full paths, and construct view/download URLs.
+ *
+ * Files are stored under `{workspaceDir}/widgets/` with timestamped,
+ * slugified filenames to avoid collisions and ensure filesystem safety.
+ */
+/**
+ * Metadata returned when listing files in the widgets directory.
+ */
+export interface WidgetFileEntry {
+    /** The file's base name (e.g. `2026-03-28T12-00-00-000Z-my-widget.html`). */
+    filename: string;
+    /** File size in bytes. */
+    sizeBytes: number;
+    /** ISO 8601 timestamp of when the file was created (from filesystem). */
+    createdAt: string;
+}
+/**
+ * Result returned after successfully saving a widget to disk.
+ */
+export interface WidgetSaveResult {
+    /** Absolute path to the saved file. */
+    filePath: string;
+    /** The generated filename (basename only). */
+    filename: string;
+}
+/**
+ * Manages the widgets directory for generated HTML widgets. Handles saving,
+ * listing, deleting, and resolving paths for widget files.
+ *
+ * @example
+ * ```ts
+ * const manager = new WidgetFileManager('/home/agent/workspace', 3777);
+ * const { filePath, filename } = await manager.save('<html>...</html>', 'My Chart');
+ * const url = manager.getWidgetUrl(filename);
+ * ```
+ */
+export declare class WidgetFileManager {
+    /** Absolute path to the widgets directory. */
+    private readonly widgetsDir;
+    /** Port used for constructing view and download URLs. */
+    private readonly serverPort;
+    /**
+     * Create a new WidgetFileManager instance.
+     *
+     * @param workspaceDir - Root workspace directory for the agent. The
+     *   widgets directory will be created as a subdirectory named `widgets`.
+     * @param serverPort - Optional port number for constructing localhost
+     *   view and download URLs. Defaults to `3777`.
+     */
+    constructor(workspaceDir: string, serverPort?: number);
+    /**
+     * Save an HTML widget to the widgets directory.
+     *
+     * Creates the widgets directory if it does not already exist. The filename
+     * is generated from the current ISO timestamp and a slugified version of
+     * the widget title, ensuring uniqueness and filesystem safety.
+     *
+     * @param html  - The complete HTML content to write.
+     * @param title - The widget title, used to derive the filename slug.
+     * @returns An object containing the absolute `filePath` and `filename`.
+     */
+    save(html: string, title: string): Promise<WidgetSaveResult>;
+    /**
+     * List all widget files in the widgets directory with their metadata.
+     *
+     * Returns an empty array if the widgets directory does not exist or
+     * contains no files. Non-file entries (directories, symlinks) are
+     * silently skipped.
+     *
+     * @returns An array of {@link WidgetFileEntry} objects sorted by filename
+     *   (newest first due to the timestamp prefix convention).
+     */
+    list(): Promise<WidgetFileEntry[]>;
+    /**
+     * Remove a widget file from the widgets directory.
+     *
+     * @param filename - The basename of the file to delete.
+     * @returns `true` if the file was successfully deleted, `false` if it
+     *   did not exist or could not be removed.
+     */
+    remove(filename: string): Promise<boolean>;
+    /**
+     * Resolve a filename to its absolute path in the widgets directory.
+     *
+     * @param filename - The basename of the file to resolve.
+     * @returns The absolute file path if the file exists, or `null` if not found.
+     */
+    resolve(filename: string): string | null;
+    /**
+     * Construct a view URL for the given widget filename.
+     *
+     * Uses the configured server port to build a localhost URL. In
+     * production deployments the URL scheme would be replaced by a
+     * reverse-proxy or CDN URL.
+     *
+     * @param filename - The basename of the widget file.
+     * @returns A fully-qualified HTTP URL pointing to the widget.
+     */
+    getWidgetUrl(filename: string): string;
+    /**
+     * Construct a download URL for the given widget filename.
+     *
+     * Returns the same URL as {@link getWidgetUrl} since the widget is
+     * a self-contained HTML file that can be both viewed and downloaded.
+     *
+     * @param filename - The basename of the widget file.
+     * @returns A fully-qualified HTTP URL pointing to the file.
+     */
+    getDownloadUrl(filename: string): string;
+    /**
+     * Convert a title string into a URL- and filesystem-safe slug.
+     *
+     * Transforms the input to lowercase, replaces non-alphanumeric
+     * characters with hyphens, collapses consecutive hyphens, and trims
+     * leading/trailing hyphens.
+     *
+     * @param title - The raw title string to slugify.
+     * @returns A clean, lowercase slug suitable for filenames.
+     *
+     * @example
+     * ```ts
+     * slugify('3D Solar System!') // '3d-solar-system'
+     * ```
+     */
+    private slugify;
+}
+//# sourceMappingURL=WidgetFileManager.d.ts.map

package/dist/WidgetFileManager.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"WidgetFileManager.d.ts","sourceRoot":"","sources":["../src/WidgetFileManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,CAAC;IAEjB,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAC;IAElB,yEAAyE;IACzE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uCAAuC;IACvC,QAAQ,EAAE,MAAM,CAAC;IAEjB,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,iBAAiB;IAC5B,8CAA8C;IAC9C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,yDAAyD;IACzD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC;;;;;;;OAOG;gBACS,YAAY,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM;IAKrD;;;;;;;;;;OAUG;IACG,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAelE;;;;;;;;;OASG;IACG,IAAI,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;IAgCxC;;;;;;OAMG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAehD;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAKxC;;;;;;;;;OASG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAItC;;;;;;;;OAQG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAIxC;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,OAAO;CAOhB"}

package/dist/WidgetFileManager.js ADDED Viewed

@@ -0,0 +1,178 @@
+/**
+ * @module WidgetFileManager
+ *
+ * Manages the local widgets directory for generated HTML widgets. Provides
+ * methods to save widget HTML to disk, list existing widgets, delete files,
+ * resolve full paths, and construct view/download URLs.
+ *
+ * Files are stored under `{workspaceDir}/widgets/` with timestamped,
+ * slugified filenames to avoid collisions and ensure filesystem safety.
+ */
+import { mkdir, writeFile, readdir, stat, unlink } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Manages the widgets directory for generated HTML widgets. Handles saving,
+ * listing, deleting, and resolving paths for widget files.
+ *
+ * @example
+ * ```ts
+ * const manager = new WidgetFileManager('/home/agent/workspace', 3777);
+ * const { filePath, filename } = await manager.save('<html>...</html>', 'My Chart');
+ * const url = manager.getWidgetUrl(filename);
+ * ```
+ */
+export class WidgetFileManager {
+    /** Absolute path to the widgets directory. */
+    widgetsDir;
+    /** Port used for constructing view and download URLs. */
+    serverPort;
+    /**
+     * Create a new WidgetFileManager instance.
+     *
+     * @param workspaceDir - Root workspace directory for the agent. The
+     *   widgets directory will be created as a subdirectory named `widgets`.
+     * @param serverPort - Optional port number for constructing localhost
+     *   view and download URLs. Defaults to `3777`.
+     */
+    constructor(workspaceDir, serverPort) {
+        this.widgetsDir = join(workspaceDir, 'widgets');
+        this.serverPort = serverPort ?? 3777;
+    }
+    /**
+     * Save an HTML widget to the widgets directory.
+     *
+     * Creates the widgets directory if it does not already exist. The filename
+     * is generated from the current ISO timestamp and a slugified version of
+     * the widget title, ensuring uniqueness and filesystem safety.
+     *
+     * @param html  - The complete HTML content to write.
+     * @param title - The widget title, used to derive the filename slug.
+     * @returns An object containing the absolute `filePath` and `filename`.
+     */
+    async save(html, title) {
+        if (!existsSync(this.widgetsDir)) {
+            await mkdir(this.widgetsDir, { recursive: true });
+        }
+        const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+        const slug = this.slugify(title);
+        const filename = `${timestamp}-${slug}.html`;
+        const filePath = join(this.widgetsDir, filename);
+        await writeFile(filePath, html, 'utf-8');
+        return { filePath, filename };
+    }
+    /**
+     * List all widget files in the widgets directory with their metadata.
+     *
+     * Returns an empty array if the widgets directory does not exist or
+     * contains no files. Non-file entries (directories, symlinks) are
+     * silently skipped.
+     *
+     * @returns An array of {@link WidgetFileEntry} objects sorted by filename
+     *   (newest first due to the timestamp prefix convention).
+     */
+    async list() {
+        if (!existsSync(this.widgetsDir)) {
+            return [];
+        }
+        const entries = await readdir(this.widgetsDir);
+        const results = [];
+        for (const entry of entries) {
+            const fullPath = join(this.widgetsDir, entry);
+            try {
+                const fileStat = await stat(fullPath);
+                if (!fileStat.isFile()) {
+                    continue;
+                }
+                results.push({
+                    filename: entry,
+                    sizeBytes: fileStat.size,
+                    createdAt: fileStat.birthtime.toISOString(),
+                });
+            }
+            catch {
+                // Skip files that can't be stat'd (e.g. permission errors)
+                continue;
+            }
+        }
+        return results;
+    }
+    /**
+     * Remove a widget file from the widgets directory.
+     *
+     * @param filename - The basename of the file to delete.
+     * @returns `true` if the file was successfully deleted, `false` if it
+     *   did not exist or could not be removed.
+     */
+    async remove(filename) {
+        const fullPath = join(this.widgetsDir, filename);
+        if (!existsSync(fullPath)) {
+            return false;
+        }
+        try {
+            await unlink(fullPath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Resolve a filename to its absolute path in the widgets directory.
+     *
+     * @param filename - The basename of the file to resolve.
+     * @returns The absolute file path if the file exists, or `null` if not found.
+     */
+    resolve(filename) {
+        const fullPath = join(this.widgetsDir, filename);
+        return existsSync(fullPath) ? fullPath : null;
+    }
+    /**
+     * Construct a view URL for the given widget filename.
+     *
+     * Uses the configured server port to build a localhost URL. In
+     * production deployments the URL scheme would be replaced by a
+     * reverse-proxy or CDN URL.
+     *
+     * @param filename - The basename of the widget file.
+     * @returns A fully-qualified HTTP URL pointing to the widget.
+     */
+    getWidgetUrl(filename) {
+        return `http://localhost:${this.serverPort}/widgets/${filename}`;
+    }
+    /**
+     * Construct a download URL for the given widget filename.
+     *
+     * Returns the same URL as {@link getWidgetUrl} since the widget is
+     * a self-contained HTML file that can be both viewed and downloaded.
+     *
+     * @param filename - The basename of the widget file.
+     * @returns A fully-qualified HTTP URL pointing to the file.
+     */
+    getDownloadUrl(filename) {
+        return `http://localhost:${this.serverPort}/widgets/${filename}`;
+    }
+    /**
+     * Convert a title string into a URL- and filesystem-safe slug.
+     *
+     * Transforms the input to lowercase, replaces non-alphanumeric
+     * characters with hyphens, collapses consecutive hyphens, and trims
+     * leading/trailing hyphens.
+     *
+     * @param title - The raw title string to slugify.
+     * @returns A clean, lowercase slug suitable for filenames.
+     *
+     * @example
+     * ```ts
+     * slugify('3D Solar System!') // '3d-solar-system'
+     * ```
+     */
+    slugify(title) {
+        return title
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, '-')
+            .replace(/-+/g, '-')
+            .replace(/^-|-$/g, '');
+    }
+}
+//# sourceMappingURL=WidgetFileManager.js.map

package/dist/WidgetFileManager.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"WidgetFileManager.js","sourceRoot":"","sources":["../src/WidgetFileManager.ts"],"names":[],"mappings":"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"}

package/dist/WidgetWrapper.d.ts ADDED Viewed

@@ -0,0 +1,65 @@
+/**
+ * @module WidgetWrapper
+ *
+ * Safety wrapper that ensures every generated widget has a well-formed
+ * HTML structure, sensible defaults, and a client-side error boundary.
+ *
+ * The wrapper is additive: it inspects the incoming HTML with
+ * case-insensitive matching and only injects elements that are missing.
+ * This prevents double-adding when the agent already includes a
+ * doctype, charset meta, viewport meta, or error handler.
+ */
+/**
+ * Wraps raw HTML content with structural defaults and an error boundary.
+ *
+ * Guarantees that every widget has:
+ * - A `<!DOCTYPE html>` declaration
+ * - A `<meta charset="utf-8">` tag
+ * - A responsive viewport meta tag
+ * - A minimal CSS reset (margin/padding/box-sizing + system-ui font)
+ * - A `window.onerror` error boundary that surfaces runtime errors visually
+ *
+ * @example
+ * ```ts
+ * const wrapper = new WidgetWrapper();
+ * const safe = wrapper.wrap('<div>Hello world</div>');
+ * // safe now contains a full HTML document with all defaults injected
+ * ```
+ */
+export declare class WidgetWrapper {
+    /**
+     * Apply the safety wrapper to the given HTML string.
+     *
+     * Performs case-insensitive checks against the source HTML and only
+     * injects elements that are not already present. The injection order
+     * is: doctype, charset, viewport, CSS reset, error boundary.
+     *
+     * @param html - Raw HTML content to wrap.
+     * @returns The wrapped HTML with all missing defaults injected.
+     */
+    wrap(html: string): string;
+    /**
+     * Inject content into the `<head>` section of the HTML document.
+     *
+     * If a `<head>` tag exists, the content is inserted right after it.
+     * Otherwise, it is prepended to the document (after the doctype, if
+     * present).
+     *
+     * @param html    - The HTML document string.
+     * @param content - The HTML fragment to inject.
+     * @returns The modified HTML with the content injected.
+     */
+    private injectIntoHead;
+    /**
+     * Inject content just before the closing `</body>` tag.
+     *
+     * If no `</body>` tag exists, the content is appended at the end
+     * of the document.
+     *
+     * @param html    - The HTML document string.
+     * @param content - The HTML fragment to inject.
+     * @returns The modified HTML with the content injected.
+     */
+    private injectBeforeBodyClose;
+}
+//# sourceMappingURL=WidgetWrapper.d.ts.map

package/dist/WidgetWrapper.d.ts.map ADDED Viewed

	@@ -0,0 +1 @@
1	+ {"version":3,"file":"WidgetWrapper.d.ts","sourceRoot":"","sources":["../src/WidgetWrapper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,aAAa;IACxB;;;;;;;;;OASG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IA6C1B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,cAAc;IAkBtB;;;;;;;;;OASG;IACH,OAAO,CAAC,qBAAqB;CAS9B"}

package/dist/WidgetWrapper.js ADDED Viewed

@@ -0,0 +1,117 @@
+/**
+ * @module WidgetWrapper
+ *
+ * Safety wrapper that ensures every generated widget has a well-formed
+ * HTML structure, sensible defaults, and a client-side error boundary.
+ *
+ * The wrapper is additive: it inspects the incoming HTML with
+ * case-insensitive matching and only injects elements that are missing.
+ * This prevents double-adding when the agent already includes a
+ * doctype, charset meta, viewport meta, or error handler.
+ */
+/**
+ * Wraps raw HTML content with structural defaults and an error boundary.
+ *
+ * Guarantees that every widget has:
+ * - A `<!DOCTYPE html>` declaration
+ * - A `<meta charset="utf-8">` tag
+ * - A responsive viewport meta tag
+ * - A minimal CSS reset (margin/padding/box-sizing + system-ui font)
+ * - A `window.onerror` error boundary that surfaces runtime errors visually
+ *
+ * @example
+ * ```ts
+ * const wrapper = new WidgetWrapper();
+ * const safe = wrapper.wrap('<div>Hello world</div>');
+ * // safe now contains a full HTML document with all defaults injected
+ * ```
+ */
+export class WidgetWrapper {
+    /**
+     * Apply the safety wrapper to the given HTML string.
+     *
+     * Performs case-insensitive checks against the source HTML and only
+     * injects elements that are not already present. The injection order
+     * is: doctype, charset, viewport, CSS reset, error boundary.
+     *
+     * @param html - Raw HTML content to wrap.
+     * @returns The wrapped HTML with all missing defaults injected.
+     */
+    wrap(html) {
+        const lower = html.toLowerCase();
+        let result = html;
+        // 1. Add <!DOCTYPE html> if missing
+        if (!lower.includes('<!doctype html>')) {
+            result = '<!DOCTYPE html>\n' + result;
+        }
+        // 2. Add <meta charset="utf-8"> if missing
+        if (!lower.includes('charset')) {
+            result = this.injectIntoHead(result, '<meta charset="utf-8">');
+        }
+        // 3. Add viewport meta if missing
+        if (!lower.includes('viewport')) {
+            result = this.injectIntoHead(result, '<meta name="viewport" content="width=device-width, initial-scale=1">');
+        }
+        // 4. Prepend CSS reset
+        if (!lower.includes('box-sizing: border-box')) {
+            const resetCss = '<style>* { margin: 0; padding: 0; box-sizing: border-box; } body { font-family: system-ui, sans-serif; }</style>';
+            result = this.injectIntoHead(result, resetCss);
+        }
+        // 5. Append error boundary script
+        if (!lower.includes('window.onerror')) {
+            const errorScript = `<script>
+window.onerror = function(msg, url, line) {
+  var el = document.createElement('div');
+  el.style.cssText = 'position:fixed;top:0;left:0;right:0;padding:16px;background:#fee2e2;color:#991b1b;font:14px system-ui;z-index:99999';
+  el.textContent = 'Widget error: ' + msg + ' (line ' + line + ')';
+  document.body.prepend(el);
+};
+</script>`;
+            result = this.injectBeforeBodyClose(result, errorScript);
+        }
+        return result;
+    }
+    /**
+     * Inject content into the `<head>` section of the HTML document.
+     *
+     * If a `<head>` tag exists, the content is inserted right after it.
+     * Otherwise, it is prepended to the document (after the doctype, if
+     * present).
+     *
+     * @param html    - The HTML document string.
+     * @param content - The HTML fragment to inject.
+     * @returns The modified HTML with the content injected.
+     */
+    injectIntoHead(html, content) {
+        const headIndex = html.toLowerCase().indexOf('<head>');
+        if (headIndex !== -1) {
+            const insertPos = headIndex + '<head>'.length;
+            return html.slice(0, insertPos) + '\n' + content + html.slice(insertPos);
+        }
+        // No <head> tag — insert after doctype if present, otherwise at the top
+        const doctypeEnd = html.toLowerCase().indexOf('<!doctype html>');
+        if (doctypeEnd !== -1) {
+            const insertPos = doctypeEnd + '<!doctype html>'.length;
+            return html.slice(0, insertPos) + '\n' + content + html.slice(insertPos);
+        }
+        return content + '\n' + html;
+    }
+    /**
+     * Inject content just before the closing `</body>` tag.
+     *
+     * If no `</body>` tag exists, the content is appended at the end
+     * of the document.
+     *
+     * @param html    - The HTML document string.
+     * @param content - The HTML fragment to inject.
+     * @returns The modified HTML with the content injected.
+     */
+    injectBeforeBodyClose(html, content) {
+        const bodyCloseIndex = html.toLowerCase().indexOf('</body>');
+        if (bodyCloseIndex !== -1) {
+            return html.slice(0, bodyCloseIndex) + content + '\n' + html.slice(bodyCloseIndex);
+        }
+        return html + '\n' + content;
+    }
+}
+//# sourceMappingURL=WidgetWrapper.js.map

package/dist/WidgetWrapper.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"WidgetWrapper.js","sourceRoot":"","sources":["../src/WidgetWrapper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,aAAa;IACxB;;;;;;;;;OASG;IACH,IAAI,CAAC,IAAY;QACf,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;QACjC,IAAI,MAAM,GAAG,IAAI,CAAC;QAElB,oCAAoC;QACpC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC;YACvC,MAAM,GAAG,mBAAmB,GAAG,MAAM,CAAC;QACxC,CAAC;QAED,2CAA2C;QAC3C,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;YAC/B,MAAM,GAAG,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC;QACjE,CAAC;QAED,kCAAkC;QAClC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;YAChC,MAAM,GAAG,IAAI,CAAC,cAAc,CAC1B,MAAM,EACN,sEAAsE,CACvE,CAAC;QACJ,CAAC;QAED,uBAAuB;QACvB,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,wBAAwB,CAAC,EAAE,CAAC;YAC9C,MAAM,QAAQ,GACZ,kHAAkH,CAAC;YACrH,MAAM,GAAG,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QACjD,CAAC;QAED,kCAAkC;QAClC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC;YACtC,MAAM,WAAW,GAAG;;;;;;;UAOhB,CAAC;YACL,MAAM,GAAG,IAAI,CAAC,qBAAqB,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;QAC3D,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;;;;;;;OAUG;IACK,cAAc,CAAC,IAAY,EAAE,OAAe;QAClD,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAEvD,IAAI,SAAS,KAAK,CAAC,CAAC,EAAE,CAAC;YACrB,MAAM,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC;YAC9C,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,GAAG,IAAI,GAAG,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QAC3E,CAAC;QAED,wEAAwE;QACxE,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC;QACjE,IAAI,UAAU,KAAK,CAAC,CAAC,EAAE,CAAC;YACtB,MAAM,SAAS,GAAG,UAAU,GAAG,iBAAiB,CAAC,MAAM,CAAC;YACxD,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,GAAG,IAAI,GAAG,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QAC3E,CAAC;QAED,OAAO,OAAO,GAAG,IAAI,GAAG,IAAI,CAAC;IAC/B,CAAC;IAED;;;;;;;;;OASG;IACK,qBAAqB,CAAC,IAAY,EAAE,OAAe;QACzD,MAAM,cAAc,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAE7D,IAAI,cAAc,KAAK,CAAC,CAAC,EAAE,CAAC;YAC1B,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,cAAc,CAAC,GAAG,OAAO,GAAG,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;QACrF,CAAC;QAED,OAAO,IAAI,GAAG,IAAI,GAAG,OAAO,CAAC;IAC/B,CAAC;CACF"}

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,58 @@
+/**
+ * @module index
+ *
+ * Widget Generator Extension Pack — generates self-contained interactive
+ * HTML/CSS/JS widgets with safety wrapping and file management.
+ *
+ * Entry point for the extension; follows the standard AgentOS extension
+ * pack factory pattern (see {@link createExtensionPack}). The factory
+ * wires up the {@link WidgetWrapper} for HTML safety, the
+ * {@link WidgetFileManager} for file persistence, and registers the
+ * `generate_widget` tool.
+ */
+import { GenerateWidgetTool } from './tools/generateWidget.js';
+/**
+ * Options accepted by the Widget Generator extension pack factory.
+ */
+export interface WidgetGeneratorExtensionOptions {
+    /** Override the default priority used when registering the tool. */
+    priority?: number;
+    /** Override the agent workspace directory (defaults to `process.cwd()`). */
+    workspaceDir?: string;
+    /** Override the server port used for widget URLs (defaults to `3777`). */
+    serverPort?: number;
+}
+/**
+ * Factory function called by the AgentOS extension loader. Returns a pack
+ * descriptor containing the `generate_widget` tool.
+ *
+ * The factory:
+ *
+ * 1. Resolves the workspace directory and server port from context options.
+ * 2. Creates the {@link WidgetWrapper} for HTML safety wrapping.
+ * 3. Creates the {@link WidgetFileManager} for file I/O.
+ * 4. Wires both into the {@link GenerateWidgetTool}.
+ * 5. Returns the tool as an extension pack descriptor with lifecycle hooks.
+ *
+ * @param context - Extension activation context provided by the AgentOS runtime.
+ * @returns An extension pack with tool descriptors and lifecycle hooks.
+ */
+export declare function createExtensionPack(context: any): {
+    name: string;
+    version: string;
+    descriptors: {
+        id: string;
+        kind: "tool";
+        priority: number;
+        payload: GenerateWidgetTool;
+    }[];
+    onActivate: () => Promise<any>;
+    onDeactivate: () => Promise<any>;
+};
+export default createExtensionPack;
+export { WidgetWrapper } from './WidgetWrapper.js';
+export { WidgetFileManager } from './WidgetFileManager.js';
+export { GenerateWidgetTool } from './tools/generateWidget.js';
+export type { GenerateWidgetInput, GenerateWidgetOutput } from './types.js';
+export type { WidgetFileEntry, WidgetSaveResult } from './WidgetFileManager.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE/D;;GAEG;AACH,MAAM,WAAW,+BAA+B;IAC9C,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,GAAG;;;;;;;;;;;EAiC/C;AAED,eAAe,mBAAmB,CAAC;AAGnC,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAG/D,YAAY,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAC5E,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/index.js ADDED Viewed

@@ -0,0 +1,64 @@
+/**
+ * @module index
+ *
+ * Widget Generator Extension Pack — generates self-contained interactive
+ * HTML/CSS/JS widgets with safety wrapping and file management.
+ *
+ * Entry point for the extension; follows the standard AgentOS extension
+ * pack factory pattern (see {@link createExtensionPack}). The factory
+ * wires up the {@link WidgetWrapper} for HTML safety, the
+ * {@link WidgetFileManager} for file persistence, and registers the
+ * `generate_widget` tool.
+ */
+import { WidgetWrapper } from './WidgetWrapper.js';
+import { WidgetFileManager } from './WidgetFileManager.js';
+import { GenerateWidgetTool } from './tools/generateWidget.js';
+/**
+ * Factory function called by the AgentOS extension loader. Returns a pack
+ * descriptor containing the `generate_widget` tool.
+ *
+ * The factory:
+ *
+ * 1. Resolves the workspace directory and server port from context options.
+ * 2. Creates the {@link WidgetWrapper} for HTML safety wrapping.
+ * 3. Creates the {@link WidgetFileManager} for file I/O.
+ * 4. Wires both into the {@link GenerateWidgetTool}.
+ * 5. Returns the tool as an extension pack descriptor with lifecycle hooks.
+ *
+ * @param context - Extension activation context provided by the AgentOS runtime.
+ * @returns An extension pack with tool descriptors and lifecycle hooks.
+ */
+export function createExtensionPack(context) {
+    const options = (context.options || {});
+    // Resolve configuration
+    const workspaceDir = options.workspaceDir ?? process.cwd();
+    const serverPort = options.serverPort ?? 3777;
+    const priority = options.priority ?? 50;
+    // Create dependencies
+    const wrapper = new WidgetWrapper();
+    const fileManager = new WidgetFileManager(workspaceDir, serverPort);
+    // Create the tool with all dependencies injected
+    const tool = new GenerateWidgetTool(wrapper, fileManager);
+    return {
+        name: '@framers/agentos-ext-widget-generator',
+        version: '1.0.0',
+        descriptors: [
+            {
+                // IMPORTANT: ToolExecutor uses descriptor id as the lookup key for tool calls.
+                // Keep it aligned with `tool.name`.
+                id: tool.name,
+                kind: 'tool',
+                priority,
+                payload: tool,
+            },
+        ],
+        onActivate: async () => context.logger?.info('Interactive Widgets activated'),
+        onDeactivate: async () => context.logger?.info('Interactive Widgets deactivated'),
+    };
+}
+export default createExtensionPack;
+// Re-export classes for direct consumption
+export { WidgetWrapper } from './WidgetWrapper.js';
+export { WidgetFileManager } from './WidgetFileManager.js';
+export { GenerateWidgetTool } from './tools/generateWidget.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAgB/D;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAY;IAC9C,MAAM,OAAO,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAoC,CAAC;IAE3E,wBAAwB;IACxB,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IAC3D,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,IAAI,CAAC;IAC9C,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC;IAExC,sBAAsB;IACtB,MAAM,OAAO,GAAG,IAAI,aAAa,EAAE,CAAC;IACpC,MAAM,WAAW,GAAG,IAAI,iBAAiB,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;IAEpE,iDAAiD;IACjD,MAAM,IAAI,GAAG,IAAI,kBAAkB,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;IAE1D,OAAO;QACL,IAAI,EAAE,uCAAuC;QAC7C,OAAO,EAAE,OAAO;QAChB,WAAW,EAAE;YACX;gBACE,+EAA+E;gBAC/E,oCAAoC;gBACpC,EAAE,EAAE,IAAI,CAAC,IAAI;gBACb,IAAI,EAAE,MAAe;gBACrB,QAAQ;gBACR,OAAO,EAAE,IAAI;aACd;SACF;QACD,UAAU,EAAE,KAAK,IAAI,EAAE,CACrB,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,+BAA+B,CAAC;QACvD,YAAY,EAAE,KAAK,IAAI,EAAE,CACvB,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,iCAAiC,CAAC;KAC1D,CAAC;AACJ,CAAC;AAED,eAAe,mBAAmB,CAAC;AAEnC,2CAA2C;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC"}