Skip to main content

cartography/
lib.rs

1// Copyright 2026 Mark AB (markik)
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4//! # Cartography
5//!
6//! Non-destructive projection layer for the
7//! [Mere](https://crates.io/crates/mere) browser.
8//!
9//! Cartography sits between **graph truth** + **intelligence signals**
10//! on the input side, and **canvas swatches** on the output side. It
11//! owns the *contracts* — the [`LayoutStrategy`] trait, the
12//! [`Projection`] / [`Overlay`] / [`MinimapDescriptor`] vocabulary, and
13//! the [`IntelligenceSignals`] narrow shape that firewalls cartography
14//! from `embed`' internals. The strategies
15//! themselves live in sibling crates (graph-layout, document-layout,
16//! …).
17//!
18//! ## The strategy contract
19//!
20//! Cartography exposes the [`LayoutStrategy`] trait: one-shot, stateless
21//! analytic projection. Picks: Phyllotaxis, Penrose, Radial, Grid,
22//! Timeline, Kanban, L-system, Spectral, SemanticEmbedding. `project()`
23//! produces a final projection in one call. Live force physics
24//! (force-directed, the affinity force) is seiche's domain; the old
25//! streaming-strategy contract was retired with the `SemanticEdgeWeight`
26//! projection once the seiche affinity force reached parity.
27//!
28//! Strategies emit a [`Projection`]
29//! output type so canvases consume one shape uniformly. See the
30//! [cartography layer brief](https://github.com/merely-made/mere/blob/main/design_docs/mere_docs/research/2026-05-10_cartography_layer_brief.md)
31//! for the full design.
32//!
33//! ## The framing
34//!
35//! Inputs:
36//!
37//! - [`kernel::graph::Graph`] — read-only reference.
38//! - [`IntelligenceSignals`] — clusters, affinity, hot regions, bridge
39//!   nodes, importance hints. Produced by `embed`
40//!   and consumed through this narrow contract type, not a direct
41//!   dependency on the crate's internals.
42//! - [`ViewIntent`] — what the user is trying to see right now: scale,
43//!   dimension, focus, filter, form factor (orrery root, workbench
44//!   swatch, volvelle radial, astroid hub-collapse, minimap thumbnail).
45//!
46//! Outputs:
47//!
48//! - [`Projection`] — positioned nodes + edges + overlays at a chosen
49//!   layout, ready for a canvas swatch to render.
50//! - [`Overlay`] variants — semantic emphases canvases apply on top of
51//!   geometry (cluster halos, edge weights, activity heat, bridge
52//!   emphasis, importance scaling).
53//! - [`MinimapDescriptor`] — thumbnail-scale projection of any swatch.
54//!
55//! The graph stays canonical. Cartography is *representation*, not
56//! truth.
57//!
58//! ## Status
59//!
60//! Pre-1.0. v0 ships contract types only — no strategy
61//! implementations, no canvas integration.
62
63#![doc(html_root_url = "https://docs.rs/cartography/0.0.1")]
64
65pub mod adapters;
66pub mod minimap;
67pub mod overlay;
68pub mod projection;
69pub mod reading;
70pub mod representation;
71pub mod request;
72pub mod scene_out;
73pub mod signals;
74pub mod spiral_score;
75pub mod strategy;
76
77pub use minimap::{MinimapDescriptor, MinimapOverlayKind};
78pub use overlay::Overlay;
79pub use projection::{PositionedEdge, PositionedNode, Projection, ProjectionMetadata};
80pub use reading::{
81    ActorScope, GRAPH_READING_REGISTRY_SCHEMA, GraphReadingProfile, GraphReadingRegistry,
82    ReadingEmphasis, ReadingSurface, default_graph_reading_registry,
83};
84pub use representation::{
85    BehaviorBinding, ConditionOperation, GRAPH_REPRESENTATION_REGISTRY_SCHEMA,
86    GraphRepresentationRegistry, HostBehavior, HostGesture, PrimitiveBody, PrimitiveProfile,
87    RepresentationCondition, RepresentationLadder, RepresentationMeasure, RepresentationProfile,
88    RepresentationRung, RepresentationState, default_graph_representation_registry,
89    default_representation_ladder,
90};
91pub use request::{
92    AxisValue, FormFactor, NodeFilter, ProjectionDimension, ProjectionRequest, TargetSize,
93    ViewIntent,
94};
95pub use scene_out::{MERE_GRAPH_ADAPTER, scene_from_projection};
96pub use signals::{
97    AffinityScores, BridgeNodes, Cluster, ClusterSet, ImportanceWeights, IntelligenceSignals,
98    NodeEmbeddings,
99};
100pub use spiral_score::{MereSpiralProjection, project_spiral_score, project_spiral_score_for_view};
101pub use strategy::LayoutStrategy;
102
103/// Crate version.
104pub const VERSION: &str = env!("CARGO_PKG_VERSION");
105
106/// Lifecycle stage marker.
107pub const STAGE: &str = "pre-alpha";