@kortix/sdk 0.13.4 → 0.13.7

package/dist/core/session/open-bundle.js

@@ -0,0 +1,183 @@
+/**
+ * ONE session-open read, shared by every consumer that would otherwise issue
+ * its own.
+ *
+ * THE PROBLEM. Opening a session made 6 serial control-plane round trips before
+ * the first honest frame — the session row, `/turn`, `/prompts`,
+ * `/transcript?shape=sync`, `/detail`, `/model-defaults` — and then kept making
+ * them, because the hooks that need those facts each own their own query. On a
+ * real deployment that is 0.3-2.3 s per read at the median (measured over 20
+ * session opens, 2026-08-26), and the last one cannot start until the first
+ * lands.
+ *
+ * THE SHAPE. `GET .../open-bundle` answers all of it at once, and this module
+ * is the seam that lets the EXISTING consumers use it without knowing it exists:
+ *
+ *   1. The open path calls `openSessionBundle()` ONCE, in a LAYOUT effect. React
+ *      runs every layout effect, tree-wide, before any passive effect, and
+ *      TanStack starts a query's fetch from a passive effect — so the bundle is
+ *      always in flight before the first `/turn` or `/prompts` fetch begins.
+ *   2. Each consumer's own `queryFn` calls `claimOpenBundle()` FIRST. A claim
+ *      returns the shared promise while the bundle is in flight, or the resolved
+ *      bundle inside a short share window, and `null` otherwise.
+ *   3. `null` means "answer the way you always did". Every consumer keeps its
+ *      own endpoint, so an old server, a failed bundle and a steady-state poll
+ *      all still work. The bundle is an ACCELERATOR, never a dependency.
+ *
+ * WHY A CLAIM CANNOT START ONE. A `/turn` poll that could start a bundle would
+ * re-read the transcript and the model catalogue every 15 s for the life of the
+ * tab. Starting is the open path's decision; claiming is everyone else's.
+ *
+ * WHY THE TRANSCRIPT IS A SEPARATE, ONE-SHOT STASH. The mirror is hydrated once
+ * the session's OpenCode root is known, which on a cold box is 18.9-24.5 s after
+ * the open (measured) — long past the share window the turn and queue legs want.
+ * It is also the one leg that must never be served twice: a second hydrate over
+ * a store the runtime has already filled is how a transcript grows ghosts.
+ *
+ * EVERY LEG IS TRI-STATE. `known: false` projects to `null`, which sends the
+ * consumer to its endpoint. It must never project to the NEGATIVE answer — an
+ * empty queue, an idle turn, an empty thread — because a default rendered as an
+ * answer is the defect the bundle exists to remove.
+ */
+import { getSessionOpenBundle, } from '../rest/projects-client/sessions.js';
+/**
+ * How long a resolved bundle keeps answering claims.
+ *
+ * It only has to outlast ONE session open's burst of first reads, not the
+ * session. Long enough and the steady-state `/turn` poll (5 s working / 15 s
+ * idle) would be answered from a snapshot instead of from the server; this
+ * window sits just under the fastest of those cadences on purpose.
+ */
+export const OPEN_BUNDLE_SHARE_MS = 5_000;
+/** How long the one-shot transcript stash survives. Sized for the slowest
+ *  measured cold box (24.5 s Platinum) with headroom, because the hydrate that
+ *  consumes it cannot run until the runtime identity resolves. */
+export const OPEN_BUNDLE_TRANSCRIPT_TTL_MS = 60_000;
+/** The mirrored-message window an open asks for — the same span the sync
+ *  controller's own first read covers. */
+export const OPEN_BUNDLE_TRANSCRIPT_LIMIT = 40;
+const entries = new Map();
+const transcripts = new Map();
+function scopeKey(projectId, sessionId) {
+    return `${projectId}/${sessionId}`;
+}
+/** Drop everything. Tests only — a module singleton with no reset is a test
+ *  that passes because of the one before it. */
+export function resetSessionOpenBundles() {
+    entries.clear();
+    transcripts.clear();
+}
+/**
+ * Start the session-open read for `(projectId, sessionId)`.
+ *
+ * Fire-and-forget and idempotent within the share window: calling it twice for
+ * one open (two hooks, StrictMode's double mount) issues one request. Never
+ * throws and never rejects — a failed bundle simply resolves `null` and every
+ * consumer falls back to its own endpoint.
+ */
+export function openSessionBundle(projectId, sessionId, options = {}) {
+    if (!projectId || !sessionId)
+        return;
+    const now = options.now ?? Date.now;
+    const nowMs = now();
+    const key = scopeKey(projectId, sessionId);
+    const existing = entries.get(key);
+    if (existing && claimable(existing, nowMs))
+        return;
+    const entry = {
+        startedAtMs: nowMs,
+        settledAtMs: null,
+        promise: getSessionOpenBundle(projectId, sessionId, {
+            transcript: options.transcript ?? OPEN_BUNDLE_TRANSCRIPT_LIMIT,
+        })
+            .then((bundle) => {
+            stashTranscript(key, bundle, now());
+            return bundle;
+        })
+            .catch(() => null),
+    };
+    entry.promise = entry.promise.then((bundle) => {
+        entry.settledAtMs = now();
+        return bundle;
+    });
+    entries.set(key, entry);
+}
+function claimable(entry, nowMs) {
+    // In flight is always claimable: the consumer that asks is precisely the one
+    // this read was started for.
+    if (entry.settledAtMs === null)
+        return true;
+    return nowMs - entry.settledAtMs <= OPEN_BUNDLE_SHARE_MS;
+}
+/**
+ * Claim the in-flight or freshly-resolved bundle for this session.
+ *
+ * Returns the shared promise, or `null` when there is nothing to share — which
+ * is the signal to read the endpoint the normal way. Synchronous in the `null`
+ * case on purpose: a consumer must be able to decide without awaiting.
+ */
+export function claimOpenBundle(projectId, sessionId, nowMs = Date.now()) {
+    if (!projectId || !sessionId)
+        return null;
+    const key = scopeKey(projectId, sessionId);
+    const entry = entries.get(key);
+    if (!entry)
+        return null;
+    if (!claimable(entry, nowMs)) {
+        entries.delete(key);
+        return null;
+    }
+    return entry.promise;
+}
+/**
+ * Project the turn leg. `null` for an unknown leg — never `{ turns: [] }`,
+ * which would be an idle claim made by something that did not know.
+ */
+export function openBundleTurn(bundle) {
+    const turn = bundle.turn;
+    if (!turn || turn.known !== true)
+        return null;
+    const observedAtMs = Date.parse(bundle.observed_at);
+    return {
+        turns: turn.turns ?? [],
+        last_ended: turn.last_ended,
+        atMs: Number.isFinite(observedAtMs) ? observedAtMs : Date.now(),
+    };
+}
+/** Project the queue leg. `null` for an unknown leg — never `[]`, which would
+ *  render as "nothing queued" for a queue nobody could read. */
+export function openBundleQueue(bundle) {
+    const queue = bundle.queue;
+    if (!queue || queue.known !== true)
+        return null;
+    return queue.prompts ?? [];
+}
+function stashTranscript(key, bundle, nowMs) {
+    const transcript = bundle.transcript;
+    if (!transcript || transcript.known !== true || transcript.requested !== true)
+        return;
+    // An unavailable mirror is not a transcript. Stashing it would let a hydrate
+    // paint an empty thread as a complete one.
+    if (!transcript.available || transcript.messages.length === 0)
+        return;
+    const { known: _known, requested: _requested, ...envelope } = transcript;
+    transcripts.set(key, { envelope, stashedAtMs: nowMs });
+}
+/**
+ * Take the mirrored transcript this open fetched, ONCE.
+ *
+ * One-shot by design: the hydrate that consumes it is the only reader that may
+ * paint a snapshot, and a second paint over a store the runtime has already
+ * filled is how a transcript grows ghosts.
+ */
+export function takeOpenBundleTranscript(projectId, sessionId, nowMs = Date.now()) {
+    const key = scopeKey(projectId, sessionId);
+    const stash = transcripts.get(key);
+    if (!stash)
+        return null;
+    transcripts.delete(key);
+    if (nowMs - stash.stashedAtMs > OPEN_BUNDLE_TRANSCRIPT_TTL_MS)
+        return null;
+    return stash.envelope;
+}
+//# sourceMappingURL=open-bundle.js.map

package/dist/core/session/open-bundle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"open-bundle.js","sourceRoot":"","sources":["../../../src/core/session/open-bundle.ts"],"names":[],"mappings":"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"}

package/dist/core/session/poll-owner.d.ts

@@ -0,0 +1,35 @@
+/**
+ * ONE cadence per session fact, however many components read it.
+ *
+ * THE PROBLEM. TanStack schedules `refetchInterval` PER OBSERVER, not per
+ * query. Three hooks mount the `/turn` query on a session route (`useSession`,
+ * the composer, the session panel) and two mount `/prompts`, so one key ran
+ * three timers and the session was polled at three times its declared cadence.
+ * Measured on a real deployment: 6 `GET .../turn` inside a single 25 s session
+ * open, against a 5 s working / 15 s idle contract.
+ *
+ * THE RULE. Exactly one observer per scope owns the interval; the rest pass
+ * `refetchInterval: false` and read the same cache entry the owner refreshes.
+ * They share a query key, so an answer reaches every observer either way —
+ * only the SCHEDULING is exclusive.
+ *
+ * OWNERSHIP MUST SURVIVE THE OWNER. A session whose only poller unmounted would
+ * stop learning that a turn started somewhere else (a trigger, a second device,
+ * the inbox delivering a queued prompt), so releasing hands the cadence to the
+ * next claimant and notifies it.
+ *
+ * Framework-free on purpose: `react/use-poll-owner.ts` is a thin
+ * `useSyncExternalStore` over this, and the rules live where they can be tested
+ * without rendering anything.
+ */
+/** Register `id` as a candidate poller for `scope`. Idempotent. */
+export declare function claimPoller(scope: string, id: string): void;
+/** Give up `id`'s claim. If it held the cadence, the next claimant takes it. */
+export declare function releasePoller(scope: string, id: string): void;
+/** Does `id` own `scope`'s cadence right now? */
+export declare function isPollOwner(scope: string, id: string): boolean;
+/** Re-render me when this scope's owner changes. Returns the unsubscribe. */
+export declare function subscribePollOwner(scope: string, listener: () => void): () => void;
+/** Drop everything. Tests only. */
+export declare function resetPollOwners(): void;
+//# sourceMappingURL=poll-owner.d.ts.map

package/dist/core/session/poll-owner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"poll-owner.d.ts","sourceRoot":"","sources":["../../../src/core/session/poll-owner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AA8BH,mEAAmE;AACnE,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAO3D;AAED,gFAAgF;AAChF,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAS7D;AAED,iDAAiD;AACjD,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAI9D;AAED,6EAA6E;AAC7E,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAOlF;AAED,mCAAmC;AACnC,wBAAgB,eAAe,IAAI,IAAI,CAEtC"}

package/dist/core/session/poll-owner.js

@@ -0,0 +1,90 @@
+/**
+ * ONE cadence per session fact, however many components read it.
+ *
+ * THE PROBLEM. TanStack schedules `refetchInterval` PER OBSERVER, not per
+ * query. Three hooks mount the `/turn` query on a session route (`useSession`,
+ * the composer, the session panel) and two mount `/prompts`, so one key ran
+ * three timers and the session was polled at three times its declared cadence.
+ * Measured on a real deployment: 6 `GET .../turn` inside a single 25 s session
+ * open, against a 5 s working / 15 s idle contract.
+ *
+ * THE RULE. Exactly one observer per scope owns the interval; the rest pass
+ * `refetchInterval: false` and read the same cache entry the owner refreshes.
+ * They share a query key, so an answer reaches every observer either way —
+ * only the SCHEDULING is exclusive.
+ *
+ * OWNERSHIP MUST SURVIVE THE OWNER. A session whose only poller unmounted would
+ * stop learning that a turn started somewhere else (a trigger, a second device,
+ * the inbox delivering a queued prompt), so releasing hands the cadence to the
+ * next claimant and notifies it.
+ *
+ * Framework-free on purpose: `react/use-poll-owner.ts` is a thin
+ * `useSyncExternalStore` over this, and the rules live where they can be tested
+ * without rendering anything.
+ */
+const scopes = new Map();
+function stateFor(scope) {
+    let state = scopes.get(scope);
+    if (!state) {
+        state = { claimants: [], listeners: new Set() };
+        scopes.set(scope, state);
+    }
+    return state;
+}
+function notify(state) {
+    for (const listener of state.listeners)
+        listener();
+}
+function forget(scope, state) {
+    // Leak hygiene: a per-session registry that never shrinks is a per-session
+    // leak. A scope with no claimants and no listeners has nothing to remember.
+    if (state.claimants.length === 0 && state.listeners.size === 0)
+        scopes.delete(scope);
+}
+/** Register `id` as a candidate poller for `scope`. Idempotent. */
+export function claimPoller(scope, id) {
+    if (!scope || !id)
+        return;
+    const state = stateFor(scope);
+    if (state.claimants.includes(id))
+        return;
+    const wasOwner = state.claimants[0];
+    state.claimants.push(id);
+    if (state.claimants[0] !== wasOwner)
+        notify(state);
+}
+/** Give up `id`'s claim. If it held the cadence, the next claimant takes it. */
+export function releasePoller(scope, id) {
+    const state = scopes.get(scope);
+    if (!state)
+        return;
+    const index = state.claimants.indexOf(id);
+    if (index === -1)
+        return;
+    const wasOwner = state.claimants[0];
+    state.claimants.splice(index, 1);
+    if (state.claimants[0] !== wasOwner)
+        notify(state);
+    forget(scope, state);
+}
+/** Does `id` own `scope`'s cadence right now? */
+export function isPollOwner(scope, id) {
+    const state = scopes.get(scope);
+    if (!state)
+        return false;
+    return state.claimants[0] === id;
+}
+/** Re-render me when this scope's owner changes. Returns the unsubscribe. */
+export function subscribePollOwner(scope, listener) {
+    const state = stateFor(scope);
+    state.listeners.add(listener);
+    return () => {
+        state.listeners.delete(listener);
+        forget(scope, state);
+    };
+}
+/** Drop everything. Tests only. */
+export function resetPollOwners() {
+    scopes.clear();
+}
+//# sourceMappingURL=poll-owner.js.map

package/dist/core/session/poll-owner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"poll-owner.js","sourceRoot":"","sources":["../../../src/core/session/poll-owner.ts"],"names":[],"mappings":"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"}

package/dist/core/session/preview-auth.d.ts

@@ -29,4 +29,29 @@
 export declare function ensurePreviewSessionCookie(previewUrl: string, options?: {
     serverUrl?: string;
 }): Promise<boolean>;
+/**
+ * The URL a caller should actually open for `previewUrl`, having given it a
+ * credential the destination will accept.
+ *
+ * The two preview forms take credentials in different ways, and using the wrong
+ * one fails silently — which is exactly what happened before this existed:
+ * `ensurePreviewSessionCookie` returns false for an ORIGIN URL (there is no
+ * `/v1/p/` path to derive an auth endpoint from), so "open in a new tab" opened
+ * the origin with no cookie and no token, and the person landed on the sign-in
+ * gate instead of their file.
+ *
+ *   - Preview ORIGIN (`{env}-p{port}-{sandbox}.{domain}`, or the localhost
+ *     form): the API's `__preview_session` cookie is host-scoped and can never
+ *     reach it, so the credential rides in the URL as a one-shot `?token`. The
+ *     proxy exchanges it for a host cookie and strips it from the address bar.
+ *   - Path proxy (`/v1/p/{sandbox}/{port}/…`): same origin as the API, so the
+ *     cookie works; mint it and return the URL untouched.
+ *
+ * Never throws. With no token, or for a URL that is not a preview at all, the
+ * input is returned unchanged — the destination then answers for itself, which
+ * is more honest than fabricating a URL that cannot work.
+ */
+export declare function authorizePreviewUrl(previewUrl: string, options?: {
+    serverUrl?: string;
+}): Promise<string>;
 //# sourceMappingURL=preview-auth.d.ts.map

package/dist/core/session/preview-auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"preview-auth.d.ts","sourceRoot":"","sources":["../../../src/core/session/preview-auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAKH;;;;;;;;GAQG;AACH,wBAAsB,0BAA0B,CAC9C,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GACnC,OAAO,CAAC,OAAO,CAAC,CAoBlB"}
+{"version":3,"file":"preview-auth.d.ts","sourceRoot":"","sources":["../../../src/core/session/preview-auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAKH;;;;;;;;GAQG;AACH,wBAAsB,0BAA0B,CAC9C,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GACnC,OAAO,CAAC,OAAO,CAAC,CAoBlB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,mBAAmB,CACvC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GACnC,OAAO,CAAC,MAAM,CAAC,CAOjB"}

package/dist/core/session/preview-auth.js

@@ -18,7 +18,7 @@
  * reloaded, bookmarked, or sent to anyone.
  */
 import { getAuthToken } from '../http/auth.js';
-import { buildPreviewAuthEndpoint } from './preview.js';
+import { appendPreviewToken, buildPreviewAuthEndpoint, isSubdomainPreviewUrl } from './preview.js';
 /**
  * Mint the `__preview_session` cookie for `previewUrl`'s proxy origin.
  *
@@ -50,4 +50,34 @@ export async function ensurePreviewSessionCookie(previewUrl, options = {}) {
         return false;
     }
 }
+/**
+ * The URL a caller should actually open for `previewUrl`, having given it a
+ * credential the destination will accept.
+ *
+ * The two preview forms take credentials in different ways, and using the wrong
+ * one fails silently — which is exactly what happened before this existed:
+ * `ensurePreviewSessionCookie` returns false for an ORIGIN URL (there is no
+ * `/v1/p/` path to derive an auth endpoint from), so "open in a new tab" opened
+ * the origin with no cookie and no token, and the person landed on the sign-in
+ * gate instead of their file.
+ *
+ *   - Preview ORIGIN (`{env}-p{port}-{sandbox}.{domain}`, or the localhost
+ *     form): the API's `__preview_session` cookie is host-scoped and can never
+ *     reach it, so the credential rides in the URL as a one-shot `?token`. The
+ *     proxy exchanges it for a host cookie and strips it from the address bar.
+ *   - Path proxy (`/v1/p/{sandbox}/{port}/…`): same origin as the API, so the
+ *     cookie works; mint it and return the URL untouched.
+ *
+ * Never throws. With no token, or for a URL that is not a preview at all, the
+ * input is returned unchanged — the destination then answers for itself, which
+ * is more honest than fabricating a URL that cannot work.
+ */
+export async function authorizePreviewUrl(previewUrl, options = {}) {
+    if (isSubdomainPreviewUrl(previewUrl)) {
+        const token = await getAuthToken();
+        return token ? appendPreviewToken(previewUrl, token) : previewUrl;
+    }
+    await ensurePreviewSessionCookie(previewUrl, options);
+    return previewUrl;
+}
 //# sourceMappingURL=preview-auth.js.map

package/dist/core/session/preview-auth.js.map

@@ -1 +1 @@
-{"version":3,"file":"preview-auth.js","sourceRoot":"","sources":["../../../src/core/session/preview-auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAC;AAErD;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC9C,UAAkB,EAClB,UAAkC,EAAE;IAEpC,MAAM,YAAY,GAAG,wBAAwB,CAAC,UAAU,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;IAC7E,IAAI,CAAC,YAAY;QAAE,OAAO,KAAK,CAAC;IAEhC,MAAM,KAAK,GAAG,MAAM,YAAY,EAAE,CAAC;IACnC,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IAEzB,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,YAAY,EAAE;YACzC,MAAM,EAAE,MAAM;YACd,WAAW,EAAE,SAAS;YACtB,OAAO,EAAE;gBACP,aAAa,EAAE,UAAU,KAAK,EAAE;gBAChC,cAAc,EAAE,kBAAkB;aACnC;SACF,CAAC,CAAC;QACH,OAAO,QAAQ,CAAC,EAAE,CAAC;IACrB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}
+{"version":3,"file":"preview-auth.js","sourceRoot":"","sources":["../../../src/core/session/preview-auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAEhG;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC9C,UAAkB,EAClB,UAAkC,EAAE;IAEpC,MAAM,YAAY,GAAG,wBAAwB,CAAC,UAAU,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;IAC7E,IAAI,CAAC,YAAY;QAAE,OAAO,KAAK,CAAC;IAEhC,MAAM,KAAK,GAAG,MAAM,YAAY,EAAE,CAAC;IACnC,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IAEzB,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,YAAY,EAAE;YACzC,MAAM,EAAE,MAAM;YACd,WAAW,EAAE,SAAS;YACtB,OAAO,EAAE;gBACP,aAAa,EAAE,UAAU,KAAK,EAAE;gBAChC,cAAc,EAAE,kBAAkB;aACnC;SACF,CAAC,CAAC;QACH,OAAO,QAAQ,CAAC,EAAE,CAAC;IACrB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,UAAkB,EAClB,UAAkC,EAAE;IAEpC,IAAI,qBAAqB,CAAC,UAAU,CAAC,EAAE,CAAC;QACtC,MAAM,KAAK,GAAG,MAAM,YAAY,EAAE,CAAC;QACnC,OAAO,KAAK,CAAC,CAAC,CAAC,kBAAkB,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC;IACpE,CAAC;IACD,MAAM,0BAA0B,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IACtD,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/dist/core/session/preview-config.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The cached template for a backend, or null when this deployment serves none —
+ * and also null before the first `load` resolves. Both mean "use the path form",
+ * which is why they need no distinction at the call site.
+ */
+export declare function cachedPreviewUrlTemplate(backendUrl: string): string | null;
+/**
+ * Whether this backend has ANSWERED yet — as opposed to "answered null", which
+ * is a real answer meaning "this deployment serves no preview domain".
+ *
+ * The two look identical through `cachedPreviewUrlTemplate`, and conflating them
+ * is how a session gets stuck: during a rolling deploy the first `ensureReady()`
+ * can hit a task that predates `/v1/p/config`, and without this the handle would
+ * keep building path-proxy URLs for the rest of its life even though every later
+ * request would have been answered by a new task.
+ */
+export declare function hasPreviewConfig(backendUrl: string): boolean;
+/**
+ * Fetch and cache the template. Concurrent callers share one request; a failed
+ * fetch caches nothing, so a deployment that was briefly unreachable is asked
+ * again rather than being remembered as having no preview domain.
+ */
+export declare function loadPreviewUrlTemplate(backendUrl: string): Promise<string | null>;
+/** Drop everything remembered — for tests and for a host re-pointing its API. */
+export declare function resetPreviewConfigCache(): void;
+//# sourceMappingURL=preview-config.d.ts.map

package/dist/core/session/preview-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview-config.d.ts","sourceRoot":"","sources":["../../../src/core/session/preview-config.ts"],"names":[],"mappings":"AAiCA;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAE1E;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAE5D;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAgCvF;AAED,iFAAiF;AACjF,wBAAgB,uBAAuB,IAAI,IAAI,CAG9C"}

package/dist/core/session/preview-config.js

@@ -0,0 +1,95 @@
+/**
+ * How this deployment addresses previews, fetched once from `GET /v1/p/config`.
+ *
+ * The preview hostname shape (`{env}-p{port}-{sandbox}.{domain}`) is a property
+ * of the deployment, not of the client: it depends on the wildcard domain the
+ * operator serves and on which environment the API is. Re-deriving it here from
+ * `backendUrl` would mean two implementations of one rule, which is how they
+ * drift. So the API states it as a template and this caches the answer.
+ *
+ * `previewUrl()` is synchronous — a React render calls it — so the fetch cannot
+ * happen there. `ensureReady()` warms this first, and until it resolves callers
+ * get the path form, which still works for everything that is not a browser.
+ */
+import { backendApi } from '../http/api-client.js';
+const templates = new Map();
+const inFlight = new Map();
+/**
+ * Cache key: the backend URL without trailing slashes, stripped LINEARLY. The
+ * regex form (`/\/+$/`) backtracks quadratically on adversarial input (CodeQL
+ * js/polynomial-redos), and this runs on a host-supplied string.
+ */
+function key(backendUrl) {
+    let end = backendUrl.length;
+    while (end > 0 && backendUrl.charCodeAt(end - 1) === 47 /* '/' */)
+        end--;
+    return backendUrl.slice(0, end);
+}
+/**
+ * The cached template for a backend, or null when this deployment serves none —
+ * and also null before the first `load` resolves. Both mean "use the path form",
+ * which is why they need no distinction at the call site.
+ */
+export function cachedPreviewUrlTemplate(backendUrl) {
+    return templates.get(key(backendUrl)) ?? null;
+}
+/**
+ * Whether this backend has ANSWERED yet — as opposed to "answered null", which
+ * is a real answer meaning "this deployment serves no preview domain".
+ *
+ * The two look identical through `cachedPreviewUrlTemplate`, and conflating them
+ * is how a session gets stuck: during a rolling deploy the first `ensureReady()`
+ * can hit a task that predates `/v1/p/config`, and without this the handle would
+ * keep building path-proxy URLs for the rest of its life even though every later
+ * request would have been answered by a new task.
+ */
+export function hasPreviewConfig(backendUrl) {
+    return templates.has(key(backendUrl));
+}
+/**
+ * Fetch and cache the template. Concurrent callers share one request; a failed
+ * fetch caches nothing, so a deployment that was briefly unreachable is asked
+ * again rather than being remembered as having no preview domain.
+ */
+export async function loadPreviewUrlTemplate(backendUrl) {
+    const cacheKey = key(backendUrl);
+    const cached = templates.get(cacheKey);
+    if (cached !== undefined)
+        return cached;
+    const pending = inFlight.get(cacheKey);
+    if (pending)
+        return pending;
+    const request = (async () => {
+        try {
+            const response = await backendApi.get('/p/config', {
+                showErrors: false,
+                // A deployment without a preview domain, and an API too old to know the
+                // route, are both ordinary answers — not incidents to report.
+                errorContext: { operation: 'load preview config', silent: true },
+            });
+            if (!response.success)
+                return null;
+            const template = typeof response.data?.preview_url_template === 'string'
+                ? response.data.preview_url_template
+                : null;
+            templates.set(cacheKey, template);
+            return template;
+        }
+        catch {
+            // An older API has no such route, and a network blip is not an answer.
+            // Leave the cache empty so the next ensureReady() asks again.
+            return null;
+        }
+        finally {
+            inFlight.delete(cacheKey);
+        }
+    })();
+    inFlight.set(cacheKey, request);
+    return request;
+}
+/** Drop everything remembered — for tests and for a host re-pointing its API. */
+export function resetPreviewConfigCache() {
+    templates.clear();
+    inFlight.clear();
+}
+//# sourceMappingURL=preview-config.js.map

package/dist/core/session/preview-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview-config.js","sourceRoot":"","sources":["../../../src/core/session/preview-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAMhD,MAAM,SAAS,GAAG,IAAI,GAAG,EAAyB,CAAC;AACnD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkC,CAAC;AAE3D;;;;GAIG;AACH,SAAS,GAAG,CAAC,UAAkB;IAC7B,IAAI,GAAG,GAAG,UAAU,CAAC,MAAM,CAAC;IAC5B,OAAO,GAAG,GAAG,CAAC,IAAI,UAAU,CAAC,UAAU,CAAC,GAAG,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,SAAS;QAAE,GAAG,EAAE,CAAC;IACzE,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AAClC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,wBAAwB,CAAC,UAAkB;IACzD,OAAO,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,IAAI,IAAI,CAAC;AAChD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAAC,UAAkB;IACjD,OAAO,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC;AACxC,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,UAAkB;IAC7D,MAAM,QAAQ,GAAG,GAAG,CAAC,UAAU,CAAC,CAAC;IACjC,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACvC,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC;IACxC,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACvC,IAAI,OAAO;QAAE,OAAO,OAAO,CAAC;IAE5B,MAAM,OAAO,GAAG,CAAC,KAAK,IAAI,EAAE;QAC1B,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,UAAU,CAAC,GAAG,CAAwB,WAAW,EAAE;gBACxE,UAAU,EAAE,KAAK;gBACjB,wEAAwE;gBACxE,8DAA8D;gBAC9D,YAAY,EAAE,EAAE,SAAS,EAAE,qBAAqB,EAAE,MAAM,EAAE,IAAI,EAAE;aACjE,CAAC,CAAC;YACH,IAAI,CAAC,QAAQ,CAAC,OAAO;gBAAE,OAAO,IAAI,CAAC;YACnC,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC,IAAI,EAAE,oBAAoB,KAAK,QAAQ;gBACtE,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,oBAAoB;gBACpC,CAAC,CAAC,IAAI,CAAC;YACT,SAAS,CAAC,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;YAClC,OAAO,QAAQ,CAAC;QAClB,CAAC;QAAC,MAAM,CAAC;YACP,uEAAuE;YACvE,8DAA8D;YAC9D,OAAO,IAAI,CAAC;QACd,CAAC;gBAAS,CAAC;YACT,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC,CAAC,EAAE,CAAC;IAEL,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAChC,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,uBAAuB;IACrC,SAAS,CAAC,KAAK,EAAE,CAAC;IAClB,QAAQ,CAAC,KAAK,EAAE,CAAC;AACnB,CAAC"}

package/dist/core/session/preview-options.d.ts

@@ -0,0 +1,25 @@
+import type { SubdomainUrlOptions } from './url.js';
+/**
+ * A fully-resolved options bag. Every field required — including
+ * `previewUrlTemplate`, whose `null` means "this deployment serves no preview
+ * domain" and is a real answer, not an omission.
+ */
+export interface ResolvedPreviewOptions extends SubdomainUrlOptions {
+    previewUrlTemplate: string | null;
+}
+/**
+ * Resolve preview options for a sandbox against a backend.
+ *
+ * Reads the deployment's answer from the `GET /v1/p/config` cache, and asks
+ * again in the background when this backend has never answered — a rolling
+ * deploy can serve one request from a task that predates the route, and without
+ * the retry that single miss would pin the caller to the path proxy for its
+ * whole life. A backend that answered "no preview domain" HAS answered and is
+ * not re-asked.
+ */
+export declare function resolvePreviewOptions(input: {
+    sandboxId: string;
+    apiBaseUrl: string;
+    backendPort: number;
+}): ResolvedPreviewOptions;
+//# sourceMappingURL=preview-options.d.ts.map

package/dist/core/session/preview-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview-options.d.ts","sourceRoot":"","sources":["../../../src/core/session/preview-options.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,OAAO,CAAC;AAEjD;;;;GAIG;AACH,MAAM,WAAW,sBAAuB,SAAQ,mBAAmB;IACjE,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB,GAAG,sBAAsB,CASzB"}

package/dist/core/session/preview-options.js

@@ -0,0 +1,45 @@
+/**
+ * The ONE way to build the options a preview URL is derived from.
+ *
+ * `rewriteLocalhostUrl` and its siblings in `url.ts` are pure: they answer
+ * "which URL" from an options bag and never touch the network. That purity is
+ * worth keeping — it is why they are exhaustively testable — but it puts the
+ * burden of assembling a COMPLETE bag on whoever calls them, and an incomplete
+ * bag does not fail. It falls back to the path proxy, silently, forever.
+ *
+ * That is not hypothetical. There are two call paths — a session handle
+ * (`kortix.session(...).previewUrl()`) and the ambient runtime
+ * (`deriveSubdomainOpts`, which the web app's preview iframe, `useSandboxProxy`
+ * and `buildStaticFilePreviewUrl` all use) — and each assembled the bag itself.
+ * When `previewUrlTemplate` was added, only the first was updated, so every
+ * preview in the session panel kept rendering `/v1/p/{sandbox}/{port}` however
+ * loudly the deployment advertised an origin. Nothing failed; the wrong thing
+ * merely kept working.
+ *
+ * So: one producer, and a return type whose fields are all REQUIRED. A future
+ * call path that forgets a field does not compile, which is the only kind of
+ * guarantee worth having for a failure mode this quiet.
+ */
+import { cachedPreviewUrlTemplate, hasPreviewConfig, loadPreviewUrlTemplate } from './preview-config.js';
+/**
+ * Resolve preview options for a sandbox against a backend.
+ *
+ * Reads the deployment's answer from the `GET /v1/p/config` cache, and asks
+ * again in the background when this backend has never answered — a rolling
+ * deploy can serve one request from a task that predates the route, and without
+ * the retry that single miss would pin the caller to the path proxy for its
+ * whole life. A backend that answered "no preview domain" HAS answered and is
+ * not re-asked.
+ */
+export function resolvePreviewOptions(input) {
+    const { apiBaseUrl } = input;
+    if (!hasPreviewConfig(apiBaseUrl))
+        void loadPreviewUrlTemplate(apiBaseUrl).catch(() => { });
+    return {
+        sandboxId: input.sandboxId,
+        backendPort: input.backendPort,
+        apiBaseUrl,
+        previewUrlTemplate: cachedPreviewUrlTemplate(apiBaseUrl),
+    };
+}
+//# sourceMappingURL=preview-options.js.map

package/dist/core/session/preview-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview-options.js","sourceRoot":"","sources":["../../../src/core/session/preview-options.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,wBAAwB,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAYtG;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAIrC;IACC,MAAM,EAAE,UAAU,EAAE,GAAG,KAAK,CAAC;IAC7B,IAAI,CAAC,gBAAgB,CAAC,UAAU,CAAC;QAAE,KAAK,sBAAsB,CAAC,UAAU,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IAC3F,OAAO;QACL,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,UAAU;QACV,kBAAkB,EAAE,wBAAwB,CAAC,UAAU,CAAC;KACzD,CAAC;AACJ,CAAC"}

package/dist/core/session/preview.d.ts

@@ -14,9 +14,14 @@
  */
 export declare function buildPreviewAuthEndpoint(previewUrl: string, serverUrl?: string): string | null;
 /**
- * Subdomain preview form: `p{port}-{sandbox}.{host}/…`. These can't use the
- * host-only `/v1/p/` session cookie (it never reaches the preview subdomain),
- * so they authenticate via a one-shot `?token` on the first request.
+ * Preview ORIGIN form: `p{port}-{sandbox}.{host}` locally, or the deployed
+ * `{env}-p{port}-{sandbox}.{domain}`.
+ *
+ * These can't use the host-only `/v1/p/` session cookie — it never reaches
+ * another hostname — so they authenticate the FIRST request with a one-shot
+ * `?token`, which the proxy exchanges for a cookie on the preview origin and
+ * then strips. Every later request (sub-resources, `fetch`, WebSockets) rides
+ * that cookie, which is the only credential an app's own code can carry.
  */
 export declare function isSubdomainPreviewUrl(candidateUrl: string): boolean;
 /** Append a one-shot `?token` to a (subdomain) preview URL. */