@cat-factory/app 0.275.0 → 0.277.0

package/app/stores/board.spec.ts

@@ -3,6 +3,8 @@ import { setActivePinia, createPinia } from 'pinia'
 import type { Block, BlockStatus } from '~/types/domain'
 import { useBoardStore } from '~/stores/board'
 import { useWorkspaceStore } from '~/stores/workspace'
+import { EMPTY_FRAME_SIZE } from '~/utils/framePlacement'
+import { frameContentSize, laneBodyHeightIn, LANE_GEOMETRY } from '~/utils/laneGeometry'
 
 /** Minimal Block factory — only the fields the read getters care about. */
 function block(id: string, over: Partial<Block> = {}): Block {
@@ -27,6 +29,8 @@ const moduleBlock = (id: string, parentId: string, over: Partial<Block> = {}) =>
   block(id, { level: 'module', parentId, ...over })
 const task = (id: string, parentId: string, over: Partial<Block> = {}) =>
   block(id, { level: 'task', parentId, ...over })
+const initiativeBlock = (id: string, parentId: string, over: Partial<Block> = {}) =>
+  block(id, { level: 'initiative', parentId, ...over })
 
 describe('board store read getters', () => {
   let store: ReturnType<typeof useBoardStore>
@@ -212,29 +216,77 @@ describe('board store read getters', () => {
   })
 
   describe('containerSize', () => {
-    it('returns base dimensions for an empty service', () => {
+    // A frame's size is now a function of the LANE GEOMETRY, not of its contents. That is the
+    // point of the swimlanes: each lane scrolls, so a service accumulating work no longer grows
+    // a taller and taller frame until it dwarfs its neighbours. These tests pin the INVARIANT
+    // (size independent of task count and task position) rather than the pixel arithmetic, which
+    // belongs to `LANE_GEOMETRY` and would otherwise be restated here to no purpose.
+    it('sizes a service with nothing in it to the panel it actually renders', () => {
+      // An empty service shows one "add the first task" panel, not lanes, so it reserves the
+      // panel's footprint. Reserving the lanes' would leave the frame more than twice as tall as
+      // its own contents — and, since a placement clears frames by their reserved size, would
+      // push its neighbours that much further away for a frame holding nothing.
       store.hydrate([frame('f1')])
-      expect(store.containerSize('f1')).toEqual({ w: 360, h: 220 })
+      expect(store.containerSize('f1')).toEqual(
+        frameContentSize({ hasChildren: false, initiatives: 0 }),
+      )
     })
 
-    it('grows to fit a task and adds the module header height for modules', () => {
+    it('reserves the same footprint for a new frame that a new frame will render at', () => {
+      // The drift this caught: `EMPTY_FRAME_SIZE` is what a placement decision reserves BEFORE the
+      // block exists, so it cannot measure the frame and has to predict it. A hand-copied pair
+      // went stale when the floor changed underneath it, and every new service was then dropped
+      // on top of a neighbour it had been placed to clear.
+      store.hydrate([frame('f1')])
+      expect(store.containerSize('f1')).toEqual(EMPTY_FRAME_SIZE)
+    })
+
+    it('does not grow with task count, however many tasks and wherever they sat', () => {
+      store.hydrate([frame('f1'), task('t1', 'f1')])
+      const oneTask = store.containerSize('f1')
+
       store.hydrate([
         frame('f1'),
-        moduleBlock('m1', 'f1', { position: { x: 0, y: 0 } }),
+        moduleBlock('m1', 'f1', { position: { x: 400, y: 300 } }),
         task('t1', 'm1', { position: { x: 300, y: 200 } }),
+        // A position far outside the old content extent: it used to stretch the frame to reach
+        // it, and now means nothing at all, because a task no longer renders at coordinates.
+        task('t2', 'f1', { position: { x: 4000, y: 9000 } }),
       ])
-      // module inner width/height fit the task, plus the 30px module header.
-      const size = store.containerSize('m1')
-      expect(size.w).toBe(300 + 210 + 12)
-      expect(size.h).toBe(200 + 160 + 12 + 30)
+      expect(store.containerSize('f1')).toEqual(oneTask)
+    })
+
+    it('makes room for the initiative band above the lanes', () => {
+      // Initiatives are the one child still laid out by the frame itself (in a wrapping band),
+      // so they are the one thing the frame's height still has to account for.
+      store.hydrate([frame('f1'), task('t1', 'f1')])
+      const withoutBand = store.containerSize('f1').h
+      store.hydrate([frame('f1'), task('t1', 'f1'), initiativeBlock('i1', 'f1')])
+      expect(store.containerSize('f1').h).toBe(withoutBand + LANE_GEOMETRY.initiativeHeight)
+    })
+
+    it('sizes a frame holding only an initiative for lanes, since that is what it renders', () => {
+      // `BlockNode` gates the lanes on having ANY child — tasks, modules or initiatives — so a
+      // frame with an initiative and no tasks renders three (empty) lanes. A size that disagreed
+      // with what rendered is the clipping this geometry exists to prevent.
+      store.hydrate([frame('f1'), initiativeBlock('i1', 'f1')])
+      expect(store.containerSize('f1')).toEqual(
+        frameContentSize({ hasChildren: true, initiatives: 1 }),
+      )
     })
 
-    it('expands a service to enclose its nested modules', () => {
-      store.hydrate([frame('f1'), moduleBlock('m1', 'f1', { position: { x: 400, y: 300 } })])
-      const mod = store.containerSize('m1')
-      const svc = store.containerSize('f1')
-      expect(svc.w).toBe(400 + mod.w + 12)
-      expect(svc.h).toBe(300 + mod.h + 12)
+    it('a module reports no canvas of its own, since it is no longer drawn as a box', () => {
+      store.hydrate([frame('f1'), moduleBlock('m1', 'f1'), task('t1', 'm1')])
+      expect(store.containerSize('m1').h).toBe(0)
+    })
+
+    it('keeps an explicitly resized frame at the size the user dragged it to', () => {
+      // The geometry is a FLOOR, not a fixed size: dragging the border still gives a reader more
+      // room, and a lane grows its scroll viewport into it rather than leaving dead canvas below.
+      store.hydrate([frame('f1', { size: { w: 2000, h: 1500 } }), task('t1', 'f1')])
+      const size = store.containerSize('f1')
+      expect(size).toEqual({ w: 2000, h: 1500 })
+      expect(laneBodyHeightIn(size, 0)).toBeGreaterThan(LANE_GEOMETRY.laneBodyHeight)
     })
   })
 
@@ -422,6 +474,59 @@ describe('board store optimistic rollback', () => {
     // the undo move is itself non-undoable, so no second toast is queued
     expect(actions).toHaveLength(1)
   })
+
+  it('reparentBlock predicts the declared module the server will re-stamp', async () => {
+    // The board reads a task's PARENT for its module and falls back to the name it DECLARES (a
+    // task can name a module before the engine materialises the block on merge). So a card
+    // dragged out of a module and left still declaring it re-groups under the module it was just
+    // dragged out of. The server re-stamps the name on every reparent; the optimistic write here
+    // has to predict the same answer or the card visibly jumps when the response lands.
+    //
+    // The request never settles, so what is asserted is strictly what this store put on screen
+    // BEFORE hearing back — the window the card would otherwise spend in the wrong group.
+    vi.stubGlobal('useApi', () => ({ reparentBlock: () => new Promise(() => {}) }))
+    vi.stubGlobal('useToast', () => ({ add: () => {} }))
+    setActivePinia(createPinia())
+    useWorkspaceStore().workspaceId = 'ws1'
+    const store = useBoardStore()
+    store.hydrate([
+      frame('f1'),
+      moduleBlock('m1', 'f1', { title: 'Sessions' }),
+      task('t1', 'm1', { moduleName: 'Sessions' }),
+      task('t2', 'f1'),
+    ])
+
+    // Out to the service frame: the declared name goes with it, as the empty string the store
+    // maps to NULL. Left behind, it is what files the card straight back into "Sessions".
+    void store.reparentBlock('t1', 'f1', { x: 0, y: 0 })
+    expect(store.getBlock('t1')?.moduleName).toBe('')
+
+    // And in: the destination module's title, whatever the task declared before.
+    void store.reparentBlock('t2', 'm1', { x: 0, y: 0 })
+    expect(store.getBlock('t2')?.moduleName).toBe('Sessions')
+  })
+
+  it('reparentBlock restores the declared module when the move is rejected', async () => {
+    // The same rollback contract the parent and position already had: a refused move must not
+    // leave the card grouped somewhere the server never put it.
+    vi.stubGlobal('useApi', () => ({
+      reparentBlock: async () => {
+        throw new Error('nope')
+      },
+    }))
+    vi.stubGlobal('useToast', () => ({ add: () => {} }))
+    setActivePinia(createPinia())
+    useWorkspaceStore().workspaceId = 'ws1'
+    const store = useBoardStore()
+    store.hydrate([
+      frame('f1'),
+      moduleBlock('m1', 'f1', { title: 'Sessions' }),
+      task('t1', 'm1', { moduleName: 'Sessions' }),
+    ])
+
+    await store.reparentBlock('t1', 'f1', { x: 0, y: 0 })
+    expect(store.getBlock('t1')).toMatchObject({ parentId: 'm1', moduleName: 'Sessions' })
+  })
 })
 
 describe('board store deferred delete + undo', () => {

package/app/stores/laneView.spec.ts

@@ -0,0 +1,61 @@
+import { beforeEach, describe, expect, it } from 'vitest'
+import { createPinia, setActivePinia } from 'pinia'
+import { useLaneViewStore } from '~/stores/laneView'
+
+// The preference is PERSISTED in the reader's browser, which makes the restored value
+// untrusted input: a blob written by an older build can name a sort key this build has
+// retired, and feeding that to the comparator lookup would throw mid-sort and take the whole
+// board down over a stale preference. That narrowing is the thing worth pinning here.
+
+describe('laneView store', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia())
+  })
+
+  it('defaults to the per-lane smart order with no grouping', () => {
+    const store = useLaneViewStore()
+    expect(store.sortKey).toBe('smart')
+    expect(store.groupKey).toBe('none')
+    expect(store.hasOverride).toBe(false)
+  })
+
+  it('opens with the Done lane collapsed', () => {
+    // A service with a long history would otherwise open as a wall of merged cards.
+    expect(useLaneViewStore().doneLaneCollapsed).toBe(true)
+  })
+
+  it('falls back to the default when a restored key is not in this build vocabulary', () => {
+    const store = useLaneViewStore()
+    // Exactly what a persisted blob from an older build looks like.
+    store.storedSortKey = 'sort_by_vibes'
+    store.storedGroupKey = 'group_by_astrology'
+    expect(store.sortKey).toBe('smart')
+    expect(store.groupKey).toBe('none')
+    // …and a stale value must not read as an override, or the board would claim a preference
+    // it is not actually applying.
+    expect(store.hasOverride).toBe(false)
+  })
+
+  it('reports an override so the control survives a switch to basic mode', () => {
+    const store = useLaneViewStore()
+    store.setSortKey('severity_desc')
+    expect(store.hasOverride).toBe(true)
+    store.reset()
+    expect(store.hasOverride).toBe(false)
+    expect(store.sortKey).toBe('smart')
+  })
+
+  it('treats grouping alone as an override', () => {
+    const store = useLaneViewStore()
+    store.setGroupKey('module')
+    expect(store.hasOverride).toBe(true)
+  })
+
+  it('toggles the Done lane', () => {
+    const store = useLaneViewStore()
+    store.toggleDoneLane()
+    expect(store.doneLaneCollapsed).toBe(false)
+    store.toggleDoneLane()
+    expect(store.doneLaneCollapsed).toBe(true)
+  })
+})

package/app/stores/laneView.ts

@@ -0,0 +1,85 @@
+import { defineStore } from 'pinia'
+import { computed, ref } from 'vue'
+import {
+  isLaneGroupKey,
+  isLaneSortKey,
+  type LaneGroupKey,
+  type LaneSortKey,
+} from '~/utils/laneSort'
+
+/**
+ * How this reader wants a frame's swimlanes ordered and grouped, plus whether the Done lane
+ * is open.
+ *
+ * Per USER and per BROWSER, persisted like the interface tier and the agent tier. That is a
+ * deliberate split from the Done lane's two CAPS, which are per-workspace settings: what the
+ * board may show is a shared decision about a service's history, while the order a reader
+ * scans it in is personal and changes several times an hour. Making the order shared would
+ * mean one person's triage sweep re-arranging everyone else's board.
+ *
+ * `sortKey` defaults to `smart`, which is per-lane (see `SMART_ORDER_BY_LANE`) rather than one
+ * global order — the actionable order genuinely differs by column. The explicit keys are an
+ * OVERRIDE of that, which is why the control offering them is an advanced-tier affordance:
+ * hiding it in basic mode leaves exactly the default it would have shown.
+ */
+export const useLaneViewStore = defineStore(
+  'laneView',
+  () => {
+    // Stored raw and narrowed on read, the same split `uiMode` uses for `storedMode`. A setup
+    // store can only persist what it returns, so these are reachable directly; the narrowing
+    // below is what makes that safe rather than a trust assumption.
+    const storedSortKey = ref<string>('smart')
+    const storedGroupKey = ref<string>('none')
+    /**
+     * Collapsed by default. The lane's job is to prove finished work exists and give a route
+     * to it, and a service with a long history would otherwise open as a wall of merged
+     * cards nobody asked to read.
+     */
+    const doneLaneCollapsed = ref(true)
+
+    const sortKey = computed<LaneSortKey>(() =>
+      isLaneSortKey(storedSortKey.value) ? storedSortKey.value : 'smart',
+    )
+    const groupKey = computed<LaneGroupKey>(() =>
+      isLaneGroupKey(storedGroupKey.value) ? storedGroupKey.value : 'none',
+    )
+
+    /**
+     * Whether the reader has overridden the defaults. Drives `showOverrideField`, so a
+     * preference set in advanced mode stays visible (and clearable) after a switch to basic
+     * — the one case where hiding an override would conceal a setting the board is using.
+     */
+    const hasOverride = computed(() => sortKey.value !== 'smart' || groupKey.value !== 'none')
+
+    function setSortKey(next: LaneSortKey) {
+      storedSortKey.value = next
+    }
+
+    function setGroupKey(next: LaneGroupKey) {
+      storedGroupKey.value = next
+    }
+
+    function reset() {
+      storedSortKey.value = 'smart'
+      storedGroupKey.value = 'none'
+    }
+
+    function toggleDoneLane() {
+      doneLaneCollapsed.value = !doneLaneCollapsed.value
+    }
+
+    return {
+      storedSortKey,
+      storedGroupKey,
+      doneLaneCollapsed,
+      sortKey,
+      groupKey,
+      hasOverride,
+      setSortKey,
+      setGroupKey,
+      reset,
+      toggleDoneLane,
+    }
+  },
+  { persist: { pick: ['storedSortKey', 'storedGroupKey', 'doneLaneCollapsed'] } },
+)

package/app/stores/taskExpansion.spec.ts

@@ -4,7 +4,7 @@ import { useUiStore } from '~/stores/ui'
 
 /**
  * The expansion gate combines two independent grants (hover at any zoom, the deep zoom
- * bands otherwise). Both `TaskPipelineMini` (what renders) and `DraggableTask` (what
+ * bands otherwise). Both `TaskPipelineMini` (what renders) and `LaneTask` (what
  * stacks on top) read `isExpanded`, so these cases pin the rule they share.
  *
  * Zoom is set through the ui store's raw `zoom`, the same value the board canvas writes;

package/app/stores/taskExpansion.ts

@@ -8,7 +8,7 @@ import { useUiStore } from '~/stores/ui'
  *
  * Two independent grants, both written every frame by the board driver
  * (`useTaskExpansion`) and combined HERE so the render (`TaskPipelineMini`) and the
- * stacking (`DraggableTask`) can never disagree about which cards are expanded:
+ * stacking (`LaneTask`) can never disagree about which cards are expanded:
  *
  *  - HOVER — the card under the pointer expands at ANY zoom level. Pointing at a task
  *    is asking what it is doing right now, and that answer used to be reachable only

package/app/stores/workspaceSettings.ts

@@ -12,6 +12,10 @@ const DEFAULTS: WorkspaceSettings = {
   storeAgentContext: true,
   publishPrVerificationReport: true,
   artifactRetentionDays: 14,
+  // The board's Done swimlane keeps two weeks and 20 cards. Both cap what is RENDERED; a
+  // task aged out of the lane is still on the board's data and still counted in its total.
+  doneLaneMaxItems: 20,
+  doneLaneRetentionDays: 14,
   kaizenEnabled: true,
   delegateAgentsToRunnerPool: false,
   inputGateMode: 'standard',

package/app/utils/binaryCandidates.ts

@@ -1,3 +1,4 @@
+import { platformAssetIdOf } from '@cat-factory/contracts'
 import type { BinaryCandidate, BinaryCandidateStepState, PipelineStep } from '~/types/execution'
 
 // ---------------------------------------------------------------------------
@@ -23,6 +24,17 @@ export interface BinaryCandidateRow extends BinaryCandidate {
   kept: boolean
   /** The id it is to be stored under, when the person who kept it assigned one. */
   storeAs?: string
+  /**
+   * The platform's own artifact id, when this candidate was staged through the platform's asset
+   * storage rather than an org's own service.
+   *
+   * It is the OTHER way a candidate gets a preview, and the one that works on a private estate:
+   * `previewUrl` needs the storage service to have issued a public link, which ours never does
+   * (its bytes are behind the workspace's own authenticated blob route). Without this a
+   * deployment using the shipped storage would compare candidates it could not see, which is the
+   * one thing this window exists to make possible.
+   */
+  assetId: string | null
 }
 
 /** The candidates for one subject, which is the unit a person compares. */
@@ -81,6 +93,7 @@ export function binaryCandidateView(
     const choice = kept.get(candidate.id)
     group.rows.push({
       ...candidate,
+      assetId: platformAssetIdOf(candidate),
       kept: choice !== undefined,
       ...(choice?.storeAs ? { storeAs: choice.storeAs } : {}),
     })
@@ -91,7 +104,12 @@ export function binaryCandidateView(
     awaiting: state.status === 'awaiting_choice',
     multiSelect: state.multiSelect === true,
     automatic: state.choice?.automatic === true,
-    withoutPreview: state.candidates.filter((candidate) => !candidate.previewUrl).length,
+    // Counts a candidate with NEITHER kind of preview: a service-issued link, or bytes the
+    // platform holds itself. Reading only `previewUrl` here would report every candidate of every
+    // run on the shipped storage as unviewable while the window was rendering all of them.
+    withoutPreview: state.candidates.filter(
+      (candidate) => !candidate.previewUrl && !platformAssetIdOf(candidate),
+    ).length,
   }
 }
 

package/app/utils/binaryOutput.ts

@@ -9,6 +9,7 @@ import {
   isHarnessTransport,
   modalityCarriesPixelDimensions,
   normalizeMediaType,
+  platformAssetIdOf,
   requiredBinaryCapabilities,
 } from '@cat-factory/contracts'
 import type {
@@ -103,6 +104,17 @@ export interface BinaryOutputRow extends BinaryOutputArtifact {
    * instead of letting an absent measurement read as a passing one.
    */
   missized: boolean
+  /**
+   * The platform's own artifact id, when THIS deployment is what holds the bytes: the row's
+   * service is the platform asset store and its `location` is a well-formed artifact id.
+   *
+   * It is what turns a location string into a picture the reader can look at and a file they can
+   * save, which is the whole difference between an asset in our storage and one in an org's
+   * private bucket. Null covers BOTH "stored elsewhere" and "stored here, but the location is not
+   * an id". A model's location is prose, and a paraphrased one costs the row its preview and
+   * never its record.
+   */
+  assetId: string | null
 }
 
 /**
@@ -301,6 +313,7 @@ export function binaryOutputView(step: PipelineStep | null | undefined): BinaryO
     unknown: unknown.has(artifact.service),
     // An UNATTRIBUTED row (no `generator` claimed) is not unknown — see the field's own note.
     generatorUnknown: artifact.generator !== undefined && unknownGenerators.has(artifact.generator),
+    assetId: platformAssetIdOf(artifact),
     // An UNMEASURED row is not missized either: absent dimensions are counted by
     // `sizeUnreported`, never folded in here.
     missized:

package/app/utils/catalog.ts

@@ -959,6 +959,12 @@ export const TASK_TYPE_META: Record<string, TaskTypeMeta> = {
     color: '#a78bfa',
     labelKey: 'board.addTask.types.ralph',
   },
+  media: {
+    taskType: 'media',
+    icon: 'i-lucide-image-plus',
+    color: '#f472b6',
+    labelKey: 'board.addTask.types.media',
+  },
   recurring: {
     taskType: 'recurring',
     icon: 'i-lucide-repeat',

package/app/utils/framePlacement.ts

@@ -8,6 +8,7 @@
  * nodes in. Sizes are the frame's rendered pixel footprint (see
  * {@link useBlockQueries.containerSize}).
  */
+import { frameContentSize } from '~/utils/laneGeometry'
 
 export interface Point {
   x: number
@@ -23,11 +24,15 @@ export interface FrameRect extends Point {
 export const FRAME_GAP = 48
 
 /**
- * Footprint of a freshly-added, empty service frame in flow-space. Mirrors the
- * empty-frame floor in {@link useBlockQueries.contentSize} (w 360, inner h 220) so a
- * placement decision made BEFORE the block exists matches how it will actually render.
+ * Footprint of a freshly-added, empty service frame in flow-space.
+ *
+ * DERIVED from the lane geometry rather than restated, because a placement decision is made
+ * BEFORE the block exists and so cannot measure it: the numbers here and the ones the frame
+ * renders at have to be the same numbers, or a new service is dropped on top of a neighbour it
+ * was placed to clear. A hand-copied pair went stale exactly that way when the frame's floor
+ * changed underneath it.
  */
-export const EMPTY_FRAME_SIZE = { w: 360, h: 220 }
+export const EMPTY_FRAME_SIZE = frameContentSize({ hasChildren: false, initiatives: 0 })
 
 /**
  * Footprint of an epic grouping node in flow-space. Epics are top-level board nodes

package/app/utils/laneGeometry.spec.ts

@@ -0,0 +1,69 @@
+import { describe, it, expect } from 'vitest'
+import { frameContentSize, laneBodyHeightIn, LANE_GEOMETRY } from './laneGeometry'
+
+/**
+ * These pin the RELATION between the two derivations, not their pixel arithmetic. The numbers are
+ * `LANE_GEOMETRY`'s to change; what must never change is that a frame sized by one of them hands
+ * the other back exactly what it reserved, because that is the agreement three consumers depend on
+ * (the frame's floor, what `FrameSwimlanes` renders into, and the spot placement reserves for a
+ * frame that does not exist yet).
+ */
+describe('frameContentSize', () => {
+  it('sizes a service with nothing in it to its "add the first task" panel, not to lanes', () => {
+    // An empty service renders no lanes at all, so reserving lane-sized space for it would leave
+    // the frame more than twice as tall as the one thing inside it — and push its neighbours that
+    // much further away, since placement clears frames by their reserved footprint.
+    const empty = frameContentSize({ hasChildren: false, initiatives: 0 })
+    expect(empty).toEqual({
+      w: LANE_GEOMETRY.emptyFrameWidth,
+      h: LANE_GEOMETRY.emptyFrameHeight,
+    })
+    expect(empty.h).toBeLessThan(frameContentSize({ hasChildren: true, initiatives: 0 }).h)
+  })
+
+  it('does not grow with anything except the initiative band', () => {
+    // The whole point of the lanes: a lane scrolls rather than growing, so nothing about a
+    // service's task count reaches this function. Initiatives are the one child the frame still
+    // lays out itself, so they are the one thing its height still answers to.
+    const base = frameContentSize({ hasChildren: true, initiatives: 0 })
+    expect(frameContentSize({ hasChildren: true, initiatives: 1 })).toEqual({
+      w: base.w,
+      h: base.h + LANE_GEOMETRY.initiativeHeight,
+    })
+    // A second row only once the first is full, whatever that width happens to allow.
+    const perRow = Math.floor(LANE_GEOMETRY.canvasWidth / LANE_GEOMETRY.initiativeWidth)
+    expect(frameContentSize({ hasChildren: true, initiatives: perRow }).h).toBe(
+      base.h + LANE_GEOMETRY.initiativeHeight,
+    )
+    expect(frameContentSize({ hasChildren: true, initiatives: perRow + 1 }).h).toBe(
+      base.h + 2 * LANE_GEOMETRY.initiativeHeight,
+    )
+  })
+})
+
+describe('laneBodyHeightIn', () => {
+  it('hands a frame at its floor size exactly the lane body that floor was computed from', () => {
+    // The round trip that keeps the lanes from being clipped by their own frame. Asserted for a
+    // frame with an initiative band too, since the band is the term the two have to agree about.
+    for (const initiatives of [0, 1, 5]) {
+      const floor = frameContentSize({ hasChildren: true, initiatives })
+      expect(laneBodyHeightIn(floor, initiatives)).toBe(LANE_GEOMETRY.laneBodyHeight)
+    }
+  })
+
+  it('gives a dragged-taller frame the whole extra height', () => {
+    // The contract `LANE_GEOMETRY` states and `containerSize` implements: the geometry is a FLOOR,
+    // and a reader who wants more room drags the border. The lanes kept a constant height before
+    // this, so the extra space was dead canvas below them and the gesture appeared to do nothing.
+    const floor = frameContentSize({ hasChildren: true, initiatives: 0 })
+    const dragged = { w: floor.w, h: floor.h + 300 }
+    expect(laneBodyHeightIn(dragged, 0)).toBe(LANE_GEOMETRY.laneBodyHeight + 300)
+  })
+
+  it('never returns less than the floor lane body, whatever it is handed', () => {
+    // A frame cannot be dragged below its floor, so this is only reachable by a caller measuring
+    // one mid-layout; collapsing a lane to nothing (or a negative height) is never the answer.
+    expect(laneBodyHeightIn({ w: 100, h: 0 }, 0)).toBe(LANE_GEOMETRY.laneBodyHeight)
+    expect(laneBodyHeightIn({ w: 100, h: 40 }, 12)).toBe(LANE_GEOMETRY.laneBodyHeight)
+  })
+})

package/app/utils/laneGeometry.ts

@@ -0,0 +1,104 @@
+/**
+ * The swimlane layout's fixed pixel geometry, and the two functions that derive a frame's size
+ * from it.
+ *
+ * One module rather than numbers spread across the components, because three consumers have to
+ * agree exactly: `useBlockQueries.contentSize` computes the frame's minimum size, `FrameSwimlanes`
+ * renders into that space, and `framePlacement` reserves a spot for a frame that does not exist
+ * yet. When they disagree the lanes are clipped by their own frame or a new service is dropped on
+ * top of its neighbour, both of which look like rendering bugs rather than a stale constant. That
+ * is why the two derivations below are FUNCTIONS here rather than arithmetic at each call site:
+ * a constant restating the result is exactly the thing that went stale.
+ *
+ * These are DELIBERATELY fixed rather than derived from content. A lane scrolls; it does not
+ * grow. The frame of a service with 300 open tasks is the same size as one with three, which is
+ * what keeps a board of many services readable — the old free-layout frames grew with their task
+ * count until the busiest service dwarfed everything around it. A reader who wants more room
+ * drags the frame's border, and the stored size raises the floor these numbers set.
+ */
+export const LANE_GEOMETRY = {
+  /** Card width, matching the task card's own fixed width. */
+  cardWidth: 210,
+  /** One lane column: a card plus its gutters. */
+  laneWidth: 226,
+  /** Gap between lane columns. */
+  laneGap: 8,
+  /** The three live lanes plus the gaps and the canvas's own padding. */
+  canvasWidth: 226 * 3 + 8 * 2 + 16,
+  /** A lane's scrolling body, at the frame's floor size. */
+  laneBodyHeight: 420,
+  /** A lane's header (label, count, the withheld-count line on the Done lane). */
+  laneHeaderHeight: 34,
+  /** The collapsed Done strip's header row. */
+  doneStripHeight: 32,
+  /** An initiative card in the band above the lanes. */
+  initiativeWidth: 240,
+  initiativeHeight: 176,
+  /**
+   * A service with no children at all renders one "add the first task" panel and no lanes, so it
+   * reserves the panel's footprint rather than the lanes'. Sizing an empty service as though the
+   * lanes were there would leave every new frame two and a half times taller than the thing
+   * inside it, and would push its neighbours that much further away for nothing.
+   */
+  emptyFrameWidth: 360,
+  emptyFrameHeight: 220,
+} as const
+
+/** What the frame lays out itself, which is everything its height cannot derive from a lane. */
+export interface FrameContent {
+  /**
+   * Whether the frame renders lanes at all: it has tasks, modules or initiatives under it. The
+   * same predicate `BlockNode` gates `FrameSwimlanes` on, because a size that disagrees with
+   * what rendered is the clipping bug this module exists to prevent.
+   */
+  readonly hasChildren: boolean
+  /** Initiative cards, which sit in a wrapping band above the lanes. */
+  readonly initiatives: number
+}
+
+/** How many initiative cards fit across a canvas `width` px wide. */
+function initiativeRows(count: number, width: number): number {
+  const perRow = Math.max(1, Math.floor(width / LANE_GEOMETRY.initiativeWidth))
+  return Math.ceil(count / perRow)
+}
+
+/**
+ * The smallest size that fits a frame's swimlanes and its initiative band: the floor a resizable
+ * frame can never be dragged below, and the footprint a placement decision reserves for one that
+ * does not exist yet.
+ */
+export function frameContentSize(content: FrameContent): { w: number; h: number } {
+  if (!content.hasChildren) {
+    return { w: LANE_GEOMETRY.emptyFrameWidth, h: LANE_GEOMETRY.emptyFrameHeight }
+  }
+  const w = LANE_GEOMETRY.canvasWidth
+  return {
+    w,
+    h:
+      initiativeRows(content.initiatives, w) * LANE_GEOMETRY.initiativeHeight +
+      LANE_GEOMETRY.laneBodyHeight +
+      LANE_GEOMETRY.laneHeaderHeight +
+      LANE_GEOMETRY.doneStripHeight,
+  }
+}
+
+/**
+ * How tall a lane's scrolling body is inside a frame of `size`.
+ *
+ * The inverse of {@link frameContentSize}: the room left once the initiative band, the lane
+ * headers and the collapsed Done strip have taken theirs. A frame at its floor size gets exactly
+ * `laneBodyHeight` back, and a frame the reader has dragged taller gives the whole difference to
+ * the lanes — which is the point of dragging it. Without this the lanes kept their constant
+ * height and the extra space was dead canvas below them, so the gesture appeared to do nothing.
+ *
+ * Never returns less than `laneBodyHeight`: a frame can be dragged no smaller than its floor, and
+ * a caller measuring one mid-layout should not be able to collapse a lane to nothing.
+ */
+export function laneBodyHeightIn(size: { w: number; h: number }, initiatives: number): number {
+  const room =
+    size.h -
+    initiativeRows(initiatives, size.w) * LANE_GEOMETRY.initiativeHeight -
+    LANE_GEOMETRY.laneHeaderHeight -
+    LANE_GEOMETRY.doneStripHeight
+  return Math.max(LANE_GEOMETRY.laneBodyHeight, room)
+}