@wix/himalaya-cli 0.987.0 → 0.989.0

package/templates/retail-store-owner/tier5-src/_shared/aria-chat.ts

@@ -46,6 +46,7 @@ import { isWebUrl } from "./aria-widget-model.js";
 import { NO_WIDGET, activeWidgetOf, asyncAdvanced, type SubtreeSlot, type WidgetOptionRow, type WidgetView }
   from "./aria-widget-view.js";
 import { substituteSelection } from "./aria-widget-model.js";
+import { LOCAL_ID_PREFIX, createRowMemo, mintLocalId, transcriptKeys, type RowMemo } from "./aria-hot-path.js";
 
 // ---------------------------------------------------------------------------
 // Shapes
@@ -119,6 +120,9 @@ export interface AriaChatState {
    *  question twice found the FIRST copy already in the transcript, dropped the
    *  second bubble off the screen, and declared the turn finished. */
   _pendingAfter: number;
+  /** The bubble id of `_pending` while the server has not echoed it — minted
+   *  once per send (`mintLocalId`) so every tick re-appends the SAME row. */
+  _pendingId: string;
   /** Server ASSISTANT-turn count at that same moment. The turn is over when the
    *  server holds more than this — read from the transcript ALONE. Gating it on
    *  the user's message having been echoed back instead meant a service that
@@ -573,33 +577,63 @@ export function plainBubble(id: string, role: string, who: string, content: stri
  *
  *  The widgets themselves are dropped here; rendering them is #2605 onward. A
  *  reply that was nothing but a widget therefore has empty prose and is filtered
- *  out below, which is deliberate: an empty bubble is a visible defect. */
-export function toBubbles(msgs: ConversationMessage[], assistantName: string, youName = "You"): AriaBubble[] {
-  return msgs
-    .map((m, i) => {
-      const raw = messageText(m);
-      const role = m.role || "ASSISTANT";
-      // Only assistant turns carry envelopes; a user's own text is literal, and
-      // scanning it would let an owner who typed `<<…>>` erase their own message.
-      // HIDDEN spans go first: the service marks text as transcript-only that
-      // way, and an aborted turn consists of nothing else. Then envelopes, then
-      // the markdown stripper — each stage handing on only what a reader should
-      // actually see.
-      // A row the service is still writing is scanned as STREAMING: an
-      // envelope whose `>>` has not arrived yet is held back rather than
-      // painted as raw JSON until the row finishes.
-      const prose = role === "USER" ? raw : proseOfParts(scanEnvelopes(stripHidden(raw), 0, !stillWriting(m)).parts);
-      return {
-        id: m.id || `m${i}`,
-        role,
-        who: role === "USER" ? youName : assistantName,
-        content: role === "USER" ? prose : stripMarkdown(prose),
-        notUser: role !== "USER",
-        notAria: role === "USER",
-        ...linkFieldsOf(prose, role),
-      };
-    })
-    .filter((b) => b.content && b.content.trim());
+ *  out below, which is deliberate: an empty bubble is a visible defect.
+ *
+ *  Pass a `memo` on a path that re-reads the transcript (every poll does): a
+ *  message whose id, text and writing state are unchanged since the last read
+ *  reuses the bubble built then instead of running the stages above again — see
+ *  `aria-hot-path.ts` rule 1. Without one, every bubble is built fresh; the two
+ *  are equivalent. */
+export function toBubbles(
+  msgs: ConversationMessage[], assistantName: string, youName = "You", memo?: BubbleMemo,
+): AriaBubble[] {
+  const ids = transcriptKeys(msgs);
+  const out: AriaBubble[] = [];
+  try {
+    for (let i = 0; i < msgs.length; i++) {
+      const m = msgs[i];
+      const role = m.role || "ASSISTANT", raw = messageText(m), id = ids[i];
+      const who = role === "USER" ? youName : assistantName;
+      // Part of the memo key, not just an input: a row that FINISHES writing
+      // can keep exactly the same text and still render differently (a held
+      // back envelope is released), so text alone would serve the stale bubble.
+      const writing = role !== "USER" && stillWriting(m);
+      const build = () => bubbleOf(id, role, who, raw, writing);
+      const b = memo ? memo.row(id, raw, `${role}\u0000${who}\u0000${writing ? "w" : ""}`, build) : build();
+      if (b) out.push(b);
+    }
+  } finally {
+    memo?.sweep();
+  }
+  return out;
+}
+
+/** Bubbles are built from one message's raw text; `null` is "paints nothing". */
+export type BubbleMemo = RowMemo<AriaBubble | null>;
+export const createBubbleMemo = (): BubbleMemo => createRowMemo<AriaBubble | null>();
+
+function bubbleOf(id: string, role: string, who: string, raw: string, writing: boolean): AriaBubble | null {
+  // Only assistant turns carry envelopes; a user's own text is literal, and
+  // scanning it would let an owner who typed `<<…>>` erase their own message.
+  // HIDDEN spans go first: the service marks text as transcript-only that
+  // way, and an aborted turn consists of nothing else. Then envelopes, then
+  // the markdown stripper — each stage handing on only what a reader should
+  // actually see.
+  // A row the service is still writing is scanned as STREAMING: an
+  // envelope whose `>>` has not arrived yet is held back rather than
+  // painted as raw JSON until the row finishes.
+  const prose = role === "USER" ? raw : proseOfParts(scanEnvelopes(stripHidden(raw), 0, !writing).parts);
+  const content = role === "USER" ? prose : stripMarkdown(prose);
+  if (!content || !content.trim()) return null;
+  return {
+    id,
+    role,
+    who,
+    content,
+    notUser: role !== "USER",
+    notAria: role === "USER",
+    ...linkFieldsOf(prose, role),
+  };
 }
 
 /** The reply the Copy / Regenerate row acts on: the LAST bubble, when it is an
@@ -648,11 +682,14 @@ export function argText(arg: AriaActionArg): string {
  *  when we sent. Until then it is appended so the owner's message does not
  *  vanish mid-turn. */
 export function reconcile(
-  server: AriaBubble[], pending: string, pendingAfter: number, youName = "You",
+  server: AriaBubble[], pending: string, pendingAfter: number, youName = "You", pendingId = "",
 ): { messages: AriaBubble[]; pending: string } {
   if (!pending) return { messages: server, pending: "" };
   if (countRole(server, "USER") > pendingAfter) return { messages: server, pending: "" };
-  return { messages: [...server, plainBubble(`pending-${server.length}`, "USER", youName, pending)], pending };
+  // `pendingId` is empty only for state persisted before ids were minted; a
+  // fixed fallback still keeps that one row stable across ticks.
+  const id = pendingId || `${LOCAL_ID_PREFIX}pending`;
+  return { messages: [...server, plainBubble(id, "USER", youName, pending)], pending };
 }
 
 /** How many turns of one role the transcript holds. Counted over BUBBLES rather
@@ -1029,7 +1066,7 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
   const initialState: AriaChatState = {
     status: "loading", statusText: "", error: "", input: "", copyNote: "", replyActionsHidden: true,
     messages: [], prompts: [], _convId: "", _siteId: "", _pending: "",
-    _pendingAfter: 0, _replyAfter: 0, _srvUsers: 0, _srvAssistants: 0,
+    _pendingAfter: 0, _pendingId: "", _replyAfter: 0, _srvUsers: 0, _srvAssistants: 0,
     _abortId: "", _turnId: "", stopHidden: true, ok: false,
     widget: NO_WIDGET,
   };
@@ -1047,6 +1084,17 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
    *  in-flight conversation. The latch is cleared once settled, so a failed
    *  create is retried rather than remembered. */
   let creating: { site: string; promise: Promise<string> } | null = null;
+
+  /** Bubbles built on the previous transcript read, reused while their message
+   *  is unchanged — every poll re-reads the WHOLE transcript, and re-deriving
+   *  every bubble on each one is the cost `aria-hot-path.ts` rule 1 removes.
+   *  Bounded by the latest read: rows it did not contain are forgotten. */
+  const bubbleMemo = createBubbleMemo();
+
+  /** Last number `mintLocalId` handed out. Not state: `mintLocalId` skips every
+   *  id already on screen, so a cold start resetting it cannot collide. */
+  let localSeq = 0;
+
   function createOnce(site: string): Promise<string> {
     if (creating && creating.site === site) return creating.promise;
     const promise = createConversation(assistantConfig, origin)
@@ -1270,7 +1318,7 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
     for (let n = 0; n < BUSY_LOOP_ROUNDS; n++) {
       const gm = await getConversationMessages(convId);
       const raw = messagesOf(gm);
-      const bubbles = toBubbles(raw, assistant(), you());
+      const bubbles = toBubbles(raw, assistant(), you(), bubbleMemo);
       if (bubbles.length) server = bubbles;
       seen = raw;
       // The turn is over when the SERVER holds an assistant answer — which a
@@ -1305,7 +1353,27 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
     turnSeq += 1;
     // Optimistic first: the owner's message and the typing line are part of the
     // state this action RETURNS, so on the `_poll` path they paint immediately.
-    const optimistic: AriaBubble[] = [...s.messages, plainBubble(`u${s.messages.length}`, "USER", you(), content)];
+    // Its id is the LOCAL SEND ID, minted here and carried as `_pendingId`, the
+    // one `reconcile` re-appends it under on every tick, so the row keeps one
+    // identity until the server's copy lands.
+    //
+    // A local bubble already on screen with these exact words is this message's
+    // FAILED attempt (an identical PENDING one is refused as a duplicate), so a
+    // retry takes over its id and replaces it rather than painting the same
+    // words twice. Matched on the words themselves — never on a hash of them.
+    const failedCopy = s.messages.find((b) =>
+      b.role === "USER" && b.id.startsWith(LOCAL_ID_PREFIX) && b.content === content);
+    let localId: string;
+    if (failedCopy) {
+      localId = failedCopy.id;
+    } else {
+      const minted = mintLocalId(localSeq, (id) => s.messages.some((b) => b.id === id));
+      localSeq = minted.seq;
+      localId = minted.id;
+    }
+    const optimistic: AriaBubble[] = [
+      ...s.messages.filter((b) => b.id !== localId), plainBubble(localId, "USER", you(), content),
+    ];
     const base: AriaChatState = {
       // `copyNote: ""` — a Copy confirmation belongs to the moment, and a new
       // turn ends it. Left in place it would sit under the next reply saying
@@ -1316,7 +1384,7 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
       // on a stale turn id would look for an answer that already exists. Both
       // are replaced the moment this send knows its own id.
       _abortId: "", _turnId: "",
-      statusText: typingText(), messages: optimistic, _pending: content,
+      statusText: typingText(), messages: optimistic, _pending: content, _pendingId: localId,
       // Mark the turn against the LAST COUNTS WE SAW, not against our own
       // message list — the greeting is a local bubble the server never had, so
       // counting `messages` would mark the turn one assistant reply ahead and
@@ -1508,15 +1576,33 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
         // this send was working on and is still the one we captured; otherwise it
         // belongs to another turn and must survive.
         : (supersedes && stalledTurn === latch ? null : stalledTurn);
+      // A FOLLOW-UP failing does not end the turn before it. Asking again while
+      // an answer is still being written is supported (`isDuplicateSend`), so
+      // the earlier turn can be in flight right now — and marking the screen
+      // `ready` here threw it away: its Stop went, and `tick` (which only slows
+      // the ladder on a turn it saw END) never slowed it, so the fast rate ran
+      // for as long as the screen stayed open (aria-hot-path.ts rule 4). Only in
+      // the same conversation: a turn in another one is not this screen's.
+      const keepsEarlier = turnInFlight(s) && convId === s._convId;
+      const earlier: Partial<AriaChatState> = keepsEarlier
+        ? { status: s.status, _pending: s._pending, _pendingId: s._pendingId, _pendingAfter: s._pendingAfter,
+            _replyAfter: s._replyAfter, _abortId: s._abortId, _turnId: s._turnId }
+        : { status: "ready", _pending: "" };
+      const slots = failureSlots(e, unavailableText);
       return {
-        ...base, status: "ready", _pending: "",
+        ...base, ...earlier,
         // `_siteId` moves with the id or neither does: a conversation remembered
         // without the site it belongs to reads as another business's on the next
         // send, and gets replaced instead of retried.
         _convId: convId, _siteId: convId === s._convId ? s._siteId : site,
         // Sets BOTH error and statusText, so it must come after the `statusText: ""`
         // this object used to carry — otherwise the literal would blank the sentence.
-        ...failureSlots(e, unavailableText),
+        ...slots,
+        // …except that a kept turn keeps its own status line. A real failure
+        // puts its sentence in `error` and blanks `statusText`, which here would
+        // leave Stop on screen beside no "Aria is typing…" until the answer
+        // landed. A boundary refusal's neutral sentence still wins.
+        ...(keepsEarlier ? { statusText: slots.statusText || s.statusText } : {}),
       };
     }
   }
@@ -1680,6 +1766,14 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
 
     load: async (s) => {
       const site = siteOf();
+      // Every branch below that puts a DIFFERENT conversation on screen abandons
+      // whatever turn was in flight — a business switch mid-turn does exactly
+      // that — so it re-arms the ladder slow, as `newChat` does. Otherwise the
+      // fast rate the send armed is never slowed: `tick` only slows on a turn it
+      // saw end (aria-hot-path.ts rule 4).
+      const wasMidTurn = !!s._pending || s.status === "sending";
+      const leaving = (next: AriaChatState): AriaChatState =>
+        wasMidTurn && o.poll ? cadence(next, o.poll.idleMs, null) : next;
       // Resume: the history screen routes here with a conversationId. Only
       // honour it for the site it belongs to — a stale id from another business
       // must not be re-opened.
@@ -1697,13 +1791,13 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
         try {
           const gm = await getConversationMessages(resumeId);
           const raw = messagesOf(gm);
-          const bubbles = toBubbles(raw, assistant(), you());
+          const bubbles = toBubbles(raw, assistant(), you(), bubbleMemo);
           const resumed = bubbles.length ? bubbles : greetingOnly();
           // `copyNote: ""` — a resumed transcript ends in a reply, so the row is
           // shown at once; a note carried over would say "Copied" beside an
           // answer from a different conversation that nobody copied.
-          return { ...s, status: "ready", _convId: resumeId, _siteId: site, _pending: "", statusText: "", error: "", copyNote: "",
-            messages: resumed, ...observed(raw, s.widget), prompts: promptsFor(resumed, promptList()) };
+          return leaving({ ...s, status: "ready", _convId: resumeId, _siteId: site, _pending: "", statusText: "", error: "", copyNote: "",
+            messages: resumed, ...observed(raw, s.widget), prompts: promptsFor(resumed, promptList()) });
         } catch { /* expired or unreachable — fall through to a fresh one */ }
       }
       // Opening a screen runs `load` more than once — the bundle self-kicks at
@@ -1735,12 +1829,12 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
         return { ...s, status: "ready", messages, prompts: promptsFor(messages, promptList()) };
       }
       try {
-        return { ...s, status: "ready", _convId: await createOnce(site), _siteId: site, _pending: "", statusText: "",
-          messages: greetingOnly(), ...observed([]), prompts: promptList() };
+        return leaving({ ...s, status: "ready", _convId: await createOnce(site), _siteId: site, _pending: "", statusText: "",
+          messages: greetingOnly(), ...observed([]), prompts: promptList() });
       } catch (e) {
         // Even if create fails, show the greeting; submit retries the create.
-        return { ...s, status: "ready", _convId: "", _siteId: site, _pending: "", ...failureSlots(e, unavailableText),
-          messages: greetingOnly(), ...observed([]), prompts: promptList() };
+        return leaving({ ...s, status: "ready", _convId: "", _siteId: site, _pending: "", ...failureSlots(e, unavailableText),
+          messages: greetingOnly(), ...observed([]), prompts: promptList() });
       }
     },
 
@@ -1842,14 +1936,14 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
         // `stop` holds a snapshot predating this read and will overwrite
         // whatever we write. A tick of a NEWER epoch is not stale, not fenced.
         if (turnSeq !== seq || abortingEpochs.has(seq)) return undefined;
-        const server = toBubbles(raw, assistant(), you());
+        const server = toBubbles(raw, assistant(), you(), bubbleMemo);
         // A transcript that renders to nothing is not necessarily an empty one:
         // a reply made entirely of widgets leaves no bubble behind. So the bail
         // is on the RAW transcript — bailing on the bubbles is what let such a
         // reply go unnoticed and pinned the ladder fast forever. Safe to return
         // `s` here: the guard above proved this tick is still current.
         if (!raw.length) return s;
-        const { messages, pending } = reconcile(server, s._pending, s._pendingAfter, you());
+        const { messages, pending } = reconcile(server, s._pending, s._pendingAfter, you(), s._pendingId);
         // …but still never PAINT nothing over something. `messages` is only
         // adopted when it has content: a transcript that renders empty leaves
         // the screen as it was (the greeting, or the last good turn) while the

package/templates/retail-store-owner/tier5-src/_shared/aria-hot-path.ts

@@ -0,0 +1,167 @@
+// The Aria transcript's hot path — the rules it is written to, and the two
+// primitives that make them hold.
+//
+// Adapted from `native-apps/PERFORMANCE.md` in wix-private/aria-native-apps, which
+// states eleven rules, each "a class of shipped regression". Most of them govern
+// 30 Hz streaming, which this app does not do yet (#2612), and adopting all eleven
+// for a POLLED chat would be cargo-culting. These four apply now (#2623):
+//
+//  1. NEVER RE-DERIVE THE WHOLE TRANSCRIPT PER TICK. Every poll re-reads the full
+//     transcript, and turning a message into a bubble is the expensive step —
+//     the envelope scan, the markdown stripper (a dozen regex passes) and the
+//     link scan. So a bubble is built once per (identity, content) and reused
+//     while its message is unchanged: a poll that brings nothing new builds
+//     nothing. `createRowMemo`.
+//     Measured per poll over an unchanged transcript of mixed-markdown replies
+//     (bubbles + both turn counts), median, QuickJS — the no-JIT floor a device
+//     worker realm runs at:
+//         messages     20      100     500
+//         before       3 ms    16 ms   79 ms
+//         after        0 ms     1 ms    6 ms   (≈5 ms of it is `countTurns`)
+//     Node's JIT shows the same ratio: 2.4 ms → 0.21 ms at 500.
+//
+//  2. A PER-TICK IDENTITY IS A CACHE FLUSH. The memo is keyed by the MESSAGE's
+//     identity, never by anything minted per read. A message that is still
+//     growing — the streaming case — keeps its id, so it overwrites its own slot
+//     in place and every settled row stays built. The memo's bound is the
+//     transcript itself (rows the latest read did not contain are dropped), so
+//     there is no LRU for a churning key to evict settled entries out of.
+//
+//  3. TRANSCRIPT IDENTITY IS THE SERVER MESSAGE ID — or the LOCAL SEND ID until
+//     the server acknowledges the message. Never an array index: an index names
+//     a POSITION, and the moment anything before it is dropped (an empty
+//     placeholder, a hidden-only row, a windowed read) the same index names a
+//     different message. The bubble id is also the row's stable test id
+//     (`<screen>.msg_<id>`, invariant 27). `transcriptKeys`, `mintLocalId`.
+//
+//  4. EVERY REPEATING CLOCK HAS AN OWNER AND STOPS ON EVERY EXIT PATH. The only
+//     clock here is the reply ladder, `_poll` id `aria-turn`, and its owner is
+//     the HOST's PollScheduler — a worker has no timers, and `PollDirective` has
+//     no stop verb. So, stated explicitly rather than implied:
+//       - one id, ever: no second `_poll` is armed (async-job progress rides the
+//         same ladder for exactly this reason — see `readJobState`);
+//       - every path that ENDS or ABANDONS a turn re-arms it at the IDLE rate
+//         (reply, Stop, ➕ mid-turn, a load that leaves the turn behind),
+//         because slowing is the only lever a worker holds;
+//       - a path that does NOT end the turn must not pretend to. A follow-up
+//         whose send failed used to discard the turn still in flight — marking
+//         the screen idle while the first answer was still being written — so
+//         `tick` never saw the turn end and the fast rate ran for as long as
+//         the screen stayed open (30 reads a minute instead of 4);
+//       - the host stops it on background, pooling and teardown (poll-parity).
+//     What it cannot do yet is stop while the screen is visible and idle: that
+//     needs a stop verb on the directive across every host arm.
+//
+// Rules for streaming (tail-only parsing, publish coalescing, frame-clock
+// drivers) and the native app's device budgets (cold start, frame time, hangs)
+// are deliberately NOT adopted here: nothing in this repo measures them for
+// Aria, and a budget nobody measures is decoration. Each rule above is pinned by
+// a test instead — `core/dev-server/tests/aria-hot-path.test.ts`.
+//
+// Dependency-free on purpose: the tests import this file directly.
+
+/** Prefix of every id minted for a bubble the server has not echoed yet. */
+export const LOCAL_ID_PREFIX = "local-";
+
+/** Mint the id for the bubble of a message the owner just sent.
+ *
+ *  MINTED once per send and then carried in state (`_pendingId`), so the
+ *  optimistic bubble `send` paints and the one `reconcile` re-appends on every
+ *  tick are the SAME row until the server's copy replaces it. It used to be
+ *  `u<list length>` in one and `pending-<server length>` in the other — two ids
+ *  for one message, both positions.
+ *
+ *  Deliberately NOT derived from the text. A 32-bit hash of it collides —
+ *  different words, one id — and then sending one message silently replaced
+ *  another's failed bubble and took over its identity. A retry of the SAME send
+ *  reuses its failed copy's id instead (see `send`).
+ *
+ *  `taken` is every id on screen, so a counter that a cold start reset can never
+ *  mint an id a persisted bubble still carries. */
+export function mintLocalId(seq: number, taken: (id: string) => boolean): { id: string; seq: number } {
+  let n = seq;
+  let id: string;
+  do { id = `${LOCAL_ID_PREFIX}${++n}`; } while (taken(id));
+  return { id, seq: n };
+}
+
+/** One transcript row, as far as identity is concerned. */
+export interface IdentityRow {
+  id?: unknown;
+}
+
+/** A usable server id: a non-empty string, or a number (kept as its string). */
+function serverIdOf(id: unknown): string {
+  if (typeof id === "string") return id;
+  if (typeof id === "number" && Number.isFinite(id)) return String(id);
+  return "";
+}
+
+/** A stable key per row: the server id when there is one.
+ *
+ *  A row with no id is keyed RELATIVE TO THE NEAREST SERVER ID BEFORE IT —
+ *  `after-<id>-<k>` for the k-th id-less row since that anchor, `head-<k>` before
+ *  any. Never by its content, and never by its absolute position:
+ *   - content would re-key a row that is still being written on every read, the
+ *     exact case where identity matters most;
+ *   - an absolute index re-keys every later row the moment anything before it
+ *     is dropped (a placeholder, a hidden-only row, a windowed read).
+ *  What remains unstable is narrow and stated: dropping an id-less row between
+ *  the same anchor and this one shifts `k`, and the `head-` rows have no anchor
+ *  to hold them. The service names its rows; this is the fallback. */
+export function transcriptKeys(rows: ReadonlyArray<IdentityRow>): string[] {
+  let anchor = "";
+  let k = 0;
+  return rows.map((r) => {
+    const id = serverIdOf(r.id);
+    if (id) { anchor = id; k = 0; return id; }
+    return anchor ? `after-${anchor}-${k++}` : `head-${k++}`;
+  });
+}
+
+/** Per-row derivation memo for a transcript that is re-read wholesale.
+ *
+ *  Use: call `row` once per message of one read, then `sweep`. A row is rebuilt
+ *  only when its key is new or its `input` / `variant` changed.
+ *
+ *  BOUND: the rows of the latest completed read — `sweep` forgets every key that
+ *  read did not touch. So the memo never outgrows the transcript on screen, and
+ *  a conversation switch drops the previous one's rows at the first read.
+ *
+ *  Values are SHARED between reads. Callers must treat them as immutable, which
+ *  the transcript already is: every reducer here replaces `messages`, none
+ *  mutates a bubble in place. */
+export interface RowMemo<V> {
+  row(key: string, input: string, variant: string, build: () => V): V;
+  sweep(): void;
+  /** How many times `build` ran since creation — what a count test pins. */
+  readonly builds: number;
+  /** Rows currently held. */
+  readonly size: number;
+}
+
+export function createRowMemo<V>(): RowMemo<V> {
+  interface Entry { input: string; variant: string; value: V }
+  let live = new Map<string, Entry>();
+  let next = new Map<string, Entry>();
+  let builds = 0;
+  return {
+    row(key, input, variant, build) {
+      const e = next.get(key) ?? live.get(key);
+      if (e && e.input === input && e.variant === variant) {
+        next.set(key, e);
+        return e.value;
+      }
+      builds++;
+      const value = build();
+      next.set(key, { input, variant, value });
+      return value;
+    },
+    sweep() {
+      live = next;
+      next = new Map();
+    },
+    get builds() { return builds; },
+    get size() { return live.size; },
+  };
+}