@nimbalyst/extension-sdk 0.1.0

package/dist/types/theme.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Core types for Nimbalyst theme system.
+ *
+ * Themes are separate from extensions - they provide styling only, no code.
+ * This module defines the schema for theme.json manifests and theme metadata.
+ */
+/**
+ * Available theme color keys that can be overridden.
+ * These map to CSS variables (--nim-*) used throughout the UI.
+ */
+export type ThemeColorKey = 'bg' | 'bg-secondary' | 'bg-tertiary' | 'bg-hover' | 'bg-selected' | 'bg-active' | 'text' | 'text-muted' | 'text-faint' | 'text-disabled' | 'border' | 'border-focus' | 'primary' | 'primary-hover' | 'link' | 'link-hover' | 'success' | 'warning' | 'error' | 'info';
+/**
+ * Theme color values.
+ * All colors are optional - missing colors will fall back to base theme.
+ */
+export type ThemeColors = Partial<Record<ThemeColorKey, string>>;
+/**
+ * Theme manifest schema (theme.json).
+ * This is the schema for standalone theme packages.
+ */
+export interface ThemeManifest {
+    /** Unique theme identifier (e.g., 'solarized-dark') */
+    id: string;
+    /** Display name shown in UI */
+    name: string;
+    /** Semantic version */
+    version: string;
+    /** Theme author name or organization */
+    author?: string;
+    /** Brief description */
+    description?: string;
+    /** Whether this is a dark theme (determines base theme for fallbacks) */
+    isDark: boolean;
+    /**
+     * Theme color overrides.
+     * Only include colors you want to override from the base theme.
+     * All color values must be valid hex codes or CSS color names.
+     */
+    colors: ThemeColors;
+    /** Path to preview image (relative to theme.json) */
+    preview?: string;
+    /** Tags for discovery and filtering */
+    tags?: string[];
+    /** License identifier (SPDX) */
+    license?: string;
+    /** Homepage or repository URL */
+    homepage?: string;
+}
+/**
+ * Full theme object with metadata and resolved colors.
+ * This is what's used at runtime after loading a theme.
+ */
+export interface Theme {
+    /** Theme ID (unique across all themes) */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Semantic version */
+    version: string;
+    /** Author */
+    author?: string;
+    /** Description */
+    description?: string;
+    /** Is dark theme */
+    isDark: boolean;
+    /** Resolved color values (merged with base theme) */
+    colors: ThemeColors;
+    /** Tags */
+    tags?: string[];
+    /** Preview image path (absolute) */
+    previewPath?: string;
+    /** Source of the theme */
+    source: ThemeSource;
+}
+/**
+ * Where the theme came from.
+ */
+export type ThemeSource = {
+    type: 'builtin';
+} | {
+    type: 'user';
+    installPath: string;
+} | {
+    type: 'extension';
+    extensionId: string;
+};
+/**
+ * Marketplace theme metadata.
+ * Used for browsing and discovering themes before installation.
+ */
+export interface MarketplaceTheme {
+    /** Theme ID */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Author */
+    author: string;
+    /** Version */
+    version: string;
+    /** Description */
+    description: string;
+    /** Download count */
+    downloads: number;
+    /** Average rating (0-5) */
+    rating: number;
+    /** Tags */
+    tags: string[];
+    /** URL to preview image */
+    preview: string;
+    /** URL to download .nimtheme file */
+    downloadUrl: string;
+    /** Last update timestamp */
+    lastUpdated: string;
+    /** License */
+    license?: string;
+    /** Homepage URL */
+    homepage?: string;
+}
+/**
+ * Theme validation result.
+ */
+export interface ThemeValidationResult {
+    /** Whether the theme is valid */
+    valid: boolean;
+    /** Validation errors (if any) */
+    errors: string[];
+    /** Validation warnings (non-fatal) */
+    warnings: string[];
+}
+/**
+ * Theme installation options.
+ */
+export interface ThemeInstallOptions {
+    /** Path to .nimtheme file or directory */
+    source: string;
+    /** Whether to overwrite existing theme with same ID */
+    overwrite?: boolean;
+}
+/**
+ * Theme uninstall options.
+ */
+export interface ThemeUninstallOptions {
+    /** Theme ID to uninstall */
+    themeId: string;
+    /** Whether to keep theme files (just disable) */
+    keepFiles?: boolean;
+}
+//# sourceMappingURL=theme.d.ts.map

package/dist/types/theme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme.d.ts","sourceRoot":"","sources":["../../src/types/theme.ts"],"names":[],"mappings":"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"}

package/dist/types/theme.js

@@ -0,0 +1,7 @@
+/**
+ * Core types for Nimbalyst theme system.
+ *
+ * Themes are separate from extensions - they provide styling only, no code.
+ * This module defines the schema for theme.json manifests and theme metadata.
+ */
+export {};

package/dist/useEditorLifecycle.d.ts

@@ -0,0 +1,166 @@
+/**
+ * useEditorLifecycle Hook
+ *
+ * The single hook for custom editors to integrate with the EditorHost API.
+ * Handles all lifecycle concerns: loading, saving, echo detection, dirty state,
+ * file change handling, diff mode, theme changes.
+ *
+ * Content state NEVER lives in this hook. The hook interacts with the editor's
+ * state through pull/push callbacks:
+ * - applyContent: push new content INTO the editor (on load, external file change)
+ * - getCurrentContent: pull current content FROM the editor (on save)
+ *
+ * This design works for all editor types:
+ * - Library-managed (Excalidraw, Three.js): callbacks talk to the library's imperative API
+ * - Store-managed (Mindmap, DatamodelLM): callbacks talk to a Zustand store
+ * - Read-only (PDF, SQLite): only applyContent, no getCurrentContent
+ *
+ * @example Library-managed editor (Excalidraw)
+ * ```tsx
+ * function ExcalidrawEditor({ host }: EditorHostProps) {
+ *   const apiRef = useRef<ExcalidrawImperativeAPI>(null);
+ *
+ *   const { markDirty, isLoading, theme } = useEditorLifecycle(host, {
+ *     applyContent: (elements) => apiRef.current?.updateScene({ elements }),
+ *     getCurrentContent: () => apiRef.current?.getSceneElements() ?? [],
+ *     parse: (raw) => JSON.parse(raw).elements,
+ *     serialize: (elements) => JSON.stringify({ elements }),
+ *   });
+ *
+ *   return <Excalidraw ref={apiRef} onChange={(el) => { if (changed(el)) markDirty(); }} />;
+ * }
+ * ```
+ *
+ * @example Store-managed editor (Mindmap)
+ * ```tsx
+ * function MindmapEditor({ host }: EditorHostProps) {
+ *   const storeRef = useRef(createMindmapStore());
+ *   const store = storeRef.current;
+ *
+ *   const { markDirty } = useEditorLifecycle(host, {
+ *     applyContent: (doc) => store.getState().loadDocument(doc),
+ *     getCurrentContent: () => store.getState().document,
+ *     parse: parseDocument,
+ *     serialize: serializeDocument,
+ *   });
+ *
+ *   return <MindmapCanvas store={store} markDirty={markDirty} />;
+ * }
+ * ```
+ *
+ * @example Read-only viewer (PDF)
+ * ```tsx
+ * function PDFViewer({ host }: EditorHostProps) {
+ *   const dataRef = useRef<ArrayBuffer | null>(null);
+ *   const [, forceRender] = useReducer((x) => x + 1, 0);
+ *
+ *   const { isLoading } = useEditorLifecycle(host, {
+ *     applyContent: (data) => { dataRef.current = data; forceRender(); },
+ *     binary: true,
+ *   });
+ *
+ *   return isLoading ? <Loading /> : <PDFRenderer data={dataRef.current} />;
+ * }
+ * ```
+ */
+import type { EditorHost, DiffConfig } from './types/editor.js';
+export interface UseEditorLifecycleOptions<T> {
+    /**
+     * Push new content into the editor.
+     * Called on initial load and on external file changes.
+     * This should update the editor's internal state WITHOUT triggering
+     * a React re-render of the entire editor tree.
+     */
+    applyContent: (content: T) => void;
+    /**
+     * Pull current content from the editor for saving.
+     * Omit for read-only editors (PDF viewer, SQLite browser, etc.)
+     */
+    getCurrentContent?: () => T;
+    /**
+     * Parse raw file content (string) into the editor's internal format.
+     * If omitted, raw string is passed through as-is.
+     */
+    parse?: (raw: string) => T;
+    /**
+     * Serialize editor's internal format back to string for saving.
+     * If omitted, String(content) is used.
+     */
+    serialize?: (content: T) => string;
+    /**
+     * Use loadBinaryContent() instead of loadContent().
+     * For binary file formats (PDF, SQLite, images, etc.)
+     * When true, parse/serialize are ignored -- applyContent receives the raw
+     * ArrayBuffer and getCurrentContent should return an ArrayBuffer.
+     */
+    binary?: boolean;
+    /**
+     * Called after initial content is loaded and applied.
+     * Use for post-load setup (e.g., fitting viewport to content).
+     */
+    onLoaded?: () => void;
+    /**
+     * Called when an external file change is detected and applied.
+     * NOT called for echoes from our own saves.
+     * Use for editor-specific reactions to external changes (e.g., re-layout).
+     */
+    onExternalChange?: (content: T) => void;
+    /**
+     * Custom save handler. When provided, replaces the default
+     * getCurrentContent -> serialize -> saveContent flow.
+     * Use for editors that require async content extraction (e.g., RevoGrid).
+     * The hook still handles dirty state clearing after onSave resolves.
+     */
+    onSave?: () => Promise<void>;
+    /**
+     * Custom diff request handler. When provided, replaces the default
+     * diff parsing and state management. The editor manages its own diff state.
+     * Use for editors with specialized diff rendering (e.g., cell-level CSV diff).
+     */
+    onDiffRequested?: (config: DiffConfig) => void;
+    /**
+     * Custom diff cleared handler. When provided, replaces the default
+     * diff cleared behavior (reload from disk). Paired with onDiffRequested.
+     */
+    onDiffCleared?: () => Promise<void>;
+}
+export interface DiffState<T> {
+    /** Content before the AI edit */
+    original: T;
+    /** Content after the AI edit (what's on disk now) */
+    modified: T;
+    /** History tag ID for this diff */
+    tagId: string;
+    /** AI session ID that made the edit */
+    sessionId: string;
+    /** Accept the AI's changes */
+    accept: () => void;
+    /** Reject the AI's changes (revert to original) */
+    reject: () => void;
+}
+export interface UseEditorLifecycleResult<T> {
+    /**
+     * Call when the user makes an edit. Marks the document dirty.
+     * No-op for read-only editors (when getCurrentContent is not provided).
+     */
+    markDirty: () => void;
+    /** Whether initial content is still loading. */
+    isLoading: boolean;
+    /** Error from initial load, or null. */
+    error: Error | null;
+    /** Current theme (reactive -- updates when user changes theme). */
+    theme: string;
+    /** Whether the editor has unsaved changes. */
+    isDirty: boolean;
+    /**
+     * Diff state when AI proposes changes. null when not in diff mode.
+     * Editors should render a diff view when this is non-null.
+     */
+    diffState: DiffState<T> | null;
+    /** Toggle source mode (switches to Monaco). Only present if host supports it. */
+    toggleSourceMode: (() => void) | undefined;
+    /** Whether source mode is currently active. */
+    isSourceMode: boolean;
+}
+export declare function useEditorLifecycle<T = string>(host: EditorHost, options: UseEditorLifecycleOptions<T>): UseEditorLifecycleResult<T>;
+//# sourceMappingURL=useEditorLifecycle.d.ts.map

package/dist/useEditorLifecycle.d.ts.map

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

package/dist/useEditorLifecycle.js

@@ -0,0 +1,327 @@
+/**
+ * useEditorLifecycle Hook
+ *
+ * The single hook for custom editors to integrate with the EditorHost API.
+ * Handles all lifecycle concerns: loading, saving, echo detection, dirty state,
+ * file change handling, diff mode, theme changes.
+ *
+ * Content state NEVER lives in this hook. The hook interacts with the editor's
+ * state through pull/push callbacks:
+ * - applyContent: push new content INTO the editor (on load, external file change)
+ * - getCurrentContent: pull current content FROM the editor (on save)
+ *
+ * This design works for all editor types:
+ * - Library-managed (Excalidraw, Three.js): callbacks talk to the library's imperative API
+ * - Store-managed (Mindmap, DatamodelLM): callbacks talk to a Zustand store
+ * - Read-only (PDF, SQLite): only applyContent, no getCurrentContent
+ *
+ * @example Library-managed editor (Excalidraw)
+ * ```tsx
+ * function ExcalidrawEditor({ host }: EditorHostProps) {
+ *   const apiRef = useRef<ExcalidrawImperativeAPI>(null);
+ *
+ *   const { markDirty, isLoading, theme } = useEditorLifecycle(host, {
+ *     applyContent: (elements) => apiRef.current?.updateScene({ elements }),
+ *     getCurrentContent: () => apiRef.current?.getSceneElements() ?? [],
+ *     parse: (raw) => JSON.parse(raw).elements,
+ *     serialize: (elements) => JSON.stringify({ elements }),
+ *   });
+ *
+ *   return <Excalidraw ref={apiRef} onChange={(el) => { if (changed(el)) markDirty(); }} />;
+ * }
+ * ```
+ *
+ * @example Store-managed editor (Mindmap)
+ * ```tsx
+ * function MindmapEditor({ host }: EditorHostProps) {
+ *   const storeRef = useRef(createMindmapStore());
+ *   const store = storeRef.current;
+ *
+ *   const { markDirty } = useEditorLifecycle(host, {
+ *     applyContent: (doc) => store.getState().loadDocument(doc),
+ *     getCurrentContent: () => store.getState().document,
+ *     parse: parseDocument,
+ *     serialize: serializeDocument,
+ *   });
+ *
+ *   return <MindmapCanvas store={store} markDirty={markDirty} />;
+ * }
+ * ```
+ *
+ * @example Read-only viewer (PDF)
+ * ```tsx
+ * function PDFViewer({ host }: EditorHostProps) {
+ *   const dataRef = useRef<ArrayBuffer | null>(null);
+ *   const [, forceRender] = useReducer((x) => x + 1, 0);
+ *
+ *   const { isLoading } = useEditorLifecycle(host, {
+ *     applyContent: (data) => { dataRef.current = data; forceRender(); },
+ *     binary: true,
+ *   });
+ *
+ *   return isLoading ? <Loading /> : <PDFRenderer data={dataRef.current} />;
+ * }
+ * ```
+ */
+import { useState, useEffect, useRef, useCallback } from 'react';
+// ============================================================================
+// Hook Implementation
+// ============================================================================
+export function useEditorLifecycle(host, options) {
+    // -- React state: only for things that SHOULD cause re-renders --
+    const [isLoading, setIsLoading] = useState(true);
+    const [error, setError] = useState(null);
+    const [isDirty, setIsDirty] = useState(false);
+    const [theme, setTheme] = useState(host.theme);
+    const [diffState, setDiffState] = useState(null);
+    const [isSourceMode, setIsSourceMode] = useState(host.isSourceModeActive?.() ?? false);
+    // -- Refs: for everything that should NOT cause re-renders --
+    // Options ref -- updated every render so callbacks are never stale
+    const optionsRef = useRef(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 ----
+    const parseContent = useCallback((raw) => {
+        const { parse } = optionsRef.current;
+        if (parse)
+            return parse(raw);
+        return raw;
+    }, [] // stable -- reads from ref
+    );
+    const serializeContent = useCallback((content) => {
+        const { serialize } = optionsRef.current;
+        if (serialize)
+            return serialize(content);
+        return String(content);
+    }, [] // stable -- reads from ref
+    );
+    // ---- markDirty ----
+    const markDirty = useCallback(() => {
+        if (!optionsRef.current.getCurrentContent)
+            return; // read-only
+        if (!isDirtyRef.current) {
+            isDirtyRef.current = true;
+            setIsDirty(true);
+            host.setDirty(true);
+        }
+    }, [host]);
+    const clearDirty = useCallback(() => {
+        if (isDirtyRef.current) {
+            isDirtyRef.current = false;
+            setIsDirty(false);
+            host.setDirty(false);
+        }
+    }, [host]);
+    // ---- Initial load ----
+    useEffect(() => {
+        if (loadedRef.current)
+            return;
+        loadedRef.current = true;
+        let mounted = true;
+        const doLoad = async () => {
+            try {
+                const opts = optionsRef.current;
+                if (opts.binary) {
+                    const data = await host.loadBinaryContent();
+                    if (!mounted)
+                        return;
+                    opts.applyContent(data);
+                }
+                else {
+                    const raw = await host.loadContent();
+                    if (!mounted)
+                        return;
+                    const parsed = parseContent(raw);
+                    lastSavedContentRef.current = raw;
+                    opts.applyContent(parsed);
+                }
+                if (!mounted)
+                    return;
+                setIsLoading(false);
+                optionsRef.current.onLoaded?.();
+            }
+            catch (err) {
+                if (!mounted)
+                    return;
+                const loadError = err instanceof Error ? err : new Error(String(err));
+                setError(loadError);
+                setIsLoading(false);
+            }
+        };
+        doLoad();
+        return () => {
+            mounted = false;
+        };
+    }, [host, parseContent]);
+    // ---- Save handling ----
+    useEffect(() => {
+        return host.onSaveRequested(async () => {
+            const opts = optionsRef.current;
+            try {
+                if (opts.onSave) {
+                    // Custom save handler (e.g., async content extraction from RevoGrid)
+                    await opts.onSave();
+                }
+                else {
+                    if (!opts.getCurrentContent)
+                        return; // read-only
+                    const content = opts.getCurrentContent();
+                    if (opts.binary) {
+                        await host.saveContent(content);
+                    }
+                    else {
+                        const serialized = serializeContent(content);
+                        // Update echo detection BEFORE saving so the subsequent onFileChanged is ignored
+                        lastSavedContentRef.current = serialized;
+                        await host.saveContent(serialized);
+                    }
+                }
+                clearDirty();
+            }
+            catch (err) {
+                // Save failed -- dirty state remains
+            }
+        });
+    }, [host, serializeContent, clearDirty]);
+    // ---- External file changes ----
+    useEffect(() => {
+        return host.onFileChanged((newRawContent) => {
+            // Echo detection: ignore if this is our own save echoing back
+            if (newRawContent === lastSavedContentRef.current) {
+                return;
+            }
+            const opts = optionsRef.current;
+            try {
+                const parsed = parseContent(newRawContent);
+                lastSavedContentRef.current = newRawContent;
+                opts.applyContent(parsed);
+                clearDirty();
+                opts.onExternalChange?.(parsed);
+            }
+            catch (err) {
+                // Failed to parse external change
+            }
+        });
+    }, [host, parseContent, clearDirty]);
+    // ---- Theme changes ----
+    useEffect(() => {
+        return host.onThemeChanged((newTheme) => {
+            setTheme(newTheme);
+        });
+    }, [host]);
+    // ---- Diff mode ----
+    useEffect(() => {
+        if (!host.onDiffRequested)
+            return;
+        const unsubDiff = host.onDiffRequested((config) => {
+            const opts = optionsRef.current;
+            // Custom diff handler -- editor manages its own diff state
+            if (opts.onDiffRequested) {
+                opts.onDiffRequested(config);
+                return;
+            }
+            let original;
+            let modified;
+            try {
+                original = opts.binary
+                    ? config.originalContent
+                    : parseContent(config.originalContent);
+                modified = opts.binary
+                    ? config.modifiedContent
+                    : parseContent(config.modifiedContent);
+            }
+            catch (err) {
+                return;
+            }
+            setDiffState({
+                original,
+                modified,
+                tagId: config.tagId,
+                sessionId: config.sessionId,
+                accept: () => {
+                    // Accept: apply modified content, report result
+                    optionsRef.current.applyContent(modified);
+                    if (!opts.binary) {
+                        lastSavedContentRef.current =
+                            serializeContent(modified);
+                    }
+                    host.reportDiffResult?.({
+                        content: opts.binary
+                            ? ''
+                            : serializeContent(modified),
+                        action: 'accept',
+                    });
+                    clearDirty();
+                    setDiffState(null);
+                },
+                reject: () => {
+                    // Reject: apply original content, report result
+                    optionsRef.current.applyContent(original);
+                    if (!opts.binary) {
+                        lastSavedContentRef.current =
+                            serializeContent(original);
+                    }
+                    host.reportDiffResult?.({
+                        content: opts.binary
+                            ? ''
+                            : serializeContent(original),
+                        action: 'reject',
+                    });
+                    clearDirty();
+                    setDiffState(null);
+                },
+            });
+        });
+        return unsubDiff;
+    }, [host, parseContent, serializeContent, clearDirty]);
+    // Handle diff cleared externally (via unified diff header)
+    useEffect(() => {
+        if (!host.onDiffCleared)
+            return;
+        return host.onDiffCleared(async () => {
+            const opts = optionsRef.current;
+            // Custom diff cleared handler
+            if (opts.onDiffCleared) {
+                await opts.onDiffCleared();
+                return;
+            }
+            setDiffState(null);
+            // Reload content since the file may have changed
+            if (!opts.binary) {
+                host.loadContent().then((raw) => {
+                    const parsed = parseContent(raw);
+                    lastSavedContentRef.current = raw;
+                    optionsRef.current.applyContent(parsed);
+                    clearDirty();
+                });
+            }
+        });
+    }, [host, parseContent, clearDirty]);
+    // ---- Source mode ----
+    useEffect(() => {
+        if (!host.onSourceModeChanged)
+            return;
+        return host.onSourceModeChanged((isActive) => {
+            setIsSourceMode(isActive);
+        });
+    }, [host]);
+    const toggleSourceMode = host.toggleSourceMode
+        ? useCallback(() => host.toggleSourceMode?.(), [host])
+        : undefined;
+    // ---- Return ----
+    return {
+        markDirty,
+        isLoading,
+        error,
+        theme,
+        isDirty,
+        diffState,
+        toggleSourceMode,
+        isSourceMode,
+    };
+}

package/dist/validate.d.ts

@@ -0,0 +1,31 @@
+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[];
+}
+/**
+ * Validates an extension bundle for common issues.
+ *
+ * Run this after building to catch configuration mistakes before runtime.
+ *
+ * @param distPath - Path to the dist directory containing the bundle
+ * @param bundleName - Name of the bundle file (default: 'index.js')
+ *
+ * @example
+ * ```ts
+ * const result = await validateExtensionBundle('./dist');
+ * if (!result.valid) {
+ *   console.error('Build failed:', result.errors);
+ *   process.exit(1);
+ * }
+ * ```
+ */
+export declare function validateExtensionBundle(distPath: string, bundleName?: string): Promise<ValidationResult>;
+/**
+ * Prints validation results to console with formatting.
+ */
+export declare function printValidationResult(result: ValidationResult): void;
+//# sourceMappingURL=validate.d.ts.map