@marver-design/marver 0.12.0 → 0.14.0

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

@@ -6,6 +6,8 @@
  */
 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 {
@@ -36,6 +38,9 @@ interface CommentsState {
   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
@@ -68,6 +73,9 @@ interface CommentsState {
 }
 
 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 : {
@@ -118,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
@@ -131,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. */
@@ -163,6 +208,7 @@ export const useComments = create<CommentsState>((set, get) => {
 
   return {
     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) {
@@ -250,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: postAuthor(me), body: body.trim(),
+        author: postAuthor(me), body: body.trim(), ...(mentions ? { mentions } : {}),
       }], draft.board)
       if (ok) set({ draft: null, active: id, commentMode: false })
     },
@@ -264,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: postAuthor(get().me), body: body.trim(),
+        author: postAuthor(get().me), body: body.trim(), ...(mentions ? { mentions } : {}),
       }], origin)
     },
 
@@ -278,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
 

package/src/client/shell/hash.ts

@@ -20,7 +20,7 @@ export interface HashState {
   n?: string[]
   c?: string
   invite?: string
-  play?: { at?: string; device?: string; theme?: string }
+  play?: { at?: string; device?: string; theme?: string; slides?: boolean }
   /** A frame deep link: lands that visit in focus, over every other rule. */
   focus?: { at: string; device?: string; theme?: string }
 }
@@ -58,6 +58,7 @@ export function parseHash(hash: string = location.hash): HashState {
         at: params.get('at') ?? undefined,
         device: params.get('device') ?? undefined,
         theme: params.get('theme') ?? undefined,
+        ...(params.get('slides') === '1' ? { slides: true } : {}),
       },
     }
   } catch { return {} }   // a malformed hash (#/b/%) is a default view, never a crash
@@ -75,6 +76,7 @@ export function buildHash(s: HashState): string {
     const p = new URLSearchParams({ at: s.play.at })
     if (s.play.device) p.set('device', s.play.device)
     if (s.play.theme) p.set('theme', s.play.theme)
+    if (s.play.slides) p.set('slides', '1')
     return `#/p/${s.board}?${p}`
   }
   if (!s.board || (s.board === 'all-scenes' && !s.n?.length && !s.c)) return '#/'

package/src/client/shell/icons.tsx

@@ -71,6 +71,8 @@ export function IntentGlyph({ intent, size = 14, ...rest }: IconProps & { intent
     : ContentBlocksIcon
   return <I size={size} role="img" aria-hidden={false} aria-label={intent} {...({ title: intent } as object)} {...rest} />
 }
+/** The slide badge (v1.5): a 16:9 stage with the play wedge - a deck frame. */
+export const SlideFrameIcon = icon(<path d="M192,48H64A16,16,0,0,0,48,64V192a16,16,0,0,0,16,16H192a16,16,0,0,0,16-16V64A16,16,0,0,0,192,48Zm0,144H64V64H192V192ZM240,56V200a8,8,0,0,1-16,0V56a8,8,0,0,1,16,0ZM32,56V200a8,8,0,0,1-16,0V56a8,8,0,0,1,16,0Z" />)
 export const PanelHollowIcon = icon(<><rect x="32" y="48" width="192" height="160" rx="32" fill="none" stroke="currentColor" strokeWidth="16" /><rect x="72" y="88" width="48" height="80" rx="24" fill="none" stroke="currentColor" strokeWidth="14" /></>)
 /** Board glyphs: CardsThree = the built-in `all-scenes` board; Cards = curated boards. */
 export const CardsThreeIcon = icon(<path d="M208,88H48a16,16,0,0,0-16,16v96a16,16,0,0,0,16,16H208a16,16,0,0,0,16-16V104A16,16,0,0,0,208,88Zm0,112H48V104H208v96ZM48,64a8,8,0,0,1,8-8H200a8,8,0,0,1,0,16H56A8,8,0,0,1,48,64ZM64,32a8,8,0,0,1,8-8H184a8,8,0,0,1,0,16H72A8,8,0,0,1,64,32Z" />)

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/play-order.ts

@@ -0,0 +1,22 @@
+/** The deck order (v1.5), pure: slide tsx frames in the board's reading
+ *  order - (y, then x, then original index), deduped by frame id. Excluded
+ *  frames come back for a ONE-TIME warning at entry; this file stays
+ *  dependency-free so unit tests import it without React or virtual modules. */
+export interface OrderNode { frame: string; x: number; y: number; missing?: boolean }
+export interface OrderFrame { id: string; kind: 'tsx' | 'html'; slide?: boolean }
+
+export function deckOrder(
+  nodes: OrderNode[], frames: Map<string, OrderFrame>,
+): { deck: string[]; excluded: string[] } {
+  const rows = nodes
+    .map((n, i) => ({ n, i, f: frames.get(n.frame) }))
+    .filter(({ n, f }) => !n.missing && !!f)
+  const excluded = rows.filter(({ f }) => f!.kind !== 'tsx' || !f!.slide).map(({ f }) => f!.id)
+  const seen = new Set<string>()
+  const deck = rows
+    .filter(({ f }) => f!.kind === 'tsx' && !!f!.slide)
+    .sort((a, b) => a.n.y - b.n.y || a.n.x - b.n.x || a.i - b.i)
+    .filter(({ n }) => !seen.has(n.frame) && (seen.add(n.frame), true))
+    .map(({ n }) => n.frame)
+  return { deck, excluded: [...new Set(excluded)] }
+}

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

@@ -1,5 +1,5 @@
 import { create } from 'zustand'
-import { ROUTE } from '../const.ts'
+import { ROUTE, slideSize } from '../const.ts'
 import { tidy, parseLayout, type BoardLayout } from './tidy.ts'
 import { stableNodeKey } from './keys.ts'
 // @ts-expect-error virtual module provided by the plugin
@@ -30,9 +30,18 @@ export const PUBLISHED = DATA !== null
 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 const BOARD_POLICY: Record<string, { type?: string; open?: string; lock?: boolean; transition?: string; chrome?: string }> = 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 { SLIDE_INTRINSIC } from '../const.ts'
+
+/** Dev-only hydration: the shell loads the repo's publish.json boards so an
+ *  author previews slides mode exactly as viewers will get it. Published
+ *  builds carry the policy inline and never call this. */
+export function hydrateBoardPolicy(boards: Record<string, { type?: string; open?: string; lock?: boolean; transition?: string; chrome?: string }>) {
+  for (const [k, v] of Object.entries(boards)) if (!BOARD_POLICY[k]) BOARD_POLICY[k] = v
+}
+
+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; slide?: boolean }
 export interface Manifest { frames: FrameEntry[]; scenes: { name: string; frames: number }[] }
 export interface Node {
   key: string; frame: string; x: number; y: number; w: number; h: number
@@ -60,9 +69,16 @@ 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; branding?: boolean } = shConfig
@@ -76,17 +92,24 @@ export function landingMode(board: string): 'canvas' | 'board' | 'present' | 'fo
   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
+    return p.open as any
   }
   switch (p.type) {
     case 'doc': return 'focus'
-    case 'slides': return 'present'          // slides mode is v1.5; present until then
+    case 'slides': return 'slides'
     case 'design': case 'sketch': case 'refs': return 'board'
     default: return 'canvas'
   }
 }
 
+/** Does this board PLAY as a deck? A `type: slides` board is a deck whatever
+ *  its landing (`open: canvas` only says where viewers arrive) - the P key and
+ *  the play button route here, never through landingMode. */
+export function playsAsSlides(board: string): boolean {
+  const p = BOARD_POLICY[board]
+  return p?.type === 'slides' || p?.open === 'slides'
+}
+
 /** 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
@@ -94,7 +117,7 @@ export const boardLocked = (board: string): boolean => BOARD_POLICY[board]?.lock
 /** 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 =>
+export const modeAllowed = (board: string, mode: 'present' | 'focus' | 'slides'): boolean =>
   !boardLocked(board) || landingMode(board) === mode
 
 export { cap, humanize } from './labels.ts'
@@ -166,6 +189,11 @@ const manifestKey = (m: Manifest) => JSON.stringify(m.frames)   // any change co
 const measuredHeights = new Map<string, number>()
 
 function defaultSize(frame: FrameEntry) {
+  // the precedence chain (spec 09 slice 1): slide intrinsic → authored
+  // viewport → content sizing → default (one helper, shared with shot) -
+  // the Slide root renders fixed 1280×720, so nothing may size it smaller
+  const sl = slideSize(frame)
+  if (sl) return { w: sl.width, h: sl.height }
   // content frames: own width from Doc layout; height from the latest
   // measurement at that width, or a placeholder until sh:measure lands.
   // meta.viewport, when declared, wins - the existing precedence.
@@ -199,7 +227,7 @@ interface State {
    *  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
+  play: { at: string; device: string; theme: string; focus?: boolean; deep?: boolean; slides?: 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
@@ -1029,7 +1057,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);
@@ -734,22 +736,6 @@ body.sh-commenting .sh-lean { opacity: 0 }
 .sh-play-chip:hover { color: #f5f5f7 }
 .sh-play-chip.idle { opacity: 0; pointer-events: none; transform: scale(.6) }
 
-/* the H coach bubble: hairline, translucent, teaches the way back from immersive mode.
-   Same pill geometry and separators as the bar it stands in for. */
-.sh-play-hint { position: absolute; top: 14px; right: 16px; display: flex; align-items: center; gap: 3px;
-  padding: 4px 4px 4px 14px; border-radius: 999px;
-  background: rgba(18, 18, 24, .6); border: 1px solid rgba(255, 255, 255, .14);
-  backdrop-filter: blur(16px); -webkit-backdrop-filter: blur(16px);
-  font: 500 12px -apple-system, system-ui, sans-serif; color: rgba(245, 245, 247, .85);
-  animation: sh-play-in .3s ease-out }
-.sh-play-hint .sep { width: 1px; height: 16px; background: rgba(255, 255, 255, .14); margin: 0 8px }
-.sh-play-hint kbd { font: 600 11px -apple-system, system-ui, sans-serif; padding: 1px 6px; border-radius: 5px;
-  background: rgba(255, 255, 255, .12); border: 1px solid rgba(255, 255, 255, .16) }
-.sh-play-hint button { height: 30px; padding: 0 12px; border: 0; border-radius: 999px; cursor: pointer;
-  font: 600 11px -apple-system, system-ui, sans-serif; background: rgba(255, 255, 255, .14); color: #f5f5f7 }
-.sh-play-hint button:hover { background: rgba(255, 255, 255, .22) }
-.sh-play-hint button.dim { background: transparent; color: rgba(245, 245, 247, .5); font-weight: 500 }
-.sh-play-hint button.dim:hover { color: rgba(245, 245, 247, .8); background: rgba(255, 255, 255, .08) }
 
 /* ---- Focus: silent for pointer + shortcut use; ONE branded inset ring, and only while
    the user is actually Tab-navigating (body.sh-kbd, armed by Tab, disarmed by pointer).
@@ -859,22 +845,19 @@ body.sh-hide-ui .sh-play-nav { display: none !important }
 
 /* ---- 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) }
+/* the brand pill matches the toolbar pill to the pixel: the SAME .sh-pill
+   padding (5px) and the SAME 34px inner height as .sh-pill-btn - its two
+   children are sized like buttons, so text metrics never set the height */
+.sh-play-brand.sh-pill { left: var(--edge); right: auto; transform-origin: 22px 22px; padding: 5px 9px 5px 5px }
+.sh-play-mark { display: inline-flex; align-items: center; gap: 7px; height: 34px; padding: 0 8px 0 10px; border-radius: 999px;
+  color: rgba(245, 245, 247, .88); text-decoration: none; cursor: pointer }
+.sh-play-mark:hover { background: rgba(255, 255, 255, .1); color: #f5f5f7 }
 .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);
+.sh-play-title { display: inline-block; height: 34px; line-height: 34px; font: 500 13px/34px -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 }
@@ -1121,6 +1104,21 @@ body.sh-hide-ui .sh-play-hint { 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% }
@@ -1208,3 +1206,36 @@ body.sh-hide-ui .sh-play-hint { 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 }
+
+/* v1.5 slides mode: the slim progress strip + the zero-chrome escape hatch */
+.sh-slides-strip { position: fixed; left: 50%; bottom: 14px; transform: translateX(-50%); z-index: 30;
+  display: flex; align-items: center; gap: 10px; padding: 8px 14px; border-radius: 999px;
+  background: var(--glass); border: 1px solid var(--glass-brd); backdrop-filter: var(--blur); -webkit-backdrop-filter: var(--blur) }
+.sh-slides-strip .n { font: 600 12px/1 -apple-system, system-ui, sans-serif; color: var(--glass-ink-2); white-space: nowrap }
+.sh-slides-strip .bar { width: 140px; height: 3px; border-radius: 999px; background: var(--glass-hover); overflow: hidden }
+.sh-slides-strip .bar i { display: block; height: 100%; border-radius: inherit; background: var(--accent); transition: width .25s ease }
+@media (max-width: 480px) { .sh-slides-strip .bar { width: 80px } }