@nimbalyst/extension-sdk 0.2.0 → 0.2.1

package/dist/useCollaborativeEditor.d.ts

@@ -37,6 +37,7 @@
  */
 import * as Y from 'yjs';
 import type { CollaborationStatus, CollaboratorInfo, EditorHost } from './types/editor.js';
+import type { CollabCodec } from './types/collab.js';
 /**
  * Origin tag used when the SDK wraps `initializeFromContent` in a Y.Doc
  * transaction. Extension bindings can compare a transaction's origin
@@ -51,44 +52,83 @@ import type { CollaborationStatus, CollaboratorInfo, EditorHost } from './types/
  * ```
  */
 export declare const COLLAB_INIT_ORIGIN: unique symbol;
-export interface UseCollaborativeEditorConfig {
+/** Context passed to the binding factory (`bind` / `createBinding`). */
+export interface CollabBindContext {
+    yDoc: Y.Doc;
+    awareness: import('y-protocols/awareness').Awareness;
+    user: {
+        id: string;
+        name: string;
+        color: string;
+    };
+}
+export type CollabBindResult = {
+    destroy: () => void;
+} | Promise<{
+    destroy: () => void;
+}>;
+/**
+ * Preferred config: pass the SAME pure {@link CollabCodec} the extension
+ * registered via `context.services.collab.registerContentAdapter(...)`, plus
+ * the one React-coupled piece (`bind`). `isEmpty` / `seedFromFile` are read
+ * off the codec, so the live seed and every headless seed provably run the
+ * same code -- an extension can no longer implement emptiness/seeding twice
+ * and have the two disagree.
+ *
+ * ```tsx
+ * useCollaborativeEditor(host, {
+ *   codec: mindmapCodec,
+ *   bind: ({ yDoc, awareness, user }) => new MindmapBinding(yDoc, api, awareness),
+ * });
+ * ```
+ */
+export interface UseCollaborativeEditorCodecConfig {
+    /** The pure codec. Its `isEmpty` gates seeding and `seedFromFile` performs it. */
+    codec: CollabCodec;
     /**
-     * Create the yJS binding that wires editor state to the Y.Doc. Called
-     * once when collaboration is ready (sync done, seed applied if needed).
-     * Returns a destroy fn invoked on unmount or when the binding needs to
-     * be torn down.
+     * Create the yJS binding that wires editor state to the Y.Doc. Called once
+     * when collaboration is ready (sync done, seed applied if needed). May return
+     * a Promise so extensions can defer construction until their imperative API
+     * has finished mounting; the hook awaits it and honors cancellation.
      */
-    createBinding(ctx: {
-        yDoc: Y.Doc;
-        awareness: import('y-protocols/awareness').Awareness;
-        user: {
-            id: string;
-            name: string;
-            color: string;
-        };
-    }): {
-        destroy: () => void;
-    };
+    bind(ctx: CollabBindContext): CollabBindResult;
     /**
-     * Decide whether the Y.Doc still needs to be seeded from file content.
-     * Returning `true` means "this Y.Doc has no extension content yet -- call
-     * initializeFromContent". Default: `Y.encodeStateAsUpdate(yDoc).byteLength <= 2`,
-     * which matches a fully empty Y.Doc.
-     *
-     * Override when your shared types may exist as empty containers (e.g. you
-     * always call `yDoc.getMap('meta')` even on first open) and a length-2
-     * encoded state would still be considered "empty" by your check.
+     * Optional: notified when the first-open seed fails or its flush is not
+     * confirmed by the server. The host uses this to surface the failure via the
+     * pending-seed machinery instead of leaving a silent `console.error`.
+     */
+    onSeedOutcome?(outcome: {
+        ok: boolean;
+        error?: unknown;
+    }): void;
+}
+/**
+ * @deprecated Legacy config shape. Prefer {@link UseCollaborativeEditorCodecConfig}
+ * (`{ codec, bind }`), which keeps the pure `isEmpty`/`seed` on the codec so
+ * live and headless seeding cannot diverge. This shape traps those pure
+ * functions inside React. Still accepted so existing editors keep working.
+ */
+export interface UseCollaborativeEditorLegacyConfig {
+    /** @deprecated Use `bind` on the codec config. */
+    createBinding(ctx: CollabBindContext): CollabBindResult;
+    /**
+     * @deprecated Provide `isEmpty` on the codec. Decide whether the Y.Doc still
+     * needs seeding from file content. Default: `Y.encodeStateAsUpdate(yDoc).byteLength <= 2`.
      */
     isEmpty?(yDoc: Y.Doc): boolean;
     /**
-     * Populate the Y.Doc from raw file content when this client is the first
-     * to open the document. Called inside a `yDoc.transact(..., COLLAB_INIT_ORIGIN)`
-     * so bindings can ignore the seeding transaction.
-     *
-     * Bootstrap race: see file-level docs. Use content-derived stable IDs.
+     * @deprecated Provide `seedFromFile` on the codec. Populate the Y.Doc from
+     * raw file content when this client is first. Called inside a
+     * `yDoc.transact(..., COLLAB_INIT_ORIGIN)`. Use content-derived stable IDs
+     * (see file-level docs) to keep the bootstrap race deterministic.
      */
     initializeFromContent(yDoc: Y.Doc, content: string | ArrayBuffer): void;
+    onSeedOutcome?(outcome: {
+        ok: boolean;
+        error?: unknown;
+    }): void;
 }
+export type UseCollaborativeEditorConfig = UseCollaborativeEditorCodecConfig | UseCollaborativeEditorLegacyConfig;
 export interface UseCollaborativeEditorResult {
     /** True when `host.collaboration` is defined. */
     isCollaborative: boolean;
@@ -100,12 +140,26 @@ export interface UseCollaborativeEditorResult {
      */
     collaborators: Map<string, CollaboratorInfo>;
     /**
-     * The binding handle once `createBinding` has run, or `null` until
+     * The binding handle once the binding factory has run, or `null` until
      * collaboration is ready / when not collab.
      */
     binding: {
         destroy: () => void;
     } | null;
+    /**
+     * Non-null when the first-open seed failed or its flush was not confirmed by
+     * the server. Hosts read this to surface the failure (pending-seed toast)
+     * rather than leaving a silent console error.
+     */
+    seedError: unknown | null;
 }
+/**
+ * True when `content` can legitimately seed a first-open collaborative doc.
+ * Empty/whitespace content must never seed: the host returns '' when it has
+ * no bytes for the document (e.g. reopening an already-shared doc), and
+ * seeding from that writes a DEFAULT document into the shared room —
+ * clobbering the room's real content for every client. Exported for tests.
+ */
+export declare function hasSeedableContent(content: string | ArrayBuffer | Uint8Array | null | undefined): boolean;
 export declare function useCollaborativeEditor(host: EditorHost, config: UseCollaborativeEditorConfig): UseCollaborativeEditorResult;
 //# sourceMappingURL=useCollaborativeEditor.d.ts.map

package/dist/useCollaborativeEditor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useCollaborativeEditor.d.ts","sourceRoot":"","sources":["../src/useCollaborativeEditor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAGH,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,KAAK,EAEV,mBAAmB,EACnB,gBAAgB,EAChB,UAAU,EACX,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,kBAAkB,eAAkC,CAAC;AAElE,MAAM,WAAW,4BAA4B;IAC3C;;;;;OAKG;IACH,aAAa,CAAC,GAAG,EAAE;QACjB,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC;QACZ,SAAS,EAAE,OAAO,uBAAuB,EAAE,SAAS,CAAC;QACrD,IAAI,EAAE;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC;KACnD,GAAG;QAAE,OAAO,EAAE,MAAM,IAAI,CAAA;KAAE,CAAC;IAE5B;;;;;;;;;OASG;IACH,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,GAAG,OAAO,CAAC;IAE/B;;;;;;OAMG;IACH,qBAAqB,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAAC;CACzE;AAED,MAAM,WAAW,4BAA4B;IAC3C,iDAAiD;IACjD,eAAe,EAAE,OAAO,CAAC;IACzB,0EAA0E;IAC1E,MAAM,EAAE,mBAAmB,CAAC;IAC5B;;;OAGG;IACH,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC7C;;;OAGG;IACH,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;CACzC;AAOD,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,4BAA4B,GACnC,4BAA4B,CAwH9B"}
+{"version":3,"file":"useCollaborativeEditor.d.ts","sourceRoot":"","sources":["../src/useCollaborativeEditor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAGH,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,KAAK,EAEV,mBAAmB,EACnB,gBAAgB,EAChB,UAAU,EACX,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,WAAW,EAA2B,MAAM,mBAAmB,CAAC;AAE9E;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,kBAAkB,eAAkC,CAAC;AAElE,wEAAwE;AACxE,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC;IACZ,SAAS,EAAE,OAAO,uBAAuB,EAAE,SAAS,CAAC;IACrD,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CACnD;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,OAAO,EAAE,MAAM,IAAI,CAAA;CAAE,GACvB,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,IAAI,CAAA;CAAE,CAAC,CAAC;AAErC;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,iCAAiC;IAChD,kFAAkF;IAClF,KAAK,EAAE,WAAW,CAAC;IAEnB;;;;;OAKG;IACH,IAAI,CAAC,GAAG,EAAE,iBAAiB,GAAG,gBAAgB,CAAC;IAE/C;;;;OAIG;IACH,aAAa,CAAC,CAAC,OAAO,EAAE;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;CACjE;AAED;;;;;GAKG;AACH,MAAM,WAAW,kCAAkC;IACjD,kDAAkD;IAClD,aAAa,CAAC,GAAG,EAAE,iBAAiB,GAAG,gBAAgB,CAAC;IAExD;;;OAGG;IACH,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,GAAG,OAAO,CAAC;IAE/B;;;;;OAKG;IACH,qBAAqB,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAAC;IAExE,aAAa,CAAC,CAAC,OAAO,EAAE;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;CACjE;AAED,MAAM,MAAM,4BAA4B,GACpC,iCAAiC,GACjC,kCAAkC,CAAC;AAEvC,MAAM,WAAW,4BAA4B;IAC3C,iDAAiD;IACjD,eAAe,EAAE,OAAO,CAAC;IACzB,0EAA0E;IAC1E,MAAM,EAAE,mBAAmB,CAAC;IAC5B;;;OAGG;IACH,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC7C;;;OAGG;IACH,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;IACxC;;;;OAIG;IACH,SAAS,EAAE,OAAO,GAAG,IAAI,CAAC;CAC3B;AAyCD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,UAAU,GAAG,IAAI,GAAG,SAAS,GAC5D,OAAO,CAIT;AAED,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,4BAA4B,GACnC,4BAA4B,CA6K9B"}

package/dist/useCollaborativeEditor.js

@@ -55,11 +55,53 @@ function defaultIsEmpty(yDoc) {
     // A fully empty Y.Doc encodes to ~2 bytes (header only).
     return Y.encodeStateAsUpdate(yDoc).byteLength <= 2;
 }
+/**
+ * Normalize the config to a single internal shape. `codec` (preferred) takes
+ * its `isEmpty`/`seed` from the pure codec; the legacy shape keeps the
+ * hand-rolled `isEmpty`/`initializeFromContent`. Content is normalized to
+ * `string | Uint8Array` for the codec path (the host's `loadInitialContent`
+ * still yields `string | ArrayBuffer`).
+ */
+function resolveConfig(config) {
+    if ('codec' in config) {
+        const { codec, bind, onSeedOutcome } = config;
+        return {
+            bind,
+            isEmpty: (yDoc) => codec.isEmpty(yDoc),
+            seed: (yDoc, content) => codec.seedFromFile(yDoc, toCodecSource(content)),
+            onSeedOutcome,
+        };
+    }
+    return {
+        bind: config.createBinding,
+        isEmpty: config.isEmpty ?? defaultIsEmpty,
+        seed: config.initializeFromContent,
+        onSeedOutcome: config.onSeedOutcome,
+    };
+}
+function toCodecSource(content) {
+    return typeof content === 'string' ? content : new Uint8Array(content);
+}
+/**
+ * True when `content` can legitimately seed a first-open collaborative doc.
+ * Empty/whitespace content must never seed: the host returns '' when it has
+ * no bytes for the document (e.g. reopening an already-shared doc), and
+ * seeding from that writes a DEFAULT document into the shared room —
+ * clobbering the room's real content for every client. Exported for tests.
+ */
+export function hasSeedableContent(content) {
+    if (content == null)
+        return false;
+    if (typeof content === 'string')
+        return content.trim().length > 0;
+    return content.byteLength > 0;
+}
 export function useCollaborativeEditor(host, config) {
     const isCollaborative = !!host.collaboration;
     const [status, setStatus] = useState(host.collaboration?.getStatus() ?? 'disconnected');
     const [collaborators, setCollaborators] = useState(() => new Map());
     const [binding, setBinding] = useState(null);
+    const [seedError, setSeedError] = useState(null);
     // Keep config in a ref so the binding-creation effect doesn't tear down on
     // every render. Hosts pass fresh config objects each render, but the
     // intent is "wire once, keep until the host changes".
@@ -114,37 +156,83 @@ export function useCollaborativeEditor(host, config) {
                 return;
             if (collab.getStatus() !== 'connected')
                 return;
-            const cfg = configRef.current;
-            const isEmptyFn = cfg.isEmpty ?? defaultIsEmpty;
-            if (isEmptyFn(collab.yDoc)) {
+            const cfg = resolveConfig(configRef.current);
+            // NEVER seed when the transport skipped payloads it could not decode:
+            // the Y.Doc looking empty then means "content exists but is unreadable
+            // on this client", and seeding would write a default document over the
+            // real content for every client (the "Untitled map" clobber).
+            const undecoded = collab.hasUndecodedContent?.() === true;
+            if (!undecoded && cfg.isEmpty(collab.yDoc)) {
                 try {
                     const content = await collab.loadInitialContent();
                     if (cancelled)
                         return;
+                    // NEVER seed from empty content. A host that has no bytes for this
+                    // document (reopen of an already-shared doc: no in-memory share
+                    // payload, no file) returns ''/empty -- seeding from that writes a
+                    // default document into the shared room and clobbers whatever the
+                    // room's real content is for every client. Fall through to bind:
+                    // the room content (or a teammate's seed) will populate the doc.
+                    if (!hasSeedableContent(content)) {
+                        console.warn('[useCollaborativeEditor] Skipping first-open seed: host returned empty initial content.');
+                    }
                     // Re-check emptiness in case another client seeded while we were
                     // awaiting -- they would have raced through the WebSocket and
                     // applied their update during our await gap. Avoid double-seeding
                     // in that case; CRDT merge would otherwise insert duplicate
                     // content unless the seed is fully deterministic.
-                    if (isEmptyFn(collab.yDoc)) {
+                    else if (cfg.isEmpty(collab.yDoc)) {
                         collab.yDoc.transact(() => {
-                            cfg.initializeFromContent(collab.yDoc, content);
+                            cfg.seed(collab.yDoc, content);
                         }, COLLAB_INIT_ORIGIN);
+                        // Durability: the seed the user sees locally must reach the server
+                        // before this provider can tear down. flushWithAck resolves only
+                        // after a server-persisted ack; flushLocalState is the deprecated
+                        // fire-and-forget fallback for older hosts.
+                        const flushed = collab.flushWithAck
+                            ? await collab.flushWithAck()
+                            : (await collab.flushLocalState?.(), true);
+                        if (!flushed) {
+                            const err = new Error('Seed flush was not confirmed by the server before timeout; content may not have persisted.');
+                            console.warn('[useCollaborativeEditor]', err.message);
+                            setSeedError(err);
+                            cfg.onSeedOutcome?.({ ok: false, error: err });
+                        }
+                        else {
+                            setSeedError(null);
+                            cfg.onSeedOutcome?.({ ok: true });
+                        }
                     }
                 }
                 catch (err) {
                     console.error('[useCollaborativeEditor] Failed to load/seed initial content:', err);
+                    setSeedError(err);
+                    cfg.onSeedOutcome?.({ ok: false, error: err });
                     // Continue with bind -- the doc may still be usable once another
                     // client seeds it.
                 }
             }
             if (cancelled)
                 return;
-            handle = cfg.createBinding({
+            const created = cfg.bind({
                 yDoc: collab.yDoc,
                 awareness: collab.awareness,
                 user: collab.user,
             });
+            const resolved = created instanceof Promise ? await created : created;
+            if (cancelled) {
+                // Effect unmounted while we were awaiting the extension's
+                // imperative API. Destroy the freshly-built handle so any
+                // observers/awareness subscriptions inside it get cleaned up.
+                try {
+                    resolved.destroy();
+                }
+                catch (err) {
+                    console.error('[useCollaborativeEditor] post-cancel destroy failed:', err);
+                }
+                return;
+            }
+            handle = resolved;
             setBinding(handle);
         };
         void tryStart();
@@ -161,5 +249,5 @@ export function useCollaborativeEditor(host, config) {
             setBinding(null);
         };
     }, [host]);
-    return { isCollaborative, status, collaborators, binding };
+    return { isCollaborative, status, collaborators, binding, seedError };
 }

package/dist/validate.browser.d.ts

@@ -0,0 +1,5 @@
+import type { ValidationResult } from './validationTypes.js';
+export declare function validateExtensionBundle(_distPath: string, _bundleName?: string): Promise<ValidationResult>;
+export declare function printValidationResult(result: ValidationResult): void;
+export type { ValidationResult } from './validationTypes.js';
+//# sourceMappingURL=validate.browser.d.ts.map

package/dist/validate.browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.browser.d.ts","sourceRoot":"","sources":["../src/validate.browser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAM7D,wBAAsB,uBAAuB,CAC3C,SAAS,EAAE,MAAM,EACjB,WAAW,SAAa,GACvB,OAAO,CAAC,gBAAgB,CAAC,CAM3B;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAmBpE;AAED,YAAY,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/validate.browser.js

@@ -0,0 +1,27 @@
+const BROWSER_VALIDATION_ERROR = 'validateExtensionBundle() is only available in Node.js build tooling. ' +
+    'Import it from a Vite config, build script, or other Node runtime.';
+export async function validateExtensionBundle(_distPath, _bundleName = 'index.js') {
+    return {
+        valid: false,
+        errors: [BROWSER_VALIDATION_ERROR],
+        warnings: [],
+    };
+}
+export function printValidationResult(result) {
+    if (result.errors.length === 0 && result.warnings.length === 0) {
+        console.warn(BROWSER_VALIDATION_ERROR);
+        return;
+    }
+    if (result.errors.length > 0) {
+        console.error('Extension bundle validation errors:');
+        for (const error of result.errors) {
+            console.error(`  - ${error}`);
+        }
+    }
+    if (result.warnings.length > 0) {
+        console.warn('Extension bundle validation warnings:');
+        for (const warning of result.warnings) {
+            console.warn(`  - ${warning}`);
+        }
+    }
+}

package/dist/validate.d.ts

@@ -1,11 +1,5 @@
-export interface ValidationResult {
-    /** Whether the bundle passed validation */
-    valid: boolean;
-    /** Critical errors that will cause runtime failures */
-    errors: string[];
-    /** Warnings that may cause issues */
-    warnings: string[];
-}
+import type { ValidationResult } from './validationTypes.js';
+export type { ValidationResult } from './validationTypes.js';
 /**
  * Validates an extension bundle for common issues.
  *

package/dist/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,gBAAgB;IAC/B,2CAA2C;IAC3C,KAAK,EAAE,OAAO,CAAC;IAEf,uDAAuD;IACvD,MAAM,EAAE,MAAM,EAAE,CAAC;IAEjB,qCAAqC;IACrC,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,MAAM,EAChB,UAAU,SAAa,GACtB,OAAO,CAAC,gBAAgB,CAAC,CAkH3B;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAmBpE"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,YAAY,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE7D;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,MAAM,EAChB,UAAU,SAAa,GACtB,OAAO,CAAC,gBAAgB,CAAC,CAsP3B;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAmBpE"}

package/dist/validate.js

@@ -3,6 +3,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
+import { validateAgentProviders, validateBackendModules, } from './manifestValidation.js';
 /**
  * Validates an extension bundle for common issues.
  *
@@ -94,6 +95,122 @@ export async function validateExtensionBundle(distPath, bundleName = 'index.js')
                     warnings.push(`manifest.json "styles" points to ${manifest.styles} but file does not exist`);
                 }
             }
+            // Validate backendModules if present. These run outside the renderer
+            // under a host-managed permission system; malformed declarations would
+            // either fail to load at runtime or, worse, declare unknown permission
+            // ids the consent prompt can't render. Catch both at build time.
+            const backendModulesIssues = validateBackendModules(manifest?.contributions?.backendModules);
+            for (const issue of backendModulesIssues) {
+                errors.push(issue.message);
+            }
+            // Also check the declared entry files exist on disk.
+            if (Array.isArray(manifest?.contributions?.backendModules)) {
+                for (const module of manifest.contributions.backendModules) {
+                    if (typeof module?.entry === 'string') {
+                        const entryPath = path.join(path.dirname(manifestPath), module.entry);
+                        if (!fs.existsSync(entryPath)) {
+                            errors.push(`backendModules[${module.id ?? '?'}].entry points to ${module.entry} but file does not exist`);
+                        }
+                    }
+                }
+            }
+            // Validate aiAgentProviders contributions: id/name/backendModuleId
+            // shape, uniqueness, model fields, toolFileLinks keys, and provider
+            // count cap. Cross-references contributions.backendModules so a typo
+            // in backendModuleId fails the build instead of erroring at runtime.
+            const agentProviderIssues = validateAgentProviders(manifest?.contributions?.aiAgentProviders, manifest?.contributions?.backendModules);
+            for (const issue of agentProviderIssues) {
+                if (issue.severity === 'warning') {
+                    warnings.push(issue.message);
+                }
+                else {
+                    errors.push(issue.message);
+                }
+            }
+            // For each agent provider, verify that the backend module it points at
+            // actually exports a usable entry point in the built bundle. The
+            // privileged host will either call `activate(context)` (the generic
+            // BackendModule contract) or `createAgentProvider(context)` (the
+            // agent-provider factory) -- catching missing exports here keeps a
+            // broken contribution from reaching the consent prompt.
+            if (Array.isArray(manifest?.contributions?.aiAgentProviders)) {
+                // Build a quick lookup so the per-provider check below can find the
+                // corresponding backend-module entry path without re-scanning the
+                // array each time.
+                const moduleEntries = new Map();
+                if (Array.isArray(manifest?.contributions?.backendModules)) {
+                    for (const moduleRaw of manifest.contributions.backendModules) {
+                        const id = moduleRaw?.id;
+                        const entry = moduleRaw?.entry;
+                        if (typeof id === 'string' && typeof entry === 'string') {
+                            moduleEntries.set(id, entry);
+                        }
+                    }
+                }
+                for (const providerRaw of manifest.contributions.aiAgentProviders) {
+                    const providerId = typeof providerRaw?.id === 'string' ? providerRaw.id : '?';
+                    const backendModuleId = typeof providerRaw?.backendModuleId === 'string'
+                        ? providerRaw.backendModuleId
+                        : undefined;
+                    if (!backendModuleId) {
+                        // Already reported by validateAgentProviders above; don't
+                        // duplicate the error here.
+                        continue;
+                    }
+                    const entryRel = moduleEntries.get(backendModuleId);
+                    if (!entryRel) {
+                        // Cross-reference error already reported by
+                        // validateAgentProviders; skip the bundle scan.
+                        continue;
+                    }
+                    const entryAbs = path.join(path.dirname(manifestPath), entryRel);
+                    if (!fs.existsSync(entryAbs)) {
+                        // The missing-file error is already raised by the backendModules
+                        // entry check above; don't pile on with a confusingly worded
+                        // duplicate. Skip the export scan.
+                        continue;
+                    }
+                    // We deliberately do a textual scan rather than executing the
+                    // module. The backend module is meant to run inside a privileged
+                    // worker; loading it inside the build script could trigger side
+                    // effects (open ports, spawn processes, write disk) that have no
+                    // business firing during `vite build`. A string check for the
+                    // known export shapes is enough to catch typos and forgotten
+                    // exports, which is the failure mode users actually hit.
+                    let entrySource;
+                    try {
+                        entrySource = fs.readFileSync(entryAbs, 'utf8');
+                    }
+                    catch (readErr) {
+                        errors.push(`aiAgentProviders[${providerId}].backendModuleId "${backendModuleId}" ` +
+                            `points at entry ${entryRel} which exists but could not be read (${String(readErr)}). ` +
+                            'The validator needs to scan the entry for an activate / createAgentProvider export.');
+                        continue;
+                    }
+                    // Look for either a top-level `export function activate` /
+                    // `export const activate` / `export { activate }`, or the same
+                    // shapes for `createAgentProvider`. Bundlers normalize these in
+                    // varied ways; the union of these patterns covers Vite, esbuild,
+                    // and tsc output. We do NOT match `exports.activate =` because
+                    // backend modules ship as ESM; CJS output would have been flagged
+                    // by the `require(` check earlier in this function anyway.
+                    const exportPatterns = [
+                        /export\s+(?:async\s+)?function\s+activate\b/,
+                        /export\s+(?:const|let|var)\s+activate\b/,
+                        /export\s*\{[^}]*\bactivate\b[^}]*\}/,
+                        /export\s+(?:async\s+)?function\s+createAgentProvider\b/,
+                        /export\s+(?:const|let|var)\s+createAgentProvider\b/,
+                        /export\s*\{[^}]*\bcreateAgentProvider\b[^}]*\}/,
+                    ];
+                    const hasExport = exportPatterns.some((p) => p.test(entrySource));
+                    if (!hasExport) {
+                        errors.push(`aiAgentProviders[${providerId}].backendModuleId "${backendModuleId}" ` +
+                            `resolves to ${entryRel}, but the entry file does not appear to export ` +
+                            'an `activate` or `createAgentProvider` function. The privileged host calls one ' +
+                            'of these to bring the provider online.');
+                    }
+                }
+            }
         }
         catch (e) {
             errors.push(`Failed to parse manifest.json: ${e}`);

package/dist/validationTypes.d.ts

@@ -0,0 +1,9 @@
+export interface ValidationResult {
+    /** Whether the bundle passed validation */
+    valid: boolean;
+    /** Critical errors that will cause runtime failures */
+    errors: string[];
+    /** Warnings that may cause issues */
+    warnings: string[];
+}
+//# sourceMappingURL=validationTypes.d.ts.map

package/dist/validationTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validationTypes.d.ts","sourceRoot":"","sources":["../src/validationTypes.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,gBAAgB;IAC/B,2CAA2C;IAC3C,KAAK,EAAE,OAAO,CAAC;IAEf,uDAAuD;IACvD,MAAM,EAAE,MAAM,EAAE,CAAC;IAEjB,qCAAqC;IACrC,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB"}

package/dist/validationTypes.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nimbalyst/extension-sdk",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "SDK for building Nimbalyst extensions",
   "repository": {
     "type": "git",
@@ -13,6 +13,9 @@
   },
   "type": "module",
   "sideEffects": false,
+  "browser": {
+    "./dist/validate.js": "./dist/validate.browser.js"
+  },
   "nimbalyst": {
     "minAppVersion": "0.58.5"
   },