SOF-8027: add the Entity Map at schemas.mat3ra.com/map

[timurbazhirov]

Ticket: SOF-8027 · Epic: SOF-8025
Plan: plan/review/2026-08-16-entity-map.md
Chained onto #416 — review that first; this PR's diff is against feature/SOF-8026.

An interactive map of the whole schema corpus at schemas.mat3ra.com/map/. Pan, zoom, search, fly to an entity, inspect its relationships, share the view as a URL. Both the MVP and polish scope land here.

The layout is the argument

The plan called for fcose. I did not use it, and the reason is the point of the feature.

A force layout arranges schemas by how densely they reference one another — which reproduces the directory tree. That is precisely what review decision 10 rejected: a map that is a prettier ls -R teaches nothing.

So placement is computed instead (src/js/scripts/entityGraphLayout.ts), by architectural layer:

centre  ->  primitives & definitions      the atoms everything is built from
            abstract                      unit-less mathematics
            reusable & reference          domain building blocks
            mixins                        in-memory-entity, system
            ROOT ENTITIES                 material, model, workflow, job …
            entity components
            categories
rim     ->  directories & parsing         concrete catalogues

Reading outward from the middle is reading the build-up the concept docs describe. Measured mean radius per layer, confirming the bands:

primitive	abstract	reusable	system	entity	component	category	directory
268	458	647	837	1020	1215	1499	1708

Three consequences, all good:

• Instant load. Coordinates are baked into graph.json at build time; Cytoscape renders preset positions and lays nothing out. No spinner, no jank.
• Stable across releases. The layout is a pure function of the graph, so unchanged schemas keep their coordinates with no warm-start machinery. The map is worth building spatial memory of.
• Three fewer CDN dependencies. No fcose, cose-base or layout-base — Cytoscape alone, pinned with a subresource-integrity hash.

Encoding

Channel	Encodes
Colour	eight domain families (22 hues would be indistinguishable)
Shape	layer — hexagon root entity, diamond component, ellipse core block, tag mixin, rectangle catalogue
Size	in-degree, so definitions/units and core/primitive/scalar read as the hubs they are
Edge style	solid extends · dashed contains · dotted variant, arrow toward the referenced schema
Badges	isResult / isMonitor / default units, from the properties manifest

Semantic zoom shows landmarks, then hubs, then everything. Font size varies per tier: Cytoscape scales text with zoom, so a fixed size vanishes entirely once the whole map fits on screen — the landmarks tier would have been unreachable.

Also here

Search with fly-to · detail panel with clickable extends / contains / variants / used-by and links to the explorer, resolved JSON, example and GitHub source · #/entity/<id> and #/view/x,y,z permalinks · focus mode (double-click, 2 hops) · edge-kind toggles · family filters from the legend · minimap · keyboard access (/ search, arrows, Escape) · prefers-reduced-motion · pinch-pan on touch.

Testing

Driven in a real browser with Playwright — not just built and assumed:

AFTER LOAD:  565 nodes, 8 legend families, 3 canvases
SEARCH:      12 hits; Enter -> #/entity/material
DETAIL:      Extends (3), Used by (5); links resolve to
             ../#schema/material.json, ../schema/material.json,
             ../example/material.json, github.com/.../schema/material.json
RELATION:    click -> #/entity/in-memory-entity/named-defaultable
DEEP LINK:   fresh tab #/entity/workflow -> selected, panel populated
FOCUS:       "Focused on material · 2 hops", 1389 elements dimmed
ZOOM 0.2:    30 labels (landmarks tier)
EDGE TOGGLE: 375 contains edges hidden of 917
CONSOLE ERRORS: none

Two bugs this caught that review would not have: the whole graph rendering collapsed at the origin (stale graph.json without coordinates), and no labels at all appearing at whole-map zoom (min-zoomed-font-size suppressing the landmarks tier).

Notes for the reviewer

• Deferred: the in-degree heat overlay — node size already encodes it, so the extra control earns nothing. Not filed as a follow-up.
• Dropped: the isolated-node "islands" strip. It existed to stop a force layout scattering disconnected schemas; a deterministic layout places them in their own band correctly.
• window.esseEntityMap is exposed deliberately, as a console handle on a page whose purpose is poking at the schema graph.
• The map needs graph.json at the site root, which SOF-8026: extract schema reference graph (graph.json) and lint the corpus #416 publishes.

🤖 Generated with Claude Code

---

Generated by Claude Code