Skip to main content

kernel/graph/
node.rs

1// Copyright 2026 Mark AB (markik)
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4//! The kernel's physical node wrapper around chartulary's neutral Container.
5//!
6//! Extracted from `graph/mod.rs` per the 2026-04-30 renderer plan §6.4
7//! decomposition target. The history-projection types (`NodeNavigationMemory`,
8//! `NodeHistoryProjection`, etc.) remain in `graph/mod.rs` for now — they
9//! are the natural next decomposition target (as `graph/history.rs`).
10//!
11//! Browser-runtime state (scroll/form restore, viewer override, compat
12//! mode, webview lifecycle) left this struct on 2026-07-09 for the
13//! host-owned `BrowserNodeState` sidecar (pandect
14//! `browser_node_state`), per the mere/turnstone boundary pass plan
15//! slice C: the graph library holds graph facts; what the browser
16//! knows about a node rides beside the graph, keyed by node id.
17
18use std::collections::BTreeMap;
19use std::ops::{Deref, DerefMut};
20
21use uuid::Uuid;
22
23use crate::address::{Address, address_from_url};
24use crate::types::{ImageRef, ImageRole};
25
26/// A neutral Container in the kernel graph.
27///
28/// The only physical residue outside Container is the D0 image-reference map.
29/// Those small, content-addressed experience handles stay here so paint can
30/// resolve them without consulting a metadata facet; pixels remain out of line.
31#[derive(Debug, Clone)]
32pub struct Node {
33    /// The one node substrate. Identity, primary-first addresses, authored
34    /// content, media type, title, tags, and nested-graph bearing live here.
35    ///
36    /// `Deref` keeps the Container capability surface direct.
37    pub container: chartulary::Container<Uuid, Address>,
38
39    /// Content-addressed preview imagery, keyed by role. The node carries
40    /// ~40-byte [`ImageRef`] handles; the pixels live in the durable blob
41    /// store under `content/image/<hex>` (see
42    /// `pandect::image_store`).
43    ///
44    /// This is the node-image externalization plan's phase 2. Inline
45    /// `thumbnail_png` / `favicon_rgba` bytes used to ride here and dominated
46    /// the graph: at 50k nodes they were 64% of live heap, and the lane-D gate
47    /// measured them at 18x the snapshot size and 3.8x its load time. A
48    /// preview is *experience*, not truth, so it belongs in a bounded,
49    /// collectable cache rather than in every node forever.
50    ///
51    /// Read through [`Node::image`] / [`Node::favicon`] / [`Node::preview`]
52    /// rather than indexing the map, so call sites name a role.
53    pub images: BTreeMap<ImageRole, ImageRef>,
54}
55
56impl Deref for Node {
57    type Target = chartulary::Container<Uuid, Address>;
58
59    fn deref(&self) -> &Self::Target {
60        &self.container
61    }
62}
63
64impl DerefMut for Node {
65    fn deref_mut(&mut self) -> &mut Self::Target {
66        &mut self.container
67    }
68}
69
70impl Node {
71    /// The image reference held for `role`, if any.
72    pub fn image(&self, role: ImageRole) -> Option<&ImageRef> {
73        self.images.get(&role)
74    }
75
76    /// The favicon reference, if one has been stored.
77    pub fn favicon(&self) -> Option<&ImageRef> {
78        self.image(ImageRole::Favicon)
79    }
80
81    /// The preview reference, if one has been stored. This is the role the
82    /// legacy inline `thumbnail_png` migrates into.
83    pub fn preview(&self) -> Option<&ImageRef> {
84        self.image(ImageRole::Preview)
85    }
86
87    /// Attach (or replace) the reference for `role`, returning any prior one.
88    /// The pixels must already be in the blob store; the node only carries
89    /// the handle.
90    pub fn set_image(&mut self, role: ImageRole, image: ImageRef) -> Option<ImageRef> {
91        self.images.insert(role, image)
92    }
93
94    /// Drop the reference for `role`, returning it. The blob itself is left
95    /// for the orphan-GC pass, per the manifest-deletion doctrine: dropping a
96    /// reference is not a delete.
97    pub fn clear_image(&mut self, role: ImageRole) -> Option<ImageRef> {
98        self.images.remove(&role)
99    }
100
101    /// Returns the node's canonical retrieval address (the first address).
102    pub fn primary_address(&self) -> &Address {
103        self.addresses
104            .first()
105            .expect("Node invariant violated: no primary address")
106    }
107
108    /// Returns the canonical retrieval URL string. Convenience over
109    /// [`Node::primary_address`].
110    pub fn url(&self) -> &str {
111        self.primary_address().as_url_str()
112    }
113
114    // Per-node navigation history moved to the graph-level shared visit space
115    // (`Graph.nav` / `SharedNavigationMemory`); read it via the `Graph::node_history_*`
116    // / `Graph::node_current_url` methods. (The (b) anchor design, 2026-06-06.)
117
118    #[cfg(not(target_arch = "wasm32"))]
119    pub fn test_stub(url: &str) -> Self {
120        Self {
121            container: chartulary::Container::with_identity(Uuid::new_v4())
122                .with_address_record(address_from_url(url))
123                .with_title(url),
124            images: BTreeMap::new(),
125        }
126    }
127}