Skip to content

ByteTerrace/Puck / .claude/skills/input

Maps Puck input: channels, inputModes, sub-tick ingress, tap/hold/chords/sequences (inputPatterns), bindings and overlays, the always-active plane, devices, haptics. Grammar: puck-dsl.

references/bindings.md

View on GitHub
# Binding composition (`WorldBindingComposer.cs`)

Part of [`puck.world.definition.v1`](../../puck-world/references/documents.md). Field names and defaults are
generated (`puck schema`, or `src/Puck.World.Schema/Schemas/schema/bindingOverlays.schema.json`);
this file is the decision/derivation prose the schema cannot state.

The composer is N-ary (`Compose(params ReadOnlySpan<BindingProfileDocument?>)`,
base-first, null layers skipped, mismatched `Version` throws). The four layer
CLASSES are assembled by `src/Puck.World.Client/WorldSeatBindings.cs`: the
engine's build layer (`WorldEditorBindings.Layer`, see Context rows) → every
world `bindingOverlays` row in order (a row with a `when` gate that does not
hold is skipped) → the seat profile's `bindings` → live session rebinds
(freshest wins). A row's members are two
lists: `held` (a SET — down in any order) and `chord` (a SEQUENCE — pressed in
that order, tested with the held members removed from the press order); a
member is a modifier id, or a raw source id (`"held": ["mouse.button1",
"mouse.button2"]`) which becomes an implicit default-threshold modifier;
`modifiers` remains for thresholds and named multi-source groups. A page row
applies when its members are satisfied (deepest wins), a command row fires
when the down set is exactly its members; a row with neither list is the
group's resting page. A command row takes the press that completes it (and
that press's release) from the source's own page binding, so the most specific
match wins; `passThrough: true` leaves the press to its own binding too, so the
row adds its destination beside what each member does alone (the Moth's
`held [mouse.button1, mouse.button2]` row walks forward while each button keeps
its own drag, in either press order). A command row targeting a channel may author
`mode: Toggle`: each chord completion flips the input-side channel latch, and
breaking the physical chord leaves that latch untouched. This is the first-class
authoring model for auto-actions: auto-X toggles channel X without inventing a
bespoke command or simulation state. A page entry takes `mode: Toggle` the same way, and the
debug world authors its auto-actions so: the Moth's resting page toggles `run` on the left stick's press beside the
held `run` on Left Shift (West/J now dash), and the bar's View page (`pad-lt`, held on LT or Z, `controls.puck`) toggles `forward` on the left
stick's press (autorun) and `rise` on the right stick's press (autofly). The page's entry replaces the resting page's at
that source, and the latch outlives the page, so the trigger lets go and she keeps going. Toggle contributions are owned by the compiled command destination,
not by the button that flipped them; synthesized chord edges carry that stable
logical source through press, reassertion, and release. Parallel auto-actions
therefore coexist, while several bindings for the same destination operate one
latch. Merge rules: the row key is
(group, sorted `held`,
ordered `chord`); a later layer's row for the same key overrides
WHOLESALE when the meaning differs (a `Command`, or a page under a different
id) and ENTRY-BY-SOURCE when both name the same page: a row's `sources` list
(a control can activate a destination from several physical sources, e.g. a
gamepad button AND a keyboard key) replaces the earlier layer's entries AT
EACH of its listed sources independently — an entry surviving at all of its
sources stays combined, one narrowed to fewer sources by a later layer keeps
only the ones still its own — first-touch-per-layer so a hold/release pair in
one layer accumulates.
A `Relative` channel declares `relative { unit, sensitivity, maximumPerStep }`.
Bind a scalar source or component such as `mouse.motion.x`; each dispatch adds
a displacement, and the next admitted submission consumes the sum once.
The router preserves sample magnitude instead of quantizing it as a normalized
stick, and no step duration multiplies it. Toggle and held/sequence activators
are invalid for displacement. `player.signal` drives this same binding path
without a physical device, including from a test's scheduled `when` block.

Simulation eligibility is compiled by `WorldInputCatalog` from `inputModes`;
it does not follow the visible binding page. `WorldInputRuntime` selects each
admitted owner's tuple and publishes its mapping, epoch and source decisions.
`WorldSeatInput` reconciles those decisions before the host submits another
batch. A `seatModes` family used by a `SeatState` input selector changes through
the ordered `WorldCommand.SelectInputState` door (`player.mode`); bindings read
the accepted cell from the authority publication. Presentation-only families
continue through their existing context path.
If that authoritative family also targets a camera, the server preflights the
proposed cell and camera application together through ordinary engagement.
One successful route barrier publishes both; a refusal restores the old cell
and application. The camera route retains the existing local-seat admission
grant and the actor's Drive/Control checks.

`world.row.set inputModes <json>` replaces that policy through the ordinary
mutation transaction. It validates every finite tuple and the current owners'
selections before installation; an oversized bank or forbidden current tuple
leaves the definition, route and held origins intact. Voluntary engagement
composition and dissolution also validate the proposed application set before
changing routing. Administrative revocation still tears down its revoked route.

History operands accept the existing typed body-reference grammar as their
owner, for example ``inputEdge(`cell:inputOwner:$value`, tap, Press, 0)`` with the
body reference quoted using the DSL's backticks. The runtime resolves the
body's admitted owner without choosing an arbitrary co-driver. A crossing's
optional `facingState` names a body counter: its sign orients the axis at
admission, and the recorded crossing retains that meaning after a later turn.

Install input barriers after each kit firing's state writes and before another
action or world rule reads channels. A refused sweep restores the body's input
epoch, origins, mapping and queued-delay image with its motion; input undo is
captured lazily at an actual boundary, so unchanged steps allocate nothing.
Foreign state effects belong to that same firing: apply all validated members
before installing its barrier, and rewind the target's state and input with a
refused source sweep. Checking foreign members separately rejects a legal
two-selector transition whose intermediate tuple is forbidden.
Waiting for the next input submission lets a world rule read an old
held action against the new state and immediately undo the transition. The
debug autofly exit scenario exposed this ordering hazard. Route barriers also
replace the body's engaged intent, so the next routed recipient cannot read
the previous recipient's image.
Reset once per application-set replacement, before per-target notifications;
resetting for both removal and addition hides cancellation in an intermediate
epoch. Context-button probes resolve the actual body's mapping and carry their
activation into that boundary; an intervening epoch invalidates a pending probe.

The barrier also replaces queued input-delay samples with the accepted continuing
baseline. Clearing only the body's current bank leaves delayed old-epoch input
able to revive a cancelled action. Timed body segments and edge latches use the
actual per-action continuation decisions, including source rebind cancellations.
Profiles register stable source names and effective binding meaning as well as
handles; renumbering an unchanged source preserves its hold, while a rebind
requires neutral. Steady batches contain active sources and explicit neutral
observations only; omission contributes zero but does not acknowledge neutral.
An unchanged binding that was already accepted neutral and live stays armed
through a continuation-policy edit. Requiring neutral again blocked an untouched
key's first press after `world.row.set inputModes`. This does not apply to an
inactive destination, a changed binding, or a source with a held/rearming sibling.
Recompiling a producer on the same attachment carries real observed source
levels by binding identity, including a release captured just before reload.
It never carries pending old-epoch events. A fresh attachment requires neutral;
owner replacement advances its epoch and preserves monotonic event identities.

Engagement reach stores logical names, including in checkpoints. Machine pad
translation and addon folding resolve against the source or recipient's current
mapping; the default table cannot interpret a reused slot. Addon handshake
handles identify logical declarations, including dormant names, rather than
permanently assigning storage addresses.

`IntentSubmission.Input` is required. Transport and replay carry one semantic
batch; the separate `Intent` is only the camera projection of movement roles.
The authority derives its held overlay after admission. `WorldAcceptedInput`
is that derived body fold, also used by already-admitted body routes; it is
never an alternative transport ingress. Bodyless sessions use the same timed
admission. A switch-tick batch can repeat its retained baseline or acknowledge
neutral, but fresh events, levels and source activations start on the following
tick. Local snapshot producers publish that baseline during the barrier tick.
Scoped body playback re-observes recorded semantic events through a local
producer under the original actor, in the current interval. It queues owned
buffers, preserves event order and offsets, and cancels its episode when the
scope stops; an old transport epoch or assigned tick is never replayed as live
ingress.

Local snapshot producers use `WorldInputRuntime.TryPublishSnapshot`: each
actor/body/source has a generation-bearing session for its history, while the
original actor still supplies Drive and contribution consent. Do not authorize
an addon by substituting a seat or minting grants for its history session.
An occupied body's engagement selects from its occupant's applications even
before a physical input profile exists; a controller's private history session
owns no engagement route. An unoccupied target follows the authorizing actor.
Proposed route and document changes validate against that same routing subject;
Drive and contribution authorization still belongs to the original actor.
`IntentSubmission.InputOwner` names that separate session. Addon omissions
publish neutral through `CompleteSnapshots`; detach, disable and replacement
cancel through `CancelSnapshots`. A body reference resolves the primary admitted
owner, or a unique co-driver, through the per-body index; ambiguous co-drivers
are not a substitute for an authored owner reference.

Authored simulation producers enter the same path before motion under the
local structural `World` actor, only while the body's selected kit declares
that producer. Their sessions survive checkpoints and end when the source is
deselected. Physical clients receive no redundant copy of local producer
profiles. `PublishBorrowed` uses reusable event/contribution arrays for immediate
admission; never queue or retain that batch. Transport and replay producers use
the owning `Publish` result instead.

Scripted `body.press` and movement tapes keep their durations in the existing
body timer/tape stores and retain the command's actual actor alongside them.
The press command carries its semantic channel name through wire, checkpoint
and replay; the authority resolves it in the target's active mapping and refuses
an inactive name. A delayed command cannot press the new occupant of a reused
slot. Console, participant and adjacency producers read the target body's
active mapping, never the world's default tuple.
Each step admits that actor's current script image before the body consumes it;
the accepted image controls motion and actions, and expiry publishes a normal
release. Revocation and authority crossings cancel. Actor arrays and queued
segment actors use the authority checkpoint leaf, including local `World`
provenance for compiled internal callers; none can claim `World` on the wire.
A default tap lasts one host step. Adding a local observation session does not
reset the body's already queued script durations.

Size history for the authored rate and sample density, including both ends of
the retention window and any burst. At 240 Hz, two seconds of continuously
changing steering axes can exceed the default 256 records. An overflow cancels
the episode and requires rearming; it must not silently overwrite unexpired
history. The curve-follow fixture sizes this allowance from its rate and axis
count, and the dense-flock law checks the synchronous path's allocation.

For a scheduled continuity demonstration, establish the physical hold before
submitting the mode-changing command. Default `player.signal` capture can land
one interval after a body command submitted on the same schedule row; that
tests a new press after entry rather than a held contribution crossing entry.
Use explicit `at:<seconds>` offsets for sub-tick ordering, as the input-history
and clock scenarios do. `keyboard.text` supplies committed text (including a
paste) as ordered Unicode scalar events, without parsing it as console input.

The merged document compiles once per change through
`BindingProfile.Compile` in `Puck.Commands` — deliberately shared, never
copied. `WorldSeatBindings` compares the filtered composed document plus the
ordered channel definitions before compiling: a route that presents a new document
instance with identical effective content is a true no-op, preserving held
commands, chord/page state, and release latches. Live surface: `player.bind`,
`player.bindings`.

A page may name `inherits`, the profile-unique id of another page in the same
group. Compilation flattens the inherited page first, then replaces its entries
at every source or activator identity the child declares; untouched bindings
remain active with no runtime fallback lookup. Missing pages, cross-group
inheritance, empty ids, and cycles refuse by page name. A radial's hold page
(an `actionWheel` page, say) that inherits `base` keeps left-stick and keyboard
movement active while its right-stick selector override is open.

A chord row's, context row's, and wheel row's `group` may be a literal or a
`state.<row>[.<key>]` reference to a Text cell. All references to one cell
resolve together before the profile is composed, so changing that single cell
renames the relationship consistently instead of requiring a document-wide
search/replace. The
[Schema README](../../../../src/Puck.World.Schema/README.md) shows the shape
(`"group": "state.bindingGroups.defaultActionGroup"`); no checked-in world
authors it today.

Each `WorldBindingOverlay` may also carry `bindingBar`: the presentation policy
for the on-screen mapping bar. Absence anywhere in the resolved chain (no
identity row, no world row) resolves to `WorldBindingBarAuthoring.Absent` — NO
bar draws. The live example is `worlds/standard/controls.puck`, which the debug world
refines and the garden imports: it refines the Moth basis's `bare` row with a `bindingBar`
(the standard controller cluster: the d-pad diamond with LB and the left stick's press, the face diamond with RB and the
right stick's press, an `iconRow` keyed by entry id, and one bank per page of the trigger-held pages with
`modelCell` reading `single`, so the bar swaps pages in place; `modifiers`, `declaredModifiersOnly` and `pageLabel` draw
the modifier row on the layout anchor (only the modifiers the document declares, the two triggers, not the implicit one
the compiler mints for each raw source a chord names: a key, a shoulder, a mouse button) and the page's name under it, while each bank's own `anchor` stands the plates above them), authors the
`icons` table, and appends a `play-wheel` row and the `pad-pages` row of the chord pages. The first world row, when one
is authored, supplies the world
floor; the selected identity's own first row may replace it for that seat,
matching the existing first-row binding-layer consumer in `WorldIdentity`.
`world.binding-bar [on|off|auto] [player]` reads the resolved policy and controls
its live visibility override.

`declaredModifiersOnly` (default `false`) narrows what `modifiers` draws. The compiler mints a single-source modifier
for every raw source a chord or held row names, so a bar over a profile with a Tab-or-LB wheel, a both-mouse-buttons
walk and a Q chord lists them all beside the page-holding triggers (`BindingModifierView.Declared` tells them apart);
with the flag on, the row and the chord hints it places keep to the declared ones, and a chord of minted modifiers
shows only where `slotSet` places each member.

**Openers.** A plate whose control the active page leaves unbound but whose hold opens a deeper page of the group (a
chord row whose members are this page's plus that control) reads as that page's opener: bright, wearing the icon the
bar's `iconRow` names for the OPENED PAGE'S ID (`state.barIcons."wheel-pad"`; `BindingPageView.Openers`). The Move
page's LB opens the play wheel this way, as `WH`. `WorldPresentationManifest`
registers each page id as an icon key.

`bindingBar.slotSet` (required, non-empty) names the physical controls the bar
shows by INPUT SOURCE ID (`gamepad.buttonSouth`, `gamepad.leftTrigger`,
`mouse.button1`, …) — the same vocabulary a binding entry's `sources` speak,
validated against `Puck.Input.InputSourceVocabulary` through
`InputSourceVocabularyHook` (the `Puck.Input`-vocabulary seam Schema reaches the
same way it reaches command/channel vocabulary), refusing an unknown id by it, a
duplicate by index, and the whole list past `WorldBindingBarCapacity.MaxSlots`
(32, a declared document ceiling).
A control appears on a bank only where the live layout places it; the engine
derives no position from the source id or the authored order.

`bindingBar.banks` (required, 1..`WorldBindingBarCapacity.MaxBanks` = 5, unique
ids) is a list of `WorldBindingBarBank(id, pageId, alpha, activeAlpha?)` rows:
each bank renders against its OWN named page (a `BindingPageDefinition.Id` —
validated to exist somewhere in the COMPOSED binding profile, checked after
`BindingProfile.Compile` succeeds, since only the whole overlay stack's result
can answer that), at its authored `alpha`, or `activeAlpha` (default 1.0) when
that bank's page is the seat's CURRENTLY active one. List order is draw order.

Where a bank sits is the layout's to say. `bindingBar.layouts` maps a name to a
`WorldBindingBarLayout`: `tables` (named plate tables, each row a
`WorldBindingBarSlotPlacement(source, x, y, badge?)` in button pitches from the
anchor, x right and y up), `banks` (per bank id, a
`WorldBindingBarBankPlacement` of ordered `pieces`, each a table moved by `at`
with an optional `badge` override, and an optional `anchor`), the bar's own
`anchor` (`WorldBindingBarAnchor(edge, inset)`), and optional size-tuning
overrides (`buttonSize` and the `*Ratio`/`*MinPx` fields). Banks sharing an
edge and inset share one frame and are laid out together on one pitch grid; a
bank with no row in the live layout is not drawn, and a source two pieces place
takes the later one. `layout` names the default layout and `layoutCell` (a text
state cell) the live one, so a chord, a wheel sector, or the console switches
the bar's whole shape by writing that cell; a name matching no layout falls
back to `layout`, then to `WorldBindingBarLayout.Default`, which places nothing.
`modelCell` (a text state cell) reading `single` draws one bar — the active
page's bank, in the first authored bank's place — and any other value draws
every placed bank. The resolved placement compiles into
`Puck.Commands.CompiledBindingBarLayout`, which `BindingBarWriter` draws.

A player's own `BindingProfileDocument.BindingBar` (stored in the identity
document's `bindingOverlays` section; `Puck.Commands.BindingBarPreferences`:
`hideUnbound`/`scale`/`contrastBoost`/`uiScale`/`layout`/`model`, all nullable, LOOK only —
never a binding) overrides the world policy and adjusts the resolved theme.
Binding-layer composition merges these fields individually, so a session scale
change retains an identity layout or contrast preference. `player.binding-bar
layout|model|scale <value> [seat]` writes the session layer; `auto` clears that
field, and `identity.bindings.save` persists it with other rebindings. Layout
and model preferences override `layoutCell` and `modelCell` for that seat only.
The [standard package](../../../../worlds/standard/README.md) authors the
concrete layouts, compact multiplier and console commands used by its Bar ring.
`world.binding-bar` reports the resolved layout name, stacked model and scale.

`bindingBar.text` (default `true`) is the bar's ATLAS-TEXT switch: `false` drops
every text run the bar writes — every badge whose authored icon row carries a
`label` (`LB`/`RB`, `LT`/`RT`, `LS`/`RS`, the menu trio, the exotics), the
active page's name under the modifier
indicators, and a chord hint's label badges and label — leaving a purely pictographic
bar: the plates, the PROCEDURAL badge glyphs (the d-pad arrows and the
face-position diamonds), the bound actions' icons, and the indicators all still
draw. The policy resolves ONCE
per seat in `WorldOverlayFeed.Tick` and shapes what it publishes (a suppressed
badge is `OverlayResolvedGlyph.None`, a suppressed label the empty string, suppressed
hints an empty span — each already a case `BindingBarWriter` draws nothing for),
so the writer carries no text policy of its own.

Authority input publications reconcile in `WorldClientSeats.ClearAnalog`, the
shared end-of-step seat lifecycle used by headless and presented hosts. Do not
put epoch, source rearming, or mapping synchronization (`WorldSeatBindings.SyncRoute`)
only in a path a presented host runs: a headless host must receive every boundary too,
including boundaries which do not change its authority route.

Each owner's snapshot also carries its `WorldInputAnswer` (`WorldInputRuntime.Answers`,
filtered by `WorldOwnedRecords.ForOwner` like the publication; a body-disclosure
observer is handed none, `WorldOutputHub.DeliverSnapshot`): the epoch, the highest event
sequence of the last batch of the owner's current epoch, for its own route, that the
authority took or refused, and the tick it answered in. The submission door writes it
through `WorldInputRuntime.Answer` before any check (a drive gate, a Drive denial, a
reach, the admission) can refuse the batch. It is delivery only, never hashed or
checkpointed. A client reads its publication and answer under its own principal, else
under whichever owner the route's authority publishes the routed body's input as
(`WorldSessionMirror.TryInputOf`: a forwarded authority stamps a traveler as its peer).
`WorldSeatInput` records the last edge it sent on each channel and clears it once the
edge's answer is presented, and `WorldSeatInput.TryLead` answers whether an edge is
outstanding from those facts ([rig](../../sdf-authoring/references/rig.md#drivers)).

Every rendered slot's `Pressed` state reflects the physical source in
`InputRouter.IsSourcePressed`, independently of a destination's toggle latch.
`WorldSeatInput.ActionStatus` supplies current-mode eligibility, awaiting-neutral,
toggle and retained-level state; the bar dims disabled or rearming actions and
keeps their state separate from physical depression. Only the active bank shows
physical depression; every bank may show an action's latch. Badge content comes
from `icons.badges`, keyed by the same input
source id: `WorldIconTable.ResolveBadge` is the one door a slot, a modifier
indicator, and a chord hint all go through, checking the row's per-family
override (`Puck.Input.Devices.GamepadType` member name) before its default icon.
A source with no badge row simply draws no badge, so badging a control the
gamepad vocabulary never named (`mouse.button1`) is an authoring act, not a code
change.

`body.rig` reads input without presentation; `body.channels` adds its existing
contribution fold. Both name the body's selected tuple and epoch, action shapes,
values, inactive actions, source rearming and held origins. Prefixed help for
`body.press`, `body.rig` and `body.channels` appends that current input vocabulary.
`world.affordances` returns an object with `commands`, `channels` (including
`active` and `value`), and `input`, the last two for the body the asking seat holds
in the authority it is routed to. Every input read-back (`body.rig`, `body.channels`,
`player.bindings`, `world.affordances` and that help) asks the seat's routed
authority for its body through `WorldInputReadBack` as the acting principal, so it
shows the seat's current mode after a portal crossing and only what the caller may
observe; a refused query reads back as a refusal. Compiled binding
handles have no console/help/vocabulary surface. Replay names accepted input
from each re-driven tick's definition, including barriers and cancelled holds;
a segment's raw bank is never labelled using a fixed or later mapping.

The input genre demonstrations are ordinary sweeps; their five plans and exact
invocations are in [the input-channel decision](../../../../docs/decisions/input-channels.md#genre-check).
Run each with a fresh boot. C7 observed authored state-writing rules refused
after `world.load`, while a fresh boot runs them. Loss of the seeded Edit grant
is an unconfirmed inference; the boot/reload finding is recorded in the open items.

The bar's `visible` predicate is the overlay visibility contract every HUD
element shares ([HUD](../../puck-world/references/hud.md#overlay-visibility)).

**Context rows.** `puck.bindings.v1` carries an optional `contexts` section:
`{family, state, group}` rows (`BindingContextDefinition`), merged across
layers on `(family, state)` — a later layer overrides a re-declared key IN
PLACE, new keys append, so precedence order is authored primarily by the
layer that ships the vocabulary. The seat's ACTIVE group derives as: first
matching context row's group (document order) → the seat's requested group
(`PagedInputBindings.SetActiveGroup`, the mode pointer) → the profile default.
A family is one of three kinds: a BUILT-IN engine family
(`WorldContextFamilies` — the output of one per-seat single-valued state
machine): `roster` publishes `unjoined|claimed|pending|active`, `engagement`
publishes `engaged|none` (a loopback read of whether the grant table's
control-application set names anything beyond the seat's own body, synced once
at post-build wiring and every tick post-step via
`WorldSeatContextSync.Publish`), `layout` publishes the window composer's
active layout selection (an authored `views.layouts` name, or `builtin`) — an
OPEN-states family (`WorldContextFamilies.IsOpenStates`): any state token is
admitted, and a token matching no authored layout simply never matches; and
`editor` publishes `play|build`, the one built-in family a seat flips itself
(`player.build [seat]`, or `player.mode editor build|play`; reset to `play` when
the seat is vacated). The engine composes a build layer beneath every world
that binds anything and authors an `editor` section (`WorldEditorBindings.Layer`,
prepended in `WorldSeatBindings.BaseLayers`): the section's authored `toggle`
entry merged into the resting page of every group the world binds. The build
page itself (grid, snap, place, nudge, turn, history) and its
`{editor, build, build}` context row are the standard's `editor` binding overlay
(`worlds/standard/editor.puck`), and a building seat whose bar places no bank
for that page shows the section's `bar`. A world that binds a toggle source
keeps its own meaning, since world layers compose over the engine's. The World
guide's *Build mode* section lists the page. Besides the built-in
families, a family may be a
`state:<row>` family (`WorldStateBindingContext`) reading the routed world's
scalar/keyed state; or an AUTHORED `seatModes` family (`WorldSeatModeFamily`,
document top-level `seatModes`) — a world-declared name plus its admitted
states, flipped by `player.mode <family> <state> [seat]` and validated
strictly (unknown states refused, the name may not collide with a built-in
family or the `state:` prefix). A state whose `target` is `"camera"` composes the camera control application:
the seat possesses its authored `camera-seat-<slot>` inhabited placement
through the ordinary Engage door, its own body intent diverting to
`body.control`'s idle contract, and its view resolving through
`views.cameraRig` (see views.md). `player.camera [seat]` is the bindable
no-token toggle onto the same state. Compile refuses a malformed/duplicate row or
an undeclared group; the vocabulary gate refuses an unadmitted family/state —
all by row. `player.bindings` leads with the derivation echo:
`group=<active> (<step>)`, per-family `<family>=<state>→<group>
(wins)|(shadowed)|(no row)`, and `requested=<group>` marked `(shadowed)` when
a row overrides it — a matching row that lost to an earlier row is reported,
never silent. The input-history and continuity scenarios under `worlds/debug`
exercise authoritative `seatModes`; a presentation context can still select a
binding group independently. Check `src/Puck.World.Schema/Schemas/schema/seatModes.schema.json` for the current
field names before authoring one. Every group needs a resting (empty-chord)
page — a blank-slate group authors one with an empty `entries` list.

**Wheel rows.** `puck.bindings.v1` also carries an optional `wheels` section
(`BindingWheelDefinition`: `{id, group, holdPages, rings, style}`). `id` is
profile-unique and is the merge/runtime-continuity identity: several radials
may share one binding GROUP, and a later layer replaces a re-declared radial
WHOLESALE by id. `holdPages` is a non-empty list of distinct chord-row page
ids from that same group. Any one of those pages presents the radial, so an
author may bind several physical openers to one wheel (Tab and LT, for
example), while other hold pages in the group present different wheels (LT
for wheel A and RT for wheel B). Releasing one opener defers commit while
another hold page still presents the same radial.

Rings are ordinary `BindingPageDefinition`s worn as concentric shells
(`BindingProfile.Compile` bounds: 1–4 rings per wheel, 2–8 sectors per ring,
ring page ids sharing the document-wide page-id namespace). A SECTOR row
narrows the page-entry shape to a command destination plus label/icon and an
optional constant `value`/`activateOn`; `source`, `activator`, `channel`,
`scale`, and a non-default `mode` refuse by name. The compiler mints an opaque
`BindingActivation` for each sector, and commit returns it through
`InputRouter.Activate` in the originating seat's deterministic lane. The
vocabulary gate therefore requires every sector command to exist, be
Bindable, and accept the authored value kind — sectors are not console
lines.

`style` is optional authoring policy. `pointerSelection` is `Angle` (direction
alone beyond the dead zone), `HitTarget` (the pointer must remain in the
authored annulus; reusable by a future touch adapter), or `Disabled`;
`placement` is `Pointer` (opening pointer position, with viewport-center
fallback) or `ViewportCenter`. Authors also control dead-zone/ring/grace
fractions, rotation, clockwise ordering, and the initial ring. `axisDeadZone`
is the normalized explicit-ring Axis2D neutral threshold, independent of the
visual/spatial `deadZoneFraction`; excursion-controlled wheels instead use
`excursion.deadZone`. `selectionGraceSeconds` is the neutral dwell before an
empty commit becomes a cancel: a quick throw remains selected during that
window, while holding the selector centered beyond it clears the command. Each
return to neutral completes one selector excursion, so another flick in the
same direction begins a fresh excursion even when its peak is weaker than the
last. Direction remains live throughout an active excursion, including a
constant-radius rotation whose magnitude never sets another peak. On return to
neutral, the wheel retains the last direction at or above `switchFraction`, or
the excursion's peak when a short throw never reached it. `switchFraction` is
also the magnitude an opposite-side excursion must reach and the magnitude a
different sector must reach while grace holds the prior sector; raise it to
reject stronger spring rebound, or lower it to admit lighter direction changes.

`ringSelection` is `Explicit` (the default: `player.wheel.ring` bindings and
authored `player.wheel.scroll` Axis2D bindings step the active ring) or `Excursion` (neutral-relative
selector magnitude chooses it). Excursion requires an `excursion` object:
`deadZone` is the inclusive magnitude that selects no ring; `thresholds`
contains exactly N-1 ascending boundaries for N rings; `hysteresis` supplies
the retained band on both sides of each boundary; and
`spatialTravelFraction` says what fraction of the seat viewport's smaller
extent equals pointer/touch magnitude 1. Axis2D magnitude is already
normalized. The final ring has no outer bound. Each spatial gesture captures
the first available device position as neutral—even when that position arrives
after the opening frame—and never moves that origin until close. Placement is
therefore visual only. With `HitTarget + Excursion`, ring choice uses distance
from captured device neutral while sector eligibility/direction remains
relative to the displayed hub; this deliberately permits direct mouse/touch
targeting and gamepad excursion on the same authored radial.

The spatial policy reads the live cursor position independently of the routed
`mouse.motion` binding: absolute-only pointer reports still aim the wheel.
This keeps the wheel usable in annotation mode, whose input filter consumes
relative motion to prevent camera drags while drawing.
Only a position change takes selection from a controller; a parked cursor
does not. Angle selection measures from the opening pointer position, while
`HitTarget` tests the drawn annulus. Relative selection bindings retain a
virtual pointer for devices without an absolute position; when a position is
available, raw motion cannot also select or jump at the window edge. Use
`world.view.pointer x y` to exercise the spatial selector through MCP.
The newest mouse or axis selection wins; axis switch hysteresis never locks
out a later mouse selection. Losing the pointer ends its hover.

Axis selection, ring navigation, commit, and cancel sources are ordinary entries
on each hold page. `worlds/standard/controls.puck`'s `play-primary` is the live
example: two hold pages (Tab, LB) that inherit the resting page and step the ring
with `player.wheel.ring` (Up and Down, a constant Axis1D value of +1 outward and -1
inward, `activateOn: Started`). The hold pages also bind `mouse.wheel` to the
Axis2D `player.wheel.scroll`: vertical notches accumulate fractionally within one
gesture and step its ring immediately. The pointer projection drains its copy
without taking any action, so a physical scroll and `player.signal mouse.wheel`
have one routing path. A closed wheel discards an already routed ring scroll.
The hold page's `mouse.wheel` entry replaces the resting page's
`player.camera.boom` on that source (inheritance replaces source by source), so
zoom stops while the wheel is open because of that authored data; the boom verb
has no wheel check of its own. The generic router watches immutable active
page identities during its ordered fold: a page transition discards relative
samples already collected in that page interval, including an open and close
within one snapshot, and consumes a relative sample that caused the transition.
Later samples resume on the new page. Rings read their labels and icons through
`state.wheelLabels`/`state.wheelIcons`. The standard has Act, View and Bar;
`worlds/debug/controls.puck` adds Places through its refinement. Up to four
rings fit the overlay reservation, whose writer and schema share one bound.

**Trigger-held pages** (the live example is `controls.puck`'s `pad-pages` row): declare
the trigger modifiers (`id: "lt"`, `sources ["gamepad.leftTrigger", "keyboard.z"]`,
with press and release thresholds for hysteresis) and one chord row per page in the same group.
A chord is a press-order prefix of the held modifiers and the deepest matching row wins, so
`["lt"]`, `["rt"]`, `["lt", "rt"]` and `["rt", "lt"]` are four pages (the two squeezes differ
by order) beside the resting page; a page that `inherits` the resting page keeps the sticks
and movement keys while it rebinds the rest. A binding document validates its chords against
its own `modifiers`, so every overlay that adds entries to a trigger page declares the
modifiers again (`let padModifiers` in `pad-kit.puck`); entries from several overlays on the
same page id merge by source. A binding to a verb only a rendered World registers
(`world.quality`) is judged by the verb catalog in every shape: `puck compile --validate` checks every
binding's command (named, Bindable, accepting `text`, the value kind) against it, a typo is refused there, and a headless
boot admits the document and drops that entry from the seat's composition with one narrated line, as the seat recompose
already does for any command a leaner shape lacks. The bar's Debug and Tour pages bind the render levers
(`world.quality next`, `world.rates toggle`), `world.screenshot` and `world.history on` directly. Authority diagnostics
(`world.inspect`, `world.debug-view`) are operator commands and have no standard seat binding. An
imported module's state rows are private, so a binding in another module that reads one
(`worlds/debug/controls.puck`'s wheel names `wheelLabels`) needs the owner's `exports { bindings [...] }`.
`WorldWheelFeed` owns logical gesture state and optional presentation;
its drawn labels, icons and hub label come from `WorldWheelRings`
(`Puck.World.Client`), which reads the label and icon rows through the seat's
routed mirror and rebuilds only when one of those cells changes. `world.view.wheel` reports the live wheel, hover, effective selector dead
zone, and neutral-grace duration. Headless hosts resolve the same directional
selection, fractional ring scroll and sector commits without inventing a pixel
viewport; the hub remains unanchored. Their logical feed advances after each
headless fixed step, and read-back never seeds or changes the gesture.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall