document_session_api/engine_ids.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//! The engine-id namespace and the genet render-rung ladder.
8//!
9//! Engine ids are facts an engine states about itself: a kept Genet session
10//! lane returns one from `SessionEngine::engine_id`. Which engine a host
11//! selects for an address is routing policy and lives with the controller
12//! in `inker::routing`; these names are what that policy is written in.
13
14/// The genet HTML engine's **static** rung (the profile ladder's base): parse →
15/// style/layout → paint, with no JS in its dependency graph. The default HTML route
16/// and the id existing per-node pins persist, so it keeps the legacy `genet.web`
17/// value rather than `genet.static`. See [`GenetRung`].
18pub const ENGINE_GENET_WEB: &str = "genet.web";
19/// Opt-in static rung rendered by the clean-room Livery CSS engine. This is a
20/// sibling implementation of [`ENGINE_GENET_WEB`], not the default route.
21pub const ENGINE_GENET_LIVERY: &str = "genet.livery";
22/// Render-free fleece extraction lowered into the portable document engine.
23/// Selectable for held HTML by explicit per-node pin; never the automatic HTML
24/// route, which remains the ordinary Genet renderer.
25pub const ENGINE_GENET_READER: &str = "genet.reader";
26/// The genet HTML rungs above static (the profile ladder; see [`GenetRung`]). A node
27/// pins one of these to escalate capability. Additive, and gated by host registration:
28/// until a rung is registered in the host's `EngineRegistry`, it is not `is_available`,
29/// so a pin to it falls back to the static route (`route_filtered`). genet scales
30/// internally from the static composition up to a full browser
31/// (genet `docs/2026-05-12_genet_profile_ladder_plan.md`); these ids select the rung.
32pub const ENGINE_GENET_INTERACTIVE: &str = "genet.interactive";
33pub const ENGINE_GENET_SCRIPTED: &str = "genet.scripted";
34/// The scripted genet rung backed by Nova instead of Boa. Same ladder rung,
35/// distinct host-visible engine id so a node can pin the JS backend explicitly.
36pub const ENGINE_GENET_SCRIPTED_NOVA: &str = "genet.scripted.nova";
37pub const ENGINE_GENET_FULLWEB: &str = "genet.fullweb";
38/// Mere-managed system-WebView tile driven by the in-house `scrying`
39/// library. Embedded-frame composition into the host's wgpu surface
40/// (frames captured via `webview2-com` on Windows / `objc2-web-kit` +
41/// ScreenCaptureKit on macOS / WebKitGTK+DMABUF on Linux).
42///
43/// Preferred non-Servo path. Not in the default routing policy —
44/// opt-in per tile via `EngineRouteRequest::pinned_engine` or a
45/// per-host override. Auto-fallback rule (genet rendering failure
46/// → propose `scrying.web`) is a follow-up; the routing surface
47/// already supports it via `pinned_engine`.
48///
49/// See `design_docs/mere_docs/research/2026-05-11_engine_peers_and_scrying_library_brief.md`.
50pub const ENGINE_SCRYING_WEB: &str = "scrying.web";
51/// Embedded Servo via the wgpu-graft producer (GL-FBO / DX12-shared / Vulkan
52/// external-memory / IOSurface interop). Tier-2 surface engine; opt-in per tile
53/// like [`ENGINE_SCRYING_WEB`], not in the default policy.
54pub const ENGINE_GRAFT_SERVO: &str = "graft.servo";
55/// Bundled Chromium via the wgpu-weld CEF accelerated-OSR producer. Tier-2
56/// surface engine; opt-in per tile like [`ENGINE_SCRYING_WEB`].
57pub const ENGINE_WELD_CHROMIUM: &str = "weld.chromium";
58pub const ENGINE_NEMATIC_FEED: &str = "nematic.feed";
59pub const ENGINE_NEMATIC_FILE: &str = "nematic.file";
60pub const ENGINE_NEMATIC_FINGER: &str = "nematic.finger";
61pub const ENGINE_NEMATIC_GEMTEXT: &str = "nematic.gemtext";
62pub const ENGINE_NEMATIC_GOPHER: &str = "nematic.gopher";
63pub const ENGINE_NEMATIC_GUPPY: &str = "nematic.guppy";
64pub const ENGINE_NEMATIC_KNOT: &str = "nematic.knot";
65pub const ENGINE_NEMATIC_KNOT_DJOT: &str = "nematic.knot-djot";
66pub const ENGINE_NEMATIC_MARKDOWN: &str = "nematic.markdown";
67pub const ENGINE_NEMATIC_MISFIN: &str = "nematic.misfin";
68pub const ENGINE_NEMATIC_NEX: &str = "nematic.nex";
69pub const ENGINE_NEMATIC_SCROLL: &str = "nematic.scroll";
70pub const ENGINE_NEMATIC_TEXT: &str = "nematic.text";
71/// Titan (`titan://`) response bodies — gemtext re-tagged with titan provenance.
72pub const ENGINE_NEMATIC_TITAN: &str = "nematic.titan";
73/// The one host-handled id inker keeps: the neutral "hand this address to the
74/// OS" target every host has, and the default policy's `fallback` rule needs
75/// one. App-flavored host-handled ids (internal pages, graph-contribution
76/// ingest markers) are the host's own vocabulary, defined app-side and layered
77/// onto the policy at construction (mere: `mere::routing`); registry keys are
78/// plain strings, so a host id costs nothing here.
79pub const ENGINE_EXTERNAL_PROTOCOL: &str = "host.external-protocol";
80
81/// Whether `engine_id` names a tier-2 **surface** engine — one that produces GPU
82/// frames (a system WebView via [`ENGINE_SCRYING_WEB`]; CEF via weld and Servo via
83/// graft when those land) rather than a portable `EngineDocument`. Surface
84/// engines go through the `SurfaceEngineRegistry` / producer path; document
85/// engines go through the `EngineRegistry`. A host branches on this to pick
86/// the lane.
87pub fn is_surface_engine(engine_id: &str) -> bool {
88 matches!(
89 engine_id,
90 ENGINE_SCRYING_WEB | ENGINE_GRAFT_SERVO | ENGINE_WELD_CHROMIUM
91 )
92}
93
94/// A rung of the genet HTML render ladder. genet is one engine that scales from a
95/// static, JS-free composition up to a full browser; the rung selects *how much of the
96/// web stack* a page is given. Each rung is **additive** over the one below, and each
97/// is a principled composition — the static rung carries no JS in its dependency graph
98/// (attack-surface + bundle-size + DOM-as-library), so a higher rung is a deliberate
99/// escalation, never the default. The default HTML route is [`Static`](Self::Static);
100/// a node pins a higher rung to opt in. Ordered by capability (the derived `Ord`).
101///
102/// Canonical: genet `docs/2026-05-12_genet_profile_ladder_plan.md`; Mere framing:
103/// `design_docs/mere_docs/implementation_strategy/2026-06-23_render_ladder_and_extraction_plan.md`.
104#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
105pub enum GenetRung {
106 /// parse → style/layout → paint. No JS. The default, and the safe/fast base.
107 Static,
108 /// + forms / focus / input / accessibility. Still no JS.
109 Interactive,
110 /// + JS engine + DOM bindings + event routing.
111 Scripted,
112 /// + navigation / workers / storage / media / WebGL / devtools.
113 FullWeb,
114}
115
116impl GenetRung {
117 /// Every rung, ascending by capability — the ladder a picker offers.
118 pub const ALL: [GenetRung; 4] = [
119 GenetRung::Static,
120 GenetRung::Interactive,
121 GenetRung::Scripted,
122 GenetRung::FullWeb,
123 ];
124
125 /// The engine id that selects this rung. Static keeps the legacy [`ENGINE_GENET_WEB`]
126 /// id so existing pins resolve; the higher rungs have their own ids.
127 pub fn engine_id(self) -> &'static str {
128 match self {
129 GenetRung::Static => ENGINE_GENET_WEB,
130 GenetRung::Interactive => ENGINE_GENET_INTERACTIVE,
131 GenetRung::Scripted => ENGINE_GENET_SCRIPTED,
132 GenetRung::FullWeb => ENGINE_GENET_FULLWEB,
133 }
134 }
135
136 /// A short label for the picker UI.
137 pub fn label(self) -> &'static str {
138 match self {
139 GenetRung::Static => "Static",
140 GenetRung::Interactive => "Interactive",
141 GenetRung::Scripted => "Scripted",
142 GenetRung::FullWeb => "Full Web",
143 }
144 }
145}
146
147/// The genet render rung an `engine_id` selects, or `None` when it is not a genet
148/// HTML rung (a nematic, surface, or marker engine).
149pub fn genet_rung(engine_id: &str) -> Option<GenetRung> {
150 match engine_id {
151 ENGINE_GENET_WEB | ENGINE_GENET_LIVERY => Some(GenetRung::Static),
152 ENGINE_GENET_INTERACTIVE => Some(GenetRung::Interactive),
153 ENGINE_GENET_SCRIPTED | ENGINE_GENET_SCRIPTED_NOVA => Some(GenetRung::Scripted),
154 ENGINE_GENET_FULLWEB => Some(GenetRung::FullWeb),
155 _ => None,
156 }
157}
158
159/// Whether `engine_id` names any rung of the genet HTML render ladder. The tier-1
160/// counterpart to [`is_surface_engine`]: a genet rung produces a portable
161/// `EngineDocument`, not a GPU surface frame.
162pub fn is_genet_rung(engine_id: &str) -> bool {
163 genet_rung(engine_id).is_some()
164}