@semiont/react-ui 0.5.22 → 0.5.24

package/src/components/resource/annotate-renderers.tsx

@@ -0,0 +1,155 @@
+'use client';
+
+import { lazy, Suspense, type ComponentType } from 'react';
+import type { Annotation } from '@semiont/core';
+import type { SemiontSession } from '@semiont/sdk';
+import { SvgDrawingCanvas } from '../image-annotation/SvgDrawingCanvas';
+import { CodeMirrorRenderer } from '../CodeMirrorRenderer';
+import { segmentTextWithAnnotations } from '../../lib/text-segmentation';
+import type { SelectionMotivation, ShapeType } from '../annotation/AnnotateToolbar';
+
+// Lazy-load the PDF component to avoid SSR issues with browser PDF.js loading.
+// Kept lazy here deliberately: hoisting it to a static import would make it
+// eager again and reintroduce the SSR problem this indirection exists for.
+const PdfAnnotationCanvas = lazy(() =>
+  import('../pdf-annotation/PdfAnnotationCanvas.client').then((mod) => ({ default: mod.PdfAnnotationCanvas })),
+);
+
+/**
+ * Common props for an ANNOTATING media renderer. The read-only sibling is
+ * `MediaRendererProps` in `browse-renderers.tsx`; this one additionally
+ * carries the active tool, because annotating is an interaction, not a paint.
+ *
+ * `content` is decoded text for the text renderer, or a media URL for the
+ * image / PDF renderers. `annotations` is the FLAT list — a renderer derives
+ * whatever shape it needs (the text one segments it), so a custom renderer is
+ * never handed a projection only one implementation can use.
+ * See .plans/ANNOTATE-RENDERER-REGISTRY.md (D1)
+ */
+export interface AnnotateMediaRendererProps {
+  content: string;
+  mimeType: string;
+  resourceUri: string;
+  annotations: Annotation[];
+  /** Session for interaction routing — the canvases emit via `session.client`. */
+  session: SemiontSession | null;
+
+  /** Active drawing tool, or null when nothing is selected (read-only paint). */
+  drawingMode: ShapeType | null;
+  selectedMotivation: SelectionMotivation | null;
+  hoveredAnnotationId?: string | null;
+  hoverDelayMs?: number;
+
+  // Text-path extras. Optional on the shared interface: a custom image or PDF
+  // renderer simply ignores them, the same way `MediaRendererProps.session` is
+  // documented to be ignorable.
+  newAnnotationIds?: Set<string>;
+  scrollToAnnotationId?: string | null;
+  showLineNumbers?: boolean;
+  enableWidgets?: boolean;
+  getTargetResourceName?: (resourceId: string) => string | undefined;
+  generatingReferenceId?: string | null;
+}
+
+/** Annotating media dispatch, keyed by the registry render mode. */
+export type AnnotateMediaRenderers = Partial<Record<string, ComponentType<AnnotateMediaRendererProps>>>;
+
+export function TextAnnotateRenderer({
+  content,
+  annotations,
+  session,
+  newAnnotationIds,
+  hoveredAnnotationId,
+  scrollToAnnotationId,
+  showLineNumbers = false,
+  hoverDelayMs = 150,
+  enableWidgets = false,
+  getTargetResourceName,
+  generatingReferenceId,
+}: AnnotateMediaRendererProps) {
+  // D1: segmentation is a text-rendering concern, derived here rather than
+  // threaded through the shared interface.
+  const segments = segmentTextWithAnnotations(content, annotations);
+
+  return (
+    <CodeMirrorRenderer
+      content={content}
+      segments={segments}
+      editable={false}
+      newAnnotationIds={newAnnotationIds}
+      {...(hoveredAnnotationId !== undefined && { hoveredAnnotationId })}
+      {...(scrollToAnnotationId !== undefined && { scrollToAnnotationId })}
+      sourceView={true}
+      showLineNumbers={showLineNumbers}
+      hoverDelayMs={hoverDelayMs}
+      enableWidgets={enableWidgets}
+      session={session}
+      {...(getTargetResourceName && { getTargetResourceName })}
+      {...(generatingReferenceId !== undefined && { generatingReferenceId })}
+    />
+  );
+}
+
+export function ImageAnnotateRenderer({
+  content,
+  resourceUri,
+  annotations,
+  session,
+  drawingMode,
+  selectedMotivation,
+  hoveredAnnotationId,
+  hoverDelayMs = 150,
+}: AnnotateMediaRendererProps) {
+  if (!content) return null;
+  return (
+    <SvgDrawingCanvas
+      imageUrl={content}
+      resourceUri={resourceUri}
+      existingAnnotations={annotations}
+      drawingMode={drawingMode}
+      selectedMotivation={selectedMotivation}
+      session={session}
+      hoveredAnnotationId={hoveredAnnotationId || null}
+      hoverDelayMs={hoverDelayMs}
+    />
+  );
+}
+
+export function PdfAnnotateRenderer({
+  content,
+  resourceUri,
+  annotations,
+  session,
+  drawingMode,
+  selectedMotivation,
+  hoveredAnnotationId,
+  hoverDelayMs = 150,
+}: AnnotateMediaRendererProps) {
+  if (!content) return null;
+  return (
+    <Suspense fallback={<div className="semiont-annotate-view__loading">Loading PDF viewer...</div>}>
+      <PdfAnnotationCanvas
+        pdfUrl={content}
+        resourceUri={resourceUri}
+        existingAnnotations={annotations}
+        drawingMode={drawingMode}
+        selectedMotivation={selectedMotivation}
+        session={session}
+        hoveredAnnotationId={hoveredAnnotationId || null}
+        hoverDelayMs={hoverDelayMs}
+      />
+    </Suspense>
+  );
+}
+
+/**
+ * Default annotating media renderers. `AnnotateView` merges a caller's
+ * `renderers` override on top of these, so a host can swap one renderer (its
+ * own PDF viewer, say) or add a mode without forking the view — the same seam
+ * `defaultBrowseRenderers` gives the read-only path.
+ */
+export const defaultAnnotateRenderers: Record<'text' | 'image' | 'pdf', ComponentType<AnnotateMediaRendererProps>> = {
+  text: TextAnnotateRenderer,
+  image: ImageAnnotateRenderer,
+  pdf: PdfAnnotateRenderer,
+};

package/src/components/resource/panels/JsonLdPanel.tsx

@@ -7,7 +7,7 @@ import { json } from '@codemirror/lang-json';
 import { oneDark } from '@codemirror/theme-one-dark';
 import { syntaxHighlighting } from '@codemirror/language';
 import { jsonLightTheme, jsonLightHighlightStyle } from '../../../lib/codemirror-json-theme';
-import { useLineNumbers } from '../../../hooks/useLineNumbers';
+import { useLineNumbers } from '../../../contexts/LineNumbersContext';
 import { useResourceGraph } from '../../../hooks/useResourceGraph';
 import type { ResourceId } from '@semiont/core';
 import './JsonLdPanel.css';

package/src/components/resource/panels/ReferencesPanel.tsx

@@ -58,9 +58,25 @@ interface Props {
 
   // Reference-specific props
   allEntityTypes: string[];
+  /**
+   * The entity-type list failed to load. Without it the picker's empty branch
+   * asserts "no entity types available" — a claim about the knowledge base
+   * that a failed load cannot support.
+   * See .plans/PANEL-FAILURE-STATES.md
+   */
+  entityTypesError?: Error | null;
   generatingReferenceId?: string | null;
   referencedBy?: ReferencedBy[];
   referencedByLoading?: boolean;
+  /**
+   * The incoming-references load failed terminally (B15). Distinct from
+   * `referencedByLoading` — without it a dead request is indistinguishable
+   * from one still in flight, and the panel says "Loading..." forever.
+   * See .plans/PANEL-FAILURE-STATES.md
+   */
+  referencedByError?: Error | null;
+  /** Retry the failed incoming-references load. */
+  onRetryReferencedBy?: () => void;
   pendingAnnotation: PendingAnnotation | null;
   scrollToAnnotationId?: string | null;
   onScrollCompleted?: () => void;
@@ -91,9 +107,12 @@ export function ReferencesPanel({
   Link,
   routes,
   allEntityTypes,
+  entityTypesError = null,
   generatingReferenceId,
   referencedBy = [],
   referencedByLoading = false,
+  referencedByError = null,
+  onRetryReferencedBy,
   pendingAnnotation,
   scrollToAnnotationId,
   onScrollCompleted,
@@ -403,7 +422,7 @@ export function ReferencesPanel({
                       ))
                     ) : (
                       <p className="semiont-assist-widget__no-types">
-                        {t('noEntityTypes')}
+                        {entityTypesError ? t('entityTypesFailed') : t('noEntityTypes')}
                       </p>
                     )}
                   </div>
@@ -485,13 +504,29 @@ export function ReferencesPanel({
           <div className="semiont-panel__divider">
             <h3 className="semiont-panel__subtitle">
               {t('incomingReferences')} ({referencedBy.length})
-              {referencedByLoading && (
+              {referencedByLoading && !referencedByError && (
                 <span className="semiont-panel__loading-indicator">({t('loading')})</span>
               )}
             </h3>
           </div>
 
-          {referencedBy.length > 0 ? (
+          {referencedByError ? (
+            <p className="semiont-panel__empty-message semiont-panel__empty-message--small">
+              {t('incomingReferencesFailed')}
+              {onRetryReferencedBy && (
+                <>
+                  {' '}
+                  <button
+                    type="button"
+                    onClick={onRetryReferencedBy}
+                    className="semiont-panel__inline-action"
+                  >
+                    {t('retry')}
+                  </button>
+                </>
+              )}
+            </p>
+          ) : referencedBy.length > 0 ? (
             <div className="semiont-panel__list">
               {referencedBy.map((ref) => {
                 const resourceId = ref.target.source;

package/src/components/resource/panels/TagEntry.tsx

@@ -1,6 +1,7 @@
 'use client';
 
 import { useMemo } from 'react';
+import { isReady } from '@semiont/sdk';
 import type { Ref } from 'react';
 import type { Annotation } from '@semiont/core';
 import { getAnnotationExactText } from '@semiont/core';
@@ -42,7 +43,10 @@ export function TagEntry({
     [session],
   );
   const schemas = useObservable(tagSchemas$);
-  const schema = schemaId && schemas ? schemas.find((s) => s.id === schemaId) ?? null : null;
+  const schema =
+    schemaId && schemas && isReady(schemas)
+      ? schemas.value.find((s) => s.id === schemaId) ?? null
+      : null;
 
   return (
     <div

package/src/components/resource/panels/TaggingPanel.tsx

@@ -1,6 +1,7 @@
 'use client';
 
 import { useState, useEffect, useRef, useCallback, useMemo } from 'react';
+import { isReady } from '@semiont/sdk';
 import { useTranslations } from '../../../contexts/TranslationContext';
 import { useObservable } from '../../../hooks/useObservable';
 import type { SemiontSession } from '@semiont/sdk';
@@ -91,7 +92,11 @@ export function TaggingPanel({
     () => session?.client.browse.tagSchemas() ?? null,
     [session],
   );
-  const schemasObserved = useObservable(tagSchemas$);
+  const schemasState = useObservable(tagSchemas$);
+  // D1 unwrap: value-or-undefined, with the third outcome explicit — a
+  // failed registry read renders like still-loading here (the panel's
+  // failure UI is PANEL-FAILURE-STATES follow-up work, not this migration).
+  const schemasObserved = schemasState && isReady(schemasState) ? schemasState.value : undefined;
   const schemas = schemasObserved ?? [];
   // True only AFTER the registry has resolved AND it's empty — distinct
   // from the initial-loading state (`schemasObserved === undefined`),

package/src/components/resource/panels/UnifiedAnnotationsPanel.tsx

@@ -46,6 +46,14 @@ interface UnifiedAnnotationsPanelProps {
 
   // All annotations (grouped internally by motivation)
   annotations: Annotation[];
+  /**
+   * The annotations load failed terminally (B15). Every tab here derives from
+   * the one `annotations` array, so without this the panel presents an empty
+   * array as fact — "no highlights" for a resource that may be full of them.
+   * See .plans/PANEL-FAILURE-STATES.md
+   */
+  annotationsError?: Error | null;
+  onRetryAnnotations?: () => void;
 
   // Annotators (pure static data - no handlers)
   annotators: Record<string, Annotator>;
@@ -65,6 +73,9 @@ interface UnifiedAnnotationsPanelProps {
   generatingReferenceId?: string | null;
   referencedBy?: any[];
   referencedByLoading?: boolean;
+  entityTypesError?: Error | null;
+  referencedByError?: Error | null;
+  onRetryReferencedBy?: () => void;
 
   // Resource context — threaded to every per-motivation panel, which stamps it
   // as `source` on mark:submit (multi-viewer routing).
@@ -174,6 +185,33 @@ export function UnifiedAnnotationsPanel(props: UnifiedAnnotationsPanelProps) {
     return `semiont-unified-panel__tab-button${isActive ? ' semiont-unified-panel__tab-button--active' : ''}`;
   };
 
+  if (props.annotationsError) {
+    // The tabs below all read one array; an empty one after a failed load is
+    // not "no annotations", it is "we do not know".
+    return (
+      <div className="semiont-unified-panel">
+        <h3 className="semiont-unified-panel__title">
+          {t('title')}
+        </h3>
+        <p className="semiont-unified-panel__error">
+          {t('annotationsFailed')}
+          {props.onRetryAnnotations && (
+            <>
+              {' '}
+              <button
+                type="button"
+                onClick={props.onRetryAnnotations}
+                className="semiont-panel__inline-action"
+              >
+                {t('retry')}
+              </button>
+            </>
+          )}
+        </p>
+      </div>
+    );
+  }
+
   return (
     <div className="semiont-unified-panel">
       {/* Panel Title */}
@@ -284,9 +322,12 @@ export function UnifiedAnnotationsPanel(props: UnifiedAnnotationsPanelProps) {
                 locale={commonProps.locale}
                 sourceLanguage={commonProps.sourceLanguage}
                 allEntityTypes={props.allEntityTypes || []}
+                entityTypesError={props.entityTypesError}
                 generatingReferenceId={props.generatingReferenceId}
                 referencedBy={props.referencedBy}
                 referencedByLoading={props.referencedByLoading}
+                referencedByError={props.referencedByError}
+                onRetryReferencedBy={props.onRetryReferencedBy}
                 Link={props.Link}
                 routes={props.routes}
               />

package/src/components/resource/panels/__tests__/JsonLdPanel.test.tsx

@@ -32,9 +32,15 @@ vi.mock('../../../lib/codemirror-json-theme', () => ({
 }));
 
 // Mock the hooks the panel consumes — NOT the session/client stack.
-vi.mock('@/hooks/useLineNumbers');
+vi.mock('@/contexts/LineNumbersContext', async () => {
+  const actual = await vi.importActual('@/contexts/LineNumbersContext');
+  // Mock ONLY the hook: renderWithProviders mounts the real
+  // LineNumbersProvider, which an auto-mock would swallow (rendering
+  // nothing), while these tests want a fixed showLineNumbers value.
+  return { ...actual, useLineNumbers: vi.fn() };
+});
 vi.mock('@/hooks/useResourceGraph');
-import { useLineNumbers } from '@/hooks/useLineNumbers';
+import { useLineNumbers } from '@/contexts/LineNumbersContext';
 import { useResourceGraph } from '@/hooks/useResourceGraph';
 
 const RID = resourceId('test-resource-1');

package/src/components/resource/panels/__tests__/ReferencesPanel.headless.test.tsx

@@ -84,4 +84,94 @@ describe('ReferencesPanel — headless (session prop, no providers)', () => {
     fireEvent.click(entryText);
     expect(client.browse.click).toHaveBeenCalledWith('ref-1', 'linking');
   });
+
+  describe('incoming references — terminal load failure', () => {
+    // `referencedByLoading` alone cannot distinguish "still in flight" from
+    // "dead" (B15), so the panel used to render "Loading..." for ever.
+    // See .plans/PANEL-FAILURE-STATES.md
+
+    type PanelProps = React.ComponentProps<typeof ReferencesPanel>;
+    const base = (): PanelProps => {
+      const { session } = fakeSession();
+      return {
+        session,
+        resourceId: 'res-1' as const,
+        annotations: [],
+        isAssisting: false,
+        progress: null,
+        pendingAnnotation: null,
+        allEntityTypes: [],
+        Link: TestLink,
+        routes: testRoutes,
+      };
+    };
+
+    it('reports the failure instead of an endless loading line', () => {
+      render(
+        <ReferencesPanel
+          {...base()}
+          referencedBy={[]}
+          referencedByLoading
+          referencedByError={new Error('Resource not found')}
+        />,
+      );
+
+      expect(screen.queryByText('Loading...')).not.toBeInTheDocument();
+      expect(screen.getByText(/Could not load incoming references/)).toBeInTheDocument();
+    });
+
+    it('offers a retry that calls back', () => {
+      const onRetryReferencedBy = vi.fn();
+      render(
+        <ReferencesPanel
+          {...base()}
+          referencedBy={[]}
+          referencedByError={new Error('boom')}
+          onRetryReferencedBy={onRetryReferencedBy}
+        />,
+      );
+
+      fireEvent.click(screen.getByRole('button', { name: 'Try again' }));
+      expect(onRetryReferencedBy).toHaveBeenCalledTimes(1);
+    });
+
+    it('with no error, a still-loading list keeps its loading affordance', () => {
+      render(
+        <ReferencesPanel
+          {...base()}
+          referencedBy={[]}
+          referencedByLoading
+        />,
+      );
+
+      expect(screen.queryByText(/Could not load incoming references/)).not.toBeInTheDocument();
+    });
+  });
+
+  describe('entity types — terminal load failure', () => {
+    // The picker's empty branch says "no entity types", which is a claim about
+    // the knowledge base. On a failed load it is false — the KB may have
+    // plenty. See .plans/PANEL-FAILURE-STATES.md
+
+    it('does not present a failed entity-type load as "none exist"', () => {
+      const { session } = fakeSession();
+      render(
+        <ReferencesPanel
+          session={session}
+          resourceId="res-1"
+          annotations={[]}
+          isAssisting={false}
+          progress={null}
+          pendingAnnotation={null}
+          allEntityTypes={[]}
+          entityTypesError={new Error('boom')}
+          Link={TestLink}
+          routes={testRoutes}
+        />,
+      );
+
+      expect(screen.queryByText('No entity types available')).not.toBeInTheDocument();
+      expect(screen.getByText(/Could not load entity types/)).toBeInTheDocument();
+    });
+  });
 });

package/src/components/resource/panels/__tests__/TagEntry.test.tsx

@@ -135,7 +135,7 @@ describe('TagEntry', () => {
       // transport's HTTP plumbing.
       const { SemiontWrapper, client, session } = createTestSemiontWrapper();
       vi.spyOn(client.browse, 'tagSchemas').mockReturnValue(
-        CacheObservable.from(of([NER_SCHEMA]))
+        CacheObservable.from(of({ status: 'ready' as const, value: [NER_SCHEMA] }))
       );
       render(<TagEntry {...defaultProps} session={session} />, { wrapper: SemiontWrapper });
 
@@ -149,7 +149,7 @@ describe('TagEntry', () => {
       // misses, the schema-name `<span>` is not rendered.
       const { SemiontWrapper, client, session } = createTestSemiontWrapper();
       vi.spyOn(client.browse, 'tagSchemas').mockReturnValue(
-        CacheObservable.from(of([]))
+        CacheObservable.from(of({ status: 'ready' as const, value: [] }))
       );
       const { container } = render(<TagEntry {...defaultProps} session={session} />, { wrapper: SemiontWrapper });
 

package/src/components/resource/panels/__tests__/TaggingPanel.test.tsx

@@ -56,7 +56,7 @@ const TEST_TAG_SCHEMAS: TagSchema[] = [
 const renderWithEventBus = (component: React.ReactElement<{ session: SemiontSession | null }>, tracker?: ReturnType<typeof createEventTracker>) => {
   const { SemiontWrapper, eventBus, client, session } = createTestSemiontWrapper();
   vi.spyOn(client.browse, 'tagSchemas').mockReturnValue(
-    CacheObservable.from(of(TEST_TAG_SCHEMAS))
+    CacheObservable.from(of({ status: 'ready' as const, value: TEST_TAG_SCHEMAS }))
   );
   if (tracker) tracker._attach(eventBus);
   const Wrapper = ({ children }: { children: React.ReactNode }) => (
@@ -74,7 +74,7 @@ const renderWithEventBus = (component: React.ReactElement<{ session: SemiontSess
 const renderWithEmptyRegistry = (component: React.ReactElement<{ session: SemiontSession | null }>) => {
   const { SemiontWrapper, client, session } = createTestSemiontWrapper();
   vi.spyOn(client.browse, 'tagSchemas').mockReturnValue(
-    CacheObservable.from(of([]))
+    CacheObservable.from(of({ status: 'ready' as const, value: [] }))
   );
   const Wrapper = ({ children }: { children: React.ReactNode }) => (
     <SemiontWrapper>{children}</SemiontWrapper>

package/src/components/resource/panels/__tests__/UnifiedAnnotationsPanel.failure.test.tsx

@@ -0,0 +1,78 @@
+/**
+ * The annotations panel must be able to say the annotations failed to load.
+ *
+ * Every tab in this panel derives from one `annotations` array. When that load
+ * fails terminally (B15) the array is empty — indistinguishable from a
+ * resource that genuinely has no annotations, so the panel cheerfully reports
+ * "no highlights" for a resource full of them. That is the same
+ * apparent-data-loss shape as the PDF-annotations bug, arrived at from a
+ * different direction.
+ *
+ * See .plans/PANEL-FAILURE-STATES.md
+ */
+import React from 'react';
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import type { SemiontSession } from '@semiont/sdk';
+import type { RouteBuilder } from '../../../../contexts/RoutingContext';
+import { UnifiedAnnotationsPanel } from '../UnifiedAnnotationsPanel';
+import { ANNOTATORS } from '../../../../lib/annotation-registry';
+
+const TestLink = ({ href, children, ...rest }: any) => <a href={href} {...rest}>{children}</a>;
+const testRoutes = {
+  resourceDetail: (id: string) => `/r/${id}`,
+} as unknown as RouteBuilder;
+
+function fakeSession(): SemiontSession {
+  return {
+    client: { browse: { click: vi.fn() }, beckon: { hover: vi.fn() } },
+    subscribe: () => () => {},
+  } as unknown as SemiontSession;
+}
+
+type PanelProps = React.ComponentProps<typeof UnifiedAnnotationsPanel>;
+
+const base = (): PanelProps => ({
+  session: fakeSession(),
+  annotations: [],
+  annotators: ANNOTATORS,
+  allEntityTypes: [],
+  pendingAnnotation: null,
+  resourceId: 'res-1',
+  Link: TestLink,
+  routes: testRoutes,
+});
+
+describe('UnifiedAnnotationsPanel — annotations load failure', () => {
+  it('reports the failure rather than presenting an empty annotation set as fact', () => {
+    render(
+      <UnifiedAnnotationsPanel
+        {...base()}
+        annotationsError={new Error('Resource not found')}
+      />,
+    );
+
+    expect(screen.getByText(/Could not load annotations/)).toBeInTheDocument();
+  });
+
+  it('offers a retry that calls back', () => {
+    const onRetryAnnotations = vi.fn();
+    render(
+      <UnifiedAnnotationsPanel
+        {...base()}
+        annotationsError={new Error('boom')}
+        onRetryAnnotations={onRetryAnnotations}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: 'Try again' }));
+    expect(onRetryAnnotations).toHaveBeenCalledTimes(1);
+  });
+
+  it('says nothing about failure when the annotations are merely empty', () => {
+    render(<UnifiedAnnotationsPanel {...base()} />);
+
+    expect(screen.queryByText(/Could not load annotations/)).not.toBeInTheDocument();
+  });
+});

package/src/components/settings/SettingsPanel.tsx

@@ -5,10 +5,10 @@ import { LOCALES } from '@semiont/core';
 import { useTranslations } from '../../contexts/TranslationContext';
 import { useLanguageChangeAnnouncements } from '../LiveRegion';
 import { useSemiont } from '../../session/SemiontProvider';
+import { useLineNumbers } from '../../contexts/LineNumbersContext';
 import './SettingsPanel.css';
 
 interface SettingsPanelProps {
-  showLineNumbers: boolean;
   theme: 'light' | 'dark' | 'system';
   locale: string;
   isPendingLocaleChange?: boolean;
@@ -24,7 +24,6 @@ interface SettingsPanelProps {
  * @emits settings:hover-delay-changed - Hover delay changed by user. Payload: { hoverDelayMs: number }
  */
 export function SettingsPanel({
-  showLineNumbers,
   theme,
   locale,
   isPendingLocaleChange = false,
@@ -32,6 +31,11 @@ export function SettingsPanel({
 }: SettingsPanelProps) {
   const t = useTranslations('Settings');
   const semiont = useSemiont();
+  // The switch renders the SHARED line-numbers state, not a prop snapshot:
+  // its toggle is applied by a bus subscriber in ToolbarPanels, so a prop
+  // fed from any per-route source is a second copy that never updates.
+  // See .plans/bugs/line-numbers-toggle-desynced-by-hoist.md
+  const { showLineNumbers } = useLineNumbers();
   const { announceLanguageChanging, announceLanguageChanged } = useLanguageChangeAnnouncements();
 
   // Track previous locale to detect changes