@marver-design/marver 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,51 @@
 
 Notable changes to `@marver-design/marver`. Format follows [Keep a Changelog](https://keepachangelog.com); versions follow semver.
 
+## 0.6.0 - 2026-08-17
+
+Image-heavy boards, done right. A board full of high-resolution screenshots now zooms fast and stays
+crisp, images render in FULL instead of cropped, content frames size themselves to their content, and
+the switcher opens on a tight landing board instead of loading every frame at once.
+
+### Added
+
+- **Client-side image level-of-detail (LOD).** A board of 150+ high-res screenshots used to jank hard
+  on zoom - the real cost was decoded memory, not file size (a 2708x1610 PNG is ~17MB decoded, so 174 of
+  them held ~3GB of bitmaps the browser resampled every frame). Each `Img` now decodes STRAIGHT to its
+  on-screen size via `createImageBitmap` and paints on a canvas; bitmaps freeze during a pan/zoom and
+  re-pick resolution only when the gesture settles (the tldraw pattern). Result on a 174-image board:
+  ~26MB decoded at overview vs ~3GB before (~100x less), lag-free zoom, crisp detail when you stop.
+  Falls back to a plain `img` where `createImageBitmap` is unavailable.
+- **Board ranking and a fast landing board.** Boards carry an `"order"` field; the switcher ranks curated
+  boards by it and always sinks the auto `all-scenes` everything-board to the BOTTOM. A fresh open now
+  lands on the FIRST curated board - a tight, fast board and a good first impression - instead of
+  rendering every frame at once. Rank boards deliberately; the first is what people see first. `order`
+  survives the shell's autosaves.
+
+### Changed
+
+- **Reference images show in FULL.** `Img` no longer cover-crops to a fixed height (that sliced the
+  sides off every screenshot). Each image fills its column at its natural aspect ratio - never cropped,
+  never letterboxed - so same-aspect screenshots line up on their own and the frame auto-heights to fit.
+  Size an image by how many share its `Row` (fewer = bigger), not by a fixed height; `h` is accepted for
+  back-compat but no longer constrains size. A clean inset hairline (grayscale, light + dark) sits on the
+  image's own edge, overriding a screenshot's ragged or baked-in border instead of framing it twice.
+- **Content frames fit their content when you resize.** A manual WIDTH resize now keeps the HEIGHT auto:
+  the frame reflows and refits to show everything, instead of freezing at a stale height (only an explicit
+  device viewport locks it). The content-frame height cap was raised so a long reference doc renders in
+  full rather than clipping, and zoom now reaches 500% for inspecting screenshot detail.
+- **Authoring doctrine updated to match.** The scaffolded instructions now teach sizing images by row
+  grouping instead of cropping, and ranking boards with `order` (first = landing, `all-scenes` is heavy
+  and auto-last).
+
+### Fixed
+
+- **No jiggle on zoom.** An image's display aspect-ratio is pinned on first decode, so an LOD resolution
+  switch changes only the pixels, never the layout box - frames no longer drift as you zoom.
+- **Fast zoom no longer stalls frames.** The LOD re-decode is debounced past the gesture and drops queued
+  work when a new gesture starts, so oscillating zoom-in/out never stacks decode waves and times frames
+  out to a ready-timeout.
+
 ## 0.5.0 - 2026-08-15
 
 The performance & fidelity release (SPEC-M5): the canvas stops jiggling. Moving around a board no

package/dist/{build-BrCl9hJS.mjs → build-BZaPa2DS.mjs}

@@ -1,6 +1,6 @@
 import { i as ROUTE, n as NAME } from "./cli.mjs";
 import { o as loadConfig, r as scanFrames, s as detectHost } from "./manifest-C8FODq2S.mjs";
-import { n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-BtSGAm2h.mjs";
+import { n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-wMY9lNf3.mjs";
 import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, sep } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -144,7 +144,11 @@ async function buildSite(root, boardsFlag, allBoardsFlag) {
 	const manifest = scanFrames(root);
 	const allBoards = readBoards(root);
 	const rights = resolvePublish(root, allBoards, boardsFlag, allBoardsFlag);
-	const publishedNames = Object.keys(rights);
+	const boardOrder = (n) => {
+		const o = allBoards[n]?.order;
+		return typeof o === "number" && Number.isFinite(o) ? o : Infinity;
+	};
+	const publishedNames = Object.keys(rights).sort((a, b) => a === "all-scenes" ? 1 : b === "all-scenes" ? -1 : boardOrder(a) - boardOrder(b) || a.localeCompare(b));
 	const includeAll = publishedNames.includes("all-scenes");
 	const boards = {};
 	for (const n of publishedNames) if (allBoards[n]) boards[n] = allBoards[n];
@@ -164,7 +168,7 @@ async function buildSite(root, boardsFlag, allBoardsFlag) {
 		},
 		boards,
 		names: publishedNames,
-		default: publishedNames[0],
+		default: publishedNames.find((n) => n !== "all-scenes") ?? publishedNames[0],
 		rights
 	};
 	const registryFile = posix(join(clientDir, "frame-host", "registry.ts"));

package/dist/cli.mjs

@@ -46,7 +46,7 @@ cli.command("init", "Scaffold design/ in this repo").option("--mode <mode>", "st
 	});
 });
 cli.command("dev", "Start the canvas").option("--root <dir>", "Host repo root", { default: "." }).option("--port <port>", "Port (default 5199)").action(async (opts) => {
-	const { dev } = await import("./dev-DdeU-Jst.mjs");
+	const { dev } = await import("./dev-DaPQ9xA5.mjs");
 	let port;
 	if (opts.port !== void 0) {
 		const n = Number(opts.port);
@@ -56,7 +56,7 @@ cli.command("dev", "Start the canvas").option("--root <dir>", "Host repo root",
 	await dev(resolve(opts.root), port);
 });
 cli.command("build", "Static export → design/.dist (what ships comes from design/publish.json - publishing is default-closed)").option("--boards <names>", "Publish only these boards (comma-separated); overrides the publish policy").option("--all-boards", "Publish every board - the loud override for the default-closed policy").option("--root <dir>", "Host repo root", { default: "." }).action(async (opts) => {
-	const { buildSite } = await import("./build-BrCl9hJS.mjs");
+	const { buildSite } = await import("./build-BZaPa2DS.mjs");
 	try {
 		const boards = opts.boards === void 0 ? void 0 : typeof opts.boards === "string" ? opts.boards : "";
 		await buildSite(resolve(opts.root), boards, opts.allBoards === true);

package/dist/{dev-DdeU-Jst.mjs → dev-DaPQ9xA5.mjs}

@@ -1,6 +1,6 @@
 import { n as NAME, r as PKG } from "./cli.mjs";
 import { o as loadConfig, s as detectHost } from "./manifest-C8FODq2S.mjs";
-import { n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-BtSGAm2h.mjs";
+import { n as tailwind3Css, r as tailwind4Plugin, t as marverPlugin } from "./plugin-wMY9lNf3.mjs";
 import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createLogger, createServer, searchForWorkspaceRoot } from "vite";

package/dist/{plugin-BtSGAm2h.mjs → plugin-wMY9lNf3.mjs}

@@ -79,9 +79,15 @@ function apiMiddleware(root) {
 				mkdirSync(boardsDir, { recursive: true });
 				return json(res, 200, readdirSync(boardsDir).filter((f) => f.endsWith(".json") && !f.endsWith(".tmp")).map((f) => {
 					const content = readFileSync(join(boardsDir, f), "utf8");
+					let order;
+					try {
+						const o = JSON.parse(content)?.order;
+						if (typeof o === "number" && Number.isFinite(o)) order = o;
+					} catch {}
 					return {
 						name: f.replace(/\.json$/, ""),
-						sha256: hash(content)
+						sha256: hash(content),
+						order
 					};
 				}));
 			}
@@ -127,6 +133,11 @@ function apiMiddleware(root) {
 						});
 					}
 					mkdirSync(boardsDir, { recursive: true });
+					const incoming = body.board;
+					if (incoming && typeof incoming === "object" && incoming.order === void 0 && current) try {
+						const o = JSON.parse(current).order;
+						if (typeof o === "number" && Number.isFinite(o)) incoming.order = o;
+					} catch {}
 					const next2 = JSON.stringify(body.board, null, 2) + "\n";
 					atomicWrite(p, next2);
 					return json(res, 200, { sha256: hash(next2) });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marver-design/marver",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "The agent-native design canvas. A design/ folder, one command, a canvas of live frames built from your repo's real components. The tool ships no AI - your coding agent is the designer.",
   "type": "module",
   "private": false,

package/src/client/content/img-lod.ts

@@ -0,0 +1,107 @@
+// Client-side image Level-Of-Detail, running INSIDE a content frame's iframe.
+//
+// THE PROBLEM: a 2708x1610 screenshot is ~1.5MB as a PNG but ~17MB once decoded to RGBA. A board with
+// 150 of them holds ~2.6GB of decoded bitmaps, and the browser resamples every one each zoom frame =
+// jank + memory pressure. File size is a red herring; DECODED size is the killer.
+//
+// THE FIX: decode each image STRAIGHT to its on-screen size with createImageBitmap(blob,{resizeWidth}) -
+// the full-size decode is never retained - and paint it on a <canvas> via a zero-copy bitmaprenderer
+// transfer. The bitmap is FROZEN while the canvas is being pan/zoomed (the shell posts sh:camera
+// {moving:true}) and only re-picked when the gesture SETTLES (sh:camera {moving:false, scale}), so zoom
+// never triggers a decode/resample storm. Crisp at rest, cheap in motion. This mirrors how tldraw does
+// LOD (resolution by on-screen size, debounced so it never thrashes mid-zoom).
+
+/** Feature probe: createImageBitmap with resize + a canvas bitmaprenderer that can receive it. */
+export const lodSupported = (() => {
+  try {
+    if (typeof createImageBitmap !== 'function' || typeof document === 'undefined') return false
+    const ctx = document.createElement('canvas').getContext('bitmaprenderer')
+    return !!ctx && typeof ctx.transferFromImageBitmap === 'function'
+  } catch { return false }
+})()
+
+// Quantized resize widths (device px). A `want` above the top bucket decodes at NATIVE (bucket 0 = no
+// resize), reached only when a frame is zoomed in past ~2048 on-screen device px.
+const BUCKETS = [256, 640, 1280, 2048]
+const DPR = (): number => Math.min(window.devicePixelRatio || 1, 2)   // cap at 2; 3x buys nothing here
+
+// Bounded decode pool: never run more than N createImageBitmap jobs at once (peak decode memory + CPU).
+const MAX = 3
+let active = 0
+const q: Array<() => void> = []
+const pump = (): void => { while (active < MAX && q.length) q.shift()!() }
+const schedule = (job: () => Promise<void>): void => {
+  q.push(() => { active++; void job().finally(() => { active--; pump() }) })
+  pump()
+}
+
+interface Item { canvas: HTMLCanvasElement; src: string; bucket: number; token: number }
+const items = new Set<Item>()
+let scale = 0.2      // overview default until the shell primes the settled scale on frame-ready
+let moving = false
+
+function pick(devicePx: number): number {
+  for (const b of BUCKETS) if (b >= devicePx) return b
+  return 0           // native decode - only past the top bucket
+}
+
+async function decode(it: Item, bucket: number): Promise<void> {
+  const token = ++it.token
+  let bmp: ImageBitmap
+  try {
+    const blob = await (await fetch(it.src)).blob()
+    bmp = bucket
+      ? await createImageBitmap(blob, { resizeWidth: bucket, resizeQuality: 'high' })
+      : await createImageBitmap(blob)
+  } catch { return }                                       // network / decode failure: keep the last frame
+  if (it.token !== token || !it.canvas.isConnected) { bmp.close(); return }   // superseded or unmounted
+  const ctx = it.canvas.getContext('bitmaprenderer')
+  if (!ctx) { bmp.close(); return }
+  // PIN the display aspect-ratio on the first decode and never change it. Different buckets round to
+  // slightly different integer dims (256x153 = 1.673 vs 1280x761 = 1.682), so if each drove height:auto
+  // the layout box would shift a hair on every resolution switch - the doc reflows, the content frame
+  // auto-resizes, and the frame "jiggles" as you zoom (and the reflow storm helped starve frames to a
+  // ready-timeout). A fixed aspect-ratio makes the box identical across buckets: only pixels sharpen.
+  if (!it.canvas.style.aspectRatio) it.canvas.style.aspectRatio = `${bmp.width} / ${bmp.height}`
+  it.canvas.width = bmp.width; it.canvas.height = bmp.height
+  ctx.transferFromImageBitmap(bmp)                         // zero-copy; consumes + closes the bitmap
+  it.bucket = bucket
+}
+
+function refresh(it: Item): void {
+  const layoutW = it.canvas.getBoundingClientRect().width
+  if (!layoutW) return                                     // not laid out yet (or display:none)
+  const want = pick(Math.ceil(layoutW * scale * DPR()))
+  if (want === it.bucket) return
+  // hysteresis: only DOWNgrade once we're comfortably below the current level, so a jittery zoom that
+  // hovers a threshold doesn't swap back and forth (upgrades are always taken - sharper is worth it).
+  if (it.bucket > 0 && want > 0 && want < it.bucket && Math.ceil(layoutW * scale * DPR()) > it.bucket * 0.6) return
+  schedule(() => decode(it, want))
+}
+
+/** A content <canvas> registers here; returns an unregister fn. Paints a cheap first frame immediately,
+ *  then sharpens to the real zoom on the next prime/settle. */
+export function registerLodImage(canvas: HTMLCanvasElement, src: string): () => void {
+  const it: Item = { canvas, src, bucket: -1, token: 0 }
+  items.add(it)
+  schedule(() => decode(it, BUCKETS[0]))                   // low-res first paint (fast, ~1MB); prime sharpens
+  return () => { items.delete(it); it.token++ }            // token bump drops any in-flight decode
+}
+
+// The shell posts camera transitions ONCE per gesture. Freeze during motion; re-pick every image's
+// resolution to the SETTLED zoom - but debounced, and cancelling any queued work from a prior settle, so
+// a fast zoom in-out-in doesn't stack decode waves across all frames (which starved the main thread and
+// timed frames out). The re-decode only fires once the camera has truly rested.
+let settleTimer = 0
+if (typeof window !== 'undefined' && lodSupported) {
+  window.addEventListener('message', (e) => {
+    if (e.origin !== location.origin) return
+    const m = (e as MessageEvent).data as { type?: string; moving?: boolean; scale?: number } | null
+    if (!m || m.type !== 'sh:camera') return
+    if (m.moving) { moving = true; clearTimeout(settleTimer); q.length = 0; return }   // new gesture: drop pending decodes
+    moving = false
+    if (typeof m.scale === 'number' && m.scale > 0) scale = m.scale
+    clearTimeout(settleTimer)
+    settleTimer = window.setTimeout(() => { if (!moving) for (const it of items) refresh(it) }, 220)
+  })
+}

package/src/client/content/index.tsx

@@ -10,6 +10,7 @@
 import { useEffect, useMemo, useRef, useState, type ReactNode } from 'react'
 import { CONTENT_WIDTH } from '../const.ts'
 import { assetUrl, renderMarkdown, FAMILIES } from './md.ts'
+import { lodSupported, registerLodImage } from './img-lod.ts'
 
 // D3: family color classes for inline Md (`:blue[...]`), theme-aware (frames carry .dark + [data-theme])
 const FAMILY_CSS = Object.entries(FAMILIES).map(([f, c]) =>
@@ -79,6 +80,14 @@ export function Md({ children }: { children?: ReactNode }) {
 export function Img({ src, caption, alt, h }: { src: string; caption?: string; alt?: string; h?: number }) {
   const url = assetUrl(src)
   const [err, setErr] = useState(false)
+  const canvasRef = useRef<HTMLCanvasElement>(null)
+  // LOD: paint the image on a <canvas> decoded to its on-screen size (never the full 17MB bitmap), and
+  // re-pick resolution only when the canvas settles after a zoom. See img-lod.ts. Falls back to a plain
+  // <img> where createImageBitmap/bitmaprenderer isn't available (correctness over the optimization).
+  useEffect(() => {
+    if (!url || err || !lodSupported || !canvasRef.current) return
+    return registerLodImage(canvasRef.current, url)
+  }, [url, err])
   if (!url || err) {
     return (
       <div className="mv-block mv-imgerr">
@@ -88,13 +97,18 @@ export function Img({ src, caption, alt, h }: { src: string; caption?: string; a
       </div>
     )
   }
+  // A reference image ALWAYS shows in full: it fills its column at its natural aspect ratio, never
+  // cropped and never letterboxed. Equal-aspect images (e.g. a row of screenshots) line up on their own,
+  // and the frame auto-heights to fit. `h` is accepted for back-compat but no longer constrains size -
+  // capping height below natural would force the image narrower than its column (whitespace) or slice it
+  // (the old object-fit:cover). Width:100% + height:auto come from the .mv-img-el rule.
+  void h
+  const style = undefined
   return (
     <figure className="mv-block mv-img">
-      {/* h: shared rendered height for a row of mixed-aspect images - equal widths
-          alone never make unequal images READ equal; cover-crop to one height does */}
-      <img src={url} alt={alt ?? caption ?? ''} loading="lazy"
-        style={h ? { height: h, width: '100%', objectFit: 'cover' } : undefined}
-        onError={() => setErr(true)} />
+      {lodSupported
+        ? <canvas ref={canvasRef} className="mv-img-el" role="img" aria-label={alt ?? caption ?? ''} style={style} />
+        : <img className="mv-img-el" src={url} alt={alt ?? caption ?? ''} loading="lazy" style={style} onError={() => setErr(true)} />}
       {caption && <figcaption>{caption}</figcaption>}
     </figure>
   )
@@ -144,14 +158,24 @@ body { margin: 0; }
    a whisper, not a card - the content pops, the block only frames it */
 .mv-block { margin: 0; padding: ${UNIT}px; border: 1px solid var(--mv-block-line);
   border-radius: 10px; background: var(--mv-block-bg); }
-.mv-block figcaption, .mv-img figcaption { font-size: 12.5px; color: var(--mv-faint); padding-top: 8px; }
+/* an image block is NOT a card: the screenshot IS the content. Drop the surface + border so we don't
+   frame a frame; give the image itself a hairline edge and a whisper of shadow so it reads as a clean,
+   distinct object on the page (no heavy double-border around browser mockups). */
+.mv-block.mv-img { padding: 0; border: none; background: none; }
+/* INSET hairline: the line sits ON the image's own rounded edge (outline-offset:-1px), overriding a
+   screenshot's ragged or baked-in dark border instead of drawing a second frame outside it. It shares
+   the image's exact border-radius (same element), so the two never mismatch. Grayscale token = clean in
+   both light and dark. A whisper of drop shadow lifts it off the page. */
+.mv-img .mv-img-el { outline: 1px solid var(--mv-line); outline-offset: -1px;
+  box-shadow: 0 1px 4px rgba(20, 22, 28, 0.07); }
+.mv-block figcaption, .mv-img figcaption { font-size: 12.5px; color: var(--mv-faint); padding-top: 10px; }
 .mv-diagram-svg { display: flex; justify-content: center; }
 .mv-diagram-svg svg { max-width: 100%; height: auto; }
 .mv-diagram-err { display: flex; flex-direction: column; gap: 4px; font-size: 13px; color: var(--mv-muted);
   font-family: ui-monospace, "SF Mono", Menlo, monospace; }
 .mv-diagram-err b { color: #E0402F; font-family: inherit; }
 .mv-diagram-err .dim, .mv-imgerr .dim { color: var(--mv-faint); font-size: 12px; }
-.mv-img img { display: block; max-width: 100%; border-radius: 6px; }
+.mv-img .mv-img-el { display: block; width: 100%; height: auto; max-width: 100%; border-radius: 6px; }
 .mv-imgerr { display: flex; flex-direction: column; gap: 4px; font-size: 13px; color: var(--mv-muted); }
 .mv-imgerr b { color: #E0402F; }
 

package/src/client/shell/App.tsx

@@ -403,12 +403,21 @@ export function App() {
   useEffect(() => {
     if (booted) return
     booted = true
-    if (bootHash.board && bootHash.board !== useStore.getState().board)
-      useStore.setState({ board: bootHash.board, boardAuto: bootHash.board === 'all-scenes' })
-    boot().then((ok) => {
+    const start = async () => {
+      if (bootHash.board) {
+        if (bootHash.board !== useStore.getState().board)   // a deep link wins
+          useStore.setState({ board: bootHash.board, boardAuto: bootHash.board === 'all-scenes' })
+      } else if (!PUBLISHED) {
+        // fresh open, no deep link: LAND on the first curated board (a tight, fast board = a good first
+        // impression) instead of the auto all-scenes everything-board, which renders every frame at once.
+        const first = (await fetchBoardNames().catch(() => [] as string[])).find((n) => n !== 'all-scenes')
+        if (first && first !== useStore.getState().board) useStore.setState({ board: first, boardAuto: false })
+      }
+      const ok = await boot()
       urlReady.current = true
-      if (ok && bootHash.play) enterPlay(bootHash.play)   // #/p/<board> alone = board start
-    })
+      if (ok && bootHash.play) enterPlay(bootHash.play)     // #/p/<board> alone = board start
+    }
+    void start()
   }, [])
 
   // the URL is a projection of state: design views replace in place; entering play and

package/src/client/shell/canvas/Canvas.tsx

@@ -4,6 +4,7 @@ import { CONFIG, useStore } from '../store.ts'
 import { bootHash } from '../hash.ts'
 import { startPerf } from '../perf.ts'
 import { FrameNode, HEADER } from './FrameNode.tsx'
+import { startCameraBroadcast, setCameraScale } from './camera-broadcast.ts'
 
 /**
  * The world. rzpp owns pan/zoom; nodes are absolutely positioned children of #sh-world.
@@ -142,7 +143,7 @@ export function Canvas() {
   const ref = useRef<ReactZoomPanPinchContentRef>(null)
   const scaleTimer = useRef(0)
 
-  useEffect(() => { startPerf() }, [])   // B0.4: frame-time sampler (window.__mvPerf)
+  useEffect(() => { startPerf(); startCameraBroadcast() }, [])   // B0.4: frame-time sampler + image-LOD camera signal
 
   useEffect(() => {
     const wrap = () => document.querySelector('.sh-canvas') as HTMLElement | null
@@ -331,7 +332,7 @@ export function Canvas() {
     <TransformWrapper
       ref={ref}
       minScale={0.05}
-      maxScale={2}
+      maxScale={5}
       limitToBounds={false}
       doubleClick={{ disabled: true }}
       // wheelDisabled is load-bearing: rzpp's onWheelPanning is a no-op without it, and
@@ -353,6 +354,7 @@ export function Canvas() {
       // re-render happens per tick during a pan/zoom.
       onTransformed={(r) => {
         paintGrid(r.state.positionX, r.state.positionY, r.state.scale)
+        setCameraScale(r.state.scale)   // keep the LOD's settle-scale current (cheap number write, no React)
         clearTimeout(scaleTimer.current)
         scaleTimer.current = window.setTimeout(() => setScale(r.state.scale), 120)
       }}

package/src/client/shell/canvas/FrameNode.tsx

@@ -4,6 +4,7 @@ import { CopyIcon, IntentGlyph, ReloadIcon, XIcon } from '../icons.tsx'
 import { CommentLayer } from '../Comments.tsx'
 import { useComments } from '../comments-store.ts'
 import { registerFrame, unregisterFrame } from './frame-registry.ts'
+import { primeCameraFor } from './camera-broadcast.ts'
 import { registerLeanFrame, dropSnapshot, scheduleCapture, invalidateLean } from './snapshots.ts'
 
 export const HEADER = 28
@@ -126,6 +127,11 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
     if (node.status === 'ready' || !interact)
       iframeRef.current?.contentWindow?.postMessage({ type: 'sh:interactive', on: interact }, location.origin)
   }, [interact, node.status])
+  // image-LOD: once the frame is ready its content listener is live, so send the settled zoom - a static
+  // board that never gets a gesture then still sharpens its images from the cheap low-res first paint.
+  useEffect(() => {
+    if (node.status === 'ready') primeCameraFor(iframeRef.current?.contentWindow)
+  }, [node.status])
 
   // a frame whose FILE actually changed (e.g. tsx -> html swap, same id) must renavigate
   useEffect(() => {

package/src/client/shell/canvas/camera-broadcast.ts

@@ -0,0 +1,44 @@
+// Tells every content frame when the canvas camera starts and stops moving, so each frame's image-LOD
+// (content/img-lod.ts) can freeze its bitmaps during motion and sharpen to the settled zoom afterwards.
+//
+// Fires ONCE per gesture, never per animation frame - it watches the single #sh-world.sh-camera class
+// that EVERY camera path (rzpp zoom/pan, wheel, pinch, programmatic setTransform) toggles, so one hook
+// covers them all. Posting a message to 150 frames every tick would be its own jank; two posts per
+// gesture (start, settle) is free.
+
+let lastScale = 1
+/** Fed live from onTransformed so `settle` always broadcasts the final zoom. Cheap (a number write). */
+export function setCameraScale(s: number): void { if (s > 0) lastScale = s }
+
+function frameWindows(): Window[] {
+  const out: Window[] = []
+  for (const f of document.querySelectorAll<HTMLIFrameElement>('#sh-world iframe'))
+    if (f.contentWindow) out.push(f.contentWindow)
+  return out
+}
+
+function broadcast(moving: boolean): void {
+  const msg = moving ? { type: 'sh:camera', moving: true } : { type: 'sh:camera', moving: false, scale: lastScale }
+  for (const w of frameWindows()) { try { w.postMessage(msg, location.origin) } catch { /* cross-doc timing */ } }
+}
+
+let started = false
+export function startCameraBroadcast(): void {
+  if (started) return
+  const world = document.getElementById('sh-world'); if (!world) return
+  started = true
+  let moving = false
+  new MutationObserver(() => {
+    const now = world.classList.contains('sh-camera')
+    if (now === moving) return
+    moving = now
+    broadcast(now)   // +sh-camera -> freeze; -sh-camera -> sharpen to the settled scale
+  }).observe(world, { attributes: true, attributeFilter: ['class'] })
+}
+
+/** Prime ONE freshly-ready frame with the current settled scale, so a static board that is never zoomed
+ *  still sharpens from its cheap low-res first paint to the right resolution. */
+export function primeCameraFor(win: Window | null | undefined): void {
+  if (!win) return
+  try { win.postMessage({ type: 'sh:camera', moving: false, scale: lastScale }, location.origin) } catch { /* timing */ }
+}

package/src/client/shell/store.ts

@@ -40,12 +40,17 @@ export const CONFIG: { viewports: Record<string, { width: number; height: number
 export { cap, humanize } from './labels.ts'
 import { cap, humanize } from './labels.ts'
 
-/** Board names for switchers: all-scenes first, the rest sorted. Throws on transport
- *  failure - callers keep their last known list. */
+/** Board names for switchers: the agent's curated boards FIRST (ranked by each board's `order`, then
+ *  name), and the auto `all-scenes` everything-board LAST - it is the expensive one, never the landing.
+ *  Throws on transport failure - callers keep their last known list. */
 export async function fetchBoardNames(): Promise<string[]> {
   if (DATA) return DATA.names
-  const list: { name: string }[] = await (await fetch(`${ROUTE}/api/boards`)).json()
-  return ['all-scenes', ...list.map((b) => b.name).filter((n) => n !== 'all-scenes').sort()]
+  const list: { name: string; order?: number }[] = await (await fetch(`${ROUTE}/api/boards`)).json()
+  const curated = list
+    .filter((b) => b.name !== 'all-scenes')
+    .sort((a, b) => (a.order ?? Infinity) - (b.order ?? Infinity) || a.name.localeCompare(b.name))
+    .map((b) => b.name)
+  return [...curated, 'all-scenes']
 }
 /** Display name for a board: the reserved 'all-scenes' key reads as "All scenes". */
 export const boardLabel = (n: string) => humanize(n)
@@ -600,27 +605,38 @@ export const useStore = create<State>((set, get) => {
     measureNode(key, frameId, ownWidth, measuredWidth, height) {
       const s = get()
       const node = s.nodes.find((n) => n.key === key)
-      if (!node || node.sizeMode !== 'auto') return       // manual/device always win
+      // Only an explicit DEVICE viewport locks a content frame's height. 'auto' and 'manual' both
+      // auto-fit height: a content frame must always grow/shrink to show ALL its content, even after
+      // the human drags its WIDTH (SPEC-026 r4). 'manual' just means the human owns the WIDTH; the
+      // HEIGHT is still measured, so resizing width reflows and refits height (no clipped/empty frame).
+      if (!node || node.sizeMode === 'device') return
       if (node.frame !== frameId) return                  // generation guard: a reused node key
                                                           // across a board switch never mis-attributes
       const f = s.manifest?.frames.find((x) => x.id === node.frame)
       if (!f?.contentWidth) return                        // not a content frame - spoof-proofing
       if (![ownWidth, measuredWidth, height].every((v) => Number.isFinite(v) && v > 0)) return
-      const maxH = Math.round(2.5 * Math.max(844, ...Object.values(CONFIG.viewports).map((v) => v.height)))
-      // declared meta.viewport WINS over the Doc layout width - the existing precedence
-      const vpw = CONFIG.viewports[f.viewport ?? '']?.width
-      const W = vpw ?? Math.min(1600, Math.max(320, Math.round(ownWidth)))
+      // Generous cap: a reference doc with many screenshots is legitimately very tall and must fit in
+      // FULL (this was 2.5x a viewport ~= 2700px, which clipped image-heavy docs). Still bounded so a
+      // broken measurement can't mint an infinite frame.
+      const maxH = 40000
       const H = Math.min(maxH, Math.max(80, Math.round(height)))
       const curW = Math.round(node.w)
       measuredHeights.set(`${node.frame}@${Math.round(measuredWidth)}`, H)
-      if (Math.round(measuredWidth) !== curW) return      // height not true at the applied width
-      if (W !== curW) {
-        // Doc layout changed (document<->wide): adopt the new own width first; the
-        // iframe resizes, remeasures, and the height commits on the next message
-        set((st) => ({ nodes: st.nodes.map((n) => (n.key === key ? { ...n, w: W } : n)) }))
-        scheduleReflow()
-        return
+      // AUTO owns the width too - adopt the Doc's declared/own width. MANUAL keeps the human's width
+      // and only fits the height.
+      if (node.sizeMode !== 'manual') {
+        // declared meta.viewport WINS over the Doc layout width - the existing precedence
+        const vpw = CONFIG.viewports[f.viewport ?? '']?.width
+        const W = vpw ?? Math.min(1600, Math.max(320, Math.round(ownWidth)))
+        if (W !== curW) {
+          // Doc layout changed (document<->wide): adopt the new own width first; the
+          // iframe resizes, remeasures, and the height commits on the next message
+          set((st) => ({ nodes: st.nodes.map((n) => (n.key === key ? { ...n, w: W } : n)) }))
+          scheduleReflow()
+          return
+        }
       }
+      if (Math.round(measuredWidth) !== curW) return      // height only true at the width it was measured at
       if (Math.round(node.h) === H) return
       set((st) => ({ nodes: st.nodes.map((n) => (n.key === key ? { ...n, h: H } : n)) }))
       scheduleReflow()

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/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
@@ -154,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