@nimbalyst/extension-sdk 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to `@nimbalyst/extension-sdk` are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this package follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+The SDK is versioned independently of the Nimbalyst app. Each release declares its minimum compatible app version under the `nimbalyst.minAppVersion` field of `package.json`.
+
+| SDK version | Minimum Nimbalyst app version |
+| --- | --- |
+| 0.1.0 | 0.58.5 |
+
+## [Unreleased]
+
+## [0.1.0] - Initial release
+
+Initial public release of the Nimbalyst extension SDK.
+
+### Added
+
+- `EditorHost` and `EditorHostProps` contract for custom editor extensions
+- `useEditorLifecycle` hook for editor load/save/dirty/theme handling
+- `ExtensionAITool`, `AIToolContext`, `ExtensionToolResult` types for AI tool extensions
+- `ExtensionContext`, `ExtensionManifest`, `ExtensionContributions` for the extension manifest schema
+- `PanelContribution`, `PanelExport`, `PanelHost` for non-file-based panels
+- `SettingsPanelContribution`, `SettingsPanelProps` for extension settings panels
+- `ThemeContribution` and `ThemeColors` for custom theme extensions
+- `createExtensionConfig` Vite helper at `@nimbalyst/extension-sdk/vite`
+- `createManifestValidationPlugin` Vite plugin to validate build output against `manifest.json`
+- `mergeExtensionConfig` for extending the base Vite config
+- Tailwind preset at `@nimbalyst/extension-sdk/tailwind`
+- Testing utilities at `@nimbalyst/extension-sdk/testing`
+- `ROLLUP_EXTERNALS`, `REQUIRED_EXTERNALS`, `EXTERNAL_PATTERNS` constants for the externals system
+- `MaterialSymbol` re-export, `createReadOnlyHost`, `clipboard`, and document-path utilities
+
+### Notes
+
+- Several legacy aliases (`CustomEditorProps`, `ToolContext`, `ToolResult`, `AIToolDefinition`, `FileIconContribution`, `LexicalNodeContribution`) are exported for migration but marked `@deprecated`. They will be removed in a future major version.
+- Requires Vite 7+ and React 18 or 19 (declared as optional peer dependencies).

package/README.md

@@ -0,0 +1,151 @@
+# `@nimbalyst/extension-sdk`
+
+Build Nimbalyst extensions with a stable TypeScript contract and Vite helpers.
+
+This package provides:
+
+- Shared extension types such as `ExtensionContext`, `EditorHostProps`, and `ExtensionAITool`
+- `createExtensionConfig()` for the required extension build setup
+- `validateExtensionBundle()` for bundle and manifest validation
+- Tailwind helpers for extension styling
+
+## Install
+
+```bash
+npm install --save-dev @nimbalyst/extension-sdk typescript vite
+```
+
+If your extension renders React UI, also install:
+
+```bash
+npm install react react-dom
+npm install --save-dev @vitejs/plugin-react
+```
+
+## Vite Setup
+
+```ts
+import react from '@vitejs/plugin-react';
+import { createExtensionConfig } from '@nimbalyst/extension-sdk/vite';
+
+export default createExtensionConfig({
+  entry: './src/index.tsx',
+  plugins: [react()],
+});
+```
+
+## Custom Editor Example
+
+Use the `useEditorLifecycle` hook to handle all editor lifecycle concerns (loading, saving, echo detection, file watching, diff mode, theme):
+
+```tsx
+import { useRef } from 'react';
+import { useEditorLifecycle, type EditorHostProps } from '@nimbalyst/extension-sdk';
+
+export function ExampleEditor({ host }: EditorHostProps) {
+  const dataRef = useRef<MyData>(defaultData);
+
+  const { isLoading, markDirty, theme } = useEditorLifecycle(host, {
+    applyContent: (data: MyData) => { dataRef.current = data; },
+    getCurrentContent: () => dataRef.current,
+    parse: (raw) => JSON.parse(raw),
+    serialize: (data) => JSON.stringify(data),
+  });
+
+  if (isLoading) return <div>Loading...</div>;
+  return <MyEditorUI data={dataRef.current} onChange={markDirty} />;
+}
+
+export const components = {
+  ExampleEditor,
+};
+```
+
+See the [custom editors guide](packages/extension-sdk-docs/custom-editors.md) for architecture patterns and advanced options.
+
+## Shared Editor Components
+
+Extensions can use the host's built-in `MonacoEditor` (code) and `MarkdownEditor` (rich text) instead of bundling their own. These are provided at runtime via the externals system with zero bundle size impact. The `MarkdownEditor` is pre-configured with toolbar, image handling, and other Nimbalyst platform features.
+
+```tsx
+import { MonacoEditor } from '@nimbalyst/runtime';
+import type { EditorHostProps } from '@nimbalyst/extension-sdk';
+
+// Use as a full file editor
+export const MyCodeEditor = ({ host }: EditorHostProps) => {
+  return <MonacoEditor host={host} fileName={host.fileName} />;
+};
+```
+
+For embedded read-only panels, use `createReadOnlyHost`:
+
+```tsx
+import { MonacoEditor } from '@nimbalyst/runtime';
+import { createReadOnlyHost } from '@nimbalyst/extension-sdk';
+
+const previewHost = createReadOnlyHost(code, {
+  fileName: 'preview.tsx',
+  theme: host.theme,
+});
+
+<MonacoEditor host={previewHost} fileName="preview.tsx" />
+```
+
+Type imports for props: `MonacoEditorProps`, `MonacoEditorConfig`, `MarkdownEditorProps`, `MarkdownEditorConfig` from `@nimbalyst/extension-sdk`.
+
+## AI Tool Example
+
+```ts
+import type {
+  ExtensionAITool,
+  ExtensionToolResult,
+} from '@nimbalyst/extension-sdk';
+
+export const aiTools: ExtensionAITool[] = [
+  {
+    name: 'example.describe_file',
+    description: 'Describe the active file',
+    scope: 'editor',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+    handler: async (_args, context): Promise<ExtensionToolResult> => {
+      const filePath = context.activeFilePath;
+      if (!filePath) {
+        return { success: false, error: 'No active file.' };
+      }
+
+      const content = await context.extensionContext.services.filesystem.readFile(filePath);
+      return {
+        success: true,
+        data: {
+          filePath,
+          length: content.length,
+        },
+      };
+    },
+  },
+];
+```
+
+## Manifest Notes
+
+- `apiVersion` is currently optional but recommended.
+- `contributions.aiTools` must be an array of tool-name strings, not full tool objects.
+- `contributions.fileIcons` must be an object map such as `{ "*.csv": "table" }`.
+
+## Docs
+
+- Getting started: `packages/extension-sdk-docs/getting-started.md`
+- Manifest reference: `packages/extension-sdk-docs/manifest-reference.md`
+- API reference: `packages/extension-sdk-docs/api-reference.md`
+- Examples: `packages/extension-sdk-docs/examples/`
+
+## Release Checks
+
+From the monorepo root:
+
+```bash
+npm run extension-sdk:check-public
+```

package/dist/MaterialSymbol.d.ts

@@ -0,0 +1,2 @@
+export { MaterialSymbol } from '@nimbalyst/runtime';
+//# sourceMappingURL=MaterialSymbol.d.ts.map

package/dist/MaterialSymbol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MaterialSymbol.d.ts","sourceRoot":"","sources":["../src/MaterialSymbol.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/MaterialSymbol.js

@@ -0,0 +1 @@
+export { MaterialSymbol } from '@nimbalyst/runtime';

package/dist/clipboard.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Clipboard utilities for Nimbalyst extensions.
+ *
+ * Routes through Electron's native clipboard via IPC when available,
+ * falling back to the standard navigator.clipboard Web API for
+ * non-Electron contexts.
+ *
+ * navigator.clipboard.writeText() can silently fail in Electron -- the
+ * promise resolves but nothing is written to the system clipboard.
+ * These helpers avoid that issue by using the IPC bridge.
+ */
+export declare function copyToClipboard(text: string): Promise<void>;
+export declare function readClipboard(): Promise<string>;
+//# sourceMappingURL=clipboard.d.ts.map

package/dist/clipboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clipboard.d.ts","sourceRoot":"","sources":["../src/clipboard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAOjE;AAED,wBAAsB,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC,CAOrD"}

package/dist/clipboard.js

@@ -0,0 +1,27 @@
+/**
+ * Clipboard utilities for Nimbalyst extensions.
+ *
+ * Routes through Electron's native clipboard via IPC when available,
+ * falling back to the standard navigator.clipboard Web API for
+ * non-Electron contexts.
+ *
+ * navigator.clipboard.writeText() can silently fail in Electron -- the
+ * promise resolves but nothing is written to the system clipboard.
+ * These helpers avoid that issue by using the IPC bridge.
+ */
+export async function copyToClipboard(text) {
+    const electronAPI = window.electronAPI;
+    if (electronAPI?.copyToClipboard) {
+        await electronAPI.copyToClipboard(text);
+        return;
+    }
+    await navigator.clipboard.writeText(text);
+}
+export async function readClipboard() {
+    const electronAPI = window.electronAPI;
+    if (electronAPI?.readClipboard) {
+        const result = await electronAPI.readClipboard();
+        return result.text ?? '';
+    }
+    return navigator.clipboard.readText();
+}

package/dist/createReadOnlyHost.d.ts

@@ -0,0 +1,45 @@
+/**
+ * ReadOnlyEditorHost factory for web share viewers.
+ *
+ * Creates a minimal EditorHost implementation that serves pre-loaded content
+ * in read-only mode. Used by the Cloudflare share viewer to render extension
+ * editors on the web without any Electron/IPC dependencies.
+ *
+ * Also useful for testing extensions in isolation.
+ *
+ * @example
+ * ```ts
+ * const host = createReadOnlyHost(decryptedContent, {
+ *   theme: 'dark',
+ *   fileName: 'diagram.mindmap',
+ * });
+ *
+ * // Mount extension component
+ * root.render(<MindmapEditor host={host} />);
+ *
+ * // Toggle theme from viewer chrome
+ * host.setTheme('light');
+ * ```
+ */
+import type { EditorHost } from './types/editor.js';
+export interface ReadOnlyHostOptions {
+    /** Current theme name (e.g., 'dark', 'light') */
+    theme: string;
+    /** File name for display */
+    fileName: string;
+    /** Optional synthetic file path (defaults to `/shared/{fileName}`) */
+    filePath?: string;
+}
+export interface ReadOnlyHost extends EditorHost {
+    /** Update the theme (call from viewer chrome's theme toggle) */
+    setTheme(theme: string): void;
+}
+/**
+ * Create a read-only EditorHost that serves pre-loaded content.
+ *
+ * All mutating methods (save, dirty, file change) are no-ops.
+ * The `readOnly` flag is set to `true` so extensions can check it
+ * to disable editing UI.
+ */
+export declare function createReadOnlyHost(content: string, opts: ReadOnlyHostOptions): ReadOnlyHost;
+//# sourceMappingURL=createReadOnlyHost.d.ts.map

package/dist/createReadOnlyHost.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createReadOnlyHost.d.ts","sourceRoot":"","sources":["../src/createReadOnlyHost.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAiC,MAAM,mBAAmB,CAAC;AAEnF,MAAM,WAAW,mBAAmB;IAClC,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC;IAEd,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAC;IAEjB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAa,SAAQ,UAAU;IAC9C,gEAAgE;IAChE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,mBAAmB,GACxB,YAAY,CAyDd"}

package/dist/createReadOnlyHost.js

@@ -0,0 +1,81 @@
+/**
+ * ReadOnlyEditorHost factory for web share viewers.
+ *
+ * Creates a minimal EditorHost implementation that serves pre-loaded content
+ * in read-only mode. Used by the Cloudflare share viewer to render extension
+ * editors on the web without any Electron/IPC dependencies.
+ *
+ * Also useful for testing extensions in isolation.
+ *
+ * @example
+ * ```ts
+ * const host = createReadOnlyHost(decryptedContent, {
+ *   theme: 'dark',
+ *   fileName: 'diagram.mindmap',
+ * });
+ *
+ * // Mount extension component
+ * root.render(<MindmapEditor host={host} />);
+ *
+ * // Toggle theme from viewer chrome
+ * host.setTheme('light');
+ * ```
+ */
+/**
+ * Create a read-only EditorHost that serves pre-loaded content.
+ *
+ * All mutating methods (save, dirty, file change) are no-ops.
+ * The `readOnly` flag is set to `true` so extensions can check it
+ * to disable editing UI.
+ */
+export function createReadOnlyHost(content, opts) {
+    let themeCallbacks = [];
+    let currentTheme = opts.theme;
+    const host = {
+        // -- File info --
+        filePath: opts.filePath ?? `/shared/${opts.fileName}`,
+        fileName: opts.fileName,
+        readOnly: true,
+        theme: currentTheme,
+        isActive: true,
+        // -- Content loading --
+        loadContent: async () => content,
+        loadBinaryContent: async () => new TextEncoder().encode(content).buffer,
+        // -- Theme --
+        onThemeChanged: (cb) => {
+            themeCallbacks.push(cb);
+            return () => {
+                themeCallbacks = themeCallbacks.filter((c) => c !== cb);
+            };
+        },
+        // -- No-ops for read-only --
+        saveContent: async () => { },
+        setDirty: () => { },
+        onSaveRequested: () => () => { },
+        onFileChanged: () => () => { },
+        openHistory: () => { },
+        registerMenuItems: (_items) => { },
+        registerEditorAPI: () => { },
+        setEditorContext: (_context) => { },
+        // -- Storage (in-memory, non-persistent) --
+        storage: {
+            get: (_key) => undefined,
+            set: async () => { },
+            delete: async () => { },
+            getGlobal: (_key) => undefined,
+            setGlobal: async () => { },
+            deleteGlobal: async () => { },
+            getSecret: async () => undefined,
+            setSecret: async () => { },
+            deleteSecret: async () => { },
+        },
+        // -- Theme toggle for viewer chrome --
+        setTheme(theme) {
+            currentTheme = theme;
+            // Update the host's own theme property
+            host.theme = theme;
+            themeCallbacks.forEach((cb) => cb(theme));
+        },
+    };
+    return host;
+}

package/dist/documentPath.d.ts

@@ -0,0 +1,6 @@
+export interface DocumentPathContextValue {
+    documentPath: string | null;
+    documentDir: string | null;
+}
+export declare function useDocumentPath(): DocumentPathContextValue;
+//# sourceMappingURL=documentPath.d.ts.map

package/dist/documentPath.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"documentPath.d.ts","sourceRoot":"","sources":["../src/documentPath.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,wBAAwB;IACvC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,wBAAgB,eAAe,IAAI,wBAAwB,CAE1D"}

package/dist/documentPath.js

@@ -0,0 +1,4 @@
+import { useDocumentPath as useHostDocumentPath } from '@nimbalyst/runtime';
+export function useDocumentPath() {
+    return useHostDocumentPath();
+}

package/dist/externals.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Libraries that MUST be externalized by extensions.
+ *
+ * These libraries are provided by the Nimbalyst host and must not be bundled
+ * by extensions. Bundling them would cause runtime errors due to:
+ * - React: Multiple instances break hooks ("rendered more hooks than previous render")
+ * - Lexical: Extensions contribute nodes to the host's editor instance
+ *
+ * Extensions should bundle their own utility libraries (zustand, lodash, etc.)
+ * for version independence.
+ */
+export declare const REQUIRED_EXTERNALS: readonly ["react", "react-dom", "react-dom/client", "react/jsx-runtime", "react/jsx-dev-runtime", "lexical", "@lexical/react/LexicalComposerContext", "@lexical/react/useLexicalEditable", "@lexical/react/useLexicalNodeSelection", "@lexical/utils", "@lexical/markdown"];
+/**
+ * Regex patterns for externals that match multiple modules.
+ */
+export declare const EXTERNAL_PATTERNS: readonly [RegExp, RegExp];
+/**
+ * Combined externals for rollup configuration.
+ * Use this in rollupOptions.external
+ */
+export declare const ROLLUP_EXTERNALS: readonly ["react", "react-dom", "react-dom/client", "react/jsx-runtime", "react/jsx-dev-runtime", "lexical", "@lexical/react/LexicalComposerContext", "@lexical/react/useLexicalEditable", "@lexical/react/useLexicalNodeSelection", "@lexical/utils", "@lexical/markdown", RegExp, RegExp, "@nimbalyst/editor-context"];
+export type RequiredExternal = (typeof REQUIRED_EXTERNALS)[number];
+//# sourceMappingURL=externals.d.ts.map

package/dist/externals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"externals.d.ts","sourceRoot":"","sources":["../src/externals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,6QAerB,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,iBAAiB,2BAGpB,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,gBAAgB,0TAInB,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/externals.js

@@ -0,0 +1,42 @@
+/**
+ * Libraries that MUST be externalized by extensions.
+ *
+ * These libraries are provided by the Nimbalyst host and must not be bundled
+ * by extensions. Bundling them would cause runtime errors due to:
+ * - React: Multiple instances break hooks ("rendered more hooks than previous render")
+ * - Lexical: Extensions contribute nodes to the host's editor instance
+ *
+ * Extensions should bundle their own utility libraries (zustand, lodash, etc.)
+ * for version independence.
+ */
+export const REQUIRED_EXTERNALS = [
+    // React core - multiple instances break hooks
+    'react',
+    'react-dom',
+    'react-dom/client',
+    'react/jsx-runtime',
+    'react/jsx-dev-runtime',
+    // Lexical - extensions contribute nodes to host's editor
+    'lexical',
+    '@lexical/react/LexicalComposerContext',
+    '@lexical/react/useLexicalEditable',
+    '@lexical/react/useLexicalNodeSelection',
+    '@lexical/utils',
+    '@lexical/markdown',
+];
+/**
+ * Regex patterns for externals that match multiple modules.
+ */
+export const EXTERNAL_PATTERNS = [
+    /^@lexical\//,
+    /^@nimbalyst\/runtime/,
+];
+/**
+ * Combined externals for rollup configuration.
+ * Use this in rollupOptions.external
+ */
+export const ROLLUP_EXTERNALS = [
+    ...REQUIRED_EXTERNALS,
+    ...EXTERNAL_PATTERNS,
+    '@nimbalyst/editor-context',
+];

package/dist/externalsPlugin.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Vite/Rollup plugin that transforms external imports to window.__nimbalyst_extensions references.
+ *
+ * This plugin runs at BUILD TIME, transforming imports BEFORE minification.
+ * This is more robust than runtime regex transformation because:
+ * 1. Source code has predictable import syntax
+ * 2. Minification happens AFTER transformation
+ * 3. Build errors are caught early
+ *
+ * HOW IT WORKS:
+ * Instead of marking modules as "external" (which keeps bare import statements that
+ * blob URLs can't resolve), we resolve imports to virtual modules that access
+ * window.__nimbalyst_extensions at runtime.
+ *
+ * Example:
+ *   import React, { useState } from 'react'
+ *   ->
+ *   // Generated virtual module gets bundled inline:
+ *   const __mod = window.__nimbalyst_extensions["react"];
+ *   export default __mod;
+ *   export const useState = __mod.useState;
+ *   // etc.
+ *
+ * The extension's code then imports from this virtual module, which after bundling
+ * becomes direct property accesses on window.__nimbalyst_extensions.
+ */
+import type { Plugin } from 'vite';
+/**
+ * Creates a Vite plugin that transforms external imports at build time.
+ *
+ * This approach uses renderChunk to transform the final output after bundling
+ * but captures the original import information during the transform phase.
+ *
+ * The key insight: we DON'T mark these as external. Instead, we let Rollup
+ * try to resolve them, fail, and then our resolveId catches them and returns
+ * a virtual module. The virtual module's code accesses window.__nimbalyst_extensions.
+ */
+export declare function nimbalystExternalsPlugin(): Plugin;
+//# sourceMappingURL=externalsPlugin.d.ts.map

package/dist/externalsPlugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"externalsPlugin.d.ts","sourceRoot":"","sources":["../src/externalsPlugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAqDnC;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,IAAI,MAAM,CAyDjD"}