@semiont/react-ui 0.5.26 → 0.5.28

package/src/components/pdf-annotation/__tests__/PdfAnnotationCanvas.test.tsx

@@ -275,7 +275,7 @@ describe('PdfAnnotationCanvas', () => {
     });
   });
 
-  test('passes the annotation rect as browse.click third argument (A1 anchor)', async () => {
+  test('passes the annotation rect as browse.click second argument (A1 anchor)', async () => {
     const click = vi.fn();
     const session = {
       client: { browse: { click }, beckon: { hover: vi.fn() } },
@@ -328,8 +328,7 @@ describe('PdfAnnotationCanvas', () => {
 
     expect(click).toHaveBeenCalledTimes(1);
     expect(click.mock.calls[0]?.[0]).toBe('ann-1');
-    expect(click.mock.calls[0]?.[1]).toBe('highlighting');
-    const anchorRect = click.mock.calls[0]?.[2];
+    const anchorRect = click.mock.calls[0]?.[1];
     expect(anchorRect).toBeDefined();
     expect(typeof anchorRect.width).toBe('number');
   });
@@ -401,8 +400,7 @@ describe('PdfAnnotationCanvas', () => {
 
     expect(click).toHaveBeenCalledTimes(1);
     expect(click.mock.calls[0]?.[0]).toBe('ann-hit-1');
-    expect(click.mock.calls[0]?.[1]).toBe('highlighting');
-    expect(click.mock.calls[0]?.[2]).toMatchObject({
+    expect(click.mock.calls[0]?.[1]).toMatchObject({
       left: displayRect.x,
       top: displayRect.y,
       width: displayRect.width,
@@ -510,6 +508,7 @@ describe('PdfAnnotationCanvas', () => {
         beckon: { hover: vi.fn() },
         browse: {
           resourceAnchoredText: vi.fn().mockResolvedValue({
+            kind: 'extracted',
             text: 'Hello world again',
             items: [
               { start: 0, end: 5, page: 1, x: 72, y: 700, width: 30, height: 12 },
@@ -562,6 +561,7 @@ describe('PdfAnnotationCanvas', () => {
     } as unknown as Awaited<ReturnType<typeof loadPdfDocument>>);
 
     const resourceAnchoredText = vi.fn().mockResolvedValue({
+      kind: 'extracted',
       text: 'Hello world again',
       items: [
         { start: 0, end: 5, page: 1, x: 72, y: 700, width: 30, height: 12 },
@@ -729,6 +729,7 @@ describe('PdfAnnotationCanvas', () => {
       scannedDoc();
 
       const resourceAnchoredText = vi.fn().mockResolvedValue({
+        kind: 'extracted',
         text: 'Hello world again',
         items: [{ start: 0, end: 5, page: 1, x: 72, y: 700, width: 30, height: 12 }],
       });
@@ -891,6 +892,40 @@ describe('PdfAnnotationCanvas', () => {
       });
     });
 
+    test('the strip sizes its scrollport to the panel that clips it — not the window', async () => {
+      // The strip is sticky with a CSS ceiling of 100vh — right when the
+      // nearest scroller is the window, a lie inside an inner-scrolled panel:
+      // there the strip's scrollport extends below the panel's clip, and
+      // `scrollIntoView({block:'nearest'})` considers a tick in that hidden
+      // band already in view — the active page vanished when it crossed the
+      // strip's bottom (never the top, whose edges coincide). Measured live:
+      // strip scrollport 126→846 vs panel 126→639. The fix sizes the
+      // scrollport to the scroller that actually clips it.
+      const io = stubIntersectionObserver();
+      scannedDoc();
+
+      const scroller = document.createElement('div');
+      scroller.style.overflowY = 'auto';
+      Object.defineProperty(scroller, 'clientHeight', { value: 513, configurable: true });
+      document.body.appendChild(scroller);
+
+      render(
+        <PdfAnnotationCanvas resourceUri="res-1"
+          pdfUrl={mockPdfUrl}
+          drawingMode={null}
+          pageLayout="scroll"
+        />,
+        { container: scroller },
+      );
+      await waitFor(() => {
+        expect(document.querySelectorAll('.semiont-pdf-annotation-canvas__strip-page')).toHaveLength(5);
+      });
+      io.fire([1]);
+
+      const strip = document.querySelector('.semiont-pdf-annotation-canvas__strip') as HTMLElement;
+      await waitFor(() => expect(strip.style.maxHeight).toBe('513px'));
+    });
+
     test('clicking a strip rectangle jumps to that page', async () => {
       const io = stubIntersectionObserver();
       scannedDoc();
@@ -1246,7 +1281,7 @@ describe('PdfAnnotationCanvas', () => {
 
       const resourceAnchoredText = vi.fn()
         .mockRejectedValueOnce(new Error('transport down'))
-        .mockResolvedValue({ text: 'later', items: [] });
+        .mockResolvedValue({ kind: 'extracted', text: 'later', items: [] });
       const session = {
         client: { beckon: { hover: vi.fn() }, browse: { resourceAnchoredText } },
       } as unknown as import('@semiont/sdk').SemiontSession;

package/src/components/resource/AnnotateView.tsx

@@ -39,7 +39,7 @@ interface Props {
   /** Session for the shown resource — its client emits mark:* / mark.request; its bus feeds toolbar + beckon events. */
   session: SemiontSession | null;
   /** Recently-created annotation ids to sparkle (host-provided; was ResourceAnnotationsContext). */
-  newAnnotationIds?: Set<string>;
+  sparkleAnnotationIds?: Set<string>;
   /** The bar's Mode control reports the chosen mode here (the owner applies it). */
   onModeChange?: (mode: boolean) => void;
   /** Render the built-in bar (default). false → no bar; selection capture and drawing stay live. */
@@ -53,7 +53,7 @@ interface Props {
  *
  * @emits mark:requested - User requested to create annotation. Payload: { selector: Selector | Selector[], motivation: SelectionMotivation }
  * @subscribes beckon:hover - Annotation hovered. Payload: { annotationId: string | null }
- * @subscribes beckon:focus - Scroll to and highlight annotation. Payload: { annotationId: string }
+ * @subscribes beckon:focus - Scroll to and highlight annotation, unless `resourceId` names a different resource (D7). Payload: { annotationId: string, resourceId?: string }
  */
 export function AnnotateView({
   content,
@@ -69,7 +69,7 @@ export function AnnotateView({
   hoverDelayMs = 150,
   annotateMode,
   session,
-  newAnnotationIds,
+  sparkleAnnotationIds,
   onModeChange,
   showToolbar = true,
   renderers,
@@ -111,10 +111,21 @@ export function AnnotateView({
   // serves, so the behaviour no longer depends on which view mode is active.
   // The `scrollToAnnotationId` prop path (uiState → renderer) stays as the
   // host-facing capability it is; this is the in-app producer's route.
-  const handleAnnotationFocus = useCallback(({ annotationId }: { annotationId?: string | null }) => {
-    if (!containerRef.current) return;
-    scrollAnnotationIntoView(annotationId ?? null, containerRef.current, { pulse: true });
-  }, []);
+  // `resourceId` is a GUARD, not navigation (GUIDED-TOUR D7): it names the
+  // resource this focus applies to, and a viewer showing a different one
+  // ignores it. Absent means unscoped — the in-app emitters (history panel,
+  // annotation list) omit it because they are already scoped to the open
+  // resource, so treating absence as "not mine" would silence all of them.
+  // Focus never navigates; driving the Browser to a resource is
+  // `browse:resource-open`'s job.
+  const handleAnnotationFocus = useCallback(
+    ({ annotationId, resourceId }: { annotationId?: string | null; resourceId?: string }) => {
+      if (resourceId && resourceId !== resourceUri) return;
+      if (!containerRef.current) return;
+      scrollAnnotationIntoView(annotationId ?? null, containerRef.current, { pulse: true });
+    },
+    [resourceUri],
+  );
 
   // Annotation hover (session-scoped). Toolbar preference changes flow through
   // props/callbacks, not the bus (TOOLBAR-PREFS-AS-PROPS).
@@ -256,7 +267,7 @@ export function AnnotateView({
           selectedMotivation={selectedMotivation}
           hoveredAnnotationId={hoveredAnnotationId}
           hoverDelayMs={hoverDelayMs}
-          newAnnotationIds={newAnnotationIds}
+          sparkleAnnotationIds={sparkleAnnotationIds}
           scrollToAnnotationId={scrollToAnnotationId}
           showLineNumbers={showLineNumbers}
           enableWidgets={enableWidgets}

package/src/components/resource/AnnotationHistory.tsx

@@ -51,6 +51,8 @@ export function AnnotationHistory({
 
   // Sort events by oldest first (most recent at bottom)
   // Filter out job events - they're represented by mark:body-updated events instead
+  // `job:progress` is no longer a persisted event type, but logs written before it
+  // was retired still hold them; naming it here keeps those out of the history.
   const events: StoredEventLike[] = eventsData
     .filter((e) => {
       return e.type !== 'job:started' && e.type !== 'job:progress' && e.type !== 'job:completed';

package/src/components/resource/BrowseView.tsx

@@ -35,7 +35,7 @@ interface Props {
   /** Session for the shown resource — emits browse:click / beckon:hover; its bus feeds beckon events. */
   session: SemiontSession | null;
   /** Recently-created annotation ids to sparkle (host-provided; was ResourceAnnotationsContext). */
-  newAnnotationIds?: Set<string>;
+  sparkleAnnotationIds?: Set<string>;
   /** Override the read-only media renderers (render mode → renderer); merged over the defaults. */
   renderers?: BrowseMediaRenderers;
   /** A content link (`<a href>` in the rendered content) was clicked. The viewer preventDefaults and
@@ -87,7 +87,7 @@ export const BrowseView = memo(function BrowseView({
   annotateMode,
   hoverDelayMs = 150,
   session,
-  newAnnotationIds,
+  sparkleAnnotationIds,
   renderers,
   onLinkClick,
   onReferenceHover,
@@ -155,7 +155,7 @@ export const BrowseView = memo(function BrowseView({
         if (annotation) {
           // The emission site owns the geometry: the clicked span's viewport
           // rect rides the event so hosts can anchor popovers (A1).
-          session.client.browse.click(annotation.id, annotation.motivation, annotationElement.getBoundingClientRect());
+          session.client.browse.click(annotation.id, annotationElement.getBoundingClientRect());
         }
       }
     };
@@ -227,11 +227,11 @@ export const BrowseView = memo(function BrowseView({
     };
 
     // Apply animation classes to new annotations
-    if (newAnnotationIds) {
+    if (sparkleAnnotationIds) {
       const annotationSpans = container.querySelectorAll('[data-annotation-id]');
       annotationSpans.forEach((span) => {
         const annotationId = span.getAttribute('data-annotation-id');
-        if (annotationId && newAnnotationIds.has(annotationId)) {
+        if (annotationId && sparkleAnnotationIds.has(annotationId)) {
           span.classList.add('annotation-sparkle');
         }
       });
@@ -248,7 +248,7 @@ export const BrowseView = memo(function BrowseView({
       cleanupHover();
       referentSub?.unsubscribe(); // in-flight referent load dies with the effect
     };
-  }, [content, allAnnotations, newAnnotationIds, hoverDelayMs, session, onReferenceHover]);
+  }, [content, allAnnotations, sparkleAnnotationIds, hoverDelayMs, session, onReferenceHover]);
 
   // Helper to scroll annotation into view with pulse effect
   const scrollToAnnotation = useCallback((annotationId: string | null, removePulse = false) => {
@@ -263,9 +263,20 @@ export const BrowseView = memo(function BrowseView({
     scrollToAnnotation(annotationId);
   }, [scrollToAnnotation]);
 
-  const handleAnnotationFocus = useCallback(({ annotationId }: { annotationId?: string | null }) => {
-    scrollToAnnotation(annotationId ?? null, true);
-  }, [scrollToAnnotation]);
+  // `resourceId` is a GUARD, not navigation (GUIDED-TOUR D7): it names the
+  // resource this focus applies to, and a viewer showing a different one
+  // ignores it. Absent means unscoped — the in-app emitters (history panel,
+  // annotation list) omit it because they are already scoped to the open
+  // resource, so treating absence as "not mine" would silence all of them.
+  // Focus never navigates; driving the Browser to a resource is
+  // `browse:resource-open`'s job.
+  const handleAnnotationFocus = useCallback(
+    ({ annotationId, resourceId }: { annotationId?: string | null; resourceId?: string }) => {
+      if (resourceId && resourceId !== resourceUri) return;
+      scrollToAnnotation(annotationId ?? null, true);
+    },
+    [scrollToAnnotation, resourceUri],
+  );
 
   useSessionEventSubscriptions(session, {
     'beckon:hover': handleAnnotationHover,

package/src/components/resource/ResourceViewer.tsx

@@ -8,7 +8,7 @@ import { BrowseView, type ReferenceHover } from './BrowseView';
 import type { BrowseMediaRenderers } from './browse-renderers';
 import { PopupContainer } from '../annotation-popups/SharedPopupElements';
 import { JsonLdView } from '../annotation-popups/JsonLdView';
-import type { Annotation, AnnotationId, ResourceDescriptor as SemiontResource, components, EventMap, AnchorRect } from '@semiont/core';
+import type { Annotation, AnnotationId, ResourceDescriptor as SemiontResource, EventMap, AnchorRect } from '@semiont/core';
 import { getExactText, getTargetSelector, getPrimaryMediaType, isHighlight, isAssessment, isReference, isComment, isTag, getBodySource } from '@semiont/core';
 import type { SemiontSession } from '@semiont/sdk';
 import { useSessionEventSubscriptions } from '../../hooks/useSessionEventSubscriptions';
@@ -50,7 +50,7 @@ interface Props {
   /** Inline display variant: auto-height, no inner scroll, no pane chrome (browse path). Default: fill-the-pane. */
   inline?: boolean;
   /** Recently-created annotation ids to sparkle (threaded to the browse/annotate subtree). */
-  newAnnotationIds?: Set<string>;
+  sparkleAnnotationIds?: Set<string>;
   generatingReferenceId?: string | null;
   showLineNumbers?: boolean;
   hoverDelayMs?: number;
@@ -102,7 +102,10 @@ interface Props {
  * panel opening invokes the host's `onOpenPanel` callback — the host owns
  * the panel and any `panel:open` emission.
  *
- * @subscribes browse:click - User clicked on annotation. Payload: { annotationId: string, motivation, anchorRect? }
+ * @subscribes browse:click - An annotation was clicked — locally, or driven over
+ *   the wire by another participant. Payload: { annotationId: string, anchorRect? };
+ *   the motivation is derived from the annotation the id names, and an id this
+ *   viewer has not loaded is a no-op.
  */
 export function ResourceViewer({
   resource,
@@ -113,7 +116,7 @@ export function ResourceViewer({
   onLinkClick,
   onReferenceHover,
   inline = false,
-  newAnnotationIds,
+  sparkleAnnotationIds,
   generatingReferenceId,
   showLineNumbers = false,
   hoverDelayMs,
@@ -270,38 +273,34 @@ export function ResourceViewer({
   }, [annotateMode, selectedClick, onOpenResource]);
 
   // Annotation click coordinator - handles panel opening and scrolling
-  const handleAnnotationClickEvent = useCallback(({ annotationId, motivation, anchorRect }: {
+  const handleAnnotationClickEvent = useCallback(({ annotationId, anchorRect }: {
     annotationId: string;
-    motivation: components['schemas']['Motivation'];
     anchorRect?: AnchorRect;
   }) => {
-    // Find the annotation metadata
-    const metadata = Object.values(ANNOTATORS).find(a => a.matchesAnnotation({ motivation } as Annotation));
-
-    if (!metadata?.hasSidePanel) {
-      // Annotation doesn't have a side panel - let handleAnnotationClick handle it
-      const allAnnotations = [...highlights, ...references, ...assessments, ...comments, ...tags];
-      const annotation = allAnnotations.find(a => a.id === annotationId);
-      if (annotation) {
-        handleAnnotationClick(annotation);
-      }
-      return;
-    }
+    // Resolve the annotation FIRST. The id is the whole address, and the
+    // motivation is derived from the annotation it names rather than carried
+    // beside it (TOUR-CLICK D2) — one fact, one encoding. Resolving first also
+    // means a click naming an annotation this viewer has not loaded (a remote
+    // drive that arrived while the participant was elsewhere) finds nothing
+    // and does nothing, which is why the channel needs no resourceId guard.
+    const allAnnotations = [...highlights, ...references, ...assessments, ...comments, ...tags];
+    const annotation = allAnnotations.find(a => a.id === annotationId);
+    if (!annotation) return;
+
+    // The real annotation, not a `{ motivation } as Annotation` stand-in.
+    const metadata = Object.values(ANNOTATORS).find(a => a.matchesAnnotation(annotation));
 
-    if (selectedClick !== 'detail') {
-      // Only open panels in detail mode - for other modes, let handleAnnotationClick handle it
-      const allAnnotations = [...highlights, ...references, ...assessments, ...comments, ...tags];
-      const annotation = allAnnotations.find(a => a.id === annotationId);
-      if (annotation) {
-        handleAnnotationClick(annotation);
-      }
+    // No side panel, or a click mode other than detail: this is a plain
+    // annotation click, not a panel-opening one.
+    if (!metadata?.hasSidePanel || selectedClick !== 'detail') {
+      handleAnnotationClick(annotation);
       return;
     }
 
     // All annotations open the unified annotations panel — the host owns the panel.
     // The panel internally switches tabs based on the motivation → tab mapping in UnifiedAnnotationsPanel.
     // View geometry passes through untouched: the emitter owned it, the host anchors with it.
-    onOpenPanel?.({ panel: 'annotations', scrollToAnnotationId: annotationId, motivation, ...(anchorRect ? { anchorRect } : {}) });
+    onOpenPanel?.({ panel: 'annotations', scrollToAnnotationId: annotationId, motivation: annotation.motivation, ...(anchorRect ? { anchorRect } : {}) });
   }, [highlights, references, assessments, comments, tags, handleAnnotationClick, selectedClick, onOpenPanel]);
 
   // Single subscription call per file (see scripts/compliance/audit-hooks-ordering.ts).
@@ -357,7 +356,7 @@ export function ResourceViewer({
           onModeChange={changeAnnotateMode}
           showToolbar={showToolbar}
           session={session}
-          newAnnotationIds={newAnnotationIds}
+          sparkleAnnotationIds={sparkleAnnotationIds}
           {...(annotateRenderers && { renderers: annotateRenderers })}
         />
       ) : (
@@ -373,7 +372,7 @@ export function ResourceViewer({
           onClickActionChange={changeClickAction}
           showToolbar={showToolbar}
           session={session}
-          newAnnotationIds={newAnnotationIds}
+          sparkleAnnotationIds={sparkleAnnotationIds}
           onLinkClick={onLinkClick}
           onReferenceHover={onReferenceHover}
           inline={inline}

package/src/components/resource/__tests__/AnnotateView.embeddable.test.tsx

@@ -1,7 +1,7 @@
 /**
  * EMBEDDABLE-RESOURCE-VIEWER step 1b — AnnotateView + AnnotateToolbar provider-free.
  *
- * AnnotateView takes `session` + `newAnnotationIds` as props; the REAL
+ * AnnotateView takes `session` + `sparkleAnnotationIds` as props; the REAL
  * AnnotateToolbar (not mocked — its decoupling is the crux of 1b) takes `session`
  * as a prop. CodeMirrorRenderer is mocked (heavy; already prop-based).
  *

package/src/components/resource/__tests__/AnnotateView.focus.test.tsx

@@ -56,3 +56,53 @@ describe('AnnotateView — beckon:focus scrolls the content', () => {
     expect(scrollSpy.mock.calls[0]?.[0]).toBe('ann-7');
   });
 });
+
+// ─────────────────────────────────────────────────────────────────────
+// GUIDED-TOUR P6 (D7) — `resourceId` is a GUARD, not navigation.
+//
+// The schema now says so out loud: "it names the resource this focus applies
+// to, and a viewer currently showing a different resource ignores the event".
+// Without the comparison the field was decorative — a guide beckoning a
+// reference in doc B scrolled every participant's doc A.
+// ─────────────────────────────────────────────────────────────────────
+describe('AnnotateView — beckon:focus is guarded by resourceId (P6/D7)', () => {
+  beforeEach(() => { scrollSpy.mockClear(); });
+
+  const renderAt = (resourceUri: string) => {
+    const { session, client } = createTestSemiontWrapper();
+    render(
+      <AnnotateView
+        content="hello world"
+        mimeType="text/plain"
+        resourceUri={resourceUri}
+        annotations={emptyAnnotations}
+        uiState={uiState}
+        session={session}
+        annotateMode
+      />,
+    );
+    return client;
+  };
+
+  it('ignores a focus aimed at a DIFFERENT resource', () => {
+    const client = renderAt('res-1');
+    client.bus.get('beckon:focus').next({ annotationId: 'ann-7', resourceId: 'res-2' });
+    expect(scrollSpy).not.toHaveBeenCalled();
+  });
+
+  it('still scrolls when the resource matches', () => {
+    const client = renderAt('res-1');
+    client.bus.get('beckon:focus').next({ annotationId: 'ann-7', resourceId: 'res-1' });
+    expect(scrollSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('still scrolls when the event names no resource at all', () => {
+    // `resourceId` is optional in the schema (`required: []`), and the in-app
+    // emitters — the history panel, the annotation list — omit it because they
+    // are already scoped to the open resource. A guard that treated absence as
+    // "not mine" would break every one of them.
+    const client = renderAt('res-1');
+    client.bus.get('beckon:focus').next({ annotationId: 'ann-7' });
+    expect(scrollSpy).toHaveBeenCalledTimes(1);
+  });
+});

package/src/components/resource/__tests__/AnnotationHistory.test.tsx

@@ -173,6 +173,8 @@ describe('AnnotationHistory', () => {
   });
 
   it('filters out job events', () => {
+    // e3 is `job:progress`, a retired event type. Logs written before it was
+    // retired still hold them, so the filter must keep excluding it.
     const events = [
       makeStoredEvent('e1', 'mark:added', 1),
       makeStoredEvent('e2', 'job:started', 2),

package/src/components/resource/__tests__/BrowseView.embeddable.test.tsx

@@ -1,7 +1,7 @@
 /**
  * EMBEDDABLE-RESOURCE-VIEWER step 1a — BrowseView renders provider-free.
  *
- * BrowseView takes its `session` + `newAnnotationIds` as props (not
+ * BrowseView takes its `session` + `sparkleAnnotationIds` as props (not
  * `useSemiont()` / `useResourceAnnotations()`), and subscribes to session-scoped
  * beckon events via `session.subscribe`. `AnnotateToolbar` is mocked here — its
  * own provider decoupling is step 1b — so this spec isolates BrowseView's body.

package/src/components/resource/__tests__/BrowseView.test.tsx

@@ -8,7 +8,7 @@ import { createTestSemiontWrapper } from '../../../test-utils';
 
 import type { Annotation, AnnotationId } from '@semiont/core';
 
-// BrowseView takes its `session` + `newAnnotationIds` as props now (step 1a) — no
+// BrowseView takes its `session` + `sparkleAnnotationIds` as props now (step 1a) — no
 // ResourceAnnotationsContext / SemiontProvider reach-in. `makeSession` (below)
 // wraps the fake client so browse:click / beckon:hover land on the bus the
 // trackers listen on, and session.subscribe registers beckon:* on that bus.
@@ -125,14 +125,14 @@ function makeSession(client: SemiontClient): SemiontSession {
 
 const renderWithProviders = (
   component: React.ReactElement<React.ComponentProps<typeof BrowseView>>,
-  options: { newAnnotationIds?: Set<string> } = {}
+  options: { sparkleAnnotationIds?: Set<string> } = {}
 ) => {
   const { SemiontWrapper, client } = createTestSemiontWrapper();
   const Wrapper = ({ children }: { children: React.ReactNode }) => (
     <SemiontWrapper>{children}</SemiontWrapper>
   );
   return render(
-    React.cloneElement(component, { session: makeSession(client), newAnnotationIds: options.newAnnotationIds }),
+    React.cloneElement(component, { session: makeSession(client), sparkleAnnotationIds: options.sparkleAnnotationIds }),
     { wrapper: Wrapper },
   );
 };
@@ -140,7 +140,7 @@ const renderWithProviders = (
 const renderWithEventTracking = (
   component: React.ReactElement<React.ComponentProps<typeof BrowseView>>,
   tracker: ReturnType<typeof createEventTracker>,
-  options: { newAnnotationIds?: Set<string> } = {}
+  options: { sparkleAnnotationIds?: Set<string> } = {}
 ) => {
   const { SemiontWrapper, eventBus, client } = createTestSemiontWrapper();
   tracker._attach(eventBus);
@@ -148,7 +148,7 @@ const renderWithEventTracking = (
     <SemiontWrapper>{children}</SemiontWrapper>
   );
   return render(
-    React.cloneElement(component, { session: makeSession(client), newAnnotationIds: options.newAnnotationIds }),
+    React.cloneElement(component, { session: makeSession(client), sparkleAnnotationIds: options.sparkleAnnotationIds }),
     { wrapper: Wrapper },
   );
 };
@@ -427,7 +427,7 @@ describe('BrowseView Component', () => {
         { id: 'comment-1', type: 'comment', motivation: 'commenting' },
       ] as const;
 
-      for (const { id, type, motivation } of clickCases) {
+      for (const { id, type } of clickCases) {
         const el = document.createElement('span');
         el.setAttribute('data-annotation-id', id);
         el.setAttribute('data-annotation-type', type);
@@ -439,8 +439,7 @@ describe('BrowseView Component', () => {
         await waitFor(() => {
           expect(tracker.events.some(e =>
             e.event === 'browse:click' &&
-            e.payload?.annotationId === id &&
-            e.payload?.motivation === motivation
+            e.payload?.annotationId === id
           )).toBe(true);
         });
       }
@@ -546,7 +545,7 @@ describe('BrowseView Component', () => {
 
   describe('Annotation Animation Classes', () => {
     it('should apply sparkle class to new annotations', () => {
-      const newAnnotationIds = new Set(['new-annotation-1']);
+      const sparkleAnnotationIds = new Set(['new-annotation-1']);
 
       const annotations = {
         ...defaultProps.annotations,
@@ -554,12 +553,12 @@ describe('BrowseView Component', () => {
       };
 
       renderWithProviders(<BrowseView {...defaultProps} annotations={annotations} />, {
-        newAnnotationIds
+        sparkleAnnotationIds
       });
 
-      // Verify the newAnnotationIds set contains the expected annotation
+      // Verify the sparkleAnnotationIds set contains the expected annotation
       // In the actual component, this triggers the sparkle class application
-      expect(newAnnotationIds.has('new-annotation-1')).toBe(true);
+      expect(sparkleAnnotationIds.has('new-annotation-1')).toBe(true);
     });
   });
 
@@ -653,3 +652,30 @@ describe('BrowseView Component', () => {
     });
   });
 });
+
+// ─────────────────────────────────────────────────────────────────────
+// GUIDED-TOUR P6 (D7) — the same guard BrowseView's sibling carries.
+// BrowseView subscribed to `beckon:focus` first, so it is the one that has
+// been scrolling on other people's resources the longest.
+// ─────────────────────────────────────────────────────────────────────
+describe('BrowseView — beckon:focus is guarded by resourceId (P6/D7)', () => {
+  it('ignores a focus aimed at a different resource, honours one that matches', () => {
+    const { session, client } = createTestSemiontWrapper();
+    const { container } = render(
+      <BrowseView
+        content="hello world"
+        mimeType="text/plain"
+        resourceUri="res-1"
+        annotations={{ highlights: [], references: [], assessments: [], comments: [], tags: [] }}
+        session={session}
+        annotateMode={false}
+      />,
+    );
+    expect(container).toBeTruthy();
+
+    // Neither call may throw; the assertion that matters is the guard's
+    // existence, pinned in AnnotateView where the scroll helper is mockable.
+    client.bus.get('beckon:focus').next({ annotationId: 'ann-7', resourceId: 'res-2' });
+    client.bus.get('beckon:focus').next({ annotationId: 'ann-7', resourceId: 'res-1' });
+  });
+});

package/src/components/resource/__tests__/ResourceViewer.embeddable.test.tsx

@@ -15,7 +15,8 @@ import { describe, it, expect, vi } from 'vitest';
 import { render, screen, act, waitFor } from '@testing-library/react';
 import '@testing-library/jest-dom';
 import type { SemiontSession } from '@semiont/sdk';
-import type { ResourceDescriptor as SemiontResource, ResourceId } from '@semiont/core';
+import type { Annotation, ResourceDescriptor as SemiontResource, ResourceId } from '@semiont/core';
+import { annotationId } from '@semiont/core';
 import { createTestSemiontWrapper } from '../../../test-utils';
 import { ResourceViewer } from '../ResourceViewer';
 
@@ -46,6 +47,23 @@ const resource: SemiontResource & { content: string } = {
 
 const annotations = { highlights: [], references: [], assessments: [], comments: [], tags: [] };
 
+/**
+ * A highlight the viewer has actually loaded. Required since TOUR-CLICK D2: the
+ * click handler resolves the annotation by id and derives the motivation from
+ * it, so a click for an id absent from this collection is a no-op. Before that,
+ * the wire carried the motivation and the viewer never looked — which is why
+ * the anchorRect test below used to pass against an empty collection.
+ */
+const loadedHighlight: Annotation = {
+  '@context': 'http://www.w3.org/ns/anno.jsonld',
+  type: 'Annotation',
+  id: annotationId('ann-1'),
+  motivation: 'highlighting',
+  target: { source: 'res-1', selector: { type: 'TextPositionSelector', start: 0, end: 10 } },
+};
+
+const annotationsWithHighlight = { ...annotations, highlights: [loadedHighlight] };
+
 describe('ResourceViewer — embeddable (bring-your-own-session, no providers)', () => {
   // GREEN: the whole browse-mode subtree (ResourceViewer → BrowseView →
   // AnnotateToolbar) renders provider-free from a bare session.
@@ -73,7 +91,7 @@ describe('ResourceViewer — embeddable (bring-your-own-session, no providers)',
       <ResourceViewer
         session={session}
         resource={resource}
-        annotations={annotations}
+        annotations={annotationsWithHighlight}
         onOpenResource={vi.fn()}
         onOpenPanel={onOpenPanel}
       />,
@@ -86,7 +104,6 @@ describe('ResourceViewer — embeddable (bring-your-own-session, no providers)',
     act(() => {
       eventBus.get('browse:click').next({
         annotationId: 'ann-1',
-        motivation: 'highlighting',
         anchorRect,
       });
     });
@@ -95,8 +112,35 @@ describe('ResourceViewer — embeddable (bring-your-own-session, no providers)',
       expect(onOpenPanel).toHaveBeenCalledWith(expect.objectContaining({
         panel: 'annotations',
         scrollToAnnotationId: 'ann-1',
+        // Derived from the annotation the id names, never carried on the wire.
+        motivation: 'highlighting',
         anchorRect: expect.objectContaining({ left: 5, width: 7 }),
       }));
     });
   });
+
+  it('ignores a browse:click naming an annotation this viewer has not loaded', async () => {
+    // A remote drive can arrive while the participant is looking at something
+    // else. Resolving the annotation FIRST makes that a no-op by construction,
+    // which is why the channel carries no resourceId guard (TOUR-CLICK D3).
+    const { session, eventBus } = createTestSemiontWrapper();
+    const onOpenPanel = vi.fn();
+
+    render(
+      <ResourceViewer
+        session={session}
+        resource={resource}
+        annotations={annotationsWithHighlight}
+        onOpenResource={vi.fn()}
+        onOpenPanel={onOpenPanel}
+      />,
+    );
+
+    act(() => {
+      eventBus.get('browse:click').next({ annotationId: 'ann-not-here' });
+    });
+
+    await new Promise((r) => setTimeout(r, 20));
+    expect(onOpenPanel).not.toHaveBeenCalled();
+  });
 });