@sheetxl/sdk 0.7.28-beta.4 → 0.8.0-beta.10

package/types/src/scripting/IScript.d.ts

@@ -97,29 +97,19 @@ export interface IScript {
      */
     isReadOnly(): boolean;
     /**
-     * Convenience method for creating a module from a file.
+     * Searches the functions of every loaded module — macros, auto-run functions and custom formula
+     * functions — as ONE list.
+     *
+     * @param options {@link IScript.SearchOptions}
      *
      * @remarks
-     * equivalent to `getModules().search( { type: 'macro', name } )`
+     * {@link IScript.SearchOptions.limit} and the ordering of {@link IFunctionCollection.search}
+     * apply to the union, not to each module separately.
      *
-     * Searches every loaded module and — with {@link IScript.SearchOptions.includeBuiltIn} — the
-     * built-in functions, as ONE list: {@link IScript.SearchOptions.limit} and the relevance ordering
-     * of {@link IFunctionCollection.search} apply to the union, not to each source separately.
+     * Built-in functions are not scripts and are not searched here. Every function a formula can call,
+     * built-in or custom, is in `workbook.getCalculation().getFunctions()`.
      */
     searchFunctions(options?: IScript.SearchOptions): Promise<IFunction[]>;
-    /**
-     * The categories the searchable functions declare, each with how many functions carry it.
-     *
-     * @param options {@link IScript.GetCategoryOptions}
-     *
-     * @returns The categories, ordered by name; counts are summed across every source searched.
-     *
-     * @remarks
-     * The workbook-level {@link IFunctionCollection.getCategories} — a function picker builds its
-     * category list from this, so a module's custom functions show up in it (in their own category, or
-     * swelling the count of a built-in one they declare).
-     */
-    getFunctionCategories(options?: IScript.GetCategoryOptions): Promise<IFunctionCollection.Category[]>;
     /**
      * Add Listeners.
      *
@@ -131,6 +121,8 @@ export interface IScript {
      * Returns a JSON representation of the script.
      */
     toJSON(): Record<string, IModule.JSON>;
+    /** For runtime type checking. */
+    readonly isIScript: true;
 }
 /**
  * {@inheritDoc IFunctionCollection}
@@ -140,6 +132,10 @@ export interface IScript {
  * {@link IFunctionCollection}
  */
 export declare namespace IScript {
+    /**
+     * The name a module gets when nothing named it — the one an editor opens by default.
+     */
+    const DEFAULT_MODULE: string;
     /**
      * Events for {@link ISheet}.
      */
@@ -250,6 +246,18 @@ export declare namespace IScript {
          * objects fall back to JSON.
          */
         render?: LogRenderer;
+        /**
+         * How long a finished run waits for what it logged to settle, in milliseconds. `0` waits
+         * indefinitely.
+         *
+         * @remarks
+         * `log(promise)` prints what the promise settles to, so a run is not done until its log is. A
+         * value still unsettled when this elapses prints as `[pending]`; nothing is thrown and the rest
+         * of the log is kept.
+         *
+         * @defaultValue 10 seconds
+         */
+        logTimeoutMs?: number;
     }
     /**
      * The result of {@link IScript.run}.
@@ -272,18 +280,12 @@ export declare namespace IScript {
          */
         diagnostics?: IModule.Diagnostic[];
     }
-    interface SearchOptions extends IFunctionCollection.SearchOptions {
-        moduleName?: string;
-        includeBuiltIn?: boolean;
-    }
     /**
-     * Options for {@link IScript.getFunctionCategories}.
+     * Options for {@link IScript.searchFunctions}.
      */
-    interface GetCategoryOptions extends IFunctionCollection.GetCategoryOptions {
+    interface SearchOptions extends IFunctionCollection.SearchOptions {
         /** Restrict to one module's functions. */
         moduleName?: string;
-        /** Include the categories of the built-in functions. */
-        includeBuiltIn?: boolean;
     }
 }
 //# sourceMappingURL=IScript.d.ts.map

package/types/src/scripting/Module.d.ts

@@ -11,12 +11,12 @@ export declare class Module implements IModule {
     protected _diagnostics: Diagnostic[];
     protected _emitter: ListenerEmitter<IModule, IModule.IListeners>;
     protected _name: string;
-    constructor(options: {
-        json: IModule.JSON;
-        readonlyFunctions: Map<string, IFunction>;
-        name: string;
-        diagnostics?: Diagnostic[];
-    });
+    /**
+     * Derived by whoever built the module from where it is stored, never read from the JSON —
+     * see {@link IModule.getScope}. Held as a getter so the module does not pin a closed sheet.
+     */
+    protected _scope: () => IModule.Scope;
+    constructor(options: Module.ConstructorOptions);
     /** {@inheritDoc IModule.getName} */
     getName(): string;
     /** {@inheritDoc IModule.getFunctions} */
@@ -25,15 +25,43 @@ export declare class Module implements IModule {
     getSource(): string | null;
     /** {@inheritDoc IModule.getLanguage} */
     getLanguage(): string;
+    /** {@inheritDoc IModule.getScope} */
+    getScope(): IModule.Scope;
     /** {@inheritDoc IModule.getErrors} */
     getErrors(): any[];
     /** {@inheritDoc IModule.getDiagnostics} */
     getDiagnostics(): Diagnostic[];
     /** {@inheritDoc IModule.delete} */
     delete(): void;
+    /**
+     * Set by the collection holding this module; throws to refuse a delete. A listener cannot refuse
+     * one — listener errors do not reach the caller.
+     * @internal
+     */
+    _setBeforeDelete(beforeDelete: (() => void) | null): void;
+    private _beforeDelete;
     /** {@inheritDoc IModule.addListeners} */
     addListeners(listeners: IModule.IListeners, options?: IListener.Options): IListener.Remove;
     /** {@inheritDoc IModule.toJSON} */
     toJSON(): IModule.JSON;
+    /** {@inheritDoc IModule.isIModule} */
+    get isIModule(): true;
+}
+export declare namespace Module {
+    interface ConstructorOptions {
+        json: IModule.JSON;
+        readonlyFunctions: Map<string, IFunction>;
+        name: string;
+        diagnostics?: Diagnostic[];
+        /**
+         * What the module is bound to, as decided by whoever is storing it.
+         *
+         * A function is accepted so an owner that is not built yet (a sheet still constructing) can
+         * be resolved on demand rather than captured.
+         *
+         * @defaultValue `null` (global)
+         */
+        scope?: IModule.Scope | (() => IModule.Scope);
+    }
 }
 //# sourceMappingURL=Module.d.ts.map

package/types/src/scripting/ModuleCollection.d.ts

@@ -1,31 +1,26 @@
+import { AbstractCollection } from '../type';
 import { ITransaction } from '../transaction';
 import { IListener } from '../listener';
-import { ListenerEmitter } from '../listener/ListenerEmitter';
 import { IModule } from './IModule';
 import { IModuleCollection } from './IModuleCollection';
 /**
  * Implementation for `IModuleCollection`.
  */
-export declare class ModuleCollection implements IModuleCollection {
-    protected _emitter: ListenerEmitter<this, IModuleCollection.IListeners>;
+export declare class ModuleCollection extends AbstractCollection<IModule, IModuleCollection.GetItemsOptions> implements IModuleCollection {
     private _options;
-    private _transactions;
+    protected _transactions: ITransaction.IStore;
     private _stateId;
     private _transactionsRemoveListener;
-    private _closed;
     constructor(options: ModuleCollection.ConstructorOptions);
     /** {@inheritDoc IModuleCollection.add} */
     add(uid: string, module: IModule, options?: IModuleCollection.AddOptions): void;
-    /** {@inheritDoc ICollection.[Symbol.iterator]} */
-    [Symbol.iterator](): IterableIterator<IModule>;
-    /** {@inheritDoc IModuleCollection.getItems} */
-    getItems(options?: IModuleCollection.GetItemsOptions): IModule[];
+    /** {@inheritDoc AbstractCollection._getItems} */
+    protected _getItems(options?: IModuleCollection.GetItemsOptions): IModule[];
     /** {@inheritDoc IModuleCollection.getByName} */
     getByName(name: string): IModule | null;
-    /** {@inheritDoc ICollection.getCount} */
-    getCount(): number;
     /** {@inheritDoc ITransaction.ITransactional.beginCommit} */
     beginCommit(options?: string | ITransaction.OperationOptions): ITransaction;
+    private _assertWritable;
     private _getState;
     private _beginCommit;
     private _updateState;
@@ -34,9 +29,14 @@ export declare class ModuleCollection implements IModuleCollection {
     addListeners(listeners: IModuleCollection.IListeners, options?: IListener.Options): IListener.Remove;
     /** {@inheritDoc IModuleCollection.toJSON} */
     toJSON(): Record<string, IModule.JSON>;
-    isClosed(): boolean;
+    /**
+     * Closes the collection. Called by the owner when it closes; announces
+     * {@link ICollection.Events.onClose} once.
+     */
     close(): void;
     get isFunctionCollection(): true;
+    /** {@inheritDoc IModuleCollection.isIModuleCollection} */
+    get isIModuleCollection(): true;
 }
 export declare namespace ModuleCollection {
     interface ConstructorOptions {
@@ -51,6 +51,11 @@ export declare namespace ModuleCollection {
         /** `module` is `null` when the removal came from saving empty content. */
         onRemove?: (moduleId: string, module: IModule | null) => void;
         onAdd?: (moduleId: string, module: IModule) => void;
+        /**
+         * Whether adding, replacing and deleting modules is refused. Loading the initial modules never
+         * is.
+         */
+        isReadOnly?: () => boolean;
     }
 }
 //# sourceMappingURL=ModuleCollection.d.ts.map

package/types/src/scripting/Runtime.d.ts

@@ -13,4 +13,19 @@ export declare const GLOBAL_SCRIPT_VARIABLE = "SheetXL";
 export declare function getRuntime(): Promise<any>;
 export declare function setGlobalRuntime(): Promise<void>;
 export declare function clearGlobalRuntime(): void;
+/**
+ * The runtime value of the `SheetXL` global — the enum constants `scripting.d.ts` declares — for a
+ * host that binds it into a scope of its own (a REPL context) rather than onto `globalThis`.
+ */
+export declare function getScriptRuntime(): Promise<any>;
+/**
+ * Runs `fn` with the `SheetXL` global installed, and removes it again however `fn` ends.
+ *
+ * @remarks
+ * For a host that executes script source WITHOUT compiling it to a module (the CLI's `-e`/`-f`,
+ * which type-strip and import): a compiled macro gets the global from the macro runtime, and this
+ * is how every other path keeps the same promise the declarations make. Wrap the LOAD as well as
+ * the call — a script may read `SheetXL.ISheet.Visibility.Hidden` at module top level.
+ */
+export declare function withScriptRuntime<T>(fn: () => Promise<T>): Promise<T>;
 //# sourceMappingURL=Runtime.d.ts.map

package/types/src/scripting/Scripts.d.ts

@@ -43,16 +43,10 @@ export declare class Scripts implements IScript {
      * executes it once against the workbook. `source` is used only to format diagnostic positions.
      */
     private _runModule;
-    /**
-     * The collections {@link searchFunctions} and {@link getFunctionCategories} span: the built-ins
-     * (when asked for) followed by each loaded module's — built-ins first, so a name they share
-     * resolves to the built-in, the way `getByName` does.
-     */
+    /** The module collections {@link searchFunctions} spans, in load order. */
     private _searchable;
     /** {@inheritDoc IScript.searchFunctions} */
     searchFunctions(options?: IScript.SearchOptions): Promise<IFunction[]>;
-    /** {@inheritDoc IScript.getFunctionCategories} */
-    getFunctionCategories(options?: IScript.GetCategoryOptions): Promise<IFunctionCollection.Category[]>;
     /** {@inheritDoc IScript.start} */
     start(): Promise<void>;
     private _doStart;
@@ -62,6 +56,8 @@ export declare class Scripts implements IScript {
     isReadOnly(): boolean;
     /** {@inheritDoc IScript.toJSON} */
     toJSON(): Record<string, IModule.JSON>;
+    /** {@inheritDoc IScript.isIScript} */
+    get isIScript(): true;
 }
 export declare namespace Scripts {
     interface ConstructorOptions {

package/types/src/scripting/TypedFunction.d.ts

@@ -1,10 +1,87 @@
-import { ScalarType, IRange, IFunction, IFormulaContext } from '@sheetxl/primitives';
+import { ScalarType, FormulaError, IRange, IFunction, IFormulaContext } from '@sheetxl/primitives';
+import { FixedPackedArray } from '../primitives/PrimitiveUtils';
 /**
  * The per-call shape of a declaration that carries a repeating group, resolved from the ARGUMENT
- * COUNT alone (`Repeating<T>`; DESIGN-ENUM §5). Excel is measured never to disambiguate by type —
+ * COUNT alone (`Repeating<T>`; DESIGN-REPEATING §2). Excel is measured never to disambiguate by type —
  * `SORTBY(array, by1, by2, o2)` is refused where a type-directed parse would have read argument 2
  * as `by_array2` — so the arithmetic is the whole rule.
  */
+/**
+ * What `_exec` needs to know about ONE parameter position, decided once per declaration (and
+ * once per expanded {@link RepeatPlan}) rather than on every call: the normalized value types,
+ * the kind flags the coercion loop branches on, and the effective error policy where it does not
+ * depend on the argument. The per-call loop reads this and the raw JSON only on its rare paths.
+ */
+/**
+ * The member set of an enum slot, precomputed per declaration. A slot holds numbers or strings,
+ * never both, so exactly one of the two is set.
+ */
+interface EnumGate {
+    numbers: ReadonlySet<number> | null;
+    /** Lower-cased spelling to the DECLARED one: a formula is case-insensitive, the body is not. */
+    strings: ReadonlyMap<string, string> | null;
+}
+interface ParamSpec {
+    /** `param.scalar` with `Null` and `*` normalized to `null` (no coercion). */
+    scalarType: ScalarType | null;
+    /** `range === '*'` — marshals as `'r'` and never triggers a lift (see the `_lc` table). */
+    isAny: boolean;
+    /** The marshalling range kind, `*` already folded to `'r'`. */
+    rangeType: 'p' | 'r' | 'm' | null;
+    rest: boolean;
+    optional: boolean;
+    /** A lambda slot (`param.lambda != null`) — takes a callable, never a member. */
+    isLambda: boolean;
+    /**
+     * The `Lazy` marker: the argument's subtree may reach the body UNEVALUATED, as a handle. The
+     * slot's {@link IFunction.ParameterTypeJSON.defaultValue} is APPLIED here rather than merely
+     * recorded, since a handle-typed parameter carries no initializer of its own.
+     */
+    lazy: boolean;
+    /** `arrayDepth > 0` — the aggregating (flatten) slot. */
+    flatten: boolean;
+    /** A scalar slot: the only kind that can START an implicit lift (see the `_lc` table). */
+    liftTrigger: boolean;
+    /** The `AcceptError` marker: a bare error is delivered, not propagated. */
+    acceptError: boolean;
+    /**
+     * `IRange | Scalar` — the arm is picked per argument by its kind
+     * ({@link IFunction.ParameterTypeJSON.valueOrRange}): a value, a bare error or a one-cell
+     * reference takes the scalar path, a container the range path; never a lift.
+     */
+    valueOrRange: boolean;
+    /**
+     * The declared type is ADVISORY ({@link IFunction.ParameterTypeJSON.reportType}): where the
+     * engine cannot deliver it, the body receives the raw argument instead of the slot answering
+     * `#VALUE!`. Today that is the multi-area union; the body reads it through `getArgs`.
+     */
+    reportType: boolean;
+    /**
+     * `ReportType<NoLift<T>>` (either order): a multi-cell REFERENCE at this scalar slot neither
+     * lifts (`NoLift`) nor refuses (`ReportType`), it is handed to the body WHOLE, as one
+     * `IReferenceRange`; an array still lifts. Excel's `Boolean|Range` slot shape, no `Array` bit:
+     * LINEST/LOGEST `const`/`stats`, TREND/GROWTH `const` (DESIGN-LIFT-AND-DEMAND §1). One flag
+     * because the coercion loop and both lift walks ask the same question, and a slot carrying only
+     * one of the two markers changes nothing here.
+     */
+    wholeReference: boolean;
+    /** The effective policy and its `allowError` half — static per declaration. */
+    policy: 'reject' | 'accept' | null;
+    allowError: boolean;
+    /**
+     * The slot's enum, when the engine enforces it: every value delivered is a member, or the slot
+     * answers as a failed coercion does. `null` for a slot with no enum, and for `ReportType<E>`,
+     * where the enum is what the caller is told and the body owns the verdict.
+     */
+    enumGate: EnumGate | null;
+    /**
+     * The plain scalar slot the inline fast path in `_exec` serves: not rest, range, lambda or
+     * flatten, and a static policy. A primitive or a single-cell reference at such a slot is the
+     * bulk of every call on a formula-heavy sheet. An enum slot is not one, so the fast path pays
+     * nothing for the check.
+     */
+    simple: boolean;
+}
 interface RepeatPlan {
     /**
      * The parameter list the coercion loop runs against.
@@ -16,10 +93,12 @@ interface RepeatPlan {
      * branch consumes the tail exactly as `...p: T[]` always did. That is not an optimization: a
      * reference union in a range-typed slot contributes one entry PER AREA, so the coerced count is
      * argument count plus extra areas and no 1:1 expansion can describe it. Marshalling it as a
-     * single reference instead answers `#REF!` (PrimitiveUtils `isMultiAreaValue`), which is how
+     * single reference instead answers `#VALUE!` (PrimitiveUtils `isMultiAreaValue`), which is how
      * `SUMPRODUCT(A1:A3,(A1:A3,C1:C3))` briefly started failing.
      */
     params: IFunction.ParameterTypeJSON[];
+    /** {@link ParamSpec} per entry of `params`. */
+    specs: ParamSpec[];
     /** Number of parameters before the group. */
     prefix: number;
     /** Group period (the slot count). */
@@ -33,6 +112,14 @@ interface RepeatPlan {
     short: boolean;
     /** Period 1 hands the body `T[]`; period 2+ hands it tuples. */
     tuples: boolean;
+    /**
+     * Declared parameters SUPPLIED after the group, solved for alongside `n` rather than fixed — a
+     * trailing suffix may be optional (SWITCH's `default`).
+     *
+     * Only `getArgs()` reads it: the suffix parameters are pinned to the TAIL of the argument list,
+     * so this is what lets a body ask for its `default` without counting how many pairs preceded it.
+     */
+    suffix: number;
 }
 export declare class TypedFunction implements IFunction {
     protected _n: string;
@@ -52,6 +139,29 @@ export declare class TypedFunction implements IFunction {
     };
     protected _lc: boolean;
     protected _rlc: boolean;
+    /**
+     * Some parameter declares `NoLift<T>` — a multi-cell REFERENCE at that non-repeating scalar
+     * slot is `#VALUE!` rather than a broadcast, per parameter as Excel needs
+     * (`NETWORKDAYS.INTL` refuses a reference at its date slots and lifts at `weekend`,
+     * CALC-ISSUES 31; DESIGN-FUNCTION-ARGUMENTS §2.3, §6). A declaration bit and not a body
+     * concern, because the body never runs: without it the lift runs instead and answers one
+     * result per cell, so there is nothing for a body-facing API to express. Precomputed so the
+     * common call pays one boolean.
+     */
+    protected _nl: boolean;
+    /** Whether ANY parameter (or repeating slot) is `Lazy` — the guard on the wrapping below. */
+    protected _lz: boolean;
+    /**
+     * Some repeating slot declares `NoFilter<T>` — its members are coerced rather than filtered:
+     * numeric text parses, a blank inside a multi-cell range reads 0, and a boolean or non-numeric
+     * text member is `#VALUE!` for the whole call. The Analysis-ToolPak reading of a repeating
+     * slot, where `NoLift<T>` is the same heritage's reading of a non-repeating one. It is applied
+     * where the native filter lives — the rest branch of the coercion loop — and nowhere else.
+     *
+     * A function has at most one repeating group, so this precomputed boolean IS the slot's flag;
+     * the common call pays one boolean rather than a property read per argument.
+     */
+    protected _nmf: boolean;
     /**
      * The declared return scalar type, normalized (`'*'`/null → null).
      *
@@ -60,12 +170,45 @@ export declare class TypedFunction implements IFunction {
      * through the parameter's coercion.
      */
     protected _rs: ScalarType | null;
+    /**
+     * The reference half of the declared RETURN KIND pair (DESIGN-DECLARATION-SURFACE §3.1): may
+     * this call answer a REFERENCE? True for a declared `IReferenceRange` return (`r:'p'` —
+     * OFFSET/INDIRECT/XLOOKUP/TAKE/DROP) and for an UNTYPED return (`any` — the pass-through
+     * selectors IF/IFS/SWITCH/CHOOSE/INDEX, and any UDF that declares nothing). False for every
+     * provable value — a declared scalar (`'*'` included: IFERROR) or a ranged array producer.
+     *
+     * Read at the call exit (a value-declared function's reference result is demoted to its VALUE)
+     * and at the `*`-slot union pass-through.
+     */
+    protected _rref: boolean;
+    /**
+     * The declared result kind is a SCALAR member of {@link ValueKind} — `ROW(A1)` is the number 3
+     * (TYPE 1) where `TRANSPOSE({5})` stays a 1x1 array (TYPE 64). Precomputed from
+     * {@link deriveReturnKind} so the call exit pays one boolean. False when the kind is
+     * Reference/Array/Lambda or dynamic (`null` — `'*'`, untyped: the result's own kind rides on
+     * the value).
+     */
+    protected _rkScalar: boolean;
     protected _json: IFunction.DeclarationJSON;
     protected _pj: IFunction.ParameterTypeJSON[] | null | undefined;
+    /** {@link ParamSpec} per declared parameter — the per-call loop's view of `_pj`. */
+    protected _ps: ParamSpec[];
     /** Index of the repeating-group parameter, or `-1`. */
     protected _gi: number;
+    /**
+     * Index of the one parameter that consumes a VARIABLE number of arguments — a repeating group or
+     * a trailing rest — or `-1`.
+     *
+     * `getArgs()` indexes by PARAMETER (DESIGN-FUNCTION-ARGUMENTS §3.3) and this is the single place
+     * parameter numbering and argument numbering part company, so it is resolved once here rather
+     * than re-derived per call. `_gi` cannot serve: it covers `Repeating<T>` only, and a plain rest
+     * parameter is the same thing to a body asking which parameter its argument landed in.
+     */
+    protected _va: number;
     /** Resolved {@link RepeatPlan} per argument count (`null` = an arity the declaration refuses). */
     protected _gc: Map<number, RepeatPlan | null> | null;
+    /** The name's argument ceiling — {@link IFunction.IDeclaration.getMaxArguments}, cached. */
+    protected _mx: number;
     constructor(json: IFunction.DeclarationJSON, fn: (...args: any) => any, getContext: () => IFormulaContext | null | undefined, desc?: IFunction.DescriptorJSON | ((locale?: string) => Promise<IFunction.DescriptorJSON>) | null, builtIn?: boolean);
     /** @inheritdoc IFunction.execute */
     execute<R = any>(...args: any[]): R;
@@ -98,6 +241,15 @@ export declare class TypedFunction implements IFunction {
      * (`Repeating<IRange>` hands the body `IRange[]`, the same shape a rest parameter would).
      */
     protected _regroup(values: any[], length: number, plan: RepeatPlan): any[];
+    /**
+     * Gates what an enum slot just delivered — `coerced` from `from` on, which is one entry for a
+     * plain slot and one per member for a rest slot. A RANGE entry is a lift's autoboxed operand and
+     * is skipped: the lift walks gate it per element, which is where its members are coerced too.
+     *
+     * @returns the slot's fault, or `null`. A refusal is a failed coercion, so `AcceptError<E>`
+     * receives it as the `#VALUE!` it would have raised rather than the call answering it.
+     */
+    protected _gateDelivered(spec: ParamSpec, coerced: FixedPackedArray, from: number): FormulaError.Known | null;
     /**
      * The body of {@link execute} after argument-source resolution. Split out so the reference
      * lift (`_refLift`) can invoke the function once per element with a substituted argument list,
@@ -106,6 +258,30 @@ export declare class TypedFunction implements IFunction {
      * writes anything into it.
      */
     protected _exec<R = any>(argsEval: any[], argsLength: number): R;
+    /**
+     * `NoLift<T>`: is a multi-cell REFERENCE sitting at a non-repeating scalar parameter marked to
+     * refuse one? (DESIGN-FUNCTION-ARGUMENTS §2.3, §2.7 rule 3.)
+     *
+     * Three qualifications, each measured rather than assumed
+     * (`fn-battery/adhoc-container-at-slot{,2}`, Excel 16.0 build 20326):
+     *
+     * - **A REFERENCE, not an array.** `MROUND({3,4,5},5)` spills where `MROUND(A1:A3,5)` is
+     *   `#VALUE!`, so an array at the same slot still lifts. That is the whole reason this reads the
+     *   argument's shape rather than trusting the parameter: the engine hands a reference over as
+     *   COORDS and an array as an `IRange`.
+     * - **MULTI-CELL.** A 1×1 reference collapses to its member and is an ordinary argument
+     *   (`EFFECT(J1,4)` over a text cell is `0.0824…`).
+     * - **NON-REPEATING.** A repeating scalar slot ABSORBS a container as members whatever the
+     *   function's heritage — `GCD(C1:C3)` is 4, `MULTINOMIAL(A1:A3)` is 27720 — and those were the
+     *   rows that could have broken the rule and did not. Period-1 groups marshal through the rest
+     *   branch and are already excluded by `rest`; period 2+ expand to per-argument entries, so the
+     *   group's span is skipped explicitly.
+     *
+     * A multi-AREA union `(A1:A3,C1:C5)` arrives as an ARRAY of areas and is not treated as a
+     * reference here — unmeasured at these slots, and inventing a verdict for it would be the kind
+     * of unification §2.0 warns about.
+     */
+    protected _refusesReferenceLift(params: IFunction.ParameterTypeJSON[] | null | undefined, paramLength: number, argsEval: any[], argsLength: number, plan: RepeatPlan | null): boolean;
     /**
      * The consumer half of the lift (CALC-ISSUES item 22 change 2). Each `refLifts` entry is a
      * reference-only (r:'p') argument holding a producer lift's preserved per-element results.
@@ -119,7 +295,7 @@ export declare class TypedFunction implements IFunction {
      * special-cased: the per-element coercion answers exactly as it would for the unlifted call
      * (item 23b's `#PARSE!`), which becomes that member of the output.
      */
-    protected _refLift<R>(context: IFormulaContext, argsEval: any[], argsLength: number, refLifts: RefLiftEntry[]): R;
+    protected _refLift<R>(context: IFormulaContext, argsEval: any[], argsLength: number, refLifts: RefLiftEntry[], firstCell?: boolean): R;
     /**
      * @hidden
      * Vends a NEW instance whose evaluation context comes from `getContext` — the public-API
@@ -138,6 +314,8 @@ export declare class TypedFunction implements IFunction {
     getDescriptor(locale?: string): Promise<IFunction.IDescriptor>;
     /** @inheritdoc IFunction.isBuiltIn */
     isBuiltIn(): boolean;
+    /** @inheritdoc IFunction.isLambda */
+    isLambda(): boolean;
     /** @inheritdoc IFunction.getContext() */
     getContext(): string | null;
     get [Symbol.toStringTag](): string;
@@ -147,6 +325,24 @@ export declare class TypedFunction implements IFunction {
     /** @inheritdoc ITypedFunction.isITypedFunction */
     get isITypedFunction(): true;
 }
+export declare class Declaration implements IFunction.IDeclaration {
+    protected _n: string;
+    protected _p: readonly IFunction.IParameterType[];
+    protected _r: IFunction.IReturnType;
+    protected _mx: number;
+    protected _h: boolean;
+    constructor(json: IFunction.DeclarationJSON);
+    /** @inheritdoc IFunction.IDeclaration.getName */
+    getName(): string;
+    /** @inheritdoc IFunction.IDeclaration.getParameters */
+    getParameters(): readonly IFunction.IParameterType[];
+    /** @inheritdoc IFunction.IDeclaration.getMaxArguments */
+    getMaxArguments(): number;
+    /** @inheritdoc IFunction.IDeclaration.getReturnType */
+    getReturnType(): IFunction.IReturnType;
+    /** @inheritdoc IFunction.IDeclaration.isHidden */
+    isHidden(): boolean;
+}
 type LiftedFnResults = {
     elements: any[];
     rows: number;

package/types/src/scripting/_FunctionIndex.d.ts

@@ -23,8 +23,8 @@ export interface FunctionIndexEntry {
     category: string;
     /** {@link category}, UPPER-cased (category matching is case-insensitive). */
     categoryUpper: string;
-    /** Whether the descriptor marks this deprecated/hidden (the string form is a label, still truthy). */
-    deprecated: boolean;
+    /** {@link IFunction.IDeclaration.isHidden}, read once with the rest of the entry. */
+    hidden: boolean;
 }
 /** One search hit: the function, its relevance {@link scoreEntry} and the key results order by. */
 export interface FunctionMatch {
@@ -63,7 +63,7 @@ export declare const scoreEntry: (entry: FunctionIndexEntry, textUpper: string)
 /** Orders matches: best score first, then alphabetically by canonical name. */
 export declare const compareMatches: (a: FunctionMatch, b: FunctionMatch) => number;
 /**
- * Re-ranks an ALREADY-merged list (built-ins + each module's functions) by canonical name relevance.
+ * Re-ranks an ALREADY-merged list (each module's functions) by canonical name relevance.
  *
  * @remarks
  * Used where the merge crosses collections and no shared index exists. Name-only by design: it must
@@ -74,6 +74,11 @@ export declare const compareMatches: (a: FunctionMatch, b: FunctionMatch) => num
  * Sorts `functions` IN PLACE (and returns it) — callers pass the freshly merged array.
  */
 export declare const rankByName: (functions: IFunction[], textUpper: string) => IFunction[];
+/**
+ * The {@link FunctionIndexEntry} for `fn`, from its descriptor — `null` for a function whose descriptor
+ * failed to resolve, which still gets an entry (name only, `Uncategorized`).
+ */
+export declare const createIndexEntry: (fn: IFunction, descriptor: IFunction.IDescriptor | null) => FunctionIndexEntry;
 /**
  * The LAZY, per-language descriptor index behind {@link IFunctionCollection.search} and
  * {@link IFunctionCollection.getCategories}.

package/types/src/scripting/_ModuleUtils.d.ts

@@ -1,5 +1,15 @@
 import { Diagnostic } from '@sheetxl/scripting';
 import { IModule } from './IModule';
-export declare function jsonToModule(name: string, json: IModule.JSON, declarationsOnly?: boolean, diagnostics?: Diagnostic[]): Promise<IModule>;
+export declare function jsonToModule(name: string, json: IModule.JSON, declarationsOnly?: boolean, diagnostics?: Diagnostic[], scope?: IModule.Scope | (() => IModule.Scope)): Promise<IModule>;
+/**
+ * Build a module without loading any compiled body — no import, no execution, no `await`.
+ *
+ * @remarks
+ * The synchronous counterpart of {@link jsonToModule}, for owners that vend their modules from a
+ * plain accessor. It is complete for a module that has no runnable `compiled` output (imported VBA
+ * source is the case that matters); a module that *does* carry one is built as declarations only,
+ * so its functions are inspectable but inert.
+ */
+export declare function jsonToModuleSync(name: string, json: IModule.JSON, scope?: IModule.Scope | (() => IModule.Scope), diagnostics?: Diagnostic[]): IModule;
 export declare function runAsyncGenerator<T>(generator: AsyncGenerator<any, T, any>): Promise<T>;
 //# sourceMappingURL=_ModuleUtils.d.ts.map

package/types/src/scripting/_ScriptUtils.d.ts

@@ -1,4 +1,5 @@
 import { IRange, FormulaError, Observable, IFormulaContext } from '@sheetxl/primitives';
+import { RunGuard } from '@sheetxl/scripting';
 export declare const _ReuseGlobalContext: {
     FormulaContext: IFormulaContext | undefined;
     ScalarType: {
@@ -12,6 +13,8 @@ export declare const _ReuseGlobalContext: {
     IRange: typeof IRange;
     FormulaError: typeof FormulaError;
     Observable: typeof Observable;
+    /** The stop check a guarded compile inserts into loops and function bodies (`CompileOptions.runGuard`). */
+    checkRun: typeof RunGuard.check;
 };
 /**
  * Publishes the shared context on `globalThis` for bundled scripts.

package/types/src/scripting/declarations.browser.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Browser loaders for the script authoring surface (`scripting.d.ts`) and its signature index
+ * (`scripting-api.json`).
+ *
+ * Selected via the `@sheetxl/sdk/scripting/declarations` conditional export (the `browser`/`default`
+ * condition). Keeping this browser-only keeps node builtins out of browser bundles entirely.
+ */
+export declare function loadScriptingDeclarations(): Promise<string>;
+export declare function loadScriptingApi(): Promise<string>;
+//# sourceMappingURL=declarations.browser.d.ts.map