arrscope 0.1.0__tar.gz

arrscope-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/
+.ruff_cache/
+.DS_Store
+*.ipynb_checkpoints/

arrscope-0.1.0/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: arrscope
+Version: 0.1.0
+Summary: Beautiful n-dimensional array visualization for Python
+Project-URL: Homepage, https://github.com/vizarray/arrscope
+Project-URL: Repository, https://github.com/vizarray/arrscope
+Author: arrscope contributors
+License: MIT
+Keywords: arrays,data-science,machine-learning,numpy,visualization
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.24
+Requires-Dist: rich>=13.0
+Provides-Extra: jax
+Requires-Dist: jax>=0.4; extra == 'jax'
+Provides-Extra: tf
+Requires-Dist: tensorflow>=2.12; extra == 'tf'
+Provides-Extra: torch
+Requires-Dist: torch>=2.0; extra == 'torch'
+Description-Content-Type: text/markdown
+
+# arrscope
+
+Beautiful n-dimensional array visualization for Python — in the terminal and Jupyter.
+
+```python
+from arrscope import scope
+import numpy as np
+
+scope(np.random.rand(2, 3, 8, 8), axes=['batch', 'heads', 'h', 'w'])
+```
+
+```
+├── [0] (3, 8, 8)
+│   ├── [0,0]: 8×8 grid
+│   ├── [0,1]: 8×8 grid
+│   └── [0,2]: 8×8 grid
+└── [1] (3, 8, 8)
+    ...
+  min=0.001  max=0.999  mean=0.5  std=0.29  zeros=0.0%
+```
+
+## Features
+
+- **1D → 6D+**: Tiered visual grammar — lists, grids, trees, collapsed hierarchies
+- **Named axes**: Attach semantics to dimensions (`batch`, `heads`, `h`, `w`)
+- **Configurable grid**: Pick which axes form the leaf 2D matrix
+- **Three color modes**:
+  - `dtype` — semantic colors by data type (float=blue, int=green, bool=magenta, …)
+  - `heatmap` — diverging colormap (red→light→blue) by value magnitude
+  - `sparsity` — zeros as `·`, non-zeros highlighted in bold
+- **Stats overlay**: min, max, mean, std, zero%, NaN count
+- **Head/tail truncation**: large dimensions show first/last N slices with `…`
+- **Smart precision**: auto-detects significant figures for floats
+- **Terminal + Jupyter**: Rich ANSI output + static HTML/CSS with dark mode
+- **Multi-framework**: NumPy, PyTorch, TensorFlow, JAX (lazy imports, no hard deps)
+
+## Install
+
+```bash
+pip install arrscope
+```
+
+Only requires `numpy` + `rich`. Torch/TF/JAX are optional — pass any array type, it just works.
+
+## Quick start
+
+```python
+from arrscope import scope
+import numpy as np
+
+# Auto-detect — last 2 dims form the grid
+scope(np.random.rand(3, 4, 5))
+
+# Named axes for clarity
+scope(
+    np.random.rand(2, 8, 32, 32),
+    axes=['batch', 'heads', 'h', 'w'],
+    grid=['h', 'w'],
+    title='Attention heads',
+)
+
+# Pick any dims as the leaf grid
+scope(data, axes=['a', 'b', 'c', 'd'], grid=['a', 'b'])
+```
+
+## Color modes
+
+```python
+scope(arr, mode='dtype')        # default — blue floats, green ints, etc.
+scope(arr, mode='heatmap')      # diverging colormap by value
+scope(arr, mode='sparsity')     # · for zeros, bold for non-zeros
+```
+
+## Stats overlay
+
+Stats are shown by default. Hide with:
+
+```python
+scope(arr, stats=False)
+```
+
+Shows: `min=0.0  max=1.0  mean=0.5  std=0.29  zeros=12.5%`
+
+## Truncation
+
+```python
+scope(np.random.rand(100, 32, 32), max_height=8)
+```
+
+Shows first 4 + last 4 slices with `… (92 more)` in between.
+
+## Custom formatting
+
+```python
+scope(arr, fmt='.2f')          # fixed precision
+scope(arr, color=False)        # monochrome
+scope(arr, style='html')       # force HTML output in terminal
+```
+
+## CLI
+
+```bash
+# Install globally (ships with the library)
+pip install arrscope
+
+# Use from anywhere
+arrscope 3x4x5
+arrscope 2x3x32x32 --axes batch heads h w --grid h w --mode heatmap
+arrscope 20x4x5 --max-height 6 --no-stats
+```
+
+## Framework support
+
+Pass any array-like — conversion is automatic:
+
+```python
+import torch
+scope(torch.randn(2, 3, 4))          # PyTorch
+
+import tensorflow as tf
+scope(tf.random.uniform((2, 3, 4)))  # TensorFlow
+
+import jax.numpy as jnp
+scope(jnp.array([[1, 2], [3, 4]]))  # JAX
+```
+
+## API
+
+```python
+scope(
+    arr,                          # np.ndarray | torch.Tensor | tf.Tensor | jax.Array
+    axes=None,                    # list[str] — name each dimension
+    grid=None,                    # list[str | int] — which dims form the leaf grid
+    title=None,                   # str — heading above the visualization
+    max_width=None,               # int — max characters wide
+    max_height=None,              # int — max rows before truncation
+    fmt=None,                     # str — format spec like '.4f'
+    color=True,                   # bool — enable/disable color
+    mode='dtype',                 # 'dtype' | 'heatmap' | 'sparsity'
+    stats=True,                   # bool — show min/max/mean/std/zeros
+    style='auto',                 # 'auto' | 'terminal' | 'html'
+)
+```
+
+## Development
+
+```bash
+git clone https://github.com/vizarray/arrscope
+cd arrscope
+uv sync
+uv run pytest
+uv run python main.py          # demo script
+uv run jupyter notebook test.ipynb  # notebook demo
+```
+
+## License
+
+MIT

arrscope-0.1.0/README.md

@@ -0,0 +1,158 @@
+# arrscope
+
+Beautiful n-dimensional array visualization for Python — in the terminal and Jupyter.
+
+```python
+from arrscope import scope
+import numpy as np
+
+scope(np.random.rand(2, 3, 8, 8), axes=['batch', 'heads', 'h', 'w'])
+```
+
+```
+├── [0] (3, 8, 8)
+│   ├── [0,0]: 8×8 grid
+│   ├── [0,1]: 8×8 grid
+│   └── [0,2]: 8×8 grid
+└── [1] (3, 8, 8)
+    ...
+  min=0.001  max=0.999  mean=0.5  std=0.29  zeros=0.0%
+```
+
+## Features
+
+- **1D → 6D+**: Tiered visual grammar — lists, grids, trees, collapsed hierarchies
+- **Named axes**: Attach semantics to dimensions (`batch`, `heads`, `h`, `w`)
+- **Configurable grid**: Pick which axes form the leaf 2D matrix
+- **Three color modes**:
+  - `dtype` — semantic colors by data type (float=blue, int=green, bool=magenta, …)
+  - `heatmap` — diverging colormap (red→light→blue) by value magnitude
+  - `sparsity` — zeros as `·`, non-zeros highlighted in bold
+- **Stats overlay**: min, max, mean, std, zero%, NaN count
+- **Head/tail truncation**: large dimensions show first/last N slices with `…`
+- **Smart precision**: auto-detects significant figures for floats
+- **Terminal + Jupyter**: Rich ANSI output + static HTML/CSS with dark mode
+- **Multi-framework**: NumPy, PyTorch, TensorFlow, JAX (lazy imports, no hard deps)
+
+## Install
+
+```bash
+pip install arrscope
+```
+
+Only requires `numpy` + `rich`. Torch/TF/JAX are optional — pass any array type, it just works.
+
+## Quick start
+
+```python
+from arrscope import scope
+import numpy as np
+
+# Auto-detect — last 2 dims form the grid
+scope(np.random.rand(3, 4, 5))
+
+# Named axes for clarity
+scope(
+    np.random.rand(2, 8, 32, 32),
+    axes=['batch', 'heads', 'h', 'w'],
+    grid=['h', 'w'],
+    title='Attention heads',
+)
+
+# Pick any dims as the leaf grid
+scope(data, axes=['a', 'b', 'c', 'd'], grid=['a', 'b'])
+```
+
+## Color modes
+
+```python
+scope(arr, mode='dtype')        # default — blue floats, green ints, etc.
+scope(arr, mode='heatmap')      # diverging colormap by value
+scope(arr, mode='sparsity')     # · for zeros, bold for non-zeros
+```
+
+## Stats overlay
+
+Stats are shown by default. Hide with:
+
+```python
+scope(arr, stats=False)
+```
+
+Shows: `min=0.0  max=1.0  mean=0.5  std=0.29  zeros=12.5%`
+
+## Truncation
+
+```python
+scope(np.random.rand(100, 32, 32), max_height=8)
+```
+
+Shows first 4 + last 4 slices with `… (92 more)` in between.
+
+## Custom formatting
+
+```python
+scope(arr, fmt='.2f')          # fixed precision
+scope(arr, color=False)        # monochrome
+scope(arr, style='html')       # force HTML output in terminal
+```
+
+## CLI
+
+```bash
+# Install globally (ships with the library)
+pip install arrscope
+
+# Use from anywhere
+arrscope 3x4x5
+arrscope 2x3x32x32 --axes batch heads h w --grid h w --mode heatmap
+arrscope 20x4x5 --max-height 6 --no-stats
+```
+
+## Framework support
+
+Pass any array-like — conversion is automatic:
+
+```python
+import torch
+scope(torch.randn(2, 3, 4))          # PyTorch
+
+import tensorflow as tf
+scope(tf.random.uniform((2, 3, 4)))  # TensorFlow
+
+import jax.numpy as jnp
+scope(jnp.array([[1, 2], [3, 4]]))  # JAX
+```
+
+## API
+
+```python
+scope(
+    arr,                          # np.ndarray | torch.Tensor | tf.Tensor | jax.Array
+    axes=None,                    # list[str] — name each dimension
+    grid=None,                    # list[str | int] — which dims form the leaf grid
+    title=None,                   # str — heading above the visualization
+    max_width=None,               # int — max characters wide
+    max_height=None,              # int — max rows before truncation
+    fmt=None,                     # str — format spec like '.4f'
+    color=True,                   # bool — enable/disable color
+    mode='dtype',                 # 'dtype' | 'heatmap' | 'sparsity'
+    stats=True,                   # bool — show min/max/mean/std/zeros
+    style='auto',                 # 'auto' | 'terminal' | 'html'
+)
+```
+
+## Development
+
+```bash
+git clone https://github.com/vizarray/arrscope
+cd arrscope
+uv sync
+uv run pytest
+uv run python main.py          # demo script
+uv run jupyter notebook test.ipynb  # notebook demo
+```
+
+## License
+
+MIT

arrscope-0.1.0/docs/ADR-001-visual-grammar.md

@@ -0,0 +1,77 @@
+# ADR-001: Visual Grammar & Display Strategy
+
+**Status:** Accepted  
+**Date:** 2026-06-30  
+
+## Context
+
+arrscope needs to visually represent n-dimensional arrays (1D to 6D+) in a way that humans can intuitively parse. The core challenge is that humans can natively perceive:
+
+- **1D** — a linear list
+- **2D** — a grid/table/matrix
+- **3D** — a stack of grids (with mental effort)
+
+Beyond 3D, direct spatial intuition fails. The library must provide a principled decomposition of higher dimensions into comprehensible visual hierarchies.
+
+## Decision
+
+### Tiered visual grammar
+
+The display strategy is a fixed **tiered system** based on the number of dimensions being displayed as the leaf grid (default: 2):
+
+| Grid dims | Total dims | Strategy | Example shape |
+|-----------|------------|----------|--------------|
+| 1 | 1 | Horizontal row `[a, b, c]` | `(5,)` |
+| 2 | 2 | Table/grid with borders | `(4, 5)` |
+| 2 | 3 | Stacked grids with index headers | `(3, 4, 5)` |
+| 2 | 4 | 2D spatial arrangement of grids (grid-of-grids) | `(2, 3, 4, 5)` |
+| 2 | 5 | Collapsed tree — outer dims as foldable sections | `(2, 3, 4, 5, 6)` |
+| 2 | 6+ | Summary mode — shape + stats + spark, expandable | `(2, 3, 4, 5, 6, 7)` |
+
+The **leaf grid** is the 2D block of actual values. Everything prior is structural nesting.
+
+### Grid-of-grids for 4D
+
+For shapes like `(batch=3, heads=4, h=8, w=8)`:
+- The 8×8 matrices are the leaf grids
+- They are arranged in a 3×4 visual grid, each cell labeled `[b=0, h=0]`, `[b=0, h=1]`, etc.
+- The outer arrangement uses the same box-drawing characters as a 2D table, creating a unified visual language
+
+### Collapsed tree for 5D+
+
+For shapes beyond 4 total dimensions:
+- Show a tree where each leaf is a grid (or summary)
+- Branches show index labels and sub-shapes
+- The tree is truncated via head/tail sampling when branches exceed a threshold
+
+Example tree output:
+```
+(3, 4, 5, 6) float64
+├── [0]: (4, 5, 6)
+│   ├── [0,0]: 5×6 grid
+│   ├── [0,1]: 5×6 grid
+│   ├── ...
+│   └── [0,3]: 5×6 grid
+├── [1]: (4, 5, 6)
+├── [2]: (4, 5, 6)
+```
+
+### Truncation
+
+Large dimensions use **head/tail truncation**: show first N and last N slices, with an ellipsis indicator in between. The threshold is adaptively chosen based on available terminal height / viewport.
+
+### Configurable axes
+
+The user can specify which axes form the leaf grid. By default, the last 2 axes are the grid. With named axes:
+```python
+viz(arr, axes=['batch', 'heads', 'h', 'w'], grid=['h', 'w'])
+```
+This changes which dimensions form the leaf 2D grid, allowing the user to prioritize the spatial dimensions most relevant to them.
+
+## Consequences
+
+- **Positive:** The grammar is deterministic and predictable. Given axes and a shape, the output layout is fully determined.
+- **Positive:** Dimensionality reduction is automatic — the user doesn't configure the tier, just the axes.
+- **Positive:** The grid-of-grids strategy for 4D is novel and immediately readable for ML practitioners.
+- **Negative:** The tree view for 5D+ is not as visually rich as the grid-of-grids; it trades density for clarity.
+- **Negative:** Head/tail truncation loses information in the middle. A future enhancement could add summary stats for truncated regions.

arrscope-0.1.0/docs/ADR-002-architecture.md

@@ -0,0 +1,102 @@
+# ADR-002: Architecture & Rendering Pipeline
+
+**Status:** Accepted  
+**Date:** 2026-06-30  
+
+## Context
+
+arrscope must render to two distinct output media (terminal ANSI and Jupyter HTML) with different layouts per medium. The architecture must be extensible, testable, and avoid duplicating layout logic.
+
+## Decision
+
+### Three-layer architecture
+
+```
+┌─────────────────────────────────────────────┐
+│                Public API                    │
+│          viz(arr, axes, grid, ...)           │
+├─────────────────────────────────────────────┤
+│              Layout Engine                   │
+│    Builds a tree of VizNode objects from     │
+│    array + axis spec → intermediate repr     │
+├──────────────────┬──────────────────────────┤
+│  TerminalRenderer│    HTMLRenderer           │
+│  (Rich library)  │  (HTML/CSS, no JS)        │
+└──────────────────┴──────────────────────────┘
+```
+
+### Layout Engine (`arrscope/_layout.py`)
+
+The core algorithm:
+
+1. **Validate inputs** — check array is rectilinear, axes match shape, grid dims are valid
+2. **Normalize axes** — assign default names if not provided, resolve grid/layout dims
+3. **Build node tree** — recursively slice the array along non-grid dimensions:
+   - Each node has: `indices`, `label`, `shape`, `children`, `grid_data`
+   - Leaves hold the 2D slice (last 2 dims after slicing outer dims)
+4. **Apply truncation** — trim child lists to head/tail at each level
+
+The `VizNode` tree is the **intermediate representation**: it contains all information needed to render, and is independent of any rendering library.
+
+```
+class VizNode:
+    indices: tuple[int, ...]     # position in parent, e.g. (0, 2)
+    label: str                   # e.g. "[batch=0, heads=2]"
+    shape: tuple[int, ...]       # full shape of this sub-array
+    children: list[VizNode]      # sub-nodes for outer dims
+    grid_data: np.ndarray | None # the 2D slice at this leaf
+    truncated: bool              # whether children were truncated
+    truncated_head: int          # count shown from start
+    truncated_tail: int          # count shown from end
+```
+
+### Terminal Renderer (`arrscope/renderers/terminal.py`)
+
+Uses the **Rich** library to render nodes:
+
+- **1D:** `rich.text.Text` with brackets
+- **2D:** `rich.table.Table` with box-drawing borders
+- **3D:** `rich.table.Table` with labeled sections, each section containing a sub-Table
+- **4D:** `rich.layout.Layout` arranging sub-Tables in a grid, or `rich.table.Table` with nested Tables in cells
+- **5D+:** `rich.tree.Tree` with `rich.table.Table` at leaves
+
+Color is applied per cell based on dtype (see ADR-001 for color scheme).
+
+### HTML Renderer (`arrscope/renderers/html.py`)
+
+Generates static HTML/CSS strings:
+
+- Uses `<table>` elements with inline CSS for styling
+- Collapsible sections use `<details>`/`<summary>` (no JavaScript)
+- CSS respects `prefers-color-scheme` for dark/light mode
+- Each output is an `HTML` object (IPython display hook)
+
+### Framework Adapters (`arrscope/adapters/`)
+
+Lazy imports with guard:
+
+```python
+def _to_numpy(arr):
+    if hasattr(arr, '__array__'):
+        return np.asarray(arr)
+    module = type(arr).__module__
+    if 'torch' in module:
+        import torch
+        return arr.detach().cpu().numpy()
+    if 'tensorflow' in module or 'keras' in module:
+        return arr.numpy()
+    if 'jax' in module:
+        import jax
+        return np.asarray(arr)
+    return np.asarray(arr)
+```
+
+Each adapter is an optional import — failure raises a clear `ImportError` with install instructions.
+
+## Consequences
+
+- **Positive:** The VizNode tree is pure data — it can be serialized, tested, and cached independently of rendering.
+- **Positive:** Adding a new renderer (e.g., SVG, PNG) requires no changes to the layout engine.
+- **Positive:** Framework adapters are isolated and easy to extend.
+- **Negative:** The full array is materialized in memory during layout tree construction. For gigantic arrays, this is unavoidable (you need the values to display them).
+- **Negative:** Rich is a heavy dependency (~500KB + deps). Tradeoff accepted for faster development.

arrscope-0.1.0/docs/ADR-003-api-design.md

@@ -0,0 +1,106 @@
+# ADR-003: Public API Design
+
+**Status:** Accepted  
+**Date:** 2026-06-30  
+
+## Context
+
+The API must be intuitive for ML practitioners, composable, and discoverable via tab-completion. The library should be importable as `arrscope` with a single top-level `scope` function as the primary entry point.
+
+## Decision
+
+### Top-level import
+
+```python
+from arrscope import scope
+```
+
+The library is installed as `pip install arrscope` and imported as `arrscope`. The `scope` function is the only public API surface in v1.
+
+### Function signature
+
+```python
+def scope(
+    arr: ArrayLike,
+    *,
+    axes: list[str] | None = None,
+    grid: list[str | int] | None = None,
+    title: str | None = None,
+    max_width: int | None = None,
+    max_height: int | None = None,
+    fmt: str | None = None,
+    color: bool = True,
+    style: str = "auto",
+) -> VizOutput:
+    ...
+```
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `arr` | `ArrayLike` | required | NumPy array, torch tensor, TF tensor, JAX array, or nested Python list |
+| `axes` | `list[str] \| None` | `None` | Names for each dimension. If None, auto-named as `dim_0, dim_1, ...` |
+| `grid` | `list[str \| int] \| None` | `None` | Which axes form the leaf 2D grid. Default: last 2. Accepts names or indices |
+| `title` | `str \| None` | `None` | Optional heading displayed above the visualization |
+| `max_width` | `int \| None` | `None` | Max characters wide. Auto-detected from terminal in TTY mode |
+| `max_height` | `int \| None` | `None` | Max rows. Triggers truncation when exceeded |
+| `fmt` | `str \| None` | `None` | Format spec for values, e.g. `'.4f'`, `'.2e'`. Default: smart precision |
+| `color` | `bool` | `True` | Enable semantic color by dtype |
+| `style` | `str` | `"auto"` | Output style: `"auto"` (detect terminal vs Jupyter), `"terminal"`, `"html"` |
+
+### Return type
+
+```python
+class VizOutput:
+    """Holds both representations. Auto-displays in the appropriate medium."""
+    html: str      # HTML/CSS string
+    ansi: str       # Rich-rendered ANSI string (or Rich Renderable)
+
+    def _repr_html_(self) -> str: ...
+    def _repr_rich_(self) -> RenderableType: ...
+```
+
+In Jupyter, `_repr_html_` is called automatically. In a terminal, when the result is the last expression in a cell, Rich's `_repr_rich_` is used. Users can also explicitly call `scope(..., style='html')` to get the HTML string.
+
+### Examples
+
+```python
+# Basic usage — auto-detect axes
+scope(np.random.rand(3, 4, 5))
+
+# With named axes and explicit grid
+scope(
+    np.random.rand(2, 8, 32, 32),
+    axes=['batch', 'heads', 'h', 'w'],
+    grid=['h', 'w'],
+    title='Attention heads'
+)
+
+# Custom format
+scope(np.eye(5), fmt='.2f', color=False)
+
+# Select specific grid dims by index
+scope(data, grid=(-2, -1))  # last two dims (same as default)
+```
+
+### Configuration via `arrscope.config`
+
+```python
+from arrscope import config
+
+config.max_width = 120
+config.color = False
+config.precision = 4
+```
+
+Module-level settings for global overrides.
+
+## Consequences
+
+- **Positive:** Single function with sensible defaults — zero-config for basic use.
+- **Positive:** Named axes system integrates naturally with ML workflows where axes have semantics.
+- **Positive:** Auto-detect of terminal vs Jupyter means no boilerplate for the user.
+- **Positive:** The `VizOutput` object leverages IPython's display protocol and Rich's repr protocol simultaneously.
+- **Negative:** The `style="auto"` heuristic may misdetect in edge cases (e.g., inside a pipe). Users can always override.
+- **Negative:** Named axes require the user to pass the `axes` list, which adds friction for quick one-offs.

arrscope-0.1.0/docs/GLOSSARY.md

@@ -0,0 +1,40 @@
+# arrscope Glossary
+
+### ArrayLike
+Any array-like object accepted by arrscope: `np.ndarray`, `torch.Tensor`, `tf.Tensor`, `jax.Array`, or deeply nested Python lists of uniform shape.
+
+### Axis
+A named dimension of an array. In `viz(arr, axes=['batch', 'h', 'w', 'c'])`, each string is an axis name. Axes can be referenced by name or index throughout the API.
+
+### Grid
+The leaf 2D representation of an array. The `grid` parameter specifies which axes form this matrix. Default is the last 2 axes.
+
+### Grid-of-grids
+The display strategy for 4D arrays: a 2D spatial arrangement of 2D matrices, each labeled by its outer indices. For `(batch=3, heads=4, h=8, w=8)` with `grid=['h','w']`, the output is a 3×4 arrangement of 8×8 grids.
+
+### Head/tail truncation
+Display strategy for large dimensions: show the first N and last N slices, with `...` (and count) between them. N is adaptively chosen based on available viewport.
+
+### Layout Engine
+The core module that converts an array + axis specification into a `VizNode` tree — a renderer-independent intermediate representation.
+
+### Leaf grid
+The final 2D slice displayed at the leaves of the node tree. This is where the actual numeric values are shown.
+
+### Semantic coloring
+Color scheme where color is determined by data type: floats → blue/cyan, ints → green, bools → magenta, strings → yellow, complex → red.
+
+### Smart precision
+Auto-detected float formatting: displays 2–4 significant figures based on magnitude. Uses scientific notation for very small/large values.
+
+### Stacked grids
+Display strategy for 3D: a sequence of 2D grids separated by section headers like `[0, :, :]`, `[1, :, :]`, etc.
+
+### Tree view
+Display strategy for 5D+: a hierarchical tree with collapsible branches, where each leaf contains a 2D grid. Outer dimensions form the tree structure.
+
+### VizNode
+The intermediate representation node. Contains `indices`, `label`, `shape`, `children`, and `grid_data`. Produced by the layout engine, consumed by renderers.
+
+### VizOutput
+The return type of `viz()`. Holds both HTML and ANSI representations and auto-displays in the correct medium via `_repr_html_` and `_repr_rich_`.