@microsoft/rayfin-app-state-fabric 1.35.0-alpha.1412

package/dist/fabricAppState.js

@@ -0,0 +1,311 @@
+/**
+ * fabricAppState — deep-linking client for Rayfin apps embedded in Fabric.
+ *
+ * An embedded app cannot touch the portal address bar, so it hands the host
+ * an opaque JSON object and the host owns the URL. That indirection is what
+ * lets the encoding change without a breaking SDK release.
+ *
+ * @example
+ * ```ts
+ * const appState = createFabricAppStateClient();
+ *
+ * // Restore before first render so defaults never flash.
+ * restoreApplicationState(appState.getLaunchStateSync());
+ *
+ * // User-initiated: Back should undo it.
+ * await appState.setState({ view: 'sales-by-region', filter: 'AT' });
+ *
+ * // App-initiated: do not grow history.
+ * await appState.replaceState({ view: 'sales-by-region', filter: 'DE' });
+ *
+ * const unsubscribe = appState.onStateChange(restoreApplicationState);
+ * ```
+ */
+import { sendBridgeRequest, subscribeBridgeEvents, } from '@microsoft/fabric-embedded-host';
+import { assertBrowser } from '@microsoft/rayfin-lib';
+import { toAppStateError } from './errors.js';
+import { readLaunchStateFromUrl, scrubLaunchParamFromUrl } from './launchState.js';
+import { FABRIC_APP_STATE_CHANNEL, KIND_CHANGED, KIND_GET_CAPABILITIES, KIND_GET_LAUNCH_STATE, KIND_PUSH, KIND_REPLACE, } from './protocol.js';
+import { DEFAULT_MAX_DEPTH, DEFAULT_MAX_ENCODED_BYTES, validateAppState, } from './validation.js';
+/** An unregistered channel may mean the host bridge has not mounted yet. */
+const READINESS_RETRY_LIMIT = 2;
+const READINESS_RETRY_DELAY_MS = 150;
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Create a {@link FabricAppStateClient} bound to the Fabric host.
+ *
+ * Safe to call once per application; create a single instance and share
+ * it rather than constructing one per component.
+ */
+export function createFabricAppStateClient(options = {}) {
+    assertBrowser('createFabricAppStateClient');
+    const { target = window.parent, targetOrigin, timeoutMs, maxEncodedBytes = DEFAULT_MAX_ENCODED_BYTES, maxDepth = DEFAULT_MAX_DEPTH, launchSearch, scrubLaunchParam = true, } = options;
+    const launchState = readLaunchStateFromUrl(launchSearch);
+    // Only rewrite the address bar when the state actually came from it, and
+    // only when embedded — a standalone page has no host that seeded it, so
+    // scrubbing there would mutate a URL the client does not own.
+    if (launchSearch === undefined && scrubLaunchParam && target !== window) {
+        scrubLaunchParamFromUrl();
+    }
+    const listeners = new Set();
+    let unsubscribeBridge;
+    let capabilitiesPromise;
+    /** Whether the last capability probe failed for a retryable reason. */
+    let capabilitiesTransientMiss = false;
+    /** `postMessage` gives no ordering guarantee, so stale events are dropped. */
+    let lastRevision = -1;
+    /** Generation of {@link lastRevision}; a change clears the high-water mark. */
+    let lastEpoch = 0;
+    /** Writes are chained so rapid calls reach the host in call order. */
+    let writeQueue = Promise.resolve();
+    /**
+     * The replace waiting to be sent, and the flush that will send it.
+     *
+     * The value lives in a slot rather than a bare variable so the flush
+     * sends whatever was pending when it was queued. A push closes the slot,
+     * which keeps a later replace from joining a flush scheduled ahead of it.
+     */
+    let replaceSlot;
+    let replaceFlush;
+    function request(kind, payload) {
+        return sendBridgeRequest({
+            target,
+            channel: FABRIC_APP_STATE_CHANNEL,
+            kind,
+            payload,
+            ...(targetOrigin !== undefined ? { targetOrigin } : {}),
+            ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+        });
+    }
+    /**
+     * Fold a response revision into the event watermark.
+     *
+     * Responses carry no epoch, so one that was already in flight when the host
+     * reset its counter would raise the watermark of the *new* epoch and
+     * silently discard every event after it. Skipping the merge when the epoch
+     * moved keeps the two generations from mixing, at the cost of one missed
+     * watermark update.
+     */
+    function mergeResponseRevision(result, epochAtRequest) {
+        if (lastEpoch !== epochAtRequest)
+            return;
+        if (typeof result?.revision === 'number') {
+            lastRevision = Math.max(lastRevision, result.revision);
+        }
+    }
+    /** Serialise a write behind any in-flight writes. */
+    function enqueueWrite(kind, state) {
+        // A Promise-returning method must never throw synchronously.
+        try {
+            validateAppState(state, maxEncodedBytes, maxDepth);
+        }
+        catch (err) {
+            return Promise.reject(toAppStateError(err));
+        }
+        // Close the open replace slot so a replace issued after this push
+        // queues behind it instead of collapsing into an earlier flush.
+        replaceSlot = undefined;
+        replaceFlush = undefined;
+        const epochAtRequest = { value: lastEpoch };
+        const send = () => {
+            // Captured at send rather than enqueue, so queuing behind a slow write
+            // does not needlessly widen the window.
+            epochAtRequest.value = lastEpoch;
+            return request(kind, { state });
+        };
+        // Chain on both settlement paths so one failure does not poison the queue.
+        const run = writeQueue.then(send, send);
+        writeQueue = run.catch(() => undefined);
+        return run.then((result) => {
+            mergeResponseRevision(result, epochAtRequest.value);
+        }, (err) => {
+            throw toAppStateError(err);
+        });
+    }
+    function ensureSubscribed() {
+        if (unsubscribeBridge)
+            return;
+        unsubscribeBridge = subscribeBridgeEvents({
+            source: target,
+            channel: FABRIC_APP_STATE_CHANNEL,
+            kind: KIND_CHANGED,
+            ...(targetOrigin !== undefined ? { origin: targetOrigin } : {}),
+            onEvent: (payload, revision, epoch) => {
+                // A reset counter would otherwise sit below the high-water mark forever.
+                if (epoch !== lastEpoch) {
+                    lastEpoch = epoch;
+                    lastRevision = -1;
+                }
+                if (revision <= lastRevision)
+                    return;
+                lastRevision = revision;
+                // Undefined means the URL carries no state; the app restores defaults.
+                const state = payload?.state;
+                // Copy: a listener may unsubscribe while the set is being walked.
+                for (const listener of [...listeners]) {
+                    try {
+                        listener(state);
+                    }
+                    catch (err) {
+                        console.error('[FabricAppState] onStateChange listener threw', err);
+                    }
+                }
+            },
+        });
+    }
+    /** Fill in any limits the host did not report with the client defaults. */
+    function toCapabilities(raw) {
+        return {
+            version: typeof raw?.version === 'number' ? raw.version : 1,
+            maxEncodedBytes: typeof raw?.maxEncodedBytes === 'number'
+                ? raw.maxEncodedBytes
+                : maxEncodedBytes,
+            maxDepth: typeof raw?.maxDepth === 'number' ? raw.maxDepth : maxDepth,
+            canPush: raw?.canPush !== false,
+        };
+    }
+    /** Ask the host for its limits, tolerating a bridge that is still mounting. */
+    async function requestCapabilities() {
+        capabilitiesTransientMiss = false;
+        for (let attempt = 0;; attempt++) {
+            try {
+                const raw = await request(KIND_GET_CAPABILITIES, {});
+                return toCapabilities(typeof raw === 'object' && raw !== null ? raw : undefined);
+            }
+            catch (err) {
+                const { code } = toAppStateError(err);
+                // A host still mounting its listener either rejects the channel or
+                // does not answer at all, so both are retryable.
+                if (code === 'UNSUPPORTED_HOST_CAPABILITY' ||
+                    code === 'BRIDGE_TIMEOUT') {
+                    if (attempt < READINESS_RETRY_LIMIT) {
+                        await delay(READINESS_RETRY_DELAY_MS);
+                        continue;
+                    }
+                    // Silence is not proof the feature is absent, so allow a later
+                    // call to probe again rather than hiding the feature for good.
+                    capabilitiesTransientMiss = code === 'BRIDGE_TIMEOUT';
+                    return undefined;
+                }
+                // Not embedded at all: definitive, so re-probing cannot help.
+                if (code === 'NO_HOST_WINDOW') {
+                    return undefined;
+                }
+                // Answered but does not know this kind: an older host that still
+                // services push and replace, so report defaults rather than hiding a
+                // feature that works.
+                if (code === 'UNKNOWN_OPERATION') {
+                    return toCapabilities();
+                }
+                // Anything else is an operational failure. Reporting capabilities
+                // here would advertise a feature that is currently broken.
+                return undefined;
+            }
+        }
+    }
+    return {
+        getLaunchStateSync() {
+            return launchState;
+        },
+        async getLaunchState() {
+            // Seeded onto the iframe URL before load, so no round trip is needed.
+            if (launchState)
+                return launchState;
+            // Fallback for hosts that do not seed the URL.
+            try {
+                const epochAtRequest = lastEpoch;
+                const result = await request(KIND_GET_LAUNCH_STATE, {});
+                mergeResponseRevision(result, epochAtRequest);
+                return result?.state;
+            }
+            catch (err) {
+                const error = toAppStateError(err);
+                // Starting up must survive a host that predates this feature, is not
+                // there at all, or is too slow to answer: all three mean "no launch
+                // state", so callers need no try/catch around startup.
+                if (error.code === 'UNSUPPORTED_HOST_CAPABILITY' ||
+                    error.code === 'NO_HOST_WINDOW' ||
+                    error.code === 'BRIDGE_TIMEOUT') {
+                    return undefined;
+                }
+                throw error;
+            }
+        },
+        isSupported() {
+            capabilitiesPromise ??= requestCapabilities().then((capabilities) => {
+                // Definitive answers stay cached; a timeout is re-probed on the
+                // next call so a host that mounts late is not missed forever.
+                if (capabilities === undefined && capabilitiesTransientMiss) {
+                    capabilitiesPromise = undefined;
+                }
+                return capabilities;
+            });
+            return capabilitiesPromise;
+        },
+        setState(state) {
+            return enqueueWrite(KIND_PUSH, state);
+        },
+        replaceState(state) {
+            // Replace is used for continuous input such as a slider drag.
+            // Sending every intermediate value would queue them behind one
+            // round trip each and leave the URL visibly lagging the UI, so
+            // only the newest pending value is written.
+            try {
+                validateAppState(state, maxEncodedBytes, maxDepth);
+            }
+            catch (err) {
+                return Promise.reject(toAppStateError(err));
+            }
+            // Coalesce into the slot that is still waiting to be sent. Once a
+            // push has closed it, open a new one so this value lands after it.
+            const open = replaceSlot;
+            if (open !== undefined && replaceFlush !== undefined) {
+                open.state = state;
+                return replaceFlush;
+            }
+            const slot = { state };
+            replaceSlot = slot;
+            const flush = writeQueue.then(runFlush, runFlush);
+            writeQueue = flush.catch(() => undefined);
+            replaceFlush = flush;
+            return flush;
+            async function runFlush() {
+                // Close the slot before sending so later replaces open a new one.
+                if (replaceSlot === slot) {
+                    replaceSlot = undefined;
+                    replaceFlush = undefined;
+                }
+                try {
+                    const epochAtRequest = lastEpoch;
+                    const result = await request(KIND_REPLACE, { state: slot.state });
+                    mergeResponseRevision(result, epochAtRequest);
+                }
+                catch (err) {
+                    throw toAppStateError(err);
+                }
+            }
+        },
+        onStateChange(listener) {
+            listeners.add(listener);
+            ensureSubscribed();
+            return () => {
+                listeners.delete(listener);
+                // Release the window listener once nobody is observing.
+                if (listeners.size === 0 && unsubscribeBridge) {
+                    unsubscribeBridge();
+                    unsubscribeBridge = undefined;
+                }
+            };
+        },
+        dispose() {
+            listeners.clear();
+            if (unsubscribeBridge) {
+                unsubscribeBridge();
+                unsubscribeBridge = undefined;
+            }
+        },
+    };
+}
+//# sourceMappingURL=fabricAppState.js.map

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export type { FabricAppState, FabricAppStateValue, FabricAppStateCapabilities, FabricAppStateClient, FabricAppStateClientOptions, FabricAppStateListener, } from './types.js';
+export { createFabricAppStateClient } from './fabricAppState.js';
+export { FabricAppStateError } from './errors.js';
+export { DEFAULT_MAX_ENCODED_BYTES, DEFAULT_MAX_DEPTH } from './validation.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,11 @@
+// ── Deep-link application state ──────────────────────────────
+//
+// The URL representation is owned by the host and is deliberately NOT
+// exported: no parameter name, no codec, no channel constant. Exporting
+// them would let a Builder depend on the encoding, which is the one
+// thing this design exists to keep changeable. They remain importable
+// from the individual modules for tests and for the host-side contract.
+export { createFabricAppStateClient } from './fabricAppState.js';
+export { FabricAppStateError } from './errors.js';
+export { DEFAULT_MAX_ENCODED_BYTES, DEFAULT_MAX_DEPTH } from './validation.js';
+//# sourceMappingURL=index.js.map

package/dist/launchState.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Launch-state seeding: decoding the state the host places on the app's
+ * own iframe URL.
+ *
+ * Everything in this module is the **URL contract between the host and
+ * this client**, not part of the Builder-facing surface.  Apps read
+ * launch state through the client, never by parsing the URL themselves —
+ * that is what allows the host to change the encoding (query parameter,
+ * path segment, short link) without a breaking SDK release.
+ *
+ * @internal
+ */
+import type { FabricAppState } from './types.js';
+/**
+ * Query parameter the host places on the app's iframe URL to seed
+ * launch state.
+ *
+ * Launch state must be available before first render, which a `postMessage`
+ * round trip cannot provide. Seeding lets the app read it synchronously from
+ * its own location.
+ *
+ * @internal
+ */
+export declare const LAUNCH_STATE_PARAM = "fabricAppState";
+/**
+ * Encoding prefix, so the wire format can be versioned.
+ *
+ * Counts against the host's encoded-size budget, so the write-path
+ * validator subtracts it before converting that budget to a raw-JSON one.
+ *
+ * @internal
+ */
+export declare const LAUNCH_STATE_PREFIX = "v1.";
+/**
+ * Read seeded launch state from the current document's URL.
+ *
+ * Synchronous and safe to call before first render.
+ *
+ * @param search - Query string to parse. Defaults to the live location,
+ *                 and is injectable for tests.
+ * @returns The decoded state, or `undefined` when absent or unusable.
+ *
+ * @internal
+ */
+export declare function readLaunchStateFromUrl(search?: string): FabricAppState | undefined;
+/**
+ * Remove the seeded parameter from the app's own address bar.
+ *
+ * Leaving it would resend the state to the app's server on reload and expose
+ * it in referrers to subresources. Only this frame's history entry is
+ * rewritten; the portal URL, which the host owns, is untouched.
+ *
+ * @internal
+ */
+export declare function scrubLaunchParamFromUrl(): void;
+//# sourceMappingURL=launchState.d.ts.map

package/dist/launchState.js

@@ -0,0 +1,116 @@
+/**
+ * Launch-state seeding: decoding the state the host places on the app's
+ * own iframe URL.
+ *
+ * Everything in this module is the **URL contract between the host and
+ * this client**, not part of the Builder-facing surface.  Apps read
+ * launch state through the client, never by parsing the URL themselves —
+ * that is what allows the host to change the encoding (query parameter,
+ * path segment, short link) without a breaking SDK release.
+ *
+ * @internal
+ */
+/**
+ * Query parameter the host places on the app's iframe URL to seed
+ * launch state.
+ *
+ * Launch state must be available before first render, which a `postMessage`
+ * round trip cannot provide. Seeding lets the app read it synchronously from
+ * its own location.
+ *
+ * @internal
+ */
+export const LAUNCH_STATE_PARAM = 'fabricAppState';
+/**
+ * Encoding prefix, so the wire format can be versioned.
+ *
+ * Counts against the host's encoded-size budget, so the write-path
+ * validator subtracts it before converting that budget to a raw-JSON one.
+ *
+ * @internal
+ */
+export const LAUNCH_STATE_PREFIX = 'v1.';
+/**
+ * Decode one base64url-encoded launch-state value.
+ *
+ * Returns `undefined` for anything unusable rather than throwing.
+ * Tolerance is a requirement, not leniency: links shared while the
+ * feature was enabled keep the parameter after it is disabled, and such
+ * a link must still open the app in its default state.
+ */
+function decodeLaunchState(raw) {
+    if (!raw.startsWith(LAUNCH_STATE_PREFIX))
+        return undefined;
+    const encoded = raw.slice(LAUNCH_STATE_PREFIX.length);
+    if (!encoded)
+        return undefined;
+    try {
+        // base64url -> base64, restoring the padding atob() requires.
+        const base64 = encoded.replace(/-/g, '+').replace(/_/g, '/');
+        const padded = base64.padEnd(base64.length + ((4 - (base64.length % 4)) % 4), '=');
+        // Reached through globalThis so the reference resolves in any
+        // module system, and so lint does not treat it as an undeclared
+        // browser global. Guarded because a non-browser host may lack it.
+        const decodeBase64 = globalThis.atob;
+        if (typeof decodeBase64 !== 'function')
+            return undefined;
+        const binary = decodeBase64(padded);
+        const bytes = Uint8Array.from(binary, (ch) => ch.charCodeAt(0));
+        const json = new TextDecoder().decode(bytes);
+        const parsed = JSON.parse(json);
+        if (typeof parsed !== 'object' ||
+            parsed === null ||
+            Array.isArray(parsed)) {
+            return undefined;
+        }
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Read seeded launch state from the current document's URL.
+ *
+ * Synchronous and safe to call before first render.
+ *
+ * @param search - Query string to parse. Defaults to the live location,
+ *                 and is injectable for tests.
+ * @returns The decoded state, or `undefined` when absent or unusable.
+ *
+ * @internal
+ */
+export function readLaunchStateFromUrl(search) {
+    const query = search ??
+        (typeof window !== 'undefined' ? window.location.search : undefined);
+    if (!query)
+        return undefined;
+    const raw = new URLSearchParams(query).get(LAUNCH_STATE_PARAM);
+    if (!raw)
+        return undefined;
+    return decodeLaunchState(raw);
+}
+/**
+ * Remove the seeded parameter from the app's own address bar.
+ *
+ * Leaving it would resend the state to the app's server on reload and expose
+ * it in referrers to subresources. Only this frame's history entry is
+ * rewritten; the portal URL, which the host owns, is untouched.
+ *
+ * @internal
+ */
+export function scrubLaunchParamFromUrl() {
+    try {
+        if (typeof window === 'undefined')
+            return;
+        const url = new URL(window.location.href);
+        if (!url.searchParams.has(LAUNCH_STATE_PARAM))
+            return;
+        url.searchParams.delete(LAUNCH_STATE_PARAM);
+        window.history.replaceState(window.history.state, '', `${url.pathname}${url.search}${url.hash}`);
+    }
+    catch {
+        // Hardening only; never let this break startup.
+    }
+}
+//# sourceMappingURL=launchState.js.map

package/dist/protocol.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Wire protocol constants for the `fabric-app-state` channel.
+ *
+ * These describe the contract between an embedded Rayfin app and the
+ * Fabric host that services it.  They are implementation detail of the
+ * client and are not part of the Builder-facing surface.
+ *
+ * @internal
+ */
+/** Channel routed by the host's `AppStatePlugin`. */
+export declare const FABRIC_APP_STATE_CHANNEL = "fabric-app-state";
+/** Request kind: read the host's limits and supported features. */
+export declare const KIND_GET_CAPABILITIES = "appState.getCapabilities";
+/** Request kind: read the state the app was launched with. */
+export declare const KIND_GET_LAUNCH_STATE = "appState.getLaunchState";
+/** Request kind: commit state as a new browser history entry. */
+export declare const KIND_PUSH = "appState.push";
+/** Request kind: commit state over the current history entry. */
+export declare const KIND_REPLACE = "appState.replace";
+/** Event kind: the host reports externally-changed state. */
+export declare const KIND_CHANGED = "appState.changed";
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.js

@@ -0,0 +1,22 @@
+/**
+ * Wire protocol constants for the `fabric-app-state` channel.
+ *
+ * These describe the contract between an embedded Rayfin app and the
+ * Fabric host that services it.  They are implementation detail of the
+ * client and are not part of the Builder-facing surface.
+ *
+ * @internal
+ */
+/** Channel routed by the host's `AppStatePlugin`. */
+export const FABRIC_APP_STATE_CHANNEL = 'fabric-app-state';
+/** Request kind: read the host's limits and supported features. */
+export const KIND_GET_CAPABILITIES = 'appState.getCapabilities';
+/** Request kind: read the state the app was launched with. */
+export const KIND_GET_LAUNCH_STATE = 'appState.getLaunchState';
+/** Request kind: commit state as a new browser history entry. */
+export const KIND_PUSH = 'appState.push';
+/** Request kind: commit state over the current history entry. */
+export const KIND_REPLACE = 'appState.replace';
+/** Event kind: the host reports externally-changed state. */
+export const KIND_CHANGED = 'appState.changed';
+//# sourceMappingURL=protocol.js.map