Build renderer and material component foundations

Add dedicated skinned rendering, pose restoration, shared Material and Material Instance slots, registry-driven components, Surface/Solari integration, transactional schema upgrades, navigation authoring, documentation, and evaluation evidence.
This commit is contained in:
Rbanh committed 2026-07-12 00:24:06 -04:00
1 parent 0553a85220
commit 0798aa5d57
169 files changed
+27098 -3469

No files matched your search

+3 -1
View File
@@ -10,7 +10,9 @@ Level data must round-trip through save/load without leaking runtime ECS compone
## Decision
- **Authoring components** (`Primitive`, `StaticMeshRenderer`, `MaterialDesc`, `MaterialOverride`, `LightDesc`, `ModelRef`, `RigidBodyDesc`, `ColliderDesc`, legacy `PhysicsBody`, `ActorKind`, etc.) are the only components written to `.scn.ron`.
- **Authoring components** (`Primitive`, `StaticMeshRenderer`, `SkinnedMeshRenderer`,
`MaterialDesc`, `MaterialOverride`, `LightDesc`, `ModelRef`, `RigidBodyDesc`, `ColliderDesc`,
legacy `PhysicsBody`, `ActorKind`, etc.) are the only components written to `.scn.ron`.
- **Hydration** in `crates/shared/src/hydration/` generates runtime components in a fixed `Update` chain.
- **Save path** uses an explicit `DynamicSceneBuilder` allowlist and `strip_hydrated_entity` on each entity before serialize.
+4 -2
View File
@@ -2,7 +2,7 @@
## Status
Accepted
Partially superseded by [ADR 0034](0034-registry-driven-authoring-components.md).
## Context
@@ -12,7 +12,9 @@ Inspector panels were routed by `if world.get::<LightDesc>` and mixed with `bevy
- Every savable `LevelObject` carries a required **`ActorKind`** component (schema v2).
- One-shot **`ActorKind` backfill** runs in `crates/scene` migration v1→v2; load-time backfill is a fallback only for unsaved in-memory entities.
- **`validate_actor`** runs on save and rejects invalid component sets per kind.
- **`validate_actor`** runs on save and rejects invalid component sets per kind. ADR 0034 replaces
this authority model with component-owned validation while retaining `ActorKind` as a derived
compatibility/display hint.
- The default **Inspector** tab uses **`actor_inspector`** only (transform first, then authoring panels). No `ui_for_entity_with_children` in production builds.
## Consequences
@@ -8,7 +8,8 @@ Accepted
glTF/GLB and FBX previously entered the editor as imported scenes through `ModelRef`, with runtime hydration loading a format-specific `WorldAssetRoot`. That path is still useful for full scene playback, but it makes ordinary static mesh placement depend on source format behavior and prevents the inspector from exposing a stable renderer component.
The editor needs model drag/drop to create editable static mesh actors by default, while retaining an explicit scene-instance path for animation, skinning, cameras, and other full-scene data.
The editor needs model drag/drop to create editable static mesh actors for unrigged geometry while
retaining explicit, separate paths for skinned geometry and generic full-scene data.
## Decision
@@ -18,7 +19,11 @@ The saved scene authoring component is `StaticMeshRenderer`. Its slots reference
Asset import settings choose the default placement mode:
- `StaticAsset` creates `ActorKind::StaticMesh + StaticMeshRenderer`; when collider generation is enabled it also creates `RigidBodyDesc + ColliderDesc::StaticMesh`.
- `StaticAsset` creates `ActorKind::StaticMesh + StaticMeshRenderer` for unrigged sources; when
collider generation is enabled it also creates `RigidBodyDesc + ColliderDesc::StaticMesh`.
- Sources containing skin-bound primitives or animation route to
`ActorKind::SkinnedMesh + SkinnedMeshRenderer` and never create static renderer slots or
automatic triangle-mesh colliders (ADR 0033).
- `SceneInstance` creates the legacy `ActorKind::ImportedModel + ModelRef`.
Hierarchy mode is also stored per asset. `SingleActor` places all mesh parts into one renderer. `SourceHierarchy` creates an authored root with child static mesh actors.
@@ -28,5 +33,6 @@ Hierarchy mode is also stored per asset. `SingleActor` places all mesh parts int
- glTF/GLB and FBX placement consume the same renderer contract after processing.
- Scene files store renderer intent, not runtime Bevy mesh/material handles.
- Static mesh actors can expose renderer slots, source labels, shadows, collider policy, and material overrides in the inspector.
- Animated/skinned playback remains on the scene-instance path until a future animation authoring component exists.
- Skinned parts are marked in artifact schema v2 and excluded from static renderer construction and
hydration. Animation playback uses the dedicated contract in ADRs 0031 and 0033.
- Generated artifacts are project files but are hidden from the Asset Browser catalog to avoid treating them as levels/prefabs.
@@ -2,7 +2,9 @@
## Status
Accepted.
Partially superseded by [ADR 0034](0034-registry-driven-authoring-components.md) for component
lifecycle, active-state ownership, history, and composition. Material ownership is superseded by
the renderer-material ADR.
## Context
@@ -23,9 +25,8 @@ Component footer rather than an ad hoc button near Transform.
`ActorName`) and repeatable authoring items use `ComponentInstanceId`.
- Editor-visible actor components are described by an
`EditorComponentRegistry`; the Add Component footer reads from this registry.
- `InspectorOrder` stores editor component order plus per-component active
state. Collapse state is session-only UI state; active state is persisted with
the scene and is undoable.
- `InspectorOrder` stores editor component order. ADR 0034 moves persisted active state to
`AuthoringComponentStates`; collapse state remains session-only UI state.
- `StaticMeshRenderer` stores `MeshRenderSlot` values that reference imported
content-browser assets through `EditorAssetRef { asset_id, sub_asset_id,
label }`. Actor renderer data does not store source FBX/glTF paths.
+3 -1
View File
@@ -12,7 +12,9 @@ Jackdaw roadmap work needs blockout geometry that is editable as authored data,
Add `ActorKind::Brush` and `BrushDesc` as persisted shared authoring data. A brush stores convex polygon faces with stable face IDs, plane data, material/texture references, UV parameters, smoothing group, and shadow flags. The MVP supports additive cube brushes and hydrates active brush components into generated mesh children; generated children are stripped from saved scenes.
Brush actors conflict with `Primitive`, `StaticMeshRenderer`, `LightDesc`, and `ModelRef` in actor validation. Scene v1-to-v2 kind backfill infers `ActorKind::Brush` when an older level object contains `BrushDesc`.
Brush actors conflict with `Primitive`, `StaticMeshRenderer`, `SkinnedMeshRenderer`, `LightDesc`,
and `ModelRef` in actor validation. Scene v1-to-v2 kind backfill infers `ActorKind::Brush` when an
older level object contains `BrushDesc`.
## Consequences
@@ -6,8 +6,8 @@ Accepted
## Context
Blacksite currently records animation and skin counts while importing glTF and FBX models, but the
authored scene contract contains only a path-based `ModelRef`. Scene-instance hydration loads a
Blacksite previously recorded animation and skin counts while importing glTF and FBX models, but the
authored scene contract contained only a path-based `ModelRef`. Generic scene-instance hydration loaded a
model world without selecting or driving its clips, and the editor has no stable clip references,
controller inspector, preview, or compatibility validation.
@@ -32,12 +32,12 @@ Each animated model has a versioned generated manifest under `assets/animations/
by the model's stable asset-registry UUID. The manifest records the source path and fingerprint,
skeletons and their exact signatures, stable clip sub-asset IDs, clip label/index/duration, target
skeleton signature, normalized event markers, and import diagnostics. Registry UUID plus sub-asset
ID is authoritative; cached `ModelRef` and `EditorAssetRef` source paths are only runtime-resolution
ID is authoritative; cached `SkinnedMeshRenderer` and `EditorAssetRef` source paths are only runtime-resolution
and repair hints. UUID-keyed generated manifests provide the current source path after a uniquely
reconciled move.
`shared` owns reflected, serializable `AnimationControllerDesc` and its named state/event value
types. A controller sits beside the model scene reference and uses `EditorAssetRef` for skeleton and
types. A controller sits beside the dedicated `SkinnedMeshRenderer` and uses `EditorAssetRef` for skeleton and
clip references. It contains one layer of named states, one default state, a default crossfade
duration, and per-state playback range, loop, and speed. State IDs are stable authored identifiers;
display labels are not runtime keys.
@@ -50,7 +50,13 @@ stored in the manifest are display metadata and never compatibility keys. Blacks
humanoid roles, rename joints, or perform proportional remapping in this version. This exact node
identity contract is animation-manifest schema v2; v1 artifacts must be reimported.
The runtime adapter waits for the model `WorldAssetRoot` instance to report readiness, finds its
Animation-manifest schema v3 adds an optional stable default clip sub-asset ID sourced from model
import settings. It is an explicit presentation policy: renderable animated-model placement creates
a one-state controller only when this ID resolves. An absent value preserves the imported node pose;
the importer and placement workflow never infer a first clip. Generic scene-instance placement does
not consume this setting.
The runtime adapter waits for the renderer's `HydratedSkinnedMeshRoot` instance to report readiness, finds its
animation player, and derives Bevy graph/player state from the controller. Generated instance,
graph, player, transition, and playback bookkeeping is transient and excluded from authored scene
serialization. Rehydration owns a dedicated generated instance root and must not despawn authored
@@ -61,6 +67,14 @@ authored/default crossfade. Invalid state requests are rejected without disturbi
state. The editor's preview and scrub controls use the same runtime adapter; starting, stopping, or
scrubbing a preview never changes the authored descriptor, history, or scene dirty state.
When a hydrated hierarchy becomes ready, the runtime captures its descendant `Transform` and
`MorphWeights` components before evaluating authored playback. Edit mode samples the configured
default state at its range start and pauses it. Preview stop, controller removal, failed graph
reconfiguration, and PIE exit first stop playback and restore the captured baseline; if a valid
default remains, it is then sampled again without a crossfade. Skin validation checks each imported
skin independently for joint/inverse-bind count and hierarchy ownership, including sources that
reuse one joint hierarchy across multiple skin records.
Interactive diagnostics, headless validation, and packaging resolve the same manifest and enforce
source availability, stable reference resolution, supported formats, valid playback ranges/events,
and exact skeleton compatibility.
@@ -79,9 +93,15 @@ the rigs into separate assets or export all clips beneath one common root.
- One-layer named states provide a deterministic gameplay integration point without committing the
editor to a visual graph format prematurely.
- Exact-signature retargeting is intentionally restrictive but cannot silently deform the wrong rig.
- Explicit edit-rest clips avoid malformed source presentation poses without coupling rendering to
animation; assets without a configured clip keep their imported rest pose.
- Baseline restoration prevents stopped previews and mode changes from leaving sampled transforms or
morph weights behind.
- Rejecting multiple animation roots prevents the runtime adapter from selecting an arbitrary first
player and driving only part of a source.
- A future visual graph, blend trees, root motion, IK, advanced retargeting, or animated FBX support
must extend or supersede this contract explicitly rather than leaking runtime Bevy components into
authored scenes.
- Implementation and production acceptance are tracked in Gitea issue #46.
- The static/skinned renderer boundary and v2-to-v3 scene migration are defined by
[ADR 0033](0033-dedicated-skinned-mesh-renderer.md).
@@ -0,0 +1,36 @@
# ADR 0032: Versioned Navigation Bake And Runtime Query
## Status
Accepted
## Context
Blacksite needs a production navigation workflow on Bevy 0.19. Current high-level Bevy navigation
plugins target older Bevy releases, while baking and pathfinding are difficult, established domains
that should not be reimplemented locally. The editor also cannot own the runtime query contract:
packaged games and headless validation must consume the same data and behavior.
## Decision
Use the engine-independent Rerecast crate for deterministic 3D walkable-surface generation and
Polyanya for any-angle path queries. Blacksite owns reflected authoring components and a versioned
generated artifact under `assets/navigation/generated/`. The artifact records the source scene,
source fingerprint, agent profile, baked mesh, links, bounds, and diagnostics.
The scene crate owns fingerprinting, bake artifact IO, and validation. The game crate owns artifact
loading and path queries. Editor bake controls, overlays, and path preview call those shared/game
contracts and keep all visual helpers transient. Relevant authored geometry changes mark the
artifact stale; V1 debounces a full deterministic rebuild and reports the affected region until
Rerecast provides production-ready tiled regeneration.
## Consequences
- Navigation remains usable on Bevy 0.19 without forking an older Bevy integration crate.
- Rerecast and Polyanya versions become explicit serialized-artifact compatibility inputs; schema
migration or rebaking is required when their representation changes.
- Static navigation and explicit links ship first. Runtime obstacle carving, crowd avoidance, and
partial tile rebuilding remain future work.
- Primitive and additive-brush triangles are deterministic source geometry. Imported static meshes
use authored navigation obstacles until their normalized artifacts expose collision triangles.
- Runtime code never depends on editor UI state, and authored scenes never contain bake visualizers.
@@ -0,0 +1,60 @@
# ADR 0033: Dedicated Skinned Mesh Renderer
## Status
Accepted
## Context
The normalized model artifact originally exposed every imported primitive to
`StaticMeshRenderer`, including primitives with joint indices and weights. Whole-model static
placement could therefore detach rigged geometry from its joints and render it in bind pose. The
animation workflow avoided individual skinned-part placement, but it still represented animated
geometry as generic `ImportedModel + ModelRef`, leaving no authoring boundary between an arbitrary
source scene and geometry that requires a skeleton hierarchy.
Static, generic scene-instance, and skinned rendering have different ownership rules. Static parts
can be flattened into independent slots and triangle-mesh colliders. A skinned mesh must retain the
source joints, inverse bind poses, animation player, and hierarchy. A generic scene instance may
contain cameras, lights, or other source data and does not imply an animation contract.
## Decision
Rigged geometry uses `ActorKind::SkinnedMesh + SkinnedMeshRenderer`. The renderer stores stable
asset identity, cached source path, and source scene index. Its dedicated hydration system creates a
`HydratedSkinnedMeshRoot` and instantiates the complete source hierarchy so Bevy owns the runtime
`SkinnedMesh`, joints, inverse bind poses, and animation-player placement. The animation runtime
binds only to this dedicated root. `AnimationControllerDesc` is valid only beside a
`SkinnedMeshRenderer`.
Renderer hydration itself remains animation-agnostic. The animation adapter captures the imported
hierarchy baseline when that root becomes ready and optionally drives the explicit default clip
recorded by animation-manifest schema v3. Without a controller, the dedicated renderer remains at
the captured imported pose.
Static-mesh artifact schema v2 marks every part as skinned or unskinned. Static renderer creation
filters out skinned parts and all geometry from an animated source; static hydration enforces the
same rule even if a scene contains a hand-authored slot. Automatic renderable-model placement
chooses `SkinnedMeshRenderer` when any source part is skin-bound or the source contains animation,
and otherwise chooses `StaticMeshRenderer`. Placing a skinned or animated subasset
places its owning model through the dedicated renderer; it never creates a detached static slot.
`ImportedModel + ModelRef` remains the explicit generic scene-instance path. It is not the animation
renderer. Scene schema v3 migrates v2 entities containing both `ModelRef` and
`AnimationControllerDesc` to `SkinnedMeshRenderer + ActorKind::SkinnedMesh`; unrelated imported
scene instances remain unchanged.
Automatic triangle-mesh collider generation applies only to static renderers. Animated collision
must be authored explicitly with stable gameplay shapes or hitboxes rather than a deforming render
surface.
## Consequences
- Static renderer slots can no longer silently accept newly imported skinned or animated geometry.
- Rigged models retain the exact hierarchy Bevy needs for skinning and animation playback.
- Generic scene instances, static meshes, and skinned meshes have distinct persisted components,
actor kinds, hydration markers, validation, and editor presentation.
- A source containing both rigid and skinned nodes is placed as one skinned actor so the imported
hierarchy remains coherent; splitting it requires separate source assets.
- FBX skinning and animation remain blocked by ADR 0031 until the FBX loader can build the same
runtime hierarchy and clip contract as glTF.
@@ -0,0 +1,45 @@
# ADR 0034: Registry-driven authoring components
## Status
Accepted
## Context
The Add Component palette was registry-backed, but presence checks, copy/paste, reset, removal,
history, save filtering, validation, and most inspector dispatch were duplicated as Rust `match`
statements. `InspectorOrder` also stored active state, causing hydration and game systems to depend
on editor presentation metadata. `ActorKind` was used as validation authority, which prevented
otherwise valid component composition such as a rendered mesh that also emits light.
## Decision
- Every authoring component registration has an immutable editor/protocol ID separate from its
reflected Rust type path. Startup validation rejects duplicate IDs/types, missing reflection
adapters, and unknown recommendation/conflict references.
- Bevy reflection supplies generic presence, default insertion/reset, removal, copy/paste, and RON
values for atomic `ComponentTransaction` history. A transaction includes the derived
`ActorKind` hint so one undo restores the complete component edit.
- The registry builds the scene component allowlist. A statically linked extension uses
`register_authoring_component` to register reflection metadata, lifecycle metadata, and an
inspector callback together.
- Persisted `AuthoringComponentStates` owns component active state. `InspectorOrder` owns only card
ordering. Schema-v3 state embedded in `InspectorOrder` is moved lazily and remains a read fallback
during migration.
- `ActorKind` remains serialized for compatibility and presentation, but is derived from component
composition on load and component transactions. Validation enforces component data and explicit
geometry-source conflicts rather than comparing behavior with the stored hint. Compatible
components, including mesh plus light, may coexist.
## Consequences
- New statically linked authoring components participate in save filtering and generic component
operations without adding editor-core history or persistence branches.
- Runtime systems read active state independently from inspector layout. Old scenes preserve their
disabled components and upgrade in memory before their next save.
- Geometry source conflicts remain explicit, while presentation categories no longer prohibit
unrelated behavior composition.
- Existing whole-entity spawn/duplicate snapshots still have typed fields. Moving those snapshots
and every built-in inspector renderer to the reflected registry is follow-up work; the generic
transaction path is the required path for new component operations.
@@ -0,0 +1,60 @@
# ADR 0035: Shared Material Assets and Renderer Slots
## Status
Accepted
## Context
Renderer material authoring previously mixed copied `MaterialDesc` values, imported source-material
defaults, and static-mesh draw data. That made a renderer's ownership unclear, encouraged material
copies per actor, and left rigged geometry without the same assignment model as static geometry.
Matching imported materials by a display name was also unsafe: names are neither unique nor stable
when a model is reimported.
Static and skinned renderers need the same Unity-like authoring contract without sharing their mesh
or hydration components. A project material must be reusable, an instance must express explicit
overrides over one base material, and each renderer must expose stable material slots independently
from its draw or skeleton representation.
## Decision
- Project materials use versioned `MaterialAsset` documents. A `MaterialInstanceAsset` references
one direct base `MaterialAsset` and stores parameter and texture overrides. Nested material
instances are invalid.
- `MaterialRef` is the assignment type. Its registry UUID and subasset ID are authoritative;
`source_path` is a cached loading hint that validation or migration may repair after a move.
- `StaticMeshRenderer` and `SkinnedMeshRenderer` each own a `RendererMaterialSet`. They do not share
a mesh component or hydration path. Each `RendererMaterialSlot` has a stable ID, a presentation
name, a read-only imported `source_material`, and an optional explicit `material` assignment.
Explicit assignment wins; clearing it returns to the imported source material.
- Static draw parts and imported skinned-hierarchy draws bind to material slots by stable IDs.
Reimport reconciles by ID only. An explicit assignment whose source slot disappears is retained as
an `OrphanedMaterialAssignment`; the editor never silently reconnects it by display name.
- Asset Browser **Apply Material** assigns a shared material or material instance to every material
slot on each selected static or skinned renderer. Renderer inspectors provide per-slot
Browse/Select/Locate/Clear controls and expose orphan warnings.
- `HydratedRendererMaterialBinding` identifies each runtime draw's owner, slot, and effective
material. A skinned renderer material-only edit patches the instantiated hierarchy without
reloading its source hierarchy or joints.
- `MaterialPropertyBlocks` are runtime-only, per-slot overrides. They do not mutate a shared asset
and are excluded from scene and prefab persistence. Persisting a reusable variation requires an
explicit material instance.
- Scene schema v4 migrates legacy renderer assignments into `RendererMaterialSet`. Project material,
material-instance, shader-schema, and scene rewrites are performed by the explicit transactional
`cargo upgrade-project` command; ordinary loading remains read-only.
## Consequences
- Static and skinned renderers have a consistent material-slot workflow while retaining distinct
geometry ownership and hydration behavior.
- An assignment remains a reference rather than a copied material value, so editing or replacing a
shared asset does not create actor-local material copies. Material/base/schema/evaluator
dependency revisions update the shared runtime handle in place across all assigned slots.
- Source reimport cannot silently move an override to the wrong draw. Orphans require an explicit
user decision to reassign or discard.
- Legacy primitive/actor `MaterialDesc` paths remain compatibility paths until their consumers move
to renderer slots; new mesh-renderer work uses shared references.
- Runtime property blocks have no editor promotion workflow yet.
- Material graph authoring, nested instances, blended/transmissive materials, and a generalized
per-renderer property-block inspector are outside this decision.
@@ -0,0 +1,72 @@
# ADR 0036: Surface ABI v1 and Solari Evaluator Parity
## Status
Accepted
## Context
Arbitrary full-pipeline WGSL cannot be carried safely between Bevy's raster pipelines and Solari's
ray-hit shaders. A custom fragment shader may own bindings, entry points, derivatives, discard, or
other stage-specific behavior that has no direct ray-tracing equivalent. Treating such a shader as
a `StandardMaterial` in Solari would produce a different material, while tracing skinned source
vertices would produce bind-pose geometry instead of the rasterized deformation.
Blacksite needs one constrained material expression that can produce the same surface values in
forward/deferred raster rendering and at Solari ray hits, while leaving transforms, skinning,
lighting, fog, shadows, and render-pipeline bindings under engine ownership.
## Decision
- `blacksite_surface` owns versioned Surface ABI v1. A custom evaluator implements:
```wgsl
fn evaluate(
input: SurfaceInput,
params: SurfaceParams,
samples: SurfaceSamples,
) -> Surface
```
`SurfaceInput` provides UV0, world position, and world normal. `Surface` returns base color,
tangent-space normal, emissive, metallic, perceptual roughness, reflectance, occlusion, alpha,
and lit/unlit model selection.
- The ABI has 16 `vec4` parameter lanes, eight sampled 2D texture slots with UV transforms, and a
400-byte `SurfaceUniform`. Shader schemas map typed Bool/Float/Vec2/Vec3/Color/Enum properties and
texture properties into that fixed layout. Exceeding either limit is a validation error.
- Evaluators cannot declare bindings or shader entry points and cannot use compute/storage,
ray-query, derivative, discard, barrier/subgroup, texture-store, or atomic constructs. The engine
supplies resources, entry points, vertex transforms/skinning, lighting, fog, and shadows.
- Raster rendering composes the evaluator between the engine-owned Surface header and footer and
installs it as an `ExtendedMaterial<StandardMaterial, SurfaceExtension>` for forward, deferred,
and prepass pipelines. Tangent-space normals are applied when the mesh supplies tangents.
- The maintained `third_party/bevy_solari` fork packs the same uniform and texture set, namespaces
validated evaluator functions, and generates a shader-ID dispatch library for ray hits. Eligible
non-deformed geometry uses the evaluator for hit material fields, tangent-space normal, emissive,
unlit behavior, and cutout candidate acceptance.
- Opaque and cutout are the supported alpha modes. Solari treats geometry as potentially
non-opaque and evaluates the exact Surface alpha and cutoff before accepting a cutout ray
candidate.
- Plain materials without a custom evaluator keep Bevy's standard raster and Solari material path.
Dependency revisions cover Material Instances, their direct base, shader schema, and evaluator.
Naga syntax/semantic validation and the cross-pipeline restrictions run before installation;
invalid updates produce diagnostics and retain the last successfully installed evaluator/library.
- Meshes with `SkinnedMesh`, runtime morph weights, or morph targets are excluded from Solari until
an instance-keyed deformed-vertex and BLAS update path exists. They continue to render through
Bevy's raster path; Solari diagnostics report the exclusion. No bind-pose ray-tracing fallback is
allowed.
## Consequences
- Custom material code is portable because it describes a surface, not an entire render stage.
- Raster and Solari evaluate the same source for supported, Solari-eligible static or rigid
geometry. Normal parity requires tangents; Solari compatibility diagnostics identify missing
tangents and other unsupported mesh layouts.
- Dynamic skinned/morph Solari geometry remains deliberate future work. This is a geometry parity
limit, not permission to substitute source/bind-pose vertices.
- ABI layout or semantic changes require a new version and migration. The fixed lanes and texture
count trade arbitrary resource layouts for deterministic cross-renderer packing.
- Blend, transmission, refraction, custom vertex displacement, arbitrary entry points, and
stage-specific shader behavior are unsupported by Surface ABI v1.
- Maintaining evaluator parity requires carrying the focused Solari fork until the necessary hooks
exist upstream; its dispatch and cutout behavior are covered by local tests.