Atlas Engine and WASM Specification

Status: draft

Last updated: 2026-05-11

Audience: frontend implementers, Rust/WASM implementers, rendering engineers, accessibility reviewers, and backend graph-view reviewers.

1. Purpose

This document defines the atlas engine boundary for UWScrape.

The atlas engine is the frontend subsystem that turns backend graph view responses into an interactive spatial exploration surface.

The atlas engine owns visual projection and interaction.

The atlas engine does not own academic meaning.

The first atlas implementation requires a Rust/WASM worker for bounded layout and spatial compute.

The first renderer implementation requires a Three.js WebGL backend.

WebGPU is a progressive renderer backend.

The atlas must have a non-canvas fallback.

2. Named Components

The frontend architecture uses the following operational component names:

AtlasEngine;
RendererBackend;
LayoutBackend;
WebGLRendererBackend;
WebGPURendererBackend;
RustWasmLayoutWorker;
AtlasDataAdapter;
AtlasInteractionController;
AtlasSelectionStore;
AtlasCameraStore;
AtlasFallbackView.

These names are contracts for documentation and implementation discussion.

They are not metaphors.

User-facing copy may describe visual elements as planets, islands, threads, gates, and timelines.

Internal architecture must prefer operational names.

3. Component Responsibilities

AtlasEngine coordinates data ingestion, layout jobs, renderer lifecycle, interaction state, and fallback selection.

RendererBackend defines the renderer interface.

LayoutBackend defines the layout interface.

WebGLRendererBackend implements required WebGL rendering through Three.js.

WebGPURendererBackend implements optional progressive WebGPU rendering.

RustWasmLayoutWorker implements required v1 bounded layout and spatial compute.

For universal Canva views, backend or index-build layout hints are the preferred input when available.

AtlasDataAdapter converts backend graph view responses into compact layout inputs.

AtlasInteractionController maps pointer, keyboard, and camera events into selection and view state.

AtlasSelectionStore holds selected, hovered, and focused ids.

AtlasCameraStore holds viewport and camera state.

AtlasFallbackView renders the same graph data without canvas.

4. Academic Boundary

The atlas engine must not evaluate prerequisites.

The atlas engine must not evaluate credential requirements.

The atlas engine must not compute academic result statuses.

The atlas engine must not decide unknown or conflict semantics.

The atlas engine must not invent source references.

The atlas engine must not derive course unlock truth from visual reachability.

The atlas engine may compute visual reachability over already-loaded projection edges.

Visual reachability must be labeled as a projection operation.

Academic reachability and unlock status must come from backend query or graph view data.

Catalog-wide reachability, Advisory alternatives, and full-universe pathway closure must come from backend or index-build services, not from client-side graph walks.

5. Input Data

The primary input is a backend graph view response.

Graph responses include nodes, edges, groups, metrics, bounds, omitted counts, overlays, source references, and metadata.

The atlas must preserve backend ids.

The atlas may create compact numeric ids for layout arrays.

The mapping between backend ids and numeric ids must be stable for the loaded graph response.

The mapping must not leak into backend API requests except through reverse lookup to backend ids.

The atlas must preserve node type.

The atlas must preserve edge type.

The atlas must preserve academic status overlays.

The atlas must preserve source reference ids.

6. Layout Input Shape

The compact layout input should be array-oriented.

The layout input should minimize structured-clone overhead.

The layout input should avoid passing full source-reference payloads into the worker.

The layout input should include:

numeric node ids;
node types;
subject groups;
catalog levels;
importance metrics;
status overlays;
numeric edge endpoints;
edge types;
edge weights;
group memberships;
fixed positions when present;
previous positions when re-layouting;
deterministic seed;
viewport hints;
layout mode.

The layout input must not include raw state_token.

The layout input must not include full grades unless a visual encoding explicitly needs status already computed by the backend.

The layout input must not include raw source text.

7. Layout Output Shape

The layout output should be array-oriented.

The layout output should include:

node positions;
node radii or display scales;
cluster ids;
visibility masks;
picking indices;
label candidates;
collision metadata;
edge routing hints;
path highlight masks;
layout diagnostics;
deterministic seed actually used.

The layout output must not include academic statuses that were not present in input overlays.

The layout output must distinguish layout failure from academic unknown.

The layout output may include warnings about degraded layout quality.

8. Worker Protocol

The worker protocol must support:

initialize;
load graph;
run layout;
update viewport;
update filters;
trace visual path;
build picking index;
cancel job;
dispose graph;
terminate.

Worker messages must include a request id.

Worker responses must include the request id.

Worker errors must be structured.

Worker errors must be redacted.

Worker errors must not include raw tokens.

Worker cancellation must be explicit.

Worker cancellation must not be rendered as academic unknown.

9. Worker Lifecycle

The atlas should create the worker lazily when an atlas route mounts.

The atlas should terminate the worker when no atlas route needs it.

The atlas may keep the worker alive across nearby route transitions when this improves responsiveness.

The atlas must handle worker initialization failure.

The atlas must handle WASM loading failure.

The atlas must handle worker crash.

The atlas must handle unsupported browser behavior.

When the worker is unavailable, the app must use AtlasFallbackView or another documented fallback.

10. WASM Boundary

Rust/WASM is required for v1 atlas layout and spatial indexing on bounded graph slices.

Rust/WASM is not required for rendering.

Rust/WASM is not required for academic evaluation.

Rust/WASM is not required for SvelteKit page rendering.

Rust/WASM must expose a narrow API through wasm-bindgen or an equivalent later-approved binding layer.

The binding layer should generate or support TypeScript types.

The Rust code should use deterministic data structures where layout reproducibility depends on iteration order.

Floating-point tolerances must be documented in tests.

When a graph node includes backend or index-build layout_hints.position, the worker should treat that position as the default coordinate and avoid recomputing broad catalog layout.

The worker may refine, filter, or adapt those positions for a bounded current view.

The worker must not make full-universe layout recomputation a prerequisite for interaction on weak client hardware.

11. Determinism

Identical graph input and identical layout seed should produce identical layout output within documented numeric tolerance.

Random initialization must use the explicit seed.

Layout modes must record parameters.

The atlas must preserve a layout seed in local UI state when reproducible screenshots or debugging matter.

Determinism applies to layout compute.

Determinism does not require identical GPU rasterization across devices.

Renderer differences must not affect academic results.

12. Renderer Interface

RendererBackend must support:

initialize;
load scene data;
update camera;
update viewport size;
update visual status overlays;
update selection overlays;
render frame;
hit test or consume picking index;
dispose resources;
report capabilities.

RendererBackend must report initialization status.

RendererBackend must report selected backend name.

RendererBackend must report critical feature support.

RendererBackend must not call backend APIs.

RendererBackend must not evaluate academic requirements.

13. WebGL Baseline

WebGLRendererBackend is required.

It should use Three.js unless implementation research finds a concrete blocker.

It must initialize on browsers with sufficient WebGL support.

It must render nodes, edges, labels, highlights, and overlays needed for v1 atlas workflows.

It must support graceful degradation for high node counts.

It must expose a failure reason when initialization fails.

It must not block fallback view rendering.

14. WebGPU Progressive Backend

WebGPURendererBackend is optional.

It may be implemented after the WebGL baseline.

It must be capability-detected.

It must fall back to WebGL if unavailable or initialization fails.

It must fall back to non-canvas fallback if both WebGPU and WebGL fail.

It must preserve the same academic display data as the WebGL backend.

It must not require different backend API payloads.

It may use different GPU buffer layouts internally.

It may support larger visible graphs or smoother interactions.

MDN documents WebGPU availability and secure-context considerations, so it must not be a v1 launch dependency.

WebGPU is a browser renderer enhancement, not the primary compute offload strategy. Expensive graph preparation should be pushed to index-build or backend services first, with future server-side GPU acceleration considered only behind the backend projection or solver contracts.

15. Renderer Selection

Renderer selection order should be:

Use user override when explicitly set and available.
Prefer WebGPU only if enabled, available, and stable enough.
Use WebGL as the required baseline.
Use non-canvas fallback when canvas rendering fails.

The app must expose enough diagnostics to know which renderer was selected.

The selected renderer may be stored in UI preferences.

The selected renderer must not be stored as academic state.

16. Camera and Viewport State

Camera state is frontend-owned.

Camera state should include:

center or target;
zoom;
rotation if 3D mode uses it;
viewport dimensions;
projection mode;
selected semantic zoom level;
motion preference.

Camera state may be encoded in local UI state.

Camera state must not be required for backend academic queries.

Camera state may be shareable later through a URL if it contains no token.

The initial v1 must not put raw state tokens in URL camera links.

17. Semantic Zoom

Semantic zoom changes what is visible or emphasized at different scales.

Semantic zoom may show credential groups at far zoom.

Semantic zoom may show subject clusters at far zoom.

Semantic zoom may show course nodes at mid zoom.

Semantic zoom may show requirement conditions and labels at close zoom.

Semantic zoom may hide labels to preserve frame rate.

Semantic zoom must not hide unknown or conflict indicators when they are materially relevant to the selected context.

Semantic zoom must not alter academic statuses.

Semantic zoom must be reproducible from view state and graph data.

18. Visual Filters

The atlas may filter by subject.

The atlas may filter by level.

The atlas may filter by credential target.

The atlas may filter by academic status overlay.

The atlas may filter by graph distance from selection.

The atlas may filter by source-backed importance metrics.

The atlas must distinguish local visual filtering from backend graph bounds.

The atlas must show omitted counts from backend graph responses.

The atlas must not imply that filtered-out courses are academically irrelevant unless backend data says so.

19. Picking and Hit Testing

Picking maps pointer or keyboard focus to graph entities.

The worker may build picking acceleration structures.

The renderer may use GPU picking or CPU picking.

The chosen strategy must preserve backend ids through the numeric id mapping.

Hit testing must support nodes.

Hit testing should support visible edges when practical.

Hit testing should support labels when labels are interactive.

Fallback list selection must provide equivalent access without pointer picking.

20. Label Placement

Label placement may be computed by Rust/WASM.

Label placement must support collision reduction.

Label placement must prioritize selected, focused, hovered, and high-relevance nodes.

Label placement must not hide all unknown or conflict labels in a selected context.

Labels must use accessible text equivalents outside the canvas.

Long labels must be truncated or wrapped in visual views without corrupting the underlying text.

The detail panel must show full text.

21. Node Types

The atlas must support graph view node types defined by the backend.

Important v1 node types include:

course_listing;
course_credit;
requirement_group;
requirement_condition;
credential;
source_reference when a graph view includes it.

The atlas must not derive type from visual shape.

The atlas may choose different glyphs for different types.

The atlas must keep text fallback representations for each type.

22. Edge Types

The atlas must support graph view edge types defined by the backend.

Important v1 edge types include:

requires;
unlocks;
part_of_requirement;
equivalent_to;
antirequisite_with;
cross_listed_with;
source_for when a graph view includes it.

The atlas may render edge types with distinct styles.

The atlas must provide a legend or equivalent discoverability.

The atlas must not infer unlocks from visual proximity.

23. Importance and Metrics

Backend-provided metrics may influence visual size.

Metrics may include unlock count, unlock diversity, credential relevance, bottleneck score, bridge score, optionality score, and conflict risk.

The frontend chooses visual mapping.

The frontend must expose enough explanation that visual size is not mistaken for official course importance.

The frontend may normalize metrics per view.

The frontend must not recompute source-backed metrics differently without marking them as local display metrics.

24. Data Transfer

The atlas should use transferable buffers for large numeric arrays when practical.

The atlas should avoid sending full JSON graph payloads repeatedly to the worker.

The adapter should build compact arrays once per graph response.

Incremental updates should send deltas when this is simpler and measured to help.

The first implementation may send full compact inputs if graph sizes remain manageable.

Performance claims must be measured before optimizing protocol complexity.

25. Performance Budgets

The first performance budget should target responsive interaction on ordinary student laptops.

Initial atlas route interaction should avoid long main-thread blocking.

Worker layout jobs should report duration.

Renderer frame times should be sampled.

Input handling should remain responsive during layout.

Large graph views may show progressive layout.

The app may reduce label density under load.

The app may reduce edge detail under load.

The app may switch to fallback view under persistent renderer failure.

Concrete numeric budgets should be set during implementation after real fixtures exist.

26. Progressive Loading

The atlas should support loading a bounded graph view first.

The atlas should support expand-node requests.

The atlas should support overlay refreshes without full layout reset when possible.

The atlas should preserve mental map across small graph updates.

The atlas may pin selected nodes during incremental layout.

The atlas must update omitted counts and bounds when graph responses change.

The atlas must not hide that a view is partial when backend bounds are reached.

27. Fallback View

AtlasFallbackView is required.

It must present graph nodes and relationships without canvas.

It must support search, filtering, selection, and detail opening.

It must show academic status overlays.

It must show unknowns and conflicts.

It must show omitted counts and graph bounds.

It must expose source references.

It must be keyboard usable.

It must be screen-reader usable.

It must be available when WebGL fails.

It must be available when WebGPU fails.

It must be available when WASM worker initialization fails.

28. Low-Power Mode

The app should support a low-power atlas mode.

Low-power mode may reduce animation.

Low-power mode may reduce visible edge detail.

Low-power mode may reduce label density.

Low-power mode may prefer the fallback view.

Low-power mode must not remove academic warnings.

Low-power mode must not remove unknown or conflict indicators.

Low-power mode may be automatic or user-selected.

29. Reduced Motion

The atlas must respect reduced-motion preferences.

Camera transitions should shorten or disable animation when reduced motion is requested.

Layout transitions should avoid excessive motion.

Selection highlights should remain visible without motion.

The app must not require animation to understand graph changes.

30. Failure Modes

The atlas must handle:

graph response validation failure;
missing graph metadata;
worker load failure;
worker runtime error;
worker timeout;
worker cancellation;
layout degraded warning;
WebGL initialization failure;
WebGPU initialization failure;
canvas context loss;
backend graph bounds exceeded;
backend unavailable.

Each failure mode needs a user-facing state.

Each failure mode needs a developer-facing diagnostic.

No failure mode may be converted into academic unknown unless the backend produced academic unknown.

31. Testing

Unit tests should cover data adapter mapping.

Unit tests should cover status-to-visual mapping.

Rust tests should cover layout graph parsing.

Rust tests should cover deterministic seed behavior.

WASM integration tests should cover worker initialization.

Browser tests should cover WebGL baseline rendering.

Browser tests should cover fallback rendering.

Browser tests should cover source-reference access from atlas selection.

Browser tests should cover unknown and conflict overlays.

WebGPU tests should be conditional on capability.

32. Test Fixtures

Atlas fixtures should include:

small course neighborhood;
credential requirements graph;
graph with nested requirement groups;
graph with cross-listed courses;
graph with antirequisite edges;
graph with unknown requirement condition;
graph with conflict overlay;
graph with omitted counts;
graph large enough to exercise culling.

Fixtures must use synthetic or source-safe examples unless extracted source terms are permitted by publication policy.

Fixtures must not include real student tokens.

33. Acceptance Criteria

The atlas can render a course neighborhood through WebGL.

The atlas can initialize the Rust/WASM worker.

The atlas can compute deterministic positions for a fixture.

The atlas can select a node and open a detail panel.

The atlas can show unknown and conflict overlays.

The atlas can show backend omitted counts.

The atlas can fall back when WebGPU is unavailable.

The atlas can fall back when WebGL is unavailable.

The atlas can fall back when the worker fails.

The atlas never changes an academic status because of renderer choice.

34. Future Extensions

Future work may add WebGPU rendering as the preferred renderer on capable devices.

Future work may add GPU-accelerated picking.

Future work may add shared worker layout caching.

Future work may add URL-shareable camera state without token data.

Future work may add offline graph exploration for public catalog data.

Future work may add Rust wgpu rendering if the TypeScript renderer becomes a measured limitation.

Future work must preserve the academic boundary.

35. Review Checklist

The worker protocol contains no academic evaluator.

The renderer protocol contains no backend query logic.

The adapter preserves backend ids.

The fallback view is not optional.

WebGPU is optional.

WebGL is the required canvas baseline.

WASM layout is required for the first atlas.

Academic unknowns remain distinct from worker errors.

Source references remain reachable.

Renderer selection is observable.