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}