@marver-design/marver 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -2,6 +2,100 @@
 
 Notable changes to `@marver-design/marver`. Format follows [Keep a Changelog](https://keepachangelog.com); versions follow semver.
 
+## 0.7.0 - 2026-08-17
+
+Prototype mode becomes a first-class review surface. The prototype (Play) now carries the same toolbar
+as the canvas, laser and comments work INSIDE it, and every comment wears the colour of the element it
+points at - the groundwork for tagging a coding agent from anywhere you review.
+
+### Added
+
+- **The prototype is a review surface, not just a viewer.** Play's top-right toolbar is now the SAME
+  controls as the canvas - device switch, theme, laser, comment - built from one shared set of
+  components so the two can never drift. Laser and comment work inside the running prototype: the stage
+  runs the same element inspector the canvas frames do, so you can point at, highlight, and comment on
+  the live app while you walk a flow. The bottom-left navigator (restart / prev / i-of-N / next) stays.
+- **Hide UI (H).** One binary toggle hides all chrome for a clean point-and-shoot frame, shared by the
+  canvas and the prototype. No auto-fade, no hover magic; a page refresh always brings the chrome back
+  (the safety net for a forgotten shortcut). It replaces the prototype's old three-state auto-hiding bar.
+- **Comments wear their element's colour.** Comment mode reuses laser's per-element depth hue: the
+  element you hover, the composer, the pin, the thread card, and the active-element highlight all take
+  that specific element's colour - a comment on a blue heading reads blue, on a green button green. The
+  avatar keeps the commenter's own colour; filled buttons use a hue-aware shade so the glyph stays legible.
+- **The commented element lights up.** Picking an element locks a persistent outline on it (the highlight
+  stops chasing the mouse while you compose), and opening a thread re-lights its anchored element - so
+  everyone sees exactly which element a comment is about. It clears on close.
+
+### Changed
+
+- **Prototype chrome is discreet and reliable.** The prototype's floating toolbar wears the same quiet
+  dark skin as the bottom-left navigator, so it recedes into the stage instead of reading as a bright
+  slab; and it no longer auto-hides or sticks under the cursor - it behaves exactly like the canvas pill
+  (explicit collapse, Hide-UI, no surprises).
+- **Prototype is an action, not a menu item.** The Prototype-view button moved into the canvas pill's
+  action group (beside comment, laser, tidy), leaving the far right purely for UI management (Hide UI,
+  collapse).
+- **The element label reads clearer.** The laser/comment element tooltip now sits below-left of the
+  cursor with a gap - clear of the element you are pointing at - and slides in from the edge instead of
+  being clipped.
+- **Escape exits laser mode**, matching comment mode.
+
+### Fixed
+
+- **Canvas comment highlight is now reliable.** A frame hosting an open thread or a draft shows its LIVE
+  app rather than the frozen lean snapshot, so the active-element highlight appears, updates, and clears
+  in real time - it used to be intermittently missing, or frozen after close, depending on snapshot
+  timing. A clean snapshot rebuilds once the thread closes.
+- **Highlights only show while a thread is active.** Closing a thread or hiding pins (Shift+C) clears the
+  element highlight; a remotely-resolved thread no longer strands one.
+- **Prototype comment overlay positions faster** after a walk and never renders behind the frame or off
+  screen. Element-hue values, message origins, and stage-swap timing are all validated.
+
+## 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.7.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; }