Skip to content

Labels as data: one record path for every 2D label (dome prep) - #1144

Merged
rulkens merged 52 commits into
mainfrom
worktree-dome-2d-labels-simplify
Nov 19, 2026
Merged

rulkens merged 52 commits into
mainfrom
worktree-dome-2d-labels-simplify

Conversation

@rulkens

@rulkens rulkens commented Nov 18, 2026

Copy link
Copy Markdown
Owner

Prep for labels on the dome: the 2D label system is rewritten so the dome PR only has to add a projection. Mono only; the dome draws no labels yet.

What changed

  • Layers describe labels as data. Each Layer hands core a LabelSource (items, describe) and a style id. The ten produce*Labels / produce*Captions files, the label director, the CPU projection and the marker-line renderer are deleted.
  • One record buffer. Core encodes descriptions into 64-byte records once, when a source's changes value changes. Per frame only alpha is written, and only the dirty range is uploaded. A still scene uploads nothing.
  • Projection on the GPU, through one OutputProjection with a TypeScript twin (projectLabel, liftedAnchor), parity-tested. Leaders draw in the label renderer.
  • One set of rules for every label (targetAlpha): fades out when its subject fills the view, hides behind bodies, "focused only" leaves the focused subject's label, a hovered or selected label keeps its label, one ranking formula, one text size clamp (LABEL_TEXT_PX), one fade (0.3 s ease).
  • Adjacent fixes: the pick sentinel has one home (packPickWord); label pixel constants are CSS pixels via a new dpr field on FrameView / ViewSpec; the light-time sphere fades by the same pixel rule as its caption; structure rings and their names appear together on every display.

Visible changes

  • Captions lift by an angle (3 radii, 14 CSS px minimum) instead of screen pixels; text stands on its anchor.
  • Declutter is judged at the drawn position, with one ranking for all kinds, so some kept labels differ in crowded views.
  • Constellation names draw at one size (the minimum).
  • The Sun/Earth/Moon caption stagger and the famous-galaxy size ramp are gone.
  • Far-scene labels hide behind planets; near labels ease in and out like far ones.
  • On a 1× display, and so in recordings at --dpr 1, label text is half its former device-pixel size (same CSS size as on Retina). Accepted by the owner.
  • On the dome the light-time spheres' fade distance now depends on the dome's resolution. Accepted; the dome PR sets the dome's pixel scale.

Performance (same-session A-B-A-B against the base, ee682ac07)

Pose labels:near0 CPU ms Label allocation, KB/frame
earth-surface 0.79 → 0.17 954 → 33
solar-system 0.75 → 0.16 897 → 29
star-field 0.73 → 0.18 823 → 32
local-group 0.04 → 0.14 141 → 22

labels:cosmo dropped 0.05–0.1 ms at every pose. GPU label passes are unchanged within noise; two merged swap groups, as before. CPU figures are from the gate run; a later allocation commit lowered the 12-pose mean further (near 0.16 → 0.12 ms, far 0.10 → 0.08 ms).

Known, not fixed here

  • Captions of very big subjects (a focused planet, Andromeda filling half the view) lift out of frame, as on the base.
  • The Perseverance caption shows its leader but no text (predates this branch).
  • Long stream names vanish when the stream spans the view.

Spec: docs/superpowers/specs/2026-11-17-dome-labels-design.md. Plan: docs/superpowers/plans/2026-11-17-labels-as-data-prep.md.

🤖 Generated with Claude Code

OutputProjection describes how a view vector lands on the output image;
projectLabel, liftedAnchor and tangentToward write into a caller's scratch
and allocate nothing. The pinhole carries its principal point so a lens
shift projects like the view-projection matrix it replaces.
lib/projectLabel.wesl carries OutputProjection, ProjectedLabel,
projectLabel and liftedAnchor field for field; writeOutputProjection packs
the uniform. The parity test holds the byte offsets, the field names and
the parallel-tangent epsilon equal across the two languages.
OVERLAYS becomes SELECTION_OVERLAYS (selection rings, clip-path debug) and
LABELS (marker-line leaders, COSMO and NEAR0 captions), so a rig can list
labels without the rings. Mono lists both and names its pinhole output;
outputProjectionOf builds that projection from a frame view.
The label vertex stage projects through lib/projectLabel.wesl and builds the
glyph quad in output px along image-up, written as NDC at w = 1; worldToClip,
pxToClipOffset, emClipScale and the shader's copy of the em retune leave it
(packLabels folds the retune into the em). projectLabels runs the same
projectLabel on the CPU. Until labels carry absolute positions, each slab's
anchors reach view space through an interim viewFromSlab, and COSMO keeps the
near-plane cut its clip-space path had, so no pixel moves. The directors are
built for their rig and hand the label passes their projection.
Splitting OVERLAYS into SELECTION_OVERLAYS and LABELS cost a swap pass
whenever a selection ring drew (Gate A: +1.4 to 2.0 ms merged) and moved the
NEAR0 ring under the COSMO labels. OVERLAYS now comes from one builder,
overlays({ selectionRings }), with the same two steps in the order mono had;
the dome PR lists it without the rings.
The label shader lifts a lifted label off its subject by today's rule
(1.5 apparent diameters, floored at 28 px, raised to clear the ink), from
the subject's radius and the text's ink bottom in the row. worldPos is
the subject, so occludeSubjectPos goes, and a lifted label's row no
longer moves with the camera. The director's applyLift, its far clamp
and em rescale, and the famous and Milky Way producers' own lift are
gone; projectLabels lifts for declutter and pick. NEAR0 declutter keeps
judging a caption at its proposed lift (declutterLift), so no kept label
changes. Leaders still draw as marker lines, synthesized per frame,
until the next commit.
The label renderer gains a records draw (vertexRecords.wesl): hi/lo positions minus the
camera's pair, the style table as a storage buffer, liftedAnchor for 'above' styles, text
clamped to LABEL_TEXT_PX, hover/select whitening by pick word, the sampled-depth verdict at the
subject. runLabelDirector runs each LABEL_DIRECTORS row beside the old directors; screenLabels
rows with describe() register there. COSMO hides labels nearer than 10 kpc (nearHideMpc), a
grounded flag keeps sub-pixel subjects on a body's ground off the depth test, and an idle
director skips its stages. Pick quads come from projectRecords' boxes.
Both Layers declare one LabelSource row instead of a produceLabels closure. A stream's subject
is its length (radius = half), tinted by colourT, picked by the ribbons' code; a figure's name
sits at its anchor with no radius or pick, re-described when the committed artifact changes.
The producers, the constellation caption builder, its style and priority constants and the
stream's old size constants go with their tests.
The craft captions are a LabelSource: the emphasis dim rides the caption's
alpha (changes: the emphasised craft), every craft keeps the shared craft
fade, the reveal band comes from captionRevealM. The frame's body map is
total, so resolveAnchors now leaves a mesh body the frame does not admit
unlocated (a craft before launch draws no caption). bodyCaption,
meshBodyCaption, composeForegroundCaption, captionComposeContextOf and
ForegroundCaption had no other user and go.
Two sources, cosmic on COSMO and the Milky Way's on NEAR0, over the
featured structures of each scale; the store's merged list identity is the
change signal. Each label takes its category's LABEL_STYLES row and fades by
its category's item; the pick is the category's code over the per-category
index, what the ring stamps. aboveRingAnchor, STRUCTURE_LABEL_ABOVE_GAP_PX and
the label fields of STRUCTURE_MARKER_STYLES go; the ring keeps
structureApparentRadiusFade.
One label per famous galaxy from the catalog joined with the compiled-in
names; the catalog object is the change signal, the pick is the famous
code over the row index the point batch stamps. The per-galaxy apparent-size
threshold (6 px for every galaxy) and the distance-ramped size cap give way
to the famousGalaxy row's appear band and LABEL_TEXT_PX. famousLabelStyle and
focusedFamousIndex had no other reader and go.
"You are here" is one item at the origin in the milkyWay style, lifted by the
15 kpc disc radius, picking what the disc impostor picks. The pick gate
moves to core (a focused subject's label stays clickable), so the
galactic-centre gate and milkyWayLabelStyle go.
Every Layer now describes its labels as LabelSource rows, so the object path
that stood beside the record path is deleted: the Label2D director and its
two configs and projections, the producer types (LayerScreenLabel, Label2D*,
PackLabelsArgs), gateLabelProducer, attachLabelDirectors, packLabels, the
old pick-quad and lift helpers (projectLabels, labelPickQuads,
labelScreenRect, labelDisplayEmPx, labelLiftPx, proposedLiftPx,
viewFromSlabOf, hasPickableLabel, isPickableLabel, whitenColor), the old
vertex shaders with LabelData/Uniforms/LIFT_* in io.wesl, and the uniform
and lift layouts with their parity tests.

The label passes read the director's records alone. labelRenderer keeps one
pipeline pair per variant: setRecords/drawRecords become set/draw, the
record shaders become labels/vertex.wesl and vertexOcclude.wesl with plain
entry points, and Label2DEnvelopePolicy becomes LabelEnvelopePolicy beside
LabelDirectorRow. Comments, RENDERER.md and two website fact sources now
name the record path.
…cted label keeps its place

Focused-only and the recession exemption read selection.focus's pick word: the
receding-focus word is null for a body focus, so focused-only hid every label.
A hovered or selected label (spec D6.4) now also skips focused-only and the
focus recession and outranks every declutter band; it still hides behind a
body and fades when its subject fills the view. An 'above' label whose
subject is behind the eye is invisible on the CPU, as in the shader.
- leaderLineStyle.ts goes (no importer); the leader padding gets a TS home
  in src/data/labels/, and it and vertexOcclude's MPC_TO_KM gain parity.
- One-value knobs go: labelRenderer's occludeAgainstScene (always true) and
  the directors' declutterPadPx (8 in both, now LABEL_DECLUTTER_PAD_PX).
- sceneBodyPickId packs through packPickWord; markGroundedRecords clears
  only the grounded bit.
- A label whose glyphs do not all fit is dropped whole, never cut off.
- No per-frame allocation for toggle addresses (built once beside
  records.sources), anchored mesh bodies, or the pick gate.
- Tests: director idle skip and wake, later source re-encoded after an
  earlier one changes, capacity, renderer upload after a rebuild.
- Docs re-pointed from label2DDirector/Label2D; the signatureOf backlog
  item goes with the function.
pxScale in mono is the canvas's device pixel ratio (backing over CSS width,
carried as FrameView.pxPerCssPx), so every label px constant is a CSS px:
text clamp, lift floors, leader gap, width and padding, declutter pad,
appear bands (the light-time sphere's too) and the pick grace pad. The
constants are halved, so a 2x display draws exactly as before and a 1x
display draws labels at the same CSS size instead of twice it.
RENDERER.md gains the label record path (sources, records, stages,
renderer) and its landmines. The dome output-space backlog item is
trimmed to the pixel floors, since dome labels are the dome PR's (spec
section 7), and records the risks that PR carries.
Math.hypot, per-frame presentation sorts, string-building entry lookups and per-call closures removed from the label stages: ~160 KB to ~30 KB per frame.
The ring's min-apparent threshold stayed in device px while the label's
appear band is CSS px times the pixel ratio, so they agreed only at dpr 2.
The ring thresholds are CSS px now, scaled by dpr where compared; dpr 2 is
unchanged. A parity test ties each category's ring to its label style.
Comments say why instead of history; the pick-word docs name packPickWord;
live docs and backlog details no longer name deleted code. overflowFade goes
through fadeBand, the stellar stream label alpha lives in its style row, the
engine's viewRig local is reverted, and the rebaseViewProj f64 note matches
its real consumers. The renderer's text clamp at dpr other than 1 is tested;
the tautological viewRigs test is deleted.
Every label fades by the 300 ms smoothstep ease. The exponential policy, LabelEnvelopePolicy, the director row's envelope field and the unused shown/lastNowMs columns are deleted.
@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Deploying with  Cloudflare Workers  Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status Name Latest Commit Preview URL Updated (UTC)
✅ Deployment successful!
View logs
skymap 12d370f Commit Preview URL

Branch Preview URL
Nov 19 2026, 12:03 AM

@rulkens
rulkens marked this pull request as ready for review November 19, 2026 00:06
@rulkens
rulkens merged commit d4051fb into main Nov 19, 2026
3 checks passed
@rulkens
rulkens deleted the worktree-dome-2d-labels-simplify branch November 19, 2026 01:17
@rulkens rulkens mentioned this pull request Nov 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant