@marver-design/marver 0.11.0 → 0.12.0

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

package/src/client/shell/canvas/ctl.ts

@@ -0,0 +1,26 @@
+/**
+ * The canvas control channel, in its own dependency-free module.
+ *
+ * Play, Comments and App steer the camera through this object; Canvas assigns
+ * the real implementations when it mounts. Living here rather than inside
+ * Canvas.tsx keeps the play/focus surfaces importable WITHOUT the canvas - a
+ * locked-shell bundle mounts the stage chrome and the canvas code never enters
+ * it (01-sharing §5.1's all-boards rule). Before Canvas mounts (or when it
+ * never does), every call is a harmless no-op.
+ */
+
+/** 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) {},
+}

package/src/client/shell/comments-store.ts

@@ -8,13 +8,28 @@ import { create } from 'zustand'
 import { replay, type CommentEvent, type Thread } from '../../shared/events.ts'
 import { ROUTE } from '../const.ts'
 
-export interface Me { email: string; name: string; avatar?: string }
+export interface Me {
+  email: string
+  name: string
+  avatar?: string
+  /** The viewer's own opaque author id on a published canvas - what projected
+   *  events carry instead of an email. "Is this mine" compares ids first. */
+  id?: string
+}
+
+/** The author snapshot a POST carries: the canonical profile, never the opaque
+ *  id - that field is server-assigned, and the server refuses it in writes. */
+const postAuthor = (me: Me | null): { email: string; name?: string; avatar?: string } | undefined =>
+  me ? { email: me.email, name: me.name, ...(me.avatar ? { avatar: me.avatar } : {}) } : undefined
 
 interface CommentsState {
   events: CommentEvent[]              // EVERY board's log, unioned - comments are frame-scoped
   threads: Thread[]                   // derived on every change; each carries its origin board
   board: string | null
   me: Me | null                       // null on published until signed in
+  /** The viewer's effective role per board (published) - what makes a locked
+   *  capability honest: `view` on a comment board = "not available for you YET". */
+  myBoards: Record<string, string> | null
   local: boolean                      // dev mirror (identity is the local profile)
   connected: boolean                  // dev only: a connect account provides name/email (read-only here)
   commentMode: boolean                // C - picking + composing
@@ -48,6 +63,8 @@ interface CommentsState {
   claim(token: string, password: string, name: string, avatar?: string): Promise<string | null>
   saveProfile(patch: Partial<Me>): Promise<string | null>
   dismissIdentity(): void
+  /** The admitted viewer's "Ask to comment" - one request into the owner's queue. */
+  askToComment(): Promise<boolean>
 }
 
 const uuid = () => crypto.randomUUID()
@@ -145,7 +162,7 @@ export const useComments = create<CommentsState>((set, get) => {
   }
 
   return {
-    events: [], threads: [], board: null, me: null, local: false, connected: false,
+    events: [], threads: [], board: null, me: null, myBoards: null, local: false, connected: false,
     commentMode: false, show: true, showAnchor: true, active: null, draft: null, needsIdentity: false, inviteToken: null,
 
     poke(board) {
@@ -165,8 +182,16 @@ export const useComments = create<CommentsState>((set, get) => {
       else set({ board })
       const me = await api('me')
       if (me.status === 404) { apiOff = true; return }   // static serve: no comments API at all
-      if (me.ok) set({ me: me.data.user ?? null, local: !!me.data.local, connected: !!me.data.connected })
+      if (me.ok) set({
+        me: me.data.user ? { ...me.data.user, ...(me.data.id ? { id: me.data.id } : {}) } : null,
+        myBoards: me.data.boards && typeof me.data.boards === 'object' ? me.data.boards : null,
+        local: !!me.data.local, connected: !!me.data.connected,
+      })
       await fetchAll()
+      // mark-seen: the board was actually PRESENTED (load runs on open, never
+      // from the background poll), so the viewer's unread mark advances - the
+      // front door's counter moves on this and nothing else (02-home §4)
+      if (!get().local && get().me) void api('seen', { board }).catch(() => {})
     },
 
     /** Liveness: SSE on the published serve; dev has no event rail (its sync loop
@@ -228,7 +253,7 @@ export const useComments = create<CommentsState>((set, get) => {
       const ok = await get().send([{
         id: uuid(), ts: Date.now(), type: 'create', commentId: id,
         nodeKey: draft.nodeKey, frame: draft.frame, anchor: draft.anchor,
-        author: me ?? undefined, body: body.trim(),
+        author: postAuthor(me), body: body.trim(),
       }], draft.board)
       if (ok) set({ draft: null, active: id, commentMode: false })
     },
@@ -241,7 +266,7 @@ export const useComments = create<CommentsState>((set, get) => {
       const origin = get().threads.find((t) => t.id === threadId)?.board
       return get().send([{
         id: uuid(), ts: Date.now(), type: 'reply', commentId: uuid(), parentId: threadId,
-        author: get().me ?? undefined, body: body.trim(),
+        author: postAuthor(get().me), body: body.trim(),
       }], origin)
     },
 
@@ -275,20 +300,25 @@ export const useComments = create<CommentsState>((set, get) => {
       set({ me: res.data.user })
       return null
     },
+    async askToComment() {
+      const res = await api('request-access', { requestedRole: 'comment' })
+      return res.ok
+    },
   }
 })
 
 // dev-only debug handle - the canvas store exposes the same
 if (typeof window !== 'undefined' && (import.meta as any).env?.DEV) (window as any).__mvComments = useComments
 
-/** Initials + deterministic hue for avatarless authors - the whole fallback ladder. */
-export const avatarFallback = (author?: { email?: string; name?: string }) => {
+/** Initials + deterministic hue for avatarless authors - the whole fallback ladder.
+ *  Hue keys on the stable identity: email locally, the opaque id when projected. */
+export const avatarFallback = (author?: { email?: string; id?: string; name?: string }) => {
   const name = author?.name || author?.email || '?'
   // the unset dev default ("You", no account) renders in the COMMENT green - it's the mode's
   // own hue, not a fake identity color, until a real profile is set
-  if (name === 'You' && !author?.email) return { initials: 'Y', hue: 131 }
+  if (name === 'You' && !author?.email && !author?.id) return { initials: 'Y', hue: 131 }
   const initials = name.split(/\s+/).map((w) => w[0]).slice(0, 2).join('').toUpperCase()
   let h = 0
-  for (const c of (author?.email || name)) h = (h * 31 + c.charCodeAt(0)) % 360
+  for (const c of (author?.email || author?.id || name)) h = (h * 31 + c.charCodeAt(0)) % 360
   return { initials, hue: h }
 }

package/src/client/shell/hash.ts

@@ -10,6 +10,9 @@
  *   #/b/<board>?c=<id>     board with a comment thread open
  *   #/i/<token>            invite link - opens the claim dialog with the token
  *   #/p/<board>?at=<frame-id>&device=<viewport>&theme=<theme>   play mode
+ *   #/f/<frame-id>?device=&theme=   focus - one frame, full screen, no board in
+ *                                   the chrome (a frame deep link is presentation,
+ *                                   not access: 01-sharing §3.5)
  */
 
 export interface HashState {
@@ -18,6 +21,8 @@ export interface HashState {
   c?: string
   invite?: string
   play?: { at?: string; device?: string; theme?: string }
+  /** A frame deep link: lands that visit in focus, over every other rule. */
+  focus?: { at: string; device?: string; theme?: string }
 }
 
 const BOARD_RE = /^[a-z0-9][a-z0-9-]*$/
@@ -31,6 +36,13 @@ export function parseHash(hash: string = location.hash): HashState {
     const params = new URLSearchParams(q === -1 ? '' : raw.slice(q + 1))
     const mi = path.match(/^\/i\/([\w-]{8,128})$/)
     if (mi) return { invite: mi[1] }
+    // frame ids are <scene>/<name> (or bare <name>), so the f route takes the rest of the path
+    const mf = path.match(/^\/f\/(.+)$/)
+    if (mf) {
+      const at = decodeURIComponent(mf[1])
+      if (!/^[\w./-]{1,200}$/.test(at) || at.includes('..')) return {}
+      return { focus: { at, device: params.get('device') ?? undefined, theme: params.get('theme') ?? undefined } }
+    }
     const m = path.match(/^\/(b|p)\/([^/?]+)$/)
     if (!m) return {}
     const board = decodeURIComponent(m[2])
@@ -52,6 +64,13 @@ export function parseHash(hash: string = location.hash): HashState {
 }
 
 export function buildHash(s: HashState): string {
+  if (s.focus?.at) {
+    const p = new URLSearchParams()
+    if (s.focus.device) p.set('device', s.focus.device)
+    if (s.focus.theme) p.set('theme', s.focus.theme)
+    const q = p.toString()
+    return `#/f/${s.focus.at}${q ? `?${q}` : ''}`
+  }
   if (s.play?.at && s.board) {
     const p = new URLSearchParams({ at: s.play.at })
     if (s.play.device) p.set('device', s.play.device)

package/src/client/shell/icons.tsx

@@ -86,3 +86,4 @@ export function deviceIcon(name: string | null, size = 14) {
   return <Icon size={size} />
 }
 
+export const BrowsersIcon = icon(<path d="M216,40H72A16,16,0,0,0,56,56V72H40A16,16,0,0,0,24,88V200a16,16,0,0,0,16,16H184a16,16,0,0,0,16-16V184h16a16,16,0,0,0,16-16V56A16,16,0,0,0,216,40ZM184,88v16H40V88Zm0,112H40V120H184v80Zm32-32H200V88a16,16,0,0,0-16-16H72V56H216Z" />)

package/src/client/shell/store.ts

@@ -10,11 +10,28 @@ import shData from 'virtual:sh-data'
 /** Published-build data. Non-null = static site: no API, no saves, no live events.
  *  `names` is the switcher list (all-scenes only when actually published); `default`
  *  is where `/` opens - never a synthesized aggregate of a filtered build. */
-const DATA: { manifest: Manifest; boards: Record<string, unknown>; names: string[]; default: string } | null = shData
+const DATA: {
+  manifest: Manifest; boards: Record<string, unknown>; names: string[]; default: string
+  /** publish.json v2: per-board artifact type + open/lock, and the reveal flags. */
+  policy?: { boards: Record<string, { type?: string; open?: string; lock?: boolean }>; reveal?: { structure?: boolean; source?: boolean }; lockedShell?: boolean }
+} | null = shData
+
+/** Every published board is locked to a stage mode - the canvas shell is never
+ *  offered on this bundle (01-sharing §5.1's all-boards rule). */
+export const LOCKED_SHELL = DATA?.policy?.lockedShell === true
 
 /** True on a published static canvas - no dev server, no API, no update checks. */
 export const PUBLISHED = DATA !== null
 
+/** May this bundle show source paths (laser copy)? Dev always; published only
+ *  when publish.json says `reveal.source: true`. The strip already removed the
+ *  paths from the bundle - this flag removes the affordance that would show
+ *  their opaque replacements (01-sharing §6.2). */
+export const SOURCE_REVEALED = DATA ? DATA.policy?.reveal?.source === true : true
+
+/** The published per-board artifact metadata (type, open, lock). Empty in dev. */
+export const BOARD_POLICY: Record<string, { type?: string; open?: string; lock?: boolean }> = DATA?.policy?.boards ?? {}
+
 export interface FrameEntry { id: string; file: string; kind: 'tsx' | 'html'; scene: string; title?: string; viewport?: string; theme?: string; variantGroup?: string; variant?: string; intent?: string; contentWidth?: number }
 export interface Manifest { frames: FrameEntry[]; scenes: { name: string; frames: number }[] }
 export interface Node {
@@ -48,7 +65,37 @@ export interface Node {
 export interface JamNote { threadId: string; board: string; preview: string; ts: number; frame?: string; frameTitle?: string; intent?: string }
 export interface Toast { id: number; text: string; jam?: JamNote }
 
-export const CONFIG: { viewports: Record<string, { width: number; height: number }>; themes: string[]; zoomSpeed?: number; noTheme: boolean; setup?: boolean; projectName?: string } = shConfig
+export const CONFIG: { viewports: Record<string, { width: number; height: number }>; themes: string[]; zoomSpeed?: number; noTheme: boolean; setup?: boolean; projectName?: string; branding?: boolean } = shConfig
+
+/** Invariant: `branding: false` strips every Marver mention - new chrome included. */
+export const BRANDING = CONFIG.branding !== false
+
+/** The five view modes' landing map (04-solution §2.35): the artifact type picks
+ *  the default view; an explicit `open` beats it; a frame deep link beats both. */
+export function landingMode(board: string): 'canvas' | 'board' | 'present' | 'focus' | 'slides' {
+  const p = BOARD_POLICY[board]
+  if (!p) return 'canvas'
+  if (p.open && ['canvas', 'board', 'present', 'focus', 'slides'].includes(p.open)) {
+    // slides is v1.5 - until the mode exists it lands in present, its nearest kin
+    return p.open === 'slides' ? 'present' : p.open as any
+  }
+  switch (p.type) {
+    case 'doc': return 'focus'
+    case 'slides': return 'present'          // slides mode is v1.5; present until then
+    case 'design': case 'sketch': case 'refs': return 'board'
+    default: return 'canvas'
+  }
+}
+
+/** Is this board frozen to its landing mode? The lock caps disclosure - no way
+ *  out into other modes, and (published) no sidebar ever renders for it. */
+export const boardLocked = (board: string): boolean => BOARD_POLICY[board]?.lock === true
+
+/** May this board enter `mode`? A lock freezes what open pinned - a board
+ *  locked to canvas must refuse present just as one locked to present refuses
+ *  canvas. Unlocked boards enter anything. */
+export const modeAllowed = (board: string, mode: 'present' | 'focus'): boolean =>
+  !boardLocked(board) || landingMode(board) === mode
 
 export { cap, humanize } from './labels.ts'
 import { cap, humanize } from './labels.ts'
@@ -148,7 +195,11 @@ interface State {
   selection: string[]                 // ordered; last entry is the primary (bar anchor)
   interact: string | null
   viewTheme: string                   // the global theme preference; sticky across boards and reloads
-  play: { at: string; device: string; theme: string } | null   // play mode; at = current frame id
+  /** Play mode; at = current frame id. `focus` = the single-frame view (the
+   *  fourth mode): no walking, doc reading preset when the board type is doc.
+   *  `deep` = entered by a frame deep link - the chrome then carries no board
+   *  name and no canvas door (presentation default of the link, 04 §2.35). */
+  play: { at: string; device: string; theme: string; focus?: boolean; deep?: boolean } | null
   gesture: boolean                    // a frame drag/resize is in progress - canvas panning is disabled
   laser: boolean                      // laser/inspect mode: frames outline their structure
   board: string                       // active board name; 'all-scenes' is the auto board

package/src/client/shell/styles.css

@@ -856,6 +856,33 @@ body.sh-hide-ui .sh-play-nav { display: none !important }
 .sh-play-pill .sep { background: rgba(255, 255, 255, .12) }
 .sh-play-pill .bd { color: rgba(245, 245, 247, .82) }
 .sh-pill-btn.bd { width: auto; gap: 6px; padding: 0 8px 0 11px; white-space: nowrap; font-weight: 600 }
+
+/* ---- present/focus chrome (sharing v1): brand pill top-left, counter in the
+   toolbar, doc reading preset. Same glass skin as the play pill. */
+.sh-play-brand.sh-pill { left: var(--edge); right: auto; transform-origin: 22px 22px; padding: 5px 14px 5px 10px }
+.sh-play-mark { display: inline-flex; align-items: center; gap: 7px; padding: 0 2px 0 6px; color: rgba(245, 245, 247, .88) }
+.sh-play-mark svg { color: #6db3ff }
+.sh-play-mark .wd { font: 600 13px -apple-system, system-ui, sans-serif; letter-spacing: -.01em }
+.sh-play-title { font: 500 13px -apple-system, system-ui, sans-serif; color: rgba(245, 245, 247, .82);
+  max-width: 143px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; padding: 0 6px }
+.sh-play-pos { font: 500 12.5px -apple-system, system-ui, sans-serif; color: rgba(245, 245, 247, .64);
+  font-variant-numeric: tabular-nums; padding: 0 8px; white-space: nowrap }
+/* the hint pill: bottom center, the design's quiet keyboard cue */
+.sh-play-hint { position: absolute; bottom: 12px; left: 50%; transform: translateX(-50%); z-index: 31;
+  border-radius: 999px; padding: 7px 16px; white-space: nowrap;
+  background: rgba(18, 18, 24, .8); border: 1px solid rgba(255, 255, 255, .1);
+  backdrop-filter: blur(16px); -webkit-backdrop-filter: blur(16px);
+  font: 500 12px -apple-system, system-ui, sans-serif; color: rgba(245, 245, 247, .64) }
+.sh-play-hint kbd { font: 500 11.5px ui-monospace, monospace }
+body.sh-hide-ui .sh-play-hint { display: none !important }
+/* doc preset: the page IS the surface - reading column on a calm ground, no
+   device shell, natural document scrolling inside the frame */
+.sh-play.doc { background: #f4f4f6 }
+.sh-play.doc.t-dark { background: #101116 }
+.sh-play.doc .dev { --pdev-bg: #fff; box-shadow: none }
+.sh-play.doc.t-dark .dev { --pdev-bg: #0f1015 }
+/* the doc chrome floats over a LIGHT ground in light theme - the dark pill skin
+   still reads (it is glass over anything), matching the design's fixed pills */
 .sh-play-update { width: auto !important; gap: 5px; padding: 0 11px !important; font-size: 12px; font-weight: 600 }
 /* the picker dropdowns portal to .sh-app; in play they carry .sh-menu-dark for the dark skin */
 .sh-menu-dark { background: rgba(20, 20, 26, .97); border-color: rgba(255, 255, 255, .12); box-shadow: 0 12px 40px rgba(0, 0, 0, .5) }

package/src/shared/events.ts

@@ -20,7 +20,10 @@ export interface CommentEvent {
   nodeKey?: string                // a frame can sit on a board twice - comments are node-scoped
   frame?: string
   anchor?: unknown                // anchor bundle; absent = frame-level comment; on 'reanchor' = the new anchor
-  author?: { email: string; name?: string; avatar?: string }
+  /** Canonical logs carry the email; the browser DTO replaces it with `id`, an
+   *  opaque per-canvas HMAC of it (01-sharing §7.5) - a member's address never
+   *  travels to another viewer's browser. Exactly one of the two is present. */
+  author?: { email?: string; id?: string; name?: string; avatar?: string }
   body?: string                   // plain text in v1
   emoji?: string                  // react events
   addressedIn?: string            // resolve events: the variant frame that answered
@@ -103,9 +106,11 @@ export function replay(events: CommentEvent[]): Thread[] {
         break
       }
       case 'react': {
-        // toggle keyed on comment+author+emoji: present removes, absent adds
+        // toggle keyed on comment+author+emoji: present removes, absent adds.
+        // The key is the opaque id when the transport is projected, the email
+        // when it is canonical - one store only ever sees one kind.
         const t = ev.commentId ? threads.get(ev.commentId) : undefined
-        const who = ev.author?.email
+        const who = ev.author?.id ?? ev.author?.email
         if (!t || !who || !ev.emoji) break
         const users = (t.reactions[ev.emoji] ??= [])
         const at = users.indexOf(who)