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

package/types/src/fill/PaintUtils.d.ts

@@ -8,8 +8,10 @@ export type ColorToCSS = (color: string) => string | null;
 /**
  * A color as concrete CSS: `#RRGGBB`, or `rgba(r,g,b,a)` when it is not opaque. Never a theme
  * reference, a CSS variable or `light-dark()`.
+ *
+ * @param darkMode The color as a dark grid draws it (`IColor.toRGBA(true)`).
  */
-export declare function toConcreteCSS(color: IColor): string;
+export declare function toConcreteCSS(color: IColor, darkMode?: boolean): string;
 /**
  * A fill with each of its colors drawn through `css`: a solid fill's color, a gradient's stops, a
  * pattern's foreground and background. What it does not color (an image, the gradient's geometry,

package/types/src/font/AdvanceTable.d.ts

@@ -32,8 +32,6 @@ export declare class AdvanceTable implements IFont.AdvanceTable {
     private _hinting;
     /** Measures a character the table lacks, per em; see {@link setMeasureMissing}. */
     private _measureMissing;
-    /** Excel's row pitch per integer ppem from `first`; set once {@link applyRows} has run. */
-    private _rows;
     /** The table in the wasm, built on first ask from this table's data; see {@link native}. */
     private _native;
     /** Per-em advances recorded since the twin was built, written to it on the next ask. */
@@ -52,19 +50,10 @@ export declare class AdvanceTable implements IFont.AdvanceTable {
      * @throws when the format is not one this reads, or the file is for another face.
      */
     applyHinting(json: AdvanceTable.HintedJSON): void;
+    /** {@inheritDoc IFont.AdvanceTable.typoLine} */
+    get typoLine(): number | null;
     /** Whether widths are GDI's hinted whole pixels ({@link applyHinting}). */
     get isHinted(): boolean;
-    /**
-     * Gives the table Excel's own row heights, from the companion `.rows.json` (format
-     * `sheetxl-font-rows/1`) captured from Excel: {@link metrics} then reports the pitch Excel
-     * autofits a row of this face to at each size. GDI's box plus 2 is Excel's up to about 22 pt
-     * and runs under it from there, by a per-font amount no table predicts.
-     *
-     * @throws when the format is not one this reads, or fewer than two sizes are listed.
-     */
-    applyRows(json: AdvanceTable.RowsJSON): void;
-    /** Whether row heights are Excel's captured ones ({@link applyRows}). */
-    get hasRows(): boolean;
     /** The number of characters with an advance. */
     get size(): number;
     /** The advance of `codepoint` per em, or `undefined` when the table has none. */
@@ -78,7 +67,7 @@ export declare class AdvanceTable implements IFont.AdvanceTable {
     private _record;
     /**
      * This table in the wasm (the binding's `MetricsTable`), for the Rust wrapper to measure from:
-     * filled once from the same advances, hinted deltas and row pitches, and kept in step with them
+     * filled once from the same advances and hinted deltas, and kept in step with them
      * afterwards, so the wrapper measures exactly what {@link width} and {@link metrics} do. The
      * table stays the owner; the twin is its view, freed by {@link release}.
      *
@@ -90,8 +79,8 @@ export declare class AdvanceTable implements IFont.AdvanceTable {
     get hasNative(): boolean;
     /**
      * Frees the wasm twin, if there is one; the next {@link native} builds it again. The wasm has
-     * no garbage collector, so a table that changes what it would answer ({@link applyHinting},
-     * {@link applyRows}) or goes out of use lets its twin go here.
+     * no garbage collector, so a table that changes what it would answer ({@link applyHinting}) or
+     * goes out of use lets its twin go here.
      */
     release(): void;
     private _buildNative;
@@ -110,7 +99,10 @@ export declare class AdvanceTable implements IFont.AdvanceTable {
     width(text: string, px: number, options?: AdvanceTable.WidthOptions): number;
     /** One character's advance in px: hinted whole pixels when the table is hinted. */
     private _advancePx;
-    /** The face's whole-px vertical metrics at `px` pixels per em. */
+    /**
+     * The face's whole-px vertical metrics at `px` pixels per em: GDI's ascent and descent, and a
+     * line their sum tall (the win metrics ask for no leading).
+     */
     metrics(px: number): IFont.Metrics;
     /**
      * The underline at `px`: its center's offset above the baseline (negative below) and its
@@ -158,31 +150,6 @@ export declare namespace AdvanceTable {
          */
         sizes: [number, number[]][];
     }
-    /** The `format` of a `.rows.json` this version reads. */
-    const ROWS_FORMAT = "sheetxl-font-rows/1";
-    /**
-     * A captured `.rows.json`, the companion of a `.metrics.json`: Excel's autofit row height for
-     * the face, in px at 96 dpi, at every integer ppem from `firstPpem` up to where the row reaches
-     * Excel's 409 pt cap (`private-assets/design/rust/tools/capture-excel-row-heights.ps1`).
-     */
-    interface RowsJSON {
-        format: typeof ROWS_FORMAT;
-        family: string;
-        weight: number;
-        italic: boolean;
-        source?: {
-            application?: string;
-            dpi?: number;
-        };
-        firstPpem: number;
-        /** `pitches[i]` is the pitch at `firstPpem + i`. */
-        pitches: number[];
-    }
-    /** Excel's row pitch per integer ppem, from `first` on. */
-    interface RowPitches {
-        readonly first: number;
-        readonly pitches: readonly number[];
-    }
     /** A table's twin in the wasm: the binding's `MetricsTable` (`crates/sheetxl-wasm-sdk`). */
     type Native = InstanceType<SdkWasmExports['MetricsTable']>;
     type Face = IFont.AdvanceTable.Face;
@@ -195,6 +162,8 @@ export declare namespace AdvanceTable {
         ascent: number;
         /** OS/2 `winDescent` per em, positive below the baseline. */
         descent: number;
+        /** See {@link IFont.AdvanceTable.typoLine}; absent for a font that does not ask for it. */
+        typoLine?: number | null;
         underline?: LineRule | null;
         strikeout?: LineRule | null;
     }
@@ -217,6 +186,11 @@ export declare namespace AdvanceTable {
         unitsPerEm: number;
         winAscent: number;
         winDescent: number;
+        /**
+         * Typo ascent less descent plus line gap in design units, present only when the font sets
+         * `USE_TYPO_METRICS`.
+         */
+        typoLine?: number;
         /** `[position, thickness]` in design units. */
         underline?: [number, number];
         /** `[position, thickness]` in design units. */

package/types/src/font/IFont.d.ts

@@ -165,9 +165,8 @@ export declare namespace IFont {
         readonly strikeThickness?: number;
         readonly italicAngle?: number;
         /**
-         * The line pitch in px — what a line of this font advances by, and the height of a row sized
-         * to it: `ascent + descent + 2` (Excel's standard row height for the font; the 2 is the
-         * gridline gutter above and below the font box). Includes {@link lineGap}.
+         * The line pitch in px — what a line of this text advances by: {@link ascent} plus
+         * {@link descent} plus {@link lineGap}.
          */
         readonly lineHeight: number;
         /**
@@ -175,6 +174,7 @@ export declare namespace IFont {
          * paints the line as a box (a CSS line box) puts the alphabetic baseline.
          */
         readonly baseline: number;
+        /** The leading in px: the room in {@link lineHeight} beyond the ascent and descent. */
         readonly lineGap: number;
         /**
          * The font's ascent above the baseline in whole px at the measured size — GDI's `tmAscent`,
@@ -190,9 +190,8 @@ export declare namespace IFont {
      *
      * @remarks
      * Advances are per em and vertical metrics follow GDI, so a table measures as Excel does: a
-     * shipped face measures GDI's hinted whole pixels and sizes rows as Excel autofits them. Tables
-     * are built by the collection from the shipped files or the platform; they are read here, never
-     * made or changed.
+     * shipped face measures GDI's hinted whole pixels. Tables are built by the collection from the
+     * shipped files or the platform; they are read here, never made or changed.
      */
     interface AdvanceTable {
         /** The family the table measures, as a style names it. */
@@ -202,8 +201,12 @@ export declare namespace IFont {
         readonly italic: boolean;
         /** Whether widths are GDI's hinted whole pixels. */
         readonly isHinted: boolean;
-        /** Whether row heights are Excel's own captured ones. */
-        readonly hasRows: boolean;
+        /**
+         * The height of a line per em by the font's typo metrics (ascent less descent plus line gap),
+         * for a font that asks for them; `null` otherwise. DirectWrite lays a line out this tall, so
+         * Excel's charts do.
+         */
+        readonly typoLine: number | null;
         /** The number of characters with an advance. */
         readonly size: number;
         /** The advance of `codepoint` per em, or `undefined` when the table has none. */
@@ -215,7 +218,10 @@ export declare namespace IFont {
          * super/subscript scale, then `letterSpacing` between characters.
          */
         width(text: string, px: number, options?: AdvanceTable.WidthOptions): number;
-        /** The face's whole-px vertical metrics at `px` pixels per em. */
+        /**
+         * The face's whole-px vertical metrics at `px` pixels per em: GDI's ascent and descent, and a
+         * line as tall as the font's own metrics ask.
+         */
         metrics(px: number): Metrics;
         /**
          * The underline at `px`: its center's offset above the baseline (negative below) and its
@@ -344,6 +350,23 @@ export declare namespace IFont {
      * ```
      */
     function captureTables(bytes: Uint8Array, options?: CaptureOptions): Promise<CapturedFace[]>;
+    /**
+     * The CSS `font-family` value that paints `family`: the family, then the fonts that stand in for
+     * it where it is not installed, then `fallbacks`, each followed by its own stand-ins.
+     *
+     * A stand-in is the family `family` is measured by and that family's open metric-compatible
+     * twins, so text painted on a machine without the original still fits its measurement.
+     *
+     * @param family The family as a style names it.
+     * @param fallbacks Families or CSS generic names to try after it.
+     *
+     * @example
+     * ```ts
+     * IFont.toCSSFontFamily('Calibri', ['sans-serif']); // 'Calibri, Carlito, sans-serif'
+     * IFont.toCSSFontFamily('Aptos Narrow', ['sans-serif']); // '"Aptos Narrow", "Intos Narrow", Calibri, Carlito, sans-serif'
+     * ```
+     */
+    function toCSSFontFamily(family: string, fallbacks?: readonly string[] | null): string;
     /**
      * Provides a font-family fallback based on the PANOSE hex string.
      *

package/types/src/font/TableFileAdvanceBuilder.d.ts

@@ -16,15 +16,18 @@ export declare class TableFileAdvanceBuilder implements AdvanceBuilder {
     readonly name = "table-file";
     readonly kind = "table";
     private readonly _base;
+    private readonly _companions;
     private readonly _pending;
     /**
      * @param base A base to search after the user resource roots, or `null` for none (the default).
+     * @param companions Other files shipped beside a face's tables, by suffix (`.rows.json`): each
+     *   one found is handed to its reader before the table resolves.
      */
-    constructor(base?: string | null);
+    constructor(base?: string | null, companions?: Readonly<Record<string, (json: any) => void>>);
     build(face: AdvanceTable.Face): Promise<AdvanceTable | null>;
     /**
-     * Gives `table` the hinted widths of its `.hinted.json` companion and Excel's row heights from
-     * its `.rows.json`, those it has.
+     * Gives `table` the hinted widths of its `.hinted.json` companion, and hands each other
+     * companion the face has to its reader.
      *
      * @returns Whether the table is hinted now.
      */

package/types/src/font/_FontUtils.d.ts

@@ -2,14 +2,6 @@ export declare const DefaultMinFontSize: number;
 export declare const DefaultMaxFontSize: number;
 export declare const DefaultMaxFontPrecision: number;
 export declare const DefaultLineHeightMultiplier: number;
-/**
- * Excel's horizontal padding a side for a cell whose font's widest digit is `digitWidth` px: a
- * quarter of that digit, rounded up (2 px at Calibri 11, 17 at Calibri 100, 56 at Arial 300).
- * Exact against Excel's own autofit over 130 cells, Calibri and Arial, 8 to 48 pt
- * (`private-assets/design/rust/tools/sweep-excel-autofit.ps1`), and against the column at which
- * Excel stops showing a number as `#` from 20 to 300 pt (`tools/oracle-excel-overflow.ps1`:
- * content + 2 x this + 1 every time).
- */
 export declare function defaultHorizontalPadding(digitWidth: number): number;
 export declare function defaultVerticalPadding(_fontSize: number): number;
 /**

package/types/src/font/_StandIns.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Which family measures which, and what paints in its place where it is not installed.
+ *
+ * Kept free of imports: the measurer (`FontCollection`) and every CSS `font-family` writer read it,
+ * so a family's paint stack and the table it is measured by cannot drift apart.
+ */
+/**
+ * Families measured by another family's table: the metric-compatible twins by the family they
+ * twin, the near relations by the closest family we have, and the CSS generic names by a family
+ * of their class. A relation is used only when the family has no table of its own: Aptos has
+ * one, and is measured as Calibri only where its tables cannot be reached (Aptos Narrow's digits
+ * are Calibri's). Calibri Light's digits and line metrics are Calibri's, its letters about 1%
+ * narrower.
+ */
+export declare const RELATED: ReadonlyMap<string, string>;
+/**
+ * The families that paint in `family`'s place, in order, not including `family` itself: its own
+ * open metric twins, then the family it is measured by when its table cannot be reached and that
+ * family's twins. Empty for a family measured by nothing but itself or the canvas, and for a CSS
+ * generic name.
+ */
+export declare function standInsOf(family: string): readonly string[];
+/**
+ * `families` with each one's stand-ins after it, duplicates dropped: the stack a platform paints
+ * `families` from.
+ */
+export declare function withStandIns(families: readonly string[]): string[];
+/**
+ * A CSS `font-family` value for `family` and its `fallbacks`, each followed by its stand-ins: a
+ * generic name bare, every other name quoted when it has more than one word.
+ */
+export declare function toCSSFontFamily(family: string, fallbacks?: readonly string[] | null): string;
+//# sourceMappingURL=_StandIns.d.ts.map

package/types/src/hyperlink/IHyperlink.d.ts

@@ -57,8 +57,18 @@ export interface IHyperlink {
     getTarget(): string;
     /**
      * Removes the link from the cell it is attached to. The cell's text stays.
+     *
+     * @throws When the link is read-only ({@link isReadOnly}).
      */
     delete(options?: ITransaction.OperationOptions): void;
+    /**
+     * Whether the link can only be followed: it is not edited or removed as a link.
+     *
+     * @remarks
+     * A link that is the cell's value (a `HYPERLINK()` result) is read-only; it changes with its
+     * formula.
+     */
+    isReadOnly(): boolean;
     /**
      * For runtime type checking.
      */

package/types/src/hyperlink/_Hyperlink.d.ts

@@ -12,7 +12,10 @@ export declare class Hyperlink implements IHyperlink {
     protected _p: IHyperlink.Properties;
     protected _r: (address: string, options: ITypes.SelectOptions | null, target: string, features?: string) => Promise<boolean>;
     protected _d: ((options?: ITransaction.OperationOptions) => void) | undefined;
-    constructor(textToDisplay: () => string, resolver: (address: string, options: ITypes.SelectOptions | null, target: string, features?: string) => Promise<boolean>, json: IHyperlink.JSON, remover?: (options?: ITransaction.OperationOptions) => void);
+    protected _readOnly: boolean;
+    constructor(textToDisplay: () => string, resolver: (address: string, options: ITypes.SelectOptions | null, target: string, features?: string) => Promise<boolean>, json: IHyperlink.JSON, remover?: (options?: ITransaction.OperationOptions) => void, readOnly?: boolean);
+    /** {@inheritDoc IHyperlink.isReadOnly} */
+    isReadOnly(): boolean;
     /** {@inheritDoc IHyperlink.delete} */
     delete(options?: ITransaction.OperationOptions): void;
     /** {@inheritDoc IHyperlink.open} */

package/types/src/index.d.ts

@@ -28,12 +28,12 @@ export * from './hyperlink';
 export * from './numFmt';
 export * from './style';
 export * from './resource';
+export * from './fetch';
 export * from './string';
 export * from './richData';
 export * from './anchored';
 export * from './chart';
 export * from './pivot';
-export * from './dataTable';
 export * from './picture';
 export * from './shape';
 export * from './group';
@@ -51,6 +51,7 @@ export * from './externalBook';
 export * from './dataValidation';
 export * from './conditionalFormat';
 export * from './protectedRange';
+export * from './cellControl';
 export * from './slicer';
 export * from './table';
 export { Table } from './table/Table';

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

@@ -454,7 +454,7 @@ export declare namespace IWorkbookIO {
          * write path both actually ask, use {@link isEncrypted}.
          *
          * Never the password: origins are rendered into logs and REPL output, and ride events and
-         * progress callbacks, so a secret has no business here (see `PROTECTION-DESIGN.md` §5f).
+         * progress callbacks, so a secret has no business here.
          *
          * Use it to show a lock affordance, and to recognise that writing plaintext over it would be a
          * downgrade — {@link IWorkbookIO.WriteOptions.password} makes that refusal explicit.
@@ -860,8 +860,8 @@ export declare namespace IWorkbookIO {
          * - `'auto'` — cached values are trusted; the load pass evaluates a formula cell with no
          *   cached value (a repair — Excel always stores one) and refreshes volatiles. Everything is
          *   recalculated only when Excel would recalculate on open: the file sets `fullCalcOnLoad`,
-         *   or for xlsx its `calcId` is missing or older than the Excel build this library is
-         *   verified against. (What this library writes carries one: the source file's, else that
+         *   or for xlsx its `calcId` is missing or older than the Excel build this library
+         *   targets. (What this library writes carries one: the source file's, else that
          *   build's.) To take the file's values as they are whatever it says — as openpyxl does —
          *   pass `'none'`; to always recalculate, `'full'`.
          * - `'full'` — everything is recalculated, whatever the file says.

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

@@ -100,12 +100,12 @@ export declare class WorkbookOrigin implements IWorkbookIO.Origin {
      * Update what is known about the file in place. Fires `onChange` if anything actually changed.
      *
      * @remarks
-     * The **privileged mutation channel** (see `DESIGN-IO.md`) for the backing store and the IO layer:
+     * The **privileged mutation channel** 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).
+     * destination mints a new origin for it.
      */
     update(next: {
         name?: string | null;

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

@@ -21,7 +21,8 @@ declare class LM {
     private _doPrint;
     private _print;
     /**
-     * Return the current license details.
+     * Return the current license details. Prints nothing: the license notice is printed when the
+     * engine starts under the license (see {@link assertUsable}).
      */
     getDetails(): Promise<LicenseDetails>;
     /**

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

@@ -13,10 +13,11 @@ export declare function getBuildDate(): string;
  *
  * @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.
+ * only one that is never updated does. Seventy days gives a pinned install (CI, a locked
+ * lockfile) over two months before it has to move, and bounds how long any one build can run
+ * unlicensed.
  */
-export declare const EVAL_PERIOD_DAYS = 90;
+export declare const EVAL_PERIOD_DAYS = 70;
 /** 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. */

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

@@ -18,7 +18,9 @@ export interface UnlicensedOptions {
  */
 export declare const genUnlicensedDetails: (options: UnlicensedOptions) => LicenseDetails;
 /**
- * The license a key grants on `host`. A key that does not decode is an `invalid` license.
+ * The license a key grants on `host`. A key that is not a validly signed token is an `invalid`
+ * license. A development build checks no signatures, so it accepts keys only in a development
+ * environment; deployed anywhere else, it rejects every key.
  */
 export declare const detailsForKey: (from: string, key: string, host: HostDetails, isDevEnv: boolean) => LicenseDetails;
 //# sourceMappingURL=details.d.ts.map

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

@@ -0,0 +1,6 @@
+/**
+ * The public keys this build accepts license tokens from, by key id, or `null` in a development build,
+ * where signatures are not checked.
+ */
+export declare function getTrustedKeys(): Readonly<Record<string, string>> | null;
+//# sourceMappingURL=keys.d.ts.map

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

@@ -1,4 +1,3 @@
-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
@@ -6,49 +5,33 @@ import { LicenseDetails } from './LicenseDetails';
  */
 export type LicenseRuntime = 'browser' | 'server';
 export declare const LICENSE_RUNTIMES: readonly LicenseRuntime[];
+/** The terms of a verified license token (see `verifyLicenseToken`). */
 export interface Decoded {
+    /** The signing key's id. */
+    keyId?: string;
+    /** The license id, stable across reissues. */
+    licenseId?: string;
     licensee?: string | null;
     type?: string;
+    /** Issued at, epoch milliseconds. */
+    issuedAt?: number;
+    /** Expires at, epoch milliseconds. */
     expiry?: number;
     developerCount?: number;
-    /** The runtimes the key covers; `undefined` for a key issued before runtimes were explicit. */
+    /** The runtimes the key covers. */
     runtimes?: LicenseRuntime[];
+    /** Licensed origins, `<protocol>://<host>` (see `Origin`). */
     domains?: string[];
+    /** Node fingerprint. */
     fingerprint?: string | null;
+    /** Number of CPUs (0 = unconstrained). */
     cpuCount?: number;
+    /** Memory in GB (0 = unconstrained). */
     memory?: number | null;
-    features?: Record<string, any>[];
+    features?: Record<string, unknown>;
 }
-/**
- * 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).
- */
+/** The runtimes a decoded key covers. */
 export declare function getRuntimes(decoded: Decoded): LicenseRuntime[];
-export interface LicenseAndKey {
-    details: LicenseDetails;
-    key: string;
-}
-export interface LicenseKeyDetails {
-    licensee: string;
-    type?: string | null;
-    expiration?: string | null;
-    developerCount?: number;
-    /**
-     * 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;
-    features?: Record<string, any> | null;
-}
-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>`.
@@ -76,5 +59,4 @@ export declare function validateOrigin(entry: string, allowDomain?: boolean): bo
  * 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/token.d.ts

@@ -0,0 +1,55 @@
+import { Decoded, LicenseRuntime } from './license-key';
+/** The format version every token starts with: `sxl1.<payload>.<signature>`. */
+export declare const LICENSE_TOKEN_PREFIX = "sxl1";
+/**
+ * The signed body of a license token. Keys are short because a browser key is served to every
+ * visitor and travels in config. There is no email or other personal data.
+ */
+export interface LicenseTokenPayload {
+    /** The signing key's id. */
+    kid: string;
+    /** The license id, stable across reissues. */
+    lid: string;
+    /** Licensee. */
+    l: string;
+    /** License type, e.g. `community`, `commercial`. */
+    t: string;
+    /** The runtimes the license covers. */
+    r: LicenseRuntime[];
+    /** Licensed origins, `<protocol>://<host>`. */
+    d?: string[];
+    /** Developer count. */
+    dc?: number;
+    /** CPU count (0 or absent = unconstrained). */
+    cc?: number;
+    /** Memory in GB (0 or absent = unconstrained). */
+    m?: number;
+    /** Node fingerprint. */
+    n?: string;
+    /** Features. */
+    f?: Record<string, unknown>;
+    /** Issued at, epoch seconds. */
+    iat: number;
+    /** Expires at, epoch seconds. */
+    exp: number;
+}
+/** Why a token was rejected. The message is shown to the user as the license exception. */
+export declare class LicenseTokenError extends Error {
+    constructor(message: string);
+}
+/** Decodes unpadded base64url. */
+export declare function fromBase64Url(text: string): Uint8Array;
+/**
+ * Reads a license token without checking its signature. For display and diagnostics only; never
+ * grant anything on the result.
+ */
+export declare function readLicenseTokenPayload(token: string): LicenseTokenPayload;
+/**
+ * Verifies a license token's signature against the keys this build trusts and returns its terms.
+ * Expiry, origin, runtime and hardware are not checked here; `details.ts` checks them against the
+ * host. With `trustedKeys` `null` (a development build, see `keys.ts`) the signature is not checked.
+ *
+ * @throws LicenseTokenError when the token is malformed, signed by an unknown key, or altered.
+ */
+export declare function verifyLicenseToken(token: string, trustedKeys?: Readonly<Record<string, string>> | null): Decoded;
+//# sourceMappingURL=token.d.ts.map

package/types/src/named/INamedCollection.d.ts

@@ -78,6 +78,25 @@ export interface INamedCollection extends ICollection<INamed> {
      * take the first.
      */
     getByRanges(ranges: ICellRanges.Address, options?: INamedCollection.GetByRangesOptions): string[];
+    /**
+     * Deletes the defined names nothing reads, as one operation.
+     *
+     * @param options `hiddenOnly` limits it to names flagged hidden; `dryRun` counts without deleting.
+     * @returns How many names were deleted, or with `dryRun`, would be.
+     * @throws `Error` if the names are read-only (a protected workbook structure) and this is not a dry run.
+     *
+     * @remarks
+     * A name is read when a cell formula, a conditional format, a data validation, a chart or another
+     * name refers to it — the readers `ICalculation.INamedFormula.getDependents` reports. A name
+     * that a kept name's definition mentions is kept too, whether or not anything reads that one.
+     * Only defined names are considered; a table is named by the table it belongs to. Excel's built-in
+     * names (`_xlnm.Print_Area`, `_xlnm.Print_Titles`, `_xlnm._FilterDatabase`) are read by the sheet
+     * itself, not by formulas, and are never removed.
+     *
+     * One operation, so one undo puts every name back. Asked of a sheet's collection
+     * (`IWorksheet.getNames()`), only the names scoped to that sheet are considered.
+     */
+    removeUnused(options?: INamedCollection.RemoveUnusedOptions): Promise<number>;
     /**
      * Lookup a named range with a given name.
      *
@@ -216,6 +235,23 @@ export declare namespace INamedCollection {
          */
         includeHidden?: boolean;
     }
+    /**
+     * Options for {@link INamedCollection.removeUnused}.
+     */
+    interface RemoveUnusedOptions {
+        /**
+         * Only names flagged hidden — the ones a user cannot see to delete.
+         *
+         * @defaultValue false
+         */
+        hiddenOnly?: boolean;
+        /**
+         * Count the names that would be deleted, and delete none.
+         *
+         * @defaultValue false
+         */
+        dryRun?: boolean;
+    }
     /**
      * Options for {@link INamedCollection.getByRanges}.
      *

package/types/src/named/NamedCollection.d.ts

@@ -143,6 +143,14 @@ export declare class NamedCollection extends AbstractCollection<INamed, INamedCo
      * {@link _scopedTo}.
      */
     addFormula(name: string, expression: string, replaceExisting?: boolean): INamed;
+    /** {@inheritDoc INamedCollection.removeUnused} */
+    removeUnused(options?: INamedCollection.RemoveUnusedOptions): Promise<number>;
+    /**
+     * {@link removeUnused}, limited to one scope — see {@link _scopedTo}.
+     *
+     * @param scope The sheet whose names are considered; `undefined` for every scope.
+     */
+    _removeUnused(options: INamedCollection.RemoveUnusedOptions | undefined, scope: string | undefined): Promise<number>;
     /** {@link addFormula}, against an explicit `scope` — see {@link _scopedTo}. */
     _addFormula(name: string, expression: string, replaceExisting?: boolean, scope?: string | null): INamed;
     /** {@inheritDoc ITransaction.ITransactional.beginCommit} */
@@ -249,6 +257,16 @@ export declare namespace NamedCollection {
          * nothing to prepare and leaves it undefined.
          */
         prepareRanges?(items: readonly INamed[]): void;
+        /**
+         * Backs {@link INamedCollection.removeUnused} for the source that owns defined names.
+         *
+         * @remarks
+         * `scope`, when given, is the sheet whose own names are considered (a sheet's collection);
+         * `undefined` considers every scope.
+         */
+        removeUnused?(options: INamedCollection.RemoveUnusedOptions & {
+            scope?: string;
+        }): Promise<number>;
     }
     /**
      * What {@link Source.add} needs to define a name.