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