@declarion/react 0.26.4 → 0.28.0

package/dist-lib/lib/canonical-url.d.ts

@@ -0,0 +1,27 @@
+/** The minimal location shape canonicalUrl needs (a router `Location` satisfies
+ *  it; tests can pass a bare object). */
+export interface CanonicalLocation {
+    pathname: string;
+    search?: string;
+}
+/**
+ * Build the canonical URL key for a location: normalized pathname + the
+ * view-defining query, sorted by key, with the embed transport params removed.
+ *
+ * Sorting makes `?a=1&b=2` and `?b=2&a=1` one key. Removing `EMBED_PARAM_KEYS`
+ * makes the same screen one key whether or not the embed params ride along, so
+ * a retained page is shared between the embedded and non-embedded view of the
+ * same URL. Default query values are NOT collapsed (which params have a default
+ * is screen-specific and collapsing the wrong one would silently merge or fork
+ * pages); two URLs that differ only by an explicit-vs-implicit default are
+ * treated as distinct, which is safe (at worst slightly less sharing).
+ */
+export declare function canonicalUrl(location: CanonicalLocation): string;
+/**
+ * The SCREEN-scoped key: the normalized pathname alone, ignoring the query.
+ * Coarser than `canonicalUrl` - it does NOT fork when filters/sort/columns
+ * change. Used for deep state that must persist ACROSS in-screen query changes
+ * (row selection, pruned to the visible result set) rather than resetting per
+ * filtered view. Two filter views of the same screen share one screen key.
+ */
+export declare function canonicalPath(location: CanonicalLocation): string;

package/dist-lib/lib/screen-back.d.ts

@@ -0,0 +1,72 @@
+import { type ReturnTarget, type TabItem } from "../stores/tabs";
+/** Drop a leading `?` so a search string matches the canonical `TabItem.search`
+ *  / `ReturnTarget.search` form (stored WITHOUT `?`). Empty in -> empty out. */
+export declare function stripLeadingQuestion(search: string | undefined | null): string;
+/** Re-attach the leading `?` for the router/`navigate` form, or `undefined`
+ *  when there is no query. The inverse of `stripLeadingQuestion`. */
+export declare function toRouterSearch(search: string | undefined): string | undefined;
+/** The current location at navigate time (canonical: `search` may carry `?`,
+ *  `hash` carries `#`). Sourced from `window.location` at the click. */
+export interface CaptureLocation {
+    pathname: string;
+    search?: string;
+    hash?: string;
+}
+/**
+ * Build the return target to stamp on the DESTINATION tab when navigating from
+ * `current` to `destinationPathname`. Returns `undefined` (no capture) when:
+ *   - the current path is not a same-origin in-app route,
+ *   - the current path is an excluded (auth) route,
+ *   - the destination shares the current PATHNAME (self guard, Invariant 7) -
+ *     a same-screen, different-query link must not self-stamp a Back.
+ *
+ * `originTab` supplies metadata (id/title/icon/screen) for switching to or
+ * reopening the origin; only the current location drives pathname/search/hash.
+ */
+export declare function captureReturnTarget(current: CaptureLocation, destinationPathname: string, originTab?: Pick<TabItem, "id" | "title" | "icon" | "screen">): ReturnTarget | undefined;
+/** The Back visibility intent, derived from a tab's `returnTo` alone (no tab
+ *  list needed). `hasOriginBack` drives an origin Back affordance;
+ *  `allowFallbackBack` permits a screen's static/parent fallback (false ONLY
+ *  for a menu-cleared `null`). */
+export interface BackVisibility {
+    hasOriginBack: boolean;
+    allowFallbackBack: boolean;
+}
+/**
+ * Interpret the tri-state `returnTo` for Back VISIBILITY:
+ *   - embed enabled -> never an origin Back; fallback allowed (embed has no tabs),
+ *   - `null` (menu-cleared) -> no origin Back AND no fallback (a menu-opened
+ *     screen has nowhere to return),
+ *   - a valid origin object -> origin Back,
+ *   - `undefined` / invalid object (deep-link) -> no origin Back, fallback allowed.
+ */
+export declare function resolveBackVisibility(returnTo: ReturnTarget | null | undefined, embedEnabled: boolean): BackVisibility;
+/** The resolved Back destination. `live` = the origin tab is still open (switch
+ *  to it); `reopen` = the origin tab was closed (reopen it). Both navigate to
+ *  the CAPTURED snapshot (pathname+search+hash). */
+export interface ResolvedBack {
+    kind: "live" | "reopen";
+    tabId?: string;
+    pathname: string;
+    search?: string;
+    hash?: string;
+    title?: string;
+    icon?: string;
+    screen?: string;
+}
+/**
+ * Resolve the Back DESTINATION from a tab's `returnTo` and the live tab list.
+ * Returns `null` when there is no valid origin (the caller then uses its
+ * fallback). The origin tab (live by `tabId`, else by `pathname`) decides only
+ * SWITCH vs REOPEN; the destination URL is always the CAPTURED snapshot. Embed
+ * yields `null` (Back is fallback-only in embed; no tab ops).
+ *
+ * Divergence from the plan's Invariant 5 (reasoned): the plan preferred the
+ * live tab's CURRENT search over the captured one, premised on every origin
+ * screen mirroring its URL into the tab store. That premise is false for custom
+ * screens (Compare, dashboards) with no per-page mirror, so preferring live
+ * search loses URL-encoded state (Business Case 3). The captured `returnTo` is
+ * exact at drill time ("where I came from"), so it is the single source of
+ * truth for the destination URL - no per-screen search mirror needed.
+ */
+export declare function resolveBackTarget(returnTo: ReturnTarget | null | undefined, tabs: TabItem[], embedEnabled: boolean): ResolvedBack | null;

package/dist-lib/lib/scroll-restoration.d.ts

@@ -0,0 +1,90 @@
+/** The default deep-state bag key under which a screen's scroll anchor is
+ *  stored. A screen with one scroll container uses this; a screen with several
+ *  passes distinct keys. */
+export declare const SCROLL_STATE_KEY = "scroll";
+/**
+ * A saved scroll position. `key` is the stable key of the row at the top of the
+ * viewport (empty when the container had no rows / is non-virtualized); `delta`
+ * is the sub-row pixel offset; `offset` is the raw scroll offset kept as a
+ * last-resort fallback when the anchor row is gone.
+ */
+export interface ScrollAnchor {
+    key: string;
+    delta: number;
+    offset: number;
+}
+/** The minimal virtualizer surface the seam needs. A
+ *  `Virtualizer<HTMLElement, Element>` is structurally assignable; a test can
+ *  pass a fake. */
+export interface ScrollableVirtualizer {
+    scrollOffset: number | null;
+    getVirtualItemForOffset: (offset: number) => {
+        index: number;
+        start: number;
+    } | undefined;
+    getOffsetForIndex: (index: number, align?: "start") => readonly [number, unknown] | undefined;
+    getTotalSize: () => number;
+    scrollToOffset: (offset: number, opts?: {
+        align?: "start";
+        behavior?: "auto";
+    }) => void;
+}
+/**
+ * Capture the scroll anchor at `scrollOffset`. `topItem` is the virtual item at
+ * the top of the viewport (`getVirtualItemForOffset(scrollOffset)`); `rowKeys`
+ * maps its index to a stable row key. Returns an anchor with an empty `key`
+ * (raw-offset-only) when there is no top item or no key for it. Pure.
+ */
+export declare function captureScrollAnchor(scrollOffset: number, topItem: {
+    index: number;
+    start: number;
+} | undefined, rowKeys: string[]): ScrollAnchor;
+/**
+ * Resolve the scroll offset to restore to, from a saved `anchor`, the CURRENT
+ * `rowKeys`, an `offsetForIndex` accessor (the virtualizer's measured start of a
+ * row), and the current `totalSize` (for clamping). Pure and testable.
+ *
+ * Fallback chain (Decision #17): anchor row found -> its measured start + delta;
+ * anchor row gone (deleted / filtered out) -> clamped raw offset; unusable
+ * offset -> top (0). Returns null when there is nothing saved.
+ */
+export declare function resolveScrollOffset(anchor: ScrollAnchor | undefined, rowKeys: string[], offsetForIndex: (index: number) => number | undefined, totalSize: number): number | null;
+/** Read the saved raw scroll offset for the current page ONCE, for seeding a
+ *  virtualizer's `initialOffset` (read-once at init). Returns 0 when none /
+ *  retention off. The full anchor re-restore happens after rows measure. */
+export declare function useSavedScrollOffset(stateKey?: string): number;
+/**
+ * Bind scroll save + anchor-row restore for a VIRTUALIZED list to the retained
+ * page keyed by the live canonical URL.
+ *
+ * - Restore: once per pageKey, after `rowKeys` first become non-empty, scrolls
+ *   to `resolveScrollOffset(...)` (anchor row -> clamped raw -> top).
+ * - Save: a throttled scroll listener captures the top-of-viewport anchor and
+ *   writes it imperatively (no re-render); the final position flushes on
+ *   unmount / pageKey change to the DEPARTING view's own URL (tracked via a
+ *   per-render ref).
+ *
+ * `enabled` (default true) lets a caller gate the seam; when false it is inert.
+ */
+export declare function useVirtualScrollRestoration(opts: {
+    virtualizer: ScrollableVirtualizer | null;
+    scrollElementRef: {
+        current: HTMLElement | null;
+    };
+    rowKeys: string[];
+    stateKey?: string;
+    enabled?: boolean;
+}): void;
+/**
+ * Scroll save + restore for a PLAIN (non-virtualized) scroll container - the
+ * detail page. Stores the raw `scrollTop` (no anchor rows to key by) under the
+ * live canonical URL; restores after first layout; saves throttled-on-scroll +
+ * on unmount flush.
+ */
+export declare function usePlainScrollRestoration(opts: {
+    scrollElementRef: {
+        current: HTMLElement | null;
+    };
+    stateKey?: string;
+    enabled?: boolean;
+}): void;

package/dist-lib/stores/page-state.d.ts

@@ -0,0 +1,61 @@
+import type { QueryClient, QueryKey } from "@tanstack/react-query";
+/** Default retention window before the `ui_page_state_ttl_ms` parameter
+ *  resolves (and the fallback when it is absent). 30 minutes - long enough to
+ *  switch among tabs all day instantly, bounded enough to keep memory sane.
+ *  Mirrors the YAML default in core_parameters.yaml; both must agree. */
+export declare const DEFAULT_PAGE_STATE_TTL_MS: number;
+/** Hard upper bound on retained-page entries. Bounds total memory and is the
+ *  ONLY bound in embed mode, which has no tab-close signal at all. Generous
+ *  relative to `ui_tabs_max_open` (a user rarely revisits more than this many
+ *  distinct URLs within one TTL window); the least-recently-active entry is
+ *  evicted first when the cap is exceeded. */
+export declare const PAGE_STATE_MAX_ENTRIES = 64;
+/** One retained page's deep state. `bag` holds small JSON-serializable deep
+ *  values; `queryKeys` references the screen's PRIMARY React Query reads so an
+ *  eviction can release the cached data alongside the deep state. */
+export interface PageStateEntry {
+    bag: Record<string, unknown>;
+    lastActiveAt: number;
+    queryKeys: QueryKey[];
+}
+interface PageStateStore {
+    /** pageKey (canonical URL) -> retained-page deep state. */
+    entries: Record<string, PageStateEntry>;
+    /** Active retention window. `<= 0` disables retention. Set by the runtime
+     *  from the resolved `ui_page_state_ttl_ms`; defaults to the 30-min fallback
+     *  so retention works before the parameter loads. */
+    ttlMs: number;
+    /** Set the retention window. `<= 0` disables retention and immediately clears
+     *  every entry (with linked `removeQueries`), so a runtime toggle to "off"
+     *  frees memory at once. */
+    setTtl: (ttlMs: number) => void;
+    /** Write a deep value under `pageKey`, refreshing `lastActiveAt` and
+     *  enforcing the LRU cap. No-op when retention is disabled. */
+    set: (pageKey: string, key: string, value: unknown) => void;
+    /** Read a deep value, or `undefined` when absent / reaped / retention off. */
+    read: (pageKey: string, key: string) => unknown;
+    /** Refresh `lastActiveAt` for a still-mounted view so it is not reaped while
+     *  active. No-op when the entry is absent or retention is disabled. */
+    touch: (pageKey: string) => void;
+    /** Track one of the screen's PRIMARY React Query keys so eviction releases
+     *  the cached data. Deduplicated. No-op when retention is disabled. */
+    registerQueryKey: (pageKey: string, queryKey: QueryKey) => void;
+    /** Explicitly evict one retained page NOW: drop its deep state AND
+     *  `removeQueries` its tracked keys. Idempotent; works even when retention is
+     *  disabled (used by per-screen kill policies, e.g. a deleted detail record). */
+    kill: (pageKey: string) => void;
+    /** Reap every entry stale past the active TTL (`now - lastActiveAt > ttlMs`),
+     *  releasing data + deep state together. When retention is disabled, evicts
+     *  all. `now` is injected for testability. */
+    sweep: (now: number) => void;
+    /** Drop EVERY retained page NOW (releasing all tracked queries) without
+     *  changing the TTL - the auth-scope reset. Called on logout so a different
+     *  user signing in within the same JS session cannot restore the prior user's
+     *  deep state (selection, scroll, custom-screen values). */
+    clear: () => void;
+}
+/** Register the app's QueryClient so retained-page eviction can release the
+ *  tracked entity-read queries. Called once at app mount. */
+export declare function setPageStateQueryClient(client: QueryClient | null): void;
+export declare const usePageStateStore: import("zustand").UseBoundStore<import("zustand").StoreApi<PageStateStore>>;
+export {};

package/dist-lib/stores/tabs.d.ts

@@ -1,5 +1,26 @@
 export type TabMode = "view" | "edit" | "create";
 export type TabCloseScope = "current" | "others" | "right" | "all";
+/**
+ * Origin-aware Back return target. The CANONICAL stored shape: `pathname` is an
+ * in-app path (no origin, starts `/` not `//`), `search` is the query string
+ * WITHOUT a leading `?` (matches `TabItem.search`), `hash` carries its leading
+ * `#`. Converted to the `?`-prefixed router form only at the navigate boundary.
+ *
+ * `hash` lives here but NOT on `TabItem` (which has no `hash` field): a closed
+ * origin tab with a hash is reopened via pathname+search, and the hash is
+ * applied only in the `navigate()` call. `tabId`/`title`/`icon`/`screen` are
+ * hints for switching to (or reopening) the origin tab. Never stores secrets,
+ * external URLs, or row data. See docs/plans/2026-06-29-origin-aware-back-navigation.md.
+ */
+export interface ReturnTarget {
+    pathname: string;
+    search?: string;
+    hash?: string;
+    tabId?: string;
+    title?: string;
+    icon?: string;
+    screen?: string;
+}
 export interface TabItem {
     id: string;
     pathname: string;
@@ -14,6 +35,7 @@ export interface TabItem {
     record?: Record<string, unknown>;
     mode?: TabMode;
     dirty?: boolean;
+    returnTo?: ReturnTarget | null;
 }
 interface TabState {
     tabs: TabItem[];
@@ -26,12 +48,24 @@ interface TabState {
     findTabByPathname: (pathname: string) => TabItem | undefined;
     updateTabTitle: (id: string, title: string) => void;
     updateTabSearch: (id: string, search: string) => void;
+    setReturnTarget: (id: string, rt: ReturnTarget | null) => void;
+    commitTabNavigation: (id: string, patch: {
+        search: string;
+        returnTo?: ReturnTarget | null;
+    }) => void;
     setDirty: (id: string, dirty: boolean) => void;
     setMode: (id: string, mode: TabMode) => void;
     updateTab: (id: string, patch: Partial<TabItem>) => void;
     setScope: (tenantId: string | null, userId: string | null) => void;
     hydrate: () => void;
 }
+/** True for an auth/chrome route that must never create a tab or be captured
+ *  as a Back origin. Shared by `openTab` and the origin-capture path. */
+export declare function isExcludedRoute(pathname: string): boolean;
+/** A same-origin in-app path: starts `/` but not `//` (the latter is a
+ *  protocol-relative external URL). The single guard reused on capture, on
+ *  snapshot load (localStorage is hostile), and in the tenant-landing peek. */
+export declare function isSameOriginPath(pathname: unknown): pathname is string;
 export declare function tabIdsForCloseScope(tabs: TabItem[], activeTabId: string | null, scope: TabCloseScope, targetId?: string): string[];
 export declare function peekTenantLandingPath(tenantId: string, userId: string): string | null;
 export declare const useTabStore: import("zustand").UseBoundStore<import("zustand").StoreApi<TabState>>;

package/dist-lib/testing.js

@@ -1,4 +1,4 @@
-import { J as e, V as t, X as n, Y as r, ft as i, t as a } from "./ActionRunner-B2e3Igpd.js";
+import { H as e, X as t, Y as n, Z as r, mt as i, t as a } from "./ActionRunner-DtUDeH4F.js";
 import { useState as o } from "react";
 import { MemoryRouter as s } from "react-router-dom";
 import { QueryClient as c, QueryClientProvider as l } from "@tanstack/react-query";
@@ -87,7 +87,7 @@ function x(e) {
 }
 function S(i) {
 	let a = i.entityData ?? {};
-	n((e, t) => {
+	r((e, t) => {
 		let n = a[e], r = x(n), i = r.meta?.per_page ?? 50, o = r.meta?.total ?? r.rows.length;
 		return t.count === "only" ? {
 			data: [],
@@ -109,19 +109,19 @@ function S(i) {
 		};
 	});
 	let o = i.entityItems ?? {};
-	r((e, n) => {
-		let r = typeof n == "string" ? n : t(n);
-		return { data: o[e]?.[r] };
+	t((t, n) => {
+		let r = typeof n == "string" ? n : e(n);
+		return { data: o[t]?.[r] };
 	});
 	let s = i.actionResults ?? {};
-	e(async (e, t) => {
+	n(async (e, t) => {
 		if (!(e in s)) throw Error(`renderWithDeclarion: no action result registered for "${e}" (seed it via actionResults)`);
 		let n = s[e];
 		return y(typeof n == "function" ? await n(t) : n);
 	});
 }
 function C() {
-	n(null), r(null), e(null), i.setState({
+	r(null), t(null), n(null), i.setState({
 		user: null,
 		isAuthenticated: !1,
 		activeTenant: null,

package/dist-lib/{value-D7fe0TEL.js → value-CNUbJNK-.js}

@@ -1,68 +1,11 @@
-import { Lt as e, Nt as t, Pt as n } from "./ActionRunner-B2e3Igpd.js";
+import { Ft as e, It as t, zt as n } from "./ActionRunner-DtUDeH4F.js";
 import { useCallback as r, useEffect as i, useRef as a, useState as o } from "react";
-//#region src/embed/file-src.ts
-var s = "/api/files";
-function c(e) {
-	if (typeof e != "object" || !e) return !1;
-	let t = e;
-	return typeof t.url == "string" && typeof t.proxy == "boolean";
-}
-function l(e, t) {
-	let n = encodeURIComponent(e);
-	return typeof t == "object" ? `${s}/${n}/derived/${encodeURIComponent(t.derivation)}/url` : `${s}/${n}/url`;
-}
-var u = class extends Error {
-	fileId;
-	key;
-	constructor(e, t) {
-		super(`derivation "${t}" of file ${e} is still generating`), this.fileId = e, this.key = t, this.name = "DerivationPendingError";
-	}
-};
-function d(e, t) {
-	return {
-		method: "GET",
-		credentials: "omit",
-		headers: { Authorization: `Bearer ${e}` },
-		signal: t
-	};
-}
-function f(e) {
-	return `${e}${e.includes("?") ? "&" : "?"}disposition=attachment`;
-}
-async function p(e, r) {
-	let i = await t(), a = await fetch(e, d(i, r));
-	if (a.status !== 401) return a;
-	n();
-	let o = await t();
-	return fetch(e, d(o, r));
-}
-async function m(t, n, r) {
-	if (!e()) throw Error("resolveEmbedFileSrc called outside embed token mode");
-	let i = await p(l(t, n), r);
-	if (i.status === 202 && typeof n == "object") throw new u(t, n.derivation);
-	if (!i.ok) throw Error(`embed file url request failed: ${i.status} ${i.statusText}`);
-	let a = await i.json();
-	if (!c(a)) throw Error("embed file url response is malformed");
-	if (!a.proxy) return {
-		url: a.url,
-		kind: "direct"
-	};
-	if (!a.url.startsWith("/api/files/")) throw Error(`embed file proxy: refusing non-files-route URL ${JSON.stringify(a.url)}`);
-	let o = await p(n === "download" ? f(a.url) : a.url, r);
-	if (!o.ok) throw Error(`embed file proxy fetch failed: ${o.status} ${o.statusText}`);
-	let s = await o.blob();
-	return {
-		url: URL.createObjectURL(s),
-		kind: "blob"
-	};
-}
-//#endregion
 //#region src/components/file-widgets/helpers.ts
-var h = ["thumb_200", "thumb_300"];
-function g() {
+var s = ["thumb_200", "thumb_300"];
+function c() {
 	return typeof navigator > "u" ? ["en"] : (navigator.languages?.length ? navigator.languages : [navigator.language]).filter((e) => typeof e == "string" && e.length > 0);
 }
-function _(e, t) {
+function l(e, t) {
 	for (let n of t) {
 		if (e[n]) return e[n];
 		let t = n.split("-")[0];
@@ -70,17 +13,17 @@ function _(e, t) {
 	}
 	for (let t of Object.values(e)) if (typeof t == "string" && t.length > 0) return t;
 }
-function v(e, t, n) {
+function u(e, t, n) {
 	if (t) return t;
 	let r = e?.metadata?.alt_text;
 	if (typeof r == "string" && r.length > 0) return r;
 	if (r && typeof r == "object" && !Array.isArray(r)) {
-		let e = _(Object.fromEntries(Object.entries(r).filter((e) => e[0].length > 0 && typeof e[1] == "string")), g());
+		let e = l(Object.fromEntries(Object.entries(r).filter((e) => e[0].length > 0 && typeof e[1] == "string")), c());
 		if (e) return e;
 	}
 	return n;
 }
-var y = new Set([
+var d = /* @__PURE__ */ new Set([
 	"image/png",
 	"image/jpeg",
 	"image/webp",
@@ -88,30 +31,30 @@ var y = new Set([
 	"image/avif",
 	"application/pdf"
 ]);
-function b(e) {
+function f(e) {
 	let t = e.content_type?.toLowerCase().split(";")[0]?.trim() ?? "";
-	return y.has(t);
+	return d.has(t);
 }
-function x(e) {
+function p(e) {
 	return e.url ?? e.presigned_url;
 }
-function S(e) {
-	return e.url ? T(e.url, "attachment") : e.presigned_url;
+function m(e) {
+	return e.url ? _(e.url, "attachment") : e.presigned_url;
 }
-function C(e, t) {
+function h(e, t) {
 	if (!e) return;
 	let n = e.derivations ?? {};
 	if (t && n[t]) return n[t];
-	for (let e of h) if (n[e]) return n[e];
+	for (let e of s) if (n[e]) return n[e];
 	return e.url ?? e.presigned_url;
 }
-function w(e, t) {
+function g(e, t) {
 	let n = e?.derivations ?? {};
 	if (t && n[t]) return { derivation: t };
-	for (let e of h) if (n[e]) return { derivation: e };
+	for (let e of s) if (n[e]) return { derivation: e };
 	return "preview";
 }
-function T(e, t) {
+function _(e, t) {
 	try {
 		let n = new URL(e, typeof window < "u" ? window.location.origin : "http://localhost");
 		return n.searchParams.set("disposition", t), /^https?:\/\//i.test(e) ? n.toString() : `${n.pathname}${n.search}${n.hash}`;
@@ -119,7 +62,7 @@ function T(e, t) {
 		return `${e}${e.includes("?") ? "&" : "?"}disposition=${t}`;
 	}
 }
-function E(e) {
+function v(e) {
 	let t = e?.metadata?.focal_point;
 	if (!t || typeof t != "object" || Array.isArray(t)) return null;
 	let n = t, r = typeof n.x == "number" ? n.x : NaN, i = typeof n.y == "number" ? n.y : NaN;
@@ -128,10 +71,10 @@ function E(e) {
 		y: i
 	};
 }
-function D(e) {
+function y(e) {
 	if (e) return `${e.x * 100}% ${e.y * 100}%`;
 }
-function O(e, t) {
+function b(e, t) {
 	return {
 		...e,
 		metadata: {
@@ -141,6 +84,63 @@ function O(e, t) {
 	};
 }
 //#endregion
+//#region src/embed/file-src.ts
+var x = "/api/files";
+function S(e) {
+	if (typeof e != "object" || !e) return !1;
+	let t = e;
+	return typeof t.url == "string" && typeof t.proxy == "boolean";
+}
+function C(e, t) {
+	let n = encodeURIComponent(e);
+	return typeof t == "object" ? `${x}/${n}/derived/${encodeURIComponent(t.derivation)}/url` : `${x}/${n}/url`;
+}
+var w = class extends Error {
+	fileId;
+	key;
+	constructor(e, t) {
+		super(`derivation "${t}" of file ${e} is still generating`), this.fileId = e, this.key = t, this.name = "DerivationPendingError";
+	}
+};
+function T(e, t) {
+	return {
+		method: "GET",
+		credentials: "omit",
+		headers: { Authorization: `Bearer ${e}` },
+		signal: t
+	};
+}
+function E(e) {
+	return `${e}${e.includes("?") ? "&" : "?"}disposition=attachment`;
+}
+async function D(n, r) {
+	let i = await e(), a = await fetch(n, T(i, r));
+	if (a.status !== 401) return a;
+	t();
+	let o = await e();
+	return fetch(n, T(o, r));
+}
+async function O(e, t, r) {
+	if (!n()) throw Error("resolveEmbedFileSrc called outside embed token mode");
+	let i = await D(C(e, t), r);
+	if (i.status === 202 && typeof t == "object") throw new w(e, t.derivation);
+	if (!i.ok) throw Error(`embed file url request failed: ${i.status} ${i.statusText}`);
+	let a = await i.json();
+	if (!S(a)) throw Error("embed file url response is malformed");
+	if (!a.proxy) return {
+		url: a.url,
+		kind: "direct"
+	};
+	if (!a.url.startsWith("/api/files/")) throw Error(`embed file proxy: refusing non-files-route URL ${JSON.stringify(a.url)}`);
+	let o = await D(t === "download" ? E(a.url) : a.url, r);
+	if (!o.ok) throw Error(`embed file proxy fetch failed: ${o.status} ${o.statusText}`);
+	let s = await o.blob();
+	return {
+		url: URL.createObjectURL(s),
+		kind: "blob"
+	};
+}
+//#endregion
 //#region src/components/file-widgets/useEmbedFileSrc.ts
 function k(e) {
 	return typeof e == "object" ? `derivation:${e.derivation}` : e;
@@ -148,50 +148,50 @@ function k(e) {
 function A(e) {
 	return e.startsWith("derivation:") ? { derivation: e.slice(11) } : e === "download" ? "download" : "preview";
 }
-function j(t, n, r) {
-	let a = k(n), [s, c] = o(() => e() ? void 0 : r);
+function j(e, t, r) {
+	let a = k(t), [s, c] = o(() => n() ? void 0 : r);
 	return i(() => {
-		e() || c(r);
+		n() || c(r);
 	}, [r]), i(() => {
-		if (!e()) return;
-		if (!t) {
+		if (!n()) return;
+		if (!e) {
 			c(void 0);
 			return;
 		}
-		let n = null, r = !1, i = new AbortController();
-		return c(void 0), m(t, A(a), i.signal).then((e) => {
+		let t = null, r = !1, i = new AbortController();
+		return c(void 0), O(e, A(a), i.signal).then((e) => {
 			if (r) {
 				e.kind === "blob" && URL.revokeObjectURL(e.url);
 				return;
 			}
-			e.kind === "blob" && (n = e.url), c(e.url);
+			e.kind === "blob" && (t = e.url), c(e.url);
 		}).catch((e) => {
 			if (!r) {
-				if (e instanceof u) {
+				if (e instanceof w) {
 					c(void 0);
 					return;
 				}
 				e instanceof DOMException && e.name === "AbortError" || (console.error("[declarion-embed] file src resolution failed:", e), c(void 0));
 			}
 		}), () => {
-			r = !0, i.abort(), n && URL.revokeObjectURL(n);
+			r = !0, i.abort(), t && URL.revokeObjectURL(t);
 		};
-	}, [t, a]), s;
+	}, [e, a]), s;
 }
 function M() {
-	let t = a([]);
+	let e = a([]);
 	return i(() => () => {
-		for (let e of t.current) URL.revokeObjectURL(e);
-		t.current = [];
-	}, []), { open: r((n, r, i) => {
-		if (!e()) {
+		for (let t of e.current) URL.revokeObjectURL(t);
+		e.current = [];
+	}, []), { open: r((t, r, i) => {
+		if (!n()) {
 			i && window.open(i, "_blank", "noopener");
 			return;
 		}
-		n && m(n, r).then((e) => {
-			e.kind === "blob" && t.current.push(e.url), window.open(e.url, "_blank", "noopener");
+		t && O(t, r).then((t) => {
+			t.kind === "blob" && e.current.push(t.url), window.open(t.url, "_blank", "noopener");
 		}).catch((e) => {
-			e instanceof u || console.error("[declarion-embed] file open failed:", e);
+			e instanceof w || console.error("[declarion-embed] file open failed:", e);
 		});
 	}, []) };
 }
@@ -207,4 +207,4 @@ function F(e) {
 	return e ? Array.isArray(e) ? e.filter(N) : N(e) ? [e] : [] : [];
 }
 //#endregion
-export { b as a, C as c, E as d, v as f, j as i, w as l, P as n, S as o, O as p, M as r, D as s, F as t, x as u };
+export { f as a, h as c, v as d, u as f, j as i, g as l, P as n, m as o, b as p, M as r, y as s, F as t, p as u };