@marver-design/marver 0.11.1 → 0.13.0

package/src/client/shell/Comments.tsx

@@ -4,16 +4,16 @@
  * top-right stack; the thread card opens beside its pin. Pins keep a screen-space
  * size via --sh-inv (the vbadge pattern) so zoom never shrinks them away.
  */
-import { useEffect, useRef, useState } from 'react'
+import { useEffect, useMemo, useRef, useState } from 'react'
 import { createPortal } from 'react-dom'
 import { avatarFallback, useComments } from './comments-store.ts'
 import { useStore, type Node } from './store.ts'
 import { threadHostKey } from './keys.ts'
-import { canvasCtl } from './canvas/Canvas.tsx'
+import { canvasCtl } from './canvas/ctl.ts'
 import { bootHash, buildHash, parseHash, writeHash } from './hash.ts'
 import { ArrowUpIcon, CheckIcon, CheckSquareOffsetIcon, LinkIcon, ParallelogramFillIcon, PencilSimpleIcon, PlusIcon, XIcon } from './icons.tsx'
 import { Tip } from './Tip.tsx'
-import { parseMentions } from './mentions.ts'
+import { mentionAlerts, mentionPeople, mentionQueryAt, parseBody, type MentionPerson } from './mentions.ts'
 import { ROUTE } from '../const.ts'
 import type { AgentMeta, Thread } from '../../shared/events.ts'
 
@@ -74,7 +74,7 @@ export function Avatar({ author, size = 22 }: { author?: { email?: string; name?
   )
 }
 
-type Face = { email?: string; name?: string; avatar?: string; agent?: boolean }
+type Face = { email?: string; id?: string; name?: string; avatar?: string; agent?: boolean }
 
 /** The signal a marker (pin or stack) carries: WHO took part and HOW MANY comments
  *  in total - root + every reply, across all the given threads. Unique participants
@@ -89,7 +89,9 @@ function markerDigest(threads: Thread[]): { faces: Face[]; count: number } {
   // Avatar renders them all as the live identity - two keys would show identical twin faces.
   const add = (a: Face | undefined, agent?: boolean) => {
     const face: Face | undefined = agent ? { agent: true } : a
-    const k = agent ? 'marver' : a?.email ? `e:${a.email.toLowerCase()}` : 'local'
+    // published transport carries the opaque id instead of an email - same
+    // namespacing rule, different stable key
+    const k = agent ? 'marver' : a?.email ? `e:${a.email.toLowerCase()}` : a?.id ? `i:${a.id}` : 'local'
     if (face && !seen.has(k)) seen.set(k, face)
   }
   for (const t of threads) {
@@ -180,13 +182,15 @@ export function CommentLayer({ node, frameId, iframe }: { node: Node; frameId: s
   const flankBadge = useStore((s) => !!s.frameFor(node)?.variantGroup)
   const flankShim = useStore((s) => s.working.includes(frameId))
   const drafting = draft?.nodeKey === node.key
+  const alertIds = useMentionAlerts()
   if (!show || (!open.length && !drafting)) return null
 
   // inactive frame: the stack - count + avatars, top-right
   const engaged = selected || open.some((t) => t.id === active) || drafting
   if (!engaged && open.length) {
     return (
-      <button className="cm-stack sh-no-pan" onClick={(e) => { e.stopPropagation(); useStore.getState().select(node.key); if (open[0]) setActive(open[0].id) }}>
+      <button className={`cm-stack sh-no-pan${open.some((t) => alertIds.has(t.id)) ? ' mention' : ''}`}
+        onClick={(e) => { e.stopPropagation(); useStore.getState().select(node.key); const hit = open.find((t) => alertIds.has(t.id)) ?? open[0]; if (hit) setActive(hit.id) }}>
         <MarkerFace threads={open} />
       </button>
     )
@@ -232,7 +236,7 @@ export function CommentLayer({ node, frameId, iframe }: { node: Node; frameId: s
         const { x, y, orphan } = pinPos(t)
         const isActive = t.id === active
         return (
-          <div key={t.id} className={`cm-pin sh-no-pan${isActive ? ' on' : ''}${isActive && cardSide === 'r' ? ' tail-r' : ''}${orphan ? ' orphan' : ''}`}
+          <div key={t.id} className={`cm-pin sh-no-pan${isActive ? ' on' : ''}${isActive && cardSide === 'r' ? ' tail-r' : ''}${orphan ? ' orphan' : ''}${alertIds.has(t.id) ? ' mention' : ''}`}
             style={{ left: x, top: y, ...hueVars(anchorHue(t.anchor)) }}
             onPointerDown={(e) => e.stopPropagation()}
             onClick={(e) => { e.stopPropagation(); setActive(t.id === active ? null : t.id) }}
@@ -256,17 +260,51 @@ export function CommentLayer({ node, frameId, iframe }: { node: Node; frameId: s
 
 const AT_TIP = "Read like any other comment. Marver won't act on this unless the owner promotes it."
 
-/** A comment body with @marver mentions styled: owner-authored → bold accent (a live trigger);
- *  anyone else's → plain + a teaching tooltip (context, not a command). */
+/** The mentionable set, derived from everything the client has seen (published:
+ *  projected ids + names; dev: canonical emails). The viewer themself is out -
+ *  this is the COMPOSER's set (you cannot mention yourself). */
+function usePeople(): MentionPerson[] {
+  const events = useComments((s) => s.events)
+  const me = useComments((s) => s.me)
+  return mentionPeople(events, me ?? undefined)
+}
+
+/** Everyone, self included - the RENDERING set: a mention of you must light up
+ *  hardest of all, not disappear (the bug that shipped: the excluded self made
+ *  your own mentions render as plain text exactly for the person they were for). */
+function useRenderPeople(): { people: MentionPerson[]; isMe: (p: MentionPerson) => boolean } {
+  const events = useComments((s) => s.events)
+  const me = useComments((s) => s.me)
+  const people = useMemo(() => mentionPeople(events), [events])
+  const isMe = (p: MentionPerson) =>
+    (!!p.id && p.id === me?.id) || (!!p.email && !!me?.email && p.email.toLowerCase() === me.email.toLowerCase())
+  return { people, isMe }
+}
+
+/** Threads holding an unseen mention of me - drives the pin/stack pulse. */
+function useMentionAlerts(): Set<string> {
+  const events = useComments((s) => s.events)
+  const me = useComments((s) => s.me)
+  const seen = useComments((s) => s.mentionSeen)
+  return useMemo(() => new Set(mentionAlerts(events, me, seen)), [events, me, seen])
+}
+
+/** A comment body with mentions styled. `@marver`: owner-authored → bold accent (a live
+ *  trigger); anyone else's → plain + a teaching tooltip (context, not a command).
+ *  `@Person` (v1.1) → the person chip; the same segmentation that derived the
+ *  event's mentions, so what lit up is what notified. */
 function CommentBody({ body, owner }: { body?: string; owner: boolean }) {
+  const { people, isMe } = useRenderPeople()
   if (!body) return null
   return (
     <p className="cm-body">
-      {parseMentions(body).map((s, i) => !s.mention
-        ? <span key={i}>{s.text}</span>
-        : owner
-          ? <span key={i} className="cm-at owner">{s.text}</span>
-          : <Tip key={i} side="top" label={<span className="cm-at-tip">{AT_TIP}</span>}><span className="cm-at">{s.text}</span></Tip>)}
+      {parseBody(body, people).map((s, i) => s.person
+        ? <span key={i} className={isMe(s.person) ? 'cm-at person me' : 'cm-at person'}>{s.text}</span>
+        : !s.marver
+          ? <span key={i}>{s.text}</span>
+          : owner
+            ? <span key={i} className="cm-at owner">{s.text}</span>
+            : <Tip key={i} side="top" label={<span className="cm-at-tip">{AT_TIP}</span>}><span className="cm-at">{s.text}</span></Tip>)}
     </p>
   )
 }
@@ -337,6 +375,27 @@ function CommentInput({ value, onChange, onSubmit, onCancel, placeholder, autoFo
   const ref = useRef<HTMLTextAreaElement>(null)
   const hlRef = useRef<HTMLDivElement>(null)
   const [busy, setBusy] = useState(false)
+  // ---- @-mention typeahead (v1.1): the token under the caret filters the people the
+  // client has seen; picking completes `@Label ` in place. Escape dismisses THIS token
+  // only (the composer keeps its own Escape = cancel semantics when no list is open).
+  const people = usePeople()
+  const [caret, setCaret] = useState(0)
+  const [pick, setPick] = useState(0)
+  const [dismissed, setDismissed] = useState<number | null>(null)
+  const q = mentionQueryAt(value, caret)
+  const matches = q && dismissed !== q.start
+    ? people.filter((p) => p.label.toLowerCase().startsWith(q.query.toLowerCase())).slice(0, 5)
+    : []
+  const listOpen = matches.length > 0
+  useEffect(() => { setPick(0) }, [q?.start, q?.query])
+  const track = () => setCaret(ref.current?.selectionStart ?? 0)
+  const choose = (p: MentionPerson) => {
+    if (!q) return
+    const pos = q.start + p.label.length + 2                        // '@' + label + ' '
+    onChange(value.slice(0, q.start) + '@' + p.label + ' ' + value.slice(caret))
+    setCaret(pos)
+    requestAnimationFrame(() => { const el = ref.current; if (el) { el.focus(); el.setSelectionRange(pos, pos) } })
+  }
   // +2: scrollHeight excludes the 1px borders, but border-box height includes them - without
   // it every line is squeezed 2px and the single-line pill renders off-center
   const grow = () => { const el = ref.current; if (el) { el.style.height = 'auto'; el.style.height = Math.min(el.scrollHeight + 2, 132) + 'px' } }
@@ -350,18 +409,38 @@ function CommentInput({ value, onChange, onSubmit, onCancel, placeholder, autoFo
   }
   return (
     <div className="cm-inputwrap">
-      {/* Live mention highlight: a mirror layer behind the transparent-text textarea, so @marver shows
-          its trigger colour AS YOU TYPE (owner = accent-blue "this will run"; else muted). */}
+      {/* Live mention highlight: a mirror layer behind the transparent-text textarea, so @marver
+          shows its trigger colour AS YOU TYPE (owner = accent-blue "this will run"; else muted)
+          and a completed @Person wears the chip it will render with. */}
       <div className="cm-hl" ref={hlRef} aria-hidden>
-        {parseMentions(value).map((s, i) => s.mention
-          ? <span key={i} className={owner ? 'cm-at owner' : 'cm-at'}>{s.text}</span>
-          : <span key={i}>{s.text}</span>)}
+        {parseBody(value, people).map((s, i) => s.person
+          ? <span key={i} className="cm-at person">{s.text}</span>
+          : s.marver
+            ? <span key={i} className={owner ? 'cm-at owner' : 'cm-at'}>{s.text}</span>
+            : <span key={i}>{s.text}</span>)}
         {value.endsWith('\n') ? '​' : ''}
       </div>
+      {listOpen && (
+        <div className="cm-mentionlist" role="listbox">
+          {matches.map((p, i) => (
+            <button key={p.id ?? p.email} type="button" className={i === pick ? 'on' : ''} role="option" aria-selected={i === pick}
+              onMouseDown={(e) => { e.preventDefault(); choose(p) }} onMouseEnter={() => setPick(i)}>
+              <Avatar author={{ ...p, name: p.label }} size={18} /><span>{p.label}</span>
+            </button>
+          ))}
+        </div>
+      )}
       <textarea ref={ref} rows={1} value={value} placeholder={placeholder} disabled={busy} spellCheck={false}
-        onChange={(e) => onChange(e.target.value)} onInput={grow} onScroll={syncScroll}
+        onChange={(e) => { onChange(e.target.value); setDismissed(null); setCaret(e.target.selectionStart ?? 0) }}
+        onInput={grow} onScroll={syncScroll} onClick={track} onKeyUp={track}
         onKeyDown={(e) => {
           e.stopPropagation()
+          if (listOpen) {
+            if (e.key === 'ArrowDown') { e.preventDefault(); setPick((v) => (v + 1) % matches.length); return }
+            if (e.key === 'ArrowUp') { e.preventDefault(); setPick((v) => (v + matches.length - 1) % matches.length); return }
+            if (e.key === 'Enter' || e.key === 'Tab') { e.preventDefault(); choose(matches[pick] ?? matches[0]); return }
+            if (e.key === 'Escape') { setDismissed(q!.start); return }
+          }
           if (e.key === 'Escape') { onCancel?.(); return }
           if (e.key === 'Enter') {
             if ((e.nativeEvent as unknown as { isComposing?: boolean }).isComposing) return   // IME: mid-composition Enter must not send
@@ -465,8 +544,10 @@ export function ThreadCard({ thread, at, bounds, nodeKey, side = 'r', flank, sta
   const local = useComments((s) => s.local)
   const canComment = local || !!me      // dev is always "me"; published needs a session
   // Owner-authored @marver is a live trigger (bold accent); anyone else's is context (plain + tooltip).
-  // Match by email when we know the owner's; in dev without a profile, local writes are the owner.
-  const isOwner = (a?: { email?: string }) => (me?.email ? a?.email === me.email : local)
+  // Match by opaque id on the projected transport, by email locally; in dev
+  // without a profile, local writes are the owner.
+  const isOwner = (a?: { email?: string; id?: string }) =>
+    me?.id && a?.id ? a.id === me.id : me?.email ? a?.email === me.email : local
   const [text, setText] = useState('')
   const [copied, setCopied] = useState(false)
   const copyTimer = useRef<ReturnType<typeof setTimeout>>(undefined)

package/src/client/shell/LockedApp.tsx

@@ -0,0 +1,113 @@
+/**
+ * The locked-shell entry (01-sharing §5.1's all-boards rule) - what a bundle
+ * whose every published board is locked to a stage mode boots into INSTEAD of
+ * the canvas shell. The build swaps this module in for App.tsx, so the canvas
+ * surface (sidebar, board grid, toolbar) is not hidden - its code never enters
+ * the bundle. Publish-to-web, as an artifact rather than a flag.
+ *
+ * What remains is exactly the locked surface: boot, the landing rule, the play
+ * or focus overlay (whose lock already refuses every exit), and deep links
+ * within what the lock allows.
+ */
+import { Component, useEffect, useRef, type ReactNode } from 'react'
+import { useStore, boardLabel, landingMode } from './store.ts'
+import { enterFocus, enterPlay, PlayOverlay, playCtl } from './Play.tsx'
+import { bootHash, parseHash, writeHash } from './hash.ts'
+import { useComments } from './comments-store.ts'
+
+export class ShellBoundary extends Component<{ children: ReactNode }, { err: Error | null }> {
+  state = { err: null as Error | null }
+  static getDerivedStateFromError(err: Error) { return { err } }
+  render() {
+    if (!this.state.err) return this.props.children
+    return (
+      <div style={{ fontFamily: 'ui-monospace, monospace', padding: 32 }}>
+        <b style={{ color: '#a81f16' }}>shell crashed</b>
+        <pre style={{ whiteSpace: 'pre-wrap', fontSize: 12 }}>{this.state.err.message}</pre>
+        <button onClick={() => location.reload()}>reload</button>
+      </div>
+    )
+  }
+}
+
+let booted = false
+
+export function App() {
+  const toasts = useStore((s) => s.toasts)
+  const board = useStore((s) => s.board)
+
+  /** The landing rule, enforced: the mode the lock pinned, entered on boot and
+   *  re-entered if anything ever drops the overlay - there is no other surface. */
+  const land = () => {
+    const s = useStore.getState()
+    if (s.play) return
+    const mode = landingMode(s.board)
+    if (mode === 'focus') enterFocus()
+    else enterPlay()
+  }
+
+  useEffect(() => {
+    if (booted) return
+    booted = true
+    const start = async () => {
+      if (bootHash.board && bootHash.board !== useStore.getState().board)
+        useStore.setState({ board: bootHash.board, boardAuto: false })
+      const ok = await boot()
+      urlReady.current = true
+      if (!ok) return
+      if (bootHash.focus) enterFocus(bootHash.focus.at, { ...bootHash.focus, deep: true })
+      else if (bootHash.play) enterPlay(bootHash.play)
+      else land()
+    }
+    const boot = useStore.getState().boot
+    void start()
+  }, [])
+
+  // the overlay IS the surface: if it ever closes, land again
+  const play = useStore((s) => s.play)
+  useEffect(() => { if (!play) setTimeout(land, 30) }, [play])
+
+  // the URL projection, minimal: stage state only (there is no selection here)
+  const urlReady = useRef(false)
+  useEffect(() => {
+    if (!urlReady.current || !play) return
+    if (play.focus && play.deep) writeHash({ focus: { at: play.at, device: play.device, theme: play.theme } })
+    else if (!play.focus) writeHash({ board: useStore.getState().board, play })
+  })
+
+  // back/forward + pasted links, within what the lock allows
+  useEffect(() => {
+    const onPop = async () => {
+      const h = parseHash()
+      const s = useStore.getState()
+      if (h.board && h.board !== s.board) {
+        await s.switchBoard(h.board)
+        land()
+        return
+      }
+      if (h.focus) enterFocus(h.focus.at, { ...h.focus, deep: true })
+      else if (h.play && s.play) playCtl.sync(h.play)
+      else if (h.play) enterPlay(h.play)
+    }
+    window.addEventListener('popstate', onPop)
+    window.addEventListener('hashchange', onPop)
+    return () => { window.removeEventListener('popstate', onPop); window.removeEventListener('hashchange', onPop) }
+  }, [])
+
+  // comment liveness for the stage overlay - same wiring the canvas shell does
+  useEffect(() => {
+    if (!board) return
+    const c = useComments.getState()
+    void c.load(board)
+    return c.live(board)
+  }, [board])
+
+  useEffect(() => { document.title = board ? `${boardLabel(board)} - Marver` : 'Marver' }, [board])
+
+  return (
+    <div tabIndex={-1} className="sh-app dark">
+      <PlayOverlay />
+      <div className="sh-toasts">{toasts.map((t) => <div className="sh-toast" key={t.id}>{t.text}</div>)}</div>
+    </div>
+  )
+}

package/src/client/shell/Play.tsx

@@ -11,14 +11,14 @@
  * next) stays prototype-only.
  */
 import { useEffect, useRef, useState } from 'react'
-import { useStore, CONFIG, boardLabel, cap, fetchBoardNames, type Node } from './store.ts'
+import { useStore, BOARD_POLICY, BRANDING, CONFIG, PUBLISHED, SOURCE_REVEALED, boardLabel, boardLocked, cap, fetchBoardNames, modeAllowed, type Node } from './store.ts'
 import { useComments } from './comments-store.ts'
 import { ROUTE } from '../const.ts'
-import { canvasCtl } from './canvas/Canvas.tsx'
+import { canvasCtl } from './canvas/ctl.ts'
 import { Tip } from './Tip.tsx'
 import { CommentButton, DevicePicker, HideUIButton, isHideUI, LaserButton, Popover, ThemePicker, toggleHideUI, usePopover } from './Toolbar.tsx'
 import { DraftComposer, hueVars, MarkerFace, ThreadCard } from './Comments.tsx'
-import { ArrowLeftIcon, ArrowRightIcon, CaretIcon, CheckIcon, PanelFilledIcon, PanelHollowIcon, ReloadIcon, XIcon } from './icons.tsx'
+import { ArrowLeftIcon, ArrowRightIcon, BrowsersIcon, CaretIcon, CheckIcon, GridIcon, PanelFilledIcon, PanelHollowIcon, ParallelogramDuoIcon, ReloadIcon, SpecDocIcon } from './icons.tsx'
 
 const commentsStore = () => useComments.getState()
 
@@ -44,6 +44,8 @@ function playList(): string[] {
  *  off-board frames, so a link captured mid-flow must restore to the same screen. */
 export function enterPlay(over?: { at?: string; device?: string; theme?: string }) {
   const s = useStore.getState()
+  // the lock freezes what open pinned: a board locked to another mode never plays
+  if (!modeAllowed(s.board, 'present')) return
   const list = playList()
   if (!list.length) { s.toast('nothing to play on this board'); return }
   const overAt = over?.at && s.manifest?.frames.some((f) => f.id === over.at && f.kind === 'tsx') ? over.at : undefined
@@ -63,6 +65,34 @@ export function enterPlay(over?: { at?: string; device?: string; theme?: string
   s.setPlay({ at, device, theme })
 }
 
+/**
+ * Enter Focus - the fourth view mode (01-sharing §6.1): one frame, full screen.
+ * Landing on a doc board opens its first frame at the doc preset; a frame deep
+ * link (`deep`) may target any playable manifest frame and carries the
+ * single-frame chrome - no board name, no canvas door. Presentation, not
+ * access: every published board stays reachable by URL (04-solution §2.35).
+ */
+export function enterFocus(at?: string, over?: { device?: string; theme?: string; deep?: boolean }) {
+  const s = useStore.getState()
+  // a frame deep link may focus anywhere EXCEPT a board locked away from focus
+  // is still allowed - the lock caps THIS board's disclosure, and a deep link
+  // into a locked board stays in focus on that frame (01-sharing §6.1 rule 4);
+  // a non-deep focus entry respects the lock like any other mode change
+  if (!over?.deep && !modeAllowed(s.board, 'focus')) return
+  const list = playList()
+  const target = at && s.manifest?.frames.some((f) => f.id === at && f.kind === 'tsx') ? at : list[0]
+  if (!target) { s.toast('nothing to focus here'); return }
+  const frame = s.manifest?.frames.find((f) => f.id === target)
+  const node = s.nodes.find((n) => n.frame === target && !n.missing)
+  const names = Object.keys(CONFIG.viewports)
+  const device = (over?.device && (CONFIG.viewports[over.device] || over.device === 'fill') ? over.device : undefined)
+    ?? (node ? names.find((v) => CONFIG.viewports[v].width === node.w) : undefined)
+    ?? (frame?.viewport && CONFIG.viewports[frame.viewport] ? frame.viewport : names[0])
+  const theme = (over?.theme && CONFIG.themes.includes(over.theme) ? over.theme : undefined)
+    ?? node?.theme ?? frame?.theme ?? s.viewTheme
+  s.setPlay({ at: target, device, theme, focus: true, ...(over?.deep ? { deep: true } : {}) })
+}
+
 /** Switch boards WITHOUT leaving play: the overlay stays up over the canvas churn, then
  *  a fresh stage mounts at the new board's start (PlayInner is keyed by board). */
 async function switchPlayBoard(name: string) {
@@ -229,6 +259,13 @@ function PlayInner() {
   const [pillOpen, setPillOpen] = useState(true)          // collapse (pill -> re-open fab), like the canvas
   const [stageReady, setStageReady] = useState(0)         // bumps on each sh:stage-ready (reload) - re-drives the highlight
   const fill = play?.device === 'fill'
+  // the mode's shape: focus is single-frame; the doc preset (reading width,
+  // page ground) applies when the board's declared type is doc; lock and deep
+  // links both drop the canvas door (lock as policy, deep as the link's chrome)
+  const focus = !!play?.focus
+  const docPreset = focus && BOARD_POLICY[board]?.type === 'doc'
+  const locked = boardLocked(board)
+  const noDoor = locked || !!play?.deep
 
   // the stage is same-origin (/__mv/stage/); a fixed target origin keeps anchor bundles
   // from leaking if a link ever navigates the iframe cross-origin
@@ -250,6 +287,9 @@ function PlayInner() {
   useEffect(() => { postStage({ type: 'sh:pick', on: commentMode, quiet: !useComments.getState().showAnchor }) }, [commentMode, playShowAnchor])
 
   const exit = () => {
+    // the lock caps disclosure: a locked board has no way out into other modes,
+    // and a deep-link visit carries no door on the surface (URL still works)
+    if (noDoor) return
     const { at } = useStore.getState().play ?? {}
     if (isHideUI()) toggleHideUI()             // never strand the canvas with its chrome hidden
     useStore.getState().setPlay(null)
@@ -272,14 +312,14 @@ function PlayInner() {
   const goTo = (at: string) => playCtl.setAt(at)
   const step = (dir: 1 | -1) => {
     const p = useStore.getState().play
-    if (!p) return
+    if (!p || p.focus) return                  // focus is one frame - no walking
     const list = playList()
     if (!list.length) return
     const i = list.indexOf(p.at)
     // an off-board frame has no position: → restarts, ← goes to the last board frame
     goTo(i === -1 ? (dir === 1 ? list[0] : list[list.length - 1]) : list[(i + dir + list.length) % list.length])
   }
-  const restart = () => { const list = playList(); if (list.length) goTo(list[0]) }
+  const restart = () => { if (useStore.getState().play?.focus) return; const list = playList(); if (list.length) goTo(list[0]) }
 
   /** Variant siblings of the CURRENT frame present on this board: the
    *  review question is "which direction is better on THIS screen" - switch in place,
@@ -398,7 +438,7 @@ function PlayInner() {
     if (key === ']') { switchVariant(1); return }
     if (key === 'r') { restart(); return }
     if (key === 'h') { toggleHideUI(); return }
-    if (key === 'l') { const s = useStore.getState(); if (!s.laser) commentsStore().setMode(false); s.setLaser(!s.laser); return }
+    if (key === 'l' && SOURCE_REVEALED) { const s = useStore.getState(); if (!s.laser) commentsStore().setMode(false); s.setLaser(!s.laser); return }
     if (key === 'c') { const c = commentsStore(); if (!c.commentMode) useStore.getState().setLaser(false); c.setMode(!c.commentMode); return }
     if (key === 'C') { const c = commentsStore(); c.setShow(!c.show); return }   // ⇧C hides/shows pins
     if (key === 'L') { const c = commentsStore(); c.setShowAnchor(!c.showAnchor); return }   // ⇧L element focus
@@ -435,12 +475,18 @@ function PlayInner() {
 
   if (!play) return null                       // parent gates on play; belt to its braces
 
-  const vp = fill ? { width: win.w, height: win.h } : CONFIG.viewports[play.device] ?? Object.values(CONFIG.viewports)[0]
-  const scale = fill ? 1 : Math.min(1, (win.w - 96) / vp.width, (win.h - 128) / vp.height)
+  // doc preset: reading width, natural document scrolling - the iframe takes the
+  // window's height at min(width, 860) CSS pixels, unscaled, and scrolls itself
+  const vp = docPreset ? { width: Math.min(win.w, 860), height: win.h }
+    : fill ? { width: win.w, height: win.h }
+    : CONFIG.viewports[play.device] ?? Object.values(CONFIG.viewports)[0]
+  const scale = fill || docPreset ? 1 : Math.min(1, (win.w - 96) / vp.width, (win.h - 128) / vp.height)
   const names = Object.keys(CONFIG.viewports)
-  const list = playList()
+  const list = focus ? [play.at] : playList()
   const pos = list.indexOf(play.at)
   const variants = variantList()
+  const frameEntry = useStore.getState().manifest?.frames.find((f) => f.id === play.at)
+  const title = focus ? (frameEntry?.title ?? (play.at.split('/').pop() ?? play.at).replace(/-/g, ' ')) : boardLabel(board)
 
   // whole-pixel wrapper + per-axis scale so the iframe lands exactly on its edges -
   // fractional sizes left subpixel seams glowing at the corners on dark frames
@@ -449,7 +495,7 @@ function PlayInner() {
   const deviceHint = fill ? 'Fill window' : `${vp.width} × ${vp.height} · keys 1-${names.length + 1}`
 
   return (
-    <div className={`sh-play${fill ? ' fill' : ''}`}>
+    <div className={`sh-play${fill || docPreset ? ' fill' : ''}${docPreset ? ` doc t-${play.theme}` : ''}`}>
       {/* device + comment overlay share ONE flex-centered box; the overlay is inset:0 over
           it (a sibling of the clipping .dev, so a thread card is never eaten by overflow) */}
       <div className="sh-play-stage" style={{ width: dw, height: dh }}>
@@ -464,13 +510,35 @@ function PlayInner() {
         <PlayComments iframe={iframeRef} frameId={play.at} vp={vp} dw={dw} dh={dh} ready={stageReady} />
       </div>
 
+      {!focus && list.length > 1 && (
+        <div className="sh-play-hint">← → to step · <kbd>c</kbd> to comment</div>
+      )}
+
+      {/* top-left: brand + place (the present chrome's identity pill). A deep-link
+          focus visit names only the frame - single-frame chrome, no board (04 §2.35);
+          branding: false strips the mark (invariant 21). */}
+      <nav className={`sh-pill sh-play-pill sh-play-brand${pillOpen ? '' : ' closed'}`} aria-hidden={!pillOpen}>
+        {BRANDING && <>
+          <span className="sh-play-mark"><ParallelogramDuoIcon size={19} /><span className="wd">Marver</span></span>
+          <i className="sep" />
+        </>}
+        {focus && <SpecDocIcon size={15} style={{ flex: 'none', opacity: .7, marginRight: -2 }} />}
+        {!focus && !locked && !PUBLISHED ? <BoardMenu current={board} /> : (
+          <Tip side="bottom" label={<b>{CONFIG.projectName ?? title}</b>}>
+            <span className="sh-play-title">{title}</span>
+          </Tip>
+        )}
+      </nav>
+
       <nav className={`sh-pill sh-play-pill${pillOpen ? '' : ' closed'}`} aria-hidden={!pillOpen}>
-        <BoardMenu current={board} />
-        <i className="sep" />
+        {!focus && list.length > 1 && <>
+          <span className="sh-play-pos">{pos === -1 ? '·' : pos + 1} / {list.length}</span>
+          <i className="sep" />
+        </>}
         <CommentButton />
         <LaserButton />
         <i className="sep" />
-        <DevicePicker value={fill ? 'fill' : play.device} onSelect={(n) => n && setDevice(n)} includeFill hint={deviceHint} dark />
+        {!docPreset && <DevicePicker value={fill ? 'fill' : play.device} onSelect={(n) => n && setDevice(n)} includeFill hint={deviceHint} dark />}
         <ThemePicker value={play.theme} onSelect={setTheme} hint="D" dark />
         {playUpdateRevision && <>
           <i className="sep" />
@@ -485,16 +553,27 @@ function PlayInner() {
             <PanelFilledIcon size={17} style={{ transform: 'rotate(90deg)' }} />
           </button>
         </Tip>
-        <Tip side="bottom" label={<><b>Exit Prototype view</b><span>Esc</span></>}>
-          <button className="sh-pill-btn" onClick={exit}><XIcon size={14} /></button>
-        </Tip>
+        {/* the canvas door: absent on a locked board (policy) and on a frame
+            deep link (the link's chrome) - not hidden, not rendered */}
+        {!noDoor && (
+          <Tip side="bottom" label={<><b>Open in canvas</b><span>Esc</span></>}>
+            <button className="sh-pill-btn" onClick={exit}><GridIcon size={16} /></button>
+          </Tip>
+        )}
+        {BRANDING && PUBLISHED && (
+          <Tip side="bottom" label={<b>Open in app</b>}>
+            <a className="sh-pill-btn" href="https://app.marver.design" target="_blank" rel="noopener" aria-label="Open in app">
+              <BrowsersIcon size={16} />
+            </a>
+          </Tip>
+        )}
       </nav>
       <Tip side="bottom" label={<><b>Open toolbar</b><span>⌘/</span></>}>
         <button className={`sh-pill-fab${pillOpen ? ' hidden' : ''}`} onClick={() => setPillOpen(true)}
           aria-hidden={pillOpen} tabIndex={pillOpen ? -1 : 0}><PanelHollowIcon size={18} style={{ transform: 'rotate(90deg)' }} /></button>
       </Tip>
 
-      <div className="sh-play-nav">
+      {!focus && <div className="sh-play-nav">
         <Tip inv label={<><b>Restart</b><span className="k">R</span></>}>
           <button onClick={restart}><ReloadIcon size={14} /></button>
         </Tip>
@@ -523,7 +602,7 @@ function PlayInner() {
             return <Tip inv label={<b>{full}</b>}><span className="vname">{full}</span></Tip>
           })()}
         </>}
-      </div>
+      </div>}
     </div>
   )
 }

package/src/client/shell/Toolbar.tsx

@@ -8,7 +8,7 @@
  */
 import { createPortal } from 'react-dom'
 import { useEffect, useRef, useState, type ReactNode } from 'react'
-import { useStore, CONFIG, cap } from './store.ts'
+import { useStore, CONFIG, SOURCE_REVEALED, cap } from './store.ts'
 import { useComments } from './comments-store.ts'
 import { Tip } from './Tip.tsx'
 import { CaretIcon, CheckIcon, CommentIcon, DevicesIcon, EyeSlashIcon, FrameCornersIcon, LaserIcon, MoonIcon, SunIcon, deviceIcon } from './icons.tsx'
@@ -89,6 +89,9 @@ function TipRows({ rows }: { rows: [string, string][] }) {
 export function LaserButton() {
   const laser = useStore((s) => s.laser)
   const showAnchor = useComments((s) => s.showAnchor)
+  // stripped build: the paths are not in the bundle, so the button that would
+  // copy them has nothing honest to offer
+  if (!SOURCE_REVEALED) return null
   return (
     <Tip side="bottom" label={<TipRows rows={[['Laser mode', 'L'], [showAnchor ? 'Hide laser comment' : 'Show laser comment', '⇧L']]} />}>
       <button className={`sh-pill-btn${laser ? ' on' : ''}`} onClick={() => {
@@ -99,10 +102,31 @@ export function LaserButton() {
   )
 }
 
-/** Comment toggle - store-level, identical on canvas and prototype. */
+/** Comment toggle - store-level, identical on canvas and prototype.
+ *  A viewer whose role stops at view on this board sees the LOCKED capability:
+ *  the honest message ("not available for you yet") and the Ask-to-comment
+ *  path into the owner's request queue (04-solution §2.35). */
 export function CommentButton() {
   const commentMode = useComments((s) => s.commentMode)
   const show = useComments((s) => s.show)
+  const me = useComments((s) => s.me)
+  const myBoards = useComments((s) => s.myBoards)
+  const board = useStore((s) => s.board)
+  const asked = useRef(0)
+  const lockedOut = !!me && !!myBoards && myBoards[board] === 'view'
+  if (lockedOut) {
+    return (
+      <Tip side="bottom" label={<><b>Commenting is not available for you yet</b><span>click to ask the owner</span></>}>
+        <button className="sh-pill-btn" style={{ opacity: .55 }} onClick={() => {
+          const s = useStore.getState()
+          if (Date.now() - asked.current < 8000) return
+          asked.current = Date.now()
+          void commentsStore().askToComment().then((ok) =>
+            s.toast(ok ? 'asked the owner for comment access - they decide' : 'could not send the request - try again'))
+        }}><CommentIcon size={16} /></button>
+      </Tip>
+    )
+  }
   return (
     <Tip side="bottom" label={<TipRows rows={[['Comment', 'C'], [show ? 'Hide pins' : 'Show pins', '⇧C']]} />}>
       <button className={`sh-pill-btn${commentMode ? ' on' : ''}`} onClick={() => {

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

@@ -84,21 +84,11 @@ export function animateLayout(ms = 360) {
   presetTimer = window.setTimeout(() => w.classList.remove('sh-preset'), ms)
 }
 
-/** B0.2: one wheel event, whatever its origin - a shell-document wheel over the canvas, or
- *  a wheel forwarded from a passive frame's iframe. clientX/Y are shell-viewport pixels. */
-export interface CanvasWheelInput {
-  deltaX: number; deltaY: number; deltaMode: number
-  ctrlKey: boolean; metaKey: boolean; clientX: number; clientY: number
-}
-
-export const canvasCtl = {
-  fitNode(_key: string) {},
-  fitNodes(_keys: string[]) {},
-  fitAll() {},
-  zoomTo(_scale: number) {},
-  zoom100() { canvasCtl.zoomTo(1) },
-  wheel(_input: CanvasWheelInput) {},
-}
+// the control channel lives in ctl.ts so play/focus can import it without
+// dragging the canvas into a locked-shell bundle; Canvas assigns the real
+// implementations below when it mounts
+import { canvasCtl, type CanvasWheelInput } from './ctl.ts'
+export { canvasCtl, type CanvasWheelInput }
 
 /** Variant-group captions: "Landing · 3 variants" above each group with
  *  2+ members on this board. World-space (scales with the canvas); min screen size via