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