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

package/types/src/io/WorkbookOrigin.d.ts

@@ -17,6 +17,10 @@ export interface WorkbookOriginOptions {
      * The last-known size of the source in bytes (stat-style), if known.
      */
     size?: number | null;
+    /**
+     * When the source was last modified, in milliseconds since the epoch (stat-style), if known.
+     */
+    lastModified?: number | null;
     /**
      * Whether the source can be written back to (a silent re-save).
      *
@@ -34,19 +38,20 @@ export interface WorkbookOriginOptions {
  * concrete "light virtual file handle" (see `IO-DESIGN.md`).
  *
  * @remarks
- * Mutable and observable: the IO/store layer holds the instance and calls {@link update} when the
- * source moves (a save that resolved a destination) or is renamed, firing `onChange` so holders —
- * including the workbook itself, whose `getName()`/`onNameChange` derive from this — propagate it.
+ * Names one file for its whole life. What is known about that file — its size, its encryption, its
+ * display label — can change in place ({@link update}, {@link setName}), firing `onChange` so
+ * holders — including the workbook, whose `getName()`/`onNameChange` derive from this — follow.
  * Source logic (paths, URLs, formats) lives here, in the IO layer, not in the workbook model.
  *
  * An **unbound** origin (`path: null`) belongs to an in-memory workbook with no destination yet; a
- * destination-resolving save fills it in place via {@link update}.
+ * save that resolves one moves the workbook to a new origin, leaving this one as it was.
  */
 export declare class WorkbookOrigin implements IWorkbookIO.Origin {
-    private _path;
+    private readonly _path;
     private _name;
     private _format;
     private _size;
+    private _lastModified;
     private _canWrite;
     private _encryption;
     /**
@@ -85,24 +90,28 @@ export declare class WorkbookOrigin implements IWorkbookIO.Origin {
     getPassword(): string | null;
     /** {@inheritDoc IWorkbookIO.Origin.getSize} */
     getSize(): number | null;
+    /** {@inheritDoc IWorkbookIO.Origin.getLastModified} */
+    getLastModified(): number | null;
     /** {@inheritDoc IWorkbookIO.Origin.canWrite} */
     canWrite(): boolean;
     /** {@inheritDoc IWorkbookIO.Origin.setName} */
     setName(name: string | null): void;
     /**
-     * Update one or more fields in place. Fires `onChange` if anything actually changed.
+     * Update what is known about the file in place. Fires `onChange` if anything actually changed.
      *
      * @remarks
-     * This is the **privileged mutation channel** (see `IO-DESIGN.md`): permitted callers are the
-     * backing store (rename/move, destination resolution), the IO layer (filling an unbound origin on
-     * a first destination-resolving save), and the document layer (Save As / rename). Never format
-     * handlers, never the model, never chrome.
+     * The **privileged mutation channel** (see `DESIGN-IO.md`) for the backing store and the IO layer:
+     * the written size, the encryption on disk, the format key a read resolved. Never format handlers,
+     * never the model, never chrome.
+     *
+     * There is no `path`: an origin names one file for its whole life. A save that resolves another
+     * destination mints a new origin for it (see `DESIGN-IO.md` §11).
      */
     update(next: {
-        path?: string | null;
         name?: string | null;
         format?: string | null;
         size?: number | null;
+        lastModified?: number | null;
         canWrite?: boolean;
         encryption?: string | null;
     }): this;

package/types/src/io/WorkbookOriginProvider.d.ts

@@ -0,0 +1,46 @@
+import { IListener } from '../listener';
+import { IWorkbookIO } from './IWorkbookIO';
+/**
+ * The provider currently supplying `origin`, or `null` when no open workbook lives in it.
+ *
+ * @remarks
+ * How the IO layer finds the workbook a save was for: it holds the origin it wrote from.
+ */
+export declare const getOriginProvider: (origin: IWorkbookIO.Origin) => WorkbookOriginProvider | null;
+/** The origins of every open workbook. */
+export declare const getOpenOrigins: () => IWorkbookIO.Origin[];
+/**
+ * Default {@link IWorkbookIO.OriginProvider}: holds the workbook's current origin and moves when
+ * told to.
+ *
+ * @remarks
+ * {@link setOrigin} is on this class, not the interface — the workbook only reads its origin. The
+ * IO layer moves it after a save that resolved a new destination.
+ *
+ * An origin is supplied by one provider at a time, so the origin a save wrote from identifies
+ * exactly one workbook. Supplying an origin another open provider already supplies throws.
+ */
+export declare class WorkbookOriginProvider implements IWorkbookIO.OriginProvider {
+    private _origin;
+    private _released;
+    private readonly _emitter;
+    constructor(origin: IWorkbookIO.Origin);
+    /** {@inheritDoc IWorkbookIO.OriginProvider.getOrigin} */
+    getOrigin(): IWorkbookIO.Origin;
+    /**
+     * Supplies `origin` from now on. Fires `onOriginChange` unless it is already the current one.
+     *
+     * @remarks
+     * Moves the workbook to another file; it writes nothing. The origin it replaces is left as it was
+     * — it still names its own file, and is free for another workbook.
+     */
+    setOrigin(origin: IWorkbookIO.Origin): void;
+    /**
+     * Stops supplying: the origin is free for another workbook. Called when the workbook closes.
+     */
+    release(): void;
+    /** {@inheritDoc IListener.ISource.addListeners} */
+    addListeners(listeners: IWorkbookIO.OriginProvider.IListeners, options?: IListener.Options): IListener.Remove;
+    private static _assertFree;
+}
+//# sourceMappingURL=WorkbookOriginProvider.d.ts.map

package/types/src/io/_XmlFragment.d.ts

@@ -0,0 +1,49 @@
+/**
+ * A reader over a captured markup fragment.
+ *
+ * @remarks
+ * Content the model does not hold structurally is kept as the source's markup and replayed on save
+ * (a shape, a chart part). This reads the few facts such markup can answer without a model behind
+ * it. It is a reader over a fragment, not an XML library: elements, attributes and character data,
+ * matched by LOCAL name — prefixes are the producer's choice (`xdr:sp`, `a:t` and `c:ser` are only
+ * Excel's). The markup was already parsed once, as part of a whole document, by the reader that
+ * captured it.
+ */
+/** One element of a parsed fragment. `name` is the local name. */
+export interface XmlElement {
+    name: string;
+    attrs: string;
+    children: (XmlElement | string)[];
+    /** Where the element's content starts in the source: just past its open tag. */
+    contentStart: number;
+    /** Where the element's content ends in the source: at its close tag. Equal to `contentStart` for an empty element. */
+    contentEnd: number;
+}
+export declare const decodeEntities: (text: string) => string;
+/** Character data as it has to be spelled inside an element. */
+export declare const encodeText: (text: string) => string;
+/** The fragment's root element, or `null` when there is none to read. */
+export declare const parseFragment: (xml: string) => XmlElement | null;
+export declare const getAttribute: (element: XmlElement, name: string) => string | null;
+export declare const childElements: (element: XmlElement) => XmlElement[];
+export declare const findChild: (element: XmlElement, name: string) => XmlElement | null;
+/** The element at the end of a path of local names, or `null` where the path breaks. */
+export declare const findPath: (element: XmlElement, ...names: string[]) => XmlElement | null;
+/** The element's own character data; what its child elements hold is not read. */
+export declare const readCharacters: (element: XmlElement) => string;
+/**
+ * The children to read in place of an `mc:AlternateContent`: ONE branch, never both.
+ *
+ * @remarks
+ * A producer states the same content once per consumer version, so a sweep over both branches
+ * reads every word twice. The fallback is the rendition for a reader that does not understand the
+ * choice's markup — which, for the markup that gets wrapped this way (an OMML equation), is this
+ * reader: the fallback carries the equation in its linear text form.
+ */
+export declare const alternateBranch: (element: XmlElement) => XmlElement[];
+/**
+ * The plain text of a DrawingML text body (`txBody`, `c:rich`): its paragraphs joined by a newline,
+ * blank ones trimmed from the ends.
+ */
+export declare const readTextBody: (body: XmlElement) => string;
+//# sourceMappingURL=_XmlFragment.d.ts.map

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

@@ -1,3 +1,4 @@
+export * from './IEmbeddedPart';
 export * from './IWorkbookIO';
 export * from './WorkbookIO';
 export * from './WorkbookOrigin';

package/types/src/license/LicenseDetails.d.ts

@@ -4,6 +4,7 @@
 export interface LicenseDetails {
     getLicensee(): string | null;
     getExpiration(): Date | null;
+    getRuntimes(): ('browser' | 'server')[];
     getDomains(): string[];
     getCpuCount(): number;
     getMemory(): number;

package/types/src/license/LicenseManager.d.ts

@@ -4,7 +4,10 @@ declare class LM {
     /**
      * Set the license key provided by SheetXL.
      * @remarks
-     * The license key can also be provided via a file named `sheetxl.lic` in the root of the web server.
+     * Without a call to this, the key is looked for where it runs:
+     * - In a browser, a file named `sheetxl.lic` served beside the page.
+     * - Outside a browser (Node, Bun, Deno, CI), the `SHEETXL_LICENSE_KEY` environment variable, then
+     *   the key saved by `sheetxl license activate`.
      *
      * @param licenseKey The license key as a string.
      * @param force If set to `true` will replace an existing key.
@@ -21,6 +24,27 @@ declare class LM {
      * Return the current license details.
      */
     getDetails(): Promise<LicenseDetails>;
+    /**
+     * Return the current license details, after confirming this runtime may run under them.
+     *
+     * @remarks
+     * {@link getDetails} only reports. This also enforces: in a browser it always resolves, because
+     * an unlicensed page runs with the evaluation watermark. Outside a browser an evaluation runs
+     * for a limited period from the build's date; past it a valid license key is required, and this
+     * rejects with the reason and what to do. The engine calls it when it starts, so a host that
+     * wants to fail at startup instead of at the first workbook calls it itself.
+     */
+    assertUsable(): Promise<LicenseDetails>;
+    /**
+     * Return the license key in use, or `null` for an evaluation.
+     *
+     * @remarks
+     * The key set by {@link setLicenseKey}, else the one found where it runs: in a browser, the
+     * `sheetxl.lic` served beside the page; outside a browser, the `SHEETXL_LICENSE_KEY` environment
+     * variable, then the key saved by `sheetxl license activate`. The key is returned as found; use
+     * {@link getDetails} to learn whether it is valid here.
+     */
+    getLicenseKey(): Promise<string | null>;
     /**
      * Print just the banner
      */

package/types/src/license/Types.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Two-tier node fingerprint.
+ * - `stable`: hash of fields unlikely to change (arch, osType, platform, memoryGB).
+ *   Used for hard enforcement.
+ * - `full`: hash that also includes hostname.
+ *   Passes silently if stable matches but full diverges (hostname rename, container re-creation).
+ */
+export interface NodeFingerprint {
+    stable: string;
+    full: string;
+}
+export interface HostDetails {
+    cpus?: number;
+    memoryGB?: number;
+    protocol?: string | null;
+    domain?: string | null;
+    fingerprint?: NodeFingerprint;
+}
+/**
+ * What looking for a license key found, read where the runtime keeps it.
+ * - `found`: a key, and where it came from.
+ * - `absent`: the lookup completed and there is no key (`from` names where it looked).
+ * - `unreachable`: the lookup could not complete (offline, a server error); whether a key exists is
+ *   unknown, so this is never treated as an evaluation.
+ */
+export type LicenseKeySource = {
+    status: 'found';
+    key: string;
+    from: string;
+} | {
+    status: 'absent';
+    from: string;
+} | {
+    status: 'unreachable';
+    from: string;
+    reason: string;
+};
+//# sourceMappingURL=Types.d.ts.map

package/types/src/license/_Utils.d.ts

@@ -0,0 +1,39 @@
+/**
+ * A placeholder license key: the "evaluation" spellings a caller may pass to
+ * `LicenseManager.setLicenseKey` to run unlicensed on purpose (`eval`, `trial`, or the
+ * `visit …`/`email …` pointer text a starter template ships with). These select an evaluation
+ * license; they are never keys, so the persistent key store ignores them.
+ */
+export declare function isPlaceholderLicenseKey(key: string | null | undefined): boolean;
+export declare function getBuildVersion(): string;
+/** When this build was made, as an ISO 8601 instant, or `''` when unstamped. */
+export declare function getBuildDate(): string;
+/**
+ * How long a build runs as an evaluation, in days from its build date.
+ *
+ * @remarks
+ * Every release restamps the date, so a current install never reaches the end of the window;
+ * only one that is never updated does. Ninety days gives a pinned install (CI, a locked
+ * lockfile) a quarter before it has to move, and bounds how long any one build can run unlicensed.
+ */
+export declare const EVAL_PERIOD_DAYS = 90;
+/** When this build's evaluation period ends, or `null` for an unstamped (workspace, test) build. */
+export declare function getEvalPeriodEnd(): Date | null;
+/** Whether this build's evaluation period is over. An unstamped build never expires. */
+export declare function isEvalPeriodExpired(): boolean;
+/**
+ * The exception an expired evaluation carries. It names the date and the two ways out, because
+ * every surface that lists exceptions (the banner, `sheetxl info`, the MCP handshake) shows it
+ * verbatim and none of them knows more than the text.
+ */
+export declare function evalPeriodExpiredMessage(): string;
+/**
+ * The build as a person reads it: the stamped version, or `local` plus the local build time.
+ *
+ * @remarks
+ * A stamped version already names its commit, so the time adds nothing to it. A workspace build
+ * has no identity except when it was built, and to the minute, because several rebuilds a day
+ * all look alike at date resolution.
+ */
+export declare function getBuildLabel(): string;
+//# sourceMappingURL=_Utils.d.ts.map

package/types/src/license/details.d.ts

@@ -0,0 +1,24 @@
+import { LicenseDetails } from './LicenseDetails';
+import { HostDetails } from './Types';
+export interface UnlicensedOptions {
+    /** The license type: `eval`, `invalid`, `unavailable`. */
+    type: string;
+    /** Where the (missing or unusable) key was looked for. */
+    keyFrom: string;
+    exceptions: readonly string[];
+    /** Whether the product runs without the watermark anyway (an evaluation on localhost). */
+    validFor: boolean;
+    isEval?: boolean;
+    licensee?: string | null;
+    developerCount?: number;
+}
+/**
+ * A license that is not a valid key: an evaluation, a key that is not a key, a key that could not
+ * be loaded. Each runtime decides which one it is running and on what terms.
+ */
+export declare const genUnlicensedDetails: (options: UnlicensedOptions) => LicenseDetails;
+/**
+ * The license a key grants on `host`. A key that does not decode is an `invalid` license.
+ */
+export declare const detailsForKey: (from: string, key: string, host: HostDetails, isDevEnv: boolean) => LicenseDetails;
+//# sourceMappingURL=details.d.ts.map

package/types/src/license/license-key.d.ts

@@ -1,25 +1,46 @@
 import { LicenseDetails } from './LicenseDetails';
+/**
+ * Where a license runs. `browser` is any page (checked against its origin); `server` is any
+ * JavaScript runtime outside a browser - Node, Bun, Deno, the CLI, a CI runner (checked against the
+ * machine).
+ */
+export type LicenseRuntime = 'browser' | 'server';
+export declare const LICENSE_RUNTIMES: readonly LicenseRuntime[];
 export interface Decoded {
     licensee?: string | null;
     type?: string;
     expiry?: number;
     developerCount?: number;
+    /** The runtimes the key covers; `undefined` for a key issued before runtimes were explicit. */
+    runtimes?: LicenseRuntime[];
     domains?: string[];
     fingerprint?: string | null;
     cpuCount?: number;
     memory?: number | null;
     features?: Record<string, any>[];
 }
+/**
+ * The runtimes a decoded key covers. A key issued before runtimes were explicit covers `browser`
+ * when it has origins, and `server` unless its cpu and memory are both 0 (the old browser-only
+ * marker).
+ */
+export declare function getRuntimes(decoded: Decoded): LicenseRuntime[];
 export interface LicenseAndKey {
     details: LicenseDetails;
     key: string;
 }
 export interface LicenseKeyDetails {
     licensee: string;
-    type?: string;
+    type?: string | null;
     expiration?: string | null;
     developerCount?: number;
-    domains?: string | string[];
+    /**
+     * The runtimes the key covers. Defaults to what the other terms imply: `browser` when there are
+     * origins, `server` when there is a fingerprint, cpu count or memory.
+     */
+    runtimes?: LicenseRuntime[] | null;
+    /** Licensed origins, `<protocol>://<host>` each (see `Origin`); a string is comma-separated. */
+    domains?: string | string[] | null;
     fingerprint?: string | null;
     cpuCount?: number | null;
     memory?: number | null;
@@ -29,5 +50,31 @@ export declare function rot(text: string, key: number, n?: number): string;
 export declare function deobs(str: string): Decoded;
 export declare function encodeLicenseKey(keyDetails: LicenseKeyDetails): LicenseAndKey;
 export declare function validateDomain(domain: string, allowDomain?: boolean): boolean;
+/**
+ * A licensed origin, `<protocol>://<host>`.
+ *
+ * The protocol is the scheme the page is served over — `https` on the web, `vscode-webview` in VS Code
+ * desktop, an app's own registered scheme in Electron — and is mandatory: a browser license names
+ * the runtime it was sold for, not just a hostname. The host is a domain (matched exactly or as a
+ * suffix — `acme.com` covers `app.acme.com`), `*` for any host (runtimes whose host is random, like
+ * VS Code's `v--<hash>`), or empty for schemes that carry no host (`file://`).
+ */
+export interface Origin {
+    protocol: string;
+    host: string;
+}
+/** Splits `<protocol>://<host>`; `null` when the entry has no protocol or a malformed one. */
+export declare function parseOrigin(entry: string): Origin | null;
+/**
+ * `true` when `entry` is a well-formed origin. Web hosts (`http`/`https`) must be a subdomain, or an
+ * apex when the license carries the `domain` feature (`allowDomain`) — the same rule `validateDomain`
+ * applies; any other scheme accepts a DNS-shaped host, `*`, or none.
+ */
+export declare function validateOrigin(entry: string, allowDomain?: boolean): boolean;
+/**
+ * `true` when the running page — `protocol` without its colon and `hostname`, as `location` reports
+ * them — is covered by `entry`. An entry with no protocol covers nothing.
+ */
+export declare function originMatches(entry: string, protocol: string, hostname: string): boolean;
 export declare function validateFingerprint(fingerprint: string | null): boolean;
 //# sourceMappingURL=license-key.d.ts.map

package/types/src/license/runtime.browser.d.ts

@@ -0,0 +1,46 @@
+import { HostDetails, LicenseKeySource } from './Types';
+import { LicenseDetails } from './LicenseDetails';
+/**
+ * What the license check sees of the page: the scheme it is served over (no colon) and its hostname.
+ * `domain` is `null` for the one dev case — loopback over http(s). The scheme is part of that test on
+ * purpose: `tauri://localhost` / `capacitor://localhost` are shipped apps that happen to use a loopback
+ * host, and are checked like production. Outside a window (a worker, node under test) both are `null`.
+ */
+export declare function getHostDetails(): Promise<HostDetails>;
+/**
+ * Only the loopback host over http(s) is a dev environment. A dev *build* served on any other host
+ * (a LAN IP, a tunnel) — or under any other scheme — is checked exactly like production: license
+ * origins apply and an evaluation shows the watermark.
+ */
+export declare function isDevEnv(): Promise<boolean>;
+/**
+ * The key in the nearest `sheetxl.lic` served at or above the page. When the server cannot be
+ * reached, the key last read from any of those locations; with none cached, `unreachable`.
+ */
+export declare function readLicenseKey(): Promise<LicenseKeySource>;
+/**
+ * A page always runs: an unlicensed one runs with the evaluation watermark, which is the browser's
+ * enforcement. Never throws.
+ */
+export declare function assertUsable(_details: LicenseDetails): void;
+/**
+ * An evaluation: unrestricted on localhost, and with the evaluation watermark anywhere else.
+ */
+export declare function getEvalLicense(keyFrom: string): Promise<LicenseDetails>;
+/**
+ * The license for this page when the host set no key: the key file's, an evaluation when there is
+ * none, or `unavailable` when it could not be loaded.
+ */
+export declare function getLicense(): Promise<LicenseDetails>;
+export declare function setKey(key: string, force?: boolean): Promise<void>;
+export declare function getKey(): Promise<string>;
+export declare function printBanner(isUser: boolean): Promise<void>;
+/**
+ * The browser always gets the full banner — there is no piped output to protect, and
+ * the console collapses repeats. (See the node variant for the throttled CLI behavior.)
+ */
+export declare function claimFullLicensePrint(): Promise<boolean>;
+/** The one-line form of the unlicensed notice; in the browser only the activation pointer. */
+export declare function printLicenseNotice(): Promise<void>;
+export declare function printDetails(details: LicenseDetails, isUser?: boolean, expanded?: boolean, ignoreExceptions?: boolean): Promise<void>;
+//# sourceMappingURL=runtime.browser.d.ts.map

package/types/src/{lib/utils/utils.node.d.ts → license/runtime.node.d.ts}

@@ -1,20 +1,27 @@
-import { HostDetails } from './_Utils';
-import { LicenseDetails } from '../../license';
+import { HostDetails, LicenseKeySource } from './Types';
+import { LicenseDetails } from './LicenseDetails';
 export declare function getHostDetails(): Promise<HostDetails>;
 export declare function isDevEnv(): Promise<boolean>;
+export declare function readLicenseKey(): Promise<LicenseKeySource>;
 /**
- * The runtime location - the current working directory in node.
+ * An evaluation: runs with the unlicensed notice.
  */
-export declare function getLocation(): string;
+export declare function getEvalLicense(keyFrom: string): Promise<LicenseDetails>;
 /**
- * The OS platform, used by the `INFO("system")` formula. `process.platform` is available
- * synchronously without importing `os`.
+ * The license for this process when the host set no key: the environment's or the stored key's,
+ * or an evaluation.
  */
-export declare function getOS(): string;
-export declare function findLicenseKey(): Promise<{
-    key: string;
-    from: string;
-} | null>;
+export declare function getLicense(): Promise<LicenseDetails>;
+/**
+ * Whether this process may run under `details`; throws with the reason when it may not.
+ *
+ * @remarks
+ * Outside a browser there is no watermark to fall back on, so the evaluation period is the
+ * enforcement: once it is over, only a current license key that covers a server runs. A key's
+ * capacity exceptions (an oversize host) are still reported rather than enforced, exactly as before
+ * the period ended. An unstamped build has no period and always runs.
+ */
+export declare function assertUsable(details: LicenseDetails): void;
 export declare function setKey(key: string, force?: boolean): Promise<void>;
 export declare function getKey(): Promise<string | undefined>;
 export declare function printBanner(isUser: boolean): Promise<void>;
@@ -39,4 +46,4 @@ export declare function claimFullLicensePrint(): Promise<boolean>;
  */
 export declare function printLicenseNotice(): Promise<void>;
 export declare function printDetails(details: LicenseDetails, isUser?: boolean, expanded?: boolean, ignoreExceptions?: boolean): Promise<void>;
-//# sourceMappingURL=utils.node.d.ts.map
+//# sourceMappingURL=runtime.node.d.ts.map

package/types/src/listener/IListener.d.ts

@@ -25,19 +25,36 @@ export declare namespace IListener {
          */
         once?: boolean;
         /**
-         * Determines if the listeners is part of the transaction.
+         * Whether the listener takes part in the operation that notifies it.
          *
-         * @defaultValue If the listener is added during a transaction this will be true.
+         * @defaultValue `true` when the listener is added through the object a batch hands its
+         * callback ({@link IWorkbook.doBatch}, {@link IWorksheet.doBatch}, {@link ICellRange.doBatch}),
+         * and `false` otherwise - however long a batch stays open.
          *
          * @remarks
-         * There are subtle differences between a transactional listener and a non-transactional listener.
+         * A script, or code acting for one, adds its listeners through its batch and takes part by
+         * default. A view, or anything else watching the document, adds them the ordinary way and is
+         * an observer by default. Neither needs to set this.
+         *
+         * A participant hears what is announced while an operation is under way. A worksheet announces
+         * each write as it is made ({@link IWorksheet.Events.onDataChange}, `onStyleChange`,
+         * `onMergesChange`, `onSpillsChange`), so a participant hears each write and an observer hears
+         * the operation once, every write merged. An event that is announced only once the operation
+         * has landed never reaches a participant; to hear one from a batch, add the listener with
+         * `transactional: false`.
          *
          * A transactional listener:
-         * * Will not be fire during undo/redo.
-         * * Will be reverted to it's original add/remove state during an undo/redo.
+         * * is told inline, inside the operation, so anything it writes joins that same commit, and
+         *   is told during an undo or a redo for the same reason;
+         * * hears nothing announced outside an operation;
+         * * is part of the document: the operation that added it removes it on undo and puts it back
+         *   on redo.
          *
          * A non-transactional listener:
-          * Will not be fire on any change.
+         * * is told once per operation, after it has landed, however many times the operation
+         *   notified, and not at all if the operation is rolled back;
+         * * is told at once when there is no operation, and at once during an undo or a redo;
+         * * survives an undo, since it is not part of the document.
          */
         transactional?: boolean;
     }

package/types/src/listener/ListenerEmitter.d.ts

@@ -3,16 +3,40 @@ import { IListener } from './IListener';
 export interface NotifyOptions<T = any> {
     params?: T | null;
     source?: any;
+    /**
+     * Collect what the listeners return. A notify that collects is a request, not an
+     * announcement, and is delivered at once wherever it is made.
+     */
     async?: boolean;
+    /**
+     * Deliver as if made inside (`true`) or outside (`false`) an operation, whatever the store
+     * says. `false` is for a signal that is not a change to the document (a dirty flag).
+     */
     transactional?: boolean;
+    /**
+     * Combines the params of two notifications that are delivered to one callback as one, after an
+     * operation lands. Without it the first notification's params are delivered.
+     */
+    merge?: (prev: T | null | undefined, next: T | null | undefined) => T | null | undefined;
 }
 /**
- * Manages Listeners
+ * Manages listeners.
  *
  * @remarks
- * A few rules to know:
+ * `transactional` ({@link IListener.Options}) says whether a listener takes part in the operation
+ * that notifies it. Unless the caller says, it does when it was added through the handle of a batch
+ * open on this emitter's store (`IWorkbook.doBatch`), and does not otherwise, however long a batch
+ * stays open.
  *
- * * non-transactional listeners are fired after the commit end and are conflated.
+ * * A transactional listener is told inline, inside the operation, so what it writes joins that
+ *   commit; it is told during a restore's dispatch for the same reason. It is versioned with the
+ *   document - an undo removes the subscription, a redo restores it - and, being part of an
+ *   operation, it hears nothing announced outside one.
+ * * A non-transactional listener is told ONCE, after the operation has landed, with everything
+ *   the operation announced conflated by callback; a rollback drops it. Outside an operation, and
+ *   during a restore, it is told at once - a restore has no commit to wait for.
+ * * A request (`async`) is delivered at once wherever it is made and returns what the listeners
+ *   answered. A question is not an announcement, and deferring one would break every `await`.
  */
 export declare class ListenerEmitter<SOURCE, EVENTS> {
     protected _transactions: ITransaction.IStore;
@@ -22,10 +46,34 @@ export declare class ListenerEmitter<SOURCE, EVENTS> {
     protected _src: SOURCE;
     protected _listeners: EntrySet<SOURCE, EVENTS>;
     protected _pending: Pending<any, SOURCE>[] | null;
+    protected _landing: Pending<any, SOURCE>[] | null;
     constructor(src: SOURCE, transactions?: ITransaction.IStore);
+    /** DEBUG (temporary): names this emitter in the `__SXL_LOG_EVENTS` trace. Remove with it. */
+    protected _label(): string;
+    /**
+     * `true` while the store is mid-operation: a transaction is open, or a restore is being
+     * dispatched. What a listener added now is a consequence of, and what a notify made now belongs
+     * to.
+     */
+    protected _inOperation(): boolean;
     /** {@inheritDoc IListener.ISource.addListeners} */
     addListeners(listeners: IListener.Callbacks<SOURCE, EVENTS>, options?: IListener.Options): IListener.Remove;
-    protected _doNotify<T = unknown>(listeners: IListener.Callback<SOURCE>[], removes?: IListener.Remove[] | null, options?: NotifyOptions<T>, fired?: Set<IListener.Callback<SOURCE>>): Promise<any>;
+    /**
+     * Write the transactional listener set, copy-on-write, as a fold rather than a step.
+     *
+     * @remarks
+     * The set is document state, so a subscription made by an operation is removed by undoing it
+     * and put back by redoing it. A fold rather than a commit because a registration is not a step
+     * in the history: it adds no undo entry and announces nothing. Inside an open operation the
+     * flag is a no-op on the nested commit and the write simply joins that operation, which is
+     * where a listener added as a consequence of it belongs.
+     */
+    protected _updateEntries(mutate: (entries: EntrySet<SOURCE, EVENTS>) => void): void;
+    protected _doNotify<T = unknown>(listeners: IListener.Callback<SOURCE>[], removes?: IListener.Remove[] | null, options?: NotifyOptions<T>, fired?: Set<IListener.Callback<SOURCE>>, merged?: Map<IListener.Callback<SOURCE>, any> | null): Promise<any>;
+    /** Whether a transactional listener is told of `key`: one is, and it is told inline. */
+    hasTransactional(key: keyof EVENTS): boolean;
+    /** The callbacks for `key` in a bucket, gathered first so a removal during delivery is safe. */
+    protected _collect(entries: EntrySet<SOURCE, EVENTS> | undefined, key: keyof EVENTS): Collected<SOURCE> | null;
     /**
      * Notify listeners.
      */
@@ -37,10 +85,11 @@ interface Entry<SOURCE, EVENTS> {
     listeners: IListener.Callbacks<SOURCE, EVENTS>;
 }
 type EntrySet<SOURCE = any, EVENTS = any> = Set<Entry<SOURCE, EVENTS>>;
-interface Pending<T, SOURCE> {
-    commitId: string;
+interface Collected<SOURCE> {
     listeners: IListener.Callback<SOURCE>[];
     removes: IListener.Remove[] | null;
+}
+interface Pending<T, SOURCE> extends Collected<SOURCE> {
     options?: NotifyOptions<T>;
 }
 export {};