@marver-design/marver 0.19.0 → 0.19.2

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 Notable changes to `@marver-design/marver`. Format follows [Keep a Changelog](https://keepachangelog.com); versions follow semver.
 
+## 0.19.2 - 2026-09-09
+
+### Fixed
+
+- **A note longer than its frame gets its room below.** 0.19.1 reserved a note's width beside its
+  frame and nothing under it: a long note ran on below the card and over the next row's notes and
+  frames. The column's height is now measured as it renders (markdown, fonts and diagrams decide
+  it) and fed to the layout: a composed board's next row starts under the note, the gutter still
+  the card's, and a board already saved re-applies its recipe when a note lands or grows past its
+  frame, as it did for width. Two columns running into each other count as cramped too; the empty
+  canvas under a card beside a long column is free. Leaving a device view re-checks the room the
+  restored rows have. Folding a note keeps its room, so a fold never moves the board.
+
+## 0.19.1 - 2026-09-08
+
+### Fixed
+
+- **A note landing on a composed board makes its own room.** 0.19.0 reserved a note's width only
+  when tidy ran; a note file added to a board that already had saved positions stood on its left
+  neighbour until someone pressed `t`. A board with a recipe (or the auto board) now re-applies
+  its layout when a note has no room - as the file lands while the board is open, and at load
+  when it landed while the board was closed - and saves the result. Boards dragged by hand keep
+  their positions, as before. A deleted frame's card counts as an obstacle; a drag inside the
+  reflow's debounce is never overwritten. The agent instructions say it plainly: placement is
+  the canvas's job, write the file.
+
 ## 0.19.0 - 2026-09-08
 
 ### Added

package/README.md

@@ -45,7 +45,7 @@ Frames appear on the canvas the moment the files land. That's the loop.
 - **Prototype links.** `data-goto="scene/frame"` on any element links frames into a walkable prototype - across boards, too.
 - **Five ways to view a board.** The canvas (frames on a plane), the board (the same, tidy), **present** (`p`: a full-screen clickable walkthrough - `data-goto` navigates, arrows step, `[` / `]` cycle variants, laser, comments, theme and device pickers in the toolbar), **focus** (one frame as a document - the reading preset for specs), and **slides** (a deck). A published board names its landing view; a frame deep link opens straight into it.
 - **Content frames.** Specs, Mermaid diagrams, mood boards, and slides live on the same canvas as the screens - import `Doc`, `Md`, `Diagram`, `Img`, `Slide`, `Chart`, `Video` from `@marver-design/marver/content` and think a feature through before any pixels exist. Works in a repo with no app at all: idea first, design second.
-- **Sticky notes.** A markdown file beside a frame (`cart.note.md`) or a scene (`_note.md`) becomes a yellow note left of the frame on the canvas - what it is for, how two variations differ, an open question. Markdown, `goto:` links to frames, hand-drawn Mermaid; readers comment on a note's text like on a frame's, fold it to its corner, hide them all with `n`. Published canvases carry them.
+- **Sticky notes.** A markdown file beside a frame (`cart.note.md`) or a scene (`_note.md`) becomes a yellow note left of the frame on the canvas - what it is for, how two variations differ, an open question. Markdown, `goto:` links to frames, hand-drawn Mermaid; readers comment on a note's text like on a frame's, fold it to its corner, hide them all with `n`. The layout makes room for it, beside the frame and below; published canvases carry them.
 - **Hi-fi at rest.** A frame at rest is its own live document, asleep: animations paused and every `backdrop-filter` element painted with a certified texture of its filtered backdrop (compiled by the dev server's headless Chrome), so a board of 30 glass screens pans like 30 statics and wakes pixel-identical on interact. Glass inside glass, blend modes and frames whose paint depends on random data or the clock stay live; `?awake=1` keeps every frame live for comparison.
 - **Charts and video in any frame.** `Chart` (Apache ECharts, SVG, still at rest) inherits the ink, typeface and accent of whatever frame it sits in - a Tailwind dashboard, a dark spec, a slide - sizes its type to the context and follows the layout on resize. `Video` is poster-first everywhere: click to play wherever the frame is live, `autoplay` for an ambient loop, `ratio` for vertical clips; omit the poster and marver renders one from the clip. A screen with a chart or a clip is still a screen.
 - **Copy as image.** Select a frame, press `i` - a 2x PNG of it lands on the clipboard, rendered by the same headless Chrome that serves `marver shot`; `⇧i` for 4x (a slide is 5120×2880). Paste into Slack, a doc, or a chat with your agent.

package/docs/sticky-notes.md

@@ -20,6 +20,13 @@ links jump to a frame; `http(s)` links open a new tab; images come from `design/
 inert. A scene note is 380 wide, a frame note 260; when a frame has both, they stack in one column,
 scene first. An edit lands on the canvas as you save, without reloading the frame.
 
+The room is the layout's job. Every layout the shell composes (a board's `layout` recipe, the auto
+board, tidy, device views) reserves the note's width in front of its frame and its height below it:
+a note longer than its frame runs on under the card, and the row beneath starts under the note, the
+gutter unchanged. A note landing on a board already composed re-applies the recipe so the frames
+make way - whether the board is open at the time or not - and so does a note that grows. Nobody
+moves frames for a note. A board dragged by hand keeps its positions; `t` makes the room there.
+
 ## Diagrams
 
 A ```mermaid fence renders hand-sketched on the paper: rough boxes, hatched fills, handwriting

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marver-design/marver",
-  "version": "0.19.0",
+  "version": "0.19.2",
   "description": "The agent-native design canvas. A design/ folder, one command, a canvas of live frames built from your repo's real components - comment @marver and your own coding agent does the work. The tool ships no AI.",
   "type": "module",
   "private": false,

package/src/client/shell/canvas/Sticky.tsx

@@ -19,6 +19,7 @@ import { cleanSource, guardDiagramSource, sanitizeSvg } from '../../content/diag
 import { useComments } from '../comments-store.ts'
 import { goTo } from '../goto.ts'
 import { NOTE_W, SCENE_NOTE_W, noteAnchor, noteVisible, useNotes, type NoteKind } from '../notes.ts'
+import { useStore } from '../store.ts'
 
 export interface NoteSpec { kind: NoteKind; id: string; text: string }
 
@@ -266,10 +267,24 @@ function StickyBody({ text, kind, nodeKey, frameId }: { text: string; kind: Note
 export const Stickies = memo(function Stickies({ nodeKey, frameId, notes, underBadge }: { nodeKey: string; frameId: string; notes: NoteSpec[]; underBadge: boolean }) {
   const ids = notes.map((n) => n.id)
   const on = useNotes((s) => noteVisible(s, ids))
+  const col = useRef<HTMLDivElement>(null)
+  // the column's extent is measured, never computed: markdown, fonts and diagrams decide it. The
+  // layout gets it (and its changes) so a note longer than its frame has room below; a folded
+  // column keeps its height (the fold is a transform), so folding never reflows. Unmounting
+  // (notes gone, board switched) clears it.
+  useEffect(() => {
+    const el = col.current
+    if (!el) return
+    const report = () => useStore.getState().noteMeasured(nodeKey, el.offsetTop + el.offsetHeight)
+    const ro = new ResizeObserver(report)
+    ro.observe(el)
+    report()
+    return () => { ro.disconnect(); useStore.getState().noteMeasured(nodeKey, 0) }
+  }, [nodeKey, underBadge, notes.length])
   if (!notes.length) return null
   const width = Math.max(...notes.map((n) => (n.kind === 'scene' ? SCENE_NOTE_W : NOTE_W)))
   return (
-    <div className={`sh-notes${on ? '' : ' off'}${underBadge ? ' below-vbadge' : ''}`} data-node-notes={nodeKey} style={{ width }}>
+    <div ref={col} className={`sh-notes${on ? '' : ' off'}${underBadge ? ' below-vbadge' : ''}`} data-node-notes={nodeKey} style={{ width }}>
       <button className="sh-notes-fold sh-no-pan" type="button" aria-label={on ? 'hide notes' : 'show notes'} title={on ? 'hide notes (N: all)' : 'show notes (N: all)'}
         onPointerDown={(e) => e.stopPropagation()}
         onClick={(e) => { e.stopPropagation(); useNotes.getState().toggle(ids) }} />

package/src/client/shell/notes.ts

@@ -40,6 +40,70 @@ export function sceneNoteHost(
   return best ? (best as { key: string }).key : null
 }
 
+/** The node header the canvas draws above a frame body (FrameNode's HEADER) - a node's card is
+ *  `h + NODE_HEADER` tall, and that is the height a note beside it has to clear. */
+export const NODE_HEADER = 28
+
+/** The measured extent of a node's note column: world px from the node's top to the bottom of
+ *  its last sticky (0 = no column, or not rendered yet). A note's height is its content's, known
+ *  only once it is drawn - so, like a content frame's height, it is measured, transient (never
+ *  serialized, a reload remeasures), and fed back to the layout when it lands. */
+const noteHeights = new Map<string, number>()
+export const noteHeight = (key: string): number => noteHeights.get(key) ?? 0
+/** Record a column's extent; true when it changed (the caller asks the layout for room then). */
+export function setNoteHeight(key: string, h: number): boolean {
+  const H = Number.isFinite(h) && h > 0 ? Math.round(h) : 0
+  if ((noteHeights.get(key) ?? 0) === H) return false
+  if (H) noteHeights.set(key, H)
+  else noteHeights.delete(key)
+  return true
+}
+/** A board load starts from no heights: node keys are per board file, and a key another board
+ *  also uses must not bring its column's height along (the old board unmounts after the load). */
+export const clearNoteHeights = (): void => { noteHeights.clear() }
+
+/** True when a note has no room: another node stands inside the space in front of a noted node
+ *  (its own note, or the scene's note it hosts) - beside its card, or below it where a note taller
+ *  than its frame runs on. Room is the layout's job, never the author's - a board the shell
+ *  composes re-applies its layout when this is true, so a note file can land on a saved board and
+ *  the frames make way. An obstacle is another node's card, or its own note column (two columns
+ *  running into each other cramp too) - the two rectangles, never their bounding box: the empty
+ *  canvas under a card beside a long column is free. Missing nodes (a deleted frame's card, still
+ *  drawn full size) block room but never host a note. `noteH` is the measured column extent. */
+export function notesCramped(
+  nodes: readonly { key: string; frame: string; x: number; y: number; w: number; h: number; missing?: boolean }[],
+  manifest: { frames: { id: string; scene: string; note?: string }[]; scenes: { name: string; note?: string }[] } | null,
+  noteH: (key: string) => number = noteHeight,
+): boolean {
+  if (!manifest) return false
+  const entry = (id: string) => manifest.frames.find((f) => f.id === id)
+  const live = nodes.filter((n) => !n.missing)
+  const hosts = new Set<string>()
+  for (const s of manifest.scenes) {
+    if (!s.note) continue
+    const h = sceneNoteHost(live, (id) => entry(id)?.scene, s.name)
+    if (h) hosts.add(h)
+  }
+  type N = (typeof nodes)[number]
+  type R = { x0: number; x1: number; y0: number; y1: number }
+  const hit = (a: R, b: R) => a.x0 < b.x1 && a.x1 > b.x0 && a.y0 < b.y1 && a.y1 > b.y0
+  const card = (n: N): R => ({ x0: n.x, x1: n.x + n.w, y0: n.y, y1: n.y + n.h + NODE_HEADER })
+  // the room a note takes: the reserve beside the card, as tall as the card or the column, whichever runs further
+  const room = (n: N): R | null => {
+    const r = n.missing ? 0 : noteReserve(!!entry(n.frame)?.note, hosts.has(n.key))
+    return r ? { x0: n.x - r, x1: n.x, y0: n.y, y1: n.y + Math.max(n.h + NODE_HEADER, noteH(n.key)) } : null
+  }
+  return live.some((n) => {
+    const mine = room(n)
+    if (!mine) return false
+    return nodes.some((o) => {
+      if (o === n) return false
+      const theirs = room(o)
+      return hit(mine, card(o)) || (!!theirs && hit(mine, theirs))
+    })
+  })
+}
+
 // ---- per-viewer visibility -------------------------------------------------------------
 
 const STORAGE = 'mv-notes'

package/src/client/shell/store.ts

@@ -1,7 +1,7 @@
 import { create } from 'zustand'
 import { ROUTE, slideSize } from '../const.ts'
 import { tidy, parseLayout, type BoardLayout, type TidyNode } from './tidy.ts'
-import { noteReserve } from './notes.ts'
+import { clearNoteHeights, noteHeight, noteReserve, notesCramped, setNoteHeight } from './notes.ts'
 import { stableNodeKey } from './keys.ts'
 // @ts-expect-error virtual module provided by the plugin
 import shConfig from 'virtual:sh-config'
@@ -208,9 +208,10 @@ export async function boardFrames(name: string): Promise<string[]> {
 }
 
 const HEADER = 28
-/** What tidy sees: nodes with their scene, variant run, header-inclusive height, and the sticky
+/** What tidy sees: nodes with their scene, variant run, header-inclusive height, the sticky
  *  note width to reserve in front (spec 18: the frame's note, and the scene's on every member -
- *  tidy keeps the scene reserve on the first node it places). */
+ *  tidy keeps the scene reserve on the first node it places), and the measured height of the
+ *  column standing there, so a note longer than its frame gets its room below as well. */
 export function tidyInput(nodes: readonly Node[], manifest: Manifest | null): TidyNode[] {
   const entryOf = (id: string) => manifest?.frames.find((f) => f.id === id)
   const sceneNote = (scene: string) => !!manifest?.scenes.find((s) => s.name === scene)?.note
@@ -219,7 +220,7 @@ export function tidyInput(nodes: readonly Node[], manifest: Manifest | null): Ti
     const scene = f?.scene ?? ''
     return {
       key: n.key, frame: n.frame, scene, group: f?.variantGroup, variant: f?.variant, w: n.w, h: n.h + HEADER,
-      noteW: noteReserve(!!f?.note, false), sceneNoteW: noteReserve(false, sceneNote(scene)),
+      noteW: noteReserve(!!f?.note, false), sceneNoteW: noteReserve(false, sceneNote(scene)), noteH: noteHeight(n.key),
     }
   })
 }
@@ -327,6 +328,8 @@ interface State {
   moveNode(key: string, x: number, y: number): void
   resizeNode(key: string, w: number, h: number): void
   measureNode(key: string, frameId: string, ownWidth: number, measuredWidth: number, height: number): void
+  /** A node's sticky column was drawn (or grew, or went): its extent from the node's top, world px. */
+  noteMeasured(key: string, height: number): void
   setStatus(key: string, status: Node['status'], error?: string): void
   bumpRev(key: string): void
   setThemeOn(key: string, theme: string): void
@@ -411,17 +414,32 @@ export const useStore = create<State>((set, get) => {
   // One cancelable, BOARD-SCOPED reflow after content measurements settle.
   // The captured board name is the generation guard - a debounce surviving a board
   // switch fires into a name check and dies, never touching the new board.
+  // `onlyIf` (a note asking for room) is re-judged when the timer fires - a drag or a restore
+  // in the meantime may have settled it - and never downgrades an unconditional reflow pending.
   let reflowTimer: ReturnType<typeof setTimeout> | undefined
-  const scheduleReflow = () => {
+  let reflowCheck: (() => boolean) | null = null
+  const scheduleReflow = (onlyIf?: () => boolean) => {
     const boardAt = get().board
+    reflowCheck = reflowTimer !== undefined && reflowCheck === null ? null : (onlyIf ?? null)
     clearTimeout(reflowTimer)
     reflowTimer = setTimeout(() => {
+      reflowTimer = undefined
+      const check = reflowCheck
+      reflowCheck = null
       const s = get()
       if (s.board !== boardAt) return
-      if (s.gesture) { scheduleReflow(); return }   // defer, never drop - retries after the drag
-      if (s.layout || s.sceneRows?.length) s.runTidy()
+      if (s.gesture) { scheduleReflow(check ?? undefined); return }   // defer, never drop - retries after the drag
+      if (check && !check()) return
+      if (composed(s)) s.runTidy()
     }, 400)
   }
+  /** Boards whose layout the shell owns: a recipe, scene rows, or the auto board. Room for a
+   *  note is made here; a board the human placed by hand is never moved (spec 18, 0.19.1). */
+  const composed = (s: { layout: BoardLayout | null; sceneRows: string[][] | null; boardAuto: boolean }) => !!(s.layout || s.sceneRows?.length || s.boardAuto)
+  const cramped = () => { const s = get(); return !!s.manifest && notesCramped(s.nodes, s.manifest) }
+  /** A note may have landed with no room (a frame note via the manifest, a scene note via
+   *  sh:scenes, either merged late by boot/switch): a composed board re-applies its layout. */
+  const roomForNotes = () => { if (composed(get()) && cramped()) scheduleReflow(cramped) }
 
   /** Theme resolution ladder: user pin > the frame's declared meta.theme > viewTheme. */
   const resolveTheme = (frame?: FrameEntry, user?: string) => user ?? frame?.theme ?? get().viewTheme
@@ -468,6 +486,7 @@ export const useStore = create<State>((set, get) => {
    *  null = failure (transport, malformed manifest, non-404 board error) - the caller
    *  keeps whatever board is currently mounted. */
   const loadBoardState = async (boardName: string): Promise<Partial<State> | null> => {
+    clearNoteHeights()                     // heights are per column drawn; a key shared by two board files carries none across
     try {
       let raw: any
       if (DATA) raw = DATA.manifest
@@ -628,18 +647,22 @@ export const useStore = create<State>((set, get) => {
           }
         }
       }
-      if ((!boardHash || needTidy) && nodes.length) {
+      // a note that landed while this board was closed has no room in the saved positions:
+      // a board with a recipe re-applies it (spec 18 - room is the layout's job)
+      const cramped = !!boardHash && !needTidy && !!(layout || sceneRows?.length || boardAuto) && notesCramped(nodes, manifest)
+      if ((!boardHash || needTidy || cramped) && nodes.length) {
         const placedAll = tidy(tidyInput(nodes, manifest), effectiveLayout(layout, sceneRows), layoutWarn)
         for (const pl of placedAll) { const n = nodes.find((x) => x.key === pl.key)!; n.x = pl.x; n.y = pl.y }
       }
       // dirty matches disk by construction - except when load-time pruning changed the
-      // node set; callers see dirty:true and schedule the save that persists the prune
+      // node set (or a cramped note re-ran the recipe); callers see dirty:true and
+      // schedule the save that persists it
       // surface recipe problems at load (dry-run): materialized boards otherwise
       // never run tidy, so a broken agent-authored layout would fail silently
-      if (layout && boardHash && !needTidy && nodes.length) {
+      if (layout && boardHash && !needTidy && !cramped && nodes.length) {
         tidy(tidyInput(nodes, manifest), layout, layoutWarn)
       }
-      return { manifest, nodes, boardHash, boardAuto, deviceView, sceneRows, layout, layoutRaw, baseLayout, selection: [], dirty: prunedAtLoad }
+      return { manifest, nodes, boardHash, boardAuto, deviceView, sceneRows, layout, layoutRaw, baseLayout, selection: [], dirty: prunedAtLoad || cramped }
     } catch { return null }
   }
 
@@ -663,6 +686,7 @@ export const useStore = create<State>((set, get) => {
       if (next.dirty) scheduleSave()          // load-time prune must reach the disk
       if (live && manifestKey(live) !== manifestKey(next.manifest as Manifest)) get().applyManifest(live)
       else if (scenesRev !== scenesAtStart && liveScenes) set({ manifest: { ...get().manifest!, scenes: liveScenes } })   // an sh:scenes that landed mid-fetch outranks the file we read
+      roomForNotes()                          // whichever way the notes arrived, they get their room
       return true
     },
 
@@ -697,6 +721,7 @@ export const useStore = create<State>((set, get) => {
       if (next.dirty) scheduleSave()           // load-time prune must reach the disk
       if (live && manifestKey(live) !== manifestKey(next.manifest as Manifest)) get().applyManifest(live)
       else if (scenesRev !== scenesAtStart && liveScenes) set({ manifest: { ...get().manifest!, scenes: liveScenes } })
+      roomForNotes()
     },
 
     renameBoard(name, title, baseHash) {
@@ -749,6 +774,7 @@ export const useStore = create<State>((set, get) => {
       liveScenes = scenes
       const m = get().manifest
       if (m) set({ manifest: { ...m, scenes } })   // before the first manifest: kept for the boot's commit
+      roomForNotes()                         // a scene note arrived: room beside the scene's first frame
     },
 
     // The whole sidebar tree in one write: order, membership, the folders themselves. The
@@ -871,6 +897,7 @@ export const useStore = create<State>((set, get) => {
         ...(changed ? { dirty: true, baseLayout: nextBase } : {}),
       }))
       if (changed) scheduleSave()
+      roomForNotes()                         // a frame note file arrived: room in front of its frame
     },
 
     removeNode(key) {
@@ -973,6 +1000,11 @@ export const useStore = create<State>((set, get) => {
       set((st) => ({ nodes: st.nodes.map((n) => (n.key === key ? { ...n, h: H } : n)) }))
       scheduleReflow()
     },
+    noteMeasured(key, height) {
+      // the column's height is its content's - the layout learns it here, and a composed board
+      // whose next row now stands under a long note re-applies its recipe (0.19.2)
+      if (setNoteHeight(key, height)) roomForNotes()
+    },
     setDeviceView(name) {
       const vp = name ? CONFIG.viewports[name] : null
       if (name && !vp) return
@@ -1003,7 +1035,7 @@ export const useStore = create<State>((set, get) => {
         return { deviceView: name, dirty: true, baseLayout, nodes }
       })
       if (name) get().runTidy()                      // restore must NOT tidy - it would destroy positions
-      else scheduleSave()
+      else { scheduleSave(); roomForNotes() }         // ...unless a note grew meanwhile and the restored rows stand under it
     },
     bumpRev(key) { set((s) => ({ nodes: s.nodes.map((n) => (n.key === key ? { ...n, rev: (n.rev ?? 0) + 1 } : n)) })) },
     setThemeOn(key, theme) { set((s) => ({ nodes: s.nodes.map((n) => (n.key === key ? { ...n, themeOn: theme } : n)) })) },

package/src/client/shell/tidy.ts

@@ -4,6 +4,10 @@ export interface TidyNode {
    *  (its own note), and in front of the scene's first placed node (the scene note - carried on
    *  every member, applied once). A column holds both, so the wider wins, never the sum. */
   noteW?: number; sceneNoteW?: number
+  /** The note column's measured extent (world px from the node's top), when it is known. A column
+   *  taller than its card runs below it: the node takes that height in its lane, so the next
+   *  lane starts under the note - the gutter itself is still sized from the card. */
+  noteH?: number
 }
 export interface Placed { key: string; x: number; y: number }
 
@@ -36,20 +40,23 @@ interface Box {
   charW: number; charH: number
 }
 
-const box = (id: string, parts: Array<{ key: string; dx: number; dy: number; w: number; h: number }>): Box => ({
+/** `h` is the part's extent (card, or its note column when that runs further); `ch` the card's own
+ *  height, the characteristic size gutters are measured from - a long note never inflates them. */
+const box = (id: string, parts: Array<{ key: string; dx: number; dy: number; w: number; h: number; ch?: number }>): Box => ({
   id,
   parts: parts.map(({ key, dx, dy }) => ({ key, dx, dy })),
   w: Math.max(0, ...parts.map((p) => p.dx + p.w)),
   h: Math.max(0, ...parts.map((p) => p.dy + p.h)),
   charW: Math.max(0, ...parts.map((p) => p.w)),
-  charH: Math.max(0, ...parts.map((p) => p.h)),
+  charH: Math.max(0, ...parts.map((p) => p.ch ?? p.h)),
 })
+const extent = (n: TidyNode) => Math.max(n.h, n.noteH ?? 0)
 
 /** A run of nodes laid side by side (a frame's instances, or a variant run). */
 const runBox = (id: string, run: TidyNode[]): Box => {
-  const parts: Array<{ key: string; dx: number; dy: number; w: number; h: number }> = []
+  const parts: Array<{ key: string; dx: number; dy: number; w: number; h: number; ch?: number }> = []
   let dx = 0
-  for (const n of run) { dx += n.noteW ?? 0; parts.push({ key: n.key, dx, dy: 0, w: n.w, h: n.h }); dx += n.w + frameGapX(n.w) }
+  for (const n of run) { dx += n.noteW ?? 0; parts.push({ key: n.key, dx, dy: 0, w: n.w, h: extent(n), ch: n.h }); dx += n.w + frameGapX(n.w) }
   return box(id, parts)
 }
 
@@ -285,7 +292,7 @@ export function tidy(nodes: TidyNode[], layout?: BoardLayout, warn: Warn = () =>
     sceneMaps.set(scene, m)
     const parts = members
       .filter((n) => m.has(n.key))
-      .map((n) => ({ key: n.key, dx: m.get(n.key)!.x, dy: m.get(n.key)!.y, w: n.w, h: n.h }))
+      .map((n) => ({ key: n.key, dx: m.get(n.key)!.x, dy: m.get(n.key)!.y, w: n.w, h: extent(n), ch: n.h }))
     sceneBoxes.set(scene, box(scene, parts))
   }
 

package/templates/AGENTS-embedded.md

@@ -131,6 +131,10 @@ Report where the request came from: chat requests get chat replies; only comment
   width; gantt, journey and timeline are wide by nature - few items, or a content frame) -
   raw HTML is inert. Readers comment on a note's text like on a frame element,
   fold it to its corner, hide all with N. An edit lands live without reloading the frame.
+  Placement is not your job: every composed layout (recipe, auto board, tidy, device views)
+  reserves the note's room in front of its frame and below it (a long note pushes the next
+  row down) and re-applies when a note lands or grows - never move frames or pad a lane for
+  a note, sideways or down, just write the file.
   Keep it an aside, a screen's worth at most: specs, flows and mood boards stay content frames.
   Full guide: instructions/shape.md.
 

package/templates/AGENTS-studio.md

@@ -131,6 +131,10 @@ Report where the request came from: chat requests get chat replies; only comment
   width; gantt, journey and timeline are wide by nature - few items, or a content frame) -
   raw HTML is inert. Readers comment on a note's text like on a frame element,
   fold it to its corner, hide all with N. An edit lands live without reloading the frame.
+  Placement is not your job: every composed layout (recipe, auto board, tidy, device views)
+  reserves the note's room in front of its frame and below it (a long note pushes the next
+  row down) and re-applies when a note lands or grows - never move frames or pad a lane for
+  a note, sideways or down, just write the file.
   Keep it an aside, a screen's worth at most: specs, flows and mood boards stay content frames.
   Full guide: instructions/shape.md.
 

package/templates/instructions/shape.md

@@ -206,6 +206,15 @@ links open a new tab, images are `design/assets/` paths, raw HTML is inert, and
 ` ```mermaid ` fence renders hand-drawn, in the note's own yellow. Readers can comment on any
 element of a note exactly as on a frame element.
 
+Placement is not your job: the canvas keeps the room. Every layout the shell composes - a
+board's `layout` recipe, the auto board, tidy, device views - reserves the note's width and
+gutter in front of its frame, and its height below it: a note longer than its frame runs on
+under the card and the next row starts under the note. When a note lands on a board that is
+already composed (open or not), or grows, the recipe re-applies and the frames make way. Never
+move frames, pad a lane or measure a gap for a note, sideways or down: write the file and the
+board takes care of it. Only a board the human dragged by hand keeps its positions as they
+are; their `t` makes the room there.
+
 ````md
 ## Why the jobs list leads