# Chunk Boundary Visualizer

Chunk Boundary Visualizer [#chunk-boundary-visualizer]

The **Chunk Boundary Visualizer** shows how a document was split into chunks. Each chunk renders as a distinct alternating-accent segment with a monospace `C1`/`C2` badge; in **semantic mode**, the inter-chunk boundary similarity (e.g. `sim: 0.74`) appears as a faint label between segments — lower values mark stronger topic breaks.

It takes a decoupled `ChunkInfo[]` (`text`, `chunkIndex`, `rightSimilarity`) plus the active mode, so it pairs directly with [`useSemanticChunk()`](https://localmode.dev/docs/react) from `@localmode/react`: map its `Chunk[]` output into `ChunkInfo[]`, pulling `rightSimilarity` from `chunk.metadata.semanticBoundaries`. It is display-only — it owns no chunking logic.

**When to use it:** a RAG ingest UI or a chunking playground where you want users to see *why* the document split where it did (e.g. tuning the semantic threshold).

Preview [#preview]

```tsx
'use client';

import * as React from 'react';
import {
  ChunkBoundaryVisualizer,
  type ChunkInfo,
} from '@/components/chunk-boundary-visualizer';

// Sample of the shape `useSemanticChunk` produces (mapped to ChunkInfo).
// A low rightSimilarity (0.31) marks the strong topic break between the
// privacy chunks and the deployment chunk.
const CHUNKS: ChunkInfo[] = [
  {
    text: 'LocalMode runs ML models entirely in the browser. Data never leaves the device, and there are no servers or API keys to manage.',
    chunkIndex: 0,
    rightSimilarity: 0.78,
  },
  {
    text: 'Embeddings, vector search, and chat all work offline after the initial model download is cached on-device.',
    chunkIndex: 1,
    rightSimilarity: 0.31,
  },
  {
    text: 'To deploy, point Vercel at the app directory and set the public site URL. The build step prerenders the registry JSON.',
    chunkIndex: 2,
    rightSimilarity: null,
  },
];

/**
 * Demo for the ChunkBoundaryVisualizer component, used by the docs live
 * preview. Toggle between semantic mode (shows inter-chunk `sim:` labels) and
 * fixed mode (segments only). Fully presentational — fed pre-computed
 * `ChunkInfo[]`, no model download.
 */
export default function ChunkBoundaryVisualizerDemo() {
  const [semantic, setSemantic] = React.useState(true);

  return (
    <div className="w-full max-w-xl space-y-3">
      <label className="flex items-center gap-2 text-xs text-muted-foreground">
        <input
          type="checkbox"
          checked={semantic}
          onChange={(e) => setSemantic(e.target.checked)}
        />
        Semantic mode (show boundary similarities)
      </label>

      <ChunkBoundaryVisualizer
        chunks={CHUNKS}
        mode={semantic ? 'semantic' : 'fixed'}
      />
    </div>
  );
}
```

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/data-documents/chunk-boundary-visualizer
```

Dependencies [#dependencies]

* **Data source:** renders the plain `ChunkInfo[]` you pass — works with any chunker; recommended LocalMode producer: `useSemanticChunk` output mapped to `ChunkInfo[]` (optional).
* `clsx` + `tailwind-merge` — via the shared `cn()` util (installed automatically as a registry dependency)

Files installed [#files-installed]

* `chunk-boundary-visualizer.tsx` — the component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**ChunkBoundaryVisualizer**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `chunks` | `array` | — | **Required.** The chunks to visualize, in order. Map `useSemanticChunk`'s `Chunk[]` into `ChunkInfo[]` (pulling `rightSimilarity` from `metadata.semanticBoundaries`). |
| `mode` | `object & string \| "recursive" \| "fixed" \| "semantic"` | `"semantic"` | The active chunking mode. In `"semantic"`, inter-chunk similarity labels render between segments; other modes hide them. |
| `maxCharsPerChunk` | `number` | — | Truncate each chunk's preview to this many characters (`0`/undefined shows the full text). |

Examples [#examples]

Visualize `useSemanticChunk` output [#visualize-usesemanticchunk-output]

```tsx
import { ChunkBoundaryVisualizer } from '@/components/chunk-boundary-visualizer';
import { useSemanticChunk } from '@localmode/react';

export function ChunkingPlayground({ model }: { model: any }) {
  const { data: chunks, execute } = useSemanticChunk({ model, threshold: 0.4 });

  return (
    <div>
      <button onClick={() => execute(documentText)}>Chunk</button>
      <ChunkBoundaryVisualizer
        mode="semantic"
        chunks={(chunks ?? []).map((c) => ({
          text: c.text,
          chunkIndex: c.index,
          rightSimilarity: c.metadata?.semanticBoundaries?.rightSimilarity ?? null,
        }))}
      />
    </div>
  );
}
```

Fixed mode (segments only) [#fixed-mode-segments-only]

```tsx
{/* boundary labels are hidden when mode !== "semantic" */}
<ChunkBoundaryVisualizer mode="fixed" chunks={chunks} />
```

Truncate long chunks [#truncate-long-chunks]

```tsx
<ChunkBoundaryVisualizer
  mode="semantic"
  maxCharsPerChunk={160}
  chunks={chunks}
/>
```

Customization [#customization]

Segments cycle through four soft accent tints (`sky` / `violet` / `emerald` / `amber` at low opacity) with shadcn/ui CSS-variable text and borders, so they read as distinct while inheriting your theme. The `C#` badge uses a `font-mono` chip; the boundary label is a faint `sim: 0.NN` between thin rules.

Boundary similarity labels render only when `mode === "semantic"`, the chunk is not the last, and `rightSimilarity` is a finite number — so non-semantic modes show clean segments without labels. Because you own the file, you can swap the `SEGMENT_TINTS` palette, color-code boundaries by threshold, or render the full text instead of truncating in the copied `chunk-boundary-visualizer.tsx`.