Skip to main content

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}