@marver-design/marver 0.19.1 → 0.19.2

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 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

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`. The layout makes room for it; 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

@@ -21,10 +21,11 @@ inert. A scene note is 380 wide, a frame note 260; when a frame has both, they s
 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 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. Nobody moves frames for a note. A board dragged by hand keeps its positions; `t`
-makes the room there.
+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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marver-design/marver",
-  "version": "0.19.1",
+  "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

@@ -44,14 +44,36 @@ export function sceneNoteHost(
  *  `h + NODE_HEADER` tall, and that is the height a note beside it has to clear. */
 export const NODE_HEADER = 28
 
-/** True when a note has no room: another node's card stands inside the reserve in front of a
- *  noted node (its own note, or the scene's note it hosts). 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. Missing nodes (a deleted frame's card, still
- *  drawn full size) block room but never host a note. */
+/** 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)
@@ -62,11 +84,23 @@ export function notesCramped(
     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 r = noteReserve(!!entry(n.frame)?.note, hosts.has(n.key))
-    if (!r) return false
-    const x0 = n.x - r, y1 = n.y + n.h + NODE_HEADER
-    return nodes.some((o) => o !== n && o.x < n.x && o.x + o.w > x0 && o.y < y1 && o.y + o.h + NODE_HEADER > n.y)
+    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))
+    })
   })
 }
 

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, notesCramped } 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
@@ -483,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
@@ -996,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
@@ -1026,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

@@ -132,8 +132,9 @@ Report where the request came from: chat requests get chat replies; only comment
   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 re-applies when a note lands - never
-  move frames or pad a lane for a note, just write the file.
+  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

@@ -132,8 +132,9 @@ Report where the request came from: chat requests get chat replies; only comment
   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 re-applies when a note lands - never
-  move frames or pad a lane for a note, just write the file.
+  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

@@ -208,10 +208,12 @@ 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 when a note lands on a board that is already composed (open
-or not) the recipe re-applies and the frames make way. Never move frames, pad a lane or
-measure a gap for a note: 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.
+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