Skip to content

ByteTerrace/Puck / .claude/skills/puck-world

puck-world

Verified

Maps Puck.World: .puck worlds, rules, grants, console verbs, extensions, the live MCP World. Use to run or verify a World change (stdin script, stale binary, headless run) or debug a refusal.

FileKindSize
SKILL.mdskill md72.0 KB
evals/w01-seat-mouse-look-sensitivity/graders/behavior-preserving-default.mdmarkdown191 B
evals/w01-seat-mouse-look-sensitivity/graders/names-the-existing-record.mdmarkdown71 B
evals/w01-seat-mouse-look-sensitivity/graders/no-flag-or-constant.mdmarkdown89 B
evals/w01-seat-mouse-look-sensitivity/graders/one-seat-through-identity.mdmarkdown186 B
evals/w01-seat-mouse-look-sensitivity/graders/pointer-sensitivity-members.mdmarkdown88 B
evals/w01-seat-mouse-look-sensitivity/graders/read-back-verb.mdmarkdown76 B
evals/w01-seat-mouse-look-sensitivity/graders/reuses-existing-vocabulary.mdmarkdown155 B
evals/w01-seat-mouse-look-sensitivity/graders/skill-fired.mdmarkdown36 B
evals/w01-seat-mouse-look-sensitivity/graders/value-in-the-document-model.mdmarkdown125 B
evals/w01-seat-mouse-look-sensitivity/prompt.mdmarkdown268 B
evals/w02-row-set-refusal/graders/actor-differs-from-target.mdmarkdown158 B
evals/w02-row-set-refusal/graders/captures-both-streams.mdmarkdown122 B
evals/w02-row-set-refusal/graders/grant-versus-subject.mdmarkdown283 B
evals/w02-row-set-refusal/graders/skill-fired.mdmarkdown36 B
evals/w02-row-set-refusal/graders/stamped-principal.mdmarkdown252 B
evals/w02-row-set-refusal/graders/success-control.mdmarkdown70 B
evals/w02-row-set-refusal/prompt.mdmarkdown251 B
evals/w03-hermetic-hud-script/graders/announcement-on-stderr.mdmarkdown84 B
evals/w03-hermetic-hud-script/graders/bom-less-utf8.mdmarkdown75 B
evals/w03-hermetic-hud-script/graders/captures-both-streams.mdmarkdown75 B
evals/w03-hermetic-hud-script/graders/drain-barrier-or-wait.mdmarkdown96 B
evals/w03-hermetic-hud-script/graders/frame-after-pending.mdmarkdown204 B
evals/w03-hermetic-hud-script/graders/isolated-state-directory.mdmarkdown76 B
evals/w03-hermetic-hud-script/graders/pixel-versus-replay-proof.mdmarkdown108 B
evals/w03-hermetic-hud-script/graders/skill-fired.mdmarkdown36 B
evals/w03-hermetic-hud-script/prompt.mdmarkdown224 B
evals/w04-cooldown-rule/graders/authored-as-puck.mdmarkdown138 B
evals/w04-cooldown-rule/graders/boots-the-source.mdmarkdown76 B
evals/w04-cooldown-rule/graders/compiled-in-memory.mdmarkdown143 B
evals/w04-cooldown-rule/graders/folds-through-the-rule-frame.mdmarkdown170 B
evals/w04-cooldown-rule/graders/gate-on-tick.mdmarkdown68 B
evals/w04-cooldown-rule/graders/names-the-mutation-kinds.mdmarkdown140 B
evals/w04-cooldown-rule/graders/no-decrementing-remainder.mdmarkdown97 B
evals/w04-cooldown-rule/graders/remove-sugar.mdmarkdown71 B
evals/w04-cooldown-rule/graders/row-set-is-not-authoring.mdmarkdown109 B
evals/w04-cooldown-rule/graders/schedule-sugar.mdmarkdown73 B
evals/w04-cooldown-rule/graders/skill-fired.mdmarkdown36 B
evals/w04-cooldown-rule/graders/targets-the-debug-world.mdmarkdown215 B
evals/w04-cooldown-rule/prompt.mdmarkdown239 B
evals/w05-gcp-storage-provider/graders/assembly-attribute.mdmarkdown82 B
evals/w05-gcp-storage-provider/graders/catalog-in-a-running-host.mdmarkdown83 B
evals/w05-gcp-storage-provider/graders/duplicates-refused-by-name.mdmarkdown149 B
evals/w05-gcp-storage-provider/graders/extension-model-laws.mdmarkdown79 B
evals/w05-gcp-storage-provider/graders/installed-not-referenced.mdmarkdown171 B
evals/w05-gcp-storage-provider/graders/mcp-services-provider.mdmarkdown188 B
evals/w05-gcp-storage-provider/graders/no-own-directory-scan.mdmarkdown84 B
evals/w05-gcp-storage-provider/graders/no-per-kind-interface.mdmarkdown87 B
evals/w05-gcp-storage-provider/graders/no-static-registry.mdmarkdown74 B
evals/w05-gcp-storage-provider/graders/one-extension-project.mdmarkdown105 B
evals/w05-gcp-storage-provider/graders/one-hosted-control.mdmarkdown85 B
evals/w05-gcp-storage-provider/graders/registers-through-add-storage.mdmarkdown141 B
evals/w05-gcp-storage-provider/graders/skill-fired.mdmarkdown36 B
evals/w05-gcp-storage-provider/prompt.mdmarkdown246 B
evals/w06-agent-harness-on-azure/graders/agent-harness-participant.mdmarkdown71 B
evals/w06-agent-harness-on-azure/graders/body-five.mdmarkdown81 B
evals/w06-agent-harness-on-azure/graders/default-azure-credential.mdmarkdown79 B
evals/w06-agent-harness-on-azure/graders/deliberate-approval.mdmarkdown89 B
evals/w06-agent-harness-on-azure/graders/extensions-document.mdmarkdown84 B
evals/w06-agent-harness-on-azure/graders/grants-in-the-world.mdmarkdown162 B
evals/w06-agent-harness-on-azure/graders/installs-beside-each-host.mdmarkdown156 B
evals/w06-agent-harness-on-azure/graders/local-config-flag.mdmarkdown81 B
evals/w06-agent-harness-on-azure/graders/no-key.mdmarkdown60 B
evals/w06-agent-harness-on-azure/graders/participant-laws.mdmarkdown86 B
evals/w06-agent-harness-on-azure/graders/participant-settings.mdmarkdown175 B
evals/w06-agent-harness-on-azure/graders/principal-not-console.mdmarkdown114 B
evals/w06-agent-harness-on-azure/graders/silo-extension-laws.mdmarkdown83 B
evals/w06-agent-harness-on-azure/graders/silo-row-extensions-member.mdmarkdown125 B
evals/w06-agent-harness-on-azure/graders/skill-fired.mdmarkdown36 B
evals/w06-agent-harness-on-azure/graders/status-line.mdmarkdown103 B
evals/w06-agent-harness-on-azure/prompt.mdmarkdown202 B
evals/w07-failed-build-stale-binary/graders/build-exits-zero.mdmarkdown104 B
evals/w07-failed-build-stale-binary/graders/documented-recipe.mdmarkdown114 B
evals/w07-failed-build-stale-binary/graders/hermetic-state-dir.mdmarkdown68 B
evals/w07-failed-build-stale-binary/graders/old-binaries-ran.mdmarkdown170 B
evals/w07-failed-build-stale-binary/graders/reports-the-run.mdmarkdown76 B
evals/w07-failed-build-stale-binary/graders/same-script.mdmarkdown72 B
evals/w07-failed-build-stale-binary/graders/says-no.mdmarkdown91 B
evals/w07-failed-build-stale-binary/graders/skill-fired.mdmarkdown36 B
evals/w07-failed-build-stale-binary/prompt.mdmarkdown261 B
evals/w08-gpu-grant-held-by-parity/graders/build-exit-zero-first.mdmarkdown129 B
evals/w08-gpu-grant-held-by-parity/graders/build-runs-beside-the-leg.mdmarkdown153 B
evals/w08-gpu-grant-held-by-parity/graders/effective-presentation-modes.mdmarkdown118 B
evals/w08-gpu-grant-held-by-parity/graders/headless-runs-now.mdmarkdown171 B
evals/w08-gpu-grant-held-by-parity/graders/headless-world-is-not-gpu-work.mdmarkdown142 B
evals/w08-gpu-grant-held-by-parity/graders/self-excluding-search.mdmarkdown166 B
evals/w08-gpu-grant-held-by-parity/graders/skill-fired.mdmarkdown36 B
evals/w08-gpu-grant-held-by-parity/graders/windowed-waits-for-a-grant.mdmarkdown121 B
evals/w08-gpu-grant-held-by-parity/prompt.mdmarkdown279 B
evals/w09-live-world-mcp/graders/camera-read-back.mdmarkdown76 B
evals/w09-live-world-mcp/graders/lists-the-worlds.mdmarkdown68 B
evals/w09-live-world-mcp/graders/names-the-world.mdmarkdown178 B
evals/w09-live-world-mcp/graders/own-world-for-worktree-edits.mdmarkdown222 B
evals/w09-live-world-mcp/graders/restores-the-mutation.mdmarkdown174 B
evals/w09-live-world-mcp/graders/skill-fired.mdmarkdown36 B
evals/w09-live-world-mcp/prompt.mdmarkdown360 B
evals/w10-bounded-diagnostic-report/graders/bounds-and-running.mdmarkdown542 B
evals/w10-bounded-diagnostic-report/graders/snapshot-and-hold.mdmarkdown453 B
evals/w10-bounded-diagnostic-report/prompt.mdmarkdown547 B
evals/w11-reload-delta/graders/delta-and-drain.mdmarkdown1.1 KB
evals/w11-reload-delta/prompt.mdmarkdown735 B
references/addons.mdmarkdown32.7 KB
references/adjacency-and-federation.mdmarkdown55.7 KB
references/authority.mdmarkdown40.0 KB
references/console.mdmarkdown58.5 KB
references/documents-composition.mdmarkdown34.4 KB
references/documents-identity.mdmarkdown19.4 KB
references/documents-motion.mdmarkdown37.2 KB
references/documents-render.mdmarkdown40.5 KB
references/documents-rules.mdmarkdown27.4 KB
references/documents-state.mdmarkdown59.2 KB
references/documents.mdmarkdown21.1 KB
references/engagement.mdmarkdown50.6 KB
references/hosting-and-release.mdmarkdown31.1 KB
references/hud.mdmarkdown33.4 KB
references/mutations.mdmarkdown36.4 KB
references/ordered-domain.mdmarkdown14.6 KB
references/replay.mdmarkdown69.7 KB
references/schedules-and-tests.mdmarkdown26.4 KB
references/session-lifecycle.mdmarkdown15.0 KB
references/views.mdmarkdown54.8 KB

references/hud.md

View on GitHub
# The HUD — document-authored overlay panels

The HUD is a world-document section rendered through the banded overlay
pipeline. Document side: `src/Puck.World.Schema/WorldHud.cs` +
`HudValidation.cs` (schema details in [documents.md](documents.md)). Render
side: `src/Puck.World/WorldHudFeed.cs`, `WorldHudBindingResolver.cs`,
`src/Puck.Overlays/HudWriter.cs`, `OverlayFrameComposer.cs`, `OverlayPackage.cs`,
`OverlayChannels.cs`, `OverlayFrameBuilder.cs`. Verbs:
`src/Puck.World/WorldHudCommandModule.cs`. Mutation kinds: see
[mutations.md](mutations.md) (ordinals 39–43).

**Owner's rulings for the debug world.** The debug world once kept the
controller bar as its only on-screen UI to clean things up; the owner lifted
that restriction, so a panel, prompt or menu is added where it serves (the
[UI decisions](../../../../docs/decisions/ui.md) and the host menu in them).
A mouse chord stays off the bar and the bar's `modifiers` row stays off. Every
control the bar shows has a sensible keyboard equivalent bound beside it, for
example WASD beside the d-pad (`worlds/debug/avatars/moth.puck`, `moth.md`).
Addon panels sit behind a separate toggle, off by default, and agents show
them when they need them (the owner's ruling). The `addonHud` state row
(`worlds/debug/addon-hud.puck`) gates every addon panel: each panel's `visible`
is an `all` of `state.addonHud` equal to 1 and its own condition. Today those
are the watchdog's panel, while a violation is recorded, and the gallery
guide's, in front of an exhibit, and the kinematics scope's while `scope[enabled]`
is nonzero. The scope is an off-by-default development tool, not part of normal
play. `world.state.cell.set addonHud $value 1` shows
them and `0` hides them. A new addon panel takes the same gate.

## Contents

- Schema and caps
- Overlay visibility
- Authoring a panel in `.puck`
- Templating (`WorldHudElement.Template`)
- The overlay reservation — what refuses at construction
- Bands — what `replace` replaces
- The reconcile split — structure vs values
- Verbs
- Verifying

## Schema and caps

`WorldHudSection(Defaults, Panels)`; `WorldHudDefaults(Enabled, Cursor?)` is
a world-level kill switch plus the drawn pointer cursor's per-world policy —
`WorldHudCursor(HoverRadius, SizePx, Role, Visible?)` (hover reach in world
units, ring radius in px, the bare cursor's core theme role (`WorldThemeRole`), an
optional visibility predicate; null draws no cursor at all, since the engine
has none of its own and the live policy is authored in
`worlds/standard/controls.puck`; whole-row replace semantics on
`SetHudDefaults`, so a defaults row authored without it clears the cursor). Validated by `hud.CursorInvalid`;
echoed RESOLVED by `world.hud`; the live pointer state (position, visibility
verdict, hover target) echoes through `world.view.pointer`
([views.md](views.md)). `WorldHudPanel(Id, Rect, Layer, Style, Elements)` —
rect normalized in SCREEN space, origin top-left, Y down.
`WorldHudElement(Id, Kind, Rect, Style, Text?, Binding?, Template?)` — rect
normalized in the OWNING PANEL's local space. `WorldHudElementKind`: `Rect`,
`Text`, `Gauge` (a bound Text's live value replaces the authored literal, or
a `Template`'s resolved string does; a bound Gauge's value drives its fill;
an unbound gauge draws empty).
`WorldHudLayer`: `Under`, `Over`, `Replace`. `WorldHudPanelStyle`:
`Panel`/`Strip`/`Chip`; `WorldHudStyleToken`: `Primary`/`Dim`/`Accent`/
`Positive`/`Warning`/`Danger`.

A Text element's optional `voice` is a `WorldVoiceProfile`: either `patchId`
or a document-relative `sampleSet` manifest, and
`cadenceTicks` plus integer `pitchThousandths`, `formantThousandths` and
`paceThousandths` scales (1000 neutral). It speaks its resolved text once on
visible arrival/change and stops on hiding, through `WorldHudSpeechFeed` and
the existing audio director/mixer. `audio.render <panelId> <elementId>
<output.wav>` exports that same source headlessly, ignoring visibility.
[The audio reference](../../../../docs/reference/audio.md#text-speech) owns the
units and articulation; `worlds/debug/guide.puck` authors the synthesized guide
and sampled map sign. `WorldVoiceSampleLoader` loads six vowel/consonant WAV
classes relative to their set; both sources share `TextSpeechSource`'s schedule.

`WorldHudCapacity` (the DOCUMENT contract): `MaxWorldPanels = 5`,
`MaxElementsPerPanel = 24`, `MaxSeatPanels = 1`, `MaxElementsPerSeatPanel =
12`, and `MaxFrameSources = 8` structurally unique `Frame` sources per HUD
document (repeated elements naming the same source share one slot). World and
identity HUD documents validate independently; if their live composition exceeds
eight unique sources, the unified overlay omits the additional source and narrates
that aggregate runtime episode instead of failing silently. The render cost an authored element expands into is the WRITER's own
constant in `Puck.Overlays` (`HudWriter.GaugeElementCost = 3` records,
`HudWriter.TextRunChars = 64` glyph words — the latter enforced as a
`WriteText` `maxChars` clamp, the way `GaugeLabelChars` always was for a gauge
label, so a template resolving many long `state` cells clips as the writer's
own attributed refusal rather than over-running the Hud reservation and
DROPPING element records). Schema declares no render cost.
Enforced by
`WorldDefinitionValidator.ValidateHudCore`, which appends every violation as a
`hud.<reason>: …` line through `HudRowValidation.Refuse` (never throwing, so one
bad row does not hide the rest) with an enum `HudRefusal` reason
(`src/Puck.World.Schema/HudValidation.cs`; the enum is the whole vocabulary,
panel and element counts, ids, rects, bindings, templates, the cursor, frame
sources and the `visible` predicate, under door `hud.validate` in
`world.refusals`; a blank id folds into the duplicate reason). `ValidateHudCore` takes an `isIdentityScope`
flag (`definition.Identity is not null` at its one call site) that swaps
`MaxWorldPanels`/`MaxElementsPerPanel` for the tighter
`MaxSeatPanels`/`MaxElementsPerSeatPanel` (a second seat panel refuses as
`TooManyPanels`, naming `MaxSeatPanels`) and refuses
`WorldHudLayer.Replace` with `SeatPanelReplaceRefused` — applied to EVERY document
carrying an `Identity` section (an owned world's boot load, a sync pull, and
`identity.hud`'s own candidate check below), never hand-rolled per door.

**Bindings are a CLOSED vocabulary** (`HudBindingVocabulary`): `world.tick`,
`world.fps`, `population.active`, `history.cursor` (the in-session history's
cursor tick, its gauge the cursor's place in the window), `history.window` (the
window's ends, its gauge how far it has filled toward its length; both read `off`
with no window), `seat.<n>.position.{x,y,z}` with `<n>`
1-based in 1..4, `state.<row>` (a `state`-section row's own SLOT cell), and
`state.<row>.<key>` (one named cell in ANY row shape — see
[documents.md](documents.md)'s `state` section). The split on the FIRST dot
after `state.` is unambiguous because a row/cell name can never itself hold a
dot (`CellName`). Refused by name at validation (`UnknownBinding`); an
empty-string binding reads as unbound rather than refused. The SAME `TryParse`
serves the validator and the render resolver, so a document can never carry a
binding the renderer silently treats as unbound; `StateBinding.TryParse` is its
`state.*` arm, the one parse every bindable token (`BindableScalar`,
`BindableColor`, `WorldColor`, overlay and binding-bar cells) goes through, and a
bindable stores the parsed `StateBinding` rather than re-parsing per read.

The generic `reading.<name>` and `recent.<name>` arms resolve registered
`PresentationReadings` sources. `HostFrameTimeline.RegisterReadings` publishes
`host.frames.interval` and `host.frames.work` in milliseconds straight from
its closed-iteration ring, including the same zero-based sample indices
`host.frames` reports. `WorldBenchmarkCommandModule` publishes its chapter,
tick, state, budget and visibility through that registry. Unknown runtime
sources are **absent**, registered sources awaiting samples are **unmeasured**,
and measured zero is **present**; text and plot status labels preserve those
distinctions. There is no HUD sampling ring.

`WorldHudElementKind.Plot` requires a `recent.<name>` binding. Its authored
`plotSamples` window, `plotMin`/`plotMax` range and optional constant
`plotReference` or live `plotReferenceBinding` drive `HudWriter.EmitPlot`.
The shared `HudRowValidation.ValidateElements` bounds total plot samples per
panel by `WorldHudCapacity.MaxPlotSamplesPerPanel`. `WorldOverlayCapacity`
transports that bound to `OverlayChannels`, which reserves each bar's
`HudWriter.PlotSampleElementCost` separately from ordinary element records.
The writer also bounds emission by that per-panel reservation.

The optional standard panel is `worlds/standard/benchmark.puck`, imported by
the debug world. `world.benchmark overlay on|off|auto` controls its visibility
reading; `auto` follows a playing run. Its predicate is generic
`{ $type: "reading", name: "benchmark.visible" }`, which holds only for a
present nonzero value or nonempty text. `world.hud` echoes visibility, reading
state, sample index, plot window and reference through the render resolver.

Either `state.*` form may carry a trailing `.$target` facet —
`state.<row>.$target` or `state.<row>.<key>.$target` — reading the addressed
cell's stored TRUTH instead of its live eased value when the cell carries a
`dynamics` trait (see [documents.md](documents.md)'s `dynamics` trait
paragraph). `$` marks the engine's own namespace (the same convention
`$value` already uses for a slot cell's key), so `target` alone — with no
`$` — parses as an ordinary author-chosen cell key, never the facet; an empty
row before `.$target` (`state.$target`) refuses. A cell with no `dynamics`
trait resolves the SAME value through either spelling, since truth and the
eased read agree when nothing is easing. The `seat.<n>.position.*`
family resolves its body index through the per-seat PERCEPTION ANCHOR
(`src/Puck.World.Client/WorldPerceptionAnchor.cs` — the seat's bound body, slot n-1, or the
routed body while possessing), the same resolution point the camera anchor
pose and the audio listener derive through, so all three follow a possession
anchor swap together, published every tick by `WorldSeatContextSync.Publish`
off the SAME grant-table Control-route read the `engagement` context family
already performs (see [engagement.md](engagement.md)); `body.where` echoes
the anchor (`anchor=body:<n>`, 0-based) for local seats.

A `state.<row>`/`state.<row>.<key>` binding's EXISTENCE — the row, and for the
cell form the key — is validated wherever a real `state` section exists to
check against: `WorldDefinitionValidator.ValidateState` returns the
declared rows BY NAME (not just the name set) and threads that into the HUD
checks (`HudRowValidation.ValidateElement`'s `stateRows` parameter), so an
unknown row OR an unknown key on a real row refuses by the SAME `UnknownBinding`
reason a malformed token does. An identity-owned world's own HUD panel
(`WorldIdentity.Hud`, read from that document's OWN `Hud.Panels`) validates
through this identical path against that document's OWN `state` section — it
is a full `WorldDefinition`, not a separate document family, so there is no
distinct "cannot verify existence" scope in this codebase today;
`HudRowValidation`'s `stateRows: null` parameter default exists for a caller
with no such document to check against, but nothing currently calls it that
way. Render-side, `WorldHudBindingResolver` parses each token once and looks
a `state.*` token's slot up (`WorldStateMirror.SlotOf`), the one path every
presentation binding reads through. A world-scope panel's token reads the
client's state mirror (`WorldClient.StateMirror`), where the document's
presentation manifest registered it. A seat's player-scope panel's token reads
the mirror of the world that seat is routed to
(`WorldSeatBindings.GetRoutedState`), where the seat registered its panel's
bindings with the rest of its reads (`WorldPresentationManifest.SeatBindings`),
so a crossed seat's panel shows the world it is in, like its bar, pages,
wheels and contexts; `HudWriter` passes the panel's seat to
`IHudBindingResolver.TryResolve`, -1 for a world-scope panel. Its text is a
borrowed character span, consumed before the next resolve. History bindings
format into a reused buffer, and `HudWriter` copies a composed template into
reused character storage, so a steady history line allocates nothing. A cell carrying a
`dynamics` trait presents its eased follower, interpolated at the frame's fraction, unless the
token carries the `.$target` facet above, in which case it presents stored truth
exactly like a cell with no trait always does. The text shows the value read at
the delivered tick. A
bound TEXT element renders the resolved cell's
value; a bound GAUGE element's fraction is `(value − min) / (max − min)`
clamped to `[0, 1]` off the ROW's OWN `min`/`max` (cells carry no envelope of
their own) when the row is `int`/`fixed` AND declares BOTH (`WorldStateRow`'s
both-or-neither rule); otherwise (a `bool`/`text` row, a numeric row with no
declared range, or a plain `state.<row>` binding on a KEYED row with no single
cell to show) the gauge draws EMPTY — the same "unbound gauge draws empty"
rule an unbound binding already follows, not a new validation-time refusal
(only existence is checked).

## Overlay visibility

Every overlay element — a `hud.panels` row, a
seat's player-scope panel, `hud.defaults` (the gate over every world panel),
`hud.defaults.cursor`, and a binding overlay's `bindingBar` — takes an optional `visible` predicate
over per-seat presentation facts (`OverlayPredicate` / `OverlayFact`,
`WorldOverlayVisibility.cs`; evaluated by `WorldOverlayFacts`): `now {fact}`,
`recently {fact, windowSeconds}`, `all`, `any`, `not`. Facts: `SeatInput` (a
routed signal this tick), `PointerMotion`, `WheelOpen`, `ConsoleOpen`,
`SeatCameraApplication` (the seat's camera control application is active —
`WorldSeatBindings.IsCameraModeActive`), `ScreenFramed` (the seat is captured
on a screen and its view shows that picture alone — `WorldPerceptionAnchor.ScreenFramed`).
Absent = always visible. `{ "$type": "recently", "fact":
"SeatInput", "windowSeconds": 3 }` hides an element three seconds after the
seat's last input and shows it on the next; a world-scope panel reads a fact as
true when it holds for any joined local seat. Windows compile through the world's
simulation rate; nothing here enters the simulation.

## Authoring a panel in `.puck`

`hud` has no dedicated DSL sugar or decompiler module (unlike `rules`/`shapes`/
`placements`/`prototypes`) — a panel is authored through the language's
generic named-block/array-property grammar alone (grammar and diagnostics
belong to the `puck-dsl` skill; this is just the vocabulary applied). A world
declaring the two `state` rows a panel below binds against, plus one panel
with a bound text element and a bound gauge:

```
state {
    world [
        { name: "score", kind: "Int", value: 0 }
        { name: "fuel", kind: "Int", value: 100, min: 0, max: 100 }
    ]
}

hud {
    defaults {
        enabled: true
    }
    panels [
        {
            id: "status"
            rect { x: 0.02, y: 0.02, width: 0.22, height: 0.08 }
            layer: "Under"
            style: "Strip"
            elements [
                {
                    id: "score-label"
                    kind: "Text"
                    rect { x: 0, y: 0, width: 1, height: 0.5 }
                    style: "Primary"
                    binding: "state.score"
                }
                {
                    id: "fuel-gauge"
                    kind: "Gauge"
                    rect { x: 0, y: 0.5, width: 1, height: 0.5 }
                    style: "Accent"
                    binding: "state.fuel"
                }
            ]
        }
    ]
}
```

`fuel` declares both `min`/`max` (the both-or-neither rule), so its gauge
fraction resolves from the row's own range rather than drawing empty. A
`Template` element is the same panel/element shape with `template:` in place
of `binding:` — see "Templating" below for the placeholder grammar.

## Templating (`WorldHudElement.Template`)

A `Text` element's `Template` string interleaves literal text with `{token}`
placeholders — each token the SAME closed `HudBindingVocabulary` a plain
`Binding` speaks, resolved through the SAME `IHudBindingResolver`/`TryResolve`
call — so many live facts compose into ONE string (`"Score: {state.score} -
{state.greeting.morning}"`) instead of one bound value replacing the whole
element. `Binding` and `Template` are refused together on one element
(`TemplateBindingConflict`) — exactly one live-value source, never a race
between two. Meaningful only for `Text`; ignored (like `Text`/`Binding`
already are) for `Rect`/`Gauge` — a gauge's fill is one fraction, not a
composed string.

**Grammar** (`HudTemplate` in `WorldHud.cs`, the ONE parser both the validator
and the console verb below call): `{{` and `}}` escape a literal brace (the MS
composite-format-string convention, not a bespoke one); `{token}` is a
placeholder. An unterminated `{`, an empty `{}`, or a lone unescaped `}` is
MALFORMED and refused by name (`MalformedTemplate`) rather than guessed at.
Every placeholder is additionally resolved against `HudBindingVocabulary` and,
for a `state.*` token, the document's own `state` section — the SAME
existence check a plain `Binding` gets — refusing by name
(`UnknownTemplatePlaceholder`) at the FIRST bad placeholder, never a partial
or silently-empty interpolation.

**`HudTemplate.TryParse` is the ONLY parse of this grammar anywhere, and the
render path is not one of its callers.** `Puck.Overlays` cannot reference
`Puck.World.Schema` (the architecture boundary), so `WorldHudFeed` parses on the
structure rebuild and hands the overlay PRE-PARSED runs
(`OverlayHudTemplateSegment`: literal-or-placeholder); `HudWriter` only
substitutes, and carries no grammar at all — the same direction the HUD
ceilings travel (as an `OverlayCapacity` the composition root builds from
Schema; nothing in `Puck.Overlays` restates a World number). Parsing on the structure rebuild
also moves the cost off the per-frame path: world scope parses per revision,
seat scope per identity edit (each seat's built panel is memoized against the
document row INSTANCE it came from, so the unconditional per-frame seat walk
stays allocation-free).

A template's `state.*` placeholders participate in whole-document
revalidation exactly as a plain `Binding` does, so `world.row.remove state` of a
row a live template names REFUSES (`hud.UnknownTemplatePlaceholder`, against
`hud.UnknownBinding` for the binding form) and the element can never go
silently stale; drop the element or the panel first. Measured on both forms
against a control (the same row removes cleanly once nothing names it).

**`world.hud.template <text...>`** (Immediate, `WorldHudCommandModule`)
resolves an AD HOC template against the LIVE document on demand — never
authored, never stored on any row. Every placeholder is validated (grammar,
vocabulary, and — for `state.*` — the live document's row/cell existence)
BEFORE anything resolves, so a bad placeholder refuses the whole call by name.
This is the read-back rule's second half for templating: `world.state`
already echoed an authored text table (see [documents.md](documents.md)'s
`state` section — a `text`-kind row IS the table substrate, keyed cells and
all); `world.hud`'s per-element echo also resolves a document
Template (reusing `HudTemplate.TryParse`, no second parser needed inside
`Puck.World`); `world.hud.template` covers the one case neither already did —
a template with no document row behind it at all.

## The overlay reservation — what refuses at construction

`OverlayChannel` has nine members, value = draw priority for the first four:
`Console = 0`, `BindingBar = 1`, `Markers = 2`, `Toast = 3`, `Hud = 4`,
`Cursor = 5`, `Wheel = 6`, `Editor = 7` (the inspector, drawn after the seat
panels), `Annotation = 8` (`AnnotationWriter`, the `view.annotate` outlines,
drawn after the editor and just before the wheel and cursor, unclipped; see
[views.md](views.md)). `AnnotationWriter` is the one writer of marks over the
frame: it also draws the `Markers` channel (`EmitMarkers`, seat-clipped chips
and rings) and the diagnostic pins (`EmitDiagnostics`). The FOUR first-party
writers are `ConsolePanelWriter`, `BindingBarWriter`, the marker emission of
`AnnotationWriter` and `ToastWriter` (`FirstPartyChannelCount = 4`); `HudWriter`
is the fifth channel, banded, not one of the four; `WheelWriter` and
`CursorWriter` are the frame's last two scopes (wheel drawn first, cursor on
top), outside the replace-band suppression — see [views.md](views.md).

`OverlayChannelLeases` (`src/Puck.Overlays/OverlayChannels.cs`) is an
INSTANCE built from an `OverlayCapacity` — the host's declared counts
(`Seats`, `HudPanels`, `HudElementsPerPanel`, `HudSeatPanelsPerSeat`,
`HudElementsPerSeatPanel`). `Puck.Overlays` restates no World number: the
composition root (`WorldBootComposition`'s one `new OverlayPackage`)
supplies `Puck.World.Client.WorldOverlayCapacity.FromSchema()` — `Seats =
WorldBodiesLimits.LocalSeatCount`, the four HUD ceilings from
`WorldHudCapacity` (`MaxSeatPanels` is the seat-panel count). Render costs stay
the writers' own (`HudWriter.GaugeElementCost`, `HudWriter.TextRunChars`, the
per-seat writers' caps — the `CursorWriter` discipline). The runtime guard is
`builder.Leases.EnsureSeatCapacity`, which throws on a roster/capacity
mismatch. The Hud reservation covers world scope (panels × elements) PLUS the
seat scope (seats × seat panels × elements), each resource at its own worst
case (`Elements` at the gauge cost, `TextWords` at the text-run clamp, one
clip per panel).

The table REFUSES AT CONSTRUCTION: its summed totals are checked against
`OverlayFrameBuilder`'s four backstops (`MaxPanels`, `MaxElements`,
`MaxClips`, `TextWordCapacity` — the GPU region the shader addresses) and an
over-subscription throws `ArgumentOutOfRangeException` naming the resource,
the total, and the backstop, on every boot. The cross-assembly proof that the
Schema-derived capacity fits is
`tests/Puck.World.Client.Tests/OverlayLeaseTableFitsBackstopsLawTests.cs`.
Runtime overflow is per-channel and attributed (a channel clips at
its own boundary, never costs another channel), with two separately-latched
narrations: reservation overflow vs a writer's own declared cap refusal.
Binding-bar visibility, layout, and scale do not change this arithmetic. The
slot reservation DOES scale with the authored vocabulary: it is
`WorldBindingBarCapacity.MaxBanks` (5 — five chord
banks: resting/LT/RT/LT>RT/RT>LT) times `MaxSlots` (32 — the declared ceiling on
one bar's authored slot set of input source ids) slots, plus
the one label, `WorldBindingBarCapacity.MaxModifiers` (16) modifier
indicators (`OverlayCapacity.BindingBarMaxModifiers`), and
`BindingBarWriter.MaxHintLines` (8) chord hints of up to
`BindingBarWriter.MaxHintMembers` (4) member chips and one action chip or label
each, which every bar draws once regardless of bank count — `OverlayCapacity.BindingBarMaxBanks`/
`BindingBarMaxSlotsPerBank`, composed the same way the Hud ceilings are.
`OverlayFrameBuilder.MaxElements` (2048) is sized to fit this reservation
beside the others.

## Bands — what `replace` replaces

`OverlayFrameComposer.Compose`, once per frame the `overlay` package records: feed tick → `RefreshFrame`
(snapshot the structure once) → UNDER band (its own
`BeginChannel(Hud)` scope) → BASE slot → OVER band. The base slot is: if any
live panel declares `Replace`, the replace panels draw IN DOCUMENT ORDER
INSTEAD OF the four first-party writers — exactly those four, nothing else;
otherwise the four run in enum order. `HasReplace` recomputes from the
fresh snapshot every frame, so removing the last replace panel restores the
writers the next produced frame. The stdin/stdout control plane is
untouched by `Replace` — the console MIRROR merely stops being drawn.
Document row order within a band is the author's ordering control. World
scope opens up to three `BeginChannel` scopes per frame; the seat-panel pass
can open a fourth. All four charge the one Hud reservation.

## The reconcile split — structure vs values

- **Structure.** World-scope panels reconcile only when
  `WorldClient.DefinitionRevision` moves: `WorldHudFeed.Tick` maps document
  panels to `OverlayHudPanel` rows; `Defaults.Enabled: false` publishes an
  empty panel set. Seat-scope panels (`WorldIdentity.Hud`, ONE
  optional panel per identity, `WorldHudCapacity.MaxElementsPerSeatPanel`
  elements, edited through `identity.hud <panel-json> [player]` and read back
  with `world.hud seat<n>` or `identity.show`) recompose EVERY produced frame
  from `PlayerRoster` + each joined seat's live identity handle instead — no
  cheap revision to key off, and no extra propagation seam for a write to
  reach the render path — into a preallocated array, then both halves publish
  together in one `OverlayStore.Publish` call so neither can lag the other.
  `HudWriter.EmitSeatPanels` draws them, one `BeginClip` per seat viewport
  (a seat panel's own rect is LOCAL to that viewport, not the whole screen),
  as a fourth `OverlayChannel.Hud`
  pass after the world-scope under/base/over sequence — unbanded, since a
  panel confined to one seat has no base slot to take over
  (`WorldHudLayer.Replace` refuses there).
- **Values** resolve render-side EVERY FRAME at emission time
  (`HudWriter.EmitText`/`EmitGauge` → `IHudBindingResolver.TryResolve`,
  never cached across frames). Presentation float is fine here — nothing
  feeds sim state. `WorldHudBindingResolver` normalization constants:
  `TickCycleLength = 256`, `FpsNormalizerCeiling = 240f`,
  `PositionNormalizerHalfRange = 50f`; seat n (1-based) maps to body index
  n−1.
- Both `UnifiedOverlaySources.Hud` and `.HudBindings` must be wired or the
  HUD silently draws nothing (no throw) — the wiring is in
  `WorldBootComposition.AddWorldPresentation`.

## Verbs

Writes go through the document's one door, `world.row.set`/`world.row.remove`
over `hud.*` (`WorldRowCommandModule`, see [console.md](console.md)):
Simulation-routed, submitting a mutation and returning `CommandResult.None` —
NO synchronous echo; the outcome arrives a tick later through
`WorldServer.EchoTap` (toast, console mirror, stderr), and a rejection
increments `wire.errors`. A toast narrates what a player's own act caused:
`WorldToastPolicy` (`Puck.World`) withholds it from an echo whose
`WorldEditEcho.ActingPrincipal` is `Console` (stdin, an MCP or control
attachment, a sweep or schedule prelude, the session grants minted at a screen
session's admission) or `World`, and from an applied addon or scoped-replay
edit. The console row, stderr and the log carry those outcomes instead. The
read-backs `world.hud` and `world.hud.template`
live in `WorldHudCommandModule`, unbindable; `world.hud toast` reads the latest
toast the store holds (`#<seq> ok|error '<text>'`, or `none`), headless too.

- `world.row.set hud.panels <panel-json>` → `UpsertHudPanel` (whole row,
  elements included — the cross-row transaction boundary).
- `world.row.remove hud.panels <id>` → `RemoveHudPanel`.
- `world.row.set hud.defaults <json>` → `SetHudDefaults`.
- There is no per-element console verb: `world.row.*` takes whole panel rows, so
  a console edit is a panel upsert. The per-element mutations
  `WorldMutation.UpsertHudElement` and `RemoveHudElement` (a read-modify-write of
  one element in an already-declared panel) are carried by addon guests
  (`WorldAddonMutationDecoder`) and the wire.
- `world.hud [seat<n>]` — the `Immediate` read-back. No argument: `[world.hud:
  enabled <b> panels N/4]` plus per-panel and per-element lines. `seat<n>`
  (1..4): that LOCAL seat's PRIVATE player-scope panel instead (or a refusal
  naming why there is none — unjoined vs. no panel authored). Either form
  resolves bound values through the SAME resolver singleton the renderer
  uses, and a `Template` element's placeholders through the SAME resolver,
  so read-back and screen cannot disagree.
- `world.hud.template <text...>` — `Immediate`, no document row. Resolves an
  AD HOC template against the live document (see "Templating" above);
  refuses by name at the first bad placeholder rather than resolving any of
  it.
- `world.theme [contrast high|normal|toggle]` — `Immediate`, bindable,
  presentation only (`WorldThemeCommandModule`, a windowed presentation's).
  Echoes `[world.theme: source=document|engine-default contrast=high|normal]`:
  whether the world authors or imports a `theme` or draws the engine's neutral
  `WorldThemeSection.Default`. `contrast high` is the player's high-contrast
  preference (`WorldThemeResolve.HighContrast`), which raises every scrim to
  `WorldThemeCapacity.HighContrastScrimAlpha`; the document is untouched.

The theme's core tokens name purposes only; each overlay component's own look is
its style under `theme.styles` (`glow`, `keycap`, `bar`, `console`, `cursor`,
`wheel`, `toast`, `hud`), whose colors take a core role (`{ role: Accent }`) or
their own (`{ color: "#RRGGBB" }`), resolved by `WorldThemeResolve` into the
token slab's component slots (`OverlayColorRole.ConsoleEcho`, `KeycapBadge`,
`KeycapBadgeInk`). The standard skin is `worlds/standard/skin.puck`.

Inline JSON is reconstructed from the raw command text (the tokenizer would
destroy quotes) and parsed through `WorldJsonPayload.TryParse` against
`WorldJsonContext` — the exact wire shape of the document row; a parse
failure echoes inline (`IsError`) and submits nothing.

**The player-scope panel is edited elsewhere.** `world.row.set hud.*` writes only the
WORLD-scope section; an identity's private panel is edited through the owned
identity's own door — `identity.hud <panel-json> [player]`
(`IdentityCommandModule`) — not through this module and not through a
`WorldMutation`. UNGATED, like `identity.motion`: an owned world is edited by
its own door with no `Edit`/subject grant check (there is no `profile:<id>`
grant subject). It validates the candidate document through the SAME
`WorldDefinitionValidator.TryValidate` any owned world loads and saves
through, then fires INLINE over loopback (unlike the writes above): the
verb's own `CommandResult` carries the applied/refused outcome synchronously,
no `EchoTap` tick-later arrival, and a refusal leaves the document untouched.

## Verifying

`HudFrameElementValidationLawTests`/`HudBindingTargetFacetTests` (`tests/Puck.World.Schema.Tests`),
`HudFrameSourceGenerationLawTests` (`tests/Puck.World.Client.Tests`), `WorldHudRoutedSeatLawTests`
(`tests/Puck.World.Tests`) and the `hud-frame-slots` canary cover parts of the HUD; validate the
rest by RUNNING THE APP;
the ad hoc recipes below are the live method.
Ad hoc, world scope: `world.row.set hud.panels` a panel with a bound gauge,
`world.wait`, read `world.hud`, screenshot for the pixel assertion, then
exercise one refusal (a fifth panel, or an unknown binding) and confirm the
enum-named rejection. A `state.<row>` binding: `world.row.set state` a row (see
`references/mutations.md`'s State row), bind a text/gauge element to it,
`world.hud` shows the live value/fraction; `world.row.set state` the SAME row to
a new value and re-read `world.hud` — no restart needed, the resolver reads
the delivered definition every frame. Upsert (via `world.row.set hud.panels`) a binding
naming an undeclared row refuses (`hud.UnknownBinding`, naming the row). A
`state.<row>.<key>` binding: `world.row.set state` a KEYED row (declared
`capacity`, or `cells` carrying more than one entry), `world.state.cell.set`
one cell, bind a text/gauge element to `state.<row>.<key>`, `world.hud` shows
the cell's live value/fraction (the gauge reading the ROW's own `min`/`max`,
not a per-cell range); binding to a real row but an undeclared key refuses
the same way (`hud.UnknownBinding`, naming the row AND the key).
A `Template`: `world.row.set state` a `text`-kind row with a keyed cell (a
generator, `world.generate`, or a plain `world.row.set state` cells array all
land the same shape), upsert a panel carrying a `Text` element with
`"template":"...{state.row}...{state.row.key}..."`, `world.hud` echoes both
the authored template AND its live-resolved string; change the underlying row
and re-read `world.hud` — the resolved string moves with no restart, same as
a plain binding. `world.hud.template <text>` resolves the identical grammar ad
hoc, against the live document, with no document row at all. Refusal
controls: a template naming an unknown token or an undeclared row/cell
(`hud.UnknownTemplatePlaceholder` at the document; a named CommandResult error
at `world.hud.template`), a malformed brace/escape sequence
(`hud.MalformedTemplate`), and both `binding`+`template` on one element
(`hud.TemplateBindingConflict`) — each control confirmed against the SAME
element succeeding once the conflict is removed.
Ad hoc, seat scope: `identity.hud <panel-json> [player]` a panel with a
bound gauge, `world.wait`, read `world.hud seat<n>` (or `identity.show
[player]` for the one-line summary), screenshot for the pixel assertion
(confined to that seat's split — an adjacent seat's half must stay clean),
restart the process against the SAME `--state-dir` and re-read
`world.hud seat<n>` for the persistence round-trip. There is no grant to
narrow (the door is ungated, like `identity.motion`) — the refusal control
instead is a malformed or over-cap panel: an element count over
`WorldHudCapacity.MaxElementsPerSeatPanel`, more than
`WorldHudCapacity.MaxFrameSources` unique frame sources, or a
`WorldHudLayer.Replace` panel refuse by name (`hud.TooManyElements` /
`hud.TooManyFrameSources` / `hud.SeatPanelReplaceRefused`) with the document
left unchanged, confirmed against an at-cap panel that still succeeds.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall