understory

KO | EN

gitlite — search

#typescript #ai-agents #deepseek-harness #dsh-plugin #open-source #ai #cli #dsh #claude-code #codex #developer-tools #react

★ 41 Open GitHub ↗

Foundational spatial and scene data structures for user interfaces and graphics editors.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Understory

Foundational spatial and scene data structures for user interfaces, graphics editors, and CAD viewers.

Understory is a small family of crates designed to be combined in different stacks over time.
The focus is on clean separation of concerns, pluggable performance trade‑offs, and long‑term architectural stability.

## Crates

- `understory_index`
  - A generic 2D AABB index with pluggable backends: FlatVec (linear scan), R‑tree, and BVH.
  - Works across `f32`/`f64`/`i64` coordinate spaces with widened accumulator metrics for robust splits.
  - Point and rectangle queries.
  - Batched updates via `commit()` with coarse damage (added, removed, moved).

- `understory_anchor`
  - Headless anchored overlay geometry resolution for popovers, menus, tooltips, combobox popups, hover cards, and selection/caret anchored surfaces.
  - Takes scene facts, preferred/fallback position options, collision constraints, and an optional previous frame, then emits stable geometry, arrows, transform origins, candidate metrics, and collision diagnostics.
  - Pure, renderer-agnostic, widget-agnostic, and built on `kurbo` geometry types.

- `understory_overlay`
  - Headless overlay lifecycle and interaction state for popovers, menus, submenus, hover cards, combobox popups, context menus, and dialogs.
  - Tracks deterministic parent/child stack mutation, modality underlays, dismiss regions, focus scopes, hover grace geometry, and event-to-operation resolution.
  - Designed to consume rectangles from `understory_anchor` while staying renderer-agnostic, widget-agnostic, and platform-agnostic.

- `understory_property`
  - Typed dependency-property ids, metadata, defaults, inheritance flags, value storage, and local/animation value slots.
  - Provides the property substrate shared by bindings, expressions, style resolution, presentation properties, and host invalidation.
  - Does not own style matching, expression evaluation, bindings, animation sampling, tree traversal, or scheduling.

- `understory_property_binding`
  - Small one-way property binding primitives for dependency-property endpoints.
  - Tracks source/target endpoint indexes, dirty binding selection, dependency ordering, and deterministic drain reports.
  - Host code owns property storage and application invalidation policy through the `BindingHost` boundary.

- `understory_property_expression`
  - Pure, typed expression IR for deriving dependency-property values from properties, resources, literals, conditionals, and registered functions.
  - Exposes dependency facts for invalidation and bundles defaults/functions in `ExpressionLayer`.
  - Does not own property storage, style matching, tree traversal, scheduling, writes, or parser vocabulary.

- `understory_style`
  - Presentation policy for dependency properties: selector matching, cascade rules, theme resources, style expressions, and expression-aware value resolution.
  - Resolves through Animation -> Local -> Style -> optional resource fallback -> Inherited -> Expression default -> Registry default.
  - Does not own widgets, bindings, animation sampling, layout, rendering, caching, dirty queues, frame scheduling, or tree-wide invalidation walks.

- `understory_presentation`
  - Retained, resolved drawing primitives keyed by caller-owned geometry ids.
  - Stores source back-references, template part identities, surface/text primitives, and deduped dirty keys.
  - Does not own layout, bounds, transforms, style/property resolution, behavior, or renderer command emission.

- `understory_presentation_properties`
  - Canonical dependency-property integration for resolved presentation primitives.
  - Registers surface background, border brush, border width, padding width, corner radius, and corner shape properties with invalidation metadata.
  - Resolves property/style/theme values into `understory_presentation::SurfacePrimitive` without owning storage, matching, layout, or rendering.

- `understory_box_decoration`
  - Renderer-neutral box decoration geometry for physical edges, box-area contours, and shaped corners.
  - Supports elliptical per-corner radii, CSS smallest-factor radius fitting, round/square/bevel/superellipse corner shapes, derived border/padding/content contours, central border-side regions, and on-demand Kurbo path writing.
  - Does not own style cascade, CSS parsing, brushes, images, layout, hit policy, or renderer command emission.

- `understory_box_tree`
  - A Kurbo‑native, spatially indexed box tree for scene geometry: local bounds, transforms, optional clips, and z‑order.
  - Computes world‑space AABBs and synchronizes them into `understory_index` for fast hit‑testing and visibility.
  - Not a layout engine.
  - Upstream code (your layout system) decides sizes and positions and then updates this tree.

- `understory_event_state`
  - Common event state managers for UI interactions: hover enter/leave transitions, focus path changes, transform‑aware click recognition, and drag tracking.
  - Each manager is a focused state machine that accepts pre‑computed information (root→target paths from `understory_responder`, pointer positions) and emits transition events.
  - Designed to integrate with any event routing or spatial query system.
  - Generic over node/widget ID types with no framework assumptions.

- `understory_focus`
  - Focus navigation primitives: navigation intents, per-node focus properties, and a spatial view of focusable candidates.
  - Provides pluggable policies for directional and ordered navigation, and an optional adapter for integrating with `understory_box_tree`.
  - Designed to be independent of any particular widget toolkit or event system.

- `understory_node_graph`
  - Headless graph document, projection, session, and computed-state primitives for node-graph editors and viewers.
  - Separates durable node-graph topology from per-projection layout, ephemeral interaction state, and derived geometry/visibility caches.
  - Includes explicit invalidation channels, replaceable edge routing, and hit testing over realized node bounds, port anchors, and edge routes.

- `understory_inspector`
  - Host-side controller for hierarchical inspection UIs built on top of outline projection, fixed-row virtualization, and selection.
  - Owns expansion/focus/selection synchronization over visible rows without taking on rendering, icons, badges, or columns.
  - Designed to sit above `understory_outline` and below any actual inspector widget or host UI.

- `understory_outline`
  - Hierarchical visible-row projection primitives for expandable tree views, grouped property grids, and disclosure lists over existing domain models.
  - Defines an `OutlineModel` trait, explicit expansion state, a cached visible-row projection controller, and a dense slice-backed reference model when data already exists in that form.
  - Designed to compose with `understory_virtual_list` rather than replace it.

- `understory_precise_hit`
  - Geometry‑level, narrow‑phase hit testing for shapes in local 2D coordinates, built on `kurbo`.
  - Provides a small `PreciseHitTest` trait with `HitParams`/`HitScore` helpers and default impls for `Rect`, `Circle`, `RoundedRect`, and fill‑only `BezPath`.
  - Designed to be paired with a broad‑phase index (e.g. `understory_index` + `understory_box_tree`) and event routing (`understory_responder`), with rich metadata carried in responder `meta` types.

- `understory_responder`
  - A deterministic event router that builds the responder chain sequence: capture → target → bubble.
  - Consumes pre‑resolved hits (from a picker or the box tree) and emits an ordered dispatch sequence.
  - Includes a tiny dispatcher helper (`dispatcher::run`) for executing handlers and honoring stop/cancelation.
  - Supports pointer capture with path reconstruction via a `ParentLookup` provider and bypasses scope filters.

- `understory_selection`
  - Generic selection container that tracks a set of keys plus an optional primary and anchor, plus a revision counter for change detection.
  - Generic over the key type `T` (no `Hash`/`Ord` requirement; only `PartialEq`), suitable for list selections, canvases, and other selection UIs.
  - Intended to pair with `understory_box_tree` / `understory_precise_hit` for hit testing and `understory_responder` for event routing.

- `understory_timing`
  - Host-agnostic timer queue primitives.
  - Tracks timer ids, target payloads, deadline ordering, cancellation, expiration, and explicit repeat policies.
  - Uses caller-supplied monotonic ticks and deliberately does not own clocks, event loops, platform wakeups, widgets, or redraw policy.

- `understory_transcript`
  - Append-order interaction log primitives with generic payloads and explicit updates for chat, shell, and agent-style systems.
  - Provides stable entry ids, typed entry kinds, `EntryBody` as a built-in text/bytes default payload, explicit parent/cause links, and explicit status/chunk updates to existing entries.
  - Designed to sit below transcript/chat/console UIs without taking on text layout, rendering, or persistence policy.

- `understory_transition`
  - Style-driven property transition declarations (duration, delay, easing) keyed by dependency-property ids, plus the retargeting/interruption state machine.
  - Samples with host-provided monotonic time and emits animation-slot writes, retargeting interrupted transitions from their current animated value with CSS-style faster reversing.
  - Does not own property storage, style matching, pseudo-class state detection, keyframe animations, frame scheduling, or renderer writes.

- `understory_view2d`
  - 2D and 1D view/viewport primitives:
    - `Viewport2D` for canvas/CAD‑style views: camera state (pan + zoom), coordinate conversion between world and device space, view fitting (center vs align‑min), and simple clamping against optional world bounds.
    - `Viewport1D` for timeline/axis‑style views: X‑only zoom/pan with range fitting and clamping, plus helpers for suggesting grid spacing.
  - Headless and renderer‑agnostic; intended to be driven by `ui-events` at higher layers and paired with `understory_box_tree` / imaging crates for canvas and timeline applications.

- `understory_virtual_list`
  - Core 1D virtualization primitives over dense index strips, expressed via the `ExtentModel` trait and helper types.
  - Provides `FixedExtentModel<S>` for uniform extents, `PrefixSumExtentModel<S>` for variable extents with a lazily‑maintained prefix‑sum cache, and `compute_visible_strip` for scroll/viewport → visible‑slice calculations with asymmetric overscan.
  - Includes a small `VirtualList<M>` controller with `ScrollAlign`, visibility queries, and scroll clamping to make it easy for host frameworks to drive virtualized lists and stacks.

All core crates are `#![no_std]` and use `alloc`.
Examples and tests use `std`.

## Why this separation?

We aim for a three‑tree model that scales and composes well.

1) Widget tree — state and interaction
2) Box tree — geometry and spatial indexing
3) Presentation tree — resolved drawing intent

This split makes debugging easier, enables incremental updates, and lets each layer evolve and be swapped independently.
For example, a canvas or DWG or DXF viewer can reuse the box and index layers without any UI toolkit.

## Design principles

- Pluggable backends and scalars.
- Choose trade‑offs per product or view.
- Predictable updates.
- Batch with `commit()` and use coarse damage for bounding paint.
- Conservative geometry.
- Use world AABBs for transforms and rounded clips and apply precise filtering where cheap.
- No surprises.
- `no_std` + `alloc`, minimal dependencies, and partial concise `Debug` by default.

## Performance notes

- Arena‑backed R‑tree and BVH reduce allocations and pointer chasing.
- STR and SAH‑like builds are available.
- Benchmarks live under `benches/` and compare backends across distributions and sizes.
- Choose R‑tree or BVH for general scenes.
- Choose FlatVec for tiny sets.

## Roadmap (sketch)

- Render tree crate and composition and layering utilities.
- Backend tuning (SAH weights, fanout/leaf sizes), bulk builders, hygiene/rotation, and churn optimizations.
- Extended benches such as update mixes, overlap stress, and external comparisons.
- Integration examples with upstream toolkits.

## Getting started

- Read the crate READMEs.
  - `understory_index/README.md` has the API and a “Choosing a backend” guide.
  - `understory_box_decoration/README.md` documents box decoration contours, shaped corners, fitted radii, and border/padding/content edge derivation.
  - `understory_anchor/README.md` documents anchored placement, multi-rect anchors, constraints, arrows, diagnostics, and hysteresis.
  - `understory_overlay/README.md` documents overlay lifecycle, modality, dismissal, focus scopes, and hover grace regions.
  - `understory_box_tree/README.md` has usage, hit‑testing, and visible‑set examples.
  - `understory_responder/README.md` explains routing, capture, and how to integrate with a picker.
  - `understory_focus/README.md` covers focus navigation policies and adapters.
  - `understory_node_graph/README.md` documents graph documents, projections, sessions, computed geometry, routing, and invalidation.
  - `understory_inspector/README.md` documents the host-side controller for outline-backed inspection UIs.
  - `understory_outline/README.md` documents hierarchical visible-row projection, expansion state, and grouped/tree-style usage.
  - `understory_selection/README.md` documents the selection container, anchor/revision semantics, and click helpers.
  - `understory_timing/README.md` documents host-driven timer queue scheduling, expiration, and repeat policy.
  - `understory_transcript/README.md` documents append-order transcript storage, generic payloads, explicit update semantics, typed entry kinds, and chat/tool/process-style usage.
  - `understory_transition/README.md` documents per-property transition declarations, retargeting and reversing semantics, host-driven sampling, and animation-slot write plans.
  - `understory_view2d/README.md` documents the 2D and 1D viewport types, clamping/fit modes, and examples of using visible regions for culling.
  - `understory_property/README.md` documents dependency-property registration, metadata, local/animation slots, inheritance, and erased values.
  - `understory_property_binding/README.md` documents one-way property bindings, host endpoint adapters, and binding-local invalidation.
  - `understory_property_expression/README.md` documents typed pure property expressions, dependency inspection, expression defaults, and function registration.
  - `understory_style/README.md` documents presentation policy resolution, selector matching, cascade rules, theme resources, style expressions, and resolver provenance.
  - `understory_presentation/README.md` documents retained resolved drawing primitives, template part identities, and dirty-key draining.
  - `understory_presentation_properties/README.md` documents canonical presentation property registration and surface resolution.
- Run examples.
  - `cargo run -p understory_examples --example index_basics`
  - `cargo run -p understory_examples --example basic_present`
  - `cargo run -p understory_examples --example presentation_properties`
  - `cargo run -p understory_examples --example property_binding_loop`
  - `cargo run -p understory_examples --example style_subject_walk`
  - `cargo run -p understory_examples --example style_reactive_loop`
  - `cargo run -p understory_examples --example style_transition_loop`
  - `cargo run -p understory_examples --example box_tree_basics`
  - `cargo run -p understory_examples --example box_tree_visible_list`
  - `cargo run -p understory_examples --example outline_property_grid`
  - `cargo run -p understory_examples --example outline_virtual_list`
  - `cargo run -p understory_examples --example outline_inspector`
  - `cargo run -p understory_examples --example timing_queue`
  - `cargo run -p understory_examples --example transcript_agent_run`
  - `cargo run -p understory_examples --example transcript_virtual_list`
  - `cargo run -p understory_examples --example transcript_tail_anchored`
  - `cargo run -p understory_examples --example responder_basics`
  - `cargo run -p understory_examples --example responder_hover`
  - `cargo run -p understory_examples --example responder_box_tree`

## MSRV & License

- Minimum supported Rust: 1.88.
- Dual‑licensed under Apache‑2.0 and MIT.

understory

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README