@nimbalyst/extension-sdk 0.1.5 → 0.2.1

package/dist/useCollaborativeEditor.d.ts

@@ -0,0 +1,165 @@
+/**
+ * useCollaborativeEditor Hook
+ *
+ * Companion to `useEditorLifecycle` for collaborative documents. When the
+ * host opens a file with `host.collaboration` defined, this hook manages the
+ * binding lifecycle: wait for sync, optionally seed the Y.Doc from file
+ * content if this client is first, create the editor's binding, destroy on
+ * unmount.
+ *
+ * Extensions wire it like this:
+ *
+ * ```tsx
+ * function MyEditor({ host }: EditorHostProps) {
+ *   const apiRef = useRef<MyImperativeAPI | null>(null);
+ *
+ *   // Local-only path (unchanged for non-collab opens).
+ *   const { isLoading } = useEditorLifecycle(host, { ... });
+ *
+ *   // Collaborative path (no-op when host.collaboration is undefined).
+ *   const { isCollaborative, status, collaborators } = useCollaborativeEditor(host, {
+ *     createBinding: ({ yDoc, awareness, user }) => {
+ *       const b = new MyBinding(yDoc, apiRef.current!, awareness, user);
+ *       return { destroy: () => b.destroy() };
+ *     },
+ *     initializeFromContent: (yDoc, content) => seedYDocFromFile(yDoc, content),
+ *   });
+ *
+ *   return <MyLibrary ref={apiRef} ... />;
+ * }
+ * ```
+ *
+ * Bootstrap-race safety: if two clients both open an empty document, both
+ * will call `initializeFromContent` and their CRDT updates merge. To avoid
+ * duplicate elements your seeded shared types MUST use **content-derived
+ * stable IDs** (e.g. element `id` from the file), not random IDs. The same
+ * input yields the same Y.Doc state; merged duplicates collapse.
+ */
+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
+ * against this to suppress their own change handlers during seeding
+ * (otherwise the binding would echo the seed back into local-edit state).
+ *
+ * ```ts
+ * yDoc.on('update', (update, origin) => {
+ *   if (origin === COLLAB_INIT_ORIGIN) return;
+ *   // ... apply remote change
+ * });
+ * ```
+ */
+export declare const COLLAB_INIT_ORIGIN: unique symbol;
+/** 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). May return
+     * a Promise so extensions can defer construction until their imperative API
+     * has finished mounting; the hook awaits it and honors cancellation.
+     */
+    bind(ctx: CollabBindContext): CollabBindResult;
+    /**
+     * 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;
+    /**
+     * @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;
+    /** Current connection status. Always `'disconnected'` when not collab. */
+    status: CollaborationStatus;
+    /**
+     * Remote collaborators keyed by their stable user id (not the y-protocols
+     * client id). Mirrors awareness; updated when remote presence changes.
+     */
+    collaborators: Map<string, CollaboratorInfo>;
+    /**
+     * 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

@@ -0,0 +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;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

@@ -0,0 +1,253 @@
+/**
+ * useCollaborativeEditor Hook
+ *
+ * Companion to `useEditorLifecycle` for collaborative documents. When the
+ * host opens a file with `host.collaboration` defined, this hook manages the
+ * binding lifecycle: wait for sync, optionally seed the Y.Doc from file
+ * content if this client is first, create the editor's binding, destroy on
+ * unmount.
+ *
+ * Extensions wire it like this:
+ *
+ * ```tsx
+ * function MyEditor({ host }: EditorHostProps) {
+ *   const apiRef = useRef<MyImperativeAPI | null>(null);
+ *
+ *   // Local-only path (unchanged for non-collab opens).
+ *   const { isLoading } = useEditorLifecycle(host, { ... });
+ *
+ *   // Collaborative path (no-op when host.collaboration is undefined).
+ *   const { isCollaborative, status, collaborators } = useCollaborativeEditor(host, {
+ *     createBinding: ({ yDoc, awareness, user }) => {
+ *       const b = new MyBinding(yDoc, apiRef.current!, awareness, user);
+ *       return { destroy: () => b.destroy() };
+ *     },
+ *     initializeFromContent: (yDoc, content) => seedYDocFromFile(yDoc, content),
+ *   });
+ *
+ *   return <MyLibrary ref={apiRef} ... />;
+ * }
+ * ```
+ *
+ * Bootstrap-race safety: if two clients both open an empty document, both
+ * will call `initializeFromContent` and their CRDT updates merge. To avoid
+ * duplicate elements your seeded shared types MUST use **content-derived
+ * stable IDs** (e.g. element `id` from the file), not random IDs. The same
+ * input yields the same Y.Doc state; merged duplicates collapse.
+ */
+import { useEffect, useRef, useState } from 'react';
+import * as Y from 'yjs';
+/**
+ * Origin tag used when the SDK wraps `initializeFromContent` in a Y.Doc
+ * transaction. Extension bindings can compare a transaction's origin
+ * against this to suppress their own change handlers during seeding
+ * (otherwise the binding would echo the seed back into local-edit state).
+ *
+ * ```ts
+ * yDoc.on('update', (update, origin) => {
+ *   if (origin === COLLAB_INIT_ORIGIN) return;
+ *   // ... apply remote change
+ * });
+ * ```
+ */
+export const COLLAB_INIT_ORIGIN = Symbol('nimbalyst:collab-init');
+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".
+    const configRef = useRef(config);
+    configRef.current = config;
+    // Status subscription.
+    useEffect(() => {
+        const collab = host.collaboration;
+        if (!collab) {
+            setStatus('disconnected');
+            return;
+        }
+        setStatus(collab.getStatus());
+        return collab.onStatusChange(setStatus);
+    }, [host]);
+    // Awareness subscription -> collaborators map. The host populates the
+    // standard `user: { id, name, color }` field on every remote awareness
+    // state via the StandardAwarenessState contract.
+    useEffect(() => {
+        const collab = host.collaboration;
+        if (!collab) {
+            setCollaborators(new Map());
+            return;
+        }
+        const rebuild = () => {
+            const next = new Map();
+            const states = collab.awareness.getStates();
+            for (const [clientId, state] of states) {
+                // Don't include ourselves.
+                if (clientId === collab.awareness.clientID)
+                    continue;
+                const user = state.user;
+                if (!user || !user.id)
+                    continue;
+                next.set(user.id, { user });
+            }
+            setCollaborators(next);
+        };
+        rebuild();
+        collab.awareness.on('change', rebuild);
+        return () => collab.awareness.off('change', rebuild);
+    }, [host]);
+    // Binding lifecycle.
+    useEffect(() => {
+        const collab = host.collaboration;
+        if (!collab)
+            return;
+        let cancelled = false;
+        let handle = null;
+        const tryStart = async () => {
+            if (cancelled || handle)
+                return;
+            if (collab.getStatus() !== 'connected')
+                return;
+            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.
+                    else if (cfg.isEmpty(collab.yDoc)) {
+                        collab.yDoc.transact(() => {
+                            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;
+            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();
+        const unsubscribe = collab.onStatusChange(() => {
+            void tryStart();
+        });
+        return () => {
+            cancelled = true;
+            unsubscribe();
+            if (handle) {
+                handle.destroy();
+                handle = null;
+            }
+            setBinding(null);
+        };
+    }, [host]);
+    return { isCollaborative, status, collaborators, binding, seedError };
+}

package/dist/useEditorLifecycle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useEditorLifecycle.d.ts","sourceRoot":"","sources":["../src/useEditorLifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAMhE,MAAM,WAAW,yBAAyB,CAAC,CAAC;IAC1C;;;;;OAKG;IACH,YAAY,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,IAAI,CAAC;IAEnC;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC,CAAC;IAE5B;;;OAGG;IACH,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,CAAC,CAAC;IAE3B;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,MAAM,CAAC;IAEnC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IAEtB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,IAAI,CAAC;IAExC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7B;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC;IAE/C;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,SAAS,CAAC,CAAC;IAC1B,iCAAiC;IACjC,QAAQ,EAAE,CAAC,CAAC;IAEZ,qDAAqD;IACrD,QAAQ,EAAE,CAAC,CAAC;IAEZ,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IAEd,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;IAElB,8BAA8B;IAC9B,MAAM,EAAE,MAAM,IAAI,CAAC;IAEnB,mDAAmD;IACnD,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AAED,MAAM,WAAW,wBAAwB,CAAC,CAAC;IACzC;;;OAGG;IACH,SAAS,EAAE,MAAM,IAAI,CAAC;IAEtB,gDAAgD;IAChD,SAAS,EAAE,OAAO,CAAC;IAEnB,wCAAwC;IACxC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAEpB,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IAEd,8CAA8C;IAC9C,OAAO,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAE/B,iFAAiF;IACjF,gBAAgB,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAC;IAE3C,+CAA+C;IAC/C,YAAY,EAAE,OAAO,CAAC;CACvB;AAMD,wBAAgB,kBAAkB,CAAC,CAAC,GAAG,MAAM,EAC3C,IAAI,EAAE,UAAU,EAChB,OAAO,EAAE,yBAAyB,CAAC,CAAC,CAAC,GACpC,wBAAwB,CAAC,CAAC,CAAC,CA+R7B"}
+{"version":3,"file":"useEditorLifecycle.d.ts","sourceRoot":"","sources":["../src/useEditorLifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAMhE,MAAM,WAAW,yBAAyB,CAAC,CAAC;IAC1C;;;;;OAKG;IACH,YAAY,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,IAAI,CAAC;IAEnC;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC,CAAC;IAE5B;;;OAGG;IACH,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,CAAC,CAAC;IAE3B;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,MAAM,CAAC;IAEnC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IAEtB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,IAAI,CAAC;IAExC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7B;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC;IAE/C;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,SAAS,CAAC,CAAC;IAC1B,iCAAiC;IACjC,QAAQ,EAAE,CAAC,CAAC;IAEZ,qDAAqD;IACrD,QAAQ,EAAE,CAAC,CAAC;IAEZ,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IAEd,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;IAElB,8BAA8B;IAC9B,MAAM,EAAE,MAAM,IAAI,CAAC;IAEnB,mDAAmD;IACnD,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AAED,MAAM,WAAW,wBAAwB,CAAC,CAAC;IACzC;;;OAGG;IACH,SAAS,EAAE,MAAM,IAAI,CAAC;IAEtB,gDAAgD;IAChD,SAAS,EAAE,OAAO,CAAC;IAEnB,wCAAwC;IACxC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAEpB,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IAEd,8CAA8C;IAC9C,OAAO,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAE/B,iFAAiF;IACjF,gBAAgB,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAC;IAE3C,+CAA+C;IAC/C,YAAY,EAAE,OAAO,CAAC;CACvB;AAMD,wBAAgB,kBAAkB,CAAC,CAAC,GAAG,MAAM,EAC3C,IAAI,EAAE,UAAU,EAChB,OAAO,EAAE,yBAAyB,CAAC,CAAC,CAAC,GACpC,wBAAwB,CAAC,CAAC,CAAC,CAiS7B"}

package/dist/useEditorLifecycle.js

@@ -81,8 +81,6 @@ export function useEditorLifecycle(host, options) {
     optionsRef.current = options;
     // Echo detection: stores the last serialized string we saved
     const lastSavedContentRef = useRef('');
-    // Prevent double-loading
-    const loadedRef = useRef(false);
     // Track dirty state in a ref too (for use in callbacks without stale closure)
     const isDirtyRef = useRef(false);
     // ---- Parse / Serialize helpers ----
@@ -118,10 +116,16 @@ export function useEditorLifecycle(host, options) {
         }
     }, [host]);
     // ---- Initial load ----
+    // Note: do NOT use a ref-based "already loaded" guard here. React 18
+    // StrictMode in dev runs effects setup -> cleanup -> setup. A persistent
+    // ref makes the second setup early-return, while the first run's `mounted`
+    // closure has already been flipped to false by cleanup, so
+    // `setIsLoading(false)` is never called and the editor is stuck on the
+    // initial Loading state forever. The dep array (`[host, parseContent]`)
+    // already prevents re-loads when nothing has changed; the strict-mode
+    // double load is idempotent (same IPC + applyContent) and only happens in
+    // dev.
     useEffect(() => {
-        if (loadedRef.current)
-            return;
-        loadedRef.current = true;
         let mounted = true;
         const doLoad = async () => {
             try {

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