> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kiwifs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Widgets

> Fenced blocks that render as interactive diagrams, data structures, charts, quizzes, and queries in the web UI, and stay readable as plain markdown.

A widget is a fenced code block whose body describes a picture or a behavior. The web UI renders it interactively. Everywhere else (`cat`, git diffs, PDF export, search) it stays readable text, because the file holds data, not a program.

Most widgets are **typed fences**: a YAML body checked against a schema. KiwiFS rejects a broken one on write, renders it in the web UI, and steps through it on a playback clock that a reader can link to.

````markdown theme={null}
```array id=two-sum caption="Two-pointer sweep on a sorted array"
values: [2, 7, 11, 15, 19]
pointers:
  - {index: 0, label: lo}
  - {index: 4, label: hi}
steps:
  - note: "2 + 19 = 21 > 9, so move hi left"
    activeIndices: [0, 4]
  - note: "2 + 15 = 17 > 9, so move hi left"
    pointers: [{index: 0, label: lo}, {index: 3, label: hi}]
  - note: "2 + 7 = 9, found it"
    pointers: [{index: 0, label: lo}, {index: 1, label: hi}]
    activeIndices: [0, 1]
```
````

## Catalog

### Data structures

> [card] [array](https://docs.kiwifs.com/widgets/data-structures.md#array)
>
> Arrays with pointers, spans, and dependency arrows.

> [card] [matrix](https://docs.kiwifs.com/widgets/data-structures.md#matrix)
>
> DP tables, grids, heatmaps, adjacency matrices.

> [card] [table](https://docs.kiwifs.com/widgets/data-structures.md#table)
>
> Named-column rows: schemas, lock tables, decision tables.

> [card] [tree](https://docs.kiwifs.com/widgets/data-structures.md#tree)
>
> BSTs, tries, heaps, union-find forests, B-tree pages.

> [card] [list](https://docs.kiwifs.com/widgets/data-structures.md#list)
>
> Linked lists, including cycles and random pointers.

> [card] [stack](https://docs.kiwifs.com/widgets/data-structures.md#stack)
>
> LIFO stacks: call stacks, undo histories.

> [card] [queue](https://docs.kiwifs.com/widgets/data-structures.md#queue)
>
> FIFO queues and ring buffers.

> [card] [map](https://docs.kiwifs.com/widgets/data-structures.md#map)
>
> Hash tables, probe paths, plain dictionaries.

> [card] [bits](https://docs.kiwifs.com/widgets/data-structures.md#bits)
>
> Bitmasks, flag registers, float layouts.

> [card] [memory](https://docs.kiwifs.com/widgets/data-structures.md#memory)
>
> Stack frames, heap objects, and the pointers between them.

### Charts and plots

> [card] [plot](https://docs.kiwifs.com/widgets/charts.md#plot)
>
> x-y curves, formulas, shaded regions.

> [card] [bars](https://docs.kiwifs.com/widgets/charts.md#bars)
>
> Columns in value space: histograms, distributions.

> [card] [numberline](https://docs.kiwifs.com/widgets/charts.md#numberline)
>
> One value axis: intervals, thresholds, SLOs.

> [card] [plane](https://docs.kiwifs.com/widgets/charts.md#plane)
>
> Coordinate geometry: points, polygons, vectors.

> [card] [timeline](https://docs.kiwifs.com/widgets/charts.md#timeline)
>
> Spans in lanes with causal arrows.

> [card] [kiwi-chart](https://docs.kiwifs.com/widgets/charts.md#kiwi-chart)
>
> Bar, line, area, pie, radar, and scatter charts from data or DQL.

> [card] [kiwi-progress](https://docs.kiwifs.com/widgets/charts.md#kiwi-progress)
>
> Progress bars and gauges.

### Diagrams

> [card] [graph](https://docs.kiwifs.com/widgets/diagrams.md#graph)
>
> Nodes and edges: architecture, state machines, DAGs.

> [card] [sequence](https://docs.kiwifs.com/widgets/diagrams.md#sequence)
>
> Message flows between participants, one hop per step.

> [card] [steps](https://docs.kiwifs.com/widgets/diagrams.md#steps)
>
> A Mermaid diagram walked through one step at a time.

> [card] [mermaid](https://docs.kiwifs.com/widgets/diagrams.md#mermaid)
>
> Standard Mermaid diagrams with clickable nodes.

> [card] [d2](https://docs.kiwifs.com/widgets/diagrams.md#d2)
>
> D2 diagrams rendered to SVG by the server.

> [card] [Drawing embeds](https://docs.kiwifs.com/widgets/diagrams.md#drawing-embeds)
>
> Excalidraw and canvas files embedded inline.

### Interactive and learning

> [card] [Quiz callouts](https://docs.kiwifs.com/widgets/interactive.md#quiz-callouts)
>
> Six question types. Answer keys stay out of search.

> [card] [kiwi-calc](https://docs.kiwifs.com/widgets/interactive.md#kiwi-calc)
>
> Back-of-envelope math with tunable assumptions.

> [card] [kiwi-playground](https://docs.kiwifs.com/widgets/interactive.md#kiwi-playground)
>
> Sliders, toggles, and pickers that export a config.

> [card] [kiwi-app](https://docs.kiwifs.com/widgets/interactive.md#kiwi-app)
>
> Sandboxed HTML, CSS, and JavaScript.

> [card] [widget:live](https://docs.kiwifs.com/widgets/interactive.md#live-react-blocks)
>
> React Live code with every widget view in scope.

> [card] [widget:code](https://docs.kiwifs.com/widgets/interactive.md#runnable-code)
>
> Runnable Python (Pyodide) or JavaScript.

### Data and queries

> [card] [kiwi-query](https://docs.kiwifs.com/widgets/data-and-queries.md#kiwi-query)
>
> Live DQL results as a table or list.

> [card] [kiwi-data](https://docs.kiwifs.com/widgets/data-and-queries.md#kiwi-data)
>
> Structured records you can query with `FROM RECORDS`.

> [card] [kiwi-kanban](https://docs.kiwifs.com/widgets/data-and-queries.md#kiwi-kanban)
>
> Drag-and-drop boards from YAML or DQL.

> [card] [widget:tracker](https://docs.kiwifs.com/widgets/data-and-queries.md#progress-tracker)
>
> Per-reader progress across a curriculum.

### Page structure

> [card] [Callouts](https://docs.kiwifs.com/widgets/page-structure.md#callouts)
>
> `> [!NOTE]` and 26 other types, optionally foldable.

> [card] [Tabs and columns](https://docs.kiwifs.com/widgets/page-structure.md#tabs)
>
> `:::tabs` and `:::columns` container directives.

> [card] [Figures](https://docs.kiwifs.com/widgets/page-structure.md#figures)
>
> Wide, full-width, or pinned media with captions.

> [card] [Claims](https://docs.kiwifs.com/widgets/page-structure.md#claims)
>
> Provenance badges, queryable with `FROM CLAIMS`.

> [card] [kiwi-diff](https://docs.kiwifs.com/widgets/page-structure.md#kiwi-diff)
>
> Annotated side-by-side or unified diffs.

> [card] [kiwi-color](https://docs.kiwifs.com/widgets/page-structure.md#kiwi-color)
>
> Color swatches with contrast ratios.

## Fence names

Each typed fence answers to three spellings, plus any aliases listed in its reference entry:

| Spelling | Example | Behavior |
| - | - | - |
| Bare name | `array` | Renders only when the YAML carries one of the fence's marker keys, such as `values` for `array`. Otherwise it stays a code block. |
| `kiwi-` prefix | `kiwi-array` | Strict: always renders, or shows an error. |
| `widget:` prefix | `widget:array` | Strict, same as `kiwi-`. Kept for older pages. |

The marker-key rule means a vault that already uses ` ```tree ` for directory listings, or ` ```table ` for pipe tables, keeps its code blocks. To turn bare names off for a workspace, or allow only some:

```toml .kiwi/config.toml theme={null}
[ui]
typed_fences = false
# or allow only these bare names:
typed_fence_tags = ["array", "matrix", "table"]
```

The `kiwi-` and `widget:` spellings keep working either way.

## Writing a typed fence

The YAML body's top-level keys are the widget's properties. Each fence's reference entry lists them, for example the [array keys](https://docs.kiwifs.com/widgets/data-structures.md#array).

### Steps

An optional `steps:` list turns the widget into a walkthrough. Each step is a shallow patch over the **previous step**, so you write only what changes. Use `frames:` instead when you want each entry applied over the base. A fence uses one or the other, not both.

A step can also carry these keys, which are not widget properties:

| Step key | Meaning |
| - | - |
| `note` | Prose shown under the picture for this step. |
| `line` / `next` | 1-based line of the `code:` listing to highlight. |
| `label` | Name for this step in the playback controls. |
| `why` | Map of part key to explanation, revealed when the reader selects that part. |
| `breakpoint` | Autoplay pauses here. |
| `duration` | Milliseconds this step holds at 1x speed. |
| `expect` | Pause until the reader selects the right part. |

A step can also be a bare string, which is a `note` over unchanged properties. The [`steps` fence](https://docs.kiwifs.com/widgets/diagrams#steps) is the exception to the patch rule: each of its steps stands alone.

Other reserved top-level keys:

| Key | Meaning |
| - | - |
| `code` + `lang` | A code listing that steps in lockstep with the picture. |
| `why` | Map of part key to explanation, revealed when the reader selects that part. Write the reasoning into the file; nothing is generated at read time. |
| `link` | `{to: <widget id>, map: index}`. Selecting a part of this widget lights the matching part of another, such as a heap drawn as both a tree and an array. |
| `props` | Escape hatch for a widget property whose name collides with a reserved key. |
| `caption`, `title`, `id`, `clock`, `width`, `autoplay`, `loop` | Same as the meta string options below. |

A property marked **Fixed across steps** in a key table can only be set at the top level. Setting it inside a step is a lint error.

### Meta string

Options after the fence name on the opening line:

| Option | Meaning |
| - | - |
| `id=name` | Names the widget, its anchor, and its clock. |
| `clock=name` | Shares one step counter with every other fence naming the same clock. |
| `caption="..."` | Caption under the figure. |
| `title="..."` | Heading above it. |
| `width=wide` or `width=full` | Figure width. |
| `autoplay`, `loop` | Playback behavior. |

> [!WARNING]
>
> Widget properties such as `layout: ring` or `direction: LR` belong in the YAML body. The meta string only reads the options in this table.

## Playback

A widget with steps gets playback controls: play and pause, step back and forward, a speed toggle (1x, 2x, 4x), **Copy link to this step**, and **Download this step as an image**. With the widget focused, <kbd>Space</kbd> plays or pauses, the arrow keys step, and <kbd>R</kbd> resets.

The current step lives in the URL fragment, so you can link a reader to one moment:

* `#?step.<id>=N` targets the widget or clock named `<id>`.
* `#?step=N` targets the first unnamed widget on the page.

Give several fences the same `clock=` and one set of controls drives them all. A shorter member holds its last frame while longer ones keep going.

````markdown theme={null}
```steps clock=probe
diagram: |
  flowchart LR
    H[hash key] --> S[slot 3]
    S --> P[probe forward]
steps:
  - {focus: [H], note: "h(mango) = 3"}
  - {focus: [S], note: "Slot 3 is taken"}
  - {focus: [P], note: "Probe forward to slot 4"}
```

```map clock=probe
mode: open
capacity: 8
slots: [null, null, null, {key: apple}, null, null, null, null]
steps:
  - {activeKey: mango, probePath: [3]}
  - {activeSlots: [3], probePath: [3]}
  - {activeSlots: [4], probePath: [3, 4]}
```
````

## Validation

KiwiFS validates typed fences against the same schema the web UI renders from.

* **On write.** Writes through KiwiFS run the markdown linter. With `[lint] reject_errors` on (the default), a page with any error-severity issue is rejected. Errors include broken YAML in a strict fence, a wrong value type, a missing required key, and setting a fixed property inside a step. An unknown key is a warning that suggests the closest valid key.
* **Nothing to draw.** A strict `kiwi-array`, `kiwi-matrix`, `kiwi-tree`, `kiwi-memory`, `kiwi-numberline`, or `kiwi-table` fence with none of its data keys is an error, for example `kiwi-array fence: needs one of "values", "rows"`. A data key introduced in the first step counts.
* **Bare names are lenient.** A bare tag whose YAML doesn't parse gets a warning, not an error, and only when the body plainly looks like that widget.
* **In the web UI.** A fence with errors shows its source with the problems listed, instead of a broken picture.

Check pages before you commit them:

> [tab] CLI
>
> ```bash Terminal theme={null}
> kiwifs lint --root ./knowledge
> ```

> [tab] REST
>
> ```bash Terminal theme={null}
> curl -X POST http://localhost:3333/api/kiwi/lint \
>   -H "Content-Type: application/json" \
>   -d '{"path": "guides/hashing.md"}'
> ```
>
> Pass `content` instead of `path` to lint markdown that isn't saved yet.

> [tab] MCP
>
> Call `kiwi_lint` with `path` or `content`.

## Reference for agents and scripts

The fence catalog is available wherever you write pages:

> [tab] CLI
>
> ```bash Terminal theme={null}
> kiwifs widgets list            # every fence, one line each
> kiwifs widgets list tree       # one fence, key by key
> kiwifs widgets list --json
> ```
>
> `kiwifs widgets suggest [path]` scans for `widget:live` blocks that only call a view component, and prints the typed fence each could become. It never rewrites files. Without a path it scans `--root` (default `./knowledge`).

> [tab] MCP
>
> `kiwi_widget_reference` lists every fence, or describes one in full when you pass `name`. Pass `examples: true` without a name to include each fence's worked example. Write the fence, then verify it with `kiwi_lint`.

## Search and export

Search indexes a typed fence's title, caption, step notes, code listing, and short labels such as node names, not its coordinates. Document export (PDF and other formats) replaces each typed fence with its caption and step notes as a blockquote, followed by the YAML, so a printed page stays readable.

## Related

> [card] [DQL](https://docs.kiwifs.com/concepts/dql.md)
>
> The query language behind `kiwi-query`, `kiwi-chart`, and `FROM RECORDS`.

> [card] [Web UI](https://docs.kiwifs.com/guides/web-ui.md)
>
> Where widgets render, and the editor that writes them.

> [card] [Canvas](https://docs.kiwifs.com/concepts/canvas.md)
>
> Spatial diagrams in `.canvas.json` files.

> [card] [MCP](https://docs.kiwifs.com/concepts/mcp.md)
>
> `kiwi_widget_reference`, `kiwi_lint`, and `kiwi_quiz` for agents.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.