@marver-design/marver 0.4.0 → 0.5.0

package/src/client/shell/store.ts

@@ -35,9 +35,10 @@ export interface Node {
 }
 export interface Toast { id: number; text: string }
 
-export const CONFIG: { viewports: Record<string, { width: number; height: number }>; themes: string[]; zoomSpeed?: number; noTheme: boolean; setup?: boolean } = shConfig
+export const CONFIG: { viewports: Record<string, { width: number; height: number }>; themes: string[]; zoomSpeed?: number; noTheme: boolean; setup?: boolean; projectName?: string } = shConfig
 
-export const cap = (s: string) => (s ? s[0].toUpperCase() + s.slice(1) : s)
+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. */
@@ -47,7 +48,7 @@ export async function fetchBoardNames(): Promise<string[]> {
   return ['all-scenes', ...list.map((b) => b.name).filter((n) => n !== 'all-scenes').sort()]
 }
 /** Display name for a board: the reserved 'all-scenes' key reads as "All scenes". */
-export const boardLabel = (n: string) => (n === 'all-scenes' ? 'All scenes' : cap(n))
+export const boardLabel = (n: string) => humanize(n)
 
 const HEADER = 28
 let toastSeq = 0
@@ -125,6 +126,14 @@ interface State {
   toasts: Toast[]
   boardHash: string | null            // sha256 of the board file on disk, when materialized
   dirty: boolean
+  // A6/A7 controlled HMR (transient, never persisted): a frame the user is actively using
+  // (interact/play target, mid-gesture, laser/comment engaged) is "leased" - a hot update to
+  // it is DEFERRED (coalesced to the latest revision) until a safe point, so an agent edit
+  // never yanks the user out of their flow.
+  pendingFrameRevisions: Record<string, string>            // frameId -> latest deferred revision
+  externalLeases: Record<string, { laser?: true; comment?: true }>   // nodeKey -> transient engagement
+  playUpdateRevision: string | null                        // a revision arrived while play is open
+  playNav: number                                          // bumps to reload the play stage on demand
 
   boot(): Promise<boolean>
   applyManifest(m: Manifest): void
@@ -141,6 +150,10 @@ interface State {
   setPlay(p: State['play']): void
   setGesture(g: boolean): void
   setLaser(on: boolean): void
+  invalidateFrames(frameIds: string[], revision: string): void
+  setExternalLease(nodeKey: string, reason: 'laser' | 'comment', on: boolean): void
+  flushFrameUpdates(frameIds?: string[]): void
+  applyPlayUpdate(): void
   moveSelectedBy(dx: number, dy: number, starts: Record<string, { x: number; y: number }>): void
   setSelectedTheme(theme: string): void
   setDeviceView(name: string | null): void
@@ -155,6 +168,16 @@ interface State {
   save(): Promise<boolean>
 }
 
+/** A6: is any node of this frame in active use, so a hot update must DEFER? Frame-scoped -
+ *  if the same frame is placed twice and one copy is active, both stay on the same revision. */
+function frameIsLeased(frameId: string, s: State): boolean {
+  return s.nodes.some((n) =>
+    n.frame === frameId && n.status !== 'error' && (
+      s.interact === n.key ||
+      (s.gesture && s.selection.includes(n.key)) ||
+      !!s.externalLeases[n.key]))
+}
+
 export const useStore = create<State>((set, get) => {
   let saveTimer: ReturnType<typeof setTimeout> | undefined
   let saveChain: Promise<boolean> = Promise.resolve(true)   // saves are serialized; responses only commit if the board is still active
@@ -393,6 +416,7 @@ export const useStore = create<State>((set, get) => {
     manifest: null, nodes: [], selection: [], interact: null, viewTheme: initialViewTheme(), play: null, gesture: false, laser: false,
     board: DATA?.default ?? 'all-scenes', boardAuto: (DATA?.default ?? 'all-scenes') === 'all-scenes', deviceView: null, sceneRows: null, layout: null, layoutRaw: undefined, baseLayout: null,
     panelOpen: true, scale: 1, toasts: [], boardHash: null, dirty: false,
+    pendingFrameRevisions: {}, externalLeases: {}, playUpdateRevision: null, playNav: 0,
 
     async boot() {
       const seq = ++loadSeq
@@ -687,9 +711,22 @@ export const useStore = create<State>((set, get) => {
     // interact is a ONE-frame mode: entering it collapses any multi-selection to the
     // interacted frame (a 4-frame selection double-clicked otherwise leaves all four
     // painted as "interactive"). Exiting keeps the frame selected for continuity.
-    setInteract(key) { set((s) => ({ interact: key, selection: key ? [key] : s.selection })) },
+    setInteract(key) {
+      set((s) => ({ interact: key, selection: key ? [key] : s.selection }))
+      get().flushFrameUpdates()   // A6: the frame just left interact is no longer leased
+    },
     setPlay(play) { set({ play }) },
-    setLaser(laser) { set({ laser }) },
+    setLaser(laser) {
+      if (laser) { set({ laser }); return }
+      // leaving laser mode drops every laser engagement lease (the bridge stops reporting), but
+      // keeps comment engagement; the freed frames may now flush a deferred update
+      set((s) => ({
+        laser,
+        externalLeases: Object.fromEntries(
+          Object.entries(s.externalLeases).filter(([, v]) => v.comment).map(([k]) => [k, { comment: true as const }])),
+      }))
+      get().flushFrameUpdates()
+    },
     setGesture(gesture) {
       set({ gesture })
       // SPEC-024 §4: a board WITH a layout recipe re-applies it when a resize
@@ -699,6 +736,49 @@ export const useStore = create<State>((set, get) => {
         if (get().layout || get().sceneRows?.length) get().runTidy()   // schedules the save
         else scheduleSave()
       }
+      if (!gesture) get().flushFrameUpdates()   // A6: gesture end is a safe point for deferred updates
+    },
+    // A6/A7: apply a controlled hot update. A leased frame's revision is deferred (coalesced to
+    // the latest) and applied at the next safe point; an idle frame reloads now via its nav nonce.
+    invalidateFrames(frameIds, revision) {
+      const ids = new Set(frameIds.filter((x) => typeof x === 'string'))
+      if (!ids.size) return
+      bumpManifestRev()
+      const s = get()
+      const pending = { ...s.pendingFrameRevisions }
+      const nodes = s.nodes.map((n) => {
+        if (!ids.has(n.frame)) return n
+        if (frameIsLeased(n.frame, s)) { pending[n.frame] = revision; return n }
+        return { ...n, status: 'loading' as const, error: undefined, nav: (n.nav ?? 0) + 1 }
+      })
+      set({ nodes, pendingFrameRevisions: pending, ...(s.play ? { playUpdateRevision: revision } : {}) })
+    },
+    flushFrameUpdates(frameIds) {
+      const s = get()
+      const ids = (frameIds ?? Object.keys(s.pendingFrameRevisions)).filter((id) => s.pendingFrameRevisions[id] && !frameIsLeased(id, s))
+      if (!ids.length) return
+      bumpManifestRev()
+      const apply = new Set(ids)
+      const pending = { ...s.pendingFrameRevisions }
+      for (const id of ids) delete pending[id]
+      const nodes = s.nodes.map((n) => apply.has(n.frame)
+        ? { ...n, status: 'loading' as const, error: undefined, nav: (n.nav ?? 0) + 1 } : n)
+      set({ nodes, pendingFrameRevisions: pending })
+    },
+    setExternalLease(nodeKey, reason, on) {
+      set((s) => {
+        const cur = { ...(s.externalLeases[nodeKey] ?? {}) }
+        if (on) cur[reason] = true; else delete cur[reason]
+        const leases = { ...s.externalLeases }
+        if (Object.keys(cur).length) leases[nodeKey] = cur; else delete leases[nodeKey]
+        return { externalLeases: leases }
+      })
+      if (!on) get().flushFrameUpdates()
+    },
+    applyPlayUpdate() {
+      if (!get().playUpdateRevision) return
+      bumpManifestRev()
+      set((s) => ({ playUpdateRevision: null, playNav: s.playNav + 1 }))
     },
     setScale(scale) { set({ scale }) },
     togglePanel() { set((s) => ({ panelOpen: !s.panelOpen })) },
@@ -803,10 +883,19 @@ export const useStore = create<State>((set, get) => {
         try {
           const res = await fetch(`${ROUTE}/api/boards/${boardName}`, {
             method: 'PUT', headers: { 'content-type': 'application/json' },
-            body: JSON.stringify({ board, baseHash: boardHash }),
+            // A9: a board loaded from disk (boardHash set) autosaves with mustExist so a
+            // rename/delete out from under us returns 409 instead of resurrecting a ghost.
+            body: JSON.stringify({ board, baseHash: boardHash, mustExist: !!boardHash }),
           })
           if (get().board !== boardName) return true   // switched boards mid-flight; stale response must not touch state
           if (res.status === 409) {
+            const info = await res.json().catch(() => ({} as { gone?: boolean }))
+            if (info?.gone) {
+              // renamed/deleted externally - drop the write, don't recreate it or loop
+              set({ dirty: false })
+              get().toast('this board was renamed or removed - not recreating it')
+              return true
+            }
             const reloaded = await get().boot()   // hash advances only when the authoritative reload commits
             if (reloaded) get().toast('board changed on disk - canvas layout reloaded')
             return reloaded   // false keeps dirty set; the next debounce retries once edits settle
@@ -825,3 +914,6 @@ export const useStore = create<State>((set, get) => {
     },
   }
 })
+
+// dev-only inspection hook for tests/debugging (never installed in published builds)
+if (import.meta.env.DEV) (window as unknown as { __mvStore: unknown }).__mvStore = useStore

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/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

@@ -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