Long URLs and filesystem paths — for example `packages/zudo-doc/src/smart-break/index.tsx` — do not wrap at arbitrary character boundaries. In narrow UI (sidebar labels, breadcrumbs, inline code, search snippets) they overflow the container or push layout wider than it should be.

The package's `smart-break` utility solves this by injecting `<wbr>` (word-break opportunity) hints after each delimiter in strings that look path-like. The browser then decides where to break based on available width.

## Automatic Behavior

Several zudo-doc surfaces already apply smart-break automatically — no configuration needed:

- **Sidebar tree labels** — category and page labels
- **Breadcrumbs** — current-page trail
- **MDX links** — anchor text inside prose
- **MDX inline code** — backtick spans inside prose
- **Search results** — titles and snippets in the search dialog
- **Doc history** — commit message rendering

You only need to invoke the utility yourself when building a custom component that renders user-provided path-like strings.

## Manual Opt-In: `SmartBreak` Component

For client islands (or any `.tsx` component in the project) use the `SmartBreak` component. It stringifies its children and injects `<wbr>` where appropriate:

```tsx
import { SmartBreak } from "@takazudo/zudo-doc/smart-break";

export function FileBadge({ path }: { path: string }) {
  return (
    <span class="font-mono text-caption">
      <SmartBreak>{path}</SmartBreak>
    </span>
  );
}
```

If `path` is not path-like (plain prose, `and/or`, `state-of-the-art`, etc.) it is returned unchanged — no stray wbrs are injected.

## Manual Opt-In: `smartBreakToHtml` Helper

Any code path that renders an HTML string (for example `rawHtml`) cannot mount zudo-react descriptions directly. Use `smartBreakToHtml` instead — it returns an HTML-escaped string with literal `<wbr>` tags injected:

```tsx
import { smartBreakToHtml } from "@takazudo/zudo-doc/smart-break";

export function PathLabel({ label }: { label: string }) {
  return <span rawHtml={smartBreakToHtml(label)} />;
}
```

The returned string is already HTML-escaped, so it is safe to pass to `rawHtml`.

## How It Decides

Smart-break does two things: it classifies the input with an `isPathLike` heuristic, and — only when the heuristic says yes — it splits on a fixed delimiter set and re-joins with `<wbr>` between segments.

### Delimiter Set

Breaks are inserted after each of these characters:

```
/  \  -  _  .  :  ?  #  &  =
```

These cover URL structure (`://`, `?query=value&other=1`, `#anchor`), filesystem paths (`/`, `\`), and compound identifiers (`snake_case`, `kebab-case`, `file.name.ext`).

### The `isPathLike` Heuristic

`isPathLike` returns `true` for strings that look like URLs, paths, or similar delimited structures:

- Contains `://` (any URL)
- Starts with `/`, `./`, or `../` (POSIX paths)
- Starts with a Windows drive prefix like `C:\` or `C:/`
- Has at least two slashes between alphanumerics (nested paths)
- Has a domain-like `a.b` pattern combined with a slash somewhere

It returns `false` for prose-y fragments that happen to contain delimiters: `and/or`, `well-known`, `state-of-the-art`, `1.2.3-beta.4`, `UI/UX`. These pass through unmodified so normal prose wrapping still applies.

### A Realistic Sample

For an input like:

```
packages/zudo-doc/src/smart-break/index.tsx
```

`isPathLike` returns `true` and `smartBreakToHtml` emits (conceptually):

```html
packages<wbr>/zudo<wbr>-doc<wbr>/src<wbr>/smart<wbr>-break<wbr>/index<wbr>.tsx
```

The browser keeps the line intact when the container is wide enough, and breaks at the nearest `<wbr>` when it must — always between segments, never mid-segment.

## When Not to Use It

- Short labels (one or two words) — there is nothing to break.
- Intentional single-token strings where any visual break is wrong (for example a version tag you must never wrap).
- CJK prose — the utility targets Latin-alphabet path-like strings; CJK line-wrapping is handled by the [CJK-friendly markdown](https://zudo-doc.takazudomodular.com/docs/reference/cjk-friendly) plugin and native browser behavior.