@sheetxl/sdk 0.8.0-beta.1 → 0.8.0-beta.3

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

@@ -62,6 +62,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). */
@@ -61,21 +140,26 @@ export declare class TypedFunction implements IFunction {
     protected _lc: boolean;
     protected _rlc: boolean;
     /**
-     * `@compat noReferenceLift` — a multi-cell REFERENCE at a non-repeating scalar parameter is
-     * `#VALUE!` rather than a broadcast (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.
+     * 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 _nrl: boolean;
+    protected _nl: boolean;
+    /** Whether ANY parameter (or repeating slot) is `Lazy` — the guard on the wrapping below. */
+    protected _lz: boolean;
     /**
-     * `@compat noMemberFilter` — members of a REPEATING scalar parameter 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 (DESIGN-FUNCTION-ARGUMENTS §2.8, §6).
-     *
-     * The other half of the ATP heritage `_nrl` carries; `@compat atp` turns on both. It is applied
+     * 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;
     /**
@@ -86,8 +170,29 @@ 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;
     /**
@@ -102,6 +207,8 @@ export declare class TypedFunction implements IFunction {
     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;
@@ -134,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,
@@ -143,8 +259,8 @@ export declare class TypedFunction implements IFunction {
      */
     protected _exec<R = any>(argsEval: any[], argsLength: number): R;
     /**
-     * `@compat noReferenceLift`: is a multi-cell REFERENCE sitting at a non-repeating scalar
-     * parameter? (DESIGN-FUNCTION-ARGUMENTS §2.3, §2.7 rule 3.)
+     * `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):
@@ -179,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
@@ -198,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;
@@ -207,6 +325,21 @@ 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;
+    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;
+}
 type LiftedFnResults = {
     elements: any[];
     rows: number;

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

@@ -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

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

@@ -0,0 +1,49 @@
+export declare function getScriptingDeclarations(): Promise<string>;
+/**
+ * The signature index of the script authoring surface — the shipped `scripting-api.json`.
+ *
+ * @remarks
+ * `scripting.d.ts` carries every declaration with its full documentation, which is what an editor
+ * wants. This is the same surface as a lookup table: one entry per declared name, one line per
+ * member, each with where its full declaration sits in `scripting.d.ts`. Both files are written by
+ * one build step from one text, so a name listed here is a name a script type-checks against.
+ */
+export declare namespace ScriptingApi {
+    /** One callable or readable member of a declaration. */
+    interface Member {
+        /** The member's name; `new`, `(call)` and `[index]` for the unnamed signature forms. */
+        readonly name: string;
+        /** The declaration on one line, without its documentation. */
+        readonly signature: string;
+        /** The first sentence of the member's documentation. */
+        readonly summary?: string;
+        readonly deprecated?: true;
+        /** 1-based, inclusive line span in `scripting.d.ts`, documentation included. */
+        readonly lines: readonly [start: number, end: number];
+    }
+    /** One declared name. */
+    interface Entry {
+        readonly kind: 'interface' | 'class' | 'enum' | 'type' | 'const' | 'function' | 'namespace';
+        /** The first sentence of the declaration's documentation. */
+        readonly summary?: string;
+        readonly deprecated?: true;
+        /** The type parameter list as written, e.g. `<T = any>`. */
+        readonly typeParams?: string;
+        /** The types this one extends, as written. Their members are reachable on this type too. */
+        readonly extends?: readonly string[];
+        /** The declaration on one line — present when there is no member list to show instead. */
+        readonly signature?: string;
+        readonly members?: readonly Member[];
+        /** Names declared in the namespace merged with this one; each is indexed as `<this>.<name>`. */
+        readonly nested?: readonly string[];
+        /** 1-based, inclusive line span in `scripting.d.ts`, documentation included. */
+        readonly lines: readonly [start: number, end: number];
+    }
+    interface Index {
+        readonly version: 1;
+        /** Keyed by the dotted path below `SheetXL` — `ICellRange`, `ICellRange.Coords`. */
+        readonly types: Readonly<Record<string, Entry>>;
+    }
+}
+export declare function getScriptingApi(): Promise<ScriptingApi.Index>;
+//# sourceMappingURL=declarations.d.ts.map

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

@@ -0,0 +1,9 @@
+/**
+ * Node 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 `node` condition).
+ */
+export declare function loadScriptingDeclarations(): Promise<string>;
+export declare function loadScriptingApi(): Promise<string>;
+//# sourceMappingURL=declarations.node.d.ts.map

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

@@ -1,4 +1,7 @@
 export * from './IScript';
 export * from './IModule';
+export * from './IModuleCollection';
 export * from './IFunctionCollection';
+export * from './declarations';
+export { getScriptRuntime, withScriptRuntime } from './Runtime';
 //# sourceMappingURL=index.d.ts.map

package/types/src/selection/IRangeSelection.d.ts

@@ -23,11 +23,14 @@ export interface IRangeSelection {
      * @param axis The axis to traverse. Default is `ICellRange.Axis.Row`.
      * @param reverse Whether to traverse in reverse. Default is false.
      * @param region An optional bounding region to *wrap within* when there is no explicit selection (a
-     *   bare cursor) — e.g. a table's data range, so Tab/Enter cycle inside it instead of walking off its
-     *   edge. Resolving this region is the caller's job (the view's `getRegionBounds`); omit it (the bare
-     *   sheet) and a bare-cursor traverse is a plain move.
+     *   bare cursor), so the move cycles inside it instead of walking off its edge. Omit it and a
+     *   bare-cursor traverse is a plain move.
      *
-     * @remarks Useful for pressing tab or enter from the UI.
+     * @remarks
+     * Useful for pressing tab or enter from the UI.
+     *
+     * A bare cursor in a table wraps a row traverse (Tab) within the table's data range without being
+     * given a region; a column traverse (Enter) moves on out of the table.
      */
     traverse(axis?: IRange.Axis, reverse?: boolean, region?: IRange.Coords): this;
     /**
@@ -177,6 +180,8 @@ export interface IRangeSelection {
      * @returns A function to remove the listeners.
      */
     addListeners(listeners: IRangeSelection.IListeners, options?: IListener.Options): IListener.Remove;
+    /** For runtime type checking. */
+    readonly isIRangeSelection: true;
 }
 /**
  * {@inheritDoc IRangeSelection}

package/types/src/selection/RangeSelection.d.ts

@@ -135,6 +135,8 @@ export declare class RangeSelection {
     protected _scrollCellCoordsIntoView(coords: Partial<IRange.Coords>, options?: globalThis.ScrollIntoViewOptions | boolean): Promise<boolean>;
     get [Symbol.toStringTag](): string;
     toString(): string;
+    /** {@inheritDoc IRangeSelection.isIRangeSelection} */
+    get isIRangeSelection(): true;
 }
 interface _ReadCache {
     range: ICellRange | null;

package/types/src/shape/IShape.d.ts

@@ -5,13 +5,17 @@ import { IModel } from '../model';
 import { IHyperlink } from '../hyperlink';
 import { IFill } from '../fill';
 import { IStroke } from '../fill/IStroke';
+import { ITextFrame } from '../text/ITextFrame';
 /**
- * Interface for working with IShape.
+ * A drawn shape: a text box, a callout, a rectangle, a connector, or a group of them.
  *
  * @remarks
+ * A shape is the content of an {@link IMovable} — `movable.getContent<IShape>()` for a movable
+ * whose content type is `'shape'`. The movable carries the position; the shape carries what is
+ * drawn there and what is written on it.
  *
- * A shape does not position information
- * **PLACEHOLDER**
+ * Reading only: a shape's preset and its text. An imported shape is otherwise kept as the source
+ * wrote it and saved back unchanged.
  */
 export interface IShape extends IModel {
     toJSON(toResourceId?: (resource: IResource) => number | null): IShape.JSON | null;
@@ -23,6 +27,37 @@ export interface IShape extends IModel {
      * Returns the description of the shape.
      */
     getDescription(): string;
+    /**
+     * Returns the kind of shape this is: its preset geometry.
+     *
+     * @remarks
+     * A DrawingML preset id — `rect`, `borderCallout2`, `curvedConnector3` — or `'custom'` for a
+     * shape drawn from its own path, or `'group'` for a group of shapes.
+     *
+     * The preset says what a shape is for where its name does not: a callout annotates something,
+     * a connector links two shapes, and a rectangle with no text is usually a box drawn around the
+     * cells under it.
+     */
+    getShapeType(): string;
+    /**
+     * Returns the text written on the shape.
+     *
+     * @remarks
+     * Text on a shape is a note from the workbook's author to its reader, so it is worth reading
+     * before the cells it sits beside. A group answers with the text of its members, in z-order.
+     *
+     * @returns `null` when the shape has no text body at all, as a connector does not. A shape that
+     * can hold text but has none answers with a frame whose text is `''`.
+     *
+     * @example
+     * ```ts
+     * for (const movable of sheet.getMovables().getItems({ type: 'shape' })) {
+     *   const text = movable.getContent<IShape>().getTextFrame()?.getText();
+     *   if (text) console.log(movable.getRange().toString(), text);
+     * }
+     * ```
+     */
+    getTextFrame(): ITextFrame.IText | null;
 }
 /**
  * {@inheritDoc IShape}
@@ -75,6 +110,9 @@ export declare namespace IShape {
         /** Opaque source XML fragment, captured verbatim from the source file and replayed as-is on
          * save, for whatever this shape doesn't (yet) model structurally. */
         xml?: string;
+        /** The `mc:Fallback` rendition of `xml`, captured verbatim, when the source offered the shape as an
+         * `mc:AlternateContent`. An equation's fallback is where its linear text form is. */
+        fallbackXml?: string;
         /** Original `cNvPr` id from the captured source fragment, if any; used to avoid id collisions
          * with freshly-generated ids on write. */
         sourceId?: number;