@marver-design/marver 0.12.0 → 0.13.0

package/dist/{share-C64b1tdN.mjs → share-Gqo_Ygqw.mjs}

@@ -1,6 +1,6 @@
 import { n as NAME } from "./cli.mjs";
 import { M as resolveAccess } from "./auth-DdUKeVKt.mjs";
-import { i as loadCollab } from "./sync-WYxDN9IT.mjs";
+import { i as loadCollab } from "./sync-BZaCWqK-.mjs";
 //#region src/cli/share.ts
 /**
 * `marver share <action>` - the roster from the terminal (01-sharing §9).
@@ -9,9 +9,12 @@ import { i as loadCollab } from "./sync-WYxDN9IT.mjs";
 * IS the whole interface, and on every canvas it calls the same owner routes
 * the app does, over the device credential `comments connect` stored. The
 * resolver ships with an explainer because a permission system nobody can
-* predict is not safe - `explain` and `who` run the SAME pure function the
-* server enforces with, on the same roster bytes, so the terminal and the
-* dialog can never disagree (acceptance 9).
+* predict is not safe - `explain` asks the canvas's OWN `share/explain` route,
+* so its trace is the resolver the doors enforce with (owner role filled,
+* `@domain` explained through a synthetic member, the winning step marked) and
+* cannot drift from the dialog's Who-sees-what (acceptance 9). `who` runs that
+* same pure function locally over the fetched roster for the granted principals
+* it lists - none of them the owner, so no server-only role handling applies.
 *
 * add <who>        grant view (default) or --role comment; --expires <iso>
 * remove <who>     remove the grant
@@ -48,19 +51,15 @@ const asStore = (roster) => ({
 	blocked: roster.blocked,
 	grants: roster.grants
 });
-/** The trace, rendered - what `explain` prints and what the dialog shows. */
-function renderExplain(who, store, ceilings) {
-	const r = resolveAccess({
-		email: who.startsWith("@") ? null : who,
-		store,
-		ceilings
-	});
+/** The resolver's trace as the server returned it - the winning step marked with
+*  an arrow, the same verdict the dialog's Who-sees-what draws. */
+function renderExplain(r) {
 	const lines = [];
-	for (const step of r.trace) lines.push(`  ${step.where.padEnd(14)} ${step.role.padEnd(9)} ${step.why}`);
+	for (const step of r.trace) lines.push(`  ${step.win ? "→" : " "} ${step.where.padEnd(14)} ${step.role.padEnd(9)} ${step.why}`);
 	const boards = Object.entries(r.boards);
 	const readable = boards.filter(([, role]) => role !== "none").length;
 	const writable = boards.filter(([, role]) => role === "comment").length;
-	for (const [b, role] of boards) lines.push(`  board ${b.padEnd(14)} ${role}`);
+	for (const [b, role] of boards) lines.push(`    board ${b.padEnd(14)} ${role}`);
 	lines.push(`  → ${readable} of ${boards.length} board${boards.length === 1 ? "" : "s"}, may comment on ${writable}`);
 	return lines.join("\n");
 }
@@ -128,8 +127,8 @@ async function shareCommand(root, action, value, opts) {
 		}
 		case "explain": {
 			if (!value) throw new Error("explain needs a principal to explain");
-			const [roster, ceilings] = await Promise.all([api(root, "GET", "share/roster"), fetchCeilings(root)]);
-			console.log(`\n${renderExplain(value, asStore(roster), ceilings)}\n`);
+			const r = await api(root, "GET", `share/explain?who=${encodeURIComponent(value)}`);
+			console.log(`\n${renderExplain(r)}\n`);
 			return;
 		}
 		case "who": {

package/dist/{summary-Bf9tiGrE.mjs → summary-C7CAypbB.mjs}

@@ -1,4 +1,4 @@
-import { n as replay } from "./events-C9k-ceOj.mjs";
+import { n as replay } from "./events-B3LBn74P.mjs";
 import { x as withLock } from "./auth-DdUKeVKt.mjs";
 import { closeSync, fsyncSync, openSync, readFileSync, renameSync, writeSync } from "node:fs";
 import { join } from "node:path";

package/dist/{sync-WYxDN9IT.mjs → sync-BZaCWqK-.mjs}

@@ -1,5 +1,5 @@
 import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
-import { t as diffEvents } from "./events-C9k-ceOj.mjs";
+import { t as diffEvents } from "./events-B3LBn74P.mjs";
 import { i as readLog, r as listBoards, t as appendEvents } from "./comments-DZyobpxG.mjs";
 import { t as CLI_TOKEN_CHARS } from "./auth-DdUKeVKt.mjs";
 import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, unlinkSync, writeSync } from "node:fs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marver-design/marver",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "The agent-native design canvas. A design/ folder, one command, a canvas of live frames built from your repo's real components - comment @marver and your own coding agent does the work. The tool ships no AI.",
   "type": "module",
   "private": false,

package/src/client/shell/App.tsx

@@ -10,7 +10,7 @@ import { bootHash, parseHash, writeHash } from './hash.ts'
 import { CardsIcon, CardsThreeIcon, CaretIcon, CheckIcon, ColumnsIcon, FrameRectIcon, IntentGlyph, MoonIcon, PanelFilledIcon, PanelHollowIcon, ParallelogramDuoIcon, ParallelogramFillIcon, PencilSimpleIcon, PlayIcon, SignpostIcon, SunIcon, VariantsIcon, XIcon, deviceIcon } from './icons.tsx'
 import { CommentsController, revealThread } from './Comments.tsx'
 import { poweredByUrl } from '../../shared/utm.ts'
-import { useComments } from './comments-store.ts'
+import { avatarFallback, useComments } from './comments-store.ts'
 import { CommentButton, DevicePicker, HideUIButton, LaserButton, Popover, ThemePicker, toggleHideUI, usePopover } from './Toolbar.tsx'
 
 const commentsStore = () => useComments.getState()
@@ -1169,6 +1169,15 @@ function JamToasts({ toasts }: { toasts: import('./store.ts').Toast[] }) {
   )
 }
 
+/** The pill's face for a human notification - the author's picture, or the
+ *  house initials fallback (same ladder the thread avatars use). */
+function JamAvatar({ author }: { author: { name?: string; avatar?: string; id?: string; email?: string } }) {
+  const { initials, hue } = avatarFallback(author)
+  return author.avatar
+    ? <img className="sh-jam-ava" src={author.avatar} alt="" referrerPolicy="no-referrer" />
+    : <span className="sh-jam-ava init" style={{ background: `hsl(${hue} 55% 45%)` }}>{initials}</span>
+}
+
 /** A data-goto whose target frame is not on the current board follows the frame HOME:
  *  the first curated board (switcher rank) that pins it is switched to and the frame
  *  focused there - a link is navigation, and navigation never edits a board. Only a
@@ -1239,11 +1248,18 @@ async function viewNote(note: import('./store.ts').JamNote, dismiss: () => void)
  *  `badge` shows the +N deck count (replacing View); `inert` disables inner clicks (the deck handles it). */
 function JamToast({ id, note, badge, inert }: { id: number; note: import('./store.ts').JamNote; badge?: number; inert?: boolean }) {
   const dismiss = () => useStore.getState().dismissToast(id)
+  // human pills are person-first: their avatar, "name mentioned you"; the
+  // agent pill keeps its frame-first shape with the mark
+  const human = note.kind && note.author
   return (
     <div className="sh-toast jam">
-      <span className="sh-jam-mark"><ParallelogramFillIcon size={17} /></span>
+      {human
+        ? <JamAvatar author={note.author!} />
+        : <span className="sh-jam-mark"><ParallelogramFillIcon size={17} /></span>}
       <div className="sh-jam-txt">
-        <b className="sh-jam-frame"><span className="t">{note.frameTitle ?? note.board}</span></b>
+        {human
+          ? <b className="sh-jam-frame"><span className="t">{note.author!.name ?? 'Someone'}</span> <span className="v">{note.kind === 'mention' ? 'mentioned you' : 'replied'}</span></b>
+          : <b className="sh-jam-frame"><span className="t">{note.frameTitle ?? note.board}</span></b>}
         <span className="sh-jam-prev">{note.preview}</span>
       </div>
       {badge != null

package/src/client/shell/Comments.tsx

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

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

@@ -60,9 +60,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
@@ -1029,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) })) },