Core API

Curated reference for LayerClient, LayerStack, layerOptions, typing helpers, and core utilities.

Symbols below are exported from @stainless-code/layers (packages/core). React/Preact/Solid/Angular/Vue/Lit/Alpine re-export the full core. Svelte re-exports selectively — core’s headless createLayer is createLayerHandle.

LayerClient

App-wide coordinator for named layer stacks.

class LayerClient {
  constructor(opts?: LayerClientOptions);
  open(options): Promise<R>;
  getStack(id?: string): LayerStack;
  ensureStack(id: string, options?: StackOptions): LayerStack;
  getStackIds(): string[];
  subscribeStacks(listener: (stackId: string) => void): () => void;
  subscribeNotify(listener: (event: StackNotifyEvent) => void): () => void;
  seedNotify(stackId?: string): void;
  dismissAll(
    stackId?: string,
    response?: unknown,
    opts?: DismissAllOptions,
  ): Promise<void>;
  cancelAll(
    stackId?: string,
    opts?: { reason?: LayerCancelReason },
  ): Promise<void>;
}

Method	Purpose
`open`	Opens a layer on a stack; resolves with the dismissal response (or rejects on load/validation/cancel)
`getStack`	Returns a stack by id, creating the default stack on first access
`ensureStack`	Returns a stack, applying `StackOptions` only when creating it
`getStackIds`	Lists materialized stack ids
`subscribeStacks`	Notifies when a stack is created for the first time
`subscribeNotify`	Labeled stack transitions (`StackNotifyEvent`) for inspectors / Devtools
`seedNotify`	Re-emits a `register` notify for one stack, or all materialized stacks when omitted
`dismissAll`	Async bulk dismiss on one stack (honors blockers unless `mode: "force"`); completes with `response`
`cancelAll`	Force-clear; rejects every open/queued caller with `LayerCancelledError` (skips blockers)

PropType

defaultStackOptions?StackDefaults

TypeStackDefaults

LayerStack

Ordered layers for one surface. Extends Subscribable — use subscribe for snapshot updates.

class LayerStack {
  readonly id: string;
  readonly options: StackOptions;

  getSnapshot(): LayerState[];
  getQueuedSnapshot(): LayerState[];
  subscribe(listener: () => void): () => void;

  find(key: LayerKey): Layer | undefined; // topmost same-key (findLast)
  getLayer(id: string): Layer | undefined;
  dismiss(layer, ...args: EndArgs<R>): Promise<boolean>;
  dismissAll(...args: DismissAllArgs<R>): Promise<void>;
  cancelAll(opts?: { reason?: LayerCancelReason }): Promise<void>;
  addBlocker(fn: StackBlockerFn): () => void;
  cancelQueued(key: LayerKey, ...args: CancelQueuedArgs<R>): boolean;
  settle(layer): void;
  setRunning(layer, running: boolean): void;
  update(layer, patch: Partial<P>): void;
}

Method	Purpose
`getSnapshot`	Stable-ref snapshot of mounted layers (`pending`/`active`/`dismissed`/`error`)
`getQueuedSnapshot`	Serial-scope queue — layers waiting behind the occupying layer
`subscribe`	Register for snapshot changes (batched via `notifyManager`)
`find`	Topmost mounted layer for a logical key (key signature; `findLast`)
`dismiss`	Resolve one layer; response optional when `undefined extends R` (`EndArgs`); blockers may veto
`cancelQueued`	Resolve a serial `queued` layer without mounting; same response gate; omit `{ id }` → FIFO, `{ id }` → exact match
`addBlocker`	Stack-scoped dismiss gate; returns a disposer

StackNotifyEvent

JSON-safe transition record for subscribeNotify (Devtools and headless inspectors). Distinct from subscribe snapshot identity — see Devtools.

PropType

toString() => string

Returns a string representation of a string.

Type() => string

charAt(pos: number) => string

Returns the character at the specified index.

Type(pos: number) => string

charCodeAt(index: number) => number

Returns the Unicode value of the character at the specified location.

Type(index: number) => number

concat(...strings: string[]) => string

Returns a string that contains the concatenation of two or more strings.

Type(...strings: string[]) => string

indexOf(searchString: string, position?: number | undefined) => number

Returns the position of the first occurrence of a substring, or -1 if it is not present.

Type(searchString: string, position?: number | undefined) => number

lastIndexOf(searchString: string, position?: number | undefined) => number

Returns the last occurrence of a substring in the string, or -1 if it is not present.

Type(searchString: string, position?: number | undefined) => number

localeCompare

{ (that: string): number; (that: string, locales?: string | string[] | undefined, options?: CollatorOptions | undefined): number; (that: string, locales?: LocalesArgument, options?: CollatorOptions | undefined): number; }

Determines whether two strings are equivalent in the current locale. Determines whether two strings are equivalent in the current or specified locale.

Type

{ (that: string): number; (that: string, locales?: string | string[] | undefined, options?: CollatorOptions | undefined): number; (that: string, locales?: LocalesArgument, options?: CollatorOptions | undefined): number; }

match

{ (regexp: string | RegExp): RegExpMatchArray | null; (matcher: { [Symbol.match](string: string): RegExpMatchArray | null; }): RegExpMatchArray | null; }

Matches a string with a regular expression, and returns an array containing the results of that search. Matches a string or an object that supports being matched against, and returns an array containing the results of that search, or null if no matches are found.

Type

{ (regexp: string | RegExp): RegExpMatchArray | null; (matcher: { [Symbol.match](string: string): RegExpMatchArray | null; }): RegExpMatchArray | null; }

replace

{ (searchValue: string | RegExp, replaceValue: string): string; (searchValue: string | RegExp, replacer: (substring: string, ...args: any[]) => string): string; (searchValue: { ...; }, replaceValue: string): string; (searchValue: { ...; }, replacer: (substring: string, ...args: any[]) => string): string; }

Replaces text in a string, using a regular expression or search string. Passes a string and {@linkcode replaceValue} to the `[Symbol.replace]` method on {@linkcode searchValue}. This method is expected to implement its own replacement algorithm. Replaces text in a string, using an object that supports replacement within a string.

Type

{ (searchValue: string | RegExp, replaceValue: string): string; (searchValue: string | RegExp, replacer: (substring: string, ...args: any[]) => string): string; (searchValue: { ...; }, replaceValue: string): string; (searchValue: { ...; }, replacer: (substring: string, ...args: any[]) => string): string; }

search{ (regexp: string | RegExp): number; (searcher: { [Symbol.search](string: string): number; }): number; }

Finds the first substring match in a regular expression search.

Type{ (regexp: string | RegExp): number; (searcher: { [Symbol.search](string: string): number; }): number; }

slice(start?: number | undefined, end?: number | undefined) => string

Returns a section of a string.

Type(start?: number | undefined, end?: number | undefined) => string

split

{ (separator: string | RegExp, limit?: number | undefined): string[]; (splitter: { [Symbol.split](string: string, limit?: number | undefined): string[]; }, limit?: number | undefined): string[]; }

Split a string into substrings using the specified separator and return them as an array.

Type

{ (separator: string | RegExp, limit?: number | undefined): string[]; (splitter: { [Symbol.split](string: string, limit?: number | undefined): string[]; }, limit?: number | undefined): string[]; }

substring(start: number, end?: number | undefined) => string

Returns the substring at the specified location within a String object.

Type(start: number, end?: number | undefined) => string

toLowerCase() => string

Converts all the alphabetic characters in a string to lowercase.

Type() => string

toLocaleLowerCase{ (locales?: string | string[] | undefined): string; (locales?: LocalesArgument): string; }

Converts all alphabetic characters to lowercase, taking into account the host environment's current locale.

Type{ (locales?: string | string[] | undefined): string; (locales?: LocalesArgument): string; }

toUpperCase() => string

Converts all the alphabetic characters in a string to uppercase.

Type() => string

toLocaleUpperCase{ (locales?: string | string[] | undefined): string; (locales?: LocalesArgument): string; }

Returns a string where all alphabetic characters have been converted to uppercase, taking into account the host environment's current locale.

Type{ (locales?: string | string[] | undefined): string; (locales?: LocalesArgument): string; }

trim() => string

Removes the leading and trailing white space and line terminator characters from a string.

Type() => string

length

Returns the length of a String object.

Type

substr(from: number, length?: number | undefined) => string

Gets a substring beginning at the specified location and having the specified length.

Type(from: number, length?: number | undefined) => string

valueOf() => string

Returns the primitive value of the specified object.

Type() => string

codePointAt(pos: number) => number | undefined

Returns a nonnegative integer Number less than 1114112 (0x110000) that is the code point value of the UTF-16 encoded code point starting at the string element at position pos in the String resulting from converting this object to a String. If there is no element at that position, the result is undefined. If a valid UTF-16 surrogate pair does not begin at pos, the result is the code unit at pos.

Type(pos: number) => number | undefined

includes(searchString: string, position?: number | undefined) => boolean

Returns true if searchString appears as a substring of the result of converting this object to a String, at one or more positions that are greater than or equal to position; otherwise, returns false.

Type(searchString: string, position?: number | undefined) => boolean

endsWith(searchString: string, endPosition?: number | undefined) => boolean

Returns true if the sequence of elements of searchString converted to a String is the same as the corresponding elements of this object (converted to a String) starting at endPosition – length(this). Otherwise returns false.

Type(searchString: string, endPosition?: number | undefined) => boolean

normalize{ (form: "NFC" | "NFD" | "NFKC" | "NFKD"): string; (form?: string | undefined): string; }

Returns the String value result of normalizing the string into the normalization form named by form as specified in Unicode Standard Annex #15, Unicode Normalization Forms.

Type{ (form: "NFC" | "NFD" | "NFKC" | "NFKD"): string; (form?: string | undefined): string; }

repeat(count: number) => string

Returns a String value that is made from count copies appended together. If count is 0, the empty string is returned.

Type(count: number) => string

startsWith(searchString: string, position?: number | undefined) => boolean

Returns true if the sequence of elements of searchString converted to a String is the same as the corresponding elements of this object (converted to a String) starting at position. Otherwise returns false.

Type(searchString: string, position?: number | undefined) => boolean

anchor(name: string) => string

Returns an `<a>` HTML anchor element and sets the name attribute to the text value

Type(name: string) => string

big() => string

Returns a `<big>` HTML element

Type() => string

blink() => string

Returns a `<blink>` HTML element

Type() => string

bold() => string

Returns a `` HTML element

Type() => string

fixed() => string

Returns a `<tt>` HTML element

Type() => string

fontcolor(color: string) => string

Returns a `` HTML element and sets the color attribute value

Type(color: string) => string

fontsize{ (size: number): string; (size: string): string; }

Returns a `` HTML element and sets the size attribute value

Type{ (size: number): string; (size: string): string; }

italics() => string

Returns an `` HTML element

Type() => string

link(url: string) => string

Returns an `<a>` HTML element and sets the href attribute value

Type(url: string) => string

small() => string

Returns a `` HTML element

Type() => string

strike() => string

Returns a `<strike>` HTML element

Type() => string

sub() => string

Returns a `` HTML element

Type() => string

sup() => string

Returns a `` HTML element

Type() => string

padStart(maxLength: number, fillString?: string | undefined) => string

Pads the current string with a given string (possibly repeated) so that the resulting string reaches a given length. The padding is applied from the start (left) of the current string.

Type(maxLength: number, fillString?: string | undefined) => string

padEnd(maxLength: number, fillString?: string | undefined) => string

Pads the current string with a given string (possibly repeated) so that the resulting string reaches a given length. The padding is applied from the end (right) of the current string.

Type(maxLength: number, fillString?: string | undefined) => string

trimEnd() => string

Removes the trailing white space and line terminator characters from a string.

Type() => string

trimStart() => string

Removes the leading white space and line terminator characters from a string.

Type() => string

trimLeft() => string

Removes the leading white space and line terminator characters from a string.

Type() => string

trimRight() => string

Removes the trailing white space and line terminator characters from a string.

Type() => string

matchAll(regexp: RegExp) => RegExpStringIterator<RegExpExecArray>

Matches a string with a regular expression, and returns an iterable of matches containing the results of that search.

Type(regexp: RegExp) => RegExpStringIterator<RegExpExecArray>

replaceAll

{ (searchValue: string | RegExp, replaceValue: string): string; (searchValue: string | RegExp, replacer: (substring: string, ...args: any[]) => string): string; }

Replace all instances of a substring in a string, using a regular expression or search string.

Type

{ (searchValue: string | RegExp, replaceValue: string): string; (searchValue: string | RegExp, replacer: (substring: string, ...args: any[]) => string): string; }

at(index: number) => string | undefined

Returns a new String consisting of the single UTF-16 code unit located at the specified index.

Type(index: number) => string | undefined

isWellFormed() => boolean

Returns true if all leading surrogates and trailing surrogates appear paired and in order.

Type() => boolean

toWellFormed() => string

Returns a string where all lone or out-of-order surrogates have been replaced by the Unicode replacement character (U+FFFD).

Type() => string

__@iterator@42() => StringIterator<string>

Iterator

Type() => StringIterator<string>

PropType

idstring

Typestring

keystring

Display string from {@link keySignature }.

Typestring

phaseLayerPhase

TypeLayerPhase

transitionLayerTransition

TypeLayerTransition

actionStatusLayerActionStatus

TypeLayerActionStatus

dismissingboolean

Typeboolean

endedboolean

Typeboolean

indexnumber

Typenumber

stackSizenumber

Typenumber

payload?unknown

Typeunknown

payloadTruncated?boolean

`true` when `payload` could not be JSON-cloned and was omitted.

Typeboolean

PropType

stackIdstring

Typestring

seqnumber

Typenumber

tsnumber

Typenumber

actionStackNotifyAction

TypeStackNotifyAction

activeLayerNotifyView[]

TypeLayerNotifyView[]

queuedLayerNotifyView[]

TypeLayerNotifyView[]

LayerState

Immutable snapshot of one layer, consumed by selectors.

PropType

idstring

Typestring

keyLayerKey

TypeLayerKey

payloadP

TypeP

data?D

TypeD

response?R

TypeR

error?E

TypeE

phaseLayerPhase

TypeLayerPhase

transitionLayerTransition

TypeLayerTransition

dismissingboolean

`true` while a user-intent dismiss is consulting blockers.

Typeboolean

actionStatusLayerActionStatus

TypeLayerActionStatus

endedboolean

Typeboolean

indexnumber

Typenumber

stackSizenumber

Typenumber

StackOptions

Per-stack options passed to ensureStack or LayerClientOptions.defaultStackOptions.

PropType

scope?

{
    strategy: "serial" | "parallel";
    /**
     * Serial only. `block` — keep `phase: "error"` until dismiss.
     * `advance` — remove the failed layer and drain the next queued open.
     * @default "block"
     */
    onLoadError?: SerialOnLoadError;
  }

Serial scope queues unmounted opens until the occupying layer leaves (`pending` / `active` / `error` for `onLoadError: "block"`).

Type

{
    strategy: "serial" | "parallel";
    /**
     * Serial only. `block` — keep `phase: "error"` until dismiss.
     * `advance` — remove the failed layer and drain the next queued open.
     * @default "block"
     */
    onLoadError?: SerialOnLoadError;
  }

Default{ strategy: "parallel" }

gcTime?number

Retains loaded data for same-key restoration.

Typenumber

Default0

dismissAllMode?DismissAllMode

TypeDismissAllMode

Default"skipBlocked"

PropType

toString() => string

Returns a string representation of a string.

Type() => string

charAt(pos: number) => string

Returns the character at the specified index.

Type(pos: number) => string

charCodeAt(index: number) => number

Returns the Unicode value of the character at the specified location.

Type(index: number) => number

concat(...strings: string[]) => string

Returns a string that contains the concatenation of two or more strings.

Type(...strings: string[]) => string

indexOf(searchString: string, position?: number | undefined) => number

Returns the position of the first occurrence of a substring, or -1 if it is not present.

Type(searchString: string, position?: number | undefined) => number

lastIndexOf(searchString: string, position?: number | undefined) => number

Returns the last occurrence of a substring in the string, or -1 if it is not present.

Type(searchString: string, position?: number | undefined) => number

localeCompare

{ (that: string): number; (that: string, locales?: string | string[] | undefined, options?: CollatorOptions | undefined): number; (that: string, locales?: LocalesArgument, options?: CollatorOptions | undefined): number; }

Determines whether two strings are equivalent in the current locale. Determines whether two strings are equivalent in the current or specified locale.

Type

{ (that: string): number; (that: string, locales?: string | string[] | undefined, options?: CollatorOptions | undefined): number; (that: string, locales?: LocalesArgument, options?: CollatorOptions | undefined): number; }

match

{ (regexp: string | RegExp): RegExpMatchArray | null; (matcher: { [Symbol.match](string: string): RegExpMatchArray | null; }): RegExpMatchArray | null; }

Type

{ (regexp: string | RegExp): RegExpMatchArray | null; (matcher: { [Symbol.match](string: string): RegExpMatchArray | null; }): RegExpMatchArray | null; }

replace

{ (searchValue: string | RegExp, replaceValue: string): string; (searchValue: string | RegExp, replacer: (substring: string, ...args: any[]) => string): string; (searchValue: { ...; }, replaceValue: string): string; (searchValue: { ...; }, replacer: (substring: string, ...args: any[]) => string): string; }

Type

{ (searchValue: string | RegExp, replaceValue: string): string; (searchValue: string | RegExp, replacer: (substring: string, ...args: any[]) => string): string; (searchValue: { ...; }, replaceValue: string): string; (searchValue: { ...; }, replacer: (substring: string, ...args: any[]) => string): string; }

search{ (regexp: string | RegExp): number; (searcher: { [Symbol.search](string: string): number; }): number; }

Finds the first substring match in a regular expression search.

Type{ (regexp: string | RegExp): number; (searcher: { [Symbol.search](string: string): number; }): number; }

slice(start?: number | undefined, end?: number | undefined) => string

Returns a section of a string.

Type(start?: number | undefined, end?: number | undefined) => string

split

{ (separator: string | RegExp, limit?: number | undefined): string[]; (splitter: { [Symbol.split](string: string, limit?: number | undefined): string[]; }, limit?: number | undefined): string[]; }

Split a string into substrings using the specified separator and return them as an array.

Type

{ (separator: string | RegExp, limit?: number | undefined): string[]; (splitter: { [Symbol.split](string: string, limit?: number | undefined): string[]; }, limit?: number | undefined): string[]; }