@cat-factory/app 0.274.0 → 0.276.0

package/app/stores/tutorial.ts

@@ -1,6 +1,6 @@
 import { defineStore } from 'pinia'
 import { computed, ref } from 'vue'
-import { createTutorialPrompt } from '~/stores/tutorial.prompt'
+import { createLaunchPrompt } from '~/stores/launchPrompt'
 import { createTutorialRecord } from '~/stores/tutorial.record'
 
 // `TutorialDecision` is deliberately NOT re-exported from here even though it used to live here:
@@ -37,9 +37,9 @@ export const useTutorialStore = defineStore(
   'tutorial',
   () => {
     const record = createTutorialRecord()
-    // The launch offer's own four-exit state machine (`stores/tutorial.prompt.ts`), which needs to
-    // know only WHETHER an answer exists.
-    const prompt = createTutorialPrompt({ hasDecision: () => record.decision.value !== null })
+    // The launch offer's own four-exit state machine (`stores/launchPrompt.ts`, shared with the
+    // role question), which needs to know only WHETHER an answer exists.
+    const prompt = createLaunchPrompt({ hasDecision: () => record.decision.value !== null })
     const { promptOpen } = prompt
     /**
      * The tutorial catalogue (every tour this deployment ships, startable at any time) is

package/app/stores/uiMode.spec.ts

@@ -66,6 +66,17 @@ describe('useUiModeStore mode resolution', () => {
     expect(ui.mode).toBe('advanced')
   })
 
+  it('ignores an unrecognised RESTORED value on the same terms as the env one', () => {
+    // `storedMode`'s type says what `setMode` writes, not what the persistence plugin
+    // rehydrated: an older build's blob (or a hand-edited one) arrives typed as a `UiMode`.
+    // Left unparsed it resolves to neither tier, and `isAdvanced` then answers a question
+    // about a value that is not a tier at all.
+    const ui = useUiModeStore()
+    ui.storedMode = 'expert' as UiMode
+    expect(ui.mode).toBe('basic')
+    expect(ui.isAdvanced).toBe(false)
+  })
+
   it('toggleMode flips between the two tiers', () => {
     const ui = useUiModeStore()
     ui.toggleMode()

package/app/stores/uiMode.ts

@@ -1,11 +1,13 @@
 import { defineStore } from 'pinia'
 import { computed, ref } from 'vue'
+import { useUiRoleStore } from '~/stores/uiRole'
 import { DEFAULT_RAIL_COLLAPSED, parseUiMode, resolveUiMode, type UiMode } from '~/utils/uiMode'
 
 /**
  * The interface tier (`basic` / `advanced`) and the side-navbar collapse state.
  *
- * Mode resolution is `env → browser-stored → basic` (see `utils/uiMode.ts`). The env value
+ * Mode resolution is `role surface → env → browser-stored → basic` (see `utils/uiMode.ts`); the
+ * role is the ceiling, so an `intake` role renders basic whatever the other two say. The env value
  * is `runtimeConfig.public.uiMode`, i.e. `NUXT_PUBLIC_UI_MODE`: the SPA is `ssr: false`, so
  * — exactly like `apiBase` — it is baked in at build time and cannot change while the app
  * is loaded. It is therefore read ONCE here rather than tracked reactively. Only the user's
@@ -31,7 +33,17 @@ export const useUiModeStore = defineStore(
     /** The rail state each tier was last left in, persisted. Seeded from the per-tier defaults. */
     const railCollapsed = ref<Record<UiMode, boolean>>({ ...DEFAULT_RAIL_COLLAPSED })
 
-    const mode = computed<UiMode>(() => resolveUiMode(envMode, storedMode.value))
+    // The role's surface caps the tier (see `resolveUiMode`): an `intake` role renders basic
+    // whatever the env pin or the stored choice says, so every `isAdvanced` reader in the app
+    // agrees with the narrowed nav without restating the role.
+    const uiRole = useUiRoleStore()
+    // The restored value goes through `parseUiMode` for the same reason the env string does, and
+    // for the reason `railCollapsed` is read defensively just below: `storedMode`'s type says
+    // what `setMode` writes, not what the persistence plugin rehydrated. An unrecognised tier
+    // would otherwise pass straight through `resolveUiMode` and render as neither tier.
+    const mode = computed<UiMode>(() =>
+      resolveUiMode(envMode, parseUiMode(storedMode.value), uiRole.surface),
+    )
     const isAdvanced = computed(() => mode.value === 'advanced')
     /** Pinned by the deployment: the switcher is read-only, since a write would be ignored. */
     const envPinned = computed(() => envMode !== null)

package/app/stores/uiRole.spec.ts

@@ -0,0 +1,185 @@
+import { beforeEach, describe, expect, it } from 'vitest'
+import { createPinia, setActivePinia } from 'pinia'
+import { missingI18nKeys } from '../../test/i18nKeys'
+import { useUiRoleStore } from '~/stores/uiRole'
+import { useUiModeStore } from '~/stores/uiMode'
+import {
+  parseUiRole,
+  ROLE_PRESENTATION,
+  ROLE_SURFACES,
+  UI_ROLES,
+  type UiRole,
+} from '~/utils/uiRole'
+
+describe('useUiRoleStore role resolution', () => {
+  it('boots on the FULL surface with nothing stored, and says nobody has chosen', () => {
+    // The two halves of the first-run condition, and they must not be conflated: an unanswered
+    // question leaves the whole product in place (`fullSurface`) while still being unanswered
+    // (`chosen`), which is what lets the prompt ask again without ever having taken anything away.
+    const role = useUiRoleStore()
+    expect(role.chosen).toBe(false)
+    expect(role.role).toBe('engineer')
+    expect(role.fullSurface).toBe(true)
+  })
+
+  it('honours a stored choice and narrows only for the intake role', () => {
+    const role = useUiRoleStore()
+    role.setRole('product-manager')
+    expect(role.role).toBe('product-manager')
+    expect(role.chosen).toBe(true)
+    // Engineer and product-manager resolve to the SAME surface today; that is the product
+    // decision, not an accident of the mapping.
+    expect(role.fullSurface).toBe(true)
+
+    role.setRole('designer')
+    expect(role.surface).toBe('intake')
+    expect(role.fullSurface).toBe(false)
+    // Persisted, so a reload restores it (the persist plugin picks `storedRole`).
+    expect(role.storedRole).toBe('designer')
+  })
+
+  it('coerces an unknown persisted value on the way IN, not at the call sites', () => {
+    // What the persistence plugin restores is a JSON blob an older build wrote or somebody hand
+    // edited, so an unknown string arrives typed as a `UiRole` and nothing downstream is
+    // forgiving: `ROLE_SURFACES[role]` is `undefined` (the nav narrows to intake without a
+    // word) and `ROLE_PRESENTATION[role].labelKey` throws in the switcher. Writing the raw
+    // value onto `storedRole` is exactly what hydration does, which is why this drives the
+    // STORE rather than calling `parseUiRole` by hand: a guard nothing calls looks identical to
+    // a guard that works.
+    const role = useUiRoleStore()
+    role.storedRole = 'architect' as UiRole
+
+    expect(role.role).toBe('engineer')
+    expect(role.surface).toBe('full')
+    expect(role.fullSurface).toBe(true)
+    // An unrecognised value is not an ANSWER, so the first-run prompt asks again and the person
+    // can replace it. Reading `storedRole !== null` instead pins the browser to the default with
+    // the one question that would fix it already marked settled.
+    expect(role.chosen).toBe(false)
+    // The resolved role indexes both catalogs, which is the property the switcher relies on.
+    expect(ROLE_PRESENTATION[role.role].labelKey).toBeTruthy()
+    expect(ROLE_SURFACES[role.role]).toBe('full')
+  })
+
+  it('parses a raw value the way the store consumes it', () => {
+    expect(parseUiRole('lead-designer')).toBeNull()
+    expect(parseUiRole(undefined)).toBeNull()
+    expect(parseUiRole(' Designer ')).toBe('designer')
+  })
+})
+
+describe('useUiRoleStore first-run prompt', () => {
+  it('offers itself once per session while unanswered', () => {
+    const role = useUiRoleStore()
+    role.maybeOfferOnLaunch()
+    expect(role.promptOpen).toBe(true)
+
+    // Closing without answering writes nothing, so the NEXT launch asks again, but this
+    // session's one offer is spent.
+    role.closePrompt()
+    expect(role.storedRole).toBeNull()
+    role.maybeOfferOnLaunch()
+    expect(role.promptOpen).toBe(false)
+  })
+
+  it('never offers itself again once a role is recorded', () => {
+    const role = useUiRoleStore()
+    role.setRole('designer')
+    role.maybeOfferOnLaunch()
+    expect(role.promptOpen).toBe(false)
+  })
+
+  it('re-arms after a deferral, so a startup advisory does not consume the offer', () => {
+    // What `pages/index.vue` does when an advisory the user must answer opens on top: the offer
+    // is withdrawn and comes back, rather than counting as a question they were asked.
+    const role = useUiRoleStore()
+    role.maybeOfferOnLaunch()
+    role.deferPrompt()
+    expect(role.promptOpen).toBe(false)
+    role.maybeOfferOnLaunch()
+    expect(role.promptOpen).toBe(true)
+  })
+
+  it('leaves a user-opened prompt alone on a deferral', () => {
+    // Opened from the command palette: it is the user's, so nothing withdraws it.
+    const role = useUiRoleStore()
+    role.openPrompt()
+    role.deferPrompt()
+    expect(role.promptOpen).toBe(true)
+  })
+
+  it('settles the prompt by picking a role', () => {
+    const role = useUiRoleStore()
+    role.openPrompt()
+    role.setRole('engineer')
+    expect(role.promptOpen).toBe(false)
+    expect(role.chosen).toBe(true)
+  })
+})
+
+describe('the role as a ceiling on the interface tier', () => {
+  beforeEach(() => {
+    setActivePinia(createPinia())
+  })
+
+  it('caps a narrowed role at the basic tier, whatever the user stored', () => {
+    // Resolved rather than merely hidden: every `isAdvanced` reader inside a surface (the
+    // override fields, the authoring affordances) has to agree with the narrowed nav, and only
+    // the resolved mode reaches all of them.
+    const mode = useUiModeStore()
+    mode.setMode('advanced')
+    expect(mode.isAdvanced).toBe(true)
+
+    useUiRoleStore().setRole('designer')
+    expect(mode.mode).toBe('basic')
+    expect(mode.isAdvanced).toBe(false)
+
+    // Leaving the narrowed role restores the tier the person had picked: the cap withholds the
+    // tier, it does not overwrite the preference.
+    useUiRoleStore().setRole('engineer')
+    expect(mode.isAdvanced).toBe(true)
+  })
+})
+
+describe('UI_ROLES catalog integrity', () => {
+  it('maps every role to a surface and presents each one', () => {
+    // Derived from the vocabulary rather than re-listed, so a new role fails here (and in the
+    // exhaustive Records themselves) until it has picked a surface and gained its copy.
+    expect(Object.keys(ROLE_SURFACES).sort()).toEqual([...UI_ROLES].sort())
+    expect(Object.keys(ROLE_PRESENTATION).sort()).toEqual([...UI_ROLES].sort())
+    // Exactly one narrowed role today, and the full ones are the majority: a mapping that
+    // narrowed everything would pass every other assertion in this file.
+    const surfaces = UI_ROLES.map((role: UiRole) => ROLE_SURFACES[role])
+    expect(surfaces.filter((s) => s === 'full').length).toBeGreaterThan(0)
+    expect(surfaces.filter((s) => s === 'intake').length).toBeGreaterThan(0)
+  })
+
+  it('names an i18n key that exists for every role label and hint', () => {
+    // A table lookup is invisible to typed message keys and to `i18n:check` (neither sees
+    // `t(ROLE_PRESENTATION[role].labelKey)`), so deleting one of these keys would otherwise read
+    // as a clean removal and render its own key path in the picker.
+    const keys = UI_ROLES.flatMap((role: UiRole) => [
+      ROLE_PRESENTATION[role].labelKey,
+      ROLE_PRESENTATION[role].hintKey,
+    ])
+    expect(missingI18nKeys(keys)).toEqual([])
+    // And the copy the two surfaces around them use, which is written literally there but is
+    // just as easy to rename out from under this table.
+    expect(
+      missingI18nKeys([
+        'uiRole.switcher',
+        'uiRole.prompt.title',
+        'uiRole.prompt.intro',
+        'uiRole.prompt.change',
+        'uiRole.prompt.later',
+      ]),
+    ).toEqual([])
+  })
+
+  it('gives every role a distinct glyph', () => {
+    // The rail renders the glyph alone above a truncated name, so two roles sharing one would be
+    // indistinguishable exactly where the label has the least room.
+    const icons = UI_ROLES.map((role: UiRole) => ROLE_PRESENTATION[role].icon)
+    expect(new Set(icons).size).toBe(icons.length)
+  })
+})

package/app/stores/uiRole.ts

@@ -0,0 +1,86 @@
+import { defineStore } from 'pinia'
+import { computed, ref } from 'vue'
+import { createLaunchPrompt } from '~/stores/launchPrompt'
+import {
+  isFullSurfaceRole,
+  parseUiRole,
+  resolveUiRole,
+  roleSurface,
+  type UiRole,
+} from '~/utils/uiRole'
+
+/**
+ * The role the person is here to do (`engineer` / `product-manager` / `designer`) and the
+ * first-run question that asks for it. Resolution and the surface each role maps to are in
+ * `utils/uiRole.ts`.
+ *
+ * Only the person's own choice exists: there is deliberately NO deployment env pin, unlike the
+ * interface tier. The tier is a fleet-shaped decision an operator can reasonably make for a
+ * kiosk deployment; which JOB the person at the keyboard does is not something the build can
+ * know, and pinning it would leave a designer's laptop configured as an engineer's with no way
+ * to say otherwise.
+ *
+ * `chosen` is the whole of the first-run condition: no recognised answer is recorded, which is
+ * what the prompt asks about, and it is what a browser that has never been asked, one whose
+ * answer was cleared, and one carrying a value that is no longer a role all have in common. The
+ * resolved role stays the default throughout, so an unanswered question never takes a
+ * destination away.
+ */
+export const useUiRoleStore = defineStore(
+  'uiRole',
+  () => {
+    /** The person's explicit pick, persisted. `null` until they choose one. */
+    const storedRole = ref<UiRole | null>(null)
+
+    /**
+     * The persisted pick, COERCED, and the only thing anything below reads.
+     *
+     * `storedRole`'s type describes what {@link setRole} WRITES, not what boot restores into it:
+     * the persistence plugin rehydrates a JSON blob a previous build wrote or a person hand-
+     * edited, so an unknown string arrives typed as a `UiRole` and every reader believes it.
+     * There is nothing forgiving downstream to catch it: `ROLE_SURFACES[role]` is `undefined`,
+     * which narrows the nav to intake without a word, and `ROLE_PRESENTATION[role].labelKey`
+     * throws in the switcher, i.e. white-screens the board rather than degrading. So the raw
+     * value is parsed ONCE here, exactly as `agentTier` does with its own restored level.
+     *
+     * `chosen` reads it too, and that is the half that makes the degradation honest rather than
+     * merely safe: an unrecognised value is not an answer, so the first-run prompt asks again
+     * and the person can replace it. Reading `storedRole !== null` instead would leave a browser
+     * pinned to the default with the question it needs to be asked already marked settled.
+     */
+    const pickedRole = computed<UiRole | null>(() => parseUiRole(storedRole.value))
+
+    const role = computed<UiRole>(() => resolveUiRole(pickedRole.value))
+    const surface = computed(() => roleSurface(role.value))
+    /**
+     * The role sees the whole product. Read by the nav gate of the same name and by the few
+     * surfaces that narrow inline; stated positively so no reader has to invert it.
+     */
+    const fullSurface = computed(() => isFullSurfaceRole(role.value))
+    /** A RECOGNISED answer has been recorded, so the first-run prompt has nothing left to ask. */
+    const chosen = computed(() => pickedRole.value !== null)
+
+    // The same once-per-session launch machine the tutorial offer runs on: the question is
+    // answered by PICKING a role, so `hasDecision` is exactly `chosen`. Closing without picking
+    // writes nothing and the next launch asks again, which is safe here precisely because the
+    // default is the full surface.
+    const prompt = createLaunchPrompt({ hasDecision: () => chosen.value })
+
+    /** Record the person's pick and settle the question. */
+    function setRole(next: UiRole) {
+      storedRole.value = next
+      prompt.promptOpen.value = false
+    }
+
+    return {
+      role,
+      surface,
+      fullSurface,
+      chosen,
+      storedRole,
+      ...prompt,
+      setRole,
+    }
+  },
+  { persist: { pick: ['storedRole'] } },
+)

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/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)
+}