stitchkit 0.114.0 → 0.114.2

package/dist/index-p02zgk8x.js

@@ -0,0 +1,351 @@
+// src/react/keyboard/layers.ts
+var RANK = {
+  overlay: 4,
+  local: 3,
+  route: 2,
+  zone: 1,
+  global: 0
+};
+var KEY_FIELD_SELECTOR = [
+  "input:not([type=button],[type=submit],[type=reset],[type=checkbox],[type=image])",
+  "textarea",
+  "select",
+  "[contenteditable]:not([contenteditable=false])",
+  "[role=textbox]",
+  "[role=combobox]",
+  "[role=slider]",
+  "[role=spinbutton]",
+  "[data-local-keys]"
+].join(",");
+function hasClosest(target) {
+  return typeof target === "object" && target !== null && "closest" in target && typeof target.closest === "function";
+}
+function closestFromTarget(target, selectors) {
+  return hasClosest(target) ? target.closest(selectors) : null;
+}
+function isKeyFieldTarget2(target) {
+  const field = closestFromTarget(target, KEY_FIELD_SELECTOR);
+  return field !== null && field !== undefined;
+}
+function liveScope(entry) {
+  const read = entry.state.scope;
+  if (read === undefined)
+    return "unscoped";
+  const element = read();
+  if (element === null || !element.isConnected)
+    return null;
+  const inert = element.closest("[inert]");
+  if (inert !== null && inert !== undefined)
+    return null;
+  if (element.checkVisibility !== undefined && !element.checkVisibility())
+    return null;
+  return element;
+}
+function askingOrder(entries) {
+  const live = [];
+  for (const entry of entries) {
+    if (entry.state.active === false)
+      continue;
+    const scope = liveScope(entry);
+    if (scope !== null)
+      live.push({ entry, scope, depth: 0 });
+  }
+  for (const layer of live) {
+    const own = layer.scope;
+    if (own === "unscoped")
+      continue;
+    layer.depth = live.filter((other) => other !== layer && other.entry.state.kind === layer.entry.state.kind && other.scope !== "unscoped" && other.scope !== own && other.scope.contains(own)).length;
+  }
+  return live.sort((left, right) => RANK[right.entry.state.kind] - RANK[left.entry.state.kind] || right.depth - left.depth || right.entry.order - left.entry.order);
+}
+function createKeyLayerStack2(target) {
+  const entries = new Set;
+  let activations = 0;
+  const bubbling = (event) => {
+    dispatch(event, "bubble");
+  };
+  const capturing = (event) => {
+    dispatch(event, "capture");
+  };
+  const attached = { bubble: false, capture: false };
+  const phaseOf = (state) => state.phase ?? "bubble";
+  function sync() {
+    for (const phase of ["bubble", "capture"]) {
+      const wanted = [...entries].some((entry) => phaseOf(entry.state) === phase);
+      if (wanted === attached[phase])
+        continue;
+      attached[phase] = wanted;
+      const listener = phase === "capture" ? capturing : bubbling;
+      if (wanted)
+        target.addEventListener("keydown", listener, phase === "capture");
+      else
+        target.removeEventListener("keydown", listener, phase === "capture");
+    }
+  }
+  function refuseUnlessLocal(state) {
+    if (phaseOf(state) === "capture" && state.kind !== "local") {
+      throw new Error(`A ${state.kind} layer cannot listen in the capture phase; only a local layer can`);
+    }
+  }
+  function dispatch(event, phase = "bubble") {
+    if (event.defaultPrevented || event.isComposing)
+      return false;
+    const isEscape = event.key === "Escape";
+    if (isEscape && event.repeat)
+      return false;
+    const inField = !isEscape && isKeyFieldTarget2(event.target);
+    let behindOverlay = false;
+    for (const { entry } of askingOrder(entries)) {
+      const { kind } = entry.state;
+      if (behindOverlay && kind !== "overlay")
+        break;
+      if (kind === "overlay")
+        behindOverlay = true;
+      if (phaseOf(entry.state) !== phase)
+        continue;
+      if (inField && entry.state.fields !== "include")
+        continue;
+      if (entry.state.onKey(event)) {
+        event.preventDefault();
+        if (phase === "capture")
+          event.stopPropagation?.();
+        return true;
+      }
+    }
+    return false;
+  }
+  function add(state) {
+    refuseUnlessLocal(state);
+    const entry = { state, order: ++activations };
+    entries.add(entry);
+    sync();
+    return {
+      update(next) {
+        refuseUnlessLocal(next);
+        const reactivated = entry.state.active === false && next.active !== false;
+        const moved = phaseOf(entry.state) !== phaseOf(next);
+        entry.state = next;
+        if (reactivated)
+          entry.order = ++activations;
+        if (moved)
+          sync();
+      },
+      remove() {
+        if (!entries.delete(entry))
+          return;
+        sync();
+      }
+    };
+  }
+  return { add, dispatch };
+}
+
+// src/react/keyboard/zone.ts
+var ZONE_ATTRIBUTE = "data-keyboard-zone";
+function nextZoneIndex2({
+  length,
+  index,
+  move,
+  loop
+}) {
+  if (length <= 0)
+    return move === "previous" || move === "first" ? "before-start" : "after-end";
+  if (move === "first")
+    return 0;
+  if (move === "last")
+    return length - 1;
+  if (index < 0 || index >= length)
+    return move === "next" ? 0 : length - 1;
+  const target = move === "next" ? index + 1 : index - 1;
+  if (target >= 0 && target < length)
+    return target;
+  if (loop)
+    return target < 0 ? length - 1 : 0;
+  return target < 0 ? "before-start" : "after-end";
+}
+function zoneIntent(event, orientation) {
+  if (event.altKey || event.ctrlKey || event.metaKey || event.shiftKey)
+    return null;
+  const vertical = orientation === "vertical";
+  switch (event.key) {
+    case (vertical ? "ArrowDown" : "ArrowRight"):
+      return { type: "move", move: "next" };
+    case (vertical ? "ArrowUp" : "ArrowLeft"):
+      return { type: "move", move: "previous" };
+    case (vertical ? "ArrowRight" : "ArrowDown"):
+      return { type: "enter" };
+    case (vertical ? "ArrowLeft" : "ArrowUp"):
+      return { type: "exit" };
+    case "Home":
+      return { type: "move", move: "first" };
+    case "End":
+      return { type: "move", move: "last" };
+    case "Enter":
+      return { type: "confirm" };
+    default:
+      return null;
+  }
+}
+function resolveZoneIndex(items, value, pointed) {
+  if (pointed !== null) {
+    const index = items.indexOf(pointed);
+    if (index >= 0)
+      return index;
+  }
+  if (value !== null) {
+    const index = items.indexOf(value);
+    if (index >= 0)
+      return index;
+  }
+  return items.length > 0 ? 0 : -1;
+}
+function isFieldInside(target, zone) {
+  const field = closestFromTarget(target, KEY_FIELD_SELECTOR);
+  if (field === null || field === undefined || field === zone)
+    return false;
+  return closestFromTarget(field, `[${ZONE_ATTRIBUTE}]`) === zone;
+}
+function createNavZone2(initial) {
+  let options = initial;
+  let pointed = null;
+  let awaiting = null;
+  const elements = new Map;
+  const listeners = new Set;
+  const point = (id) => {
+    if (pointed === id)
+      return;
+    pointed = id;
+    for (const listener of listeners)
+      listener();
+  };
+  const chosenValue = () => options.value ?? null;
+  function currentIndex() {
+    return resolveZoneIndex(options.items, chosenValue(), pointed);
+  }
+  function current() {
+    return options.items[currentIndex()] ?? null;
+  }
+  function focusElement(element) {
+    element.focus({ preventScroll: true });
+    element.scrollIntoView?.({ block: "nearest", inline: "nearest" });
+  }
+  function focus(id) {
+    const target = id ?? current();
+    if (target === null)
+      return false;
+    point(target);
+    const element = elements.get(target);
+    if (element === undefined) {
+      awaiting = target;
+      options.onReveal?.(target);
+      return true;
+    }
+    awaiting = null;
+    focusElement(element);
+    return true;
+  }
+  const taken = (answer) => answer !== false;
+  function choose(id, cause) {
+    if (options.mode !== "focus")
+      options.onChange(id, cause);
+  }
+  function apply(intent) {
+    const { items, mode = "select", loop = false } = options;
+    const index = currentIndex();
+    const id = items[index] ?? null;
+    switch (intent.type) {
+      case "move": {
+        const landed = nextZoneIndex2({ length: items.length, index, move: intent.move, loop });
+        if (typeof landed !== "number") {
+          if (options.onBoundary === undefined)
+            return false;
+          return taken(options.onBoundary(landed === "before-start" ? "start" : "end"));
+        }
+        const next = items[landed];
+        if (next === undefined)
+          return false;
+        focus(next);
+        if (mode === "select" && next !== chosenValue())
+          choose(next, "arrow");
+        return true;
+      }
+      case "enter":
+        return id !== null && options.onEnter !== undefined && taken(options.onEnter(id));
+      case "exit":
+        return options.onExit !== undefined && taken(options.onExit());
+      case "confirm":
+        if (id === null || mode === "focus")
+          return false;
+        if (mode === "highlight") {
+          choose(id, "confirm");
+          return true;
+        }
+        return options.onEnter !== undefined && taken(options.onEnter(id));
+    }
+  }
+  return {
+    update(next) {
+      const changed = (next.value ?? null) !== chosenValue();
+      options = next;
+      if (changed)
+        point(null);
+    },
+    get options() {
+      return options;
+    },
+    pointedItem: () => pointed,
+    current,
+    keyDown(event, zone) {
+      if (event.defaultPrevented || event.isComposing || isFieldInside(event.target, zone)) {
+        return false;
+      }
+      if (closestFromTarget(event.target, `[${ZONE_ATTRIBUTE}]`) !== zone)
+        return false;
+      const intent = zoneIntent(event, options.orientation ?? "vertical");
+      if (intent === null || options.ignore?.(event) === true)
+        return false;
+      const landsOnCurrent = event.target === zone && intent.type === "move" && (intent.move === "next" || intent.move === "previous");
+      if (!(landsOnCurrent ? focus() : apply(intent)))
+        return false;
+      event.preventDefault();
+      return true;
+    },
+    keyFromOutside(event) {
+      if (closestFromTarget(event.target, `[${ZONE_ATTRIBUTE}]`) !== null)
+        return false;
+      const intent = zoneIntent(event, options.orientation ?? "vertical");
+      if (intent?.type !== "move" || intent.move !== "next" && intent.move !== "previous") {
+        return false;
+      }
+      if (options.ignore?.(event) === true)
+        return false;
+      return options.outside === "move" ? apply(intent) : focus();
+    },
+    focused(id) {
+      if (id !== pointed && !options.items.includes(id))
+        return;
+      awaiting = null;
+      point(id);
+    },
+    focus,
+    setItemElement(id, element) {
+      if (element === null) {
+        elements.delete(id);
+        return;
+      }
+      elements.set(id, element);
+      if (id === awaiting) {
+        awaiting = null;
+        focusElement(element);
+      }
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    }
+  };
+}
+
+export { KEY_FIELD_SELECTOR, isKeyFieldTarget2, createKeyLayerStack2, ZONE_ATTRIBUTE, nextZoneIndex2, resolveZoneIndex, createNavZone2 };

package/dist/{index-vtann8bz.js → index-p0rf7sq9.js}

@@ -27,14 +27,6 @@ import {
   bindContract,
   mediaTypeEssence
 } from "./index-cqmqyjax.js";
-import {
-  readBoundedChunks,
-  concatChunks,
-  readBoundedBody2
-} from "./index-5efrpfmj.js";
-import {
-  assertPositiveSafeInteger
-} from "./index-0s4xebbg.js";
 import {
   assertCorsConfig,
   isOriginAllowed,
@@ -59,6 +51,11 @@ import {
   getClientInfo2,
   parseQueryParams
 } from "./index-kw1ws0cs.js";
+import {
+  readBoundedChunks,
+  concatChunks,
+  readBoundedBody2
+} from "./index-qndsr7f0.js";
 import {
   abortReason,
   untilAborted
@@ -67,6 +64,9 @@ import {
   isUnsafeKey,
   safeJsonParse
 } from "./index-zsarb5xp.js";
+import {
+  assertPositiveSafeInteger
+} from "./index-0s4xebbg.js";
 import {
   AppError2,
   badRequest2,

package/dist/{index-aykhzcnf.js → index-qj1sy4ep.js}

@@ -19,7 +19,7 @@ import {
   appendEventIn,
   ArchiveProjectionSchema,
   createAgentRuntimeStore2
-} from "./index-523tq7y4.js";
+} from "./index-a3462dqf.js";
 import {
   AgentConversationPageSchema2,
   AgentConversationMessagePageSchema2

package/dist/{index-k7z3j3hr.js → index-tnxsq7cw.js}

@@ -23,19 +23,19 @@ import {
   createToolRunner,
   formatToolError
 } from "./index-htxh46ej.js";
+import {
+  collectToolSurface
+} from "./index-86nbfysb.js";
 import {
   fetchGuarded,
   readCapped
-} from "./index-cxpcdswt.js";
+} from "./index-mgb7r8b8.js";
 import {
   isWithinDir2
 } from "./index-5cc6r990.js";
 import {
   sleep
 } from "./index-eemvahkc.js";
-import {
-  collectToolSurface
-} from "./index-86nbfysb.js";
 import {
   isUnsafeKey,
   safeJsonParse

package/dist/{index-c5at3ykd.js → index-tsngj2b5.js}

@@ -336,6 +336,8 @@ function escapeRegex(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 function decodePathSegment(value) {
+  if (!value.includes("%"))
+    return value;
   try {
     return decodeURIComponent(value);
   } catch {
@@ -356,28 +358,38 @@ function createClientRouteMatcher(endpoint, contractPrefix, config) {
   const wildcard = patternSegments.at(-1)?.startsWith("*") === true;
   const fixedCount = wildcard ? patternSegments.length - 1 : patternSegments.length;
   const markers = Object.values(markerByKey);
+  const segmentTests = patternSegments.slice(0, fixedCount).map((pattern) => compileSegmentTest(pattern, markers));
   return (pathname) => {
-    const actualSegments = pathname.split("/").filter(Boolean).map(decodePathSegment);
+    const actualSegments = pathname.split("/").filter(Boolean);
     if (wildcard ? actualSegments.length < fixedCount : actualSegments.length !== fixedCount) {
       return false;
     }
     for (let index = 0;index < fixedCount; index += 1) {
-      const pattern = patternSegments[index];
+      const test = segmentTests[index];
       const actual = actualSegments[index];
-      if (!pattern || actual === undefined)
+      if (test === undefined || actual === undefined)
         return false;
-      if (pattern.startsWith(":"))
-        continue;
-      let source = escapeRegex(pattern);
-      for (const marker of markers) {
-        source = source.replaceAll(escapeRegex(marker), "[^/]+");
-      }
-      if (!new RegExp(`^${source}$`).test(actual))
+      if (test !== null && !test(decodePathSegment(actual)))
         return false;
     }
     return true;
   };
 }
+function compileSegmentTest(pattern, markers) {
+  if (pattern.startsWith(":"))
+    return null;
+  let source = escapeRegex(pattern);
+  let marked = false;
+  for (const marker of markers) {
+    const next = source.replaceAll(escapeRegex(marker), "[^/]+");
+    marked ||= next !== source;
+    source = next;
+  }
+  if (!marked)
+    return (actual) => actual === pattern;
+  const expression = new RegExp(`^${source}$`);
+  return (actual) => expression.test(actual);
+}
 function extractParamNames(path) {
   const matches = path.match(/:(\w+)/g);
   const names = matches ? matches.map((match) => match.slice(1)) : [];

package/dist/internal/pinned-http.d.ts

@@ -0,0 +1,27 @@
+/**
+ * One hop over a socket opened to the address the guard validated.
+ *
+ * The address is given, never looked up here: that is what makes a validated
+ * answer the one the connection uses. The `Host` header keeps the URL's host
+ * and, over TLS, the certificate is verified against it (`servername`), so a
+ * pinned connection is not a weaker one. The body is a Fetch stream over the
+ * socket, with backpressure and cancellation preserved.
+ */
+import type { IncomingMessage } from 'node:http';
+/** One hop, already resolved: open the connection to exactly `address`. */
+export type PinnedTransport = (url: URL, resolved: {
+    address: string;
+    family: 4 | 6;
+}, signal: AbortSignal | undefined) => Promise<Response>;
+/**
+ * One hop over a socket opened to `resolved.address`: the `Host` header keeps
+ * the URL's host and, for TLS, the certificate is verified against it
+ * (`servername`), so a pinned connection is not a weaker connection.
+ */
+export declare function requestPinned(url: URL, resolved: {
+    address: string;
+    family: 4 | 6;
+}, signal: AbortSignal | undefined, headers?: Record<string, string>): Promise<Response>;
+/** An `IncomingMessage` as a streaming Fetch response, keeping backpressure and cancellation. */
+export declare function pinnedResponse(incoming: IncomingMessage): Response;
+//# sourceMappingURL=pinned-http.d.ts.map

package/dist/internal/pinned-http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pinned-http.d.ts","sourceRoot":"","sources":["../../src/internal/pinned-http.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAIjD,2EAA2E;AAC3E,MAAM,MAAM,eAAe,GAAG,CAC5B,GAAG,EAAE,GAAG,EACR,QAAQ,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAA;CAAE,EAC5C,MAAM,EAAE,WAAW,GAAG,SAAS,KAC5B,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEvB;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,GAAG,EACR,QAAQ,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAA;CAAE,EAC5C,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GACnC,OAAO,CAAC,QAAQ,CAAC,CAgCnB;AAED,iGAAiG;AACjG,wBAAgB,cAAc,CAAC,QAAQ,EAAE,eAAe,GAAG,QAAQ,CA6ClE"}

package/dist/internal/secure-fetch.d.ts

@@ -1,3 +1,4 @@
+import type { PinnedTransport } from './pinned-http.js';
 /** True unless the literal belongs to the globally routable unicast Internet. */
 export declare function isPrivateIp(ip: string): boolean;
 /**
@@ -14,13 +15,21 @@ export declare function assertPublicUrl(url: URL, signal?: AbortSignal): Promise
 /**
  * Fetch a URL with the SSRF guard enforced on the initial URL and on every
  * redirect hop — a public host can otherwise `302` to an internal address or a
- * non-http(s) scheme.
- *
- * Note: the DNS resolution here and the resolution `fetch` performs are
- * separate, so a hostile resolver retains a narrow rebinding window. The
- * per-hop re-check is the larger and fully-closed hole; a static private DNS
- * record is rejected outright.
+ * non-http(s) scheme — and with the connection pinned to the address that
+ * passed the check, so a resolver cannot answer public and then connect
+ * somewhere private.
+ */
+/**
+ * The resolver seam: one `lookup` call per hop. Production uses `node:dns`;
+ * a test supplies a controlled answer to prove which address the socket went
+ * to, and that a second answer cannot open another one.
  */
+export type GuardedDnsLookup = (host: string, options: {
+    all: true;
+}) => Promise<Array<{
+    address: string;
+    family: number;
+}>>;
 export interface GuardedFetchOptions {
     /**
      * Deadline for producing the FINAL response headers — DNS, connects and every
@@ -36,6 +45,17 @@ export interface GuardedFetchOptions {
     bodyTimeoutMs?: number;
     /** Optional caller cancellation, combined with both deadlines. */
     signal?: AbortSignal;
+    /**
+     * Test seam: the resolver whose answer the connection is pinned to. Default
+     * `node:dns`. It replaces the name lookup, never the address check.
+     */
+    dns?: GuardedDnsLookup;
+    /**
+     * Test seam: how one resolved hop is opened. Default the pinned
+     * `http`/`https` request. Only the redirect tests replace it; production and
+     * the rebinding test use the default, which is where pinning happens.
+     */
+    transport?: PinnedTransport;
 }
 export declare function fetchGuarded(start: URL, allowPrivate: boolean, options?: GuardedFetchOptions): Promise<Response>;
 export interface PinnedDocumentFetchOptions {

package/dist/internal/secure-fetch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"secure-fetch.d.ts","sourceRoot":"","sources":["../../src/internal/secure-fetch.ts"],"names":[],"mappings":"AAmEA,iFAAiF;AACjF,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CA8D/C;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAEnF;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kEAAkE;IAClE,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,wBAAsB,YAAY,CAChC,KAAK,EAAE,GAAG,EACV,YAAY,EAAE,OAAO,EACrB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,QAAQ,CAAC,CAiDnB;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,6DAA6D;IAC7D,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,UAAU,CAAC;IACjB,GAAG,EAAE,GAAG,CAAC;CACV;AAED;;;;;;;;GAQG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,IAAI,2BAA2B;CACzC;AA8CD;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,GAAG,EACV,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,sBAAsB,CAAC,CAkFjC;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAGnF"}
+{"version":3,"file":"secure-fetch.d.ts","sourceRoot":"","sources":["../../src/internal/secure-fetch.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAmDrD,iFAAiF;AACjF,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CA8D/C;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAEnF;AAED;;;;;;GAMG;AACH;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAC7B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;IAAE,GAAG,EAAE,IAAI,CAAA;CAAE,KACnB,OAAO,CAAC,KAAK,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAAC;AAQzD,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kEAAkE;IAClE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;OAGG;IACH,GAAG,CAAC,EAAE,gBAAgB,CAAC;IACvB;;;;OAIG;IACH,SAAS,CAAC,EAAE,eAAe,CAAC;CAC7B;AAED,wBAAsB,YAAY,CAChC,KAAK,EAAE,GAAG,EACV,YAAY,EAAE,OAAO,EACrB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,QAAQ,CAAC,CAuDnB;AAqBD,MAAM,WAAW,0BAA0B;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,6DAA6D;IAC7D,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,UAAU,CAAC;IACjB,GAAG,EAAE,GAAG,CAAC;CACV;AAED;;;;;;;;GAQG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,IAAI,2BAA2B;CACzC;AA+CD;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,GAAG,EACV,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,sBAAsB,CAAC,CA2CjC;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAGnF"}

package/dist/react/entity-cache.d.ts

@@ -47,7 +47,16 @@ export interface EntityCacheTotalPolicy<TData> {
     /** What to do when an unseen id makes the delta unknowable. Default `preserve`. */
     unknown?: 'preserve' | 'invalidate';
 }
-/** List envelope, scoped key and explicit CRUD policies. */
+/**
+ * List envelope, scoped key and explicit CRUD policies. It stays an interface,
+ * not a union of shapes: a consumer's config is often a value of this type, and
+ * a union turns `compare` and `insertCompare` into a discriminated choice the
+ * compiler cannot narrow from the fields alone.
+ *
+ * At most one of `compare` and `insertCompare` is set — a list has one answer to
+ * "what order is this?". `createEntityCacheHandlers` refuses both at creation.
+ * With neither, a create goes to the `createAt` edge and every other row stays.
+ */
 export interface EntityCacheListConfig<TData, TListItem> {
     /** Static query-key prefix or an event-aware scoped key factory. */
     key: EntityCacheKey<TData>;
@@ -55,8 +64,21 @@ export interface EntityCacheListConfig<TData, TListItem> {
     createAt: 'start' | 'end';
     /** Explicit behavior when an update's id is absent from every cached page. */
     updateMissing: 'skip' | 'insert';
-    /** Backend-equivalent ordering for each affected logical item array. */
+    /**
+     * Backend-equivalent ordering of each affected logical item array: it is
+     * sorted again after every create and update. Only for an order the row
+     * itself determines; never together with `insertCompare`.
+     */
     compare?: (left: TListItem, right: TListItem) => number;
+    /**
+     * Where a row that is *entering* the list goes: before the first row it sorts
+     * ahead of, with ties broken by `createAt` (`'start'`: before equal rows,
+     * `'end'`: after them). On a list already in this order the result is the one
+     * `compare` gives; on a list that is not — an order the server decides with
+     * facts the row does not carry — no other row moves, and a row that is already
+     * there is replaced in place. Never together with `compare`.
+     */
+    insertCompare?: (incoming: TListItem, existing: TListItem) => number;
     /** Cached data envelope; no runtime shape inference is performed. */
     shape: EntityCacheListShape;
     /** Optional per-query filter membership. Omit for the envelope-preserving legacy path. */

package/dist/react/entity-cache.d.ts.map

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