@quereus/plugin-loader 0.1.0

package/README.md

@@ -0,0 +1,69 @@
+# @quereus/plugin-loader
+
+Plugin loading system for Quereus. This package provides dynamic module loading capabilities for extending Quereus with custom virtual tables, functions, collations, and types.
+
+**Note:** This package uses dynamic `import()` which is not compatible with React Native. For React Native environments, use static imports and manual plugin registration instead.
+
+## Installation
+
+```bash
+npm install @quereus/plugin-loader
+# or
+yarn add @quereus/plugin-loader
+```
+
+## Usage
+
+```typescript
+import { Database } from '@quereus/quereus';
+import { loadPlugin, dynamicLoadModule } from '@quereus/plugin-loader';
+
+const db = new Database();
+
+// Load from npm package (Node.js)
+await loadPlugin('npm:@acme/quereus-plugin-foo@^1', db, { api_key: '...' });
+
+// Load from URL (Node.js or Browser)
+await dynamicLoadModule('https://example.com/plugin.js', db, { timeout: 10000 });
+
+// Browser with CDN (opt-in)
+await loadPlugin('npm:@acme/quereus-plugin-foo@^1', db, {}, { allowCdn: true });
+```
+
+## React Native
+
+This package is **not compatible** with React Native due to its use of dynamic `import()`. For React Native apps:
+
+1. Exclude this package from your dependencies
+2. Use static imports for plugins
+3. Manually register plugins with the database
+
+Example for React Native:
+
+```typescript
+import { Database } from '@quereus/quereus';
+import myPlugin from './plugins/my-plugin';
+
+const db = new Database();
+
+// Manually register the plugin
+const registrations = await myPlugin(db, { /* config */ });
+
+// Register vtables
+if (registrations.vtables) {
+  for (const vtable of registrations.vtables) {
+    db.registerVtabModule(vtable.name, vtable.module, vtable.auxData);
+  }
+}
+
+// Register functions, collations, types similarly...
+```
+
+## API
+
+See the [Plugin System Documentation](https://github.com/gotchoices/quereus/blob/main/packages/quereus/docs/plugins.md) for complete details.
+
+## License
+
+MIT
+

package/dist/src/config-loader.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Configuration loader for Quoomb
+ * Handles loading, parsing, and interpolating quoomb.config.json files
+ */
+import type { Database } from '@quereus/quereus';
+/**
+ * Plugin configuration from config file
+ */
+export interface PluginConfig {
+    source: string;
+    config?: Record<string, any>;
+}
+/**
+ * Quoomb configuration file format
+ */
+export interface QuoombConfig {
+    $schema?: string;
+    plugins?: PluginConfig[];
+    autoload?: boolean;
+}
+/**
+ * Interpolate environment variables in a value
+ * Supports ${VAR_NAME} and ${VAR_NAME:-default} syntax
+ */
+export declare function interpolateEnvVars(value: any, env?: Record<string, string>): any;
+/**
+ * Interpolate environment variables in a config object
+ */
+export declare function interpolateConfigEnvVars(config: QuoombConfig, env?: Record<string, string>): QuoombConfig;
+/**
+ * Load plugins from a config object
+ */
+export declare function loadPluginsFromConfig(db: Database, config: QuoombConfig, options?: {
+    allowCdn?: boolean;
+    env?: 'auto' | 'browser' | 'node';
+}): Promise<void>;
+/**
+ * Validate a config object
+ */
+export declare function validateConfig(config: any): config is QuoombConfig;
+//# sourceMappingURL=config-loader.d.ts.map

package/dist/src/config-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-loader.d.ts","sourceRoot":"","sources":["../../src/config-loader.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAY,MAAM,kBAAkB,CAAC;AAG3D;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAAG,GAAG,CAkBpF;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,YAAY,CAazG;AAED;;GAEG;AACH,wBAAsB,qBAAqB,CACzC,EAAE,EAAE,QAAQ,EACZ,MAAM,EAAE,YAAY,EACpB,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAAA;CAAE,GAClE,OAAO,CAAC,IAAI,CAAC,CA+Bf;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,GAAG,GAAG,MAAM,IAAI,YAAY,CA2BlE"}

package/dist/src/config-loader.js

@@ -0,0 +1,102 @@
+/**
+ * Configuration loader for Quoomb
+ * Handles loading, parsing, and interpolating quoomb.config.json files
+ */
+import { loadPlugin } from './plugin-loader.js';
+/**
+ * Interpolate environment variables in a value
+ * Supports ${VAR_NAME} and ${VAR_NAME:-default} syntax
+ */
+export function interpolateEnvVars(value, env = {}) {
+    if (typeof value === 'string') {
+        return value.replace(/\$\{([^}]+)\}/g, (match, varSpec) => {
+            const [varName, defaultValue] = varSpec.split(':-');
+            return env[varName.trim()] ?? defaultValue ?? match;
+        });
+    }
+    if (typeof value === 'object' && value !== null) {
+        if (Array.isArray(value)) {
+            return value.map(v => interpolateEnvVars(v, env));
+        }
+        const result = {};
+        for (const [key, val] of Object.entries(value)) {
+            result[key] = interpolateEnvVars(val, env);
+        }
+        return result;
+    }
+    return value;
+}
+/**
+ * Interpolate environment variables in a config object
+ */
+export function interpolateConfigEnvVars(config, env) {
+    let envVars = {};
+    if (env) {
+        envVars = env;
+    }
+    else if (typeof process !== 'undefined' && process.env) {
+        // Filter out undefined values from process.env
+        envVars = Object.fromEntries(Object.entries(process.env).filter(([, v]) => v !== undefined));
+    }
+    return interpolateEnvVars(config, envVars);
+}
+/**
+ * Load plugins from a config object
+ */
+export async function loadPluginsFromConfig(db, config, options) {
+    if (!config.plugins || config.plugins.length === 0) {
+        return;
+    }
+    for (const pluginConfig of config.plugins) {
+        try {
+            const configObj = pluginConfig.config ?? {};
+            // Convert config values to SqlValue type
+            const sqlConfig = {};
+            for (const [key, value] of Object.entries(configObj)) {
+                if (value === null || value === undefined) {
+                    sqlConfig[key] = null;
+                }
+                else if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+                    sqlConfig[key] = value;
+                }
+                else {
+                    // For complex types, convert to JSON string
+                    sqlConfig[key] = JSON.stringify(value);
+                }
+            }
+            await loadPlugin(pluginConfig.source, db, sqlConfig, options);
+        }
+        catch (error) {
+            console.warn(`Warning: Failed to load plugin from ${pluginConfig.source}: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+}
+/**
+ * Validate a config object
+ */
+export function validateConfig(config) {
+    if (typeof config !== 'object' || config === null) {
+        return false;
+    }
+    if (config.plugins !== undefined) {
+        if (!Array.isArray(config.plugins)) {
+            return false;
+        }
+        for (const plugin of config.plugins) {
+            if (typeof plugin !== 'object' || plugin === null) {
+                return false;
+            }
+            if (typeof plugin.source !== 'string') {
+                return false;
+            }
+            if (plugin.config !== undefined && typeof plugin.config !== 'object') {
+                return false;
+            }
+        }
+    }
+    if (config.autoload !== undefined && typeof config.autoload !== 'boolean') {
+        return false;
+    }
+    return true;
+}
+//# sourceMappingURL=config-loader.js.map

package/dist/src/config-loader.js.map

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

package/dist/src/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @quereus/plugin-loader
+ *
+ * Plugin loading system for Quereus with dynamic import() support.
+ *
+ * WARNING: This package uses dynamic import() which is NOT compatible with React Native.
+ * For React Native environments, use static imports and manual plugin registration instead.
+ */
+export { dynamicLoadModule, validatePluginUrl, loadPlugin } from './plugin-loader.js';
+export type { PluginModule, LoadPluginOptions } from './plugin-loader.js';
+export type { PluginManifest, PluginRecord, PluginSetting, VTablePluginInfo, FunctionPluginInfo, CollationPluginInfo, TypePluginInfo, PluginRegistrations } from './manifest.js';
+export { interpolateEnvVars, interpolateConfigEnvVars, loadPluginsFromConfig, validateConfig } from './config-loader.js';
+export type { PluginConfig, QuoombConfig } from './config-loader.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACtF,YAAY,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAG1E,YAAY,EACX,cAAc,EACd,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,EACnB,cAAc,EACd,mBAAmB,EACnB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACN,kBAAkB,EAClB,wBAAwB,EACxB,qBAAqB,EACrB,cAAc,EACd,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/src/index.js

@@ -0,0 +1,13 @@
+/**
+ * @quereus/plugin-loader
+ *
+ * Plugin loading system for Quereus with dynamic import() support.
+ *
+ * WARNING: This package uses dynamic import() which is NOT compatible with React Native.
+ * For React Native environments, use static imports and manual plugin registration instead.
+ */
+// Re-export plugin loader functions
+export { dynamicLoadModule, validatePluginUrl, loadPlugin } from './plugin-loader.js';
+// Re-export config loader
+export { interpolateEnvVars, interpolateConfigEnvVars, loadPluginsFromConfig, validateConfig } from './config-loader.js';
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,oCAAoC;AACpC,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAetF,0BAA0B;AAC1B,OAAO,EACN,kBAAkB,EAClB,wBAAwB,EACxB,qBAAqB,EACrB,cAAc,EACd,MAAM,oBAAoB,CAAC"}

package/dist/src/manifest.d.ts

@@ -0,0 +1,72 @@
+import type { SqlValue, FunctionSchema, CollationFunction, TypePluginInfo, VirtualTableModule, VirtualTable } from '@quereus/quereus';
+export type { TypePluginInfo };
+/**
+ * Configuration setting definition for a plugin
+ */
+export interface PluginSetting {
+    key: string;
+    label: string;
+    type: 'string' | 'number' | 'boolean' | 'select';
+    default?: SqlValue;
+    options?: SqlValue[];
+    help?: string;
+}
+/**
+ * Virtual table module registration info
+ */
+export interface VTablePluginInfo {
+    name: string;
+    module: VirtualTableModule<VirtualTable, any>;
+    auxData?: unknown;
+}
+/**
+ * Function registration info
+ */
+export interface FunctionPluginInfo {
+    schema: FunctionSchema;
+}
+/**
+ * Collation registration info
+ */
+export interface CollationPluginInfo {
+    name: string;
+    func: CollationFunction;
+}
+/**
+ * Plugin registration items - what the plugin wants to register
+ */
+export interface PluginRegistrations {
+    vtables?: VTablePluginInfo[];
+    functions?: FunctionPluginInfo[];
+    collations?: CollationPluginInfo[];
+    types?: TypePluginInfo[];
+}
+/**
+ * Plugin manifest that describes the plugin's metadata and configuration options
+ */
+export interface PluginManifest {
+    name: string;
+    version: string;
+    author?: string;
+    description?: string;
+    pragmaPrefix?: string;
+    settings?: PluginSetting[];
+    capabilities?: string[];
+    provides?: {
+        vtables?: string[];
+        functions?: string[];
+        collations?: string[];
+        types?: string[];
+    };
+}
+/**
+ * Plugin record used for persistence across sessions
+ */
+export interface PluginRecord {
+    id: string;
+    url: string;
+    enabled: boolean;
+    manifest?: PluginManifest;
+    config: Record<string, SqlValue>;
+}
+//# sourceMappingURL=manifest.d.ts.map

package/dist/src/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,iBAAiB,EAAE,cAAc,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAGtI,YAAY,EAAE,cAAc,EAAE,CAAC;AAE/B;;GAEG;AACH,MAAM,WAAW,aAAa;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;IACjD,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB,OAAO,CAAC,EAAE,QAAQ,EAAE,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,kBAAkB,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC;IAC9C,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,MAAM,EAAE,cAAc,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,iBAAiB,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC,OAAO,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC7B,SAAS,CAAC,EAAE,kBAAkB,EAAE,CAAC;IACjC,UAAU,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACnC,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IAGxB,QAAQ,CAAC,EAAE;QACV,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;QACrB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;QACtB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;KACjB,CAAC;CACF;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;CACjC"}

package/dist/src/manifest.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=manifest.js.map

package/dist/src/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../src/manifest.ts"],"names":[],"mappings":""}

package/dist/src/plugin-loader.d.ts

@@ -0,0 +1,51 @@
+import type { Database, SqlValue } from '@quereus/quereus';
+import type { PluginManifest, PluginRegistrations } from './manifest.js';
+/**
+ * Plugin module interface - what we expect from a plugin module
+ */
+export interface PluginModule {
+    /** Default export - the plugin registration function */
+    default: (db: Database, config?: Record<string, SqlValue>) => Promise<PluginRegistrations> | PluginRegistrations;
+}
+/**
+ * Dynamically loads and registers a plugin module
+ *
+ * @param url The URL to the ES module (can be https:// or file:// URL)
+ * @param db The Database instance to register the module with
+ * @param config Configuration values to pass to the module
+ * @returns The plugin's manifest if available
+ */
+export declare function dynamicLoadModule(url: string, db: Database, config?: Record<string, SqlValue>): Promise<PluginManifest | undefined>;
+/**
+ * Validates that a URL is likely to be a valid plugin module
+ *
+ * @param url The URL to validate
+ * @returns true if the URL appears valid
+ */
+export declare function validatePluginUrl(url: string): boolean;
+/** Loader options for loadPlugin */
+export interface LoadPluginOptions {
+    /**
+     * Environment hint. Defaults to auto-detection.
+     * 'browser' enables optional CDN resolution when allowCdn is true.
+     */
+    env?: 'auto' | 'browser' | 'node';
+    /**
+     * Allow resolving npm: specs to a public CDN in browser contexts.
+     * Disabled by default (opt-in).
+     */
+    allowCdn?: boolean;
+    /** Which CDN to use when allowCdn is true. Defaults to 'jsdelivr'. */
+    cdn?: 'jsdelivr' | 'unpkg' | 'esm.sh';
+}
+/**
+ * High-level plugin loader that accepts npm specs or direct URLs.
+ *
+ * Examples:
+ * - npm:@scope/quereus-plugin-foo@^1
+ * - @scope/quereus-plugin-foo (npm package name)
+ * - https://raw.githubusercontent.com/user/repo/main/plugin.js
+ * - file:///path/to/plugin.js (Node only)
+ */
+export declare function loadPlugin(spec: string, db: Database, config?: Record<string, SqlValue>, options?: LoadPluginOptions): Promise<PluginManifest | undefined>;
+//# sourceMappingURL=plugin-loader.d.ts.map

package/dist/src/plugin-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-loader.d.ts","sourceRoot":"","sources":["../../src/plugin-loader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE3D,OAAO,KAAK,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEzE;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B,wDAAwD;IACxD,OAAO,EAAE,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,KAAK,OAAO,CAAC,mBAAmB,CAAC,GAAG,mBAAmB,CAAC;CACjH;AAqBD;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACtC,GAAG,EAAE,MAAM,EACX,EAAE,EAAE,QAAQ,EACZ,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAM,GACnC,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAyCrC;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAkBtD;AAGD,oCAAoC;AACpC,MAAM,WAAW,iBAAiB;IAC9B;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,sEAAsE;IACtE,GAAG,CAAC,EAAE,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC;CACzC;AAED;;;;;;;;GAQG;AACH,wBAAsB,UAAU,CAC5B,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,QAAQ,EACZ,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAM,EACrC,OAAO,GAAE,iBAAsB,GAChC,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAoErC"}

package/dist/src/plugin-loader.js

@@ -0,0 +1,227 @@
+import { registerPlugin } from '@quereus/quereus';
+/**
+ * Extracts plugin manifest from package.json metadata
+ * Looks for metadata in package.json root fields and quereus.provides/settings
+ */
+function extractManifestFromPackageJson(pkg) {
+    const quereus = pkg.quereus || {};
+    return {
+        name: pkg.name || 'Unknown Plugin',
+        version: pkg.version || '0.0.0',
+        author: pkg.author,
+        description: pkg.description,
+        pragmaPrefix: quereus.pragmaPrefix,
+        settings: quereus.settings,
+        provides: quereus.provides,
+        capabilities: quereus.capabilities
+    };
+}
+/**
+ * Dynamically loads and registers a plugin module
+ *
+ * @param url The URL to the ES module (can be https:// or file:// URL)
+ * @param db The Database instance to register the module with
+ * @param config Configuration values to pass to the module
+ * @returns The plugin's manifest if available
+ */
+export async function dynamicLoadModule(url, db, config = {}) {
+    try {
+        // Add cache-busting timestamp for development
+        const moduleUrl = new URL(url);
+        if (moduleUrl.protocol === 'file:' || moduleUrl.hostname === 'localhost') {
+            moduleUrl.searchParams.set('t', Date.now().toString());
+        }
+        // Dynamic import with Vite ignore comment for bundler compatibility
+        const mod = await import(/* @vite-ignore */ moduleUrl.toString());
+        // Validate module structure
+        if (typeof mod.default !== 'function') {
+            throw new Error(`Module at ${url} has no default export function`);
+        }
+        // Use the core registerPlugin function from @quereus/quereus
+        // This reuses the same registration logic as static plugin loading
+        await registerPlugin(db, mod.default, config);
+        console.log(`Successfully loaded plugin from ${url}`);
+        // Try to extract manifest from package.json
+        let manifest;
+        try {
+            const packageJsonUrl = new URL('package.json', moduleUrl);
+            const packageJsonResponse = await fetch(packageJsonUrl.toString());
+            if (packageJsonResponse.ok) {
+                const pkg = await packageJsonResponse.json();
+                manifest = extractManifestFromPackageJson(pkg);
+            }
+        }
+        catch {
+            // package.json not found or not accessible - that's okay
+            console.log(`Could not load package.json for plugin at ${url}`);
+        }
+        return manifest;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to load plugin from ${url}: ${message}`);
+    }
+}
+/**
+ * Validates that a URL is likely to be a valid plugin module
+ *
+ * @param url The URL to validate
+ * @returns true if the URL appears valid
+ */
+export function validatePluginUrl(url) {
+    try {
+        const parsed = new URL(url);
+        // Allow https:// and file:// protocols
+        if (!['https:', 'file:'].includes(parsed.protocol)) {
+            return false;
+        }
+        // Must end with .js or .mjs
+        if (!/\.(m?js)$/i.test(parsed.pathname)) {
+            return false;
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * High-level plugin loader that accepts npm specs or direct URLs.
+ *
+ * Examples:
+ * - npm:@scope/quereus-plugin-foo@^1
+ * - @scope/quereus-plugin-foo (npm package name)
+ * - https://raw.githubusercontent.com/user/repo/main/plugin.js
+ * - file:///path/to/plugin.js (Node only)
+ */
+export async function loadPlugin(spec, db, config = {}, options = {}) {
+    const env = options.env && options.env !== 'auto' ? options.env : (isBrowserEnv() ? 'browser' : 'node');
+    // Direct URL or file path via dynamicLoadModule
+    if (isUrlLike(spec)) {
+        return await dynamicLoadModule(spec, db, config);
+    }
+    // Interpret as npm spec or bare package name
+    const npm = parseNpmSpec(spec);
+    if (!npm) {
+        throw new Error(`Invalid plugin spec: ${spec}. Use a URL, file://, or npm package (e.g., npm:@scope/name@version).`);
+    }
+    if (env === 'node') {
+        // Resolve using Node ESM resolution. Prefer exported subpath './plugin'.
+        const subpathImport = `${npm.name}/plugin${npm.subpath ?? ''}`;
+        const candidates = [subpathImport, `${npm.name}${npm.subpath ?? ''}`];
+        let mod;
+        let lastErr = undefined;
+        for (const target of candidates) {
+            try {
+                mod = await import(/* @vite-ignore */ target);
+                break;
+            }
+            catch (e) {
+                lastErr = e;
+            }
+        }
+        if (!mod) {
+            throw new Error(`Failed to resolve plugin package '${npm.name}'. Ensure it exports './plugin' or a default module. Last error: ${lastErr instanceof Error ? lastErr.message : String(lastErr)}`);
+        }
+        if (typeof mod.default !== 'function') {
+            throw new Error(`Resolved module for '${npm.name}' has no default export function`);
+        }
+        // Use the core registerPlugin function from @quereus/quereus
+        await registerPlugin(db, mod.default, config);
+        console.log(`Successfully loaded plugin from package ${npm.name}`);
+        // Try to extract manifest from package.json
+        let manifest;
+        try {
+            // Try to import package.json directly
+            const pkg = await import(`${npm.name}/package.json`, { assert: { type: 'json' } });
+            manifest = extractManifestFromPackageJson(pkg.default);
+        }
+        catch {
+            // package.json not found - that's okay
+            console.log(`Could not load package.json for plugin ${npm.name}`);
+        }
+        return manifest;
+    }
+    // Browser path: npm spec requires CDN; only if explicitly allowed
+    if (!options.allowCdn) {
+        throw new Error(`Loading npm packages in the browser requires allowCdn=true. Received spec '${spec}'. ` +
+            `Either provide a direct https:// URL to the ESM plugin or enable CDN resolution.`);
+    }
+    const cdnUrl = toCdnUrl(npm, options.cdn ?? 'jsdelivr');
+    return await dynamicLoadModule(cdnUrl, db, config);
+}
+function isBrowserEnv() {
+    // Heuristic: presence of document on globalThis implies browser
+    return typeof globalThis !== 'undefined' && typeof globalThis.document !== 'undefined';
+}
+function isUrlLike(s) {
+    try {
+        const u = new URL(s);
+        return u.protocol === 'https:' || u.protocol === 'http:' || u.protocol === 'file:';
+    }
+    catch {
+        return false;
+    }
+}
+function parseNpmSpec(input) {
+    // Remove optional npm: prefix
+    const raw = input.startsWith('npm:') ? input.slice(4) : input;
+    // Quick reject if contains spaces or empty
+    if (!raw || /\s/.test(raw))
+        return null;
+    // Support patterns like:
+    // @scope/name@1.2.3/path   name@^1  name  name/path
+    // Split off subpath (first '/' that is not part of scope)
+    let nameAndVersion = raw;
+    let subpath;
+    if (raw.startsWith('@')) {
+        // Scoped: look for second '/'
+        const secondSlash = raw.indexOf('/', raw.indexOf('/') + 1);
+        if (secondSlash !== -1) {
+            nameAndVersion = raw.slice(0, secondSlash);
+            subpath = raw.slice(secondSlash);
+        }
+    }
+    else {
+        const firstSlash = raw.indexOf('/');
+        if (firstSlash !== -1) {
+            nameAndVersion = raw.slice(0, firstSlash);
+            subpath = raw.slice(firstSlash);
+        }
+    }
+    // Now split name@version
+    const atIndex = nameAndVersion.lastIndexOf('@');
+    if (nameAndVersion.startsWith('@')) {
+        // Scoped: the first '@' is part of the scope
+        if (atIndex > 0) {
+            const name = nameAndVersion.slice(0, atIndex);
+            const version = nameAndVersion.slice(atIndex + 1) || undefined;
+            return { name, version, subpath };
+        }
+        return { name: nameAndVersion, subpath };
+    }
+    else {
+        if (atIndex > 0) {
+            const name = nameAndVersion.slice(0, atIndex);
+            const version = nameAndVersion.slice(atIndex + 1) || undefined;
+            return { name, version, subpath };
+        }
+        return { name: nameAndVersion, subpath };
+    }
+}
+function toCdnUrl(spec, cdn) {
+    const versionSegment = spec.version ? `@${spec.version}` : '';
+    const subpath = spec.subpath ? spec.subpath.replace(/^\//, '') : 'plugin';
+    switch (cdn) {
+        case 'unpkg':
+            return `https://unpkg.com/${spec.name}${versionSegment}/${subpath}`;
+        case 'esm.sh':
+            // esm.sh expects ?path=/subpath or direct subpath after package
+            // Use direct subpath; esm.sh will transform to ESM
+            return `https://esm.sh/${spec.name}${versionSegment}/${subpath}`;
+        case 'jsdelivr':
+        default:
+            return `https://cdn.jsdelivr.net/npm/${spec.name}${versionSegment}/${subpath}`;
+    }
+}
+//# sourceMappingURL=plugin-loader.js.map

package/dist/src/plugin-loader.js.map

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

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@quereus/plugin-loader",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Plugin loading system for Quereus - supports dynamic imports for Node.js and browsers",
+  "publisher": "Got Choices Foundation",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gotchoices/quereus.git",
+    "directory": "packages/plugin-loader"
+  },
+  "license": "MIT",
+  "main": "dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "files": [
+    "src",
+    "dist",
+    "!**/*.tsbuildinfo"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    }
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@quereus/quereus": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.29",
+    "typescript": "^5.8.3"
+  }
+}
+

package/src/config-loader.ts

@@ -0,0 +1,139 @@
+/**
+ * Configuration loader for Quoomb
+ * Handles loading, parsing, and interpolating quoomb.config.json files
+ */
+
+import type { Database, SqlValue } from '@quereus/quereus';
+import { loadPlugin } from './plugin-loader.js';
+
+/**
+ * Plugin configuration from config file
+ */
+export interface PluginConfig {
+  source: string;
+  config?: Record<string, any>;
+}
+
+/**
+ * Quoomb configuration file format
+ */
+export interface QuoombConfig {
+  $schema?: string;
+  plugins?: PluginConfig[];
+  autoload?: boolean;
+}
+
+/**
+ * Interpolate environment variables in a value
+ * Supports ${VAR_NAME} and ${VAR_NAME:-default} syntax
+ */
+export function interpolateEnvVars(value: any, env: Record<string, string> = {}): any {
+  if (typeof value === 'string') {
+    return value.replace(/\$\{([^}]+)\}/g, (match, varSpec) => {
+      const [varName, defaultValue] = varSpec.split(':-');
+      return env[varName.trim()] ?? defaultValue ?? match;
+    });
+  }
+  if (typeof value === 'object' && value !== null) {
+    if (Array.isArray(value)) {
+      return value.map(v => interpolateEnvVars(v, env));
+    }
+    const result: Record<string, any> = {};
+    for (const [key, val] of Object.entries(value)) {
+      result[key] = interpolateEnvVars(val, env);
+    }
+    return result;
+  }
+  return value;
+}
+
+/**
+ * Interpolate environment variables in a config object
+ */
+export function interpolateConfigEnvVars(config: QuoombConfig, env?: Record<string, string>): QuoombConfig {
+  let envVars: Record<string, string> = {};
+
+  if (env) {
+    envVars = env;
+  } else if (typeof process !== 'undefined' && process.env) {
+    // Filter out undefined values from process.env
+    envVars = Object.fromEntries(
+      Object.entries(process.env).filter(([, v]) => v !== undefined) as Array<[string, string]>
+    );
+  }
+
+  return interpolateEnvVars(config, envVars);
+}
+
+/**
+ * Load plugins from a config object
+ */
+export async function loadPluginsFromConfig(
+  db: Database,
+  config: QuoombConfig,
+  options?: { allowCdn?: boolean; env?: 'auto' | 'browser' | 'node' }
+): Promise<void> {
+  if (!config.plugins || config.plugins.length === 0) {
+    return;
+  }
+
+  for (const pluginConfig of config.plugins) {
+    try {
+      const configObj = pluginConfig.config ?? {};
+
+      // Convert config values to SqlValue type
+      const sqlConfig: Record<string, SqlValue> = {};
+      for (const [key, value] of Object.entries(configObj)) {
+        if (value === null || value === undefined) {
+          sqlConfig[key] = null;
+        } else if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+          sqlConfig[key] = value;
+        } else {
+          // For complex types, convert to JSON string
+          sqlConfig[key] = JSON.stringify(value);
+        }
+      }
+
+      await loadPlugin(pluginConfig.source, db, sqlConfig, options);
+    } catch (error) {
+      console.warn(
+        `Warning: Failed to load plugin from ${pluginConfig.source}: ${
+          error instanceof Error ? error.message : 'Unknown error'
+        }`
+      );
+    }
+  }
+}
+
+/**
+ * Validate a config object
+ */
+export function validateConfig(config: any): config is QuoombConfig {
+  if (typeof config !== 'object' || config === null) {
+    return false;
+  }
+
+  if (config.plugins !== undefined) {
+    if (!Array.isArray(config.plugins)) {
+      return false;
+    }
+    for (const plugin of config.plugins) {
+      if (typeof plugin !== 'object' || plugin === null) {
+        return false;
+      }
+      if (typeof plugin.source !== 'string') {
+        return false;
+      }
+      if (plugin.config !== undefined && typeof plugin.config !== 'object') {
+        return false;
+      }
+    }
+  }
+
+  if (config.autoload !== undefined && typeof config.autoload !== 'boolean') {
+    return false;
+  }
+
+  return true;
+}
+

package/src/index.ts

@@ -0,0 +1,34 @@
+/**
+ * @quereus/plugin-loader
+ * 
+ * Plugin loading system for Quereus with dynamic import() support.
+ * 
+ * WARNING: This package uses dynamic import() which is NOT compatible with React Native.
+ * For React Native environments, use static imports and manual plugin registration instead.
+ */
+
+// Re-export plugin loader functions
+export { dynamicLoadModule, validatePluginUrl, loadPlugin } from './plugin-loader.js';
+export type { PluginModule, LoadPluginOptions } from './plugin-loader.js';
+
+// Re-export manifest types
+export type {
+	PluginManifest,
+	PluginRecord,
+	PluginSetting,
+	VTablePluginInfo,
+	FunctionPluginInfo,
+	CollationPluginInfo,
+	TypePluginInfo,
+	PluginRegistrations
+} from './manifest.js';
+
+// Re-export config loader
+export {
+	interpolateEnvVars,
+	interpolateConfigEnvVars,
+	loadPluginsFromConfig,
+	validateConfig
+} from './config-loader.js';
+export type { PluginConfig, QuoombConfig } from './config-loader.js';
+

package/src/manifest.ts

@@ -0,0 +1,83 @@
+import type { SqlValue, FunctionSchema, CollationFunction, TypePluginInfo, VirtualTableModule, VirtualTable } from '@quereus/quereus';
+
+// Re-export TypePluginInfo so it can be imported from this module
+export type { TypePluginInfo };
+
+/**
+ * Configuration setting definition for a plugin
+ */
+export interface PluginSetting {
+	key: string;                    // "path"
+	label: string;                  // "JSON Path"
+	type: 'string' | 'number' | 'boolean' | 'select';
+	default?: SqlValue;
+	options?: SqlValue[];           // for select type
+	help?: string;
+}
+
+/**
+ * Virtual table module registration info
+ */
+export interface VTablePluginInfo {
+	name: string;                   // module name for registration
+	module: VirtualTableModule<VirtualTable, any>;    // the VirtualTableModule implementation
+	auxData?: unknown;             // optional auxiliary data
+}
+
+/**
+ * Function registration info
+ */
+export interface FunctionPluginInfo {
+	schema: FunctionSchema;        // complete function schema
+}
+
+/**
+ * Collation registration info
+ */
+export interface CollationPluginInfo {
+	name: string;                  // collation name
+	func: CollationFunction;       // comparison function
+}
+
+/**
+ * Plugin registration items - what the plugin wants to register
+ */
+export interface PluginRegistrations {
+	vtables?: VTablePluginInfo[];
+	functions?: FunctionPluginInfo[];
+	collations?: CollationPluginInfo[];
+	types?: TypePluginInfo[];
+}
+
+/**
+ * Plugin manifest that describes the plugin's metadata and configuration options
+ */
+export interface PluginManifest {
+	name: string;                   // "JSON_TABLE"
+	version: string;                // "1.0.0"
+	author?: string;
+	description?: string;
+	pragmaPrefix?: string;          // default = name, used for PRAGMA commands
+	settings?: PluginSetting[];     // configuration options
+	capabilities?: string[];        // e.g. ['scan', 'index', 'write']
+
+	// Plugin type indicators (for UI display)
+	provides?: {
+		vtables?: string[];         // names of vtable modules provided
+		functions?: string[];       // names of functions provided
+		collations?: string[];      // names of collations provided
+		types?: string[];           // names of types provided
+	};
+}
+
+/**
+ * Plugin record used for persistence across sessions
+ */
+export interface PluginRecord {
+	id: string;                     // UUID for this installation
+	url: string;                    // Full URL to the ES module
+	enabled: boolean;               // Whether to load at startup
+	manifest?: PluginManifest;      // Cached after first successful load
+	config: Record<string, SqlValue>; // User-configured values
+}
+

package/src/plugin-loader.ts

@@ -0,0 +1,296 @@
+import type { Database, SqlValue } from '@quereus/quereus';
+import { registerPlugin } from '@quereus/quereus';
+import type { PluginManifest, PluginRegistrations } from './manifest.js';
+
+/**
+ * Plugin module interface - what we expect from a plugin module
+ */
+export interface PluginModule {
+	/** Default export - the plugin registration function */
+	default: (db: Database, config?: Record<string, SqlValue>) => Promise<PluginRegistrations> | PluginRegistrations;
+}
+
+/**
+ * Extracts plugin manifest from package.json metadata
+ * Looks for metadata in package.json root fields and quereus.provides/settings
+ */
+function extractManifestFromPackageJson(pkg: any): PluginManifest {
+	const quereus = pkg.quereus || {};
+
+	return {
+		name: pkg.name || 'Unknown Plugin',
+		version: pkg.version || '0.0.0',
+		author: pkg.author,
+		description: pkg.description,
+		pragmaPrefix: quereus.pragmaPrefix,
+		settings: quereus.settings,
+		provides: quereus.provides,
+		capabilities: quereus.capabilities
+	};
+}
+
+/**
+ * Dynamically loads and registers a plugin module
+ *
+ * @param url The URL to the ES module (can be https:// or file:// URL)
+ * @param db The Database instance to register the module with
+ * @param config Configuration values to pass to the module
+ * @returns The plugin's manifest if available
+ */
+export async function dynamicLoadModule(
+	url: string,
+	db: Database,
+	config: Record<string, SqlValue> = {}
+): Promise<PluginManifest | undefined> {
+	try {
+		// Add cache-busting timestamp for development
+		const moduleUrl = new URL(url);
+		if (moduleUrl.protocol === 'file:' || moduleUrl.hostname === 'localhost') {
+			moduleUrl.searchParams.set('t', Date.now().toString());
+		}
+
+		// Dynamic import with Vite ignore comment for bundler compatibility
+		const mod = await import(/* @vite-ignore */ moduleUrl.toString()) as PluginModule;
+
+		// Validate module structure
+		if (typeof mod.default !== 'function') {
+			throw new Error(`Module at ${url} has no default export function`);
+		}
+
+		// Use the core registerPlugin function from @quereus/quereus
+		// This reuses the same registration logic as static plugin loading
+		await registerPlugin(db, mod.default, config);
+
+		console.log(`Successfully loaded plugin from ${url}`);
+
+		// Try to extract manifest from package.json
+		let manifest: PluginManifest | undefined;
+		try {
+			const packageJsonUrl = new URL('package.json', moduleUrl);
+			const packageJsonResponse = await fetch(packageJsonUrl.toString());
+			if (packageJsonResponse.ok) {
+				const pkg = await packageJsonResponse.json();
+				manifest = extractManifestFromPackageJson(pkg);
+			}
+		} catch {
+			// package.json not found or not accessible - that's okay
+			console.log(`Could not load package.json for plugin at ${url}`);
+		}
+
+		return manifest;
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		throw new Error(`Failed to load plugin from ${url}: ${message}`);
+	}
+}
+
+/**
+ * Validates that a URL is likely to be a valid plugin module
+ *
+ * @param url The URL to validate
+ * @returns true if the URL appears valid
+ */
+export function validatePluginUrl(url: string): boolean {
+	try {
+		const parsed = new URL(url);
+
+		// Allow https:// and file:// protocols
+		if (!['https:', 'file:'].includes(parsed.protocol)) {
+			return false;
+		}
+
+		// Must end with .js or .mjs
+		if (!/\.(m?js)$/i.test(parsed.pathname)) {
+			return false;
+		}
+
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+
+/** Loader options for loadPlugin */
+export interface LoadPluginOptions {
+    /**
+     * Environment hint. Defaults to auto-detection.
+     * 'browser' enables optional CDN resolution when allowCdn is true.
+     */
+    env?: 'auto' | 'browser' | 'node';
+    /**
+     * Allow resolving npm: specs to a public CDN in browser contexts.
+     * Disabled by default (opt-in).
+     */
+    allowCdn?: boolean;
+    /** Which CDN to use when allowCdn is true. Defaults to 'jsdelivr'. */
+    cdn?: 'jsdelivr' | 'unpkg' | 'esm.sh';
+}
+
+/**
+ * High-level plugin loader that accepts npm specs or direct URLs.
+ *
+ * Examples:
+ * - npm:@scope/quereus-plugin-foo@^1
+ * - @scope/quereus-plugin-foo (npm package name)
+ * - https://raw.githubusercontent.com/user/repo/main/plugin.js
+ * - file:///path/to/plugin.js (Node only)
+ */
+export async function loadPlugin(
+    spec: string,
+    db: Database,
+    config: Record<string, SqlValue> = {},
+    options: LoadPluginOptions = {}
+): Promise<PluginManifest | undefined> {
+    const env = options.env && options.env !== 'auto' ? options.env : (isBrowserEnv() ? 'browser' : 'node');
+
+    // Direct URL or file path via dynamicLoadModule
+    if (isUrlLike(spec)) {
+        return await dynamicLoadModule(spec, db, config);
+    }
+
+    // Interpret as npm spec or bare package name
+    const npm = parseNpmSpec(spec);
+    if (!npm) {
+        throw new Error(`Invalid plugin spec: ${spec}. Use a URL, file://, or npm package (e.g., npm:@scope/name@version).`);
+    }
+
+    if (env === 'node') {
+        // Resolve using Node ESM resolution. Prefer exported subpath './plugin'.
+        const subpathImport = `${npm.name}/plugin${npm.subpath ?? ''}`;
+        const candidates = [subpathImport, `${npm.name}${npm.subpath ?? ''}`];
+
+        let mod: PluginModule | undefined;
+        let lastErr: unknown = undefined;
+        for (const target of candidates) {
+            try {
+                mod = await import(/* @vite-ignore */ target) as PluginModule;
+                break;
+            } catch (e) {
+                lastErr = e;
+            }
+        }
+
+        if (!mod) {
+            throw new Error(
+                `Failed to resolve plugin package '${npm.name}'. Ensure it exports './plugin' or a default module. Last error: ${lastErr instanceof Error ? lastErr.message : String(lastErr)}`
+            );
+        }
+
+        if (typeof mod.default !== 'function') {
+            throw new Error(`Resolved module for '${npm.name}' has no default export function`);
+        }
+
+        // Use the core registerPlugin function from @quereus/quereus
+        await registerPlugin(db, mod.default, config);
+        console.log(`Successfully loaded plugin from package ${npm.name}`);
+
+        // Try to extract manifest from package.json
+        let manifest: PluginManifest | undefined;
+        try {
+            // Try to import package.json directly
+            const pkg = await import(`${npm.name}/package.json`, { assert: { type: 'json' } });
+            manifest = extractManifestFromPackageJson(pkg.default);
+        } catch {
+            // package.json not found - that's okay
+            console.log(`Could not load package.json for plugin ${npm.name}`);
+        }
+
+        return manifest;
+    }
+
+    // Browser path: npm spec requires CDN; only if explicitly allowed
+    if (!options.allowCdn) {
+        throw new Error(
+            `Loading npm packages in the browser requires allowCdn=true. Received spec '${spec}'. ` +
+            `Either provide a direct https:// URL to the ESM plugin or enable CDN resolution.`
+        );
+    }
+
+    const cdnUrl = toCdnUrl(npm, options.cdn ?? 'jsdelivr');
+    return await dynamicLoadModule(cdnUrl, db, config);
+}
+
+function isBrowserEnv(): boolean {
+    // Heuristic: presence of document on globalThis implies browser
+    return typeof globalThis !== 'undefined' && typeof (globalThis as unknown as { document?: unknown }).document !== 'undefined';
+}
+
+function isUrlLike(s: string): boolean {
+    try {
+        const u = new URL(s);
+        return u.protocol === 'https:' || u.protocol === 'http:' || u.protocol === 'file:';
+    } catch {
+        return false;
+    }
+}
+
+interface NpmSpec {
+    name: string; // @scope/pkg or pkg
+    version?: string; // optional semver or tag
+    subpath?: string; // optional subpath after package root (rarely used)
+}
+
+function parseNpmSpec(input: string): NpmSpec | null {
+    // Remove optional npm: prefix
+    const raw = input.startsWith('npm:') ? input.slice(4) : input;
+
+    // Quick reject if contains spaces or empty
+    if (!raw || /\s/.test(raw)) return null;
+
+    // Support patterns like:
+    // @scope/name@1.2.3/path   name@^1  name  name/path
+    // Split off subpath (first '/' that is not part of scope)
+    let nameAndVersion = raw;
+    let subpath: string | undefined;
+    if (raw.startsWith('@')) {
+        // Scoped: look for second '/'
+        const secondSlash = raw.indexOf('/', raw.indexOf('/') + 1);
+        if (secondSlash !== -1) {
+            nameAndVersion = raw.slice(0, secondSlash);
+            subpath = raw.slice(secondSlash);
+        }
+    } else {
+        const firstSlash = raw.indexOf('/');
+        if (firstSlash !== -1) {
+            nameAndVersion = raw.slice(0, firstSlash);
+            subpath = raw.slice(firstSlash);
+        }
+    }
+
+    // Now split name@version
+    const atIndex = nameAndVersion.lastIndexOf('@');
+    if (nameAndVersion.startsWith('@')) {
+        // Scoped: the first '@' is part of the scope
+        if (atIndex > 0) {
+            const name = nameAndVersion.slice(0, atIndex);
+            const version = nameAndVersion.slice(atIndex + 1) || undefined;
+            return { name, version, subpath };
+        }
+        return { name: nameAndVersion, subpath };
+    } else {
+        if (atIndex > 0) {
+            const name = nameAndVersion.slice(0, atIndex);
+            const version = nameAndVersion.slice(atIndex + 1) || undefined;
+            return { name, version, subpath };
+        }
+        return { name: nameAndVersion, subpath };
+    }
+}
+
+function toCdnUrl(spec: NpmSpec, cdn: 'jsdelivr' | 'unpkg' | 'esm.sh'): string {
+    const versionSegment = spec.version ? `@${spec.version}` : '';
+    const subpath = spec.subpath ? spec.subpath.replace(/^\//, '') : 'plugin';
+    switch (cdn) {
+        case 'unpkg':
+            return `https://unpkg.com/${spec.name}${versionSegment}/${subpath}`;
+        case 'esm.sh':
+            // esm.sh expects ?path=/subpath or direct subpath after package
+            // Use direct subpath; esm.sh will transform to ESM
+            return `https://esm.sh/${spec.name}${versionSegment}/${subpath}`;
+        case 'jsdelivr':
+        default:
+            return `https://cdn.jsdelivr.net/npm/${spec.name}${versionSegment}/${subpath}`;
+    }
+}
+