@declarion/react 0.60.0 → 0.63.0

package/dist-lib/embed/embed-history.d.ts

@@ -1,19 +0,0 @@
-/** The React Router navigation action, as returned by `useNavigationType()`. */
-export type EmbedNavAction = "PUSH" | "POP" | "REPLACE";
-interface EmbedHistoryState {
-    /** In-frame history depth: 0 at the entry screen, +1 per in-frame drill. */
-    readonly depth: number;
-    /** When true, the NEXT applied navigation is treated as a fresh root (depth
-     *  resets to 0) regardless of its action. Set by a host-driven `navigate`. */
-    readonly nextIsRoot: boolean;
-    /** Apply one navigation's action to the depth. PUSH +1, POP -1 (floored at
-     *  0), REPLACE unchanged; a pending root marker forces 0 and clears itself.
-     *  Called once per navigation by the tracker. */
-    applyNavigation: (action: EmbedNavAction) => void;
-    /** Mark the next applied navigation as a fresh root (host-driven `navigate`). */
-    markRoot: () => void;
-    /** Reset to the entry screen (embed re-bootstrap). */
-    reset: () => void;
-}
-export declare const useEmbedHistoryStore: import("zustand").UseBoundStore<import("zustand").StoreApi<EmbedHistoryState>>;
-export {};

package/dist-lib/embed/embed-nav-guard.d.ts

@@ -1,20 +0,0 @@
-interface EmbedNavGuardState {
-    /**
-     * The deferred navigation, or null when nothing is pending. Set by
-     * `useEmbedScreenNavigate` when it intercepts a dirty navigation; consumed
-     * by `EmbedUnsavedGuard`.
-     */
-    readonly pendingNavigation: (() => void) | null;
-    /** Defer a navigation behind the unsaved-changes confirm dialog. */
-    requestNavigation: (run: () => void) => void;
-    /** Run the deferred navigation (the user chose discard + leave). */
-    confirmNavigation: () => void;
-    /** Drop the deferred navigation (the user chose to stay). */
-    cancelNavigation: () => void;
-}
-/**
- * The embed-mode pending-navigation store. A non-null `pendingNavigation`
- * means a dirty navigation is waiting on the confirm dialog.
- */
-export declare const useEmbedNavGuardStore: import("zustand").UseBoundStore<import("zustand").StoreApi<EmbedNavGuardState>>;
-export {};

package/dist-lib/embed/file-src.d.ts

@@ -1,63 +0,0 @@
-/**
- * The kind of URL `resolveEmbedFileSrc` produced, so the caller knows whether
- * an object URL was created and must be revoked.
- *
- * - `direct`: a presigned (non-proxy) URL or a `data:` URL. Nothing to revoke.
- * - `blob`: a `blob:` object URL created from fetched bytes. The caller MUST
- *   call `URL.revokeObjectURL` on it when the file changes or the component
- *   unmounts.
- */
-export type EmbedFileSrcKind = "direct" | "blob";
-/** The resolved source for a file, plus the cleanup obligation. */
-export interface EmbedFileSrc {
-    /** The URL to assign to `<img src>` / pass to `window.open`. */
-    readonly url: string;
-    /** Whether `url` is a revocable `blob:` object URL. */
-    readonly kind: EmbedFileSrcKind;
-}
-/**
- * What to resolve for a given file: the primary file, a named derivation
- * (thumbnail), or the download (attachment-disposition) form.
- *
- * - `preview`  -> `/api/files/{id}/url`, inline disposition.
- * - `download` -> `/api/files/{id}/url`; when the result is a proxy URL the
- *   `disposition=attachment` query is preserved so the proxy stream forces a
- *   download. A presigned URL already carries its disposition.
- * - a derivation key string -> `/api/files/{id}/derived/{key}/url`.
- */
-export type EmbedFileVariant = "preview" | "download" | {
-    derivation: string;
-};
-/**
- * A 202 `{ status: "generating" }` from the derived endpoint - the async
- * generator has not produced the derivation yet. Thrown so the React hook can
- * fall back to the primary file rather than rendering broken media.
- */
-export declare class DerivationPendingError extends Error {
-    readonly fileId: string;
-    readonly key: string;
-    constructor(fileId: string, key: string);
-}
-/**
- * Resolve a file (or one of its derivations) into a URL a native element can
- * load under Bearer-only embed auth.
- *
- * Step 1: call the file URL endpoint WITH the Bearer header and
- *         `credentials: "omit"`. A 202 from the derived endpoint throws
- *         `DerivationPendingError`.
- * Step 2: when `proxy: false`, the endpoint returned a presigned URL - return
- *         it directly (`kind: "direct"`), nothing to revoke.
- * Step 3: when `proxy: true`, fetch the proxy bytes WITH the Bearer header,
- *         wrap them in a `blob:` object URL, and return it (`kind: "blob"`).
- *         The caller owns revocation.
- *
- * Both requests go through `embedAuthedFetch`, so a missing/stale token is
- * waited out and a 401 is retried once with a freshly minted token.
- *
- * `signal` aborts both the metadata request and the bytes fetch, so a file
- * change or unmount mid-flight cancels the in-flight work cleanly.
- *
- * Throws when not in embed token mode - callers outside embed mode MUST use
- * the static URL path instead and never reach this function.
- */
-export declare function resolveEmbedFileSrc(fileId: string, variant: EmbedFileVariant, signal?: AbortSignal): Promise<EmbedFileSrc>;

package/dist-lib/embed/handshake.d.ts

@@ -1,57 +0,0 @@
-import { type EmbedSetTokenPayload, type EmbedMessage, type EmbedNavigatePayload, type EmbedSetThemePayload } from "./protocol";
-/**
- * The classification of an inbound `message` event after validation.
- *
- * - `valid`: a trusted, shape-correct, version-matched embed frame. `message`
- *   is the typed envelope.
- * - `protocol-mismatch`: origin + source are trusted, but the `protocol`
- *   version differs. The caller logs a warning; the frame is not acted on.
- * - `rejected`: the frame is not a trusted embed frame (wrong origin,
- *   missing/foreign `source`, malformed envelope). The caller drops it
- *   silently.
- */
-export type InboundClassification = {
-    kind: "valid";
-    message: EmbedMessage;
-} | {
-    kind: "protocol-mismatch";
-    received: unknown;
-} | {
-    kind: "rejected";
-};
-/**
- * Validate and classify an inbound `message` event against the trusted
- * `parentOrigin`.
- *
- * Returns `rejected` for anything that is not a trusted embed frame - the
- * caller drops those with no logging. Returns `protocol-mismatch` when the
- * frame is trusted but on a different protocol version. Returns `valid` with
- * the typed envelope otherwise.
- *
- * `parentOrigin` MUST be a concrete origin; the inbound listener is not
- * installed at all when it is null, so this function assumes a real value.
- */
-export declare function classifyInboundMessage(event: MessageEvent, parentOrigin: string): InboundClassification;
-/**
- * The set of inbound-message callbacks the embed bootstrap supplies. Each is
- * invoked only for a `valid`, version-matched frame of the matching type.
- */
-export interface InboundHandlers {
-    /** A host `auth` frame: store/refresh the embed token. */
-    onAuth: (payload: EmbedSetTokenPayload) => void;
-    /** A host `navigate` frame: drive the iframe to a screen route. */
-    onNavigate: (payload: EmbedNavigatePayload) => void;
-    /** A host `theme` frame: switch the iframe theme at runtime. */
-    onTheme: (payload: EmbedSetThemePayload) => void;
-}
-/**
- * Build the `message` event listener for the inbound embed protocol.
- *
- * The returned listener validates every event via `classifyInboundMessage`,
- * drops untrusted frames silently, warns once on a protocol mismatch, and
- * dispatches a valid frame to the matching handler.
- *
- * Returned as a standalone function (not auto-attached) so the React
- * bootstrap owns `addEventListener` / `removeEventListener` lifecycle.
- */
-export declare function createInboundMessageListener(parentOrigin: string, handlers: InboundHandlers): (event: MessageEvent) => void;

package/dist-lib/embed/index.d.ts

@@ -1,19 +0,0 @@
-export { EmbedProvider, useEmbed, toEmbedContextValue, type EmbedContextValue, } from "./EmbedContext";
-export { parseEmbedParams, parseExactOrigin, appendEmbedParams, DEFAULT_NAVIGATION_MODE, EMBED_PARAM_EMBED, EMBED_PARAM_PARENT_ORIGIN, EMBED_PARAM_THEME, EMBED_PARAM_NAV, EMBED_PARAM_KEYS, type EmbedParams, type EmbedTheme, type EmbedNavigationMode, } from "./params";
-export { applyEmbedTheme, applyEmbedThemeFromQuery, applyEmbedThemeFromLocation, } from "./theme";
-export { initEmbedTokenMode, isEmbedTokenMode, getEmbedToken, getEmbedParentOrigin, setEmbedToken, clearEmbedToken, awaitEmbedToken, } from "./token";
-export { resolveEmbedFileSrc, DerivationPendingError, type EmbedFileSrc, type EmbedFileSrcKind, type EmbedFileVariant, } from "./file-src";
-export { classifyInboundMessage, createInboundMessageListener, type InboundClassification, type InboundHandlers, } from "./handshake";
-export { EmbedAuthBootstrap } from "./EmbedAuthBootstrap";
-export { EmbedResizeReporter } from "./EmbedResizeReporter";
-export { EmbedDirtyReporter } from "./EmbedDirtyReporter";
-export { EMBED_MESSAGE_SOURCE, EMBED_PROTOCOL_VERSION, EMBED_MESSAGE_TYPES, postToParent, type EmbedMessageType, type EmbedMessage, type EmbedMessagePayloadMap, type EmbedReadyPayload, type EmbedSetTokenPayload, type EmbedTokenExpiredPayload, type EmbedReloadRequiredPayload, type EmbedResizedPayload, type EmbedNavigationPayload, type EmbedDirtyChangedPayload, type EmbedNavigationFailedPayload, type EmbedNavigatePayload, type EmbedSetThemePayload, } from "./protocol";
-export { resolveEmbedNavigation, resolveEmbedNavigationPayload, } from "./screen-location";
-export type { EmbedNavigationResolution } from "./screen-location";
-export { useEmbedNavigate, useEmbedScreenNavigate, useEmbedScreenBack, useEmbedNavigationFailed, } from "./useEmbedNavigate";
-export { useEmbedHistoryStore, type EmbedNavAction } from "./embed-history";
-export { EmbedHistoryTracker } from "./EmbedHistoryTracker";
-export { useGlobalLinkInterceptor, interceptedNavigationTarget, interceptedProgrammaticTarget, NATIVE_LINK_ATTR, } from "./useGlobalLinkInterceptor";
-export { EmbedLocationReporter } from "./EmbedLocationReporter";
-export { useEmbedDirtyStore, useReportEmbedDirty } from "./embed-dirty";
-export { EmbedUnsavedGuard } from "./EmbedUnsavedGuard";

package/dist-lib/embed/params.d.ts

@@ -1,75 +0,0 @@
-/** Theme hint carried on the `theme` query param. */
-export type EmbedTheme = "light" | "dark";
-/**
- * Navigation mode carried on the `nav` query param.
- *
- * - `self`: the iframe navigates internally between Declarion screen routes.
- * - `delegated`: the host owns navigation; the iframe stays put and only
- *   emits intent. Defaults to `self` (see DEFAULT_NAVIGATION_MODE).
- */
-export type EmbedNavigationMode = "self" | "delegated";
-/** Default navigation mode when `nav` is absent or invalid. */
-export declare const DEFAULT_NAVIGATION_MODE: EmbedNavigationMode;
-/** Query-param names that make up the embed contract. */
-export declare const EMBED_PARAM_EMBED = "embed";
-export declare const EMBED_PARAM_PARENT_ORIGIN = "parent_origin";
-export declare const EMBED_PARAM_THEME = "theme";
-export declare const EMBED_PARAM_NAV = "nav";
-/**
- * The four embed query params, in URL-stable order. `appendEmbedParams`
- * iterates this list so preserved params always appear in the same order.
- */
-export declare const EMBED_PARAM_KEYS: readonly ["embed", "parent_origin", "theme", "nav"];
-/**
- * Parsed, validated embed context.
- *
- * `enabled` is true ONLY when `embed=1` is explicitly present. Being inside
- * an iframe (frame detection) MUST NOT enable embed mode - a Declarion app
- * framed without `embed=1` still renders the full shell.
- */
-export interface EmbedParams {
-    /** True only when `embed=1` is explicitly present in the query string. */
-    readonly enabled: boolean;
-    /**
-     * Exact parent origin from `parent_origin`, validated as a well-formed
-     * origin (scheme + host + optional port, no path/query/fragment). `null`
-     * when absent, malformed, or carrying anything beyond an origin.
-     */
-    readonly parentOrigin: string | null;
-    /** Theme hint from `theme`; any value other than light/dark drops to null. */
-    readonly theme: EmbedTheme | null;
-    /** Navigation mode from `nav`; invalid or absent values fall back to `self`. */
-    readonly navigationMode: EmbedNavigationMode;
-}
-/**
- * Validate that `raw` is exactly a well-formed origin: `scheme://host[:port]`
- * with no path, query, fragment, or credentials. `new URL(raw).origin`
- * normalizes the input; requiring `raw === url.origin` rejects any extra
- * structure (`https://h.com/`, `https://h.com/path`, `https://h.com?x=1`).
- *
- * Returns the origin on success, `null` otherwise.
- */
-export declare function parseExactOrigin(raw: string | null | undefined): string | null;
-/**
- * Parse the embed contract out of a query string.
- *
- * Accepts a raw query string (`window.location.search`) or a
- * `URLSearchParams`. Pure and deterministic - the single parser used by
- * both the React provider and the pre-paint theme bootstrap.
- */
-export declare function parseEmbedParams(query: string | URLSearchParams): EmbedParams;
-/**
- * Given an internal Declarion URL or path, return it with the currently-set
- * embed params (`embed`, `parent_origin`, `theme`, `nav`) preserved on its
- * query string. Only params present in `current` are appended; absent ones
- * are not invented.
- *
- * Used by internal navigation so a full iframe reload of the navigated URL
- * still resolves to shellless embed mode. When embed mode is off, the input
- * is returned unchanged.
- *
- * The input may be an absolute URL or a root-relative path. A relative path
- * is resolved against a placeholder base purely so `URLSearchParams` can be
- * manipulated; the returned string keeps the input's relative shape.
- */
-export declare function appendEmbedParams(url: string, current: EmbedParams): string;

package/dist-lib/embed/protocol.d.ts

@@ -1,165 +0,0 @@
-/**
- * The `source` discriminator stamped on every embed frame. The host SDK and
- * the iframe both filter inbound messages on this value so unrelated
- * `postMessage` traffic (browser extensions, other widgets) is ignored.
- */
-export declare const EMBED_MESSAGE_SOURCE: "declarion-embed";
-/**
- * The protocol version. Bumped only on a breaking envelope/payload change.
- * The host SDK warns when its version and the iframe's version differ.
- */
-export declare const EMBED_PROTOCOL_VERSION: 1;
-/**
- * Every protocol message `type`. The object key is the camelCase name used in
- * code; the value is the on-wire string. Events (iframe -> host) are past
- * tense; commands (host -> iframe) are imperative - see the naming contract
- * at the top of this file.
- */
-export declare const EMBED_MESSAGE_TYPES: {
-    /** iframe -> host: SDK mounted, requests the first token. */
-    readonly ready: "ready";
-    /** host -> iframe: deliver or refresh the embed token. */
-    readonly setToken: "set-token";
-    /** iframe -> host: token rejected or near expiry. */
-    readonly tokenExpired: "token-expired";
-    /** iframe -> host: the iframe must be reloaded. */
-    readonly reloadRequired: "reload-required";
-    /** iframe -> host: embed content height changed. */
-    readonly resized: "resized";
-    /** iframe -> host: `self` mode internal navigation happened. */
-    readonly navigated: "navigated";
-    /** iframe -> host: `delegated` mode navigation requested, iframe stayed. */
-    readonly navigationRequested: "navigation-requested";
-    /** iframe -> host: the embedded screen's unsaved-edits state flipped. */
-    readonly dirtyChanged: "dirty-changed";
-    /** iframe -> host: an in-frame navigation could not be handled (unknown
-     *  route, or a 404 the host should recover from). The iframe stayed put. */
-    readonly navigationFailed: "navigation-failed";
-    /** host -> iframe: drive the iframe to a screen (deep-linking). */
-    readonly navigate: "navigate";
-    /** host -> iframe: runtime theme switch. */
-    readonly setTheme: "set-theme";
-};
-/** The union of all on-wire message `type` strings. */
-export type EmbedMessageType = (typeof EMBED_MESSAGE_TYPES)[keyof typeof EMBED_MESSAGE_TYPES];
-/** `ready` payload: empty - the frame itself is the signal. */
-export type EmbedReadyPayload = Record<string, never>;
-/** `set-token` payload: the embed token and its absolute expiry. */
-export interface EmbedSetTokenPayload {
-    /** The scoped, refresh-less embed JWT. */
-    readonly token: string;
-    /** RFC 3339 expiry timestamp of the token. */
-    readonly expires_at: string;
-}
-/** `token-expired` payload: empty - the host re-mints via `getToken`. */
-export type EmbedTokenExpiredPayload = Record<string, never>;
-/** `reload-required` payload: a human-readable reason for the reload. */
-export interface EmbedReloadRequiredPayload {
-    /** Why the iframe must be reloaded (asset drift, terminal auth failure). */
-    readonly reason: string;
-}
-/** `resized` payload: the measured content height in CSS pixels. */
-export interface EmbedResizedPayload {
-    /** Content height in CSS pixels. */
-    readonly height: number;
-}
-/**
- * `navigated` / `navigation-requested` payload: the screen route and, when
- * resolvable, the matched screen code, bound entity code, and record id.
- *
- * `screenCode`, `entity`, and `recordId` are optional: an unregistered path
- * resolves to none of them, a `custom` screen has no entity, and a list route
- * has no record id. The host needs `screenCode` to mint a scoped embed token
- * for the target screen when it executes a `delegated` navigation intent.
- */
-export interface EmbedNavigationPayload {
-    /** The Declarion screen route path the navigation targets. */
-    readonly route: string;
-    /**
-     * The matched screen's code (its key in the schema screen map), when a
-     * registered screen owns the route. Absent for an unresolved path. The host
-     * passes this as `screen_code` to `auth.create_embed_session`.
-     */
-    readonly screenCode?: string;
-    /** The bound entity code, when the route resolves to one. */
-    readonly entity?: string;
-    /** The record id, when the route is a detail route with an id. */
-    readonly recordId?: string;
-}
-/**
- * `dirty-changed` payload: whether the embedded screen currently has unsaved
- * edits. The host tracks this so it can guard its own navigation (its menu,
- * a host-initiated `navigate`) before moving the iframe away from a dirty
- * screen - the iframe never pops a dialog for host-driven navigation.
- */
-export interface EmbedDirtyChangedPayload {
-    /** True when the embedded screen has unsaved edits. */
-    readonly dirty: boolean;
-}
-/**
- * `navigation-failed` payload: an in-frame navigation the iframe refused or
- * could not resolve. The iframe stayed put; the host owns recovery (show its
- * own not-found, reset its sidebar selection, etc.).
- *
- * `reason` is a closed set, each with a real producer: `not_found` from the
- * embedded 404 catch-all, `unresolved` from the navigation chokepoint when the
- * target route matches no registered screen.
- */
-export interface EmbedNavigationFailedPayload {
-    /** The route that could not be navigated to. */
-    readonly route: string;
-    /** Why it failed. */
-    readonly reason: "not_found" | "unresolved";
-}
-/** `navigate` payload: the route the host drives the iframe to. */
-export interface EmbedNavigatePayload {
-    /** The Declarion screen route the host wants opened. */
-    readonly route: string;
-}
-/** `set-theme` payload: the theme the host switches the iframe to. */
-export interface EmbedSetThemePayload {
-    /** The requested theme. */
-    readonly theme: "light" | "dark";
-}
-/**
- * Maps each message type to its payload shape. Used to type `postToParent`
- * so the payload argument is checked against the message type.
- */
-export interface EmbedMessagePayloadMap {
-    [EMBED_MESSAGE_TYPES.ready]: EmbedReadyPayload;
-    [EMBED_MESSAGE_TYPES.setToken]: EmbedSetTokenPayload;
-    [EMBED_MESSAGE_TYPES.tokenExpired]: EmbedTokenExpiredPayload;
-    [EMBED_MESSAGE_TYPES.reloadRequired]: EmbedReloadRequiredPayload;
-    [EMBED_MESSAGE_TYPES.resized]: EmbedResizedPayload;
-    [EMBED_MESSAGE_TYPES.navigated]: EmbedNavigationPayload;
-    [EMBED_MESSAGE_TYPES.navigationRequested]: EmbedNavigationPayload;
-    [EMBED_MESSAGE_TYPES.dirtyChanged]: EmbedDirtyChangedPayload;
-    [EMBED_MESSAGE_TYPES.navigationFailed]: EmbedNavigationFailedPayload;
-    [EMBED_MESSAGE_TYPES.navigate]: EmbedNavigatePayload;
-    [EMBED_MESSAGE_TYPES.setTheme]: EmbedSetThemePayload;
-}
-/**
- * The wire envelope. Every embed frame is exactly this shape: a fixed
- * `source` + `protocol` pair, a discriminating `type`, and the typed
- * `payload` for that type.
- */
-export interface EmbedMessage<T extends EmbedMessageType = EmbedMessageType> {
-    readonly source: typeof EMBED_MESSAGE_SOURCE;
-    readonly protocol: typeof EMBED_PROTOCOL_VERSION;
-    readonly type: T;
-    readonly payload: EmbedMessagePayloadMap[T];
-}
-/**
- * Post an enveloped embed message to the host page.
- *
- * Targets the EXACT `parentOrigin` - never `"*"` - so a malicious page that
- * re-frames the iframe cannot intercept auth or navigation frames.
- *
- * No-op (returns false) when:
- *  - `parentOrigin` is null or empty (no trusted origin to target), or
- *  - the document is not framed (`window.parent === window`), or
- *  - there is no `window` (SSR / unit environment without a DOM).
- *
- * Returns true when a message was posted.
- */
-export declare function postToParent<T extends EmbedMessageType>(parentOrigin: string | null, type: T, payload: EmbedMessagePayloadMap[T]): boolean;

package/dist-lib/embed/screen-location.d.ts

@@ -1,50 +0,0 @@
-import type { EmbedNavigationPayload } from "./protocol";
-import type { Screen } from "../types/schema.d.ts";
-/**
- * The result of resolving a router pathname against the screen schema.
- *
- * `matched` is the load-bearing flag for the navigation chokepoint: when a
- * registered screen owns the path it is `true` and `screenCode` names that
- * screen; when no screen owns the path it is `false` (the chokepoint then
- * refuses an embed navigation and emits `navigation-failed`). `payload` is
- * always present - it carries the matched screen route (or the raw pathname
- * when unmatched) for the `navigated` / `navigation-requested` messages.
- */
-export interface EmbedNavigationResolution {
-    /** True when a registered screen route owns this pathname. */
-    readonly matched: boolean;
-    /** The matched screen's code (its key in `screens`), when matched. */
-    readonly screenCode?: string;
-    /** The matched screen's `type` (`list` / `detail` / `custom` / ...), when
-     *  matched. Matched-screen metadata the host may use (e.g. to label or
-     *  classify a navigation it observes). */
-    readonly screenType?: string;
-    /** The navigation payload to emit (route always set; ids when resolvable). */
-    readonly payload: EmbedNavigationPayload;
-}
-/**
- * Resolve a router pathname against the screen schema, with match status.
- *
- * Matches the pathname against every registered screen route. An exact
- * (wildcard-free) route wins over a `:param` route, mirroring
- * `screenTitleForPath`, so `/cases` resolves to the list screen even though
- * the detail route `/cases/:id` also shares the prefix.
- *
- * - `matched` is true only when a registered screen owns the path.
- * - `screenCode` is the matched screen's map key (so the host can mint a
- *   scoped token for it).
- * - `payload.route` is the matched screen's own route pattern, or the raw
- *   pathname when no screen owns it (a route always exists in the payload).
- * - `payload.entity` is the matched screen's bound entity code, when it has one.
- * - `payload.recordId` is the last path segment for a detail (`:param`) route,
- *   when that segment is present and non-empty.
- *
- * `screens` may be undefined (schema not yet loaded); the result is then
- * `matched: false` with the raw pathname as `payload.route`.
- */
-export declare function resolveEmbedNavigation(pathname: string, screens: Record<string, Screen> | undefined): EmbedNavigationResolution;
-/**
- * Convenience wrapper returning just the payload, for the `navigated` and
- * `navigation-requested` emitters that do not need the match status.
- */
-export declare function resolveEmbedNavigationPayload(pathname: string, screens: Record<string, Screen> | undefined): EmbedNavigationPayload;

package/dist-lib/embed/theme.d.ts

@@ -1,34 +0,0 @@
-import { type EmbedTheme } from "./params";
-/**
- * Apply an embed theme to <html> immediately, WITHOUT persisting it.
- *
- * The single theme-apply path for embed mode: the pre-paint URL bootstrap
- * (`applyEmbedThemeFromQuery`) and the runtime `theme` postMessage handler
- * both route through here, so they can never diverge.
- *
- * `applyPreferences` is the single writer of <html> preference attributes; it
- * keeps accent / density / etc. intact. The store slice is then set directly
- * (not via `setMany`) so later reads stay consistent WITHOUT writing
- * localStorage - the embed color scheme is a host-supplied, ephemeral hint,
- * not a user choice.
- */
-export declare function applyEmbedTheme(theme: EmbedTheme): void;
-/**
- * Read the embed `theme` param from the given query string and, when it is a
- * valid `light`/`dark` value under an active `embed=1`, apply it to
- * <html> immediately.
- *
- * Returns true when an embed theme was applied, false otherwise.
- *
- * Apply path: routes through `applyEmbedTheme`, which writes `data-color-scheme` and
- * updates the preferences store; nothing is persisted.
- */
-export declare function applyEmbedThemeFromQuery(query: string | URLSearchParams): boolean;
-/**
- * Apply the embed theme from `window.location.search` at module load.
- *
- * Called once from the embed barrel so importing the embed entry point is
- * enough to get pre-paint theming, exactly like the preferences module's
- * own module-load `applyPreferences(initial)`.
- */
-export declare function applyEmbedThemeFromLocation(): boolean;

package/dist-lib/embed/token.d.ts

@@ -1,57 +0,0 @@
-/**
- * Activate embed token mode. Called once at bootstrap by the embed auth
- * handshake. `parentOrigin` is the exact host origin that `token-expired`
- * frames are emitted to.
- *
- * Idempotent: re-activation only refreshes the parent origin.
- */
-export declare function initEmbedTokenMode(parentOrigin: string | null): void;
-/**
- * True when embed token mode is active. Transports branch on this to switch
- * from the cookie path to the Bearer path. False everywhere outside an
- * embed iframe, so the cookie path stays byte-equivalent to today.
- */
-export declare function isEmbedTokenMode(): boolean;
-/** The current embed token string, or null before the first `auth` frame. */
-export declare function getEmbedToken(): string | null;
-/**
- * The exact parent origin embed frames are emitted to, or null before
- * `initEmbedTokenMode` runs. Used by transports outside this module (e.g.
- * the version probe) that need to post a frame to the host.
- */
-export declare function getEmbedParentOrigin(): string | null;
-/**
- * Store a token delivered by the host's `auth` frame.
- *
- * Resolves any in-flight `awaitEmbedToken()` wait so every transport that
- * was blocked on a fresh token unblocks at once. A malformed payload
- * (missing token, unparseable expiry) is ignored - the wait stays pending
- * until a well-formed frame arrives or the timeout fires.
- */
-export declare function setEmbedToken(payload: {
-    token: string;
-    expires_at: string;
-}): void;
-/**
- * Clear the held token. Used when a terminal failure makes the current
- * token unusable; the next transport call will await a fresh one.
- */
-export declare function clearEmbedToken(): void;
-/**
- * Return a usable embed token, requesting a fresh one from the host when
- * needed.
- *
- * SINGLE-FLIGHT: when the held token is still usable it resolves
- * immediately. When the token is missing or stale, it emits exactly one
- * `token-expired` frame to the host and waits for the next `auth` frame.
- * Concurrent callers during that window share the one in-flight wait - the
- * `token-expired` frame is emitted once, not once per caller.
- *
- * The wait is bounded by `TOKEN_WAIT_TIMEOUT_MS`; on timeout the promise
- * rejects so the transport caller fails loudly instead of hanging.
- */
-export declare function awaitEmbedToken(): Promise<string>;
-/**
- * Test-only: reset all module state. Not exposed via package exports.
- */
-export declare function __resetEmbedTokenForTests(): void;

package/dist-lib/embed/useEmbedNavigate.d.ts

@@ -1,48 +0,0 @@
-import { type NavigateOptions } from "react-router";
-import { type EmbedNavigationFailedPayload } from "./protocol";
-/**
- * The shared embed navigation policy, decoupled from React Router's hook.
- *
- * `rawNavigate` is the underlying navigator (`useNavigate()`'s return value
- * for `useEmbedNavigate`, the same for `useTabNavigate`). The returned
- * `screenNavigate` applies the embed branch and reports whether it actually
- * navigated:
- *
- *   - returns `false` in `delegated` embed mode (intercepted; iframe stayed),
- *   - returns `true` otherwise (a real navigation happened).
- *
- * Callers in embed mode use the boolean to skip side effects (opening a tab)
- * that only make sense for a navigation that actually moved.
- */
-export declare function useEmbedScreenNavigate(): (to: string, opts?: NavigateOptions) => boolean;
-/**
- * Embed-aware replacement for `useNavigate` at internal screen-route call
- * sites. Returns a `navigate(to, opts)` function with the embed branch
- * applied. Outside embed mode it is `useNavigate()` unchanged.
- *
- * Use this for every raw screen transition (cancel-edit, save success,
- * delete success, Back). Do NOT use it for non-route navigation (anchors,
- * external URLs); those are not screen routes and embed mode does not touch
- * them.
- */
-export declare function useEmbedNavigate(): (to: string, opts?: NavigateOptions) => void;
-/**
- * Embed-mode Back: pop the iframe's own browser history (`navigate(-1)`) to the
- * exact prior URL, so the URL-keyed retained page + cache restore the prior
- * screen's full state - "the same as a normal app", just without tab chrome.
- *
- * Routed through the SAME deferred unsaved-changes guard the rest of embed
- * navigation uses: a raw `navigate(-1)` would bypass the dirty guard and
- * silently discard an in-progress edit. The CALLER
- * (`useScreenBack`) decides WHEN to use this (only when in-frame history depth
- * > 0); this hook only performs the guarded pop.
- */
-export declare function useEmbedScreenBack(): () => void;
-/**
- * Emit a `navigation-failed` event to the host. Used where an in-frame
- * navigation cannot be handled OUTSIDE the chokepoint - chiefly the embedded
- * 404 page, which the iframe reaches via a host-driven `navigate` command, a
- * bad initial route, or a hard reload (none of which pass through the
- * chokepoint's own guard). A no-op outside embed mode.
- */
-export declare function useEmbedNavigationFailed(): (route: string, reason: EmbedNavigationFailedPayload["reason"]) => void;