@marver-design/marver 0.11.1 → 0.13.0

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

@@ -6,21 +6,41 @@
  */
 import { create } from 'zustand'
 import { replay, type CommentEvent, type Thread } from '../../shared/events.ts'
+import { mentionPeople, mentionsIn } from './mentions.ts'
+import { playPing } from './sound.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
   show: boolean                       // Shift+C - pins visible at all
   showAnchor: boolean                 // Shift+L - light the tagged ELEMENT while its thread is open
   active: string | null               // open thread id
+  /** threadId -> when I last opened it; feeds the mention-alert pulse. This
+   *  browser only (localStorage) - a per-person server mark is v1.2 territory. */
+  mentionSeen: Record<string, number>
   // picked, composing. `board` is captured at pick time - the write must land in the
   // log of the board the user was LOOKING at, however long the composer stays open
   draft: { nodeKey: string; frame: string; anchor: unknown; board?: string } | null
@@ -48,9 +68,14 @@ 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()
+const loadMentionSeen = (): Record<string, number> => {
+  try { return JSON.parse(localStorage.getItem('mv-mention-seen') ?? '{}') } catch { return {} }
+}
 const csrf = () => /(?:^|;\s*)mv_c=([\w-]+)/.exec(document.cookie)?.[1] ?? ''
 const api = async (path: string, body?: unknown) => {
   const res = await fetch(`${ROUTE}/api/${path}`, body === undefined ? undefined : {
@@ -101,6 +126,41 @@ export const useComments = create<CommentsState>((set, get) => {
       }
     })
   }
+  // A HUMAN's fresh comment that concerns me raises the same pill the agent
+  // gets, person-first: a mention of me anywhere, or a reply in a thread I am
+  // part of. Same freshness rules as notifyAgent; one ping per batch, not per
+  // event - a burst must not become a drum roll.
+  const notifyHuman = (fresh: CommentEvent[]) => {
+    const me = get().me
+    if (!me) return
+    const isMe = (a?: { id?: string; email?: string }) =>
+      !!a && ((!!a.id && a.id === me.id) || (!!a.email && !!me.email && a.email.toLowerCase() === me.email.toLowerCase()))
+    const news = fresh.filter((e) => !e.agent && (e.type === 'create' || e.type === 'reply') && e.author && !isMe(e.author))
+    if (!news.length) return
+    const notes: { e: CommentEvent; kind: 'mention' | 'reply' }[] = []
+    for (const e of news) {
+      if ((e.mentions ?? []).some((m) => isMe(m))) { notes.push({ e, kind: 'mention' }); continue }
+      if (e.type !== 'reply' || !e.parentId) continue
+      const t = get().threads.find((t) => t.id === e.parentId)
+      const mine = !!t && (isMe(t.author) || t.replies.some((r) => r.id !== e.commentId && isMe(r.author)))
+      if (mine) notes.push({ e, kind: 'reply' })
+    }
+    if (!notes.length) return
+    playPing()
+    void import('./store.ts').then(({ useStore }) => {
+      const s = useStore.getState()
+      for (const { e, kind } of notes) {
+        const threadId = e.type === 'reply' ? e.parentId! : e.commentId!
+        const t = get().threads.find((t) => t.id === threadId)
+        const entry = t?.frame ? s.manifest?.frames.find((f) => f.id === t.frame) : undefined
+        s.jamToast({
+          threadId, board: t?.board ?? e.board ?? get().board ?? '', ts: e.ts, kind, author: e.author,
+          preview: (e.body ?? '').replace(/\s+/g, ' ').slice(0, 90),
+          frame: t?.frame, frameTitle: entry?.title ?? t?.frame, intent: entry?.intent,
+        })
+      }
+    })
+  }
   // events are append-only everywhere, so union is ALWAYS safe - the one rule is the
   // baseline, PER BOARD: a board's first successful read must never replay its history
   // as notifications (the switcher list can arrive after the first sweep, so a global
@@ -114,7 +174,9 @@ export const useComments = create<CommentsState>((set, get) => {
     const fresh = events.filter((e) => !have.has(key(e)) && (have.add(key(e)), true))
     if (!fresh.length) return
     set(derive([...get().events, ...fresh]))
-    notifyAgent(fresh.filter((e) => (e.board && baselinedBoards.has(e.board)) || e.ts > bootTs))
+    const news = fresh.filter((e) => (e.board && baselinedBoards.has(e.board)) || e.ts > bootTs)
+    notifyAgent(news)
+    notifyHuman(news)
   }
   /** Legacy logs (0.8.0 clients never sent `board`) get it from the endpoint they came
    *  from - without it, replies to their threads would route to whatever board is open. */
@@ -145,7 +207,8 @@ 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,
+    mentionSeen: loadMentionSeen(),
     commentMode: false, show: true, showAnchor: true, active: null, draft: null, needsIdentity: false, inviteToken: null,
 
     poke(board) {
@@ -165,8 +228,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
@@ -225,10 +296,11 @@ export const useComments = create<CommentsState>((set, get) => {
       const { draft, me } = get()
       if (!draft || !body.trim()) return
       const id = uuid()
+      const mentions = mentionsIn(body.trim(), mentionPeople(get().events, me ?? undefined))
       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(), ...(mentions ? { mentions } : {}),
       }], draft.board)
       if (ok) set({ draft: null, active: id, commentMode: false })
     },
@@ -239,9 +311,10 @@ export const useComments = create<CommentsState>((set, get) => {
       // route to the thread's ORIGIN log - the viewer may be reading it from another
       // board (frame-scoped display); a reply landing in the wrong log would fork it
       const origin = get().threads.find((t) => t.id === threadId)?.board
+      const mentions = mentionsIn(body.trim(), mentionPeople(get().events, get().me ?? undefined))
       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(), ...(mentions ? { mentions } : {}),
       }], origin)
     },
 
@@ -253,7 +326,14 @@ export const useComments = create<CommentsState>((set, get) => {
     setMode(on) { set({ commentMode: on, ...(on ? { show: true } : { draft: null }) }) },
     setShow(show) { set({ show }) },
     setShowAnchor(showAnchor) { set({ showAnchor }) },
-    setActive(active) { set({ active }) },
+    setActive(active) {
+      // opening a thread is SEEING it - the mention pulse for it stops here
+      if (active) {
+        const mentionSeen = { ...get().mentionSeen, [active]: Date.now() }
+        try { localStorage.setItem('mv-mention-seen', JSON.stringify(mentionSeen)) } catch { /* private mode */ }
+        set({ active, mentionSeen })
+      } else set({ active })
+    },
     setDraft(draft) { set({ draft: draft ? { ...draft, board: draft.board ?? get().board ?? undefined } : null }) },
     dismissIdentity() { set({ needsIdentity: false }) },   // inviteToken survives dismissal - commenting later reopens the claim
 
@@ -275,20 +355,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/mentions.ts

@@ -1,7 +1,13 @@
 /**
- * @marver mention parsing - pure, so the rendering is unit-testable without
+ * Mention parsing - pure, so the rendering is unit-testable without
  * pulling the whole comment UI (and its virtual:sh-config) into the test.
+ *
+ * Two kinds live in a body: `@marver` (the Live Jam trigger, reserved) and
+ * person mentions (`@Display Name`, sharing v1.1). ONE segmentation drives
+ * highlighting AND the mentions array a send derives - what lights up is
+ * exactly what notifies.
  */
+import type { CommentEvent, Mention } from '../../shared/events.ts'
 
 /** Split a comment body into plain text and @marver mention segments (case-insensitive, word-bounded). */
 export function parseMentions(body: string): { text: string; mention: boolean }[] {
@@ -16,3 +22,104 @@ export function parseMentions(body: string): { text: string; mention: boolean }[
   if (last < body.length) out.push({ text: body.slice(last), mention: false })
   return out.length ? out : [{ text: body, mention: false }]
 }
+
+/** Someone the composer may name: a distinct author (or past mention target)
+ *  seen in this canvas's events. `id` on a published canvas (the projected
+ *  transport), `email` in dev (canonical) - exactly what the event will carry. */
+export interface MentionPerson { label: string; id?: string; email?: string; avatar?: string }
+
+const personKey = (p: { id?: string; email?: string }) => p.id ? `i:${p.id}` : `e:${p.email?.toLowerCase()}`
+
+/** The mentionable set: named humans from the event log, first-seen order,
+ *  minus the viewer themself and the reserved agent NAMESPACE - any label
+ *  STARTING with the word "marver" is out, because the Live Jam daemon's own
+ *  watcher sees `@marver` inside `@Marver Team` and would run the agent. */
+export function mentionPeople(events: CommentEvent[], self?: { id?: string; email?: string }): MentionPerson[] {
+  const seen = new Map<string, MentionPerson>()
+  const selfKey = self && (self.id || self.email) ? personKey(self) : null
+  const add = (a?: { id?: string; email?: string; name?: string; avatar?: string }, label?: string) => {
+    const name = (label ?? a?.name)?.trim()
+    if (!a || (!a.id && !a.email) || !name || /^marver\b/i.test(name)) return
+    const k = personKey(a)
+    if (k !== selfKey && !seen.has(k)) seen.set(k, { label: name, id: a.id, email: a.email, avatar: a.avatar })
+  }
+  for (const ev of events) {
+    if (!ev.agent && (ev.type === 'create' || ev.type === 'reply')) add(ev.author)
+    for (const m of ev.mentions ?? []) add(m, m.label)
+  }
+  return [...seen.values()]
+}
+
+export type BodySegment = { text: string; marver?: boolean; person?: MentionPerson }
+
+const escapeRe = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+/** Segment a body against the known people: `@Label` runs (longest label wins
+ *  at each position, case-insensitive, trailing-boundary-guarded, and only at
+ *  a mention START - after whitespace, an opener, or the beginning; `foo@Sam`
+ *  is an address shape, not a mention, exactly the rule the typeahead uses)
+ *  plus `@marver` (whose namespace mentionPeople already reserves). */
+export function parseBody(body: string, people: MentionPerson[]): BodySegment[] {
+  if (!people.length) return parseMentions(body).map((s) => (s.mention ? { text: s.text, marver: true } : { text: s.text }))
+  const byLength = [...people].sort((a, b) => b.label.length - a.label.length)
+  const alts = byLength.map((p) => `${escapeRe(p.label)}(?![\\w])`)
+  alts.push('marver\\b')
+  const pattern = new RegExp(`(?<=^|[\\s(])@(?:${alts.join('|')})`, 'gim')
+  const out: BodySegment[] = []
+  let last = 0
+  for (const m of body.matchAll(pattern)) {
+    const i = m.index ?? 0
+    if (i > last) out.push({ text: body.slice(last, i) })
+    const hit = m[0].slice(1)
+    if (/^marver$/i.test(hit)) out.push({ text: m[0], marver: true })
+    else out.push({ text: m[0], person: byLength.find((p) => p.label.toLowerCase() === hit.toLowerCase()) })
+    last = i + m[0].length
+  }
+  if (last < body.length) out.push({ text: body.slice(last) })
+  return out.length ? out : [{ text: body }]
+}
+
+/** The mentions a body carries, in event form - derived from the SAME
+ *  segmentation the highlight uses: what lights up is what notifies. ≤ 8,
+ *  the validator's cap. An ambiguous label (two people wearing the same
+ *  display name) mentions EVERY bearer - deterministic and stateless, where
+ *  remembering which twin was picked would depend on hidden composer state. */
+export function mentionsIn(body: string, people: MentionPerson[]): Mention[] | undefined {
+  const out = new Map<string, Mention>()
+  const hit = new Set([...parseBody(body, people)].flatMap((s) => (s.person ? [s.person.label.toLowerCase()] : [])))
+  for (const p of people) {
+    if (out.size >= 8) break
+    if (hit.has(p.label.toLowerCase()))
+      out.set(personKey(p), p.id ? { id: p.id, label: p.label } : { email: p.email, label: p.label })
+  }
+  return out.size ? [...out.values()] : undefined
+}
+
+/** The @-token the caret sits in, for the typeahead: `@` + a partial name
+ *  (letters, spaces) immediately before `caret`, not already a completed
+ *  mention. Null when the caret is not in one. */
+export function mentionQueryAt(text: string, caret: number): { start: number; query: string } | null {
+  const upto = text.slice(0, caret)
+  const m = /(^|[\s(])@([^@\n]{0,40})$/.exec(upto)
+  if (!m) return null
+  return { start: (m.index ?? 0) + m[1].length, query: m[2] }
+}
+
+/** Thread ids holding a mention of ME newer than my seen mark - what the pin
+ *  pulse and unread ring key on. Pure; the store persists `seen` per thread. */
+export function mentionAlerts(
+  events: CommentEvent[], me: { id?: string; email?: string } | null | undefined,
+  seen: Record<string, number>,
+): string[] {
+  if (!me || (!me.id && !me.email)) return []
+  const mine = (m: Mention) =>
+    (!!m.id && m.id === me.id) || (!!m.email && !!me.email && m.email.toLowerCase() === me.email.toLowerCase())
+  const out = new Set<string>()
+  for (const ev of events) {
+    if (ev.type !== 'create' && ev.type !== 'reply') continue
+    if (!(ev.mentions ?? []).some(mine)) continue
+    const thread = ev.type === 'reply' ? ev.parentId : ev.commentId
+    if (thread && ev.ts > (seen[thread] ?? 0)) out.add(thread)
+  }
+  return [...out]
+}

package/src/client/shell/sound.ts

@@ -0,0 +1,32 @@
+/**
+ * The notification ping - two soft sine tones, generated, no asset to load.
+ * Autoplay policy makes this best-effort by nature: the context only runs
+ * after the person has interacted with the page (they are ON the canvas, so
+ * in practice it plays). Every failure path is silence, never an error.
+ */
+let ctx: AudioContext | null = null
+
+export function playPing(): void {
+  try {
+    ctx ??= new AudioContext()
+    if (ctx.state === 'suspended') {
+      // resume() only sticks inside a user gesture; fire-and-forget - if the
+      // browser refuses, this ping is silent and the NEXT one plays
+      void ctx.resume().catch(() => {})
+      if (ctx.state === 'suspended') return
+    }
+    const t0 = ctx.currentTime
+    for (const [freq, at, dur] of [[880, 0, .09], [1174.7, .09, .16]] as const) {
+      const osc = ctx.createOscillator()
+      const gain = ctx.createGain()
+      osc.type = 'sine'
+      osc.frequency.value = freq
+      gain.gain.setValueAtTime(0, t0 + at)
+      gain.gain.linearRampToValueAtTime(.14, t0 + at + .015)
+      gain.gain.exponentialRampToValueAtTime(.0001, t0 + at + dur)
+      osc.connect(gain).connect(ctx.destination)
+      osc.start(t0 + at)
+      osc.stop(t0 + at + dur + .02)
+    }
+  } catch { /* no audio here - fine */ }
+}

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 {
@@ -43,12 +60,49 @@ export interface Node {
    *  on every fresh navigation. */
   readyRetried?: boolean
 }
-/** A Live Jam notification: a persistent bottom-right glass pill for a Marver
- *  reply. Frame-first: the FRAME is the news (icon + title, blue), Marver + preview below. */
-export interface JamNote { threadId: string; board: string; preview: string; ts: number; frame?: string; frameTitle?: string; intent?: string }
+/** A comment notification: a persistent bottom-right glass pill. Three kinds
+ *  share it - a Marver (agent) reply renders frame-first with the mark; a
+ *  human `mention`/`reply` renders person-first: their avatar, "«name»
+ *  mentioned you" / "«name» replied", the message underneath. */
+export interface JamNote {
+  threadId: string; board: string; preview: string; ts: number
+  frame?: string; frameTitle?: string; intent?: string
+  kind?: 'mention' | 'reply'                      // absent = the agent pill
+  author?: { name?: string; avatar?: string; id?: string; email?: 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 +202,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
@@ -978,7 +1036,8 @@ export const useStore = create<State>((set, get) => {
      *  supersedes), capped so the stack stays small. */
     jamToast(note) {
       const id = ++toastSeq
-      set((s) => ({ toasts: [...s.toasts.filter((t) => t.jam?.threadId !== note.threadId), { id, text: 'Marver replied', jam: note }].slice(-8) }))
+      const text = note.kind === 'mention' ? 'You were mentioned' : note.kind === 'reply' ? 'New reply' : 'Marver replied'
+      set((s) => ({ toasts: [...s.toasts.filter((t) => t.jam?.threadId !== note.threadId), { id, text, jam: note }].slice(-8) }))
     },
     dismissToast(id) { set((s) => ({ toasts: s.toasts.filter((t) => t.id !== id) })) },
     clearJamToasts() { set((s) => ({ toasts: s.toasts.filter((t) => !t.jam) })) },

package/src/client/shell/styles.css

@@ -7,6 +7,7 @@
   --accent: #0088ff; --accent-ring: rgba(0, 136, 255, .2); --beam: rgba(0, 136, 255, .42); --beam-blur: 6px; --beam-bottom: -13px; --beam-h: 12px; --beam-inset: 12%; --edge-accent: rgba(0, 136, 255, .8); --inner-tint: rgba(0, 136, 255, .13); --tip-bg: #18181b; --tip-ink: #fafafa; --accent-wash: rgba(0, 136, 255, .07);
 
   --glass: rgba(255, 255, 255, .64);
+  --solid: #ffffff;
   --glass-brd: rgba(24, 24, 27, .1);
   --glass-ink: #18181b;
   --glass-ink-2: rgba(24, 24, 27, .66);
@@ -46,6 +47,7 @@
   --accent: #0088ff; --accent-ring: rgba(0, 136, 255, .32); --beam: rgba(0, 136, 255, .5); --beam-blur: 3px; --beam-bottom: -13px; --beam-h: 16px; --beam-inset: 20%; --edge-accent: rgba(92, 179, 255, .85); --inner-tint: rgba(92, 179, 255, .16); --tip-bg: #f4f4f5; --tip-ink: #18181b; --accent-wash: rgba(0, 136, 255, .14);
 
   --glass: rgba(12, 12, 17, .72);
+  --solid: #17171b;
   --glass-brd: rgba(255, 255, 255, .16);
   --glass-ink: #f5f5f7;
   --glass-ink-2: rgba(245, 245, 247, .64);
@@ -856,6 +858,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) }
@@ -1094,6 +1123,21 @@ body.sh-hide-ui .sh-play-nav { display: none !important }
 .cm-hl .cm-at { font-weight: inherit; -webkit-text-stroke: .4px currentColor }
 .cm-at-tip { display: block; max-width: 220px; line-height: 1.4 }
 
+/* v1.1: @Person mentions - the comment accent, medium weight (the mirror rule above
+   already keeps composer metrics honest: color + stroke only, never font-weight). */
+.cm-at.person { color: var(--cm-line, var(--comment)); font-weight: 600 }
+.cm-hl .cm-at.person { font-weight: inherit }
+/* The typeahead: a small glass list ABOVE the composer; rows follow the pick. */
+/* SOLID, never glass: the picker floats over thread text, and translucency
+   made the names unreadable */
+.cm-mentionlist { position: absolute; bottom: calc(100% + 6px); left: 0; z-index: 5; min-width: 180px; max-width: 260px;
+  display: flex; flex-direction: column; padding: 4px; border-radius: 10px;
+  background: var(--solid); border: 1px solid var(--glass-brd); box-shadow: 0 10px 28px rgba(0,0,0,.22) }
+.cm-mentionlist button { display: flex; align-items: center; gap: 8px; padding: 6px 8px; border: 0; border-radius: 7px;
+  background: none; color: var(--glass-ink); font: 500 12.5px/1.2 inherit; text-align: left; cursor: pointer; white-space: nowrap }
+.cm-mentionlist button span { overflow: hidden; text-overflow: ellipsis }
+.cm-mentionlist button.on { background: var(--glass-hover) }
+
 /* Marver identity: the agent's avatar mark + provenance tooltip (§7). Always accent, never a hue. */
 .cm-avatar.cm-marver { background: var(--mv-blue); color: rgba(255,255,255,.9); cursor: default }   /* white/90 mark, embedded in the accent */
 .cm-marver-wrap { display: inline-flex; border-radius: 50% }
@@ -1181,3 +1225,27 @@ body.sh-hide-ui .sh-play-nav { display: none !important }
    its children (pins, cards, stacks) fully interactive */
 .cm-layer { position: absolute; left: 0; width: 100%; pointer-events: none; z-index: 25 }
 .cm-layer > * { pointer-events: auto }
+
+/* v1.1: an unseen mention of YOU pulses the pin - accent lights until the
+   thread is opened (opening marks it seen). Motion-reduced readers keep a
+   steady accent ring instead of the pulse. */
+.cm-pin.mention, .cm-stack.mention { outline: 2px solid var(--accent); outline-offset: 1px;
+  animation: cm-mention-pulse 1.7s ease-out infinite }
+@keyframes cm-mention-pulse {
+  0% { box-shadow: 0 0 0 0 var(--accent-ring), 0 0 0 0 rgba(0, 136, 255, .45) }
+  70% { box-shadow: 0 0 0 6px rgba(0, 136, 255, 0), 0 0 0 12px rgba(0, 136, 255, 0) }
+  100% { box-shadow: 0 0 0 0 rgba(0, 136, 255, 0), 0 0 0 0 rgba(0, 136, 255, 0) }
+}
+@media (prefers-reduced-motion: reduce) {
+  .cm-pin.mention, .cm-stack.mention { animation: none }
+}
+/* a mention of YOU inside a thread: the loudest chip - accent, heavier */
+.cm-at.person.me { color: var(--accent); font-weight: 700 }
+
+/* human notification pill: the author's face, then "name mentioned you".
+   The face outsizes the agent mark (34px) on purpose - a person is the news. */
+.sh-jam-ava { width: 36px; height: 36px; border-radius: 999px; object-fit: cover; flex: none }
+.sh-jam-ava.init { display: inline-flex; align-items: center; justify-content: center;
+  color: rgba(255,255,255,.92); font: 700 13px/1 -apple-system, system-ui, sans-serif; letter-spacing: .02em }
+/* the title row is flex, which swallows the JSX whitespace - the verb carries its own gap */
+.sh-jam-frame .v { color: var(--glass-ink-2); font-weight: 500; margin-left: 4px; flex: none }