@qontinui/ui-bridge-native 0.6.12 → 0.6.14

package/dist/control/types.d.ts

@@ -4,6 +4,7 @@
  * Types for action execution and control operations.
  */
 import type { NativeActionRequest, NativeActionResponse, NativeFindRequest, NativeFindResponse, NativeElementState, WaitOptions } from '../core/types';
+import type { ParamValidationMode } from '../core/param-schema';
 /**
  * Extended action request with control-specific options
  */
@@ -24,6 +25,13 @@ export interface ControlActionRequest extends NativeActionRequest {
 export interface ControlActionResponse extends NativeActionResponse {
     /** Request ID for correlation */
     requestId?: string;
+    /**
+     * Machine-readable failure code, set only when an action failed for a
+     * reason with an honest code of its own — today only `NOT_SUPPORTED`
+     * (`scrollIntoView` with no usable declared scroll container). Absent on
+     * every other failure, which the HTTP handler reports as `ACTION_FAILED`.
+     */
+    code?: string;
     /** Retry count */
     retryCount?: number;
 }
@@ -37,6 +45,57 @@ export interface ComponentActionRequest {
     params?: Record<string, unknown>;
     /** Request ID for correlation */
     requestId?: string;
+    /**
+     * Abandon the action if it has not produced a result within this many
+     * milliseconds (plan `2026-08-20-ui-bridge-action-declaration-shape`,
+     * Phase 3). Omitted = no timeout.
+     *
+     * The wire-reachable half of cancellation: an `AbortSignal` cannot be
+     * JSON-serialized, so an HTTP caller has no other way to call off a hung
+     * handler. In-process callers should prefer the `{ signal }` option bag on
+     * `executeComponentAction`; whichever fires first wins.
+     *
+     * Abandonment does not depend on the handler observing its signal — the
+     * executor races the handler promise.
+     *
+     * **Validated and clamped at the executor**, so no wire caller reaches a
+     * timer unchecked: `0` abandons on the next tick; a negative, `NaN`,
+     * infinite or non-numeric value is REFUSED (the response is `success: false`
+     * naming `timeoutMs`); anything above 24h is clamped, because past 2^31-1
+     * `setTimeout` wraps negative and fires immediately. See
+     * `core/abortable.ts` `normalizeActionTimeoutMs`.
+     */
+    timeoutMs?: number;
+}
+/**
+ * Per-invocation options for `NativeActionExecutor.executeComponentAction`.
+ *
+ * In-process only — nothing here survives JSON serialization, which is why the
+ * wire-reachable timeout lives on {@link ComponentActionRequest} instead.
+ *
+ * Mirrors `@qontinui/ui-bridge` `ComponentActionInvokeOptions`; kept local
+ * because that package is an OPTIONAL peer dependency here (see
+ * `core/types.ts`).
+ */
+export interface ComponentActionInvokeOptions {
+    /**
+     * Cancellation signal owned by the caller. Aborting it abandons the
+     * invocation whether or not the handler observes the signal it is given.
+     */
+    signal?: AbortSignal;
+    /**
+     * What to do when `params` violate the action's declared `paramSchema`
+     * (Phase 2). Omitted = `getDefaultParamValidationMode()`, which starts at
+     * `'warn'`. Deliberately NOT on {@link ComponentActionRequest}: enforcement
+     * is a deployment's policy, not the validated caller's to switch off.
+     *
+     * NOTE: this tree's {@link ComponentActionResponse} carries no
+     * `failureDetails`, so an enforced rejection surfaces as a prose `error`
+     * naming each offending param — the same limitation Phase 3's cancellation
+     * path hit here. Giving the native channel structured failure details is a
+     * separate change.
+     */
+    paramValidation?: ParamValidationMode;
 }
 /**
  * Component action response
@@ -97,7 +156,7 @@ export interface NativeActionExecutor {
     /**
      * Execute a component action
      */
-    executeComponentAction(componentId: string, request: ComponentActionRequest): Promise<ComponentActionResponse>;
+    executeComponentAction(componentId: string, request: ComponentActionRequest, options?: ComponentActionInvokeOptions): Promise<ComponentActionResponse>;
     /**
      * Find elements
      */
@@ -168,6 +227,28 @@ export interface ScrollActionParams {
     /** Animate the scroll */
     animated?: boolean;
 }
+/**
+ * `scrollIntoView` action params.
+ *
+ * Vertical containers only. A container declared `horizontal` is answered
+ * `NOT_SUPPORTED` where the bridge can see the declaration (captured props, or
+ * a FlatList / SectionList instance), or where the element is measured laid
+ * out beyond the container's width — which also refuses an element wider than
+ * its vertical container, or one inside a nested horizontal carousel whose
+ * declared ancestor is the outer vertical feed; see `performScrollIntoView`.
+ */
+export interface ScrollIntoViewActionParams {
+    /**
+     * Gap (logical dp) left between the top of the scroll container's viewport
+     * and the element after scrolling. Finite and non-negative; default 16.
+     *
+     * Measured from the container's CONTENT origin, so a `paddingTop` on the
+     * ScrollView's own style, or an iOS `contentInset.top` / automatic
+     * safe-area inset, shifts where the element lands — add it here if the row
+     * must clear a header.
+     */
+    padding?: number;
+}
 /**
  * Swipe action params
  */

package/dist/control/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/control/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/control/types.ts"],"names":[],"mappings":"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"}

package/dist/core/abortable.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Abandonment primitive for action invocation.
+ *
+ * Plan `2026-08-20-ui-bridge-action-declaration-shape`, Phase 3.
+ *
+ * `ActionHandler`'s `options.signal` is **cooperative**: a well-behaved handler
+ * observes it and returns early. Cooperation cannot be enforced, and a handler
+ * that hangs is exactly the case cancellation exists for — so the executor
+ * never trusts the handler to observe the signal. It races the handler promise
+ * against the abort and reports the outcome either way.
+ *
+ * DUPLICATE OF `@qontinui/ui-bridge` `src/core/abortable.ts` — DELIBERATELY NOT
+ * AN IMPORT. `@qontinui/ui-bridge` is an OPTIONAL peerDependency of this
+ * package and is absent from `dependencies`, so a consumer may install
+ * `@qontinui/ui-bridge-native` alone; importing from it would resolve inside
+ * this monorepo and then fail for that consumer. See the same note on
+ * `core/types.ts` `ActionHandler`.
+ *
+ * KEEP IN SYNC with `@qontinui/ui-bridge` `src/core/abortable.ts` — including
+ * `MAX_ACTION_TIMEOUT_MS` and `normalizeActionTimeoutMs` below. The module has
+ * no imports and touches no DOM API — only `AbortController` and `setTimeout`,
+ * both present in React Native.
+ */
+/** Which of the two cancellation sources fired. */
+export type AbortReason = 'signal' | 'timeout';
+/**
+ * Ceiling applied to a caller-supplied `timeoutMs` — **24 hours**.
+ *
+ * `ComponentActionRequest.timeoutMs` crosses the wire, so it is attacker- (or
+ * typo-) controlled: an HTTP or WebSocket caller can put any JSON number in
+ * it and it would otherwise land in `setTimeout` unchecked. Two concrete
+ * hazards that ceiling closes:
+ *
+ * - **`setTimeout`'s 32-bit delay overflow.** Any delay above 2147483647ms
+ *   wraps to a *negative* 32-bit int in every major runtime and the timer
+ *   fires **immediately** — so `timeoutMs: 2147483648` ("about 25 days,
+ *   effectively no timeout") would abandon the action on the next tick, the
+ *   exact opposite of what the caller asked for. Clamping below that boundary
+ *   makes the semantics monotonic: a bigger number never means a shorter wait.
+ * - **A pinned timer per in-flight request.** Nothing here is unbounded work,
+ *   but a 100-year timeout is indistinguishable from "no timeout" while still
+ *   holding the handler's abandonment machinery alive, so there is nothing to
+ *   buy above a day.
+ *
+ * Clamping (rather than rejecting) is right at the top end because the intent
+ * is unambiguous — "effectively forever" — and the clamped value honours it as
+ * closely as the platform can. The malformed cases below are rejected instead,
+ * because there the intent is NOT recoverable.
+ */
+export declare const MAX_ACTION_TIMEOUT_MS = 86400000;
+/**
+ * Outcome of {@link normalizeActionTimeoutMs}. Discriminated on `ok` so a
+ * rejected value cannot be read as a timeout by accident.
+ */
+export type TimeoutNormalization = {
+    ok: true;
+    /** `undefined` ≡ no timeout. Always a finite integer in `[0, MAX]`. */
+    timeoutMs: number | undefined;
+    /** True iff the caller's value was above {@link MAX_ACTION_TIMEOUT_MS}. */
+    clamped: boolean;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Validate and clamp a wire-supplied `timeoutMs` before it can reach a timer.
+ *
+ * The policy, stated once so all three executors share it:
+ *
+ * | Supplied | Result | Why |
+ * |---|---|---|
+ * | absent / `null` | no timeout | the documented "omitted ⇒ no timeout" default |
+ * | `0` | abandon on the next tick | a coherent request ("don't let it run"), and what `setTimeout(…, 0)` already means |
+ * | `1 … MAX` | honoured, floored to an integer | fractional ms is not a thing a timer can express |
+ * | `> MAX` | clamped to {@link MAX_ACTION_TIMEOUT_MS} | see that constant — above 2^31-1 the platform timer silently inverts |
+ * | negative | **rejected** | `setTimeout` would treat it as `0`, i.e. a sign typo would abandon every call instantly and silently |
+ * | `NaN` / `±Infinity` | **rejected** | `setTimeout(NaN)` is `setTimeout(0)` — same silent-instant-abandon trap |
+ * | not a number (`"5000"`, `{}`, `true`) | **rejected** | JSON has numbers; a string here means the caller built the body wrong, and coercing would hide it |
+ *
+ * Rejection is loud on purpose: every rejected case is one where *ignoring*
+ * the field fails open (the action runs uncancellable) and *coercing* it fails
+ * closed at zero. Neither is what the caller asked for, and both are silent —
+ * which is the defect class this whole plan exists to remove.
+ */
+export declare function normalizeActionTimeoutMs(raw: unknown): TimeoutNormalization;
+/**
+ * Result of {@link runAbortable}. Discriminated on `aborted` so the caller
+ * cannot read `result` off an abandoned invocation.
+ */
+export type AbortableOutcome<T> = {
+    aborted: false;
+    result: T;
+} | {
+    aborted: true;
+    reason: AbortReason;
+};
+/** Cancellation sources composed by {@link runAbortable}. */
+export interface RunAbortableOptions {
+    /**
+     * An in-process caller's signal. Cannot cross the wire — that is what
+     * `timeoutMs` is for.
+     */
+    signal?: AbortSignal;
+    /**
+     * Milliseconds after which the invocation is abandoned. Serializable, so
+     * this is the arm an HTTP/WebSocket caller can actually use.
+     *
+     * Expected to have been through {@link normalizeActionTimeoutMs} already —
+     * every executor seam runs it, because this value arrives from the wire.
+     * The `Number.isFinite` / `>= 0` guard below is defence in depth for a
+     * direct in-process caller, and ignores anything malformed rather than
+     * letting it reach `setTimeout`.
+     */
+    timeoutMs?: number;
+}
+/**
+ * A fresh `AbortSignal` that is never aborted.
+ *
+ * `ActionHandlerOptions` promises the bag is *always* supplied, so a handler
+ * written the way the docs describe — `(params, { signal }) => …` — must never
+ * be called with `undefined` as its second argument. Not every invocation seam
+ * has a cancellation source to give it though: an ELEMENT custom action
+ * (`ControlActionRequest`) carries no `timeoutMs` and the executor holds no
+ * controller for it, so there is nothing that could ever abort. Those seams
+ * pass this instead of `undefined`, which keeps the destructure safe and keeps
+ * `signal.aborted` honestly `false`.
+ *
+ * **Fresh per call, deliberately.** A shared singleton would accumulate one
+ * listener per handler that calls `signal.addEventListener('abort', …)` and
+ * never releases them — a leak on a hot path. A `AbortController` allocation
+ * is a few bytes and custom element actions are not a hot path.
+ *
+ * When element actions grow a cancellation source, replace the call sites with
+ * a real `runAbortable` race — the handler contract does not change.
+ */
+export declare function inertAbortSignal(): AbortSignal;
+/**
+ * Invoke `invoke` with a derived `AbortSignal`, abandoning it if either the
+ * caller's signal aborts or `timeoutMs` elapses.
+ *
+ * - Returns `{ aborted: true, reason }` **without invoking at all** when the
+ *   caller's signal is already aborted.
+ * - Returns `{ aborted: false, result }` on normal completion.
+ * - **Rejects** if `invoke` throws/rejects while the race is still live, so a
+ *   genuine handler error stays distinguishable from a cancellation.
+ * - A rejection that arrives *after* an abort already won is swallowed:
+ *   `Promise.race` has a rejection handler attached, so the abandoned handler
+ *   cannot surface as an unhandled rejection.
+ */
+export declare function runAbortable<T>(invoke: (signal: AbortSignal) => T | Promise<T>, options?: RunAbortableOptions): Promise<AbortableOutcome<T>>;
+//# sourceMappingURL=abortable.d.ts.map

package/dist/core/abortable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abortable.d.ts","sourceRoot":"","sources":["../../src/core/abortable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,mDAAmD;AACnD,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,qBAAqB,WAAa,CAAC;AAEhD;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAC5B;IACE,EAAE,EAAE,IAAI,CAAC;IACT,uEAAuE;IACvE,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,2EAA2E;IAC3E,OAAO,EAAE,OAAO,CAAC;CAClB,GACD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAElC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,OAAO,GAAG,oBAAoB,CA0B3E;AAED;;;GAGG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAC1B;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,CAAC,CAAA;CAAE,GAC7B;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,WAAW,CAAA;CAAE,CAAC;AAE3C,6DAA6D;AAC7D,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,IAAI,WAAW,CAE9C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,MAAM,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAC/C,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAsD9B"}

package/dist/core/action-effect.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Action effect defaults for `@qontinui/ui-bridge-native`.
+ *
+ * Plan `2026-08-20-ui-bridge-action-declaration-shape`, Phase 4.
+ *
+ * `IREffect` ("read" | "write" | "destructive") has exactly one job: **exclude
+ * destructive actions from automatic walks.** Two sources feed it, in order:
+ *
+ *   1. `action.effect` — the author's explicit per-registration declaration.
+ *   2. `NATIVE_STANDARD_ACTION_EFFECTS[action.id]` — the static default below.
+ *
+ * **1 wins.** A static `press → write` map is wrong precisely on a delete
+ * control — guaranteed wrong in the one case the annotation exists for — and it
+ * fails *open*, so an unmarked destructive action gets walked.
+ *
+ * DUPLICATE of `@qontinui/ui-bridge` `src/core/action-effect.ts` +
+ * `src/native/core/action-effect.ts`, and deliberately not a re-export:
+ * `@qontinui/ui-bridge` is an OPTIONAL peer of this package, so a consumer may
+ * install `@qontinui/ui-bridge-native` alone. Same constraint that keeps
+ * `ActionHandler` / `ComponentAction` / `IREffect` duplicated in
+ * `./types` — see the long note there. KEEP IN SYNC.
+ */
+import type { IREffect, NativeStandardAction } from './types';
+/**
+ * Static default effect for each {@link NativeStandardAction} verb.
+ *
+ * Typed `Record<NativeStandardAction, IREffect>` so adding a verb without
+ * classifying it is a compile error — a *map* silently falling behind the
+ * *union* it describes is exactly the drift class this plan exists to fix.
+ *
+ * **No verb maps to `'destructive'`, and none ever should.** Destructiveness
+ * is a property of what a control does, not of the verb used to reach it;
+ * `'destructive'` is reachable only through an explicit `effect`.
+ *
+ * The non-obvious calls, justified:
+ *
+ * - **`longPress` → `read`.** The touch analogue of a right-click: it reveals
+ *   a context menu / selection affordance. Long-press is *associated* with
+ *   delete on mobile, but it only surfaces the option — the delete is a
+ *   separate press with its own effect.
+ * - **`swipe` → `write`.** Genuinely ambiguous, and it resolves the other way
+ *   from `longPress`: a swipe is sometimes just a scroll gesture (read), but
+ *   swipe-to-delete / swipe-to-archive **commits on the gesture itself**, with
+ *   nothing in the verb to tell the two apart. It takes the more cautious
+ *   classification, and a swipe-to-delete row must still declare
+ *   `effect: 'destructive'`.
+ * - **`focus` / `blur` → `read`.** They move focus, which is UI state, not
+ *   persistent state.
+ * - **`scrollIntoView` → `read`.** It moves the declared scroll container's
+ *   content offset (UI state) and fires no element handler.
+ *
+ * Note this union carries `click`, `setValue` and `scrollIntoView` that the
+ * `@qontinui/ui-bridge` `native/core` copy does not — a real divergence
+ * between the two native unions, not a sync error.
+ */
+export declare const NATIVE_STANDARD_ACTION_EFFECTS: Record<NativeStandardAction, IREffect>;
+/**
+ * The static default for a native action id, or `undefined` when the id is not
+ * one of the native standard verbs (the normal case for a `ComponentAction`,
+ * whose ids are free-form).
+ *
+ * `undefined` means **unknown**, not "safe" — a caller that walks unknown
+ * actions is choosing to fail open and should say so.
+ */
+export declare function nativeStandardActionEffect(actionId: string): IREffect | undefined;
+/**
+ * Resolve the effective annotation for a declared action: **explicit
+ * declaration first, static verb map second.**
+ */
+export declare function resolveActionEffect(action: {
+    id: string;
+    effect?: IREffect;
+}): IREffect | undefined;
+//# sourceMappingURL=action-effect.d.ts.map

package/dist/core/action-effect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-effect.d.ts","sourceRoot":"","sources":["../../src/core/action-effect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,8BAA8B,EAAE,MAAM,CAAC,oBAAoB,EAAE,QAAQ,CAiBjF,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAIjF;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAC1C,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,EAAE,QAAQ,CAAC;CACnB,GAAG,QAAQ,GAAG,SAAS,CAEvB"}

package/dist/core/element-actions.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The ONE wire projection for an element's custom actions.
+ *
+ * Plan `2026-09-04-effect-calculus-joins-the-component-action-registry`,
+ * Design decision 4 step 3.
+ *
+ * DUPLICATE of `@qontinui/ui-bridge` `src/core/element-actions.ts`, for the same
+ * reason the types beside it are duplicated: this package must not import from
+ * `@qontinui/ui-bridge` (an optional peer). KEEP IN SYNC — a divergence here is
+ * a divergence in what the two channels advertise about the same annotation.
+ *
+ * ---------------------------------------------------------------------------
+ * WHAT THIS DOES NOT DO: default the effect
+ * ---------------------------------------------------------------------------
+ *
+ * `effect` is carried through **verbatim and undefaulted**. An action whose
+ * author declared nothing is emitted with `effect` absent, never with a
+ * manufactured `'read'` — a default rendered as a declaration is a fail-open lie
+ * on exactly the surface the annotation exists to protect. **Absent means
+ * UNCLASSIFIED, not safe**, which is what served policy `operating-rules`
+ * `what-makes-an-action-destructive` requires of an unestablished effect.
+ */
+import type { CustomAction, SerializedElementAction } from './types';
+type ProjectableCustomActions = Record<string, Pick<CustomAction, 'label' | 'description' | 'effect'> | undefined>;
+/**
+ * Project `RegisteredNativeElement.customActions` to its wire shape.
+ *
+ * - `undefined` in → `undefined` out (an element with no custom actions must not
+ *   start emitting `[]`; `JSON.stringify` keeps `[]` and drops `undefined`).
+ * - An empty record in → `[]` out, matching what `Object.keys({})` gave before.
+ *
+ * The emitted `id` is the RECORD KEY — the executor dispatches by key, so the
+ * key is the name a caller must send. Nullish entries are skipped: they carry no
+ * handler, so advertising them would advertise a capability that does not exist.
+ */
+export declare function serializeElementCustomActions(customActions: ProjectableCustomActions | undefined): SerializedElementAction[] | undefined;
+export {};
+//# sourceMappingURL=element-actions.d.ts.map

package/dist/core/element-actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-actions.d.ts","sourceRoot":"","sources":["../../src/core/element-actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAErE,KAAK,wBAAwB,GAAG,MAAM,CACpC,MAAM,EACN,IAAI,CAAC,YAAY,EAAE,OAAO,GAAG,aAAa,GAAG,QAAQ,CAAC,GAAG,SAAS,CACnE,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAAgB,6BAA6B,CAC3C,aAAa,EAAE,wBAAwB,GAAG,SAAS,GAClD,uBAAuB,EAAE,GAAG,SAAS,CAcvC"}

package/dist/core/index.d.ts

@@ -4,6 +4,10 @@
  * Core types and registry for React Native.
  */
 export * from './types';
+export * from './abortable';
+export * from './param-schema';
+export * from './action-effect';
 export * from './registry';
 export * from './element-identifier';
+export { serializeElementCustomActions } from './element-actions';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,SAAS,CAAC;AAGxB,cAAc,aAAa,CAAC;AAG5B,cAAc,gBAAgB,CAAC;AAG/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,sBAAsB,CAAC;AAGrC,OAAO,EAAE,6BAA6B,EAAE,MAAM,mBAAmB,CAAC"}