@marver-design/marver 0.2.4 → 0.3.1

package/src/client/content/index.tsx

@@ -0,0 +1,196 @@
+/**
+ * Content-frame block primitives (SPEC-026): Doc, Row, Col, Space, Md, Diagram, Img.
+ * One vocabulary at two scales: boards arrange frames in rows/columns with space
+ * units; these primitives do the same for blocks INSIDE a frame - as CSS flex,
+ * deliberately NOT the SPEC-024 lane grammar (shared vocabulary, not semantics).
+ *
+ * Doc owns the measurement protocol: it reports its content height so the shell
+ * can give the frame a natural size (the shell alone owns node dimensions).
+ */
+import { useEffect, useMemo, useRef, useState, type ReactNode } from 'react'
+import { CONTENT_WIDTH } from '../const.ts'
+import { assetUrl, renderMarkdown } from './md.ts'
+
+export { Diagram } from './diagram.tsx'
+
+const UNIT = 16   // one gap unit, px - plain adjacency on boards is one gutter; same feel here
+
+/* ---------------------------------- Doc ---------------------------------- */
+
+export function Doc({ layout = 'document', children }: { layout?: 'document' | 'wide'; children?: ReactNode }) {
+  const ref = useRef<HTMLDivElement>(null)
+  useEffect(() => {
+    ensureStyles()
+    const el = ref.current
+    if (!el || window.parent === window) return
+    let t: ReturnType<typeof setTimeout> | undefined
+    const params = new URLSearchParams(location.search)
+    const post = () => {
+      window.parent.postMessage({
+        type: 'sh:measure',
+        // identity guards: board files may reuse node keys (frame id must match), and
+        // a WindowProxy survives navigation (gen = THIS document's URL rev - the shell
+        // drops echoes that don't match the iframe's current src)
+        frame: params.get('id') ?? '',
+        gen: params.get('r') ?? '',
+        ownWidth: CONTENT_WIDTH[layout] ?? CONTENT_WIDTH.document,
+        measuredWidth: window.innerWidth,          // the width this height is TRUE at (r3 #1)
+        height: Math.ceil(el.getBoundingClientRect().height),
+      }, '*')
+    }
+    // debounced ~300ms after the last content change; the shell guards staleness
+    // on its side (event.source must map to a mounted iframe; reflow is board-scoped)
+    const ro = new ResizeObserver(() => { clearTimeout(t); t = setTimeout(post, 300) })
+    ro.observe(el)
+    post()
+    return () => { ro.disconnect(); clearTimeout(t) }
+  }, [layout])
+  return <div ref={ref} className={`mv-doc mv-doc-${layout}`}>{children}</div>
+}
+
+/* ----------------------------- layout blocks ------------------------------ */
+
+export function Row({ space = 1, children }: { space?: number; children?: ReactNode }) {
+  return <div className="mv-row" style={{ gap: space * UNIT }}>{children}</div>
+}
+
+export function Col({ space = 1, children }: { space?: number; children?: ReactNode }) {
+  return <div className="mv-col" style={{ gap: space * UNIT }}>{children}</div>
+}
+
+export function Space({ n = 1 }: { n?: number }) {
+  return <div aria-hidden className="mv-space" style={{ flex: `0 0 ${n * UNIT}px`, minWidth: n * UNIT, minHeight: n * UNIT }} />
+}
+
+/* ---------------------------------- Md ------------------------------------ */
+
+export function Md({ children }: { children?: ReactNode }) {
+  const src = typeof children === 'string' ? children : Array.isArray(children) ? children.join('') : String(children ?? '')
+  const html = useMemo(() => renderMarkdown(src), [src])
+  return <div className="mv-md" dangerouslySetInnerHTML={{ __html: html }} />
+}
+
+/* ---------------------------------- Img ----------------------------------- */
+
+export function Img({ src, caption, alt, h }: { src: string; caption?: string; alt?: string; h?: number }) {
+  const url = assetUrl(src)
+  const [err, setErr] = useState(false)
+  if (!url || err) {
+    return (
+      <div className="mv-block mv-imgerr">
+        <b>image unavailable</b>
+        <span>{src}</span>
+        {!url && <span className="dim">must be a relative path inside design/assets/</span>}
+      </div>
+    )
+  }
+  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)} />
+      {caption && <figcaption>{caption}</figcaption>}
+    </figure>
+  )
+}
+
+/* --------------------------------- styles --------------------------------- */
+
+/** Injected once per document. Content frames paint their own surface and read
+ *  the frame theme from the bridge's signals (html.dark / [data-theme]). */
+let stylesIn = false
+function ensureStyles() {
+  if (stylesIn || document.getElementById('mv-content-css')) { stylesIn = true; return }
+  stylesIn = true
+  const el = document.createElement('style')
+  el.id = 'mv-content-css'
+  el.textContent = CSS
+  document.head.appendChild(el)
+}
+
+const CSS = `
+/* only content frames inject this stylesheet, and their document is the Doc -
+   zeroing the body margin makes the measured height the truth (a min-height
+   would echo the frame's own height back and the measurement could never shrink) */
+body { margin: 0; }
+.mv-doc {
+  --mv-bg: #FFFFFF; --mv-surface: #F7F7F9; --mv-line: #D1D1D6; --mv-line-soft: #E5E5EA;
+  --mv-text: #1C1C1E; --mv-muted: #636366; --mv-faint: #8E8E93; --mv-accent: #0088FF;
+  --mv-block-bg: rgba(20, 22, 28, 0.02); --mv-block-line: rgba(20, 22, 28, 0.07);
+  box-sizing: border-box; width: 100%;
+  background: var(--mv-bg); color: var(--mv-text);
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+  font-size: 15px; line-height: 1.6; -webkit-font-smoothing: antialiased;
+  padding: 40px; display: flex; flex-direction: column; gap: ${UNIT}px;
+}
+.dark .mv-doc, [data-theme="dark"] .mv-doc {
+  --mv-bg: #1C1C1E; --mv-surface: #26262A; --mv-line: #3A3A3C; --mv-line-soft: #2C2C2E;
+  --mv-text: #F2F2F7; --mv-muted: #AEAEB2; --mv-faint: #8E8E93; --mv-accent: #0091FF;
+  --mv-block-bg: rgba(255, 255, 255, 0.025); --mv-block-line: rgba(255, 255, 255, 0.07);
+}
+.mv-doc * { box-sizing: border-box; }
+.mv-row { display: flex; flex-wrap: wrap; align-items: flex-start; }
+.mv-row > * { flex: 1 1 260px; min-width: 0; }
+.mv-row > .mv-space { flex: none; }
+.mv-col { display: flex; flex-direction: column; min-width: 0; }
+
+/* the rubber: diagram + image blocks own their breathing room. The surface is
+   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; }
+.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-imgerr { display: flex; flex-direction: column; gap: 4px; font-size: 13px; color: var(--mv-muted); }
+.mv-imgerr b { color: #E0402F; }
+
+/* markdown typography - the HIG scale, Notion's calm. Body 16 on generous
+   leading; headings tighten tracking as they grow (SF behavior); sections
+   breathe ABOVE far more than below, so structure reads at a glance. Every
+   list-style is re-asserted: host Tailwind preflight strips markers. */
+.mv-md { max-width: 72ch; min-width: 0; font-size: 16px; line-height: 1.65; }
+.mv-md > :first-child { margin-top: 0; }
+.mv-md > :last-child { margin-bottom: 0; }
+.mv-md h1 { font-size: 30px; line-height: 1.16; letter-spacing: -0.021em; font-weight: 700; margin: 44px 0 14px; }
+.mv-md h2 { font-size: 22px; line-height: 1.22; letter-spacing: -0.017em; font-weight: 700; margin: 40px 0 12px; }
+.mv-md h3 { font-size: 18px; line-height: 1.3; letter-spacing: -0.01em; font-weight: 650; margin: 30px 0 8px; }
+.mv-md h4, .mv-md h5, .mv-md h6 { font-size: 15px; font-weight: 650; margin: 24px 0 6px; }
+.mv-md p { margin: 0 0 14px; }
+.mv-md ul, .mv-md ol { margin: 0 0 14px; padding-left: 26px; }
+.mv-md ul { list-style: disc; }
+.mv-md ul ul { list-style: circle; }
+.mv-md ol { list-style: decimal; }
+.mv-md li { margin-bottom: 5px; }
+.mv-md li::marker { color: var(--mv-faint); }
+.mv-md li:has(> input[type="checkbox"]) { list-style: none; margin-left: -26px; }
+.mv-md a { color: var(--mv-accent); text-decoration: none; }
+.mv-md a[data-goto] { border-bottom: 1px dashed var(--mv-accent); cursor: pointer; }
+.mv-md blockquote { margin: 4px 0 16px; padding: 2px 0 2px 18px; border-left: 3px solid var(--mv-text);
+  color: var(--mv-text); }
+.mv-md blockquote p:last-child { margin-bottom: 0; }
+.mv-md code { font-family: ui-monospace, "SF Mono", Menlo, Consolas, monospace; font-size: 0.85em;
+  background: var(--mv-surface); border: 1px solid var(--mv-line-soft); border-radius: 5px; padding: 1.5px 6px; }
+.mv-md pre { background: var(--mv-surface); border: 1px solid var(--mv-line-soft); border-radius: 10px;
+  padding: 16px 18px; overflow-x: auto; margin: 0 0 16px; }
+.mv-md pre code { background: none; border: 0; padding: 0; font-size: 13px; line-height: 1.65; }
+/* tables are CONTAINED (Notion): outer border + radius, header surface, row hairlines */
+.mv-md table { border-collapse: separate; border-spacing: 0; width: 100%; margin: 4px 0 18px;
+  font-size: 14.5px; border: 1px solid var(--mv-line-soft); border-radius: 10px; overflow: hidden; }
+.mv-md th, .mv-md td { text-align: left; padding: 9px 14px; }
+.mv-md th { font-size: 11.5px; text-transform: uppercase; letter-spacing: 0.07em; font-weight: 600;
+  color: var(--mv-faint); background: var(--mv-surface); border-bottom: 1px solid var(--mv-line-soft); }
+.mv-md td { border-bottom: 1px solid var(--mv-line-soft); }
+.mv-md tr:last-child td { border-bottom: 0; }
+.mv-md img { max-width: 100%; border-radius: 8px; }
+.mv-md hr { border: 0; border-top: 1px solid var(--mv-line-soft); margin: 32px 0; }
+.mv-md input[type="checkbox"] { appearance: auto; accent-color: var(--mv-accent); width: 15px; height: 15px;
+  margin: 0 8px 0 0; vertical-align: -2px; }
+.mv-md-noimg { font-size: 13px; color: var(--mv-faint); font-style: italic; }
+`

package/src/client/content/md.ts

@@ -0,0 +1,50 @@
+/**
+ * Markdown rendering for the Md block (SPEC-026 security section).
+ * Raw HTML is inert (escaped, never parsed). Links and images have SEPARATE
+ * policies: links may be goto:/http(s)/mailto (external ones open a new tab,
+ * never navigate the iframe); images are local-only - design/assets/ paths.
+ */
+import { Marked } from 'marked'
+
+const escapeHtml = (s: string) => s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`)
+
+/** Relative design/assets/ path -> served URL; null for anything else (fail closed).
+ *  Decodes BEFORE validating (a %2e%2e must not sneak past the ".." check) and
+ *  re-encodes per segment, so the validated path is the path the browser requests. */
+export function assetUrl(src: string): string | null {
+  let p = String(src ?? '').trim()
+  try { p = decodeURIComponent(p) } catch { return null }
+  if (p.includes('%')) return null   // still encoded after one decode - refuse double-encoding games
+  if (!p || p.includes('://') || p.includes(':') || p.startsWith('/') || p.startsWith('\\') || p.includes('\\')) return null
+  if (p.split('/').some((seg) => seg === '..' || seg === '.' || seg === '')) return null
+  return `/design/assets/${p.split('/').map(encodeURIComponent).join('/')}`
+}
+
+const marked = new Marked({
+  gfm: true,
+  renderer: {
+    // raw HTML (block or inline) renders as its literal text - inert by construction
+    html(token: any) { return escapeHtml(String(token.text ?? '')) },
+    link(token: any) {
+      const href = String(token.href ?? '')
+      const inner = this.parser.parseInline(token.tokens ?? [])
+      if (href.startsWith('goto:')) {
+        const target = href.slice('goto:'.length)
+        return `<a href="#" data-goto="${escapeHtml(target)}">${inner}</a>`
+      }
+      if (/^https?:\/\//i.test(href) || /^mailto:/i.test(href))
+        return `<a href="${escapeHtml(href)}" target="_blank" rel="noopener noreferrer">${inner}</a>`
+      return inner                       // disallowed protocol: the text, no link
+    },
+    image(token: any) {
+      const url = assetUrl(String(token.href ?? ''))
+      const alt = escapeHtml(String(token.text ?? ''))
+      if (!url) return `<span class="mv-md-noimg">[image unavailable: ${alt || 'external images are not allowed'}]</span>`
+      return `<img src="${escapeHtml(url)}" alt="${alt}" loading="lazy" />`
+    },
+  },
+})
+
+export function renderMarkdown(src: string): string {
+  return marked.parse(src, { async: false }) as string
+}

package/src/client/content/palette.ts

@@ -0,0 +1,93 @@
+/**
+ * The marver diagram identity (SPEC-026): the full Apple system palette (HIG),
+ * every value the HIG's own light/dark pair - never inverted. Structure comes
+ * from the systemGray ramp, emphasis from blue+purple, series diversity from
+ * the 12-color set.
+ */
+export const FONT_STACK = `-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif`
+
+/** systemGray 1..6 (index 0 = gray1). */
+const GRAY_LIGHT = ['#8E8E93', '#AEAEB2', '#C7C7CC', '#D1D1D6', '#E5E5EA', '#F2F2F7']
+const GRAY_DARK = ['#8E8E93', '#636366', '#48484A', '#3A3A3C', '#2C2C2E', '#1C1C1E']
+
+/** red orange yellow green mint teal cyan blue indigo purple pink brown. */
+const SERIES_LIGHT = ['#FF383C', '#FF8D28', '#FFCC00', '#34C759', '#00C8B3', '#00C3D0', '#00C0E8', '#0088FF', '#6155F5', '#CB30E0', '#FF2D55', '#AC7F5E']
+const SERIES_DARK = ['#FF4245', '#FF9230', '#FFD600', '#30D158', '#00DAC3', '#00D2E0', '#3CD3FE', '#0091FF', '#6D7CFF', '#DB34F2', '#FF375F', '#B78A66']
+
+export const ACCENT = { blue: { light: '#0088FF', dark: '#0091FF' }, purple: { light: '#CB30E0', dark: '#DB34F2' } }
+
+/** Rides INSIDE the SVG via mermaid's themeCSS option - labels must be MEASURED
+ *  with this treatment (host CSS landing after render would change text metrics
+ *  without mermaid re-laying-out the boxes). Same voice as the Md typography:
+ *  medium-weight labels, SF-style tightening, breathing room on wrapped lines. */
+export const THEME_CSS = `
+  .nodeLabel, .cluster-label, .label, text { letter-spacing: -0.01em; }
+  .nodeLabel, .cluster-label { font-weight: 600; line-height: 1.4; }
+  .nodeLabel p, .edgeLabel p, .label p { margin: 0; }
+  .edgeLabel, .edgeLabel .label { font-weight: 500; }
+`
+
+/** Mermaid themeVariables for one mode. Base theme + these = the marver look. */
+export function themeVars(dark: boolean): Record<string, string> {
+  const g = dark ? GRAY_DARK : GRAY_LIGHT
+  const s = dark ? SERIES_DARK : SERIES_LIGHT
+  const text = dark ? '#F2F2F7' : '#1C1C1E'
+  const surface = dark ? '#1C1C1E' : '#FFFFFF'
+  const blue = dark ? ACCENT.blue.dark : ACCENT.blue.light
+  const purple = dark ? ACCENT.purple.dark : ACCENT.purple.light
+  // Nodes are ACCENTED by default - a plain flowchart only ever touches
+  // primaryColor, so a gray primary meant every default diagram rendered
+  // gray-on-gray (Nic's dogfood catch, 2026-08-13). Structure (lines, clusters,
+  // labels) stays grayscale; the shapes carry the marver blue.
+  const blueWash = dark ? '#123A5C' : '#E4F0FF'
+  const purpleWash = dark ? '#3A1440' : '#F8E4FC'
+  const tealWash = dark ? '#0C3B40' : '#DFF7F9'
+  const vars: Record<string, string> = {
+    fontFamily: FONT_STACK,
+    fontSize: '15px',
+    background: surface,
+    mainBkg: blueWash,                // the default node: blue-washed, blue-edged
+    primaryColor: blueWash,
+    primaryTextColor: text,
+    primaryBorderColor: blue,
+    nodeBorder: blue,
+    lineColor: g[0],                  // gray1 - edges read as drawing strokes
+    textColor: text,
+    secondaryColor: purpleWash,
+    secondaryTextColor: text,
+    secondaryBorderColor: purple,
+    tertiaryColor: tealWash,
+    tertiaryTextColor: text,
+    tertiaryBorderColor: dark ? '#00D2E0' : '#00C3D0',
+    clusterBkg: dark ? '#232326' : '#FAFAFC',
+    clusterBorder: g[3],
+    edgeLabelBackground: surface,
+    titleColor: text,
+    actorBkg: blueWash,
+    actorBorder: blue,
+    actorTextColor: text,
+    signalColor: g[0],
+    signalTextColor: text,
+    labelBoxBkgColor: g[4],
+    labelTextColor: text,
+    noteBkgColor: dark ? '#2C2A20' : '#FFF9E0',
+    noteTextColor: text,
+    noteBorderColor: g[2],
+    activationBkgColor: dark ? '#123A5C' : '#E0F0FF',
+    activationBorderColor: blue,
+    errorBkgColor: dark ? '#4A1D1E' : '#FFE5E5',
+    errorTextColor: text,
+  }
+  // categorical series: pie slices, git branches, generic color scales
+  s.forEach((c, i) => {
+    vars[`pie${i + 1}`] = c
+    vars[`cScale${i}`] = c
+    if (i < 8) vars[`git${i}`] = c
+  })
+  vars.pieTitleTextColor = text
+  vars.pieSectionTextColor = dark ? '#1C1C1E' : '#FFFFFF'
+  vars.pieLegendTextColor = text
+  vars.pieStrokeColor = surface
+  vars.pieOuterStrokeColor = g[2]
+  return vars
+}

package/src/client/shell/App.tsx

@@ -1,12 +1,12 @@
 import { Component, useEffect, useRef, useState, type ReactNode } from 'react'
 import { createPortal } from 'react-dom'
-import { useStore, CONFIG, PUBLISHED, boardLabel, cap, fetchBoardNames } from './store.ts'
+import { useStore, CONFIG, PUBLISHED, boardLabel, cap, fetchBoardNames, type FrameEntry } from './store.ts'
 import { Tip } from './Tip.tsx'
 import { PKG, ROUTE } from '../const.ts'
 import { animateLayout, Canvas, canvasCtl } from './canvas/Canvas.tsx'
 import { enterPlay, playCtl, PlayOverlay } from './Play.tsx'
 import { bootHash, parseHash, writeHash } from './hash.ts'
-import { CardsIcon, CardsThreeIcon, CaretIcon, CheckIcon, DevicesIcon, GridIcon, MoonIcon, PanelFilledIcon, PanelHollowIcon, ParallelogramDuoIcon, PlayIcon, PlusIcon, SignpostIcon, SunIcon, VariantsIcon, XIcon, deviceIcon } from './icons.tsx'
+import { CardsIcon, CardsThreeIcon, CaretIcon, CheckIcon, DevicesIcon, FrameRectIcon, GridIcon, IntentGlyph, MoonIcon, PanelFilledIcon, PanelHollowIcon, ParallelogramDuoIcon, PlayIcon, PlusIcon, SignpostIcon, SunIcon, VariantsIcon, XIcon, deviceIcon } from './icons.tsx'
 
 let booted = false                             // survives Fast Refresh; see the boot effect
 
@@ -529,6 +529,16 @@ export function App() {
         s.setStatus(nodeKey, 'error', String(data.message ?? 'unknown error'))
       } else if (data.type === 'sh:exit-interact') {
         if (s.interact === nodeKey) setInteract(null)
+      } else if (data.type === 'sh:measure') {
+        // SPEC-026 generation guard: the sender echoes ITS document's URL rev; a
+        // WindowProxy survives navigation, so a stale pre-navigation message would
+        // otherwise route as if it came from the current document. Compare against
+        // the iframe's CURRENT src - mismatched generations are dropped.
+        const gen = el.src.match(/[?&]r=(\d+)/)?.[1] ?? ''
+        if (String(data.gen ?? '') !== gen) return
+        // measureNode does the rest of the admission (content frames only,
+        // frame-id match, finite positive, clamped)
+        s.measureNode(nodeKey, String(data.frame ?? ''), Number(data.ownWidth), Number(data.measuredWidth), Number(data.height))
       } else if (data.type === 'sh:go') {
         const target = String(data.target ?? '')
         const existing = s.nodes.find((n) => n.frame === target && !n.missing)
@@ -605,7 +615,18 @@ export function App() {
   // the sidebar reflects the ACTIVE BOARD: only scenes/frames with a node on this board
   const onBoard = new Set(nodes.map((n) => n.frame))
   const frames = (manifest?.frames ?? []).filter((f) => onBoard.has(f.id))
-  const scenes = [...new Set(frames.map((f) => f.scene))].sort()
+  // scene groups follow the CANVAS reading order (earliest node y, then x), the
+  // same law as frame rows - a story board's phases list top-to-bottom as laid out
+  const scenes = [...new Set(frames.map((f) => f.scene))].sort((a, b) => {
+    const min = (sc: string) => nodes.reduce((acc, n) => {
+      const f = frames.find((x) => x.id === n.frame)
+      if (f?.scene !== sc) return acc
+      return !acc || n.y < acc.y || (n.y === acc.y && n.x < acc.x) ? { y: n.y, x: n.x } : acc
+    }, null as { y: number; x: number } | null)
+    const ma = min(a), mb = min(b)
+    if (!ma || !mb) return ma ? -1 : mb ? 1 : a.localeCompare(b)
+    return ma.y - mb.y || ma.x - mb.x || a.localeCompare(b)
+  })
     .map((name) => ({ name, frames: frames.filter((f) => f.scene === name).length }))
   // frame ids currently selected, for marking their parent scenes as `held`
   const selFrames = new Set(nodes.filter((n) => selection.includes(n.key)).map((n) => n.frame))
@@ -651,8 +672,24 @@ export function App() {
                 }}>
                 {(() => {
                   // variant groups render as ONE surface row with A/B/C chips (SPEC-023 §5)
-                  const sceneFrames = frames.filter((f) => f.scene === sc.name)
                   const nodeFor = (id: string) => nodes.find((x) => x.frame === id && !x.missing) ?? nodes.find((x) => x.frame === id)
+                  // sidebar order follows the CANVAS (reading order: rows top-to-bottom,
+                  // left-to-right) - a story board's list must tell the same story as its
+                  // layout. Grouped frames anchor at their group's earliest position so
+                  // the run stays contiguous; members sort by letter within it.
+                  const pos = (id: string) => { const n = nodeFor(id); return n ? { y: n.y, x: n.x } : { y: Number.MAX_SAFE_INTEGER, x: 0 } }
+                  const sceneFrames = frames.filter((f) => f.scene === sc.name)
+                  const groupPos = new Map<string, { y: number; x: number }>()
+                  for (const f of sceneFrames) {
+                    if (!f.variantGroup) continue
+                    const p = pos(f.id), g = groupPos.get(f.variantGroup)
+                    if (!g || p.y < g.y || (p.y === g.y && p.x < g.x)) groupPos.set(f.variantGroup, p)
+                  }
+                  const keyOf = (f: FrameEntry) => f.variantGroup ? groupPos.get(f.variantGroup)! : pos(f.id)
+                  sceneFrames.sort((a, b) => {
+                    const ka = keyOf(a), kb = keyOf(b)
+                    return ka.y - kb.y || ka.x - kb.x || (a.variant ?? '').localeCompare(b.variant ?? '')
+                  })
                   const go = (id: string, shift: boolean) => {
                     const n = nodeFor(id)
                     if (!n) return
@@ -675,12 +712,14 @@ export function App() {
                         // group participates without claiming full selection
                         const held = !allOn && memberKeys.some((k) => selection.includes(k) || useStore.getState().interact === k)
                         // group header: click selects EVERY variant (the quick compare-and-test grab)
+                        // the group row leads with the flask - variant-ness IS the row's
+                        // identity; members carry their letter chips, indented below it
                         rows.push(
                           <div key={`g:${f.variantGroup}`} className={`sub vgroup${allOn ? ' on' : ''}${held ? ' held' : ''}`}
                             title="Select all variants"
                             onClick={() => { useStore.getState().selectMany(memberKeys); canvasCtl.fitNodes(memberKeys) }}>
+                            <VariantsIcon size={13} className="iicon" />
                             <span className="glabel">{rel}</span>
-                            <VariantsIcon size={14} className="gicon" />
                           </div>,
                         )
                         // one row per variant: [letter chip] + name, individually selectable
@@ -700,7 +739,12 @@ export function App() {
                     const n = nodeFor(f.id)
                     const on = !!n && selection.includes(n.key)
                     rows.push(
-                      <div key={f.id} className={`sub${on ? ' on' : ''}`} onClick={(e) => go(f.id, e.shiftKey)}>
+                      <div key={f.id} className={`sub${on ? ' on' : ''}`} onClick={(e) => go(f.id, e.shiftKey)} title={f.intent}>
+                        {/* every frame leads with an icon: intent glyph for content
+                            frames, the plain frame rectangle for UI frames */}
+                        {f.intent
+                          ? <IntentGlyph intent={f.intent} size={13} className="iicon" aria-label={f.intent} />
+                          : <FrameRectIcon size={13} className="iicon" />}
                         {cap(f.id.split('/').slice(1).join('/') || f.id)}
                       </div>,
                     )

package/src/client/shell/Play.tsx

@@ -420,7 +420,6 @@ function PlayInner() {
         </Tip>
         {variants.length > 1 && <>
           <i className="sep" />
-          <span className="vname">{(() => { const c = variants.find((v) => v.id === play.at); return c ? (c.title ?? (c.id.split('/').pop() ?? '').replace(/^[a-z]-/, '').replace(/-/g, ' ')) : '' })()}</span>
           {variants.map((v) => (
             <Tip inv key={v.id} label={<><b>{v.title ?? v.id}</b><span className="k">[ ]</span></>}>
               <button className={`vchip${v.id === play.at ? ' on' : ''}`} onClick={() => goTo(v.id)}>
@@ -428,6 +427,13 @@ function PlayInner() {
               </button>
             </Tip>
           ))}
+          {(() => {
+            // chips lead as the stable anchor; the name trails at natural width, so
+            // a length change grows the pill rightward instead of shifting the chips
+            const c = variants.find((v) => v.id === play.at)
+            const full = c ? (c.title ?? (c.id.split('/').pop() ?? '').replace(/^[a-z]-/, '').replace(/-/g, ' ')) : ''
+            return <Tip inv label={<b>{full}</b>}><span className="vname">{full}</span></Tip>
+          })()}
         </>}
       </div>
     </div>

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

@@ -1,6 +1,6 @@
 import { memo, useEffect, useRef } from 'react'
 import { cap, frameUrl, useStore, CONFIG, type Node } from '../store.ts'
-import { CopyIcon, ReloadIcon, XIcon } from '../icons.tsx'
+import { CopyIcon, IntentGlyph, ReloadIcon, XIcon } from '../icons.tsx'
 
 export const HEADER = 28
 const SNAP = 12
@@ -169,6 +169,8 @@ export const FrameNode = memo(function FrameNode({ node }: { node: Node }) {
         </div>
       )}
       <div className="sh-node-head sh-no-pan" onPointerDown={(e) => drag(e, 'move')} title={frame.file}>
+        {/* content frames carry their intent glyph in the chrome (SPEC-026) */}
+        {frame.intent && <IntentGlyph intent={frame.intent} size={12} className="iicon sh-no-pan" aria-label={frame.intent} />}
         <span className="id sh-no-pan">{frame.title ?? frame.id}</span>
         <span className="dim sh-no-pan">{Math.round(node.w)} · {node.theme}</span>
       </div>

package/src/client/shell/icons.tsx

@@ -38,6 +38,28 @@ export const ParallelogramDuoIcon = icon(<><path d="M239.29,59.28l-64.8,144a8,8,
 /** Sidebar trigger, custom in Phosphor 256-space: outer frame + panel pill -
  *  pill filled while the sidebar is open, hollow while collapsed. */
 export const PanelFilledIcon = icon(<><rect x="32" y="48" width="192" height="160" rx="32" fill="none" stroke="currentColor" strokeWidth="16" /><rect x="72" y="88" width="48" height="80" rx="24" /></>)
+
+/** Plain UI frame - the rectangle every non-content sidebar row leads with. */
+export const FrameRectIcon = icon(<rect x="40" y="52" width="176" height="152" rx="20" fill="none" stroke="currentColor" strokeWidth="16" />)
+
+/* Content-frame intent glyphs (SPEC-026), custom in the same 256-space. */
+export const DiagramShapeIcon = icon(<><rect x="28" y="36" width="88" height="64" rx="14" fill="none" stroke="currentColor" strokeWidth="16" /><rect x="140" y="156" width="88" height="64" rx="14" fill="none" stroke="currentColor" strokeWidth="16" /><path d="M116 68 H184 V156" fill="none" stroke="currentColor" strokeWidth="16" strokeLinecap="round" strokeLinejoin="round" /></>)
+export const SpecDocIcon = icon(<><path d="M44 48 H180 M44 96 H212 M44 144 H212 M44 192 H140" fill="none" stroke="currentColor" strokeWidth="16" strokeLinecap="round" /></>)
+export const MoodboardIcon = icon(<><rect x="32" y="48" width="192" height="160" rx="20" fill="none" stroke="currentColor" strokeWidth="16" /><circle cx="96" cy="104" r="18" /><path d="M56 192 L112 128 L150 168 L178 140 L200 164 V192 Z" /></>)
+export const NoteStickyIcon = icon(<><path d="M52 40 H204 a16 16 0 0 1 16 16 V152 L156 216 H52 a16 16 0 0 1 -16 -16 V56 a16 16 0 0 1 16 -16 Z" fill="none" stroke="currentColor" strokeWidth="16" strokeLinejoin="round" /><path d="M156 216 V168 a16 16 0 0 1 16 -16 h48" fill="none" stroke="currentColor" strokeWidth="16" strokeLinejoin="round" /></>)
+export const ContentBlocksIcon = icon(<><rect x="36" y="36" width="80" height="80" rx="14" fill="none" stroke="currentColor" strokeWidth="16" /><circle cx="180" cy="180" r="44" fill="none" stroke="currentColor" strokeWidth="16" /><path d="M180 36 L224 116 H136 Z" fill="none" stroke="currentColor" strokeWidth="16" strokeLinejoin="round" /></>)
+
+/** intent -> glyph; unknown intents fall to the generic content icon (forward-compatible).
+ *  Accessible by default: role img + label + tooltip carry the intent name (the base
+ *  icon() is aria-hidden; the spread below overrides it). */
+export function IntentGlyph({ intent, size = 14, ...rest }: IconProps & { intent: string }) {
+  const I = intent === 'diagram' ? DiagramShapeIcon
+    : intent === 'spec' ? SpecDocIcon
+    : intent === 'moodboard' ? MoodboardIcon
+    : intent === 'notes' ? NoteStickyIcon
+    : ContentBlocksIcon
+  return <I size={size} role="img" aria-hidden={false} aria-label={intent} {...({ title: intent } as object)} {...rest} />
+}
 export const PanelHollowIcon = icon(<><rect x="32" y="48" width="192" height="160" rx="32" fill="none" stroke="currentColor" strokeWidth="16" /><rect x="72" y="88" width="48" height="80" rx="24" fill="none" stroke="currentColor" strokeWidth="14" /></>)
 /** Board glyphs: CardsThree = the built-in `all-scenes` board; Cards = curated boards. */
 export const CardsThreeIcon = icon(<path d="M208,88H48a16,16,0,0,0-16,16v96a16,16,0,0,0,16,16H208a16,16,0,0,0,16-16V104A16,16,0,0,0,208,88Zm0,112H48V104H208v96ZM48,64a8,8,0,0,1,8-8H200a8,8,0,0,1,0,16H56A8,8,0,0,1,48,64ZM64,32a8,8,0,0,1,8-8H184a8,8,0,0,1,0,16H72A8,8,0,0,1,64,32Z" />)