@driftengine/core 3.61.0

package/dist/index.js

@@ -0,0 +1,320 @@
+/*! DriftEngine | Copyright 2026 Drift Technologies | Apache-2.0 | https://github.com/drftrun/driftengine */
+/** Public engine surface. Game code imports from '@driftengine/core' only. */
+export { startLoop } from './core/loop.js';
+export { StepBudget } from './core/stepBudget.js';
+export { hashToUnit, mulberry32, pickBySeed, savableMulberry32 } from './core/rng.js';
+export { exactAcos, exactCos, exactExp, exactSin } from './math/exact.js';
+export { TickTrace } from './core/tickTrace.js';
+export { BrowserStore, MemoryStore, defaultStore } from './core/storage.js';
+/* The same seam over a backend that answers later, with the queue, the retry and the status. */
+export { RemoteSaveStore, defaultSaveTimer } from './core/remoteSave.js';
+/*
+ * The rest of the capability seam, on `KeyValueStore`'s pattern and for its reason: the engine
+ * declares what it needs and a host supplies it, so nothing under `src/` ever names a shell.
+ *
+ * The browser implementations are exported beside the interfaces because a consumer in a browser
+ * is a consumer with a host — an ordinary one — and should not have to write `BrowserDisplay`
+ * itself. `PlatformServices` has no default implementation on purpose: there is nothing honest a
+ * browser can do with an achievement, and a consumer that never asks for one ships nothing.
+ */
+export { BrowserDisplay } from './host/display.js';
+/*
+ * What a phone has instead of a window: an orientation, a safe area and a screen that sleeps.
+ * Separate from `DisplayControl` because a desktop shell has no use for it and a phone has no use
+ * for most of that — and public, because a game's own settings menu is what calls it.
+ */
+export { BrowserScreenPresentation } from './host/screen.js';
+export { BrowserLifecycle } from './host/lifecycle.js';
+export { BrowserFileDialogs } from './host/files.js';
+export { PreferenceStore, loadPreferences, savePreferences } from './core/preferences.js';
+export { OnceSet } from './core/onceSet.js';
+export { MAX_TIME_CURVE_AMOUNT, curveOffsetSec, curveSpanSec, linearCurve, timeCurve, } from './core/timeCurve.js';
+export { CinematicPlayer } from './cinematic/player.js';
+export { defineCinematic, validateCinematic } from './cinematic/script.js';
+export { MessageQueue } from './core/messageQueue.js';
+export { celestialStateAt, createCelestialState, moonIllumination, } from './environment/celestialClock.js';
+export { TAU, DEG_TO_RAD, clamp, lerp, smoothstep, damp, dampTracking, angleDelta, dampAngle, wrapAngle, lerpAngle, } from './math/scalar.js';
+export { hslToRgb, mixColor, mixColorInto, scaleColor } from './math/color.js';
+export { Camera } from './render/camera.js';
+export { ThirdPersonCamera } from './render/thirdPersonCamera.js';
+export { CinematicCamera } from './render/cinematicCamera.js';
+/*
+ * The arm's own timings, so a rig with a short boom can say so.
+ *
+ * `Boom` itself is exported because it is the one implementation of "shorten against geometry, but
+ * gradually" and a consumer with its own rig should use it rather than write a third — which is the
+ * argument its own header makes about the two that already existed.
+ */
+export { Boom, DEFAULT_BOOM_TIMING } from './render/boom.js';
+export { billboardMatrix, billboardMatrixY } from './render/billboard.js';
+export { Mesh } from './render/mesh.js';
+export { UPLOAD_BYTES_PER_STEP } from './render/uploadStep.js';
+export { MAX_DEPTH_LAYER, Renderer, WebGL2Renderer } from './render/backend/webgl2/renderer.js';
+/*
+ * **The class as well as its two types, from 2026-09-03.** Every renderer holds one and
+ * exposes it through `registerPickable` and `pickAt`, so picking has been reachable since
+ * it shipped — but only against the set a renderer owns. A consumer that wants a second
+ * set, over gizmo handles or over anything a renderer never draws, had the types to
+ * describe one and no way to build it.
+ */
+export { PickableSet } from './render/pickable.js';
+/* How big a piece of geometry is, which everything that culls or picks a detail level starts from. */
+export { boundsOfBox, boundsOfPositions, createBounds } from './math/bounds.js';
+export { createFrustum, frustumFromViewProjection, sphereInFrustum } from './math/frustum.js';
+export { boundsVisible } from './render/visibility.js';
+export { apparentSize, lodForBounds } from './render/lod.js';
+/* A transform hierarchy. Additive: nothing in the renderer knows a node exists. */
+export { SceneNode } from './scene/node.js';
+export { MAX_JOINTS, MAX_MORPH_TARGETS, SKIN_PALETTE_TEXTURE_UNIT, morphTexelIndex, paletteTextureWidth, } from './render/skinPalette.js';
+export { createVisitResult, visitVisible } from './scene/visit.js';
+export { createPassAttachment } from './render/passTarget.js';
+export { OcclusionBuffer } from './render/occlusion.js';
+/*
+ * `Renderer` above stays exported and is not deprecated. `createRenderer` is the way to get
+ * whichever backend a browser will give you, and it is asynchronous because asking for a
+ * WebGPU adapter is; a consumer that does not want an await in its boot has no reason to
+ * take one.
+ */
+export { createRenderer } from './render/backend/createRenderer.js';
+/*
+ * The acceptance probe, exported because a consumer may want to ask the question itself — an
+ * editor deciding whether to offer a backend, a shell deciding what to tell the player — and
+ * because `demo/dev/backend-probe.html` drives it the way a consumer would rather than by
+ * reaching past the barrel into `src/render/`.
+ */
+/*
+ * The colour grade: a lookup table over display values, applied at the composite.
+ *
+ * `identityGradeLut` is exported because it is where a consumer building one by hand starts —
+ * take the identity, bend it, hand it back — and because it is what the placeholder is.
+ */
+export { GRADE_PLACEHOLDER_SIZE, MAX_GRADE_SIZE, identityGradeLut } from './render/colourGrade.js';
+export { probeDevice } from './render/backend/probe.js';
+/*
+ * Reading an image's texels back exactly, which no canvas and no `VideoFrame` will do.
+ *
+ * Here rather than in the package that needed it — `@driftengine/splats`, for `.sog` captures whose
+ * images are lookups rather than pictures — because it is raw WebGL and `AGENTS.md` allows that
+ * only under `render/`. The module's own header carries the measurement.
+ */
+export { createImageTexelDecoder } from './render/imageTexels.js';
+export { DEFAULT_RENDER_QUALITY, resolveRenderQuality } from './render/renderQuality.js';
+/**
+ * The global medium's own arithmetic, so a consumer can clamp its numbers the way the engine will.
+ *
+ * The pass itself is not exported and should not be: `setGlobalMedium` is the whole surface, and a
+ * consumer holding a `GlobalMediumPass` would own a target the renderer already owns. What is here
+ * is the type the setter takes and the two bounds a settings screen has to know about.
+ */
+export { DEFAULT_GLOBAL_MEDIUM, MAX_GLOBAL_MEDIUM_STEPS, WEAK_GPU_MEDIUM_STEPS, resolveGlobalMedium, } from './render/globalMedium.js';
+/*
+ * Equirectangular to cube faces, and the roughness a prefiltered level stands for.
+ *
+ * Exported because a consumer that wants to load an environment needs the first, and a consumer
+ * writing its own probe tooling needs the second. Neither pulls in a decoder: reading a `.hdr` is
+ * `@driftengine/assets`, and a game that never loads one imports none of it.
+ */
+export { equirectToCubeFaces } from './render/equirectToCube.js';
+export { IRRADIANCE_EDGE, PREFILTER_SAMPLE_COUNTS, ggxMaxLevelFor, irradianceLevelFor, octahedralEdgeFor, roughnessForLevel, } from './render/prefilterEnvMap.js';
+/**
+ * Where probes stand, and which of them light a point.
+ *
+ * Exported because placement is a consumer's decision and because a consumer sizing its own
+ * storage needs `MAX_ENV_PROBES` — every probe is one layer of one array texture, so the budget is
+ * memory rather than texture units. `nearestProbes` is the same trilinear blend the shader
+ * computes from three uniforms, which is what makes a consumer's bake ordering agree with what the
+ * lit pass will read.
+ */
+export { MAX_ENV_PROBES, ProbeGrid, createProbeBlend, nearestProbes } from './render/probeGrid.js';
+export { IES_ATLAS_WIDTH, packIesAtlas } from './render/iesProfile.js';
+export { MAX_AREA_LIGHTS, createAreaLightBuffer, selectAreaLights } from './render/areaLights.js';
+/**
+ * A rectangle's occlusion. Exported because a consumer sizing its own storage budget needs the
+ * layer arithmetic, and because `castingRange` is the one predicate that decides whether a
+ * declaration will actually cast — a consumer asserting that its fixtures do should ask the engine
+ * rather than re-implement the two conditions.
+ */
+export { areaShadowLayerCount, castingRange, firstAreaShadowLayer, } from './render/areaShadowSet.js';
+export { MAX_POINT_LIGHTS, SURFACE_TEXTURE_UNIT } from './render/lightBudget.js';
+export { SurfaceTexture } from './render/surfaceTexture.js';
+export { DEFAULT_GOVERNOR_LIMITS, ResolutionGovernor } from './render/resolutionGovernor.js';
+export { isWeakGpuFamily } from './render/gpuCapability.js';
+/**
+ * The same question `isWeakGpuFamily` answers, asked early enough to choose a profile with.
+ *
+ * `RendererApi.rendererName` and `CreatedRenderer.rendererName` are this answer after the fact,
+ * which is the right time for a boot log and too late for a decision.
+ */
+export { describeGpu } from './render/gpuCapability.js';
+export { DEFAULT_POINT_LIGHT_VIEW_RANGE, createPointLightBuffer, selectPointLights, } from './render/pointLightSelection.js';
+export { computeLightMatrix } from './render/lightMatrix.js';
+export { PlumeRenderer } from './render/plumeRenderer.js';
+export { createEnvironment } from './render/backend/webgl2/renderer.js';
+export { TrampleField, TRAMPLE_SLOTS } from './render/trample.js';
+/*
+ * Turns a silent uniform miss into a warning. See `shader.ts` — writing to a uniform the
+ * program does not have is a legal no-op, which is how an effect can quietly not exist.
+ */
+export { setUniformStrictMode } from './render/shader.js';
+/*
+ * And everything an app is waiting for as one weighted number, which is the part every consumer
+ * was writing for itself. Ids and numbers only: what to call a stage depends on who is reading it,
+ * so the words stay with whoever is showing them.
+ */
+export { LoadTracker } from './core/loadTracker.js';
+/*
+ * Closing the inside of a model that is only a surface, which a great many bought models are: a
+ * car with no cabin, a building with no rooms. Drawn alone they are correct, and any opening in
+ * them shows straight through the object and out the far side. Takes sizes and fractions; what a
+ * subject looks like is the caller's to state.
+ */
+export { buildShellFill, shellSkin, shellFillMatrix, DEFAULT_SHELL_PROFILE, } from './geometry/shellFill.js';
+/*
+ * The grade a forward pass applies when nothing follows it.
+ *
+ * **Exported because a package cannot obey the rule otherwise.** `AGENTS.md`, 2026-08-17: every
+ * forward pass grades itself when nothing follows it, `outputTransform.ts` is the single
+ * definition, and *do not copy the curve*. A pass contributed through `registerPass` is a forward
+ * pass like any other — a splat cloud writes straight to the canvas with no composite — and until
+ * this line the only way for it to comply was to copy, which is what the rule forbids.
+ */
+export { OUTPUT_TRANSFORM_GLSL } from './render/shaders/outputTransform.js';
+export { PLUME_VERT, FIRE_FRAG } from './render/shaders/fire.js';
+export { ARCANE_FRAG } from './render/shaders/arcane.js';
+export { SMOKE_FRAG } from './render/shaders/smoke.js';
+export { WaterRenderer } from './render/waterRenderer.js';
+export { MeshBuilder } from './geometry/meshBuilder.js';
+/* A tangent frame, which every map in the material track reads. */
+export { generateTangents } from './geometry/tangents.js';
+export { Spline, createSplineSample } from './geometry/spline.js';
+export { RIBBON_COLLIDER_GIVE_M, RIBBON_STEP_M } from './geometry/ribbon.js';
+export { buildRibbon } from './geometry/ribbon.js';
+export { buildFilmPatch } from './geometry/filmPatch.js';
+export { buildLightVolume } from './geometry/lightVolume.js';
+export { buildTextMesh, textMeshHeightM, textMeshWidthM } from './geometry/textMesh.js';
+export { CausticsRenderer } from './render/causticsRenderer.js';
+export { buildSheets } from './render/surfaceSheet.js';
+export { RibbonSurface, createSurfaceHit } from './physics/ribbonSurface.js';
+export { CompositeSurface } from './physics/compositeSurface.js';
+export { colliderSurface } from './physics/colliderSurface.js';
+/*
+ * **Which way depth runs, reachable.** A consumer choosing a near plane or an offset for a decal
+ * has to know: a conventional buffer resolves about `z² / (near · 2^bits)` and a reversed float one
+ * is near enough uniform, and the difference is millimetres of offset and a factor on the near
+ * plane. Reported per renderer as `reversedDepth`, which is what the context *granted*; these are
+ * what the engine asks for, and the two agree everywhere except a WebGL2 context without
+ * `EXT_clip_control`.
+ */
+export { DEPTH_CLEAR, DEPTH_COMPARE, DEPTH_COMPARE_EQUAL, DEPTH_FORMAT, DEPTH_OFFSET_SIGN, REVERSED_DEPTH, conventionalDepth, } from './render/depthConvention.js';
+export { BoxSurface } from './physics/boxSurface.js';
+export { heightSurface } from './physics/heightSurface.js';
+export { DebugLines } from './render/debugLines.js';
+/*
+ * The gizmo is a generator, the way `DebugLines` above it is: it answers what a ray is
+ * over and what a drag does, and fills line buffers the caller draws with `drawLines`.
+ * Nothing here touches a context.
+ */
+export { GIZMO_GROUP_ACTIVE, GIZMO_GROUP_COLORS, GIZMO_GROUP_COUNT, GIZMO_GROUP_NEUTRAL, GIZMO_GROUP_X, GIZMO_GROUP_Y, GIZMO_GROUP_Z, GIZMO_NONE, GIZMO_ROTATE_X, GIZMO_ROTATE_Y, GIZMO_ROTATE_Z, GIZMO_SCALE_UNIFORM, GIZMO_SCALE_X, GIZMO_SCALE_Y, GIZMO_SCALE_Z, GIZMO_TRANSLATE_X, GIZMO_TRANSLATE_XY, GIZMO_TRANSLATE_Y, GIZMO_TRANSLATE_YZ, GIZMO_TRANSLATE_Z, GIZMO_TRANSLATE_ZX, Gizmo, gizmoScaleFor, } from './render/gizmo.js';
+export { RainField } from './render/rainField.js';
+export { coveredAbove } from './physics/heightSurface.js';
+export { buildNavGraph, nearestNavNode } from './nav/navGraph.js';
+export { NavSearch } from './nav/navSearch.js';
+export { NavPath, createNavSteer } from './nav/navPath.js';
+export { BehaviorRunner, FAILURE, RUNNING, SUCCESS, buildBehaviorTree, } from './behavior/behaviorTree.js';
+export { projectDecal } from './geometry/decal.js';
+export { DecalProjector } from './render/decalProjector.js';
+export { ReflectiveSurface } from './render/screenSpaceReflection.js';
+/*
+ * `@driftengine/physics` is re-exported **wholesale**, and the star is the point.
+ *
+ * This was a hand-written list of names, and it drifted: by the time Track B finished, seventy-nine
+ * of the package's hundred and ten exports were missing from it, so a consumer reaching for the
+ * solver, the joints, the queries, the controller or the ragdolls through this barrel found
+ * nothing. Nothing failed, because a name that is not re-exported is simply a name nobody can
+ * import — the quietest kind of gap there is.
+ *
+ * A star cannot drift. **What it costs** is that this file no longer lists what collision offers,
+ * so a reader has to open the package; **what would make it wrong** is a name collision between the
+ * two, which is a compile error here rather than a silent shadow — and it is why the physics
+ * package renamed `Pose` to `ShapePose` and `collide` to `collideShapes` before this line existed,
+ * since `Pose` already means a skeleton's pose one package over.
+ *
+ * Core depends on this package rather than the other way round, because the cameras, the contact
+ * probe and the ribbon builder all need the sweep.
+ */
+export * from '@driftengine/physics';
+export { AXIS_X, AXIS_Y, AXIS_Z, ColliderSet, aabbFromCenter, bodyBounds, boxCollider, boxShape, capsuleShape, colliderFromShape, createBodyBounds, cylinderShape, createMassProperties, ejectFromSolid, faceCount, faceVertices, fingerprintBodies, fingerprintColliders, hullShape, moveAxis, segmentHit, shapeBounds, shapeMassProperties, sphereShape, } from '@driftengine/physics';
+export { InputSource } from './input/input.js';
+export { isTypingTarget } from './input/typingTarget.js';
+/* Positions rather than lettering, and the constant a consumer overrides to taste. */
+export { DEFAULT_DEADZONE } from './input/gamepadMapping.js';
+/* The platform's own ceiling on one haptic effect, so a settings screen can bound its slider. */
+export { MAX_RUMBLE_MS } from './input/rumble.js';
+export { ActionMap } from './input/actionMap.js';
+export { TouchControls } from './input/touchControls.js';
+export { pixelCursor } from './ui/pixelCursor.js';
+export { fullscreenWanted, requestFullscreenOnGesture } from './ui/fullscreen.js';
+/*
+ * The engine badge. `createRenderer` mounts it by default, so a game needs none of these names —
+ * they are here for the consumer that declines the automatic one and places its own, and because
+ * the two decisions behind it are worth reading before overriding either.
+ */
+export { SPLASH_FADE_MS, SPLASH_HARD_CAP_MS, SPLASH_MIN_MS, forcedSplash, mountSplash, splashDecision, splashWanted, } from './ui/splash.js';
+export { DEFAULT_CLIP_FPS, FrameRecorder, offerClip } from './ui/frameRecorder.js';
+// Not on `FrameRecorder`, so a screenshot does not cost a clip pipeline. See the module.
+export { stillFrame } from './ui/stillFrame.js';
+/*
+ * From `clipMime` rather than `frameRecorder`, and re-exporting them from there would
+ * undo the point: a consumer asking whether this browser can record at all must not
+ * pull the recorder in to find out. See `ui/clipMime.ts`.
+ */
+export { describeClipMime, supportedClipMimeType } from './ui/clipMime.js';
+export { EXPORT_FALLBACK_SCALE, ExportTarget, clipBitrate, exportAspect, exportSizeExact, isDuplicateFrame, CLIP_FPS_LADDER, clipFpsFor, exportSizeFor, } from './ui/exportTarget.js';
+export { FramePacer } from './ui/framePacer.js';
+export { bakeOverlay, drawPixelText, pixelTextCells, pixelTextSize } from './ui/frameOverlay.js';
+export { FpsMeter } from './dev/fpsMeter.js';
+export { CONTACT_LIMIT, createContactReports, describeContacts } from './dev/contactProbe.js';
+export { GPU_SLOTS, GpuTimer } from './render/gpuTimer.js';
+export { classifyRightGesture } from './input/rightGesture.js';
+export { createWindState, sampleWind } from './render/wind.js';
+export { advanceWindField, createWindField } from './render/windField.js';
+export { seaStateForAgitation, seaStateForWind } from './render/seaState.js';
+export { InstancedMesh, createInstanceData, writeInstance } from './render/instancedMesh.js';
+/*
+ * The instanced *mesh* surface, which is not the scatter above it: a scatter owns its own base
+ * geometry and carries a scale, a yaw and a wind response, because it describes a plant. These
+ * attach to a mesh the consumer already uploaded and carry a full transform, because a vehicle
+ * pitches and rolls and a yaw cannot say so.
+ */
+export { createMeshInstances, packInstances, INSTANCE_FLOATS, INSTANCE_STRIDE, } from './render/instances.js';
+export { ParticlePool } from './render/particlePool.js';
+export { ParticleBatch } from './render/particleBatch.js';
+export { PARTICLE_MOTE_FRAG, PARTICLE_SMOKE_FRAG, PARTICLE_SPARK_FRAG, PARTICLE_VERT, } from './render/shaders/particle.js';
+export { BoltPool } from './render/boltPool.js';
+export { BoltBatch } from './render/boltBatch.js';
+export { createLineSegments, setPolyline } from './render/linePoints.js';
+export { FlockRenderer } from './render/flockRenderer.js';
+/*
+ * Text is reached through the renderer, not constructed.
+ *
+ * `TextRenderer` is no longer exported: it holds a `WebGL2RenderingContext`, so a caller that
+ * built one was a caller pinned to one backend — which is exactly what kept `showroom` off
+ * WebGPU. `renderer.createText()` hands back an opaque `TextHandle` and the renderer draws it,
+ * the same shape scatter, plumes, particles, flocks and bolts already have. The measuring
+ * helpers were statics on the class and are free functions now, because neither needs a device.
+ */
+export { DEFAULT_TEXT_STYLE, textHeightPx, textWidthPx } from './render/textLayout.js';
+export { GLYPH_HEIGHT, GLYPH_SPACING, GLYPH_WIDTH, countCells, forEachCell, forEachRun, glyphRows, hasGlyph, measureText, } from './geometry/pixelFont.js';
+/*
+ * SDF text, reached the same way pixel text is: the verbs are on the renderer and the
+ * handle is opaque. What a consumer does need in its own hands is the metrics document,
+ * because the engine fetches nothing — `setSdfText` takes a parsed font and an atlas the
+ * consumer already owns, so a consumer that could not call `parseSdfFont` could not call
+ * `setSdfText` either. Phase one shipped the verbs and not this, which made the whole
+ * capability unreachable through the barrel; `demo/dev/sdf-text.ts` was reaching two
+ * directories deeper to work around it.
+ */
+export { parseSdfFont } from './render/sdfFont.js';
+export { DEFAULT_SDF_TEXT_STYLE, SdfTextLayout } from './render/sdfTextLayout.js';
+export { WindStreakRenderer } from './render/windStreakRenderer.js';
+export { buildTree } from './geometry/treeBuilder.js';

package/dist/input/actionMap.d.ts

@@ -0,0 +1,181 @@
+import type { KeyValueStore } from '../core/storage.ts';
+import type { InputSource } from './input.ts';
+import type { GamepadButton } from './gamepadMapping.ts';
+/**
+ * Actions a game asks about, and the bindings that satisfy them.
+ *
+ * **This is what makes the gamepad worth having.** Without it every site that reads input carries
+ * the device branch by hand — `isDown('Space') || pad?.down('faceDown')` — every new device widens
+ * it, and a player cannot change either half. A game asks whether *jump* happened and does not ask
+ * which device said so.
+ *
+ * **The action name is the consumer's own string.** A game's verbs are a game's business, and an
+ * engine-side enumeration of them would be exactly the "needs to know what something *is*" boundary
+ * error `AGENTS.md` forbids.
+ */
+/** One thing that can satisfy an action. */
+export type Binding = {
+    readonly device: 'keyboard';
+    readonly code: string;
+} | {
+    readonly device: 'gamepad';
+    readonly button: GamepadButton;
+};
+/** Jump, fire, pause: a state, bound to keys and buttons. */
+export interface DigitalAction {
+    readonly keys?: readonly string[];
+    readonly buttons?: readonly GamepadButton[];
+}
+/**
+ * Move, look: a direction rather than a state.
+ *
+ * **The reason this cannot be a button-only design.** A stick is not a key, and a game that treated
+ * one as four keys would throw away the magnitude the player is actually controlling.
+ *
+ * Key directions follow the stick's convention, which is the specification's: **up is negative**.
+ * The alternative was to flip one of them, and an engine that silently disagrees with the API it
+ * wraps is one a consumer cannot reason about.
+ */
+export interface AnalogAction {
+    readonly stick: 'left' | 'right';
+    /**
+     * One code or several, per direction.
+     *
+     * **Several, because `DigitalAction` above takes several and a player does not care which kind
+     * of action they are rebinding.** A game binding both `KeyW` and `ArrowUp` to forward — which is
+     * the ordinary thing to do — could express that for jump and not for movement, and the asymmetry
+     * was the whole of the gap: the alternative was two analog actions merged by hand at the call
+     * site, which is the engine handing back a job it already does.
+     */
+    readonly up?: string | readonly string[];
+    readonly down?: string | readonly string[];
+    readonly left?: string | readonly string[];
+    readonly right?: string | readonly string[];
+}
+export type ActionDefinition = DigitalAction | AnalogAction;
+export declare class ActionMap {
+    private readonly input;
+    private readonly definitions;
+    /** The current bindings per digital action, which rebinding and loading replace. */
+    private readonly bindings;
+    private readonly defaults;
+    private warnedAboutRecord;
+    constructor(input: InputSource, definitions: Readonly<Record<string, ActionDefinition>>);
+    /** Whether anything bound to this action is held. */
+    down(action: string): boolean;
+    /** Whether anything bound to it went down since the last poll. Readable by anything. */
+    pressed(action: string): boolean;
+    /**
+     * The same edge, claimed: true for exactly one caller.
+     *
+     * **Claims through the device rather than keeping its own set**, so a claim made here is also
+     * gone from `input.keyPressed` and from the pad's own `pressed`. Two claim registers over one
+     * physical press is how a press gets acted on twice.
+     */
+    consumePress(action: string): boolean;
+    /**
+     * Fill `out` with an analog action's direction.
+     *
+     * **The larger of stick and keys, never the sum.** A player holding a key while pushing the
+     * stick the same way is asking to go that way, once; adding the contributions would send them at
+     * twice the speed, which is the bug a naive merge ships with. What it costs: the two cannot be
+     * combined to exceed the rim, which is the intent. What would make it wrong: an action where two
+     * devices genuinely should add, and nothing has asked for one.
+     *
+     * **This is the reader for a direction.** If the two axes are two separate controls — throttle
+     * and steering, pitch and roll — read them one at a time with `axis`, which does not normalise
+     * them against each other. See its note for what the joint normalisation cost one consumer.
+     */
+    vector(action: string, out: {
+        x: number;
+        y: number;
+    }): void;
+    /**
+     * One axis of an analog action, on its own, **not normalised against the other**.
+     *
+     * **`vector` is right for a direction and wrong for two controls**, and the difference is not
+     * cosmetic. On foot the two axes are one direction, so a keyboard diagonal must be shortened to
+     * the rim or the player walks faster askew than straight ahead — that is what `vector` is for and
+     * it should stay the default. At a wheel the same two axes are throttle and steering, which are
+     * two separate controls that happen to share an action: normalising them together means a driver
+     * holding forward and left gets 0.707 of each and **can never reach full lock while accelerating**.
+     *
+     * A consumer lost two weeks to this. The report was "the car does not turn and it is slow", the
+     * whole vehicle model was rewritten looking for it, and it was not in the vehicle model — it was
+     * `Math.hypot` three call frames away, doing exactly what it was written to do. They shipped four
+     * duplicate digital actions bound to the same keys to get around it.
+     *
+     * The pad is unchanged either way: a stick already gives its two axes independently, so a caller
+     * driving with one reads the same numbers from both methods. The keyboard is where they part.
+     */
+    axis(action: string, axis: 'x' | 'y'): number;
+    /**
+     * Fill the two scratch vectors for an analog action, and say whether there was one.
+     *
+     * Shared so that `vector` and `axis` cannot disagree about which device is being read or how a
+     * key becomes a number — the device choice in particular is subtle enough that two copies of it
+     * would drift.
+     */
+    private sample;
+    /**
+     * Whether the pad these actions read has motors this browser can drive.
+     *
+     * **Pad 0, which is the pad every other member of this class already reads.** An action map is
+     * one player's controls, so "the pad the actions come from" is the device a rumble belongs on;
+     * a consumer running local multiplayer reaches `InputSource.pad(n).rumble` directly.
+     *
+     * Grey the control out when this is false. It is re-read rather than cached, because a pad
+     * unplugged and plugged back in is a different device behind the same slot.
+     */
+    get canRumble(): boolean;
+    /**
+     * Rumble that pad for `durationMs`, at two magnitudes in [0, 1]. Answers whether it was taken.
+     *
+     * `false` where there is no pad, no actuator, or nothing to play. Never throws.
+     */
+    rumble(durationMs: number, strong: number, weak: number): boolean;
+    /** Stop whatever that pad is playing. Answers whether the platform took it. */
+    stopRumble(): boolean;
+    /**
+     * Whether any of a direction's codes is held.
+     *
+     * Allocation-free for both shapes: a single code is compared without wrapping it in an array,
+     * and an array is walked by index. `vector` runs once a tick.
+     */
+    private anyDown;
+    /** What currently satisfies an action. */
+    bindingsFor(action: string): readonly Binding[];
+    /**
+     * Give an action a binding, and say which actions lost it.
+     *
+     * **Reports rather than decides.** A binding already serving another action is the interesting
+     * case in every rebinding screen there has ever been, and what to do about it is a product
+     * decision: steal it silently, warn, or refuse. A consumer that wants uniqueness enforced reads
+     * the return and rebinds back.
+     */
+    rebind(action: string, binding: Binding): readonly string[];
+    /** Put one action, or every action, back to what the game shipped with. */
+    resetToDefaults(action?: string): void;
+    /**
+     * Write the bindings a player has actually changed, and nothing else.
+     *
+     * **A diff rather than a snapshot, and this is the load-bearing decision.** A snapshot freezes
+     * the map at the version that saved it: a game that later adds an action, or changes a default
+     * nobody had rebound, finds every returning player still on the old set with no way to tell a
+     * deliberate choice from a stale record. A diff means an untouched action always follows the
+     * current default and only real choices survive an update.
+     *
+     * Through `KeyValueStore` because the engine calls no platform API a consumer might want to
+     * supply differently — the rule that put saves behind this seam.
+     */
+    save(store: KeyValueStore, key: string): void;
+    /**
+     * Apply a stored record over the defaults.
+     *
+     * **An unreadable record is the defaults, reported once.** A player whose stored bindings cannot
+     * be parsed should get a working game rather than a broken one, and should not have that decided
+     * silently — the same shape as every other refusal in this engine.
+     */
+    load(store: KeyValueStore, key: string): void;
+    private any;
+}