@cadit-app/script-params 0.5.2 → 0.5.3

package/dist/script.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Script module types and core functions (defineParams, createMain).
+ *
+ * This module provides the main API for defining parametric scripts.
+ */
+import type { ParamSchema, Params } from './params';
+import type { Exporters } from './exporters';
+/**
+ * Configuration object for defineParams when using named properties.
+ * All options are named for clarity and extensibility.
+ */
+export interface ScriptConfig<S extends ParamSchema, R = unknown> {
+    /** The parameter schema defining all inputs. */
+    params: S;
+    /** Optional main function that generates geometry. */
+    main?: (params: Params<S>) => R;
+    /** Optional exporters for custom download formats (SVG, PNG, etc.). */
+    exporters?: Exporters<Params<S>>;
+}
+/**
+ * The result returned by defineParams.
+ * Contains the schema (for UI), optional exporters, and is optionally callable.
+ */
+export interface ScriptModule<S extends ParamSchema, R = unknown> {
+    /** The parameter schema for UI generation. */
+    params: S;
+    /** Optional exporters for custom download formats. */
+    exporters?: Exporters<Params<S>>;
+    /**
+     * Execute the script with optional parameter overrides.
+     * Missing parameters use their default values.
+     * Only available if a main function was provided.
+     */
+    (inputParams?: Partial<Params<S>>): R;
+}
+/**
+ * Infer the params type from a ScriptModule.
+ * Use this to get the typed params for use in exporters defined in separate files.
+ *
+ * @example
+ * ```typescript
+ * // In main.ts
+ * const script = defineParams({
+ *   params: {
+ *     size: { type: 'number', default: 10 },
+ *     label: { type: 'text', default: 'Hello' },
+ *   },
+ *   main: (p) => { ... },
+ * });
+ * export default script;
+ *
+ * // In pngExport.ts
+ * import type { Exporter, InferParams } from '@cadit-app/script-params';
+ * import type script from './main';
+ *
+ * type QrCodeParams = InferParams<typeof script>;
+ * // { size: number; label: string }
+ *
+ * export const pngExporter: Exporter<QrCodeParams> = {
+ *   name: 'PNG',
+ *   export: (params) => { ... }, // params.size is number, params.label is string
+ * };
+ * ```
+ */
+export type InferParams<T> = T extends ScriptModule<infer S, unknown> ? Params<S> : T extends {
+    params: infer S extends ParamSchema;
+} ? Params<S> : never;
+/**
+ * Build default values object from a schema.
+ * @internal
+ */
+declare function buildDefaults<S extends ParamSchema>(schema: S): Params<S>;
+/**
+ * Define parameters for a parametric script.
+ *
+ * Pass a config object with `params` (required), and optionally `main` and `exporters`.
+ *
+ * @example Basic usage
+ * ```typescript
+ * export default defineParams({
+ *   params: {
+ *     size: { type: 'number', default: 10 },
+ *   },
+ *   main: (params) => Manifold.cube([params.size, params.size, params.size]),
+ * });
+ * ```
+ *
+ * @example With exporters
+ * ```typescript
+ * export default defineParams({
+ *   params: {
+ *     size: { type: 'number', default: 10 },
+ *   },
+ *   exporters: {
+ *     svg: { name: 'SVG', export: (p) => svgExport(p) },
+ *     png: { name: 'PNG', export: (p) => pngExport(p) },
+ *   },
+ *   main: (params) => Manifold.cube([params.size, params.size, params.size]),
+ * });
+ * ```
+ *
+ * @example Without main (add main separately with createMain)
+ * ```typescript
+ * const script = defineParams({
+ *   params: { size: { type: 'number', default: 10 } },
+ *   exporters: { svg: svgExporter },
+ * });
+ * export default createMain(script, myMainFunction);
+ * ```
+ */
+export declare function defineParams<const S extends ParamSchema, R = unknown>(config: ScriptConfig<S, R>): ScriptModule<S, R>;
+/**
+ * Create an executable script module by adding a main function.
+ *
+ * Use this when you want to define your main function separately from the params,
+ * for example when the main is complex or needs to be tested independently.
+ *
+ * Preserves any exporters defined on the original ScriptModule.
+ *
+ * @example
+ * ```typescript
+ * const script = defineParams({
+ *   params: { size: { type: 'number', default: 10 } },
+ *   exporters: { svg: svgExporter },
+ * });
+ *
+ * export default createMain(script, (p) => Manifold.cube([p.size, ...]));
+ * ```
+ */
+export declare function createMain<S extends ParamSchema, R>(scriptModule: ScriptModule<S, unknown>, main: (params: Params<S>) => R): ScriptModule<S, R>;
+export { buildDefaults as _buildDefaults };
+//# sourceMappingURL=script.d.ts.map

package/dist/script.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"script.d.ts","sourceRoot":"","sources":["../src/script.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,EAAoB,MAAM,UAAU,CAAC;AACtE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAM7C;;;GAGG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,WAAW,EAAE,CAAC,GAAG,OAAO;IAC9D,gDAAgD;IAChD,MAAM,EAAE,CAAC,CAAC;IACV,sDAAsD;IACtD,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IAChC,uEAAuE;IACvE,SAAS,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;CAClC;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,WAAW,EAAE,CAAC,GAAG,OAAO;IAC9D,8CAA8C;IAC9C,MAAM,EAAE,CAAC,CAAC;IACV,sDAAsD;IACtD,SAAS,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IACjC;;;;OAIG;IACH,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;CACvC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,SAAS,YAAY,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,GACjE,MAAM,CAAC,CAAC,CAAC,GACT,CAAC,SAAS;IAAE,MAAM,EAAE,MAAM,CAAC,SAAS,WAAW,CAAA;CAAE,GAC/C,MAAM,CAAC,CAAC,CAAC,GACT,KAAK,CAAC;AAMZ;;;GAGG;AACH,iBAAS,aAAa,CAAC,CAAC,SAAS,WAAW,EAAE,MAAM,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAgBlE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,YAAY,CAAC,KAAK,CAAC,CAAC,SAAS,WAAW,EAAE,CAAC,GAAG,OAAO,EACnE,MAAM,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,GACzB,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,CAmBpB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,WAAW,EAAE,CAAC,EACjD,YAAY,EAAE,YAAY,CAAC,CAAC,EAAE,OAAO,CAAC,EACtC,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,GAC7B,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,CAcpB;AAGD,OAAO,EAAE,aAAa,IAAI,cAAc,EAAE,CAAC"}

package/dist/script.js

@@ -0,0 +1,117 @@
+/**
+ * Script module types and core functions (defineParams, createMain).
+ *
+ * This module provides the main API for defining parametric scripts.
+ */
+// =============================================================================
+// Core Functions
+// =============================================================================
+/**
+ * Build default values object from a schema.
+ * @internal
+ */
+function buildDefaults(schema) {
+    const defaults = {};
+    for (const [key, def] of Object.entries(schema)) {
+        if (def.type === 'embedded') {
+            // For embedded params, build a nested default object
+            const embeddedDef = def;
+            defaults[key] = {
+                enabled: embeddedDef.enabled ?? false,
+                showSettings: embeddedDef.showSettings ?? false,
+                params: buildDefaults(embeddedDef.params),
+            };
+        }
+        else {
+            defaults[key] = def.default;
+        }
+    }
+    return defaults;
+}
+/**
+ * Define parameters for a parametric script.
+ *
+ * Pass a config object with `params` (required), and optionally `main` and `exporters`.
+ *
+ * @example Basic usage
+ * ```typescript
+ * export default defineParams({
+ *   params: {
+ *     size: { type: 'number', default: 10 },
+ *   },
+ *   main: (params) => Manifold.cube([params.size, params.size, params.size]),
+ * });
+ * ```
+ *
+ * @example With exporters
+ * ```typescript
+ * export default defineParams({
+ *   params: {
+ *     size: { type: 'number', default: 10 },
+ *   },
+ *   exporters: {
+ *     svg: { name: 'SVG', export: (p) => svgExport(p) },
+ *     png: { name: 'PNG', export: (p) => pngExport(p) },
+ *   },
+ *   main: (params) => Manifold.cube([params.size, params.size, params.size]),
+ * });
+ * ```
+ *
+ * @example Without main (add main separately with createMain)
+ * ```typescript
+ * const script = defineParams({
+ *   params: { size: { type: 'number', default: 10 } },
+ *   exporters: { svg: svgExporter },
+ * });
+ * export default createMain(script, myMainFunction);
+ * ```
+ */
+export function defineParams(config) {
+    const { params: schema, main, exporters } = config;
+    const defaults = buildDefaults(schema);
+    const scriptModule = ((inputParams) => {
+        if (!main) {
+            throw new Error('This script does not have a main function. Use createMain() to add one.');
+        }
+        const merged = { ...defaults, ...inputParams };
+        return main(merged);
+    });
+    scriptModule.params = schema;
+    if (exporters) {
+        scriptModule.exporters = exporters;
+    }
+    return scriptModule;
+}
+/**
+ * Create an executable script module by adding a main function.
+ *
+ * Use this when you want to define your main function separately from the params,
+ * for example when the main is complex or needs to be tested independently.
+ *
+ * Preserves any exporters defined on the original ScriptModule.
+ *
+ * @example
+ * ```typescript
+ * const script = defineParams({
+ *   params: { size: { type: 'number', default: 10 } },
+ *   exporters: { svg: svgExporter },
+ * });
+ *
+ * export default createMain(script, (p) => Manifold.cube([p.size, ...]));
+ * ```
+ */
+export function createMain(scriptModule, main) {
+    const defaults = buildDefaults(scriptModule.params);
+    const newModule = ((inputParams) => {
+        const merged = { ...defaults, ...inputParams };
+        return main(merged);
+    });
+    newModule.params = scriptModule.params;
+    if (scriptModule.exporters) {
+        newModule.exporters = scriptModule.exporters;
+    }
+    return newModule;
+}
+// Re-export buildDefaults for internal use
+export { buildDefaults as _buildDefaults };
+//# sourceMappingURL=script.js.map

package/dist/script.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"script.js","sourceRoot":"","sources":["../src/script.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA0EH,gFAAgF;AAChF,iBAAiB;AACjB,gFAAgF;AAEhF;;;GAGG;AACH,SAAS,aAAa,CAAwB,MAAS;IACrD,MAAM,QAAQ,GAAG,EAAe,CAAC;IACjC,KAAK,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAChD,IAAI,GAAG,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YAC5B,qDAAqD;YACrD,MAAM,WAAW,GAAG,GAAuB,CAAC;YAC3C,QAAoC,CAAC,GAAG,CAAC,GAAG;gBAC3C,OAAO,EAAE,WAAW,CAAC,OAAO,IAAI,KAAK;gBACrC,YAAY,EAAE,WAAW,CAAC,YAAY,IAAI,KAAK;gBAC/C,MAAM,EAAE,aAAa,CAAC,WAAW,CAAC,MAAM,CAAC;aAC1C,CAAC;QACJ,CAAC;aAAM,CAAC;YACL,QAAoC,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC;QAC3D,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,UAAU,YAAY,CAC1B,MAA0B;IAE1B,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,MAAM,CAAC;IAEnD,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IAEvC,MAAM,YAAY,GAAG,CAAC,CAAC,WAAgC,EAAK,EAAE;QAC5D,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,MAAM,IAAI,KAAK,CAAC,yEAAyE,CAAC,CAAC;QAC7F,CAAC;QACD,MAAM,MAAM,GAAG,EAAE,GAAG,QAAQ,EAAE,GAAG,WAAW,EAAe,CAAC;QAC5D,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC;IACtB,CAAC,CAAuB,CAAC;IAEzB,YAAY,CAAC,MAAM,GAAG,MAAM,CAAC;IAC7B,IAAI,SAAS,EAAE,CAAC;QACd,YAAY,CAAC,SAAS,GAAG,SAAS,CAAC;IACrC,CAAC;IAED,OAAO,YAAY,CAAC;AACtB,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,UAAU,CACxB,YAAsC,EACtC,IAA8B;IAE9B,MAAM,QAAQ,GAAG,aAAa,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;IAEpD,MAAM,SAAS,GAAG,CAAC,CAAC,WAAgC,EAAK,EAAE;QACzD,MAAM,MAAM,GAAG,EAAE,GAAG,QAAQ,EAAE,GAAG,WAAW,EAAe,CAAC;QAC5D,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC;IACtB,CAAC,CAAuB,CAAC;IAEzB,SAAS,CAAC,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC;IACvC,IAAI,YAAY,CAAC,SAAS,EAAE,CAAC;QAC3B,SAAS,CAAC,SAAS,GAAG,YAAY,CAAC,SAAS,CAAC;IAC/C,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,2CAA2C;AAC3C,OAAO,EAAE,aAAa,IAAI,cAAc,EAAE,CAAC"}

package/dist/utils.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Utility functions for working with script-params.
+ *
+ * Includes conversion utilities, validation functions, and helpers for
+ * embedding parameters from other scripts.
+ */
+import type { ParamSchema, Params, EmbeddedParamDef } from './params';
+import type { ScriptModule } from './script';
+import type { Exporters } from './exporters';
+/**
+ * Convert an object-based schema to array format for legacy UI compatibility.
+ *
+ * This function transforms the script-params schema format into the
+ * ObjectMakerParam[] format expected by the Core UI.
+ *
+ * @example
+ * ```typescript
+ * const schema = { size: { type: 'number', default: 10 } };
+ * const array = schemaToArray(schema);
+ * // [{ name: 'size', type: 'number', initial: 10, caption: 'size' }]
+ * ```
+ */
+export declare function schemaToArray<S extends ParamSchema>(schema: S): Array<Record<string, unknown>>;
+/**
+ * Extract defaults from a schema as a plain object.
+ *
+ * @example
+ * ```typescript
+ * const schema = {
+ *   size: { type: 'number', default: 10 },
+ *   label: { type: 'text', default: 'Hi' },
+ * };
+ * const defaults = getDefaults(schema);
+ * // { size: 10, label: 'Hi' }
+ * ```
+ */
+export declare function getDefaults<S extends ParamSchema>(schema: S): Params<S>;
+/**
+ * Check if a module export uses the defineParams format.
+ *
+ * @example
+ * ```typescript
+ * const mod = await import('./script.ts');
+ * if (isScriptModule(mod.default)) {
+ *   const result = mod.default({ size: 20 });
+ * }
+ * ```
+ */
+export declare function isScriptModule(value: unknown): value is ScriptModule<ParamSchema, unknown>;
+/**
+ * Extract the parameter schema from a ScriptModule.
+ * Useful for embedding another script's parameters.
+ *
+ * @example
+ * ```typescript
+ * import qrCodeScript from './qr-code';
+ *
+ * const qrParams = getParams(qrCodeScript);
+ *
+ * // Use in embedded param definition
+ * export default defineParams({
+ *   params: {
+ *     qrCode: {
+ *       type: 'embedded',
+ *       params: getParams(qrCodeScript),
+ *       enabled: false,
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export declare function getParams<S extends ParamSchema>(source: ScriptModule<S, unknown>): S;
+/**
+ * Extract exporters from a ScriptModule.
+ * Returns an empty object if the module has no exporters.
+ *
+ * @example
+ * ```typescript
+ * import qrCodeScript from './qr-code';
+ *
+ * const exporters = getExporters(qrCodeScript);
+ * // { svg: { name: 'SVG', ... }, png: { name: 'PNG', ... } }
+ * ```
+ */
+export declare function getExporters<S extends ParamSchema>(source: ScriptModule<S, unknown>): Exporters<Params<S>>;
+/**
+ * Helper to create an embedded param definition with npm package metadata.
+ * This enables relative asset paths (like buttonGrid images) to be resolved
+ * correctly when embedding another npm package's parameters.
+ *
+ * @param npmPackage - The npm package name (e.g., '@cadit-app/qr-code')
+ * @param embeddedDef - The embedded param definition
+ * @returns The embedded definition with npmPackage attached
+ *
+ * @example
+ * ```typescript
+ * import qrCodeModule from '@cadit-app/qr-code';
+ * import { defineParams, embedParams } from '@cadit-app/script-params';
+ *
+ * export default defineParams({
+ *   params: {
+ *     qrCodeSettings: embedParams('@cadit-app/qr-code', {
+ *       type: 'embedded',
+ *       label: 'QR Code (Optional)',
+ *       params: qrCodeModule.params,
+ *       enabled: false,
+ *       showSettings: false,
+ *     }),
+ *   },
+ *   main: (params) => { ... },
+ * });
+ * ```
+ */
+export declare function embedParams(npmPackage: string, embeddedDef: Omit<EmbeddedParamDef, 'npmPackage'>): EmbeddedParamDef;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAY,MAAM,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAChF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AA2F7C;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,WAAW,EACjD,MAAM,EAAE,CAAC,GACR,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAEhC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,WAAW,EAAE,MAAM,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAEvE;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,YAAY,CAAC,WAAW,EAAE,OAAO,CAAC,CAO7C;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,WAAW,EAC7C,MAAM,EAAE,YAAY,CAAC,CAAC,EAAE,OAAO,CAAC,GAC/B,CAAC,CAEH;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,WAAW,EAChD,MAAM,EAAE,YAAY,CAAC,CAAC,EAAE,OAAO,CAAC,GAC/B,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAEtB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,WAAW,CACzB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,IAAI,CAAC,gBAAgB,EAAE,YAAY,CAAC,GAChD,gBAAgB,CAKlB"}

package/dist/utils.js

@@ -0,0 +1,224 @@
+/**
+ * Utility functions for working with script-params.
+ *
+ * Includes conversion utilities, validation functions, and helpers for
+ * embedding parameters from other scripts.
+ */
+import { _buildDefaults } from './script';
+// =============================================================================
+// Schema Conversion Utilities
+// =============================================================================
+/**
+ * Convert a single param def to ObjectMakerParam format.
+ * Handles special cases like embedded params that need recursive conversion.
+ * @internal
+ */
+function convertParamDef(name, def) {
+    const base = {
+        name,
+        type: def.type,
+        caption: def.label ?? name,
+    };
+    // Copy common properties
+    if ('default' in def) {
+        base.initial = def.default;
+    }
+    if ('min' in def)
+        base.min = def.min;
+    if ('max' in def)
+        base.max = def.max;
+    if ('step' in def)
+        base.step = def.step;
+    if ('maxLength' in def)
+        base.maxLength = def.maxLength;
+    // Handle type-specific conversions
+    switch (def.type) {
+        case 'choice':
+        case 'radio': {
+            // Handle both simple string options and { value, label } objects
+            const options = def.options;
+            const values = [];
+            const captions = [];
+            let hasCaptions = false;
+            for (const opt of options) {
+                if (typeof opt === 'string') {
+                    values.push(opt);
+                    captions.push(opt); // Use value as caption if no label
+                }
+                else {
+                    values.push(opt.value);
+                    captions.push(opt.label ?? opt.value);
+                    if (opt.label)
+                        hasCaptions = true;
+                }
+            }
+            base.values = values;
+            // Only set captions if at least one option has a label
+            if (hasCaptions) {
+                base.captions = captions;
+            }
+            break;
+        }
+        case 'buttonGrid': {
+            // Convert buttonGrid options to ObjectMakerButtonGridParam format
+            base.options = def.options.map((opt) => ({
+                value: opt.value,
+                image: opt.image,
+                caption: opt.caption,
+            }));
+            break;
+        }
+        case 'preset': {
+            // Convert preset options to ObjectMakerPresetParam format
+            base.presets = def.presets.map((preset) => ({
+                value: preset.value,
+                label: preset.label,
+                presetValues: preset.presetValues,
+            }));
+            break;
+        }
+        case 'embedded': {
+            // Convert embedded params recursively
+            const embeddedDef = def;
+            base.parameters = schemaToArray(embeddedDef.params);
+            base.enabled = embeddedDef.enabled ?? false;
+            base.showSettings = embeddedDef.showSettings ?? false;
+            // Propagate npm package for resolving relative asset URLs
+            if (embeddedDef.npmPackage) {
+                base.npmPackage = embeddedDef.npmPackage;
+            }
+            break;
+        }
+    }
+    return base;
+}
+/**
+ * Convert an object-based schema to array format for legacy UI compatibility.
+ *
+ * This function transforms the script-params schema format into the
+ * ObjectMakerParam[] format expected by the Core UI.
+ *
+ * @example
+ * ```typescript
+ * const schema = { size: { type: 'number', default: 10 } };
+ * const array = schemaToArray(schema);
+ * // [{ name: 'size', type: 'number', initial: 10, caption: 'size' }]
+ * ```
+ */
+export function schemaToArray(schema) {
+    return Object.entries(schema).map(([name, def]) => convertParamDef(name, def));
+}
+/**
+ * Extract defaults from a schema as a plain object.
+ *
+ * @example
+ * ```typescript
+ * const schema = {
+ *   size: { type: 'number', default: 10 },
+ *   label: { type: 'text', default: 'Hi' },
+ * };
+ * const defaults = getDefaults(schema);
+ * // { size: 10, label: 'Hi' }
+ * ```
+ */
+export function getDefaults(schema) {
+    return _buildDefaults(schema);
+}
+// =============================================================================
+// ScriptModule Utilities
+// =============================================================================
+/**
+ * Check if a module export uses the defineParams format.
+ *
+ * @example
+ * ```typescript
+ * const mod = await import('./script.ts');
+ * if (isScriptModule(mod.default)) {
+ *   const result = mod.default({ size: 20 });
+ * }
+ * ```
+ */
+export function isScriptModule(value) {
+    return (typeof value === 'function' &&
+        'params' in value &&
+        typeof value.params === 'object' &&
+        value.params !== null);
+}
+/**
+ * Extract the parameter schema from a ScriptModule.
+ * Useful for embedding another script's parameters.
+ *
+ * @example
+ * ```typescript
+ * import qrCodeScript from './qr-code';
+ *
+ * const qrParams = getParams(qrCodeScript);
+ *
+ * // Use in embedded param definition
+ * export default defineParams({
+ *   params: {
+ *     qrCode: {
+ *       type: 'embedded',
+ *       params: getParams(qrCodeScript),
+ *       enabled: false,
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export function getParams(source) {
+    return source.params;
+}
+/**
+ * Extract exporters from a ScriptModule.
+ * Returns an empty object if the module has no exporters.
+ *
+ * @example
+ * ```typescript
+ * import qrCodeScript from './qr-code';
+ *
+ * const exporters = getExporters(qrCodeScript);
+ * // { svg: { name: 'SVG', ... }, png: { name: 'PNG', ... } }
+ * ```
+ */
+export function getExporters(source) {
+    return source.exporters ?? {};
+}
+// =============================================================================
+// Embedding Utilities
+// =============================================================================
+/**
+ * Helper to create an embedded param definition with npm package metadata.
+ * This enables relative asset paths (like buttonGrid images) to be resolved
+ * correctly when embedding another npm package's parameters.
+ *
+ * @param npmPackage - The npm package name (e.g., '@cadit-app/qr-code')
+ * @param embeddedDef - The embedded param definition
+ * @returns The embedded definition with npmPackage attached
+ *
+ * @example
+ * ```typescript
+ * import qrCodeModule from '@cadit-app/qr-code';
+ * import { defineParams, embedParams } from '@cadit-app/script-params';
+ *
+ * export default defineParams({
+ *   params: {
+ *     qrCodeSettings: embedParams('@cadit-app/qr-code', {
+ *       type: 'embedded',
+ *       label: 'QR Code (Optional)',
+ *       params: qrCodeModule.params,
+ *       enabled: false,
+ *       showSettings: false,
+ *     }),
+ *   },
+ *   main: (params) => { ... },
+ * });
+ * ```
+ */
+export function embedParams(npmPackage, embeddedDef) {
+    return {
+        ...embeddedDef,
+        npmPackage,
+    };
+}
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cadit-app/script-params",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "Type-safe parameter definitions for CADit scripts",
   "type": "module",
   "main": "./dist/index.js",