Loomworks list-loading — CR-2: frontend load-more + page size — v0.3

Document: loomworks-list-loading-cr-2-frontend-load-more-v0_3 Version: v0.3 Status: working draft — Steps 1–2 built; Steps 3–6 in progress (split per surface); D-4 resolved empirically at build Date: 2026-06-27 Supersedes: loomworks-list-loading-cr-2-frontend-load-more-v0_2 (2026-06-27), …-v0_1 Queue item: Companion build queue Item 1 — list-loading (cross-cutting pagination), frontend half Handoff: loomworks-list-loading-cr-drafting-handoff-v0_1 Step-0 source: loomworks-list-loading-cr-2-step0-report-v0_1 (live OL + merged-engine inspection — build CR-2 steps from THIS) Engine contract: CR-1 merged at eeae9c2 / alembic 0096 — the ten endpoints return limit + cursor + has_more + total_count + next_cursor Repo: loomworks (Operator Layer) — branch off current feat-companion-surface 17263c9. Engine touched only for the lists.page_size setting plumbing (one KNOWN_SETTINGS entry + one _LABEL_TO_KEY synonym set). Two-role note: This CR is scoping/drafting. CC executes. Nothing commits or pushes without the Operator's explicit authorisation — explicit-path staging, per-step commits, suite green at each step, push on separate authorisation.

1. What this CR does

CR-1 brought ten engine endpoints to one keyset contract. CR-2 builds the frontend that consumes it: a reusable explicit load-more control, applied to the list surfaces that exist today, plus the per-surface page-size defaults and the voice-adjustable global override.

Build status (2026-06-27)

Why 3–6 are split. Steps 3–6 collectively touch well over 30 existing tests — each surface is embedded in parents whose tests mock the fetch adapters, so rewiring one fetch contract cascades mock updates across that surface's test and every embedder. The CR's >30-test halt threshold fired during the build; CC stopped at a clean boundary (both repos green, spine proven, nothing half-wired). Steps 3–6 proceed as bounded per-surface sessions against the built spine, each committed separately, each under the threshold: renders, Memory/assertions, engagements (Step 3's three surfaces, each its own session), home+defaults (Steps 4+5), CenterPane (Step 6). The spine — the high-value, hard part — is done; each remaining step is a surface-wiring.

Scope is set by what is live. Step-0 D found only 4 of the 10 endpoints have an Operator Layer surface today (engagements, assertions/Memory, renders/Rendering, conversation-history/CenterPane). The other six (considerations, compositions, shape-events, assertion-groups, manifestations, shapings) have no frontend consumer — their rooms are empty stubs (RoomView.tsx:37). CR-2 paginates what is live and defers the six roomless endpoints to a bounded follow-on: they get the load-more control when their rooms are built, not before. Building pagination for a surface that does not exist would be building against nothing.

Five pieces: 1. A reusable load-more control + paged-list state — explicit (not infinite scroll), has_more-gated, total_count surfaced, parameterised by item-key. 2. Applied to the 4 live endpoint surfaces (three swap wholesale limit=200 → cursor; CenterPane migrates before → cursor). 3. Home lenses re-wired to stop discarding next_cursor. 4. Per-surface page-size defaults. 5. lists.page_size voice-adjustable global override (nullable; the three-place settings extension).

2. The two decisions the Operator confirmed at drafting

Defer the six roomless endpoints. CR-2 covers only surfaces that exist. The six endpoints whose rooms are empty stubs are a named follow-on — paginated when their rooms are built. CR-2 stays a pagination CR, not a room-building CR.

The limit=200 → paginated swap is intended. Three surfaces (engagements, Memory/assertions, Rendering/renders) currently fetch wholesale limit=200. CR-2 swaps each to cursor pagination with a per-surface default (~15–40). This is a visible behaviour change — a user who today sees up to 200 rows at once will see one page plus a load-more control. Named explicitly because it is the one place CR-2 changes what an existing surface shows. It is the intended change — the whole point of the work — and satisfies the seed's "only show what is available" + total_count-surfaced shape.

3. The reusable load-more control (the spine)

One control, built once, applied to every paged surface. Generalised from the precedent that already exists: CenterPane's "load earlier" control (ConversationPane.tsx:179).

Behaviour (settled pattern, from the handoff): - Explicit, not infinite scroll. A control the Operator clicks/taps to load the next page. (Operator-authority posture: the surface signals "more exists"; the Operator chooses to load it.) - has_more-gated. The control appears only when has_more is true. When has_more is false, the control does not render — no disabled state, no greyed-out control (seed: "only show what is available"). - total_count always visible. The surface shows "showing N of TOTAL" (or equivalent) whenever a list is paged, so no truncation is silent (handoff rule 2). - Parameterised by item-key. Step-0 A found the response item-array key varies per endpoint — most use the endpoint's natural key, compositions uses items, conversation-history uses turns. The control takes the item-key as a prop rather than assuming a fixed field, so one control serves all surfaces. (Also ignore assertions' vestigial limit response field — Step-0 A; rely on has_more/next_cursor.)

Paged-list state (the reusable hook/store): - Holds: accumulated items, next_cursor, has_more, total_count, loading flag. - First fetch on mount: limit=<surface default>, no cursor. - Load-more: fetch limit=<default>&cursor=<next_cursor>, append to accumulated items, update next_cursor/has_more. - Direction note: most surfaces prepend nothing (append newest-first or oldest-first per the surface); CenterPane is the exception — it loads earlier turns and prepends (existing behaviour, preserved). The reusable state supports both append and prepend modes.

Settled (D-3): extract a shared control; CenterPane adopts it at Step 6. Build the reusable control to the general list shape; CenterPane migrates onto it, keeping its dedup guard as a CenterPane-level concern. The precedent becomes the reusable thing rather than a parallel implementation. [CC reads the existing CenterPane control's shape (ConversationPane.tsx:179) to extract the general control cleanly and identify what stays CenterPane-specific — the prepend bias is a mode the shared control supports; the dedup guard stays at CenterPane.]

4. Step plan — built from Step-0's live surface inventory

Engine setting plumbing first (it is the only engine touch and unblocks the override), then the control, then each live surface, then home, then the global override, then CenterPane migration last (it is both a surface and the precedent).

Step 1 — engine: lists.page_size setting plumbing

Step 2 — the reusable load-more control + paged-list state

Step 3 — apply to the three wholesale endpoint surfaces

Step 4 — home lenses re-wire (frontend-only, no engine)

Step 5 — per-surface page-size defaults

Step 6 — CenterPane migration: before → cursor (the breaking site + the precedent)

5. Out of scope (named follow-ons)

• The six roomless endpoints (considerations, compositions, shape-events, assertion-groups, manifestations, shapings) — paginate when their rooms are built. Bounded follow-on; the reusable control (Step 2) is ready for them, so each is a wire-up, not new design. Note for that follow-on: compositions uses item-key items (Step-0 A outlier) — the control's item-key prop already handles it.
• Room-building itself — Manifestation/Shaping rooms are empty stubs. Building them is separate, larger work; CR-2 does not touch it.
• Infinite scroll — explicitly rejected; the load-more pattern is the settled choice.

6. The four decisions — settled

All four resolved with the Operator at drafting. Rationale recorded per corrections-preserved discipline.

D-3 rationale (the one structural, expensive-to-reverse call). CenterPane's existing control is shaped for a conversation stream: it loads earlier turns, prepends, and carries a dedup guard. The other five surfaces append, no dedup. Generalising CenterPane's control in place would bend a conversation-stream control to cover list surfaces, leaving list pagination dependent on conversation-specific machinery — a seam that drifts (a later change to conversation dedup silently changes how the Memory room pages). Extracting inverts it: the shared control is genuinely general (the list shape), CenterPane's conversation behaviour stays at CenterPane. Same discipline as CR-1's codec lift — generalise the shared thing properly rather than propagating a special case. CenterPane's dedup guard is now redundant (CR-1's composite cursor handles the R2 skip it guarded against) but kept as harmless belt-and-braces.

7. Done criteria

CR-2 done when: lists.page_size lands on the three-place pattern (engine suite green); the reusable control + paged-list state built and tested in isolation; the three wholesale surfaces (engagements, Memory, Rendering) swapped to cursor pagination; the two home lenses re-wired to stop discarding next_cursor; per-surface defaults set; CenterPane migrated before→cursor with load-earlier preserved and total_count surfaced; both conversation-history call sites pass cursor; OL suite green at each step; verified against playground_dev. The six roomless endpoints remain a named follow-on. Push on separate authorisation.

DUNIN7 — Done In Seven LLC — Miami, Florida Loomworks list-loading — CR-2: frontend load-more + page size — v0.3 — 2026-06-27 Frontend CR against merged CR-1 (eeae9c2/0096). Steps 1–2 built (engine setting + reusable spine); Steps 3–6 split per surface for blast-radius. D-4 resolved at build to land-on-oldest (forward-only ASC keyset). Supersedes v0.2, v0.1.