@marver-design/marver 0.4.0 → 0.6.0

package/src/client/shell/styles.css

@@ -122,6 +122,13 @@ button { font-family: inherit }
 button svg { pointer-events: none }   /* event targets stay on the button - pan exclusion depends on it */
 @media (prefers-reduced-motion: reduce) { *, *::before, *::after { transition: none !important } }
 
+/* Default app pointer: the marver arrowhead (tilted left, rounded, thick border, soft shadow),
+   theme-adaptive - black/white on light, white/dark on dark. Hotspot at its tip (5,2). Overridden by
+   the state cursors: grab (space-pan), resize handles, comment-pin / laser-crosshair (set in-frame by
+   the bridge), and a normal pointer in interact / prototype mode. */
+.sh-app { --sh-cursor: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='22' height='22' viewBox='0 0 26 26'%3E%3Cdefs%3E%3Cfilter id='s' x='-40%' y='-40%' width='180%' height='180%'%3E%3CfeDropShadow dx='0.4' dy='0.9' stdDeviation='0.7' flood-color='%23000000' flood-opacity='0.4'/%3E%3C/filter%3E%3C/defs%3E%3Cg filter='url(%23s)'%3E%3Cg transform='rotate(-20 6 3)'%3E%3Cpath fill='%23000000' stroke='%23FFFFFF' stroke-width='1.6' stroke-linejoin='round' stroke-linecap='round' d='M5.5 3.21V20.8c0 .45.54.67.85.35l4.86-4.86a1 1 0 0 1 .7-.3h6.87a1 1 0 0 0 .7-1.7L6.35 2.85a.5.5 0 0 0-.85.35Z'/%3E%3C/g%3E%3C/g%3E%3C/svg%3E") 5 2, default; cursor: var(--sh-cursor) }
+.sh-app.dark { --sh-cursor: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='22' height='22' viewBox='0 0 26 26'%3E%3Cdefs%3E%3Cfilter id='s' x='-40%' y='-40%' width='180%' height='180%'%3E%3CfeDropShadow dx='0.4' dy='0.9' stdDeviation='0.7' flood-color='%23000000' flood-opacity='0.4'/%3E%3C/filter%3E%3C/defs%3E%3Cg filter='url(%23s)'%3E%3Cg transform='rotate(-20 6 3)'%3E%3Cpath fill='%23FFFFFF' stroke='%2318181b' stroke-width='1.6' stroke-linejoin='round' stroke-linecap='round' d='M5.5 3.21V20.8c0 .45.54.67.85.35l4.86-4.86a1 1 0 0 1 .7-.3h6.87a1 1 0 0 0 .7-1.7L6.35 2.85a.5.5 0 0 0-.85.35Z'/%3E%3C/g%3E%3C/g%3E%3C/svg%3E") 5 2, default }
+.sh-app.interacting { cursor: auto }
 .sh-app { position: relative; height: 100%; color: var(--glass-ink); outline: none;
   transition: --accent .4s ease, --accent-ring .4s ease, --beam .4s ease,
     --edge-accent .4s ease, --inner-tint .4s ease, --accent-wash .4s ease,
@@ -141,15 +148,20 @@ button svg { pointer-events: none }   /* event targets stay on the button - pan
   opacity: var(--grid-alpha, 1) }
 .sh-content { will-change: auto }
 #sh-world { position: relative; width: 1px; height: 1px }
-#sh-world.sh-gesturing iframe { pointer-events: none }            /* law G-4 */
+#sh-world.sh-gesturing .sh-live { pointer-events: none }          /* law G-4 (live iframe only; lean is always pe:none) */
 .sh-gesturing .sh-content { will-change: transform }              /* law G-3: gesture-scoped only */
 /* preset transitions: armed by animateLayout() around device/tidy mutations - nodes ease
    to their new frame on the same 320ms ease-out the camera fit animates with */
 #sh-world.sh-preset .sh-node { transition: transform .32s cubic-bezier(.25,.46,.45,.94),
   width .32s cubic-bezier(.25,.46,.45,.94), height .32s cubic-bezier(.25,.46,.45,.94) }
 #sh-world.sh-preset .sh-node-body,
-#sh-world.sh-preset .sh-node iframe { transition: width .32s cubic-bezier(.25,.46,.45,.94),
+#sh-world.sh-preset .sh-node .sh-live { transition: width .32s cubic-bezier(.25,.46,.45,.94),
   height .32s cubic-bezier(.25,.46,.45,.94) }
+/* SPEC-M5 device-sweep: a frame WITH a ready lean cover jumps its LIVE iframe straight to the final
+   width (ONE reflow, hidden under the cover) while the lean cover - being width:100% of the animating
+   body - reflows smoothly every frame (real CSS, the device-sweep fix). A frame WITHOUT a usable
+   cover keeps the live width animation above. */
+body:not(.sh-laser):not(.sh-commenting) #sh-world.sh-preset .sh-node:has(.sh-lean[data-ready]):not(.interact) .sh-live { transition: none }
 
 /* cursor conventions (Figma): arrow everywhere; grab only while space is held */
 body.sh-space .sh-canvas { cursor: grab }
@@ -183,7 +195,7 @@ body.sh-space .sh-node { pointer-events: none }                   /* space-drag
   box-shadow: 0 0 0 calc(4px * var(--sh-inv, 1)) var(--accent-ring), var(--shadow-node) }
 .sh-node-head { height: 28px; display: flex; align-items: center; gap: 8px; padding: 0 11px;
   font-size: 11px; color: var(--head-dim);
-  border-bottom: 1px solid var(--node-brd); cursor: default; user-select: none;
+  border-bottom: 1px solid var(--node-brd); user-select: none;
   border-radius: var(--r-node) var(--r-node) 0 0;
   background-color: var(--head-bg); background-image: var(--head-sheen);
   backdrop-filter: var(--blur); -webkit-backdrop-filter: var(--blur) }
@@ -197,7 +209,20 @@ body.sh-space .sh-node { pointer-events: none }                   /* space-drag
 .sh-node-head .dim { margin-left: auto; color: var(--head-dim); flex: none; font-variant-numeric: tabular-nums }
 .sh-node-body { position: relative; background: var(--node-bg); border-radius: 0 0 var(--r-node) var(--r-node); overflow: hidden }
 .sh-node iframe { border: 0; display: block }
-.sh-overlay { position: absolute; inset: 0; cursor: default }
+/* SPEC-M5 LEAN-PRIMARY: the lean DOM-snapshot <iframe> (static html, 0 JS) is what you SEE for a
+   passive frame - at rest AND during pan/zoom/resize. There is NO per-gesture swap between the lean
+   and the live iframe (the swap shifted text ~1-2px = "jiggle", and flashed mermaid/theme colors,
+   because two documents never render pixel-identically). The live app (.sh-live) sits underneath and
+   shows ONLY when: the frame is interacted (.interact), laser/comment mode is on, or the lean is not
+   yet built (no data-ready = live-fallback). Hard cut, never a crossfade - two ~1px-offset text docs
+   would ghost into double text. */
+.sh-lean { position: absolute; inset: 0; width: 100%; height: 100%; border: 0; z-index: 1;
+  opacity: 0; pointer-events: none; transition: none; background: var(--node-bg) }
+.sh-lean[data-ready] { opacity: 1 }
+.sh-node.interact .sh-lean,
+body.sh-laser .sh-lean,
+body.sh-commenting .sh-lean { opacity: 0 }
+.sh-overlay { position: absolute; inset: 0; z-index: 2 }   /* above the lean (z1) so drag-by-body works; inherits the app arrow cursor */
 .sh-node.interact { border-color: var(--interact);
   outline: calc(2px * var(--sh-inv, 1)) solid var(--interact);
   outline-offset: calc(-1px * var(--sh-inv, 1));
@@ -319,8 +344,11 @@ body.sh-space .sh-node { pointer-events: none }                   /* space-drag
   transform-origin: 22px 22px; transition: transform var(--morph), opacity .2s ease }
 .sh-panel.closed { transform: scale(.16); opacity: 0; pointer-events: none }
 .sh-panel-top { display: flex; align-items: center; gap: 8px; padding: 2px 2px 8px 8px }
-.sh-panel-top .mark { flex: none; color: var(--accent) }
-.sh-panel-top .name { font-weight: 700; font-size: 15px; flex: 1; letter-spacing: -0.01em }
+.sh-panel-top .mark-link { flex: none; display: flex; border-radius: 6px; outline-offset: 2px; transition: opacity .15s ease }
+.sh-panel-top .mark-link:hover { opacity: .72 }
+.sh-panel-top .mark { flex: none; color: var(--accent); display: block }
+.sh-panel-top .name { margin-right: auto; min-width: 0; font-weight: 700; font-size: 15px; letter-spacing: -0.01em;
+  overflow: hidden; text-overflow: ellipsis; white-space: nowrap }
 .sh-panel-scroll { overflow-y: auto; min-height: 0; padding-bottom: 2px; scrollbar-width: thin;
   scrollbar-color: var(--glass-ink-3) transparent }
 /* Sidebar list system (macOS-sidebar conventions): every row is 28px tall with an
@@ -449,7 +477,7 @@ body.sh-space .sh-node { pointer-events: none }                   /* space-drag
 /* ---- Play mode (SPEC-M2 §1): near-black stage, one centered device, auto-hiding bar.
    Fixed dark palette - the backdrop never follows the board theme, so no tokens here. */
 .sh-play { position: absolute; inset: 0; z-index: 30; background: #0a0a0b; display: flex;
-  align-items: center; justify-content: center; animation: sh-play-in .28s ease-out }
+  align-items: center; justify-content: center; animation: sh-play-in .28s ease-out; cursor: auto }
 @keyframes sh-play-in { from { opacity: 0 } }
 /* the device wears the frame-node card language: same theme border tokens, the same
    masked 1px edge-light gradient ring (glass catching light), and a real drop shadow
@@ -498,6 +526,8 @@ body.sh-space .sh-node { pointer-events: none }                   /* space-drag
 /* board switcher */
 .sh-play-bar .bd-wrap { position: relative }
 .sh-play-bar .bd { width: auto; gap: 6px; padding: 0 10px 0 12px; white-space: nowrap; font: inherit }
+.sh-play-bar .sh-play-update { width: auto; gap: 5px; padding: 0 11px; font-size: 12px; font-weight: 600; color: #6db3ff; white-space: nowrap }
+.sh-play-bar .sh-play-update:hover { background: rgba(109, 179, 255, .16); color: #8ec5ff }
 /* no backdrop-filter here: the menu nests inside the blurred bar, and glass never nests
    (a nested backdrop-filter samples the bar, not the page) - near-opaque ink instead */
 .sh-play-menu { position: absolute; top: calc(100% + 10px); left: 0; min-width: 150px; padding: 4px;

package/src/client/stage/main.tsx

@@ -31,6 +31,8 @@ window.addEventListener('unhandledrejection', (e) => post({ type: 'sh:stage-erro
 // pinch inside the stage must not zoom the parent page (same rule as the frame bridge)
 window.addEventListener('wheel', (e) => { if (e.ctrlKey || e.metaKey) e.preventDefault() }, { passive: false })
 document.addEventListener('gesturestart', (e) => e.preventDefault())
+// B0.2: a nested scroll container hitting its boundary must not chain into the shell page
+document.documentElement.style.overscrollBehavior = 'contain'
 
 interface Mounted { id: string; Frame: ComponentType; wrappers: ComponentType[] }
 

package/templates/instructions/boards.md

@@ -9,7 +9,7 @@ Minimal is enough - list the frames; the shell fills sizes from each frame's
 viewport and lays it out:
 
 ```json
-{ "version": 1, "name": "checkout-compare", "auto": false,
+{ "version": 1, "name": "checkout-compare", "order": 1, "auto": false,
   "nodes": [ { "frame": "checkout-a/cart" }, { "frame": "checkout-b/cart" } ] }
 ```
 
@@ -18,8 +18,14 @@ viewport and lays it out:
   increasing `x`).
 - The human's tidy (`t`) and device views re-layout in frame-id order, so id
   ordering is the durable arrangement; explicit coordinates are one-off setups.
-- `auto: false` boards show exactly their list. `all-scenes` is auto-managed -
-  never write it.
+- **`"order": <n>` ranks the board in the switcher, and the LOWEST-ordered board is
+  the LANDING board the canvas opens on.** Rank them so the first is a tight, fast,
+  orienting board (an overview or the primary flow) - never a giant one. Boards
+  without an `order` sort after the ranked ones, by name. Set `order` deliberately on
+  every curated board; it is the first impression.
+- `auto: false` boards show exactly their list. `all-scenes` is auto-managed (it holds
+  EVERY frame, so it is the heavy one) and always sinks to the BOTTOM of the switcher -
+  never the landing board, and never write its file.
 - Do not edit board files while the canvas is open unless asked; the shell owns
   their layout fields.
 - Use boards for comparisons: version A vs B vs C of a flow, side by side. Variant

package/templates/instructions/reference/color.md

@@ -46,8 +46,29 @@ present). Focus indicators need contrast AND a clearly visible change of appeara
 Check interactive states, text over images, and BOTH themes.
 Anything conveyed by color alone also needs text, shape, icon, or position.
 
+## Content-frame families (one palette, prose + diagrams)
+
+In content frames (`Md`, `Diagram`), color-code by MEANING using the built-in family
+names - never hand-roll hex or mermaid `classDef`. The same six families work in both,
+so a sentence and the diagram beside it read as one color language:
+
+- **Prose:** `:blue[the shipper's world]`, `:orange[the carrier market]`, `:purple[the
+  driver pool]`, `:green[...]`, `:red[...]`, `:gray[...]` inside any `Md` block.
+- **Diagram nodes:** tag a node with the family - `HQ:::blue`, `Carriers:::orange`,
+  `Drivers:::purple`. No `classDef` needed; they're injected for you.
+
+Pick ONE family per concept and hold it everywhere it appears (the intro word, the
+diagram box, the section heading). That consistency is what lets a reader link the
+picture to the prose at a glance. Reserve `gray` for the neutral/background ("the platform",
+"out of scope"); use the vivid families for the actors that matter.
+
+Node text: write labels as `Head :: gloss` - marver renders the head bold on top
+with the gloss lighter and smaller below, so a box scans as label-then-detail,
+never a run-on. Just the ` :: ` token; no backticks or `**` needed.
+
 ## Verify
 
 Every color has a stable role; attention lands on the intended action; the palette
 holds across quiet, dense, error, and empty states; both themes are composed; the
-result is recognizably THIS product, not a generic colorful treatment.
+result is recognizably THIS product, not a generic colorful treatment. In content
+frames, each concept keeps ONE family across prose and diagram.

package/templates/instructions/shape.md

@@ -92,10 +92,10 @@ export default () => (
   shows an in-frame card: fix the source, the frame heals live. Never hand-set
   colors or `%%{init}%%` themes - marver's palette is injected and source
   overrides are stripped.
-- `Img` shows `design/assets/<src>` with an optional caption; `h={n}` cover-crops
-  to a fixed rendered height (the lever for optically aligning a mixed row - see
-  "Images and mood boards" below). Blocks carry their own padding, border, and
-  surface - never hand-manage spacing around them.
+- `Img` shows `design/assets/<src>` with an optional caption, ALWAYS in full at its
+  natural aspect ratio - never cropped, never letterboxed. Size it by how many images
+  share its `Row` (fewer = bigger), not by a fixed height. Blocks carry their own
+  padding, border, and surface - never hand-manage spacing around them.
 - `intent` (`diagram` | `spec` | `moodboard` | `notes`) is the frame's PURPOSE,
   not its content mix - a frame with two diagrams and a paragraph is still the
   "diagram frame" if diagrams are why it exists. It drives the icon the human
@@ -110,27 +110,34 @@ a quadrant for prioritization, a state diagram for lifecycle logic, a sequence
 for API choreography. The syntax reference is the Mermaid docs:
 https://mermaid.js.org/intro/ - pull the one page you need, apply, return.
 
-**Color carries meaning - and the floor is never gray-on-gray.** The marver
-theme already colors every node (accent-washed fills, accent borders, both
-modes) - a default diagram looks designed with zero effort, so never hand-set
-grays "to be safe" and never re-theme (init directives are stripped anyway).
-Where the diagram has SEMANTICS, add them with `classDef` on top:
+**Two pieces of built-in sugar make a flowchart read well with zero fiddling -
+use them, don't hand-roll their raw mermaid equivalents.**
+
+*Label hierarchy (`::`).* Write a node label as `Head :: gloss` and marver
+renders the **head bold** on top with the gloss on a lighter, smaller line
+below - no backticks, no `**`, no `<br>`. A box should scan as label-then-
+detail, so lead with the actor and let the example follow:
 
 ```
 flowchart LR
-  A[Draft] --> B{Review?} -->|approved| C[Published]
-  B -->|rejected| D[Archived]
-  classDef win fill:#34C759,stroke:#248A3D,color:#fff
-  classDef stop fill:#FF383C,stroke:#D70015,color:#fff
-  class C win
-  class D stop
+  S["Shipper :: the company that needs freight moved"]:::blue
+  C["Carrier :: the trucking company that hauls it"]:::orange
+  D["Driver :: the person behind the wheel"]:::purple
+  S --> C --> D
 ```
 
-Use the system palette (the same 12 colors the series ramp uses), a few
-classes at most, and never encode meaning in color ALONE - the label or shape
-must carry it too. Check the diagram in BOTH themes (`d`): fills flip with
-the theme, hand-set classDef colors do not, so pick values that hold on both
-grounds (the system colors do).
+*Family colors (`:::name`).* Tag a node with a built-in family and it gets a
+filled, on-brand color with a legible border in both themes - no `classDef`.
+The SAME six names work in `Md` prose (`:blue[the shipper's world]`), so a
+sentence and the diagram beside it read as one color language:
+`blue orange purple green red gray`. Pick ONE family per concept and hold it
+everywhere; reserve `gray` for the neutral/background actor. Never encode
+meaning in color ALONE - the label carries it too.
+
+The marver theme already accent-washes every default node (both modes), so a
+plain flowchart looks designed with zero effort - never hand-set grays "to be
+safe" and never re-theme (init directives are stripped anyway). Check in BOTH
+themes (`d`).
 
 ## Images and mood boards
 
@@ -147,21 +154,23 @@ screenshots, official brand logos, product visuals - download into
 of described imagery every time (the full asset rules: instructions/craft.md,
 "Real assets").
 
-**Size images to be SEEN, and make rows read as one set:**
-
-- An image that renders as a stamp is a defect. The image IS the content of a
-  mood board - give the important one most of a row, let supporting shots share
-  a row, and never pack so many into one `Row` that each collapses below
-  legibility.
-- Equal component widths do NOT make unequal images look equal - aspect ratios
-  and internal density differ, so a row of same-width `Img` blocks can still
-  read ragged. Normalize a mixed row with a shared rendered height:
-  `<Img src="..." h={240} />` cover-crops every image in the row to one height,
-  which is what makes them READ aligned. Group similar aspects together when
-  cropping would destroy the shot.
-- Alignment is judged on the RENDER, not the props: after composing, look at the
-  actual frame (screenshot it if you can) and adjust until the rows sit
-  optically consistent. "The code says they're the same width" proves nothing.
+**Size images to be SEEN - by row grouping, never by cropping:**
+
+- The image IS the content: it always renders in FULL at its natural aspect ratio, so
+  a screenshot stays fully legible and is never sliced. You size it by how many images
+  share a `Row` - fewer per row = larger. Give a detailed screenshot its own row or a
+  pair; let small supporting shots share a row of three or four. An image that renders
+  as a stamp is a defect - pull it into a shorter row.
+- A row of same-aspect images (e.g. app screenshots, all the same window shape) lines
+  up as one set on its own: equal column width + equal aspect = equal height, with no
+  fixed-height prop. Only mixed aspects read ragged - split those into their own rows
+  by shape rather than forcing a height (forcing one would crop or letterbox the shot).
+- Reach for `layout="wide"` on image-heavy reference frames so each shot has room, and
+  never set a frame height - the frame auto-heights to fit everything the canvas
+  measures. Marver renders images crisp and zooms fast, so fine detail is one zoom away.
+- Judge on the RENDER, not the props: after composing, look at the actual frame
+  (screenshot it if you can) and adjust the per-row count until it reads well. "The code
+  says they're the same width" proves nothing.
 
 ## When Shape ends