@marver-design/marver 0.19.0 → 0.19.1

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.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; 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,12 @@ 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 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.
+
 ## 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.1",
   "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/notes.ts

@@ -40,6 +40,36 @@ 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
+
+/** 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. */
+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,
+): 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)
+  }
+  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)
+  })
+}
+
 // ---- 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 { noteReserve, notesCramped } from './notes.ts'
 import { stableNodeKey } from './keys.ts'
 // @ts-expect-error virtual module provided by the plugin
 import shConfig from 'virtual:sh-config'
@@ -411,17 +411,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
@@ -628,18 +643,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 +682,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 +717,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 +770,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 +893,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) {

package/templates/AGENTS-embedded.md

@@ -131,6 +131,9 @@ 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 re-applies when a note lands - never
+  move frames or pad a lane for a note, 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,9 @@ 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 re-applies when a note lands - never
+  move frames or pad a lane for a note, 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,13 @@ 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 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.
+
 ````md
 ## Why the jobs list leads