@bendyline/squisq-react 1.4.0 → 1.4.1

package/src/LinearDocView.tsx

@@ -28,17 +28,32 @@ import {
   type Theme,
 } from '@bendyline/squisq/schemas';
 import { VIEWPORT_PRESETS } from '@bendyline/squisq/schemas';
-import { getLayers, hasTemplate, DEFAULT_THEME, deriveTemplateInputs } from '@bendyline/squisq/doc';
+import {
+  getLayers,
+  hasTemplate,
+  markdownToDoc,
+  DEFAULT_THEME,
+  deriveTemplateInputs,
+} from '@bendyline/squisq/doc';
 import type { RenderContext } from '@bendyline/squisq/doc';
-import { extractPlainText } from '@bendyline/squisq/markdown';
+import { extractPlainText, parseMarkdown } from '@bendyline/squisq/markdown';
 import { BlockRenderer } from './BlockRenderer';
 import { MarkdownRenderer } from './MarkdownRenderer';
 
 // ── Props ──────────────────────────────────────────────────────────
 
 export interface LinearDocViewProps {
-  /** The Doc to render */
-  doc: Doc;
+  /**
+   * The Doc to render. Wins over `markdown` when both are provided.
+   * When neither `doc` nor `markdown` is given, an empty container renders.
+   */
+  doc?: Doc;
+  /**
+   * Markdown source to render. When `doc` is absent, the markdown is parsed
+   * and converted to a Doc via `markdownToDoc(parseMarkdown(markdown))`.
+   * Ignored when `doc` is provided.
+   */
+  markdown?: string;
   /** Base path for resolving media URLs (images, etc.) */
   basePath?: string;
   /** Viewport config for SVG card rendering (default: landscape) */
@@ -78,16 +93,33 @@ export type ImageDisplayMode = 'inline' | 'thumbnail';
 
 // ── Helpers ────────────────────────────────────────────────────────
 
+// Unknown template names we've already warned about (module-level so each
+// name warns at most once per page, not once per render).
+const warnedUnknownTemplates = new Set<string>();
+
 /**
  * Determine whether a block has a template annotation that should be
  * rendered as a visual SVG card. A block is "annotated" when:
  * 1. Its sourceHeading has a templateAnnotation, AND
  * 2. The annotated template exists in the registry
+ *
+ * Blocks annotated with a template that is NOT in the registry fall back
+ * to plain markdown rendering, with a one-shot dev-visible warning per
+ * unknown template name.
  */
 function isAnnotatedBlock(block: Block): boolean {
   const annotation = block.sourceHeading?.templateAnnotation;
-  if (!annotation) return false;
-  return !!annotation.template && hasTemplate(annotation.template);
+  if (!annotation?.template) return false;
+  if (!hasTemplate(annotation.template)) {
+    if (!warnedUnknownTemplates.has(annotation.template)) {
+      warnedUnknownTemplates.add(annotation.template);
+      console.warn(
+        `[squisq] Unknown template "${annotation.template}" — rendering the block as plain markdown.`,
+      );
+    }
+    return false;
+  }
+  return true;
 }
 
 /**
@@ -221,8 +253,6 @@ function BlockSection({ block, basePath, viewport, renderContext, blockIndex }:
   );
 }
 
-// ── Template Defaults (mirrored from PreviewPanel) ─────────────────
-
 // ── Main Component ─────────────────────────────────────────────────
 
 /**
@@ -239,6 +269,7 @@ function BlockSection({ block, basePath, viewport, renderContext, blockIndex }:
  */
 export function LinearDocView({
   doc,
+  markdown,
   basePath = '/',
   viewport,
   className,
@@ -248,7 +279,18 @@ export function LinearDocView({
   imageDisplayMode = 'inline',
 }: LinearDocViewProps) {
   const activeViewport = viewport ?? VIEWPORT_PRESETS.landscape;
-  const totalBlocks = useMemo(() => countAll(doc.blocks), [doc.blocks]);
+
+  // Parse markdown into a Doc only when no explicit doc is supplied.
+  const markdownDoc = useMemo(
+    () => (!doc && markdown !== undefined ? markdownToDoc(parseMarkdown(markdown)) : undefined),
+    [doc, markdown],
+  );
+  const resolvedDoc = doc ?? markdownDoc;
+
+  const totalBlocks = useMemo(
+    () => (resolvedDoc ? countAll(resolvedDoc.blocks) : 0),
+    [resolvedDoc],
+  );
   const autoSurface = useAutoSurface(surface === 'auto');
   const resolvedSurface: SurfaceScheme | undefined = surface === 'auto' ? autoSurface : surface;
 
@@ -266,6 +308,13 @@ export function LinearDocView({
   }, [activeViewport, totalBlocks, theme, resolvedSurface]);
 
   const activeTheme = renderContext.theme!;
+
+  // Nothing to render — keep an empty (but classed) container so hosts can
+  // still target/measure the view.
+  if (!resolvedDoc) {
+    return <div className={`squisq-linear squisq-linear--empty ${className || ''}`} />;
+  }
+
   const bgColor = activeTheme.colors.background;
   const textColor = activeTheme.colors.text;
   const mutedColor = activeTheme.colors.textMuted;
@@ -428,7 +477,7 @@ export function LinearDocView({
             background: color-mix(in srgb, var(--squisq-linear-primary) 8%, transparent);
           }
         `}</style>
-        {doc.blocks.map((block, i) => (
+        {resolvedDoc.blocks.map((block, i) => (
           <BlockSection
             key={block.id}
             block={block}

package/src/MarkdownRenderer.tsx

@@ -43,15 +43,29 @@ export interface MarkdownRendererProps {
    * event handlers, and executable URL schemes before rendering.
    */
   htmlPolicy?: HtmlPolicy;
+  /**
+   * Extra URL schemes to allow on links (e.g. a host app's internal
+   * navigation scheme it intercepts on click). Executable schemes are
+   * never allowed regardless. See {@link SanitizeUrlOptions}.
+   */
+  linkSchemes?: readonly string[];
 }
 
+/** Options threaded through the recursive renderers. */
+interface RenderCtx {
+  htmlPolicy: HtmlPolicy;
+  linkSchemes?: readonly string[];
+}
+
+const DEFAULT_CTX: RenderCtx = { htmlPolicy: 'sanitize' };
+
 // ── Inline Renderer ────────────────────────────────────────────────
 
 /** Render an array of inline nodes into React elements. */
 function renderInline(
   nodes: MarkdownInlineNode[],
   keyPrefix = '',
-  htmlPolicy: HtmlPolicy = 'sanitize',
+  ctx: RenderCtx = DEFAULT_CTX,
 ): React.ReactNode[] {
   return nodes.map((node, i) => {
     const key = `${keyPrefix}i${i}`;
@@ -79,21 +93,21 @@ function renderInline(
       case 'emphasis':
         return (
           <em key={key} className="squisq-md-em">
-            {renderInline(node.children, key, htmlPolicy)}
+            {renderInline(node.children, key, ctx)}
           </em>
         );
 
       case 'strong':
         return (
           <strong key={key} className="squisq-md-strong">
-            {renderInline(node.children, key, htmlPolicy)}
+            {renderInline(node.children, key, ctx)}
           </strong>
         );
 
       case 'delete':
         return (
           <del key={key} className="squisq-md-del">
-            {renderInline(node.children, key, htmlPolicy)}
+            {renderInline(node.children, key, ctx)}
           </del>
         );
 
@@ -105,11 +119,11 @@ function renderInline(
         );
 
       case 'link': {
-        const href = sanitizeUrl(node.url, 'link');
+        const href = sanitizeUrl(node.url, 'link', { extraLinkSchemes: ctx.linkSchemes });
         if (!href) {
           return (
             <span key={key} className="squisq-md-link squisq-md-link--blocked">
-              {renderInline(node.children, key, htmlPolicy)}
+              {renderInline(node.children, key, ctx)}
             </span>
           );
         }
@@ -122,7 +136,7 @@ function renderInline(
             target="_blank"
             rel="noopener noreferrer"
           >
-            {renderInline(node.children, key, htmlPolicy)}
+            {renderInline(node.children, key, ctx)}
           </a>
         );
       }
@@ -143,11 +157,11 @@ function renderInline(
         );
 
       case 'htmlInline':
-        if (htmlPolicy === 'strip') return null;
+        if (ctx.htmlPolicy === 'strip') return null;
         // Fast path: no <video>/<audio> in the subtree → use the original
         // rawHtml passthrough (preserves arbitrary HTML for custom embeds).
         if (
-          htmlPolicy === 'trusted' &&
+          ctx.htmlPolicy === 'trusted' &&
           !containsMediaTag(node.htmlChildren) &&
           !containsDangerousTag(node.htmlChildren) &&
           !hasDangerousRawHtml(node.rawHtml)
@@ -164,7 +178,7 @@ function renderInline(
         // go through MediaContext-aware player components.
         return (
           <span key={key} className="squisq-md-html-inline">
-            {renderHtmlNodes(resolveHtmlNodes(node.htmlChildren, htmlPolicy), `${key}h`)}
+            {renderHtmlNodes(resolveHtmlNodes(node.htmlChildren, ctx.htmlPolicy), `${key}h`)}
           </span>
         );
 
@@ -179,7 +193,7 @@ function renderInline(
         // Render as plain text (definition targets not available at render time)
         return (
           <span key={key} className="squisq-md-link-ref">
-            {renderInline(node.children, key, htmlPolicy)}
+            {renderInline(node.children, key, ctx)}
           </span>
         );
 
@@ -193,7 +207,7 @@ function renderInline(
       case 'textDirective':
         return (
           <span key={key} className="squisq-md-text-directive" data-directive={node.name}>
-            {renderInline(node.children, key, htmlPolicy)}
+            {renderInline(node.children, key, ctx)}
           </span>
         );
 
@@ -223,13 +237,13 @@ function renderInline(
 function renderBlock(
   node: MarkdownBlockNode,
   key: string,
-  htmlPolicy: HtmlPolicy = 'sanitize',
+  ctx: RenderCtx = DEFAULT_CTX,
 ): React.ReactNode {
   switch (node.type) {
     case 'paragraph':
       return (
         <p key={key} className="squisq-md-p">
-          {renderInline(node.children, key, htmlPolicy)}
+          {renderInline(node.children, key, ctx)}
         </p>
       );
 
@@ -237,7 +251,7 @@ function renderBlock(
       const Tag = `h${node.depth}` as 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
       return (
         <Tag key={key} className={`squisq-md-heading squisq-md-h${node.depth}`}>
-          {renderInline(node.children, key, htmlPolicy)}
+          {renderInline(node.children, key, ctx)}
         </Tag>
       );
     }
@@ -245,7 +259,7 @@ function renderBlock(
     case 'blockquote':
       return (
         <blockquote key={key} className="squisq-md-blockquote">
-          {renderBlocks(node.children, key, htmlPolicy)}
+          {renderBlocks(node.children, key, ctx)}
         </blockquote>
       );
 
@@ -253,13 +267,13 @@ function renderBlock(
       if (node.ordered) {
         return (
           <ol key={key} className="squisq-md-list squisq-md-ol" start={node.start ?? undefined}>
-            {node.children.map((item, i) => renderListItem(item, `${key}li${i}`, htmlPolicy))}
+            {node.children.map((item, i) => renderListItem(item, `${key}li${i}`, ctx))}
           </ol>
         );
       }
       return (
         <ul key={key} className="squisq-md-list squisq-md-ul">
-          {node.children.map((item, i) => renderListItem(item, `${key}li${i}`, htmlPolicy))}
+          {node.children.map((item, i) => renderListItem(item, `${key}li${i}`, ctx))}
         </ul>
       );
 
@@ -274,14 +288,14 @@ function renderBlock(
       return <hr key={key} className="squisq-md-hr" />;
 
     case 'table':
-      return renderTable(node.children, node.align, key, htmlPolicy);
+      return renderTable(node.children, node.align, key, ctx);
 
     case 'htmlBlock':
-      if (htmlPolicy === 'strip') return null;
+      if (ctx.htmlPolicy === 'strip') return null;
       // Fast path: no <video>/<audio> → preserve the existing rawHtml
       // passthrough so arbitrary HTML embeds still survive verbatim.
       if (
-        htmlPolicy === 'trusted' &&
+        ctx.htmlPolicy === 'trusted' &&
         !containsMediaTag(node.htmlChildren) &&
         !containsDangerousTag(node.htmlChildren) &&
         !hasDangerousRawHtml(node.rawHtml)
@@ -298,7 +312,7 @@ function renderBlock(
       // route through the player components and resolve via MediaContext.
       return (
         <div key={key} className="squisq-md-html-block">
-          {renderHtmlNodes(resolveHtmlNodes(node.htmlChildren, htmlPolicy), `${key}h`)}
+          {renderHtmlNodes(resolveHtmlNodes(node.htmlChildren, ctx.htmlPolicy), `${key}h`)}
         </div>
       );
 
@@ -317,7 +331,7 @@ function renderBlock(
       return (
         <div key={key} className="squisq-md-footnote-def" id={`fn-${node.identifier}`}>
           <sup>{node.label ?? node.identifier}</sup>
-          {renderBlocks(node.children, key, htmlPolicy)}
+          {renderBlocks(node.children, key, ctx)}
         </div>
       );
 
@@ -329,7 +343,7 @@ function renderBlock(
           data-directive={node.name}
         >
           {node.label && <div className="squisq-md-directive-label">{node.label}</div>}
-          {renderBlocks(node.children, key, htmlPolicy)}
+          {renderBlocks(node.children, key, ctx)}
         </div>
       );
 
@@ -340,7 +354,7 @@ function renderBlock(
           className={`squisq-md-directive squisq-md-directive-${node.name}`}
           data-directive={node.name}
         >
-          {renderInline(node.children, key, htmlPolicy)}
+          {renderInline(node.children, key, ctx)}
         </div>
       );
 
@@ -351,13 +365,13 @@ function renderBlock(
             if (child.type === 'definitionTerm') {
               return (
                 <dt key={`${key}dt${i}`} className="squisq-md-dt">
-                  {renderInline(child.children, `${key}dt${i}`, htmlPolicy)}
+                  {renderInline(child.children, `${key}dt${i}`, ctx)}
                 </dt>
               );
             }
             return (
               <dd key={`${key}dd${i}`} className="squisq-md-dd">
-                {renderBlocks(child.children, `${key}dd${i}`, htmlPolicy)}
+                {renderBlocks(child.children, `${key}dd${i}`, ctx)}
               </dd>
             );
           })}
@@ -373,7 +387,7 @@ function renderBlock(
 function renderListItem(
   item: MarkdownListItem,
   key: string,
-  htmlPolicy: HtmlPolicy = 'sanitize',
+  ctx: RenderCtx = DEFAULT_CTX,
 ): React.ReactNode {
   const isTask = item.checked !== null && item.checked !== undefined;
   return (
@@ -381,7 +395,7 @@ function renderListItem(
       {isTask && (
         <input type="checkbox" checked={!!item.checked} readOnly className="squisq-md-checkbox" />
       )}
-      {renderBlocks(item.children, key, htmlPolicy)}
+      {renderBlocks(item.children, key, ctx)}
     </li>
   );
 }
@@ -391,7 +405,7 @@ function renderTable(
   rows: MarkdownTableRow[],
   align: (('left' | 'right' | 'center') | null)[] | undefined,
   key: string,
-  htmlPolicy: HtmlPolicy = 'sanitize',
+  ctx: RenderCtx = DEFAULT_CTX,
 ): React.ReactNode {
   const [headerRow, ...bodyRows] = rows;
   return (
@@ -405,7 +419,7 @@ function renderTable(
                 className="squisq-md-th"
                 style={align?.[ci] ? { textAlign: align[ci]! } : undefined}
               >
-                {renderInline(cell.children, `${key}th${ci}`, htmlPolicy)}
+                {renderInline(cell.children, `${key}th${ci}`, ctx)}
               </th>
             ))}
           </tr>
@@ -421,7 +435,7 @@ function renderTable(
                   className="squisq-md-td"
                   style={align?.[ci] ? { textAlign: align[ci]! } : undefined}
                 >
-                  {renderInline(cell.children, `${key}td${ri}-${ci}`, htmlPolicy)}
+                  {renderInline(cell.children, `${key}td${ri}-${ci}`, ctx)}
                 </td>
               ))}
             </tr>
@@ -436,9 +450,9 @@ function renderTable(
 function renderBlocks(
   nodes: MarkdownBlockNode[],
   keyPrefix = '',
-  htmlPolicy: HtmlPolicy = 'sanitize',
+  ctx: RenderCtx = DEFAULT_CTX,
 ): React.ReactNode[] {
-  return nodes.map((node, i) => renderBlock(node, `${keyPrefix}b${i}`, htmlPolicy));
+  return nodes.map((node, i) => renderBlock(node, `${keyPrefix}b${i}`, ctx));
 }
 
 // ── Image with MediaProvider resolution ───────────────────────────
@@ -655,10 +669,13 @@ export function MarkdownRenderer({
   nodes,
   className,
   htmlPolicy = 'sanitize',
+  linkSchemes,
 }: MarkdownRendererProps) {
   if (!nodes || nodes.length === 0) return null;
 
   return (
-    <div className={`squisq-md ${className || ''}`}>{renderBlocks(nodes, '', htmlPolicy)}</div>
+    <div className={`squisq-md ${className || ''}`}>
+      {renderBlocks(nodes, '', { htmlPolicy, linkSchemes })}
+    </div>
   );
 }

package/src/__tests__/DocPlayer.test.tsx

@@ -14,20 +14,20 @@ function minimalDoc(): Doc {
 
 describe('DocPlayer smoke test', () => {
   it('renders without crashing in video mode (default)', () => {
-    const { container } = render(<DocPlayer script={minimalDoc()} basePath="/test" />);
+    const { container } = render(<DocPlayer doc={minimalDoc()} basePath="/test" />);
     expect(container.firstChild).toBeTruthy();
   });
 
   it('renders without crashing in slideshow mode', () => {
     const { container } = render(
-      <DocPlayer script={minimalDoc()} basePath="/test" displayMode="slideshow" />,
+      <DocPlayer doc={minimalDoc()} basePath="/test" displayMode="slideshow" />,
     );
     expect(container.firstChild).toBeTruthy();
   });
 
   it('renders without crashing in linear mode', () => {
     const { container } = render(
-      <DocPlayer script={minimalDoc()} basePath="/test" displayMode="linear" />,
+      <DocPlayer doc={minimalDoc()} basePath="/test" displayMode="linear" />,
     );
     expect(container.firstChild).toBeTruthy();
   });
@@ -36,7 +36,7 @@ describe('DocPlayer smoke test', () => {
     let controls: { play: () => void; pause: () => void } | null = null;
     render(
       <DocPlayer
-        script={minimalDoc()}
+        doc={minimalDoc()}
         basePath="/test"
         showControls={false}
         onControlsReady={(c) => {
@@ -49,3 +49,33 @@ describe('DocPlayer smoke test', () => {
     expect(typeof controls!.pause).toBe('function');
   });
 });
+
+describe('DocPlayer front door (doc / markdown resolution)', () => {
+  it('renders a doc built from the markdown prop', () => {
+    const { container } = render(
+      <DocPlayer markdown={'# Hello From Markdown\n\nBody text here.'} displayMode="linear" />,
+    );
+    expect(container.querySelector('.doc-player')).toBeTruthy();
+    expect(container.textContent).toContain('Hello From Markdown');
+  });
+
+  it('doc wins over markdown when both are provided', () => {
+    const { container } = render(
+      <DocPlayer doc={minimalDoc()} markdown="# Markdown Loses" displayMode="linear" />,
+    );
+    expect(container.querySelector('.doc-player')).toBeTruthy();
+    expect(container.textContent).not.toContain('Markdown Loses');
+  });
+
+  it('renders an empty state without throwing when neither doc nor markdown is given', () => {
+    const { container } = render(<DocPlayer />);
+    const empty = container.querySelector('.doc-player--empty');
+    expect(empty).toBeTruthy();
+    expect(empty!.classList.contains('doc-player')).toBe(true);
+  });
+
+  it('defaults basePath when omitted', () => {
+    const { container } = render(<DocPlayer doc={minimalDoc()} />);
+    expect(container.querySelector('.doc-player')).toBeTruthy();
+  });
+});

package/src/__tests__/DocPlayerStylesSentinel.test.tsx

@@ -0,0 +1,41 @@
+/**
+ * Missing-stylesheet sentinel test.
+ *
+ * Lives in its own file so it owns a fresh module instance of DocPlayer
+ * (vitest isolates module registries per test file) — the sentinel warning
+ * is one-shot at module level, so this file's first mount deterministically
+ * observes it.
+ */
+
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { render } from '@testing-library/react';
+import { DocPlayer } from '../DocPlayer';
+import type { Doc } from '@bendyline/squisq/schemas';
+
+function minimalDoc(): Doc {
+  return {
+    articleId: 'sentinel',
+    duration: 5,
+    blocks: [{ id: 'b1', startTime: 0, duration: 5, audioSegment: 0, layers: [] }],
+    audio: { segments: [] },
+  };
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('DocPlayer missing-CSS sentinel', () => {
+  it('warns once (and only once) in dev when the stylesheet is not loaded', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    render(<DocPlayer doc={minimalDoc()} />);
+    const sentinelCalls = () =>
+      warnSpy.mock.calls.filter((c) => String(c[0]).includes('squisq-react/styles'));
+    expect(sentinelCalls().length).toBe(1);
+
+    // Second mount must not warn again — module-level one-shot.
+    render(<DocPlayer doc={minimalDoc()} />);
+    expect(sentinelCalls().length).toBe(1);
+  });
+});

package/src/__tests__/LinearDocView.test.tsx

@@ -1,4 +1,4 @@
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, vi } from 'vitest';
 import { render } from '@testing-library/react';
 import { LinearDocView } from '../LinearDocView';
 import type { Doc, Block } from '@bendyline/squisq/schemas';
@@ -279,3 +279,55 @@ describe('LinearDocView', () => {
     expect(el.style.background).toBe(probe.style.background);
   });
 });
+
+describe('LinearDocView markdown prop', () => {
+  it('renders from the markdown prop when no doc is given', () => {
+    const { container } = render(<LinearDocView markdown={'# From Markdown\n\nParagraph body.'} />);
+    expect(container.textContent).toContain('From Markdown');
+    expect(container.textContent).toContain('Paragraph body.');
+  });
+
+  it('doc wins over markdown when both are provided', () => {
+    const doc = mkDoc([mkBlock({ id: 'b', contents: [paragraph(text('Doc body wins'))] })]);
+    const { container } = render(<LinearDocView doc={doc} markdown="# Markdown Loses" />);
+    expect(container.textContent).toContain('Doc body wins');
+    expect(container.textContent).not.toContain('Markdown Loses');
+  });
+
+  it('renders an empty container when neither doc nor markdown is given', () => {
+    const { container } = render(<LinearDocView />);
+    expect(container.querySelector('.squisq-linear--empty')).toBeTruthy();
+  });
+});
+
+describe('LinearDocView unknown template annotations', () => {
+  it('warns once per unknown template name and falls back to plain markdown', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const doc = mkDoc([
+      mkBlock({
+        id: 'unknown-1',
+        sourceHeading: {
+          type: 'heading',
+          depth: 2,
+          children: [text('Mystery Section')],
+          templateAnnotation: { template: 'no-such-template-xyz' },
+        },
+        contents: [paragraph(text('Fallback body content'))],
+      }),
+    ]);
+
+    const { container } = render(<LinearDocView doc={doc} />);
+    // Renders as plain markdown: heading + body, no SVG card.
+    expect(container.textContent).toContain('Mystery Section');
+    expect(container.textContent).toContain('Fallback body content');
+    expect(container.querySelector('.squisq-linear-card')).toBeNull();
+
+    // Re-render: the warning stays one-shot per unknown template name.
+    render(<LinearDocView doc={doc} />);
+    const sentinelCalls = warnSpy.mock.calls.filter((c) =>
+      String(c[0]).includes('no-such-template-xyz'),
+    );
+    expect(sentinelCalls.length).toBe(1);
+    warnSpy.mockRestore();
+  });
+});

package/src/__tests__/MarkdownRenderer.test.tsx

@@ -102,6 +102,24 @@ describe('MarkdownRenderer', () => {
     expect(container.innerHTML).not.toContain('javascript:');
   });
 
+  it('linkSchemes allows a host scheme as a real anchor, never executable ones', () => {
+    const nodes = parseNodes('[a](gezel-nav:src%2Fa.ts) [b](javascript:alert(1))');
+    const blocked = render(<MarkdownRenderer nodes={nodes} />);
+    expect(blocked.container.querySelector('a.squisq-md-link')).toBeNull();
+
+    const allowed = render(<MarkdownRenderer nodes={nodes} linkSchemes={['gezel-nav']} />);
+    const a = allowed.container.querySelector('a.squisq-md-link') as HTMLAnchorElement;
+    expect(a?.getAttribute('href')).toBe('gezel-nav:src%2Fa.ts');
+    // javascript: stays blocked even when a host lists it
+    const evil = render(
+      <MarkdownRenderer
+        nodes={parseNodes('[b](javascript:alert(1))')}
+        linkSchemes={['javascript']}
+      />,
+    );
+    expect(evil.container.querySelector('a.squisq-md-link')).toBeNull();
+  });
+
   it('renders an image', () => {
     const nodes: MarkdownBlockNode[] = [
       paragraph({

package/src/__tests__/useJsonViewTokens.test.ts

@@ -0,0 +1,41 @@
+import { describe, it, expect, afterEach, vi } from 'vitest';
+import { renderHook } from '@testing-library/react';
+import { DARK_SURFACE, LIGHT_SURFACE, DEFAULT_THEME } from '@bendyline/squisq/schemas';
+import { useJsonViewTokens } from '../jsonView/useJsonViewTokens';
+
+type StyleBag = Record<string, string>;
+
+function mockPrefersDark(dark: boolean): void {
+  Object.defineProperty(window, 'matchMedia', {
+    configurable: true,
+    value: (query: string) => ({
+      matches: dark && query.includes('dark'),
+      media: query,
+      onchange: null,
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      dispatchEvent: vi.fn(() => false),
+    }),
+  });
+}
+
+describe('useJsonViewTokens', () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  it('emits json-prefixed tokens for a static surface', () => {
+    const { result } = renderHook(() => useJsonViewTokens(DEFAULT_THEME, LIGHT_SURFACE));
+    const style = result.current.style as StyleBag;
+    expect(style['--squisq-json-bg']).toBe(LIGHT_SURFACE.background);
+    expect(style['--squisq-json-text']).toBe(LIGHT_SURFACE.text);
+  });
+
+  it("tracks a dark OS preference under surface='auto'", () => {
+    mockPrefersDark(true);
+    const { result } = renderHook(() => useJsonViewTokens(DEFAULT_THEME, 'auto'));
+    const style = result.current.style as StyleBag;
+    expect(style['--squisq-json-bg']).toBe(DARK_SURFACE.background);
+    expect(result.current.theme.colors.background).toBe(DARK_SURFACE.background);
+  });
+});