understory

KO | EN

gitlite — search

#javascript #python #hacktoberfest #typescript #golang #machine-learning #rust #macos #windows #kubernetes #security #openai #ios #mcp

(★ 41)

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

understory Latest Version Download

Download Latest Version (.zip)

// 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

understory Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

understory

understory Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README