@marver-design/marver 0.18.0 → 0.19.0

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,21 @@ 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.
+  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,21 @@ 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.
+  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,68 @@ 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.
+
+````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