@bendyline/squisq-react 1.1.2 → 1.3.0

package/src/MarkdownRenderer.tsx

@@ -21,8 +21,12 @@ import type {
   MarkdownListItem,
   MarkdownTableRow,
   MarkdownTableCell,
+  HtmlNode,
+  HtmlElement,
 } from '@bendyline/squisq/markdown';
 import { useMediaUrl } from './hooks/MediaContext';
+import { InlineVideoPlayer } from './InlineVideoPlayer.js';
+import { InlineAudioPlayer } from './InlineAudioPlayer.js';
 
 // ── Props ──────────────────────────────────────────────────────────
 
@@ -40,8 +44,25 @@ function renderInline(nodes: MarkdownInlineNode[], keyPrefix = ''): React.ReactN
   return nodes.map((node, i) => {
     const key = `${keyPrefix}i${i}`;
     switch (node.type) {
-      case 'text':
-        return <Fragment key={key}>{node.value}</Fragment>;
+      case 'text': {
+        // Soft breaks (newlines without two trailing spaces) become \n in
+        // text nodes. HTML collapses \n to whitespace, which loses the visual
+        // line break the author wanted, so render <br> for each newline.
+        if (!node.value.includes('\n')) {
+          return <Fragment key={key}>{node.value}</Fragment>;
+        }
+        const parts = node.value.split('\n');
+        return (
+          <Fragment key={key}>
+            {parts.map((part, j) => (
+              <Fragment key={j}>
+                {j > 0 && <br />}
+                {part}
+              </Fragment>
+            ))}
+          </Fragment>
+        );
+      }
 
       case 'emphasis':
         return (
@@ -101,12 +122,23 @@ function renderInline(nodes: MarkdownInlineNode[], keyPrefix = ''): React.ReactN
         );
 
       case 'htmlInline':
+        // Fast path: no <video>/<audio> in the subtree → use the original
+        // rawHtml passthrough (preserves arbitrary HTML for custom embeds).
+        if (!containsMediaTag(node.htmlChildren)) {
+          return (
+            <span
+              key={key}
+              className="squisq-md-html-inline"
+              dangerouslySetInnerHTML={{ __html: node.rawHtml }}
+            />
+          );
+        }
+        // Otherwise reconstruct the subtree as React so <video>/<audio>
+        // go through MediaContext-aware player components.
         return (
-          <span
-            key={key}
-            className="squisq-md-html-inline"
-            dangerouslySetInnerHTML={{ __html: node.rawHtml }}
-          />
+          <span key={key} className="squisq-md-html-inline">
+            {renderHtmlNodes(node.htmlChildren, `${key}h`)}
+          </span>
         );
 
       case 'footnoteReference':
@@ -138,6 +170,20 @@ function renderInline(nodes: MarkdownInlineNode[], keyPrefix = ''): React.ReactN
           </span>
         );
 
+      case 'mention':
+        return (
+          <span
+            key={key}
+            className="squisq-md-mention mention"
+            data-mention="true"
+            data-kind={node.targetKind}
+            data-id={node.targetId}
+            data-label={node.displayName}
+          >
+            @{node.displayName}
+          </span>
+        );
+
       default:
         return null;
     }
@@ -200,12 +246,23 @@ function renderBlock(node: MarkdownBlockNode, key: string): React.ReactNode {
       return renderTable(node.children, node.align, key);
 
     case 'htmlBlock':
+      // Fast path: no <video>/<audio> → preserve the existing rawHtml
+      // passthrough so arbitrary HTML embeds still survive verbatim.
+      if (!containsMediaTag(node.htmlChildren)) {
+        return (
+          <div
+            key={key}
+            className="squisq-md-html-block"
+            dangerouslySetInnerHTML={{ __html: node.rawHtml }}
+          />
+        );
+      }
+      // Otherwise reconstruct subtree as React so <video>/<audio>
+      // route through the player components and resolve via MediaContext.
       return (
-        <div
-          key={key}
-          className="squisq-md-html-block"
-          dangerouslySetInnerHTML={{ __html: node.rawHtml }}
-        />
+        <div key={key} className="squisq-md-html-block">
+          {renderHtmlNodes(node.htmlChildren, `${key}h`)}
+        </div>
       );
 
     case 'math':
@@ -346,6 +403,126 @@ function MdImage({ src, alt, title }: { src: string; alt: string; title?: string
   return <img className="squisq-md-image" src={resolved} alt={alt} title={title} />;
 }
 
+// ── Raw-HTML walker (intercepts <video>/<audio>) ─────────────────
+
+/** True when the htmlElement subtree contains a tag we want to swap
+ *  for a React component. Cheap recursive scan — lets us keep the
+ *  `dangerouslySetInnerHTML` fast path for everything else. */
+function containsMediaTag(nodes: HtmlNode[]): boolean {
+  for (const node of nodes) {
+    if (node.type !== 'htmlElement') continue;
+    if (node.tagName === 'video' || node.tagName === 'audio') return true;
+    if (containsMediaTag(node.children)) return true;
+  }
+  return false;
+}
+
+/** A pragmatic shortlist of HTML attributes the raw-HTML walker
+ *  passes through to React when reconstructing a non-media element.
+ *  Anything outside this list is silently dropped — the media-tag
+ *  fast path means most authors will never hit this code, so we
+ *  keep the surface narrow to avoid React warnings about unknown
+ *  attributes. */
+const PASSTHROUGH_ATTRS: Record<string, string> = {
+  // common
+  class: 'className',
+  id: 'id',
+  title: 'title',
+  style: 'style',
+  // media-adjacent (used when video/audio appear inside other wrappers)
+  width: 'width',
+  height: 'height',
+  // anchor
+  href: 'href',
+  target: 'target',
+  rel: 'rel',
+};
+
+function reactPropsFromAttrs(attrs: Record<string, string>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [name, value] of Object.entries(attrs)) {
+    const propName = PASSTHROUGH_ATTRS[name];
+    if (!propName) continue;
+    if (propName === 'style') {
+      // We can't safely parse arbitrary `style="..."` strings without
+      // an HTML parser; preserve as a data attribute so authors can
+      // see it survived round-trip without crashing React.
+      out['data-style'] = value;
+      continue;
+    }
+    out[propName] = value;
+  }
+  return out;
+}
+
+function renderHtmlElement(el: HtmlElement, key: string): React.ReactNode {
+  if (el.tagName === 'video') {
+    return (
+      <InlineVideoPlayer
+        key={key}
+        src={el.attributes.src ?? ''}
+        width={el.attributes.width}
+        height={el.attributes.height}
+        poster={el.attributes.poster}
+        // The `controls` attribute is a boolean — present means true,
+        // even if its value is an empty string.
+        controls={'controls' in el.attributes}
+        preload={
+          el.attributes.preload === 'none' ||
+          el.attributes.preload === 'metadata' ||
+          el.attributes.preload === 'auto'
+            ? el.attributes.preload
+            : undefined
+        }
+      />
+    );
+  }
+  if (el.tagName === 'audio') {
+    return (
+      <InlineAudioPlayer
+        key={key}
+        src={el.attributes.src ?? ''}
+        controls={'controls' in el.attributes}
+        preload={
+          el.attributes.preload === 'none' ||
+          el.attributes.preload === 'metadata' ||
+          el.attributes.preload === 'auto'
+            ? el.attributes.preload
+            : undefined
+        }
+      />
+    );
+  }
+
+  const Tag = el.tagName as keyof JSX.IntrinsicElements;
+  const props = reactPropsFromAttrs(el.attributes);
+  if (el.selfClosing) {
+    return <Tag key={key} {...props} />;
+  }
+  return (
+    <Tag key={key} {...props}>
+      {renderHtmlNodes(el.children, `${key}c`)}
+    </Tag>
+  );
+}
+
+function renderHtmlNodes(nodes: HtmlNode[], keyPrefix: string): React.ReactNode[] {
+  return nodes.map((node, i) => {
+    const key = `${keyPrefix}${i}`;
+    switch (node.type) {
+      case 'htmlElement':
+        return renderHtmlElement(node, key);
+      case 'htmlText':
+        return <Fragment key={key}>{node.value}</Fragment>;
+      case 'htmlComment':
+        // Comments don't render in React; ignore.
+        return null;
+      default:
+        return null;
+    }
+  });
+}
+
 // ── Main Component ─────────────────────────────────────────────────
 
 /**

package/src/SocialCaptionOverlay.tsx

@@ -17,6 +17,7 @@
 import { useMemo } from 'react';
 import type { CaptionTrack, CaptionPhrase, ViewportConfig } from '@bendyline/squisq/schemas';
 import type { Theme } from '@bendyline/squisq/schemas';
+import { resolveFontFamily } from '@bendyline/squisq/schemas';
 
 /** Target words per visible chunk. */
 const TARGET_CHUNK_SIZE = 4;
@@ -196,8 +197,8 @@ export function SocialCaptionOverlay({
 
   // Theme-derived styling
   const primaryColor = theme?.colors?.primary ?? '#5b9bd5';
-  const fontFamily = theme?.typography?.titleFontFamily
-    ? `"${theme.typography.titleFontFamily}", system-ui, sans-serif`
+  const fontFamily = theme?.typography?.titleFont
+    ? resolveFontFamily(theme.typography.titleFont, '"PT Serif", Georgia, serif')
     : '"PT Serif", Georgia, serif';
 
   // Scale font to viewport — aim for ~5.5% of viewport height

package/src/__tests__/JsonView.test.tsx

@@ -0,0 +1,111 @@
+import { describe, it, expect } from 'vitest';
+import { render } from '@testing-library/react';
+import { JsonView } from '../jsonView';
+import type { SquisqAnnotatedSchema } from '@bendyline/squisq/jsonForm';
+
+describe('JsonView', () => {
+  it('renders an object schema as labeled rows', () => {
+    const schema: SquisqAnnotatedSchema = {
+      type: 'object',
+      properties: {
+        title: { type: 'string', title: 'Page Title' },
+        active: { type: 'boolean' },
+      },
+    };
+    const { container } = render(
+      <JsonView schema={schema} value={{ title: 'Hello', active: true }} />,
+    );
+    expect(container.textContent).toContain('Page Title');
+    expect(container.textContent).toContain('Hello');
+    expect(container.textContent).toContain('On');
+  });
+
+  it('renders an array of primitives as chips', () => {
+    const schema: SquisqAnnotatedSchema = {
+      type: 'array',
+      items: { type: 'string' },
+    };
+    const { container } = render(<JsonView schema={schema} value={['a', 'b', 'c']} />);
+    expect(container.querySelectorAll('.squisq-jv-chip')).toHaveLength(3);
+  });
+
+  it('renders an array of objects as cards with itemLabel.fromField', () => {
+    const schema: SquisqAnnotatedSchema = {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          heading: { type: 'string' },
+          body: { type: 'string' },
+        },
+        squisq: { itemLabel: { fromField: 'heading' } },
+      },
+    };
+    const { container } = render(
+      <JsonView
+        schema={schema}
+        value={[
+          { heading: 'Section A', body: 'Body A' },
+          { heading: 'Section B', body: 'Body B' },
+        ]}
+      />,
+    );
+    const cards = container.querySelectorAll('.squisq-jv-card');
+    expect(cards).toHaveLength(2);
+    expect(cards[0].textContent).toContain('Section A');
+    expect(cards[1].textContent).toContain('Section B');
+  });
+
+  it('renders a color value as a swatch + hex', () => {
+    const schema: SquisqAnnotatedSchema = {
+      type: 'string',
+      format: 'color',
+    };
+    const { container } = render(<JsonView schema={schema} value="#ff0080" />);
+    const swatch = container.querySelector('.squisq-jv-color__swatch') as HTMLElement | null;
+    expect(swatch).not.toBeNull();
+    expect(swatch?.style.background).toContain('rgb(255, 0, 128)');
+    expect(container.textContent).toContain('#ff0080');
+  });
+
+  it('hides fields whose squisq.hidden rule matches', () => {
+    const schema: SquisqAnnotatedSchema = {
+      type: 'object',
+      properties: {
+        showAuthor: { type: 'boolean' },
+        authorName: {
+          type: 'string',
+          squisq: { hidden: { field: 'showAuthor', truthy: false } },
+        },
+      },
+    };
+    const visible = render(
+      <JsonView schema={schema} value={{ showAuthor: true, authorName: 'Alex' }} />,
+    );
+    expect(visible.container.textContent).toContain('Alex');
+
+    const hidden = render(
+      <JsonView schema={schema} value={{ showAuthor: false, authorName: 'Alex' }} />,
+    );
+    expect(hidden.container.textContent).not.toContain('Alex');
+  });
+
+  it('renders empty values as the em-dash placeholder', () => {
+    const schema: SquisqAnnotatedSchema = {
+      type: 'object',
+      properties: { title: { type: 'string' } },
+    };
+    const { container } = render(<JsonView schema={schema} value={{}} />);
+    expect(container.textContent).toContain('—');
+  });
+
+  it('respects squisq.enumLabels when displaying enum values', () => {
+    const schema: SquisqAnnotatedSchema = {
+      type: 'string',
+      enum: ['s', 'm', 'l'],
+      squisq: { enumLabels: { s: 'Small', m: 'Medium', l: 'Large' } },
+    };
+    const { container } = render(<JsonView schema={schema} value="m" />);
+    expect(container.textContent).toContain('Medium');
+  });
+});

package/src/__tests__/LinearDocView.test.tsx

@@ -2,6 +2,7 @@ import { describe, it, expect } from 'vitest';
 import { render } from '@testing-library/react';
 import { LinearDocView } from '../LinearDocView';
 import type { Doc, Block } from '@bendyline/squisq/schemas';
+import { DARK_SURFACE, DEFAULT_THEME, LIGHT_SURFACE } from '@bendyline/squisq/schemas';
 import type {
   MarkdownBlockNode,
   MarkdownInlineNode,
@@ -84,6 +85,72 @@ describe('LinearDocView', () => {
     expect(container.textContent).toContain('Section body text');
   });
 
+  it('feeds imageWithCaption blocks the first body image as imageSrc', () => {
+    // Regression: without auto-extracting imageSrc from contents, the
+    // template renders a layer with `src=undefined` and the SVG card
+    // shows a broken image in document (linear) mode.
+    const doc = mkDoc([
+      mkBlock({
+        id: 'img-1',
+        sourceHeading: {
+          type: 'heading',
+          depth: 1,
+          children: [text('Mike Ammerlaan')],
+          templateAnnotation: { template: 'imageWithCaption' },
+        },
+        contents: [paragraph({ type: 'image', url: 'mikehome_files/profile.png', alt: 'Mike' })],
+      }),
+    ]);
+    const { container } = render(<LinearDocView doc={doc} />);
+    const card = container.querySelector('.squisq-linear-card');
+    expect(card).toBeTruthy();
+    const img = card!.querySelector('image, img') as Element | null;
+    expect(img).toBeTruthy();
+    const href =
+      img!.getAttribute('href') ?? img!.getAttribute('xlink:href') ?? img!.getAttribute('src');
+    expect(href).toContain('mikehome_files/profile.png');
+  });
+
+  it('extracts imageSrc from raw HTML <img> (resized image)', () => {
+    // The WYSIWYG editor emits `<img src width>` for resized images
+    // because markdown shorthand has no width syntax. The linear view
+    // must read that form too, or every resized imageWithCaption block
+    // renders as a broken card.
+    const doc = mkDoc([
+      mkBlock({
+        id: 'img-2',
+        sourceHeading: {
+          type: 'heading',
+          depth: 1,
+          children: [text('Resized')],
+          templateAnnotation: { template: 'imageWithCaption' },
+        },
+        contents: [
+          {
+            type: 'htmlBlock',
+            rawHtml: '<img alt="resized" src="resized.png" width="194">',
+            htmlChildren: [
+              {
+                type: 'htmlElement',
+                tagName: 'img',
+                attributes: { src: 'resized.png', alt: 'resized', width: '194' },
+                children: [],
+                selfClosing: true,
+              },
+            ],
+          } as unknown as MarkdownBlockNode,
+        ],
+      }),
+    ]);
+    const { container } = render(<LinearDocView doc={doc} />);
+    const card = container.querySelector('.squisq-linear-card');
+    expect(card).toBeTruthy();
+    const img = card!.querySelector('image, img') as Element | null;
+    const href =
+      img?.getAttribute('href') ?? img?.getAttribute('xlink:href') ?? img?.getAttribute('src');
+    expect(href).toContain('resized.png');
+  });
+
   it('renders annotated block as SVG card', () => {
     const doc = mkDoc([
       mkBlock({
@@ -177,4 +244,38 @@ describe('LinearDocView', () => {
     expect(container.querySelector('[data-block-id="alpha"]')).toBeTruthy();
     expect(container.querySelector('[data-block-id="beta"]')).toBeTruthy();
   });
+
+  it('uses the theme background by default', () => {
+    const doc = mkDoc([mkBlock({ id: 'b', contents: [paragraph(text('hi'))] })]);
+    const { container } = render(<LinearDocView doc={doc} />);
+    const el = container.querySelector('.squisq-linear') as HTMLElement;
+    expect(el.style.background).toBeTruthy();
+    // DEFAULT_THEME has a specific background; applying LIGHT_SURFACE below
+    // must produce a different value to prove override is working.
+    expect(el.style.background).not.toBe(LIGHT_SURFACE.background);
+  });
+
+  it('light surface overlays the theme background', () => {
+    const doc = mkDoc([mkBlock({ id: 'b', contents: [paragraph(text('hi'))] })]);
+    const { container } = render(
+      <LinearDocView doc={doc} theme={DEFAULT_THEME} surface={LIGHT_SURFACE} />,
+    );
+    const el = container.querySelector('.squisq-linear') as HTMLElement;
+    // React inline style background may round-trip as hex or rgb; compare the
+    // colour-normalized value by mounting a plain div with the expected.
+    const probe = document.createElement('div');
+    probe.style.background = LIGHT_SURFACE.background;
+    expect(el.style.background).toBe(probe.style.background);
+  });
+
+  it('dark surface overlays the theme background', () => {
+    const doc = mkDoc([mkBlock({ id: 'b', contents: [paragraph(text('hi'))] })]);
+    const { container } = render(
+      <LinearDocView doc={doc} theme={DEFAULT_THEME} surface={DARK_SURFACE} />,
+    );
+    const el = container.querySelector('.squisq-linear') as HTMLElement;
+    const probe = document.createElement('div');
+    probe.style.background = DARK_SURFACE.background;
+    expect(el.style.background).toBe(probe.style.background);
+  });
 });

package/src/hooks/MediaContext.tsx

@@ -41,17 +41,24 @@ export function useMediaProvider(): MediaProvider | null {
 export function useMediaUrl(relativePath: string, basePath: string): string {
   const provider = useMediaProvider();
 
+  // Defensive: callers (esp. preview surfaces like InlinePreviewGutter)
+  // sometimes feed in template-generated layers whose `content.src` is
+  // undefined while the user is still authoring the block. Treat that
+  // as an empty string rather than crashing the whole React tree.
+  const safePath = typeof relativePath === 'string' ? relativePath : '';
+
   // For absolute/http URLs, skip resolution entirely
   const isAbsolute =
-    relativePath.startsWith('http') ||
-    relativePath.startsWith('/') ||
-    relativePath.startsWith('data:') ||
-    relativePath.startsWith('blob:');
+    !safePath ||
+    safePath.startsWith('http') ||
+    safePath.startsWith('/') ||
+    safePath.startsWith('data:') ||
+    safePath.startsWith('blob:');
 
   // Memoize fallback to avoid recalculating on every render
   const fallback = useMemo(
-    () => (isAbsolute ? relativePath : `${basePath}/${relativePath}`),
-    [isAbsolute, relativePath, basePath],
+    () => (isAbsolute ? safePath : `${basePath}/${safePath}`),
+    [isAbsolute, safePath, basePath],
   );
 
   // Fast path: no provider or absolute URL — return synchronously, skip effect entirely
@@ -66,14 +73,14 @@ export function useMediaUrl(relativePath: string, basePath: string): string {
     }
 
     let cancelled = false;
-    provider!.resolveUrl(relativePath).then((resolved) => {
+    provider!.resolveUrl(safePath).then((resolved) => {
       if (!cancelled) setUrl(resolved);
     });
 
     return () => {
       cancelled = true;
     };
-  }, [needsProvider, provider, relativePath, fallback]);
+  }, [needsProvider, provider, safePath, fallback]);
 
   // When provider is not needed, return fallback directly to avoid
   // the one-frame delay from the initial useState → useEffect cycle

package/src/hooks/useAutoSurface.ts

@@ -0,0 +1,33 @@
+import { useCallback, useMemo, useSyncExternalStore } from 'react';
+import { DARK_SURFACE, LIGHT_SURFACE, type SurfaceScheme } from '@bendyline/squisq/schemas';
+
+const DARK_QUERY = '(prefers-color-scheme: dark)';
+const getServerSnapshot = () => LIGHT_SURFACE;
+
+/**
+ * Live-track `prefers-color-scheme` and return a stable SurfaceScheme.
+ * `enabled: false` short-circuits to LIGHT_SURFACE (callers pass `false`
+ * when a static surface was provided so the hook never observes the
+ * media query). The `MediaQueryList` and the `subscribe`/`getSnapshot`
+ * callbacks are memoized so `useSyncExternalStore` doesn't resubscribe on
+ * every parent render.
+ */
+export function useAutoSurface(enabled: boolean): SurfaceScheme {
+  const mql = useMemo(
+    () => (enabled && typeof window !== 'undefined' ? window.matchMedia(DARK_QUERY) : null),
+    [enabled],
+  );
+
+  const subscribe = useCallback(
+    (cb: () => void) => {
+      if (!mql) return () => {};
+      mql.addEventListener('change', cb);
+      return () => mql.removeEventListener('change', cb);
+    },
+    [mql],
+  );
+
+  const getSnapshot = useCallback(() => (mql?.matches ? DARK_SURFACE : LIGHT_SURFACE), [mql]);
+
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}

package/src/index.ts

@@ -11,6 +11,11 @@ export { DocPlayerWithSidebar } from './DocPlayerWithSidebar.js';
 export { DocProgressBar } from './DocProgressBar.js';
 export { MarkdownRenderer } from './MarkdownRenderer.js';
 export { LinearDocView } from './LinearDocView.js';
+export type { LinearDocViewProps, ImageDisplayMode } from './LinearDocView.js';
+export { InlineVideoPlayer } from './InlineVideoPlayer.js';
+export type { InlineVideoPlayerProps } from './InlineVideoPlayer.js';
+export { InlineAudioPlayer } from './InlineAudioPlayer.js';
+export type { InlineAudioPlayerProps } from './InlineAudioPlayer.js';
 
 // Layer components
 export { ImageLayer } from './layers/ImageLayer.js';
@@ -25,6 +30,7 @@ export { useAudioSync } from './hooks/useAudioSync.js';
 export { useDocPlayback } from './hooks/useDocPlayback.js';
 export { useViewportOrientation } from './hooks/useViewportOrientation.js';
 export { MediaContext, useMediaProvider, useMediaUrl } from './hooks/MediaContext.js';
+export { useAutoSurface } from './hooks/useAutoSurface.js';
 
 // Types
 export type { AudioProvider, AudioState, AudioActions } from './hooks/AudioProvider.js';
@@ -48,3 +54,7 @@ export { formatTime } from './types.js';
 
 // Utilities
 export { getAnimationStyle, getTransitionClass } from './utils/animationUtils.js';
+
+// JSON Form — read-only viewer
+export { JsonView } from './jsonView/index.js';
+export type { JsonViewProps } from './jsonView/index.js';

package/src/jsonView/JsonView.tsx

@@ -0,0 +1,51 @@
+/**
+ * <JsonView>
+ *
+ * Read-only renderer for any JSON value bound to a JSON Schema (with
+ * optional Squisq UI hints). Designed to look like a polished settings
+ * summary or CRM record — not a disabled form. Themable via the
+ * standard Theme + SurfaceScheme props used elsewhere in Squisq.
+ */
+
+import type { SquisqAnnotatedSchema } from '@bendyline/squisq/jsonForm';
+import type { SurfaceScheme, Theme } from '@bendyline/squisq/schemas';
+import { useJsonViewTokens } from './useJsonViewTokens';
+import { RenderNode } from './RenderNode';
+
+export interface JsonViewProps {
+  /** Schema describing the value's shape (with optional `squisq` UI hints). */
+  schema: SquisqAnnotatedSchema;
+  /** The value to display. */
+  value: unknown;
+  /** Optional theme. Defaults to `DEFAULT_THEME`. */
+  theme?: Theme;
+  /** Light/dark surface override; `'auto'` follows `prefers-color-scheme`. */
+  surface?: SurfaceScheme | 'auto';
+  /** Padding/gap density. Default: 'comfortable'. */
+  density?: 'comfortable' | 'compact';
+  /** Optional CSS class for the outer container. */
+  className?: string;
+}
+
+export function JsonView(props: JsonViewProps) {
+  const { schema, value, theme, surface, density = 'comfortable', className } = props;
+  const { style } = useJsonViewTokens(theme, surface);
+
+  const cls =
+    'squisq-json-view' +
+    (density === 'compact' ? ' squisq-json-view--compact' : '') +
+    (className ? ` ${className}` : '');
+
+  return (
+    <div className={cls} style={style}>
+      <RenderNode
+        value={value}
+        schema={schema}
+        rootSchema={schema}
+        rootData={value}
+        pointer=""
+        density={density}
+      />
+    </div>
+  );
+}