@maccesar/titools 5.2.0 → 5.2.2

package/skills/ti-game/references/api.md

@@ -1,8 +1,8 @@
 # ti.game API reference
 
-Complete JS surface of `ti.game` as of upstream `main` at `3bea2f4`, 2026-09-02, verified against every Android proxy/engine and its iOS twin. Defaults come from native fields, not prose. The manifests read **`0.6.0`**, which is unreleased: the published **`0.5.0`** release carries the same engine code, because its tag sits on the commit right before the version bump. Read the number as a floor, never as a feature list — a locally built artifact stamped `0.5.0` may predate that release by weeks. Older `0.3.0`/`0.4.0` artifacts also vary by build date; feature-detect when the artifact is unknown. Read a property before writing it, because Kroll can retain an unknown write on the proxy. Methods are safer probes (`typeof Game.createTileLayer === 'function'`), as are normalized properties (`solidMode` reads an unknown name back as `'block'` only when the engine implements it).
+Portable JS surface reviewed against `m1ga/ti.game` main at `88e181cb85526d8146d0be6e09b2b90c2551baad` and the documentation refresh in `macCesar/ti.game@2bf5f828a3bb8028eed20d6ba27b97dd3aa9a753`, 2026-10-23. Android uses OpenGL ES 2.0; Apple uses Metal on iPhone, iPad and Mac Catalyst. Both manifests declare `1.0.0` and minimum Titanium SDK `13.4.0`; this source review does not establish the version or behavior of an installed artifact. Check the artifact's source commit, especially nightly builds sharing a version. Feature-detect when the artifact is unknown: methods are safer probes than unknown property writes retained on a Kroll proxy.
 
-Properties are live unless their table says creation-time or read-only. Every writable property can be passed to its `create*` factory. `TileLayer` has four cross-platform creation-time inputs (`legend`, `firstGid`, `cols`, `rows`) because Android does not expose the live setters that iOS has. All durations crossing the JS boundary are **milliseconds**.
+Properties are live unless their table says creation-time or read-only. Every writable property can be passed to its `create*` factory. Exceptions for portable code: `animations` must be supplied at Sprite creation, and TileLayer `legend`, `firstGid`, `cols`, `rows` must be supplied at TileLayer creation. All durations crossing the JS boundary are **milliseconds**. For keyboard, mouse, action maps and focus, read [input.md](input.md).
 
 <!-- TOC-START -->
 ## Contents
@@ -100,10 +100,13 @@ A normal Titanium view — add it to a window or any container, size it with the
 | `remove(object)` | method | — | Remove one object from the scene — **and, recursively, every sprite attached to it** (see [Attachment](#attachment)) |
 | `removeAllSprites()` | method | — | Clears Sprite/Text objects and their attachments. It does **not** remove emitters, ropes, or tile layers; track and remove those separately |
 | `pause()` / `resume()` | method | — | Render loop control. The activity/app lifecycle already pauses and resumes automatically |
-| `backgroundColor` | string | — | GL clear color |
+| `backgroundColor` | string | — | Native scene clear color |
 | `maxFps` | int | `0` | Frame cap. `60` stops 120 Hz ProMotion displays from doubling render work; `0` = display refresh rate |
-| `timeScale` | float | `1` | Multiplies the scene dt for physics, sheet animations, tweens, particles and camera. `0.5` = slow motion; at `0` rendering/touch continue. Rope's previous-displacement integration still runs at zero dt in the pinned source, so complete rope freeze is not guaranteed; see [physics.md](physics.md#verlet-ropes-and-tethers) |
+| `timeScale` | float | `1` | Multiplies the scene dt for physics, sheet animations, tweens, particles and camera. `0.5` = slow motion; at `0` rendering/touch continue while rope nodes, their history, constraints and tether response freeze. New rope geometry can still initialize for drawing; see [physics.md](physics.md#verlet-ropes-and-tethers) |
 | `surfaceWidth` / `surfaceHeight` | int | — | Read-only surface size in pixels |
+| `inputMap` | dict | `{}` | Contexts → named actions → binding arrays. Invalid maps throw without replacing the current map or active state; see [input.md](input.md) |
+| `inputContext` | string / null | `'gameplay'` | Active action context; `null` disables actions. A changed context releases active actions and requires a fresh press |
+| `focusInput()` | method | — | Request canvas keyboard focus on the UI thread; does not open the software keyboard or capture keys globally |
 | `cameraX` / `cameraY` | float | `0` | World-space offset of the view |
 | `cameraScale` | float | `1` | Zoom, anchored on the view center |
 | `cameraBounds` | dict / null | `null` | `{ minX, minY, maxX, maxY }` world rect the visible area is clamped into |
@@ -111,7 +114,7 @@ A normal Titanium view — add it to a window or any container, size it with the
 | `follow(sprite, options)` | method | — | Native dead-zone follow, see below |
 | `stopFollow()` | method | — | Stop following; the camera stays where it is |
 | `shake({ strength, duration })` | method | `12` px, `400` ms | Detuned-sine rumble on the projection only — follow, bounds and touch mapping are unaffected |
-| `raycast(x0, y0, x1, y1, groups)` | method | — | One-shot nearest-hit query along the segment against **visible, non-`screenFixed`** sprites carrying a `collisionGroup` in `groups` (omit for any tagged sprite). Returns `null` for a clear ray, else `{ x, y, distance, group, sprite, normal: { x, y } }`. Rect hitboxes are tested as their AABB, circle hitboxes exactly; a ray starting inside a hitbox reports it at distance 0 |
+| `raycast(x0, y0, x1, y1, groups)` | method | — | One-shot nearest-hit query along the segment against **visible, non-`screenFixed`** sprites carrying a `collisionGroup` in `groups` (omit for any tagged sprite). Returns `null` for a clear ray, else `{ x, y, distance, group, sprite, normal: { x, y } }`. Plain rect hitboxes use their AABB; circle and `rotatedRect` hitboxes use their actual shapes; a ray starting inside a hitbox reports it at distance 0 |
 | `findPath(from, to, options)` | method | — | Grid A\* from `from` to `to` (`{ x, y }` world points) around visible, non-`screenFixed` sprites and fully solid TileLayer cells carrying a `collisionGroup` in `options.groups` (omit for any tagged obstacle). Returns `{ x, y }` waypoints ready for `sprite.followPath()`, or `null`. Options below |
 | `after(ms, callback)` | method | — | Runs `callback` once after `ms` of **game time** — the delay stretches under `timeScale` slow motion, freezes at `0` and pauses with the render loop, unlike `setTimeout`. Returns an int id. The callback receives `{ id }` |
 | `every(ms, callback)` | method | — | Like `after()`, repeating until cancelled. Fires at most once per frame, and restarts its interval after a stall instead of bursting to catch up |
@@ -127,6 +130,8 @@ A normal Titanium view — add it to a window or any container, size it with the
 
 Events: `press`, `tap`, `release` — fired for **every** touch anywhere on the view, with payload `x`, `y` in scene coordinates (tap-anywhere controls, flappy-style). `resize` carries the real surface `width`, `height` in pixels. `performance` carries a one-second telemetry snapshot only while a listener exists; see [debugging-performance.md](debugging-performance.md).
 
+Keyboard `keydown` / `keyup` carry `code`, `character`, and `modifiers: { shift, control, alt, meta }`. Action `actiondown` / `actionup` carry `action` and `context`; cancellation may release actions without raw `keyup`. See [input.md](input.md).
+
 Plus `timer` with payload `id`, fired only for `after()` / `every()` calls made **without** a callback — pass a callback or listen for the event, not both.
 
 Kroll never runs a `@Kroll.setProperty` setter for a key passed to `createGameView()`: each one needs its own branch in the native creation handler. `cameraX`, `cameraY`, `cameraScale` and `cameraBounds` were silently dropped at creation before `3bea2f4` and are honored from it on. Assigning them after creation always worked and still does — prefer that when the installed artifact is unknown.
@@ -192,9 +197,7 @@ On Android the buttons are captured at the activity window: the game view needs
 
 `platformer.js` runs on either the on-screen buttons or a pad.
 
-That single-view example does not establish independent receivers for several
-retained iOS GameViews: the pinned controller adapter overwrites a shared
-GCController callback. See [lifecycle and input ownership](project-setup.md#retained-ios-scenes-and-multiple-gameviews).
+Every live GameView receives controller input independently, including retained views under a modal scene. Closing one releases its input and unregisters only that receiver. Apple receivers share the GameController profile callback with registration, dispatch and cleanup on the main queue. Route input to the active screen in app code; see [lifecycle and input ownership](project-setup.md#retained-ios-scenes-and-multiple-gameviews).
 
 ## SpriteSheet
 
@@ -205,17 +208,17 @@ Create one sheet per texture and share it across every sprite that uses it — s
 | `image` | — | Path to the texture, relative to the resources root (`'assets/hero.png'`) |
 | `frameWidth` / `frameHeight` | — | Grid mode: cell size in source pixels. Frames are numbered left-to-right, top-to-bottom, starting at 0 |
 | `atlas` | — | TexturePacker JSON (hash or array format) instead of a grid |
-| `smoothing` | `true` | `false` = GL_NEAREST, the pixel-art setting. On a **grid** sheet, `true` also insets the frame UVs by half a texel so magnified edges cannot sample the neighbouring frame — **both** edges of any axis that has more than one frame, since 2026-08-24. An axis with a single frame keeps the exact 0..1 range, which is what `tileRepeat` needs to wrap. Atlas frames come from the JSON untouched |
-| `repeat` | `false` | GL_REPEAT wrap, required by sprites using `tileRepeat`. Needs power-of-two texture dimensions |
+| `smoothing` | `true` | `false` = nearest-neighbor filtering, the pixel-art setting. On a **grid** sheet, `true` also insets the frame UVs by half a texel so magnified edges cannot sample the neighbouring frame — **both** edges of any axis that has more than one frame, since 2026-08-24. An axis with a single frame keeps the exact 0..1 range, which is what `tileRepeat` needs to wrap. Atlas frames come from the JSON untouched |
+| `repeat` | `false` | Texture repeat, required by sprites using `tileRepeat`. Android OpenGL ES 2.0 requires power-of-two texture dimensions |
 
 | Member | Notes |
 | --- | --- |
 | `frameCount` | Number of frames. `0` until the texture has loaded, for grid sheets |
 | `frameNames` | Sorted frame names — atlas sheets only |
 | `frameIndex(name)` | Index for an atlas frame name, `-1` if unknown |
-| `unload()` | Frees the GL texture on the next rendered frame, from the render thread. **Permanent** — sprites still using the sheet stop drawing. For level streaming: unload the finished level's atlases instead of accumulating GPU memory. Since 2026-08-23 |
+| `unload()` | Permanently disposes the GPU texture on the render thread. Sprites still using the sheet stop drawing. For level streaming: unload the finished level's atlases instead of accumulating GPU memory. Since 2026-08-23 |
 
-Textures upload to the GPU lazily on first use, from the render thread, and are re-created automatically after an EGL context loss. Releasing the proxy unloads its texture too, so a sheet that goes out of scope does not strand GPU memory.
+Textures upload to the GPU lazily on first use, from the render thread, and are re-created automatically after an Android EGL context loss. Apple resources are Metal textures; do not apply EGL-specific lifecycle assumptions to Apple views. Releasing the proxy unloads its texture too, so a sheet that goes out of scope does not strand GPU memory.
 
 ## Sprite
 
@@ -244,12 +247,12 @@ Textures upload to the GPU lazily on first use, from the render thread, and are
 | Property | Default | Notes |
 | --- | --- | --- |
 | `sheet` | — | The SpriteSheet |
-| `frame` | `0` | Current frame index; writing it stops nothing, it just shows that frame |
-| `animations` | — | Named definitions: `{ walk: { frames: [1, 2], fps: 6, loop: true } }` |
+| `frame` | `0` | Current frame index; writing it stops the running sheet animation and its queued chain, then shows that frame |
+| `animations` | — | Creation-only for portable code; iOS also accepts later assignment, Android has no live setter. Definitions: `{ walk: { frames: [1, 2], fps: 6, loop: true } }` |
 | `animation` | — | Read-only name of the current animation. **Keeps its value after `stop()`** — track "is walking" yourself if you need it |
 | `tileRepeat` | `false` | `true` / `'x'` / `'y'` — tile the frame at native size instead of stretching. Needs `repeat: true` on the sheet and a frame spanning the whole texture |
 
-An animation definition takes `frames` (array of indices), `fps`, `loop`, and an optional `frame` — the sheet frame to show once a non-looping animation finishes (default: hold the last animation frame).
+An animation definition takes `frames` (array of indices), `fps`, `loop`, and, on Android only, an optional completion `frame` (default: hold the last animation frame). iOS ignores that definition key. Both platforms support a completion `frame` in `animate()`.
 
 Methods: `play(name)` starts an animation, `stop()` halts it on the current frame.
 
@@ -275,7 +278,7 @@ Hit-testing runs against the transformed shape (rotation and scale included), to
 | `velocityX`, `velocityY` | `0` | px/s |
 | `gravity` | `0` | px/s², added to `velocityY`. Per sprite — there is no global gravity |
 | `gravityX` | `0` | px/s², added to `velocityX`. The **sibling** of `gravity`, not half of a vector: `gravity` keeps its exact vertical meaning. Wind, a conveyor, or a top-down game whose "down" is sideways (`gravity: 0`, `gravityX` non-zero). Since 2026-08-27 |
-| `linearDamping` | `0` | Coefficient in 1/s: each step retains `max(0, 1−linearDamping·dt)` of both velocity axes, after thrust/gravity and before position. Below combined speed **4 px/s** it zeroes both axes; this can erase a small first thrust step. ~`0.6` is used for pool felt, but damping acts even without contact. Negative values clamp to0. See [physics.md](physics.md#thrust-inertia-and-linear-damping) |
+| `linearDamping` | `0` | Coefficient in 1/s: each step retains `max(0, 1−linearDamping·dt)` of both velocity axes, after thrust/gravity and before position. The **4 px/s** rest cutoff stops coasting and blocked residual motion, but effective thrust, gravity or powered car input can build velocity from rest. The post-contact decision excludes blocked motion and cancelled forces; damping still attenuates acceleration and depends on dt. ~`0.6` is used for pool felt, but damping acts even without contact. Negative values clamp to0. See [physics.md](physics.md#thrust-inertia-and-linear-damping) |
 | `maxSpeed` | `500` | px/s cap applied **only** to `thrust` acceleration and the `carMode` model. Writing `velocityX`/`velocityY` directly is never clamped |
 | `angularVelocity` | `0` | deg/s |
 | `thrust` | `0` | px/s² along the current heading (Newtonian flight) |
@@ -325,7 +328,7 @@ Two consequences that cost an afternoon each if you meet them by surprise:
 | `hitboxScale` | `1` | Shrinks the collision box **around the anchor** — which is what makes `anchor` the other half of the tuning: `anchor: 'bottom'` with `hitboxScaleY: '55%'` covers the lower half without lifting the box off the floor. Also takes `'80%'` |
 | `hitboxScaleX`, `hitboxScaleY` | `1` | Per-axis corrections **multiplied on top of** `hitboxScale`, for art that fills its frame by a different fraction on each axis. A 20×44 drawing in a 32×48 frame needs `0.62` wide and `0.92` tall — no single `hitboxScale` describes it. Ignored by circle hitboxes. Since 2026-08-23 |
 | `hitboxShape` | `'rect'` | `'circle'` — radius = half the smaller drawn side × `hitboxScale` (the per-axis scales are skipped: a circle has no axes). Circles resolve against solids along the contact normal (corner bounces) and get a round touch area. `'rotatedRect'` keeps the collision rect **turned with the sprite** (an OBB) instead of re-boxing it square to the screen: a plain `'rect'` at 45° is re-boxed around its turned corners and comes out 41% wider with a flat top that is not there. Only matters once `rotation` is non-zero, and it does honour `hitboxScaleX`/`hitboxScaleY`, unlike a circle. Covers solids, `collidesWith` overlap, `raycast`, the swept pass and the debug overlay. Since 2026-08-27 |
-| `swept` | `false` | Test this sprite's movement as a **path** (swept AABB), not just at the end position, so a fast mover cannot tunnel between frames. Applies to both `collidesWith` events and `solidWith` blocking (the sprite is clamped to the impact point, then resolved by the normal static pass). Two **circle** hitboxes now sweep as circles (the Minkowski sum of two circles is a circle of radius r1+r2); a circle against a rectangular or turned solid sweeps as a box, and against a turned one the box is grown into a *rounded* rect so the diagonal does not poke out by 1.41r. Set it on the *mover* — the bullet, not the wall. The sweep skips solids that are not `solidMode: 'block'` |
+| `swept` | `false` | Test this sprite's movement as a **path**, not just at the end position, so a fast mover cannot tunnel between frames. Applies to both `collidesWith` events and `solidWith` blocking (the sprite is clamped to the impact point, then resolved by the normal static pass). Two **circle** hitboxes now sweep as circles (the Minkowski sum of two circles is a circle of radius r1+r2); trigger sweeps for circle/rectangle pairs use a rounded box (including turned boxes), while rectangle pairs use AABBs. The `solidWith` blocking sweep is separate: circle pairs use circles; circle-versus-rect blocking keeps its own expanded-box/rounded-OBB path. Do not infer identical trigger and blocking geometry. Set it on the *mover* — the bullet, not the wall. The sweep skips solids that are not `solidMode: 'block'` |
 | `debug` | `false` | Draw this sprite's shapes: green = collision AABB, blue = touch bounds, orange dot = anchor |
 
 ### Car (`carMode`)
@@ -373,7 +376,7 @@ Every sprite gets its own phase, and the wobble unwinds exactly when disabled. T
 | --- | --- |
 | `play(name, options)` | Start a named animation; returns `false` for an unknown name. `options.then` (a name or an array of names) chains natively — each queued animation starts as the previous non-looping one finishes, and `animationcomplete` still fires per step. A looping animation ends the chain |
 | `stop()` | Stop the animation on the current frame; also drops any queued `then` chain |
-| `followPath(points, options)` | Walk the sprite along `points` — `{ x, y }` objects or `[x, y]` pairs, **at least two**, fewer is ignored with a warning. `options`: `speed` px/s (default `100`), `loop` (closed circuit), `rotate` (face along the path, 0 = up), `smoothing` (corner radius in px, precomputed once). Fires `pathcomplete` at the end of a non-looping run and clears itself. `followPath(null)` stops in place |
+| `followPath(points, options)` | Walk the sprite along `points` — `{ x, y }` objects or `[x, y]` pairs, **at least two**; fewer logs a warning and clears the path. `options`: `speed` px/s (default `100`), `loop` (closed circuit), `rotate` (face along the path, 0 = up), `smoothing` (corner radius in px, precomputed once). Fires `pathcomplete` at the end of a non-looping run and clears itself. `followPath(null)` stops in place |
 | `animate(options)` | Native tween, fires `complete` |
 | `clearTweens()` | Cancel tweens in progress — call before starting a replacement tween |
 | `flash(color, duration)` | Fills the sprite's silhouette with `color` (default white) and fades it out over `duration` ms (default 150). The classic damage/invincibility flash that a multiplicative `tintColor` cannot do |
@@ -435,7 +438,7 @@ The rest of the contract, all read from the engine:
 
 ## Font
 
-A glyph atlas for text sprites. Create it once, outside `resize`, like a SpriteSheet — it holds a GL texture.
+A glyph atlas for text sprites. Create it once, outside `resize`, like a SpriteSheet — it holds a GPU texture.
 
 ```javascript
 // 1. Built-in: nothing to ship. A 9x15 pixel font embedded in the module.
@@ -460,6 +463,8 @@ const mono = Game.createFont({ image: 'assets/mono.png', charWidth: 9, charHeigh
 | `lineHeight` | — | Read-only: the font's natural line height in px |
 | `unload()` | Method, not an option: frees the glyph texture exactly like `SpriteSheet.unload()`, and just as permanently. Since 2026-08-23 |
 
+The built-in font is Press Start 2P with 9×15 cells: ASCII 32..126 plus `ÁÉÍÓÚÜÑáéíóúüñ¿¡ÄÖäößËÏëïÈèÊêÀà`. It accepts these precomposed characters, not combining accents; `ẞ` is absent, so uppercase German text uses `SS`. Custom grid fonts still default to ASCII only. The source TTF and SIL Open Font License are in `tools/default-font/`; regenerate both embedded images with `uv run --with pillow --with fonttools python tools/build_default_font.py`.
+
 A descriptor that fails to parse falls back to the built-in font and logs the error — the text still renders, in the wrong face, which is the symptom to recognize.
 
 ## Text
@@ -520,12 +525,12 @@ music.play();
 
 | Option | Default | Notes |
 | --- | --- | --- |
-| `url` | required | App resource or file path |
+| `url` | required | Creation-only app resource or file path |
 | `volume` | `1` | 0..1, live |
 | `loop` | `false` | Live |
 | `music` | `false` | Chooses the backend — **set at creation, not changeable later** |
 
-Effect mode (the default) is built for low latency: a shared `SoundPool` on Android, a small pool of preloaded players on iOS. Call `play()` from any handler and repeated plays overlap instead of cutting each other off. `music: true` picks the streaming backend (`MediaPlayer` / `AVAudioPlayer`) for longer tracks; music pauses when the app backgrounds and resumes with it.
+Effect mode (the default) is built for low latency: a shared `SoundPool` on Android, a small pool of preloaded players on iOS. Call `play()` from any handler and repeated plays overlap instead of cutting each other off; a play requested during loading is queued. `music: true` picks the streaming backend (`MediaPlayer` / `AVAudioPlayer`) for longer tracks; music pauses when the app backgrounds and resumes with it.
 
 Methods: `play()`, `pause()` (resumes where it stopped), `stop()` (rewinds to the beginning). Formats: WAV, MP3, OGG on Android; WAV, MP3, M4A on iOS.
 
@@ -550,7 +555,7 @@ Add and remove like a sprite: `gameView.add(emitter)` / `remove(emitter)`. Spawn
 | `size` | `0` | Base particle width in px; `0` = frame size |
 | `startScale` / `endScale` | `1` / `1` | Interpolated over `lifetime` |
 | `startOpacity` / `endOpacity` | `1` / `0` | Interpolated over `lifetime` |
-| `tint` | white | Tint white particle art at runtime — one tiny texture covers every color in the game |
+| `tint` | white | Write-only. Tint white particle art at runtime — one tiny texture covers every color in the game |
 | `blend` | `'normal'` | `'add'` for fire, sparks and magic; `'multiply'` for smoke and dust that darken what they cross; `'screen'` for soft haze |
 | `maxParticles` | `200` | Pool size, hard cap 1000 |
 
@@ -577,9 +582,8 @@ A native Verlet chain: integration and distance constraints run in the game loop
 | `visible` | `true` | |
 | `endX`, `endY` | — | Read-only live position of the loose end (grappling-hook tips) |
 
-Per-step retention is not a per-second rate. Rope's existing displacement and
-constraint passes still execute at `dt=0` in the pinned implementation;
-see [Verlet equations and pause limits](physics.md#verlet-ropes-and-tethers).
+Per-step retention is not a per-second rate. At `dt<=0`, node positions, previous positions, constraint relaxation and tether response stay frozen. New geometry still initializes so a newly created rope can draw while paused;
+see [Verlet equations and pause behavior](physics.md#verlet-ropes-and-tethers).
 
 The tether yields at the end no finger owns: with a fixed head anchor the tail sprite is simply leashed, but with sprites on both ends you can drag either one and the other is towed once the rope goes taut.
 
@@ -589,7 +593,7 @@ One native grid replaces a sprite per tile. Only cells inside the camera are dra
 
 | Group | Members | Notes |
 | --- | --- | --- |
-| Grid input | `data` | Nested numeric rows, string rows decoded through `legend`, or flat row-major ids sized by `cols`/`rows`. Live on both platforms |
+| Grid input | `data` | Live write-only input. Nested numeric rows, string rows decoded through `legend`, or flat row-major ids sized by `cols`/`rows`. Live on both platforms |
 | Creation-time grid configuration | `legend`, `firstGid`, `cols`, `rows` | Set in `createTileLayer()` for portability. `cols`/`rows` read back from the parsed grid; Android has no live setters for the four configuration inputs |
 | Derived size | `width`, `height` | Read-only world dimensions |
 | Placement | `x`, `y`, `tileWidth`, `tileHeight`, `zIndex`, `scrollFactor` | Tile sizes default to the sheet frame dimensions |
@@ -603,7 +607,7 @@ Tiled data uses `firstGid`: gid 0 becomes empty when an offset is active, and fl
 | `getTile(col, row)` | Frame id, `-1` when empty or outside |
 | `setTile(col, row, id)` | Replaces art and recalculates its flag from `solid`/`oneWay` |
 | `isBlocked(col, row)` | Fully solid status; one-way cells answer `false` |
-| `setBlocked(col, row, bool)` | Per-cell full-solid override without changing art |
+| `setBlocked(col, row, bool)` | Per-cell full-solid override without changing art, until `data`, `solid` or `oneWay` changes |
 | `tileAt(x, y)` | World point → `{ col, row, tile, solid, x, y }`, or `null` outside |
 | `cellAt(col, row)` | Cell → the same structure; `x`/`y` are the center |
 
@@ -613,7 +617,7 @@ Movers list the layer's `collisionGroup` in `solidWith`. Rect, circle, swept, re
 
 Only these events exist. Nothing fires per frame, and events are only fired if a listener is registered.
 
-- **GameView**: `press`, `tap`, `release`, `resize`, `timer`, `performance`, `buttondown`, `buttonup`, `stick`, `trigger`, `gamepadconnected`, `gamepaddisconnected`
+- **GameView**: `press`, `tap`, `release`, `resize`, `timer`, `performance`, `buttondown`, `buttonup`, `stick`, `trigger`, `gamepadconnected`, `gamepaddisconnected`, `keydown`, `keyup`, `actiondown`, `actionup`
 - **Sprite** (and therefore **Text**): `press`, `release`, `tap`, `dragstart`, `drag`, `dragend`, `pinch`, `rotate`, `animationcomplete`, `complete`, `pathcomplete`, `collision`, `collisionend`, `land`, `wallhit`, `solidimpact`
 - **SpriteSheet, Font, Sound, Emitter, Rope, TileLayer**: none
 
@@ -631,12 +635,12 @@ There is `collision` (enter) and `collisionend` (exit), but deliberately **no**
 - **`music` is chosen at creation.** Creating an effect sound and flipping `music` later does not switch backends.
 - **`collision` fires once per overlap-enter**, re-arming only after the shapes separate. A sprite resting inside a trigger does not re-fire — `collisionend` tells you when it left.
 - **Pooling a sprite with `visible = false` fires `collisionend`** on whoever was touching it. That is usually what you want (a plate whose ball was despawned closes its door), but a handler that assumes separation means "the player walked away" will misfire.
-- **The built-in pixel font only covers ASCII 32..126.** Em dashes, accents and `ñ` render as blanks or garbage — the module's own demos rewrote `—` as `-` for this reason. Ship a BMFont atlas (`tools/genfont.py` rasterizes any TTF) when the game needs accented Spanish text.
+- **The built-in font includes a specific accented Latin repertoire, not arbitrary Unicode.** Precomposed Spanish `ñ` and the listed accented characters work; combining accents, em dashes and unlisted glyphs need a custom BMFont/grid atlas. Custom grid fonts default to ASCII 32..126 unless `characters` is supplied.
 - **A bouncy floor switches `onGround` off.** In every resolver the grounding and the `land` event live in the branch taken when the bounce is *damped away*; a contact whose rebound would exceed 40 px/s reflects and grounds nothing. That was always true of a bouncy rider, but `restitution` now mixes as `max(mover, solid)`, so giving a *floor* `restitution: 0.5` silently stops every rider that lands hard on it from ever reporting `onGround` — and a jump gated on `onGround` stops working on that one platform.
 - **A two-sided `restitution` cannot be opted out of.** The mix is `max`, not a product or an average, so the springier surface always wins: a deliberately dead `restitution: 0` crate still bounces off a floor set to `0.5`. If one rider must not bounce, the bounce has to live on the riders, not on the surface.
 - **A resting body is allowed to sink half a pixel — in some resolvers.** Separation is skipped when the overlap is under 0.5 px, because shoving a gravity-loaded body back out sixty times a second is what makes a settled pile tremble; the closing velocity is still cancelled, so the sink cannot grow past it. It applies to the circle path, the turned-rect path and `'push'` pairs. Plain rect-against-rect still separates in full. Do not derive an exact contact position from `y` after a landing.
 - **`linearDamping` is not surface friction.** Nothing checks whether the sprite is touching anything: it bleeds speed on both axes every frame, in the air as much as on the felt, and along a slope as much as across it. It is right for a pool table and wrong for a hill, which is why upstream still lists contact-only friction as unbuilt. A projectile that must keep its arc wants `0`.
-- **`linearDamping` kills a slow deliberate drift.** Under a combined 4 px/s the engine zeroes *both* axes outright, since a proportion never reaches zero on its own. A conveyor nudging something along at 3 px/s stops dead the moment that sprite also carries any damping.
+- **`linearDamping` stops slow coasting.** Under 4 px/s it stops unpowered drift; an effective acceleration can now build speed from rest. Forces cancelled by opposing forces or a solid do not keep residual tangential coasting alive. This rest policy does not make Euler damping independent of frame rate.
 - **A swept sprite is not contained and not pushed.** The sweep only considers solids in `solidMode: 'block'` — a `'contain'` boundary would stop the ball against its *outside*, and a `'push'` body is meant to move. So `swept: true` does not stop a fast enough ball from crossing a drum wall between frames; only the static pass contains it. Keep the speeds inside a container below its wall thickness per frame.
 - **`'push'` pairs never publish ground or wall contact.** The bilateral resolver moves positions and exchanges velocity but does not update `onGround`, `onWallLeft` / `onWallRight`, `land`, or `wallhit`. A pile of balls resting on each other reports contact only with any separate `'block'` surface underneath it.
 - **The `'push'` exchange has no masses, no spin and no friction.** A marble and a boulder trade velocity identically, and nothing ever starts rotating from a contact. `restitution` mixes as `max` here too, and with no mass to weight it against, that is the whole model.

package/skills/ti-game/references/debugging-performance.md

@@ -1,6 +1,7 @@
 # Debugging and performance telemetry
 
-Verified against `ti.game@3bea2f4`: both `GameViewProxy` implementations, `DebugHud`, `FrameStats`, both scene renderers, `example/camera.js`, `example/particles.js`, and `example/tilemap.js`.
+Reviewed on 2026-10-23 against upstream native `88e181c` and
+`macCesar/ti.game@2bf5f82` documentation: both `GameViewProxy` implementations, `DebugHud`, `FrameStats`, both scene renderers, `example/camera.js`, `example/particles.js`, and `example/tilemap.js`.
 
 ## The two debug aids
 
@@ -32,7 +33,7 @@ The HUD is screen-space and is drawn after the camera effect. Camera scroll, zoo
 - Green: collision shape after `hitboxScale`, `hitboxScaleX`, and `hitboxScaleY`.
 - Blue: full sprite/touch bounds.
 - Orange: anchor.
-- Tile debug: outlines fully solid cells in view.
+- Tile debug: green outlines fully solid cells; yellow marks one-way top faces.
 
 Tune geometry in this order:
 
@@ -47,7 +48,7 @@ The scale properties affect collision, not the touch rectangle. `hitboxShape: 'c
 
 | HUD | Event key | Meaning |
 | --- | --- | --- |
-| `FPS` | `fps` | Frames presented in the closed one-second window |
+| `FPS` | `fps` | Frames recorded in the measurement window; Metal submission does not confirm physical presentation |
 | `MS` | `averageCpuMs` | Average engine CPU time per frame; the `maxFps` wait is excluded |
 | `P95` | `p95CpuMs` | 95th percentile CPU frame time |
 | `MAX` | `maxCpuMs` | Worst CPU frame in the window |
@@ -60,8 +61,8 @@ The scale properties affect collision, not the touch rectangle. `hitboxShape: 'c
 | `UPDATE` | `averageUpdateMs` | Physics, animation, tween, and scene update time |
 | `TEXTURE` | `averageTexturePrepareMs` | Texture preparation/upload time |
 | `BATCH` | `averageBatchMs` | Batching and drawing time |
-| `PRESENT` | `averagePresentMs` | iOS only: buffer presentation time |
-| `PRESENTFAIL` | `presentFailures` | iOS only: failed presentations |
+| `PRESENT` | `averagePresentMs` | Apple only: CPU time acquiring a Metal drawable and submitting presentation; excludes GPU execution |
+| `PRESENTFAIL` | `presentFailures` | Apple only: missing drawables and reported command errors |
 
 The event also includes `surfaceWidth` and `surfaceHeight`. Android omits `averagePresentMs` and `presentFailures`; do not interpret missing keys as zero.
 
@@ -81,7 +82,7 @@ function cleanup() {
 }
 ```
 
-Telemetry is opt-in inside the renderers. With the HUD disabled and no `performance` listener, frame-stat clock reads are disabled. Use the HUD while developing; use the event for short diagnostic sessions or a deliberate in-app performance screen, not permanent per-frame business logic.
+Telemetry is opt-in inside the renderers. With the HUD disabled and no `performance` listener, telemetry timing and HUD drawing are skipped. The simulation clock still runs. Use the HUD while developing; use the event for short diagnostic sessions or a deliberate in-app performance screen, not permanent per-frame business logic.
 
 ## Reading the numbers
 
@@ -90,15 +91,23 @@ Telemetry is opt-in inside the renderers. With the HUD disabled and no `performa
 - High update time: narrow collision groups and reduce active colliders/particles; hidden sprites are excluded from render and collision.
 - A large `TileLayer` should keep draw calls and visible work stable while the camera moves; one sprite per tile scales with the whole scene instead.
 - `maxFps: 60` can prevent a 120 Hz display from doubling work when the game does not need it.
-- Judge final performance on hardware. The iOS Simulator's translated OpenGL path is intentionally rendered at 1× and remains slower than a device.
+- Judge final performance on hardware. The Apple backend uses Metal on iPhone, iPad, Simulator and Mac Catalyst. Simulator/host fixture results do not establish physical-device GPU timing or presentation.
+
+The Apple Simulator keeps a 1× logical drawable; physical iPhone/iPad builds
+use native screen scale. A frame-cap request is platform scheduling, and a
+Metal frame can be skipped when its in-flight slot or drawable is unavailable.
+The next successful simulation frame includes elapsed time capped at 0.1 s.
+Do not compare telemetry across different drawable scales or call submission
+counts a measurement of physically presented frames.
 
 ## Common diagnostic order
 
 For a physics discrepancy, record the installed build/commit, surface size,
 `timeScale`, input values and actual FPS first. `maxFps` is a cap, not a fixed
 physics step. A visible thruster proves an animation state, not acceleration.
-The damping rest threshold can erase a small first thrust step, and Rope uses
-per-update damping. See [physics.md](physics.md#time-step-and-frame-rate).
+Older builds could erase a small first thrust step; current source preserves
+effective acceleration and settles coasting after contacts. Rope still uses
+per-update damping, but now freezes at zero game delta. See [physics.md](physics.md#time-step-and-frame-rate).
 
 1. Confirm the object was added and is visible/in bounds.
 2. Turn on the relevant sprite/layer debug shape, then the global overlay if relationships are unclear.

package/skills/ti-game/references/examples.md

@@ -1,6 +1,6 @@
-# Upstream example catalog
+# Module example catalog
 
-Verified against all 34 self-contained demos under `ti.game@3bea2f4:example/`, plus the launcher `example/app.js` and the shared back-control helper `example/backnav.js` (neither is a demo). `wallhit` now has one user — `worldwrap.js` counts bolt hits with it — but `wallSlideSpeed` and the `onWallLeft`/`onWallRight` flags still have no demo; for those use [the platformer recipe](recipes-action.md#platformer), verified against both native implementations and the README contract.
+Catalog checked against `macCesar/ti.game@2bf5f82:README.md` (Learn from the examples) and `example/app.js`: 35 demos at the reviewed snapshot, 34 touch-ready entries on phones/tablets and the additional Configurable Input entry on Mac Catalyst (`osname === 'macos'`). The launcher and `backnav.js`, `keyboard.js`, and `pool-viewport.js` are helpers, not demos. The current upstream branch is `m1ga/ti.game@88e181c`; the reviewed checkout adds documentation commit `2bf5f82`. These features are not established by the older `3bea2f4` skill pin. `wallhit` now has one user — `worldwrap.js` counts bolt hits with it — but `wallSlideSpeed` and the `onWallLeft`/`onWallRight` flags still have no demo; for those use [the platformer recipe](recipes-action.md#platformer), verified against both native implementations and the README contract.
 
 The demos show intended API combinations; reading them does not verify an
 installed module or device. They are **not** production templates: most keep
@@ -10,50 +10,51 @@ then apply the focused structure and cleanup patterns in this skill.
 
 For equations, units, genre selection and frame-rate limits, use
 [physics.md](physics.md). Rhythm's 400 ms interval is a quarter note at its
-stated 150 BPM, despite the upstream "eighth" comments. Flappy replaces
+stated 150 BPM; the current source now corrects the older "eighth" comments. Flappy replaces
 vertical velocity per tap; it does not add repeated impulses. The curated
 Lunar Lander recipe is not an additional upstream demo.
 
 | Demo | What it proves | Production-oriented reference |
 | --- | --- | --- |
+| `inputmap.js` | Native configurable actions shared across keys/mouse/gamepads; focus ownership, pause contexts, movement/aim/crouch/projectiles and raw input monitor | [Shared digital actions](recipes-action.md#shared-digital-actions) |
 | `basic.js` | Sheets, frame animation, drag/pinch/rotate, tween completion | [Scaffolding](patterns.md#the-scaffolding) |
-| `puzzle.js` | Multi-touch drag, press-to-lift, snapping and tween-back | [Cards and board games](recipes-adventure-effects.md#cards-and-board-games) |
-| `flappy.js` | Gravity impulse, invisible score/death zones, wrapping parallax | [Tap-to-flap](recipes-action.md#tap-to-flap) |
-| `platformer.js` | `solidWith`, `land`, `oneWay`, carried rider, camera follow, multi-touch controls, and the same actions driven by a gamepad | [Platformer](recipes-action.md#platformer) |
-| `volley.js` | Restitution ball, `land`, collision response, coarse AI timer | [Ball sports](recipes-action.md#ball-sports--breakout-physics) |
+| `puzzle.js` | Multi-touch drag, press-to-lift, free-cell snapping/re-drag, tween-back, solved spin and Restart | [Cards and board games](recipes-adventure-effects.md#cards-and-board-games) |
+| `flappy.js` | Gravity with replacement flap velocity, invisible score/death zones, five-gate win/reset and wrapping parallax | [Tap-to-flap](recipes-action.md#tap-to-flap) |
+| `platformer.js` | `solidWith`, `land`, `oneWay`, carried rider, camera follow, multi-touch controls, and shared keyboard/gamepad actions | [Platformer](recipes-action.md#platformer) |
+| `volley.js` | Restitution ball, `land`, biased player reflection, opponent score/serve, coarse AI and shared keyboard/gamepad actions | [Ball sports](recipes-action.md#ball-sports--breakout-physics) |
 | `racing.js` | `carMode`, drift, skid marks, checkpoints and lap state | [Top-down racer](recipes-action.md#top-down-racer) |
-| `cards.js` | Dealing, fanned layout, selection tweens and idle wobble | [Cards and board games](recipes-adventure-effects.md#cards-and-board-games) |
-| `asteroids.js` | Thrust, angular velocity, wrapping, pooling, additive bolts, effect/music audio | [Space shooter](recipes-action.md#asteroids--space-shooter) |
-| `topdown.js` | Small string map made from sprites, `ySort`, eight-way input, decision timer | [Top-down / Zelda](recipes-action.md#top-down--zelda) |
+| `cards.js` | Five-card deal, three-card selection, glow/wobble, Done play/re-fan and Reset sweep/redeal | [Cards and board games](recipes-adventure-effects.md#cards-and-board-games) |
+| `asteroids.js` | Thrust, angular velocity, wrapping, momentum-inheriting pooled/additive bolts, five-rock waves, three-hit lives/invulnerability/reset and audio | [Space shooter](recipes-action.md#asteroids--space-shooter) |
+| `topdown.js` | 12-column/15-row sprite map, animated water/solid house, nonblocking depth-sorted trees, eight-way input and companion follow/tree-state AI | [Top-down / Zelda](recipes-action.md#top-down--zelda) |
 | `skate.js` | Endless-runner pooling, carried/uncarried terrain, parallax, emitter and audio hooks | [Endless runner](recipes-action.md#endless-runner) |
 | `pointclick.js` | Tap-to-walk with `findPath` → `followPath`, hotspots and `ySort` | [Point-and-click](recipes-adventure-effects.md#point--click-adventure) |
 | `particles.js` | Continuous/burst emitters, sprite target, HUD telemetry | [Particles](recipes-adventure-effects.md#particles) and [debugging](debugging-performance.md) |
 | `worldwrap.js` | `worldWrapX` end to end: seam-aware camera, touch, overlap, solid resolution, swept movement, `wallhit`, and a full-width TileLayer that repeats across the seam | [Circular worlds](api.md#gameview) |
 | `rhythm.js` | Pooled notes, native velocity, `press` pads, timing and audio feedback | [Rhythm game](recipes-action.md#rhythm-game) |
-| `camera.js` | Two-axis follow, bounds, zoom, shake, camera effects, parallax and debug HUD | [Camera work](recipes-adventure-effects.md#camera-work) |
-| `rope.js` | Rope pinned to a sprite, fixed head, tail weight | [Ropes and chains](recipes-adventure-effects.md#ropes-and-chains) |
+| `camera.js` | Two-axis follow, bounds, zoom, shake, camera effects, parallax and screen-space `topRight` debug HUD | [Camera work](recipes-adventure-effects.md#camera-work) |
+| `rope.js` | Rope pinned to a sprite, fixed head/tail weight and two draggable ends | [Ropes and chains](recipes-adventure-effects.md#ropes-and-chains) |
 | `flip.js` | Draw-only flips driven by direction and inverted gravity | [Visual effects](recipes-adventure-effects.md#visual-effects) |
 | `hitbox.js` | Global/sprite debug overlays and per-axis hitbox correction | [Seeing the hitbox](patterns.md#seeing-the-hitbox--hitboxjs) |
 | `blend.js` | Normal/add/multiply/screen modes and `flash()` | [Visual effects](recipes-adventure-effects.md#visual-effects) |
-| `text.js` | Screen-fixed HUD, world labels, text buttons, word wrap and `attachTo` | [HUD](patterns.md#hud--textjs-flappyjs) |
+| `text.js` | Screen-fixed HUD, world labels, text buttons, word wrap, precomposed ES/DE/NL characters and `attachTo` | [HUD](patterns.md#hud--textjs-flappyjs) |
 | `swept.js` | Identical fast bullets with and without continuous sweep | [Object pooling](patterns.md#object-pooling) and [API gotchas](api.md#gotchas-the-property-tables-do-not-show) |
 | `path.js` | Looped/smoothed paths, one-shot paths and animation chains | [Patrol routes](patterns.md#patrol-routes-and-animation-chains--pathjs) |
 | `raycast.js` | Line of sight, ledge probes and tap-fired hitscan | [Raycast pattern](patterns.md#line-of-sight-ledge-probes-and-hitscan--raycastjs) |
 | `zones.js` | `collision`/`collisionend`, pressure plate and removal during contact | [Zones](patterns.md#zones-you-can-be-inside-of-enter--exit--zonesjs) |
-| `demoscene.js` | Follow-path circles, per-character scroller, glow, blend and music | [Visual effects](recipes-adventure-effects.md#visual-effects) |
-| `maze.js` | Raw/simplified A*, re-pathing AI and path visualization | [Pathfinding](patterns.md#pathfinding-around-obstacles--mazejs-pointclickjs) |
+| `demoscene.js` | Arc-offset per-character closed-path sine scroller, additive circle-driven copper bars, glowing logo, chained opacity pulse, period-scrolled starfield and music cleanup | [Visual effects](recipes-adventure-effects.md#visual-effects) |
+| `maze.js` | Raw/simplified A* dots, tap routes, 800 ms game-clock re-pathing chase and catch/den reset | [Pathfinding](patterns.md#pathfinding-around-obstacles--mazejs-pointclickjs) |
 | `timescale.js` | Slow/frozen scene, engine timer versus real-time interval | [Game-clock timers](patterns.md#timers-on-the-game-clock) |
 | `circles.js` | Rect/circle/rotated-rect solids and `block` versus bilateral `push` | [Shaped solids](patterns.md#shaped-solids-ramps-round-posts-and-bodies-that-push-back--slopesjs-circlesjs-pooljs-drumjs) |
 | `slopes.js` | Rotated-rect ramp normals and restitution supplied by a surface | [Shaped solids](patterns.md#shaped-solids-ramps-round-posts-and-bodies-that-push-back--slopesjs-circlesjs-pooljs-drumjs) |
-| `plinko.js` | Circular pegs, swept balls, trigger slots and `solidimpact` audio | [Shaped solids](patterns.md#shaped-solids-ramps-round-posts-and-bodies-that-push-back--slopesjs-circlesjs-pooljs-drumjs) |
-| `pool.js` | Bilateral circle momentum, rails, pockets, linear damping and `solidimpact` | [Shaped solids](patterns.md#shaped-solids-ramps-round-posts-and-bodies-that-push-back--slopesjs-circlesjs-pooljs-drumjs) |
-| `drum.js` | Analytic circular containment, contact-driven impulses and `solidimpact` | [Shaped solids](patterns.md#shaped-solids-ramps-round-posts-and-bodies-that-push-back--slopesjs-circlesjs-pooljs-drumjs) |
+| `plinko.js` | 86 circular pegs, swept/push chips, rect dividers, trigger payouts, chosen/random one/ten drops and deduplicated impact audio | [Shaped solids](patterns.md#shaped-solids-ramps-round-posts-and-bodies-that-push-back--slopesjs-circlesjs-pooljs-drumjs) |
+| `pool.js` | 16 bilateral push balls, rect rails, circular trigger pockets, felt damping, additive anytime shot, pair-deduplicated impact audio/reset and fitted portrait stage | [Shaped solids](patterns.md#shaped-solids-ramps-round-posts-and-bodies-that-push-back--slopesjs-circlesjs-pooljs-drumjs) |
+| `drum.js` | Analytic circular containment, 25 push balls, shake, enter/exit-rearmed tumble strip, separate glass/ball impact audio and pair deduplication | [Shaped solids](patterns.md#shaped-solids-ramps-round-posts-and-bodies-that-push-back--slopesjs-circlesjs-pooljs-drumjs) |
 | `wind.js` | `gravityX` as wind and as top-down constant acceleration | [Shaped solids](patterns.md#shaped-solids-ramps-round-posts-and-bodies-that-push-back--slopesjs-circlesjs-pooljs-drumjs) |
-| `tilemap.js` | One 120×90 `TileLayer`, visible-cell rendering, cell collision, live edits, A* and HUD | [Tile maps](tilemaps.md) |
+| `tilemap.js` | One 120×90 `TileLayer`, visible-cell rendering, cell collision, live edits, A* and HUD relayout on later resizes | [Tile maps](tilemaps.md) |
 
 ## Choosing the right map example
 
-`topdown.js` deliberately creates one sprite per tile for a small 16×12 scene; that remains reasonable when individual tiles need sprite behavior. `tilemap.js` is the reference for large or mostly static grids: one native `TileLayer` avoids ticking, sorting, drawing, and collision-scanning off-screen tile sprites.
+`topdown.js` deliberately creates one sprite per tile for a small 12-column by 15-row scene; that remains reasonable when individual tiles need sprite behavior. `tilemap.js` is the reference for large or mostly static grids: one native `TileLayer` avoids ticking, sorting, drawing, and collision-scanning off-screen tile sprites.
 
 ## Reading a demo safely
 
@@ -62,3 +63,85 @@ Lunar Lander recipe is not an additional upstream demo.
 3. Replace `var` and function-expression callbacks with the project's current ES6+ style.
 4. Keep resources outside `resize`; create surface-sized scene objects inside one guarded `resize` path.
 5. Separate reusable state from launcher UI and add explicit cleanup for app-owned listeners, timers, and sounds.
+
+## Keyboard shortcuts and shared helpers
+
+`keyboard.js` builds a native `inputMap`, dispatches `actiondown`/`actionup`
+to the existing gameplay functions, activates/focuses the canvas on window
+open/focus, and sets `inputContext = null` on blur/close. It removes its two
+action listeners on close. It also focuses immediately because a guarded
+scene `resize` may initialize after `Window.open`. This helper replaces the
+entire map; merge bindings in app code if the view already owns other actions.
+Platformer and Volley route mapped gamepad buttons through the same actions;
+do not also dispatch those actions from `buttondown`/`buttonup`.
+
+| Demos | Keyboard shortcuts |
+| --- | --- |
+| Platformer, Volley | Left/Right, A/D or J/L move; Space/Up/W/I jump; pad d-pad/left stick and A/up use the same actions |
+| Flappy, Flip | Space/Up/W flap or restart / invert gravity |
+| Skate | Space/Up/W jump or restart |
+| Plinko | Space/1 drops one chip; 0 drops ten |
+| Pool | R resets; mouse/touch aims |
+| Drum | Space shakes; T toggles tumble |
+| Circles | Space shoots; D toggles shapes |
+| Slopes | R resets; D toggles shapes |
+| Zones | Space/R removes or respawns the ball |
+| Text | Space scores; R resets; N advances dialog |
+| Tilemap | B toggles building; D toggles debug; mouse/touch selects cells |
+| Wind | Space drops; Left/Right or A/D changes wind |
+| Particles, Blend | Space creates a centered burst / flashes ships |
+| Rhythm | A/S/D or Left/Down/Right hits the lanes |
+| Swept | Space shoots both lanes; Left/Right or A/D changes speed |
+| Camera | Z/X zooms out/in; Space shakes |
+| Timescale | 1/2/3/4 selects 1/0.5/0.1/0 speed |
+
+Configurable Input has its own map: A/D, J/L or arrows move; last pressed
+left/right wins and releasing it restores the other held direction. Space
+or pad A jumps once from the ground. W/I/Up aims up (with horizontal movement
+for diagonal shots), S/K/Down crouches while grounded, left canvas click or
+pad X fires. The normalized direction keeps diagonal projectile speed equal
+to straight shots; crouching changes height while preserving foot position.
+Escape switches between gameplay/paused contexts and toggles `timeScale`.
+The right/middle mouse bindings are test entries: the reviewed docs report
+that they do not trigger on Mac; left click is the verified path.
+
+Instructions remain separate from changing action feedback. The monitor
+shows physical key codes/modifiers and pad buttons/sticks/triggers. Focusing
+the native text field disables actions and clears held movement; window
+focus does not steal that text focus. The focus button or first canvas click
+restores game input; that first click does not shoot. Blur/close disables
+actions, close cancels projectile-expiry game timers and unloads the four
+owned sheets. Run the indirect-input configuration from [project setup](project-setup.md)
+before mouse testing on the supported older Apple systems. Physical peripheral
+and overlay acceptance is separate from compilation and resolver fixtures.
+
+## Resizable scenes and portrait Pool
+
+The current demos size foreground art against both surface dimensions rather
+than letting a wide Mac window enlarge actors beyond its height. Scenes with
+native overlay controls derive pixels per view point from
+`resize.width / gameView.rect.width`, with a positive finite check and a
+logical-density fallback; monitor/display height is not the GameView size.
+
+Pool alone uses `pool-viewport.js`: a 380 by 680 point portrait stage contains
+both GameView and native Reset control. Host `postlayout` applies a uniform
+`min(hostWidth / 380, hostHeight / 680)` transform and removes that listener on
+close. Window resizing fits the running stage; it does not recreate balls,
+timers, collision bounds or drag state. Tilemap instead retains its native
+map and relays later `resize` values to HUD layout. Plinko fits chip/peg sizes
+to horizontal, diagonal and two-row gaps while preserving their proportions;
+wide/short scenes must still leave chip-sized passages.
+
+## Running and verification boundaries
+
+From the module's `android/`, use `ti build -p android --sdk 13.4.1.GA` for
+the launcher. On Apple, build the module, copy `example/` into a Classic app's
+`Resources/` and register the `iphone` module; keep the three helpers when
+copying demos that require them. Mac lists Configurable Input; mobile retains
+34 touch-ready entries, with the input demo source available for external
+peripheral tests. Back uses action-bar Up on Android and a shared overlay on Apple.
+
+The catalog is not exhaustive API acceptance: no dedicated wall-slide/jump or
+`unload()` demo exists, nor coverage for every gamepad event or creation-time
+option. `worldwrap.js` does exercise `wallhit`. Use native-contract references
+for uncovered members and verify the actual installed binary on the target.

package/skills/ti-game/references/input.md

@@ -0,0 +1,101 @@
+# Keyboard, mouse and action maps
+
+Reviewed 2026-10-23 against `m1ga/ti.game@88e181cb85526d8146d0be6e09b2b90c2551baad` native input resolvers and canvas adapters, with README clarification from `macCesar/ti.game@2bf5f828a3bb8028eed20d6ba27b97dd3aa9a753`. Requires an artifact containing those APIs; a shared version number is insufficient evidence. Existing controller events and analog input remain documented in [api.md](api.md#gamepads).
+
+## Map and event contract
+
+`GameView.inputMap` is optional, live, readable/writable and defaults to `{}`. It maps contexts to named actions, each with an array of digital bindings. `inputContext` accepts only a string or `null` (other types throw) and defaults to `'gameplay'`; `null` disables actions. Replace the whole map to rebind; the module supplies no settings UI or persistence.
+
+```javascript
+const gameView = Game.createGameView({
+	inputMap: {
+		gameplay: {
+			thrust: [
+				{ device: 'keyboard', code: 'KeyW' },
+				{ device: 'keyboard', code: 'ArrowUp' }
+			],
+			fire: [
+				{ device: 'keyboard', code: 'Space' },
+				{ device: 'mouse', button: 'left' },
+				{ device: 'gamepad', button: 'a' }
+			],
+			pause: [{ device: 'keyboard', code: 'Escape' }]
+		},
+		paused: { pause: [{ device: 'keyboard', code: 'Escape' }] }
+	}
+});
+gameView.addEventListener('actiondown', ({ action, context }) => {
+	// Dispatch discrete actions or write native motion properties here.
+	// A pause handler can change inputContext to 'paused' and timeScale to 0.
+});
+gameView.addEventListener('actionup', ({ action, context }) => {
+	// Clear held controls, including releases caused by lost focus/cancellation.
+});
+// Add the view, open the window, then call this (also after native text entry):
+gameView.focusInput();
+```
+
+The snippet is a map/transition template; scene setup and window lifecycle are in [project-setup.md](project-setup.md). No per-frame JavaScript polling is needed: action resolution runs natively on input transitions.
+
+| Input | Contract |
+| --- | --- |
+| `actiondown` / `actionup` | Payload `{ action, context }`. An action goes down on its first active binding and up after its last source releases, across different bindings and controllers |
+| Map replacement | A valid map releases previous active actions and requires a fresh press; held keys cannot activate the replacement map until released and pressed again |
+| Context change | Releases active actions from the old context, requires a fresh press; assigning the same context leaves state unchanged |
+| Invalid map | Throws without replacing the map or active state |
+| Cancellation | Focus loss, suspension, device disconnection and view shutdown release held actions. An action release need not have a physical/raw `keyup`; drive gameplay from action transitions |
+| Auto-repeat | Ignored as a new press; holding a key does not repeat `actiondown` |
+
+Context and action names must be nonempty strings. Empty contexts and empty action arrays are allowed. Each binding has **exactly two keys**: `device` plus `code` for keyboard, or `device` plus `button` for mouse/gamepad. Analog axes are not action bindings.
+
+| Device | Accepted binding values |
+| --- | --- |
+| `keyboard` (`code`) | `KeyA`…`KeyZ`, `Digit0`…`Digit9`, `ArrowUp`, `ArrowDown`, `ArrowLeft`, `ArrowRight`, `Space`, `Escape`, `Enter`, `Tab`, `Backspace`, `Delete`, `Home`, `End`, `PageUp`, `PageDown`, `F1`…`F12`, `ShiftLeft`/`ShiftRight`, `ControlLeft`/`ControlRight`, `AltLeft`/`AltRight`, `MetaLeft`/`MetaRight` |
+| `mouse` (`button`) | `left`, `middle`, `right` |
+| `gamepad` (`button`) | `a`, `b`, `x`, `y`, `l1`, `r1`, `l2`, `r2`, `l3`, `r3`, `start`, `select`, `home`, `up`, `down`, `left`, `right` |
+
+Existing gamepad properties, individual button events, sticks and triggers are unchanged. Use mapped actions **or** individual button handlers for each gameplay action to avoid dispatching twice. An app keeping its own gamepad adapter can omit gamepad bindings from the map.
+
+## Keyboard focus and pointer ownership
+
+Raw `keydown` / `keyup` events carry `{ code, character, modifiers: { shift, control, alt, meta } }`. `code` identifies the physical key independently of its text character; `character` can be empty for non-text keys.
+
+Only the focused GameView receives keyboard events. `focusInput()` requests canvas focus on the UI thread; it neither opens a software keyboard nor captures keys globally. Native text fields retain their focus. Call it after opening the game window and after returning from a native text field.
+
+When the active context has mouse bindings, pointer gestures delivered to the canvas feed mapped actions and are consumed rather than also becoming sprite tap/drag interactions. Empty maps, keyboard-only contexts and disabled actions preserve existing sprite pointer interaction. Overlay Titanium controls retain their clicks and focus; the module does not capture their mouse events. Android retains the engine touch listener.
+
+For iOS/iPadOS 13.4–16 pointer identification, set the consuming application's `tiapp.xml` opt-in (iOS 17+ defaults it to true):
+
+```xml
+<ios>
+  <plist>
+    <dict>
+      <key>UIApplicationSupportsIndirectInputEvents</key>
+      <true/>
+    </dict>
+  </plist>
+</ios>
+```
+
+This application-level setting distinguishes indirect pointers from direct touch; the module does not change global input settings at runtime. The current Apple package targets iOS/iPadOS **15+** and Mac Catalyst with Metal. Its keyboard/pointer guards dating from iOS 13.4 and disconnection notification guards dating from iOS 14 do not lower that package minimum.
+
+## Runnable example and acceptance limits
+
+`example/inputmap.js` is the current action-map demo. The launcher exposes it on Mac only; mobile builds retain touch-ready demos. The source remains usable for external-peripheral testing on mobile.
+
+- A/D, J/L, arrows or gamepad move the character. The last pressed direction wins; releasing it resumes the other held direction.
+- Space or gamepad A jumps. W/I/Up aims upward, including diagonal combinations; S/K/Down crouches.
+- Left canvas click or gamepad X fires. Right/middle mouse bindings are accepted for testing but currently do not trigger actions on Mac; left click is verified by the source's acceptance notes.
+- Escape switches pause/resume action contexts. A separate monitor shows raw key codes/modifiers and existing gamepad buttons, sticks and triggers.
+- Instructions and action feedback occupy separate areas. An overlaid text field and focus button demonstrate native ownership; clicking the canvas after text entry restores game focus, and the first click does not fire. The shared back control returns to the launcher.
+
+Upstream verification commands, run from the module checkout:
+
+```sh
+python3 tests/input-map/run.py
+python3 tests/input-map/uikit.py
+python3 tests/gamepad-fixture/check.py
+node --test tests/example-input/controls.test.js
+```
+
+Resolver regressions test native binding validation, aggregation and transitions. UIKit fixtures exercise production responder methods with renderer/event sinks for focus, raw-key repetition/cancellation and pointer/overlay ownership. GameController fixtures cover receiver fanout, disconnect and action delivery without individual listeners. JavaScript example tests check demo control behavior. Compilation and these fixtures do not establish physical keyboard, mouse, controller or overlay behavior on every supported device; record that acceptance separately.