@semiont/react-ui 0.5.10 → 0.5.12

package/src/components/resource/__tests__/ResourceViewer.mode-switch.test.tsx

@@ -19,14 +19,10 @@ import { TranslationProvider } from '../../../contexts/TranslationContext';
 import { ResourceAnnotationsProvider } from '../../../contexts/ResourceAnnotationsContext';
 import type { ResourceDescriptor as SemiontResource, ResourceId } from '@semiont/core';
 
-// Mock dependencies
-vi.mock('../../../hooks/useObservableBrowse', () => ({
-  useObservableExternalNavigation: () => vi.fn(),
-}));
-
-// ResourceViewer (and ResourceAnnotationsContext) now resolve the client via
+// ResourceViewer now takes its session as a prop; its children (BrowseView /
+// AnnotateView) and ResourceAnnotationsContext still resolve the client via
 // useSemiont(). Mock useSemiont to emit a minimal session carrying a stub
-// client with the methods the subject component touches. The session also
+// client with the methods those children touch. The session also
 // exposes `on` and `emit` stubs so useEventSubscription(s) don't explode.
 const stubClient = {
   browse: { invalidateAnnotationList: vi.fn() },
@@ -115,6 +111,7 @@ describe('ResourceViewer - Mode Switching', () => {
         <ResourceViewer
           resource={mockResource}
           annotations={mockAnnotations}
+          session={null}
         />
       </TestWrapper>
     );
@@ -128,6 +125,7 @@ describe('ResourceViewer - Mode Switching', () => {
         <ResourceViewer
           resource={mockResource}
           annotations={mockAnnotations}
+          session={null}
         />
       </TestWrapper>
     );
@@ -144,6 +142,7 @@ describe('ResourceViewer - Mode Switching', () => {
         <ResourceViewer
           resource={mockResource}
           annotations={mockAnnotations}
+          session={null}
         />
       </TestWrapper>
     );
@@ -158,6 +157,7 @@ describe('ResourceViewer - Mode Switching', () => {
         <ResourceViewer
           resource={mockResource}
           annotations={mockAnnotations}
+          session={null}
         />
       </TestWrapper>
     );
@@ -169,6 +169,7 @@ describe('ResourceViewer - Mode Switching', () => {
         <ResourceViewer
           resource={mockResource}
           annotations={mockAnnotations}
+          session={null}
         />
       </TestWrapper>
     );
@@ -181,6 +182,7 @@ describe('ResourceViewer - Mode Switching', () => {
         <ResourceViewer
           resource={mockResource}
           annotations={mockAnnotations}
+          session={null}
         />
       </TestWrapper>
     );
@@ -193,6 +195,7 @@ describe('ResourceViewer - Mode Switching', () => {
         <ResourceViewer
           resource={mockResource}
           annotations={mockAnnotations}
+          session={null}
         />
       </TestWrapper>
     );
@@ -209,6 +212,7 @@ describe('ResourceViewer - Mode Switching', () => {
         <ResourceViewer
           resource={mockResource}
           annotations={mockAnnotations}
+          session={null}
         />
       </TestWrapper>
     );
@@ -221,6 +225,7 @@ describe('ResourceViewer - Mode Switching', () => {
           <ResourceViewer
             resource={mockResource}
             annotations={mockAnnotations}
+            session={null}
           />
         </TestWrapper>
       );

package/src/components/resource/__tests__/ResourceViewer.toolbar-opt-out.test.tsx

@@ -0,0 +1,135 @@
+/**
+ * VIEWER-TOOLBAR-OPT-OUT — `showToolbar={false}` is a supported opt-out.
+ *
+ * Tier-2 hosts (controlled props, host-composed controls) hide the built-in
+ * bar by CONTRACT, not by CSS-ing react-ui's internals. Hiding the bar must
+ * not disable any seam: the keystone here proves annotate-mode selection
+ * capture still emits mark.request with the bar gone.
+ *
+ * Started RED (the prop doesn't exist; bars render everywhere) → GREEN.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { render, fireEvent, screen, within } 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 { ResourceViewer } from '../ResourceViewer';
+
+// Render the real content so jsdom text selection can target it.
+vi.mock('../../CodeMirrorRenderer', () => ({
+  CodeMirrorRenderer: ({ content }: { content: string }) => <div className="codemirror-renderer">{content}</div>,
+}));
+vi.mock('../../image-annotation/SvgDrawingCanvas', () => ({ SvgDrawingCanvas: () => <div>svg-mock</div> }));
+vi.mock('../../pdf-annotation/PdfAnnotationCanvas.client', () => ({ PdfAnnotationCanvas: () => <div>pdf-mock</div> }));
+vi.mock('react-markdown', () => ({ default: ({ children }: { children: string }) => <div>{children}</div> }));
+vi.mock('remark-gfm', () => ({ default: () => ({}) }));
+
+const CONTENT = 'hello world selectme end';
+
+function makeResource(mediaType = 'text/plain'): SemiontResource & { content: string } {
+  return {
+    '@context': 'https://www.w3.org/ns/activitystreams',
+    '@id': 'res-1' as ResourceId,
+    name: 'Doc',
+    created: '2024-01-01T00:00:00Z',
+    entityTypes: [],
+    archived: false,
+    representations: [{ mediaType, byteSize: 10 }],
+    content: CONTENT,
+  };
+}
+
+const annotations = { highlights: [], references: [], assessments: [], comments: [], tags: [] };
+
+function fakeSession() {
+  const client = {
+    browse: { click: vi.fn(), invalidateAnnotationList: vi.fn() },
+    beckon: { hover: vi.fn() },
+    mark: { request: vi.fn(), delete: vi.fn() },
+  };
+  return { session: { client, subscribe: () => () => {} } as unknown as SemiontSession, client };
+}
+
+const bars = (c: HTMLElement) => c.querySelectorAll('.semiont-annotate-toolbar').length;
+
+describe('ResourceViewer — showToolbar opt-out', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    window.getSelection()?.removeAllRanges();
+  });
+
+  it('default pins today’s behavior: the bar renders in browse and annotate modes', () => {
+    const { session } = fakeSession();
+    const browse = render(
+      <ResourceViewer session={session} resource={makeResource()} annotations={annotations} />,
+    );
+    expect(bars(browse.container)).toBe(1);
+
+    const annotate = render(
+      <ResourceViewer session={session} resource={makeResource()} annotations={annotations}
+        annotateMode={true} onAnnotateModeChange={vi.fn()} />,
+    );
+    expect(bars(annotate.container)).toBe(1);
+  });
+
+  it('showToolbar={false}: no bar in browse mode', () => {
+    const { session } = fakeSession();
+    const { container } = render(
+      <ResourceViewer session={session} resource={makeResource()} annotations={annotations}
+        showToolbar={false} />,
+    );
+    expect(bars(container)).toBe(0);
+    expect(screen.getByText(CONTENT)).toBeInTheDocument(); // content still renders
+  });
+
+  it('showToolbar={false}: no bar in any annotate render mode (text / image / pdf)', async () => {
+    const { session } = fakeSession();
+    const text = render(
+      <ResourceViewer session={session} resource={makeResource('text/plain')} annotations={annotations}
+        annotateMode={true} onAnnotateModeChange={vi.fn()} showToolbar={false} />,
+    );
+    expect(bars(text.container)).toBe(0);
+
+    const image = render(
+      <ResourceViewer session={session} resource={makeResource('image/png')} annotations={annotations}
+        annotateMode={true} onAnnotateModeChange={vi.fn()} showToolbar={false} />,
+    );
+    expect(within(image.container).getByText('svg-mock')).toBeInTheDocument();
+    expect(bars(image.container)).toBe(0);
+
+    const pdf = render(
+      <ResourceViewer session={session} resource={makeResource('application/pdf')} annotations={annotations}
+        annotateMode={true} onAnnotateModeChange={vi.fn()} showToolbar={false} />,
+    );
+    await within(pdf.container).findByText('pdf-mock'); // flush the lazy canvas
+    expect(bars(pdf.container)).toBe(0);
+  });
+
+  it('keystone: with the bar hidden, annotate-mode selection still emits mark.request', () => {
+    const { session, client } = fakeSession();
+    const { container } = render(
+      <ResourceViewer session={session} resource={makeResource('text/plain')} annotations={annotations}
+        annotateMode={true} onAnnotateModeChange={vi.fn()}
+        selectionMotivation="highlighting" onSelectionMotivationChange={vi.fn()}
+        showToolbar={false} />,
+    );
+    expect(bars(container)).toBe(0);
+
+    // Select "world" (offsets 6..11) inside the rendered content, then mouseup.
+    const contentEl = within(container).getByText(CONTENT);
+    const range = document.createRange();
+    range.setStart(contentEl.firstChild!, 6);
+    range.setEnd(contentEl.firstChild!, 11);
+    const selection = window.getSelection()!;
+    selection.removeAllRanges();
+    selection.addRange(range);
+
+    fireEvent.mouseUp(contentEl);
+
+    expect(client.mark.request).toHaveBeenCalledTimes(1);
+    const [source, selectors, motivation] = client.mark.request.mock.calls[0]!;
+    expect(String(source)).toBe('res-1');
+    expect(selectors).toBeTruthy();
+    expect(motivation).toBe('highlighting');
+  });
+});

package/src/components/resource/__tests__/ResourceViewer.toolbar-prefs.test.tsx

@@ -0,0 +1,200 @@
+/**
+ * TOOLBAR-PREFS-AS-PROPS — keystone + per-pref specs.
+ *
+ * Preferences are state, not events: each of the four toolbar prefs (mode, click
+ * action, selection motivation, shape) is a controlled/uncontrolled prop pair.
+ * Controlled instances render the given value and report intents via the callback —
+ * never self-mutate, never touch localStorage, never hear other instances.
+ * Uncontrolled instances hold a plain internal default (false / 'detail' /
+ * 'linking' / 'rectangle') — NOT the legacy localStorage+bus behavior (that lives
+ * in the useToolbarPrefs() policy layer).
+ *
+ * RED ledger: authored `it.fails` (observed: 5 expected fail), flipped to `it` at
+ * Phase 1 GREEN. Provider-free; real AnnotateToolbar (its controls are the subject).
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { render, fireEvent, within, 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 { ResourceViewer } from '../ResourceViewer';
+
+vi.mock('../../CodeMirrorRenderer', () => ({ CodeMirrorRenderer: () => <div>cm-mock</div> }));
+vi.mock('../../image-annotation/SvgDrawingCanvas', () => ({ SvgDrawingCanvas: () => <div>svg-mock</div> }));
+vi.mock('react-markdown', () => ({ default: ({ children }: { children: string }) => <div>{children}</div> }));
+vi.mock('remark-gfm', () => ({ default: () => ({}) }));
+
+function makeResource(mediaType = 'text/plain'): SemiontResource & { content: string } {
+  return {
+    '@context': 'https://www.w3.org/ns/activitystreams',
+    '@id': 'res-1' as ResourceId,
+    name: 'Doc',
+    created: '2024-01-01T00:00:00Z',
+    entityTypes: [],
+    archived: false,
+    representations: [{ mediaType, byteSize: 10 }],
+    content: 'Prefs content.',
+  };
+}
+
+const annotations = { highlights: [], references: [], assessments: [], comments: [], tags: [] };
+
+/** Session double with a live subscribe registry so specs can fire legacy broadcasts. */
+function liveSession() {
+  const handlers = new Map<string, Set<(p: unknown) => void>>();
+  const client = {
+    browse: { click: vi.fn(), invalidateAnnotationList: vi.fn() },
+    beckon: { hover: vi.fn() },
+    mark: {
+      toggleMode: vi.fn(), delete: vi.fn(), request: vi.fn(),
+      changeSelection: vi.fn(), changeClick: vi.fn(), changeShape: vi.fn(),
+    },
+  };
+  const session = {
+    client,
+    subscribe: (channel: string, handler: (p: unknown) => void) => {
+      if (!handlers.has(channel)) handlers.set(channel, new Set());
+      handlers.get(channel)!.add(handler);
+      return () => { handlers.get(channel)!.delete(handler); };
+    },
+  } as unknown as SemiontSession;
+  const fire = (channel: string, payload?: unknown) =>
+    handlers.get(channel)?.forEach((h) => h(payload));
+  return { session, client, fire };
+}
+
+const isAnnotate = (c: HTMLElement) => !!c.querySelector('.semiont-annotate-view');
+const isBrowse = (c: HTMLElement) => !!c.querySelector('.semiont-browse-view');
+
+/** Open a bar dropdown group by aria-label and click an option in its menu. */
+async function pick(container: HTMLElement, group: string, option: string) {
+  const trigger = within(container).getByLabelText(group);
+  fireEvent.mouseEnter(trigger.parentElement!);
+  await waitFor(() => {
+    const menu = within(container).getByRole('menu');
+    fireEvent.click(within(menu).getByText(option));
+  });
+}
+
+const PREF_KEYS = ['annotateMode', 'semiont-toolbar-click', 'semiont-toolbar-selection'];
+let getSpy: ReturnType<typeof vi.spyOn>;
+let setSpy: ReturnType<typeof vi.spyOn>;
+const prefKeyTouched = (spy: ReturnType<typeof vi.spyOn>) =>
+  spy.mock.calls.some((call: unknown[]) => {
+    const key = String(call[0]);
+    return PREF_KEYS.includes(key) || key.includes('shape');
+  });
+
+describe('ResourceViewer — toolbar prefs as props', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    localStorage.clear();
+    getSpy = vi.spyOn(Storage.prototype, 'getItem');
+    setSpy = vi.spyOn(Storage.prototype, 'setItem');
+  });
+  afterEach(() => {
+    getSpy.mockRestore();
+    setSpy.mockRestore();
+  });
+
+  // ── Keystone: per-instance isolation across three viewers on one session ──
+  it('keystone: three viewers — controlled A/B independent, C uncontrolled; B\'s Mode click fires only B\'s callback', async () => {
+    const { session, client } = liveSession();
+    const onB = vi.fn();
+    const a = render(
+      <ResourceViewer session={session} resource={makeResource()} annotations={annotations}
+        annotateMode={true} clickAction="follow" onAnnotateModeChange={vi.fn()} onClickActionChange={vi.fn()} />,
+    );
+    const b = render(
+      <ResourceViewer session={session} resource={makeResource()} annotations={annotations}
+        annotateMode={false} onAnnotateModeChange={onB} />,
+    );
+    const c = render(
+      <ResourceViewer session={session} resource={makeResource()} annotations={annotations} />,
+    );
+
+    expect(isAnnotate(a.container)).toBe(true);   // A renders its controlled mode
+    expect(isBrowse(b.container)).toBe(true);
+    expect(isBrowse(c.container)).toBe(true);     // C: plain default (false)
+
+    await pick(b.container, 'Mode', 'Annotate');
+
+    expect(onB).toHaveBeenCalledWith(true);                 // B reports intent…
+    expect(isBrowse(b.container)).toBe(true);               // …and does not self-flip
+    expect(isAnnotate(a.container)).toBe(true);             // A unchanged
+    expect(isBrowse(c.container)).toBe(true);               // C unchanged
+    expect(client.mark.toggleMode).not.toHaveBeenCalled();  // no global emit
+    expect(prefKeyTouched(getSpy)).toBe(false);             // no localStorage traffic
+    expect(prefKeyTouched(setSpy)).toBe(false);
+  });
+
+  // ── Per-pref: mode ──
+  it('mode: uncontrolled uses the plain default and is inert to the legacy broadcast', () => {
+    localStorage.setItem('annotateMode', 'true'); // legacy key must be IGNORED
+    getSpy.mockClear(); setSpy.mockClear();
+    const { session, fire } = liveSession();
+    const u = render(
+      <ResourceViewer session={session} resource={makeResource()} annotations={annotations} />,
+    );
+    expect(isBrowse(u.container)).toBe(true);      // plain default, not the stored 'true'
+    fire('mark:mode-toggled');
+    expect(isBrowse(u.container)).toBe(true);      // inert: preference events are gone
+    expect(prefKeyTouched(getSpy)).toBe(false);
+    expect(prefKeyTouched(setSpy)).toBe(false);
+  });
+
+  // ── Per-pref: click action ──
+  it('clickAction: controlled renders the value; the bar control reports and does not mutate', async () => {
+    const { session, client } = liveSession();
+    const onChange = vi.fn();
+    const v = render(
+      <ResourceViewer session={session} resource={makeResource()} annotations={annotations}
+        clickAction="follow" onClickActionChange={onChange} />,
+    );
+    const bar = v.container.querySelector('.semiont-annotate-toolbar') as HTMLElement;
+    expect(within(bar).getByText('Follow')).toBeInTheDocument();  // renders the prop value
+
+    await pick(v.container, 'Click', 'Detail');
+    expect(onChange).toHaveBeenCalledWith('detail');              // reports intent
+    expect(within(bar).getByText('Follow')).toBeInTheDocument();  // does not self-mutate
+    expect(client.mark.changeClick).not.toHaveBeenCalled();
+  });
+
+  // ── Per-pref: selection motivation (annotate-mode bar) ──
+  it('selectionMotivation: controlled renders the value; picking reports; re-picking the current reports null', async () => {
+    const { session, client } = liveSession();
+    const onChange = vi.fn();
+    const v = render(
+      <ResourceViewer session={session} resource={makeResource()} annotations={annotations}
+        annotateMode={true} onAnnotateModeChange={vi.fn()}
+        selectionMotivation="highlighting" onSelectionMotivationChange={onChange} />,
+    );
+    const bar = v.container.querySelector('.semiont-annotate-toolbar') as HTMLElement;
+    expect(within(bar).getByText('Highlight')).toBeInTheDocument(); // renders the prop value
+
+    await pick(v.container, 'Motivation', 'Comment');
+    expect(onChange).toHaveBeenCalledWith('commenting');
+
+    await pick(v.container, 'Motivation', 'Highlight');             // current value → toggles off
+    expect(onChange).toHaveBeenCalledWith(null);
+    expect(client.mark.changeSelection).not.toHaveBeenCalled();
+  });
+
+  // ── Per-pref: shape (media-gated; image annotate bar) ──
+  it('shape: controlled renders the value; picking reports and does not mutate', async () => {
+    const { session, client } = liveSession();
+    const onChange = vi.fn();
+    const v = render(
+      <ResourceViewer session={session} resource={makeResource('image/png')} annotations={annotations}
+        annotateMode={true} onAnnotateModeChange={vi.fn()}
+        shape="circle" onShapeChange={onChange} />,
+    );
+    const bar = v.container.querySelector('.semiont-annotate-toolbar') as HTMLElement;
+    expect(within(bar).getByText('Circle')).toBeInTheDocument();    // renders the prop value
+
+    await pick(v.container, 'Shape', 'Polygon');
+    expect(onChange).toHaveBeenCalledWith('polygon');
+    expect(within(bar).getByText('Circle')).toBeInTheDocument();    // does not self-mutate
+    expect(client.mark.changeShape).not.toHaveBeenCalled();
+  });
+});

package/src/components/resource/__tests__/browse-renderers.dispatch.test.tsx

@@ -0,0 +1,113 @@
+/**
+ * BUG: image-browse-renderer-drops-annotations — the default renderers must
+ * forward what BrowseView hands them.
+ *
+ * ImageBrowseRenderer destructured only content/mimeType and mounted a bare
+ * ImageViewer: shape annotations invisible in browse mode (annotate mode
+ * proves the data). Fix: the read-only annotation canvas (drawingMode=null),
+ * WITH the session extension on MediaRendererProps — clicks/hover route in
+ * browse mode too, and the PDF renderer's pre-existing session-less click gap
+ * heals in the same motion (per the fork note in the bug doc).
+ *
+ * Prop-capturing canvas mocks pin the contract: mounted, given the
+ * annotations, read-only, session threaded. Started RED (image: no canvas at
+ * all; pdf: no session) → GREEN.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { render, within } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import type { SemiontSession } from '@semiont/sdk';
+import type { Annotation, AnnotationId } from '@semiont/core';
+import { BrowseView } from '../BrowseView';
+
+const captured = vi.hoisted(() => ({
+  svg: [] as Record<string, unknown>[],
+  pdf: [] as Record<string, unknown>[],
+}));
+
+vi.mock('../../image-annotation/SvgDrawingCanvas', () => ({
+  SvgDrawingCanvas: (props: Record<string, unknown>) => {
+    captured.svg.push(props);
+    return <div className="semiont-svg-drawing-canvas">svg-canvas-mock</div>;
+  },
+}));
+vi.mock('../../pdf-annotation/PdfAnnotationCanvas.client', () => ({
+  PdfAnnotationCanvas: (props: Record<string, unknown>) => {
+    captured.pdf.push(props);
+    return <div>pdf-canvas-mock</div>;
+  },
+}));
+vi.mock('../../annotation/AnnotateToolbar', () => ({ AnnotateToolbar: () => null }));
+vi.mock('react-markdown', () => ({ default: ({ children }: { children: string }) => <div>{children}</div> }));
+vi.mock('remark-gfm', () => ({ default: () => ({}) }));
+
+function fakeSession(): SemiontSession {
+  return {
+    client: { browse: { click: vi.fn() }, beckon: { hover: vi.fn() } },
+    subscribe: () => () => {},
+  } as unknown as SemiontSession;
+}
+
+/** A shape annotation (SvgSelector region) — the image-annotation shape. */
+function shapeAnnotation(): Annotation {
+  return {
+    '@context': 'http://www.w3.org/ns/anno.jsonld',
+    id: 'shape-1' as AnnotationId,
+    type: 'Annotation',
+    motivation: 'highlighting',
+    creator: { '@type': 'Person', name: 'user@example.com' },
+    created: '2026-07-14T00:00:00Z',
+    target: {
+      source: 'res-1',
+      selector: { type: 'SvgSelector', value: '<svg><rect x="1" y="1" width="5" height="5"/></svg>' },
+    },
+  } as unknown as Annotation;
+}
+
+const emptyAnnotations = { highlights: [], references: [], assessments: [], comments: [], tags: [] };
+
+const baseProps = {
+  resourceUri: 'res-1',
+  annotateMode: false,
+};
+
+describe('browse-renderers — annotation + session forwarding (dispatch contract)', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    captured.svg.length = 0;
+    captured.pdf.length = 0;
+  });
+
+  it('image browse mounts the read-only annotation canvas with the annotations and session', () => {
+    const session = fakeSession();
+    const annotations = { ...emptyAnnotations, highlights: [shapeAnnotation()] };
+    const { container } = render(
+      <BrowseView {...baseProps} content="blob:image-url" mimeType="image/png"
+        annotations={annotations} session={session} />,
+    );
+
+    expect(within(container).getByText('svg-canvas-mock')).toBeInTheDocument();
+    expect(captured.svg).toHaveLength(1);
+    const props = captured.svg[0]!;
+    expect(props.imageUrl).toBe('blob:image-url');
+    expect(props.existingAnnotations).toEqual([shapeAnnotation()]); // the dropped prop
+    expect(props.drawingMode).toBeNull();                           // read-only in browse
+    expect(props.session).toBe(session);                            // interaction parity
+  });
+
+  it('pdf browse keeps its annotations (pinned) and gains the session (the healed click gap)', async () => {
+    const session = fakeSession();
+    const annotations = { ...emptyAnnotations, highlights: [shapeAnnotation()] };
+    const { container } = render(
+      <BrowseView {...baseProps} content="blob:pdf-url" mimeType="application/pdf"
+        annotations={annotations} session={session} />,
+    );
+
+    await within(container).findByText('pdf-canvas-mock'); // flush the lazy canvas
+    expect(captured.pdf).toHaveLength(1);
+    const props = captured.pdf[0]!;
+    expect(props.existingAnnotations).toEqual([shapeAnnotation()]); // pinned — worked before
+    expect(props.drawingMode).toBeNull();
+    expect(props.session).toBe(session);                            // NEW — was a session-less no-op
+  });
+});

package/src/components/resource/__tests__/browse-renderers.test.tsx

@@ -0,0 +1,34 @@
+/**
+ * EMBEDDABLE-VIEWER-COMPLETION Phase 0 — regression: the browse `text` default
+ * renders markdown as **formatted prose**, not raw source.
+ *
+ * The other BrowseView suites mock `react-markdown` away for simplicity, so
+ * nothing currently pins that the default text renderer actually *formats*
+ * markdown. This spec uses the real renderer and guards against a regression to
+ * raw/source rendering.
+ */
+import { describe, it, expect } from 'vitest';
+import { render } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { TextBrowseRenderer, defaultBrowseRenderers } from '../browse-renderers';
+
+const base = { mimeType: 'text/markdown', resourceUri: 'res-1', annotations: [] };
+
+describe('browse-renderers — markdown-as-prose (Phase 0 regression)', () => {
+  it('TextBrowseRenderer is the default `text` renderer', () => {
+    expect(defaultBrowseRenderers.text).toBe(TextBrowseRenderer);
+  });
+
+  it('renders markdown as formatted HTML, not raw source', () => {
+    const { container } = render(
+      <TextBrowseRenderer content={'# Big Heading\n\nsome **bold** and a [link](https://x.test).'} {...base} />,
+    );
+    // Formatted: heading / strong / anchor elements exist (react-markdown output).
+    expect(container.querySelector('h1')?.textContent).toBe('Big Heading');
+    expect(container.querySelector('strong')?.textContent).toBe('bold');
+    expect(container.querySelector('a')?.getAttribute('href')).toBe('https://x.test');
+    // NOT raw: the literal markdown syntax must not survive to the text content.
+    expect(container.textContent).not.toContain('# Big Heading');
+    expect(container.textContent).not.toContain('**bold**');
+  });
+});

package/src/components/resource/__tests__/inline-embedding.test.tsx

@@ -0,0 +1,81 @@
+/**
+ * EMBEDDABLE-VIEWER-COMPLETION Phase 1 — inline embedding.
+ *
+ * `inline` is a display variant (default: today's pane behavior, frontend
+ * untouched): the viewer renders at content height in a bare container — no
+ * inner scroll container, no pane chrome. jsdom can't compute stylesheet
+ * layout, so this spec pins the two testable seams: (1) the components emit
+ * the `--inline` modifier classes; (2) the stylesheet contains the inline
+ * overrides (height:auto / overflow:visible / padding drop). The visual
+ * auto-height check is the plan's live smoke-test.
+ *
+ * Started RED (no `inline` prop) and GREEN once Phase 1 lands.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { render } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import type { SemiontSession } from '@semiont/sdk';
+import type { ResourceDescriptor as SemiontResource, ResourceId } from '@semiont/core';
+import { BrowseView } from '../BrowseView';
+import { ResourceViewer } from '../ResourceViewer';
+
+vi.mock('../../annotation/AnnotateToolbar', () => ({ AnnotateToolbar: () => null }));
+vi.mock('react-markdown', () => ({ default: ({ children }: { children: string }) => <div>{children}</div> }));
+vi.mock('remark-gfm', () => ({ default: () => ({}) }));
+
+const emptyAnnotations = { highlights: [], references: [], assessments: [], comments: [], tags: [] };
+
+function fakeSession(): SemiontSession {
+  return {
+    client: { browse: { click: vi.fn() }, beckon: { hover: vi.fn() } },
+    subscribe: () => () => {},
+  } as unknown as SemiontSession;
+}
+
+const resource: SemiontResource & { content: string } = {
+  '@context': 'https://www.w3.org/ns/activitystreams',
+  '@id': 'res-1' as ResourceId,
+  name: 'Doc',
+  created: '2024-01-01T00:00:00Z',
+  entityTypes: [],
+  archived: false,
+  representations: [{ mediaType: 'text/plain', byteSize: 10 }],
+  content: 'Inline content.',
+};
+
+describe('inline embedding (Phase 1)', () => {
+  it('BrowseView: `inline` adds the modifier class; default does not', () => {
+    const props = {
+      content: 'x', mimeType: 'text/plain', resourceUri: 'res-1',
+      annotations: emptyAnnotations, annotateMode: false, session: fakeSession(),
+    };
+    const { container: pane } = render(<BrowseView {...props} />);
+    expect(pane.querySelector('.semiont-browse-view')).not.toHaveClass('semiont-browse-view--inline');
+
+    const { container } = render(<BrowseView {...props} inline />);
+    expect(container.querySelector('.semiont-browse-view')).toHaveClass('semiont-browse-view--inline');
+  });
+
+  it('ResourceViewer: `inline` marks its root and threads to BrowseView', () => {
+    const { container } = render(
+      <ResourceViewer
+        resource={resource} annotations={emptyAnnotations}
+        session={fakeSession()} inline
+      />,
+    );
+    expect(container.querySelector('.semiont-resource-viewer')).toHaveClass('semiont-resource-viewer--inline');
+    expect(container.querySelector('.semiont-browse-view')).toHaveClass('semiont-browse-view--inline');
+  });
+
+  it('stylesheet carries the inline overrides (static gate — layout itself is the live check)', () => {
+    // vitest runs with cwd = the package root (same in CI's per-workspace run).
+    const css = readFileSync(resolve(process.cwd(), 'src/styles/features/resource-viewer.css'), 'utf8');
+    // Auto-height roots, and the content area stops being a scroll container / drops the pane gutter.
+    expect(css).toMatch(/\.semiont-resource-viewer--inline\s*\{[^}]*height:\s*auto/);
+    expect(css).toMatch(/\.semiont-browse-view--inline\s*\{[^}]*height:\s*auto/);
+    expect(css).toMatch(/\.semiont-browse-view--inline\s+\.semiont-browse-view__content\s*\{[^}]*overflow:\s*visible/);
+    expect(css).toMatch(/\.semiont-browse-view--inline\s+\.semiont-browse-view__content\s*\{[^}]*padding:\s*0/);
+  });
+});