@marver-design/marver 0.18.0 → 0.19.1

package/src/client/shell/store.ts

@@ -1,6 +1,7 @@
 import { create } from 'zustand'
 import { ROUTE, slideSize } from '../const.ts'
-import { tidy, parseLayout, type BoardLayout } from './tidy.ts'
+import { tidy, parseLayout, type BoardLayout, type TidyNode } from './tidy.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'
@@ -50,8 +51,8 @@ export function hydrateBoardPolicy(boards: Record<string, { type?: string; open?
   for (const [k, v] of Object.entries(boards)) if (!BOARD_POLICY[k]) BOARD_POLICY[k] = v
 }
 
-export interface FrameEntry { id: string; file: string; kind: 'tsx' | 'html'; scene: string; title?: string; viewport?: string; theme?: string; variantGroup?: string; variant?: string; intent?: string; contentWidth?: number; slide?: boolean }
-export interface Manifest { frames: FrameEntry[]; scenes: { name: string; frames: number; title?: string; description?: string }[] }
+export interface FrameEntry { id: string; file: string; kind: 'tsx' | 'html'; scene: string; title?: string; viewport?: string; theme?: string; variantGroup?: string; variant?: string; intent?: string; contentWidth?: number; slide?: boolean; note?: string }
+export interface Manifest { frames: FrameEntry[]; scenes: { name: string; frames: number; title?: string; description?: string; note?: string }[] }
 export interface Node {
   key: string; frame: string; x: number; y: number; w: number; h: number
   /** RESOLVED theme (what renders): themeUser ?? frame meta.theme ?? viewTheme. */
@@ -207,6 +208,21 @@ 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
+ *  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). */
+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
+  return nodes.map((n) => {
+    const f = entryOf(n.frame)
+    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)),
+    }
+  })
+}
 let toastSeq = 0
 const nodeKey = () => 'n_' + Math.random().toString(36).slice(2, 8)
 
@@ -395,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
@@ -612,26 +643,22 @@ export const useStore = create<State>((set, get) => {
           }
         }
       }
-      if ((!boardHash || needTidy) && nodes.length) {
-        const entryOf = (id: string) => manifest.frames.find((f) => f.id === id)
-        const placedAll = tidy(nodes.map((n) => {
-          const f = entryOf(n.frame)
-          return { key: n.key, frame: n.frame, scene: f?.scene ?? '', group: f?.variantGroup, variant: f?.variant, w: n.w, h: n.h + HEADER }
-        }), effectiveLayout(layout, sceneRows), layoutWarn)
+      // 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) {
-        const entryOf2 = (id: string) => manifest.frames.find((f) => f.id === id)
-        tidy(nodes.map((n) => {
-          const f = entryOf2(n.frame)
-          return { key: n.key, frame: n.frame, scene: f?.scene ?? '', group: f?.variantGroup, variant: f?.variant, w: n.w, h: n.h + HEADER }
-        }), layout, layoutWarn)
+      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 }
   }
 
@@ -655,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
     },
 
@@ -689,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) {
@@ -741,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
@@ -863,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) {
@@ -1203,11 +1234,7 @@ export const useStore = create<State>((set, get) => {
     },
     runTidy() {
       const { nodes, manifest, sceneRows, layout } = get()
-      const entryOf = (id: string) => manifest?.frames.find((f) => f.id === id)
-      const placed = tidy(nodes.map((n) => {
-        const f = entryOf(n.frame)
-        return { key: n.key, frame: n.frame, scene: f?.scene ?? '', group: f?.variantGroup, variant: f?.variant, w: n.w, h: n.h + HEADER }
-      }), effectiveLayout(layout, sceneRows), layoutWarn)
+      const placed = tidy(tidyInput(nodes, manifest), effectiveLayout(layout, sceneRows), layoutWarn)
       set((s) => ({
         nodes: s.nodes.map((n) => {
           const p = placed.find((x) => x.key === n.key)

package/src/client/shell/styles.css

@@ -1022,6 +1022,8 @@ body.sh-hide-ui .sh-play-nav { display: none !important }
   margin-left: calc(-1 * clamp(8px, calc(12px * var(--sh-inv, 1)), 36px)) }
 .cm-card.parked.dock-l.flank-shim { margin-left: calc(-1 * clamp(18px, calc(28px * var(--sh-inv, 1)), 68px)) }
 .cm-card.parked.dock-l.flank-badge { margin-left: calc(-1 * clamp(26px, calc(44px * var(--sh-inv, 1)), 108px)) }
+/* a sticky column (spec 18) is world-sized: the card clears it and its gutter */
+.cm-card.parked.dock-l.flank-note { margin-left: calc(-1 * (var(--sh-note-w, 260px) + 36px)) }
 /* PLAY: fixed beside the static device, viewport-clamped (position comes inline). Near-solid
    ground - the stage floats the card over arbitrary artwork on a dark room, glass is unreadable
    there. No transform: play has no zoom, and a leaked --sh-inv must never scale it. */
@@ -1265,3 +1267,84 @@ body.sh-hide-ui .sh-play-nav { display: none !important }
 .sh-slides-strip .bar { width: 140px; height: 3px; border-radius: 999px; background: var(--glass-hover); overflow: hidden }
 .sh-slides-strip .bar i { display: block; height: 100%; border-radius: inherit; background: var(--accent); transition: width .25s ease }
 @media (max-width: 480px) { .sh-slides-strip .bar { width: 80px } }
+
+
+/* ---- sticky notes (spec 18): the yellow column left of a frame ------------------------------
+   World-sized (it scales with the canvas, like the artwork); the fold's hit target keeps a screen
+   minimum through --sh-inv. Yellow in both shell themes - a sticky is yellow. */
+.sh-node { --note-bg: #fff3a3; --note-bg-2: #ffeb85; --note-ink: #2b2500; --note-dim: rgba(43, 37, 0, .62);
+  --note-line: rgba(107, 90, 0, .28); --note-link: #7a4d00; --note-fold: #e9cf5e; --note-fold-2: #c9ae3c }
+/* dark canvas: a deeper mustard so the paper reads as paper, not as a highlight; ink darker for contrast */
+.sh-node[data-theme="dark"] { --note-bg: #e6c94f; --note-bg-2: #d6b73c; --note-ink: #1f1a00; --note-dim: rgba(31, 26, 0, .68);
+  --note-line: rgba(70, 56, 0, .35); --note-link: #5c3a00; --note-fold: #c9aa33; --note-fold-2: #8f7518 }
+.sh-notes { position: absolute; right: 100%; top: 0; margin-right: 24px;
+  display: flex; flex-direction: column; align-items: flex-end; gap: 12px; pointer-events: none }
+.sh-notes.below-vbadge { top: 72px }
+.sh-notes > * { pointer-events: auto }
+.sh-sticky { position: relative; box-sizing: border-box; background: var(--note-bg); color: var(--note-ink);
+  border-radius: 2px 10px 2px 2px; padding: 14px 16px 12px;
+  box-shadow: 0 1px 2px rgba(60, 45, 0, .18), 0 6px 18px -6px rgba(60, 45, 0, .35);
+  font: 400 13px/1.45 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+  transform-origin: top right; opacity: 1; visibility: visible;
+  transition: transform .18s cubic-bezier(.2, .7, .3, 1), opacity .16s ease, visibility 0s linear 0s;
+  user-select: text; -webkit-user-select: text; cursor: default }
+.sh-sticky[data-sticky="scene"] { padding: 18px 20px 16px; font-size: 14px }
+.sh-notes.off .sh-sticky { transform: scale(.04); opacity: 0; visibility: hidden;
+  transition: transform .18s cubic-bezier(.4, 0, .8, .4), opacity .14s ease .04s, visibility 0s linear .18s; pointer-events: none }
+/* the dog-ear: on the column it is the top sticky's folded corner; folded, it is the tab that stays */
+.sh-notes-fold { position: absolute; top: 0; right: 0; z-index: 2; padding: 0; border: 0; cursor: pointer;
+  width: clamp(22px, calc(14px * var(--sh-inv, 1)), 72px); height: clamp(22px, calc(14px * var(--sh-inv, 1)), 72px);
+  border-radius: 0 10px 0 4px;
+  background: linear-gradient(225deg, transparent 50%, var(--note-fold) 50%, var(--note-fold-2) 100%);
+  transition: background .18s ease, border-radius .18s ease, box-shadow .18s ease, transform .18s ease }
+.sh-notes-fold:hover { filter: brightness(.96) }
+.sh-notes-fold:focus-visible { outline: 2px solid var(--accent, #2f6df6); outline-offset: 2px }
+.sh-notes.off .sh-notes-fold { border-radius: 3px 3px 3px 8px; background: linear-gradient(160deg, var(--note-bg) 0%, var(--note-bg-2) 100%);
+  box-shadow: 0 1px 2px rgba(60, 45, 0, .25), 0 3px 8px -2px rgba(60, 45, 0, .35) }
+.sh-notes.off .sh-notes-fold::after { content: ""; position: absolute; right: 0; top: 0; width: 38%; height: 38%;
+  border-radius: 0 3px 0 3px; background: linear-gradient(225deg, transparent 50%, var(--note-fold-2) 50%) }
+@media (prefers-reduced-motion: reduce) { .sh-sticky, .sh-notes-fold { transition: none } }
+/* comment mode: hover names the element the click would pick; the lock is the shell's own outline */
+body.sh-commenting .sh-sticky-body :is(p, li, h1, h2, h3, h4, blockquote, pre, img, table, .sh-sticky-diagram):hover { outline: 1.5px solid var(--accent, #2f6df6); outline-offset: 2px; border-radius: 3px }
+body.sh-commenting .sh-sticky-body { cursor: crosshair }
+.sh-sticky-body [data-sh-lock] { outline: 2px solid hsl(var(--cm-h, 48) 80% 42%); outline-offset: 3px; border-radius: 3px;
+  box-shadow: 0 0 0 5px hsl(var(--cm-h, 48) 90% 60% / .28) }
+/* prose: the Md block's vocabulary, sized for an aside */
+.sh-sticky-body > :first-child { margin-top: 0 }
+.sh-sticky-body > :last-child { margin-bottom: 0 }
+.sh-sticky-body h1, .sh-sticky-body h2, .sh-sticky-body h3, .sh-sticky-body h4 { margin: 0 0 6px; line-height: 1.25; letter-spacing: -0.01em; text-wrap: balance }
+.sh-sticky-body h1 { font-size: 1.28em; font-weight: 700 }
+.sh-sticky-body h2 { font-size: 1.14em; font-weight: 650 }
+.sh-sticky-body h3, .sh-sticky-body h4 { font-size: 1em; font-weight: 650 }
+.sh-sticky-body p, .sh-sticky-body ul, .sh-sticky-body ol, .sh-sticky-body blockquote, .sh-sticky-body pre, .sh-sticky-body table { margin: 0 0 8px }
+.sh-sticky-body ul, .sh-sticky-body ol { padding-left: 18px }
+.sh-sticky-body li { margin: 2px 0 }
+.sh-sticky-body li > ul, .sh-sticky-body li > ol { margin-bottom: 0 }
+.sh-sticky-body blockquote { padding: 2px 0 2px 10px; border-left: 3px solid var(--note-line); color: var(--note-dim) }
+.sh-sticky-body a { color: var(--note-link); text-decoration: underline; text-underline-offset: 2px; text-decoration-color: rgba(122, 77, 0, .45) }
+.sh-sticky-body a:hover { text-decoration-color: currentColor }
+.sh-sticky-body a[data-goto]::after { content: "\2197"; font-size: .8em; margin-left: 2px; text-decoration: none; display: inline-block }
+.sh-sticky-body code { font: 500 .9em/1.4 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; background: rgba(43, 37, 0, .07); padding: 1px 4px; border-radius: 3px }
+.sh-sticky-body pre { padding: 8px 10px; border-radius: 6px; background: rgba(43, 37, 0, .07); overflow-x: auto; white-space: pre }
+.sh-sticky-body pre code { background: none; padding: 0; font-weight: 400 }
+.sh-sticky-body pre.err { background: rgba(190, 40, 20, .1); color: #7a1f0f }
+.sh-sticky-body hr { border: 0; border-top: 1px solid var(--note-line); margin: 10px 0 }
+.sh-sticky-body img { max-width: 100%; border-radius: 4px; display: block }
+.sh-sticky-body strong { font-weight: 650 }
+.sh-sticky-body table { border-collapse: collapse; font-size: .92em; width: 100%; table-layout: auto }
+.sh-sticky-body td, .sh-sticky-body th { overflow-wrap: anywhere }
+.sh-sticky-body th, .sh-sticky-body td { border: 1px solid var(--note-line); padding: 3px 6px; text-align: left; vertical-align: top }
+.sh-sticky-body th { font-weight: 650; background: rgba(43, 37, 0, .05) }
+.sh-sticky-body input[type="checkbox"] { margin: 0 6px 0 0; vertical-align: -1px }
+.sh-sticky-body .mv-md-noimg { color: var(--note-dim); font-style: italic }
+.sh-sticky-body .mv-c-blue { color: #0070d6 } .sh-sticky-body .mv-c-orange { color: #c9640a } .sh-sticky-body .mv-c-purple { color: #9a23ad }
+.sh-sticky-body .mv-c-green { color: #1a8a3f } .sh-sticky-body .mv-c-red { color: #c72a22 } .sh-sticky-body .mv-c-gray { color: #6b7480 }
+/* the hand-drawn diagram: the fence's place, the paper's colors, scaled to the column */
+.sh-sticky-diagram { margin: 4px 0 10px; overflow: visible; display: flex; justify-content: center }
+.sh-sticky-diagram svg { display: block; max-width: 100%; height: auto; margin: 0 auto;
+  /* the canvas scales the world with a CSS transform, and Chrome lays SVG text out ONCE for the
+     scale it was inserted at (a diagram born at 13 % zoom keeps 13 %-zoom glyph positions at
+     140 %: labels drift, some vanish). geometricPrecision lays glyphs out scale-free - measured,
+     research/notes/diagprobe5.ts */
+  text-rendering: geometricPrecision }
+.sh-sticky-diagram svg text, .sh-sticky-diagram svg tspan { text-rendering: geometricPrecision }

package/src/client/shell/tidy.ts

@@ -1,4 +1,10 @@
-export interface TidyNode { key: string; frame: string; scene: string; group?: string; variant?: string; w: number; h: number }
+export interface TidyNode {
+  key: string; frame: string; scene: string; group?: string; variant?: string; w: number; h: number
+  /** Sticky notes (spec 18), world px INCLUDING the gutter: reserved in front of this node
+   *  (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
+}
 export interface Placed { key: string; x: number; y: number }
 
 // Lane-flow grammar: one shape at both scopes. A scope is rows XOR columns
@@ -43,7 +49,7 @@ const box = (id: string, parts: Array<{ key: string; dx: number; dy: number; w:
 const runBox = (id: string, run: TidyNode[]): Box => {
   const parts: Array<{ key: string; dx: number; dy: number; w: number; h: number }> = []
   let dx = 0
-  for (const n of run) { 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: n.h }); dx += n.w + frameGapX(n.w) }
   return box(id, parts)
 }
 
@@ -264,6 +270,18 @@ export function tidy(nodes: TidyNode[], layout?: BoardLayout, warn: Warn = () =>
   for (const scene of scenes) {
     const members = nodes.filter((n) => n.scene === scene)
     const m = layoutScene(scene, members, layout?.scenes?.[scene], warn)
+    // the scene note sits in front of the scene's first node in reading order (the host the
+    // shell picks): widen the scene box on the left by what that node's own note does not cover
+    const sceneNoteW = Math.max(0, ...members.map((n) => n.sceneNoteW ?? 0))
+    if (sceneNoteW) {
+      const placed = members.filter((n) => m.has(n.key))
+      const first = placed.reduce<TidyNode | null>((best, n) => {
+        const p = m.get(n.key)!, b = best && m.get(best.key)!
+        return !b || p.y < b.y || (p.y === b.y && p.x < b.x) ? n : best
+      }, null)
+      const extra = sceneNoteW - (first?.noteW ?? 0)
+      if (extra > 0) for (const [k, p] of m) m.set(k, { x: p.x + extra, y: p.y })
+    }
     sceneMaps.set(scene, m)
     const parts = members
       .filter((n) => m.has(n.key))

package/templates/AGENTS-embedded.md

@@ -118,6 +118,24 @@ Report where the request came from: chat requests get chat replies; only comment
 - CONTENT frames (specs, mermaid diagrams, mood boards) are ordinary tsx frames built
   from the block primitives in '@marver-design/marver/content' - import them directly
   in the frame file and declare meta.intent. Full guide: instructions/shape.md.
+- STICKY NOTES: the aside beside a frame. One markdown file, nothing to declare:
+  `design/scenes/<scene>/<frame>.note.md` beside the frame file (tsx, jsx or html),
+  `design/scenes/<scene>/_note.md` for the scene (it shows beside the scene's first frame),
+  `design/components/<name>.note.md` for a component. It renders as a yellow note left of the
+  frame on every canvas, dev and published. Write one when a reader needs what the screen
+  cannot say: what the frame is for, how two variations differ, how a mechanism works, an
+  open question. Markdown (headings, lists, tables, emphasis, code), `[text](goto:scene/frame)`
+  links that jump to a frame, images from design/assets/, and ```mermaid fences drawn
+  hand-sketched in the note's own yellow - plain mermaid, any family, no init/theme/style
+  lines, no URLs (flowchart, sequence, state, class, ER, pie, mindmap read well at note
+  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.
 
 ## Structure ladder (embedded mode: screens live in src/)
 1. First pass: write the whole page inline in the frame file. Diverge fast.

package/templates/AGENTS-studio.md

@@ -118,6 +118,24 @@ Report where the request came from: chat requests get chat replies; only comment
 - CONTENT frames (specs, mermaid diagrams, mood boards) are ordinary tsx frames built
   from the block primitives in '@marver-design/marver/content' - import them directly
   in the frame file and declare meta.intent. Full guide: instructions/shape.md.
+- STICKY NOTES: the aside beside a frame. One markdown file, nothing to declare:
+  `design/scenes/<scene>/<frame>.note.md` beside the frame file (tsx, jsx or html),
+  `design/scenes/<scene>/_note.md` for the scene (it shows beside the scene's first frame),
+  `design/components/<name>.note.md` for a component. It renders as a yellow note left of the
+  frame on every canvas, dev and published. Write one when a reader needs what the screen
+  cannot say: what the frame is for, how two variations differ, how a mechanism works, an
+  open question. Markdown (headings, lists, tables, emphasis, code), `[text](goto:scene/frame)`
+  links that jump to a frame, images from design/assets/, and ```mermaid fences drawn
+  hand-sketched in the note's own yellow - plain mermaid, any family, no init/theme/style
+  lines, no URLs (flowchart, sequence, state, class, ER, pie, mindmap read well at note
+  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.
 
 ## Structure ladder
 1. First pass: write the whole page inline in the frame file. Diverge fast.

package/templates/instructions/shape.md

@@ -187,6 +187,75 @@ of described imagery every time (the full asset rules: instructions/craft.md,
   has the shell-less way) and adjust the per-row count until it reads well. "The code
   says they're the same width" proves nothing.
 
+## Sticky notes - the aside beside a frame
+
+A sticky note is one markdown file beside the thing it explains. It renders as a yellow note
+left of the frame on the canvas, in dev and in every published or shared canvas. Nothing to
+declare, no board node, no imports, no iframe:
+
+| For | Write | Shows |
+|---|---|---|
+| a frame `checkout/cart` (`cart.tsx`, `cart.jsx` or `cart.html`) | `design/scenes/checkout/cart.note.md` | left of that frame, 260 wide |
+| a scene `checkout` | `design/scenes/checkout/_note.md` | left of the scene's first frame on the board, 380 wide |
+| a component frame | `design/components/<name>.note.md` | as a frame note |
+
+Write one when a reader needs something the screen cannot say: what the frame is for, what
+differs between two variations, how a mechanism works, an open question. Markdown, the Md
+block's rules: `[text](goto:scene/frame)` links jump to a frame on the canvas, `http(s)`
+links open a new tab, images are `design/assets/` paths, raw HTML is inert, and a
+` ```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
+
+Drivers ask "where am I going first" - the list beats the map here.
+Compare with the [empty day](goto:app-home/today-empty): same header, one call to action.
+
+| Reason | Effect |
+|---|---|
+| Too far | lane weight down |
+
+```mermaid
+flowchart LR
+  Login --> Today --> Jobs
+```
+````
+
+### Diagrams in a note
+
+A ```mermaid fence in a note renders hand-sketched on the yellow paper: rough boxes, hatched
+fills, handwriting labels, one ink. You write plain mermaid and nothing else - no `%%{init}%%`,
+no theme, no colours, no `style` lines (the note has one look and applies it to every family),
+no URLs or images in the source (refused). Every family works: flowchart, sequence, state,
+class, ER, pie, mindmap, timeline, gantt, journey, quadrant, git graph, block.
+
+Fit the note: flowchart (`TD` for a tall note, `LR` for three or four steps), sequence, state,
+class, ER, pie and mindmap read well at 260 or 380 wide. Gantt, journey, timeline, quadrant and
+git graphs are drawn at the note's width too but are wide by nature - keep them to a handful of
+items, or give them a content frame. Five to eight nodes is the sweet spot; short labels
+(two or three words); one diagram per note, above or below the prose it explains.
+
+```mermaid
+sequenceDiagram
+  participant D as Driver
+  participant G as Gate
+  D->>G: scan gate code
+  G-->>D: bay + lot map
+```
+
+Keep it an aside: a screen's worth of reading at most. The spec, the flow, the mood board stay
+content frames - a note explains, it does not document. Every viewer can fold a note to its
+corner tab (the choice is theirs, never saved to the board) and hide all of them with `N`.
+Edits to a note file land on the canvas as you save, without reloading the frame.
+
 ## When Shape ends
 
 The board holds the agreed flow, spec, and direction. Wireframe picks up from