@maccesar/titools 4.12.0 → 4.13.0

package/README.md

@@ -177,7 +177,7 @@ The knowledge index is based on the latest Titanium SDK documentation. If your p
 | ti-expert    | Architecture and implementation     | Starting point for most tasks           |
 | purgetss     | Utility-first styling               | UI styling and animations               |
 | ti-ui        | UI/UX patterns                      | Complex layouts, ListViews, platform UI |
-| ti-game      | 2D games with the `ti.game` module  | Sprites, physics, collisions, raycasts, pathfinding, text HUDs, particles, camera |
+| ti-game      | 2D games with the `ti.game` module  | Sprites, physics, collisions, raycasts, pathfinding, text HUDs, sprite attachment, particles, camera |
 | ti-api       | Complete Titanium API reference     | Looking up properties, methods, events  |
 | ti-guides    | SDK fundamentals                    | tiapp.xml, Hyperloop, distribution, JDK/Xcode compatibility, release notes |
 | ti-howtos    | Native feature integration          | Location, push, media, platform APIs    |
@@ -439,6 +439,7 @@ When it activates:
 - Raycasts for line of sight, ledge probes and hitscan shots
 - A* pathfinding (`findPath`) around tagged obstacles, feeding native patrol paths (`followPath`) and animation chaining (`play(name, { then })`)
 - Bitmap-font text sprites with native word wrap, and screen-fixed HUDs inside the scene
+- Sprites pinned to other sprites (`attachTo`) — name tags, health bars, shadows, turrets, tracked natively every frame
 - Particle emitters, Verlet ropes, camera follow/zoom/shake/effects, `scrollFactor` parallax, low-latency sound
 - Game-clock timers that obey pause and slow motion, texture `unload()` for level streaming, and what LiveView reloads clean up on their own
 - Drag & drop, pinch, rotate, multitouch controls

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maccesar/titools",
-  "version": "4.12.0",
+  "version": "4.13.0",
   "description": "Titanium SDK skills and agents for AI coding assistants (Claude Code, Gemini CLI, Codex CLI)",
   "main": "lib/index.js",
   "type": "module",

package/skills/purgetss/references/EXAMPLES.md

@@ -20,7 +20,7 @@ Complete examples of common patterns with anti-patterns and correct implementati
   - [`rounded-full` Without Size](#rounded-full-without-size)
   - [Square Brackets for Arbitrary Values](#square-brackets-for-arbitrary-values)
   - [Layout Defaults](#layout-defaults)
-  - [ScrollView Without `content-w-screen` / `content-h-auto`](#scrollview-without-content-w-screen-content-h-auto)
+  - [ScrollView Without `content-w-screen` / `content-h-auto`](#scrollview-without-content-w-screen--content-h-auto)
   - [Deprecated `theme.View.DEFAULT` vs `theme.extend.View`](#deprecated-themeviewdefault-vs-themeextendview)
   - [Quick Reference Table](#quick-reference-table)
 

package/skills/purgetss/references/dynamic-component-creation.md

@@ -12,7 +12,7 @@
 - [Community-Discovered Patterns](#community-discovered-patterns)
 - [Overview](#overview)
 - [Method 1: `$.UI.create()` (Recommended)](#method-1-uicreate-recommended)
-- [Method 2: `Alloy.createStyle()` + `applyProperties()`](#method-2-alloycreatestyle-applyproperties)
+- [Method 2: `Alloy.createStyle()` + `applyProperties()`](#method-2-alloycreatestyle--applyproperties)
 - [Comparison: Which Method to Use?](#comparison-which-method-to-use)
 - [Real-World Examples](#real-world-examples)
 - [Important Notes](#important-notes)

package/skills/purgetss/references/multi-density-images.md

@@ -18,7 +18,7 @@ For the terse flag reference, see the [`images` command reference](./cli-command
 - [Why multi-density?](#why-multi-density)
 - [Quick start](#quick-start)
 - [The `purgetss/images/` convention](#the-purgetssimages-convention)
-- [Source sizes — the 4× master convention](#source-sizes-the-4-master-convention)
+- [Source sizes — the 4× master convention](#source-sizes--the-4-master-convention)
 - [Pinning the output width with `--width`](#pinning-the-output-width-with---width)
 - [The `images:` config section](#the-images-config-section)
 - [Per-file overrides with `images.files`](#per-file-overrides-with-imagesfiles)

package/skills/ti-expert/references/alloy-builtins.md

@@ -6,10 +6,10 @@
 - [Compiler directives](#compiler-directives)
 - [Alloy.Globals](#alloyglobals)
 - [Alloy.CFG](#alloycfg)
-- [Alloy.isTablet / Alloy.isHandheld](#alloyistablet-alloyishandheld)
-- [$.args , controller arguments](#args-controller-arguments)
-- [Alloy.createController / Alloy.createWidget](#alloycreatecontroller-alloycreatewidget)
-- [Alloy.createModel / Alloy.createCollection](#alloycreatemodel-alloycreatecollection)
+- [Alloy.isTablet / Alloy.isHandheld](#alloyistablet--alloyishandheld)
+- [$.args , controller arguments](#args--controller-arguments)
+- [Alloy.createController / Alloy.createWidget](#alloycreatecontroller--alloycreatewidget)
+- [Alloy.createModel / Alloy.createCollection](#alloycreatemodel--alloycreatecollection)
 - [Conditional code in XML](#conditional-code-in-xml)
 - [Quick reference](#quick-reference)
 

package/skills/ti-expert/references/alloy-structure.md

@@ -8,7 +8,7 @@
 - [lib/ folder and module require paths](#lib-folder-and-module-require-paths)
 - [Data layer: two approaches](#data-layer-two-approaches)
 - [Controller rules](#controller-rules)
-- [Navigation & cleanup pattern](#navigation-cleanup-pattern)
+- [Navigation & cleanup pattern](#navigation--cleanup-pattern)
 - [i18n and accessibility rules](#i18n-and-accessibility-rules)
 - [Widget structure](#widget-structure)
 - [config.json reference](#configjson-reference)

package/skills/ti-expert/references/code-conventions.md

@@ -7,7 +7,7 @@
 - [ES6+ features (Non-Module)](#es6-features-non-module)
 - [No semicolons](#no-semicolons)
 - [Styling with TSS](#styling-with-tss)
-- [Platform & device modifiers](#platform-device-modifiers)
+- [Platform & device modifiers](#platform--device-modifiers)
 - [applyProperties() pattern](#applyproperties-pattern)
 - [ListView templates](#listview-templates)
 - [Memory cleanup](#memory-cleanup)

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

@@ -8,7 +8,7 @@
 - [Native module wrapper service](#native-module-wrapper-service)
 - [i18n helper](#i18n-helper)
 - [Model with SQL adapter](#model-with-sql-adapter)
-- [Fully styled & accessible view](#fully-styled-accessible-view)
+- [Fully styled & accessible view](#fully-styled--accessible-view)
 - [Cleanup pattern in controller](#cleanup-pattern-in-controller)
 - [Animation usage](#animation-usage)
 - [Complete crud example](#complete-crud-example)

package/skills/ti-game/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: ti-game
-description: "Use when building or reviewing 2D games with the ti.game module for Titanium SDK (Android and iOS) — sprites, sprite sheets, animations, tweens, physics (gravity, solids, carMode drifting, thrust), collision groups, trigger zones, swept AABB, raycast, paths, bitmap text, particles, ropes, camera follow/zoom/shake, parallax, sound, drag & drop, multitouch. AUTO-DETECT: if tiapp.xml declares ti.game or any file calls require('ti.game'), invoke BEFORE writing ANY game code. Also trigger on: game, juego, sprite, spritesheet, platformer, endless runner, top-down, shooter, racer, flappy, breakout, rhythm, cards, puzzle, collision, hitbox, raycast, line of sight, pathfinding, maze, patrol, parallax, particles, HUD, score, game loop, 60 fps, GameView. ti.game is NOT Phaser, Godot or Box2D: you never write a game loop, never move a sprite from setInterval, and several familiar features (tilemap layer, sprite parenting, joystick, gamepads) do not exist yet — check references/roadmap.md before inventing an API."
+description: "Use when building or reviewing 2D games with the ti.game module for Titanium SDK (Android and iOS) — sprites, sprite sheets, animations, tweens, physics (gravity, solids, carMode drifting, thrust), collision groups, trigger zones, swept AABB, raycast, paths, bitmap text, particles, ropes, camera follow/zoom/shake, parallax, sound, drag & drop, multitouch, attached labels, bars and turrets. AUTO-DETECT: if tiapp.xml declares ti.game or any file calls require('ti.game'), invoke BEFORE writing ANY game code. Also trigger on: game, juego, spritesheet, platformer, endless runner, top-down, shooter, racer, flappy, breakout, rhythm, cards, puzzle, hitbox, attachTo, line of sight, pathfinding, maze, patrol, HUD, score, game loop, 60 fps, GameView. ti.game is NOT Phaser, Godot or Box2D: you never write a game loop, never move a sprite from setInterval, and several familiar features (tilemap layer, parent/child transforms, joystick, gamepads) do not exist yet — check references/roadmap.md before inventing an API."
 argument-hint: "[genre or feature]"
 allowed-tools: Read, Grep, Glob, Edit, Write, Bash(node *)
 ---
 
 # ti.game — 2D game engine for Titanium SDK
 
-`ti.game` is a native OpenGL ES 2.0 sprite engine exposed to JavaScript, written and maintained by **Michael Gangolf (m1ga)** — upstream is https://github.com/m1ga/ti.game. This skill tracks upstream `main` as of **2026-08-23**, manifest **`0.4.0`** — that bump is the first in a long run of feature landings (the text engine, `screenFixed`, `swept` collisions, `collisionend`, `followPath`, animation chaining, `raycast`, `findPath`, game-clock timers, `scrollFactor` parallax and the `multiply`/`screen` blend modes all shipped while it still said `0.3.0`), so anything still calling itself 0.3.0 has none of them. The number lags the code in the other direction too: per-axis hitboxes (`hitboxScaleX`/`hitboxScaleY`), text word wrap (`maxWidth`), `unload()` on sheets and fonts, and the LiveView renderer lifecycle all landed on 2026-08-23 with the manifest still at `0.4.0`, so date the build rather than trusting the version. When upstream and any fork disagree, upstream wins. Same JS API on Android and iOS — the iOS side is a class-per-class Obj-C twin of the Android engine.
+`ti.game` is a native OpenGL ES 2.0 sprite engine exposed to JavaScript, written and maintained by **Michael Gangolf (m1ga)** — upstream is https://github.com/m1ga/ti.game. This skill tracks upstream `main` as of **2026-08-26**, manifest **`0.4.0`** — that bump is the first in a long run of feature landings (the text engine, `screenFixed`, `swept` collisions, `collisionend`, `followPath`, animation chaining, `raycast`, `findPath`, game-clock timers, `scrollFactor` parallax and the `multiply`/`screen` blend modes all shipped while it still said `0.3.0`), so anything still calling itself 0.3.0 has none of them. The number lags the code in the other direction too: per-axis hitboxes (`hitboxScaleX`/`hitboxScaleY`), text word wrap (`maxWidth`), `unload()` on sheets and fonts and the LiveView renderer lifecycle (2026-08-23), then sprite attachment (`attachTo`/`detach`, 2026-08-26), all landed with the manifest still at `0.4.0`, so date the build rather than trusting the version. When upstream and any fork disagree, upstream wins. Same JS API on Android and iOS — the iOS side is a class-per-class Obj-C twin of the Android engine.
 
 Works in **both Classic and Alloy** projects. Nothing here depends on PurgeTSS.
 
@@ -33,6 +33,7 @@ The practical consequence, and the single biggest mistake to avoid:
 | Parallax layers under a moving camera | hand-scrolled layers | `scrollFactor` on each layer |
 | Camera that follows the player | timer writing `cameraX` | `gameView.follow(sprite, options)` |
 | A score, a title, a label | `Ti.UI.Label` overlays | `Game.createText({ text, screenFixed: true })` |
+| A name tag, health bar or turret that rides a sprite | a timer copying `owner.x`/`y` onto it | `tag.attachTo(owner, { offsetY: -40 })` |
 | A dialog box that fits the screen | breaking the lines with `\n` after measuring in JS | `maxWidth` on the text sprite |
 | A bullet fast enough to skip past a thin wall | shrinking the time step | `swept: true` on the bullet |
 | To know the player *left* a zone | polling on a timer | the `collisionend` event |
@@ -168,6 +169,8 @@ One long string wraps itself: `maxWidth` breaks lines on word boundaries and re-
 
 `screenFixed: true` works on **any** sprite: `x`/`y` become surface coordinates and camera position, zoom and shake are ignored, while touch still maps back. That is the HUD pattern — the score stays put while the camera follows the player. Without it, text is world-space and scrolls past like scenery (signposts, floating damage numbers).
 
+A label that belongs *on* a moving sprite is neither: `tag.attachTo(hero, { offsetY: -40 })` pins it natively, resolved every frame after physics and before collisions, so it never lags by a frame and needs no JS. It works on any sprite, not just text — health bars, shadows, an invisible hitbox on a body, and with `rotate: true` a turret whose offset swings with the tank. Removing the owner removes what is attached to it. What it does *not* inherit is scale, opacity, visibility or tint — position and rotation only.
+
 Overlaid `Ti.UI.Label` views still work and are still right for anything the engine cannot draw: native inputs, system fonts, accented text the built-in font lacks, scrollable menus. Just do not reach for them for a score any more.
 
 Standard Titanium touch events do not reach the GameView, but ordinary Titanium buttons and views layered on top work normally, and sibling views receive simultaneous pointers — which is how the demos build multitouch d-pads (hold ▶ and press jump at the same time). One caveat from the demos: Android's `touchFeedback` ripple cannot animate over this canvas and spams `RippleDrawable` errors, so on-screen buttons set their own `backgroundColor` on `touchstart`/`touchend`.
@@ -225,4 +228,5 @@ When this skill runs out — a brand-new feature, a demo's exact code, a build q
 8. Is the HUD `Game.createText` with `screenFixed: true`, rather than a stack of overlaid labels?
 9. Does anything travel far enough per frame to tunnel? Give it `swept: true`.
 10. Does a timer drive game logic (spawn waves, AI ticks, respawns)? Move it to `gameView.every`/`after` so it obeys pause and slow motion.
-11. Are you using an API that actually exists? Anything involving tilemaps, sprite parenting, joysticks, gamepads or slopes — check [roadmap.md](references/roadmap.md) first.
+11. Does anything ride on top of a moving sprite — a name tag, a health bar, a turret, a hitbox? `attachTo` pins it natively; a timer copying coordinates is the old workaround.
+12. Are you using an API that actually exists? Anything involving tilemaps, full parent/child transforms, joysticks, gamepads or slopes — check [roadmap.md](references/roadmap.md) first.

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

@@ -1,9 +1,10 @@
 # ti.game API reference
 
-Complete JS surface of `ti.game` as of upstream `main` on 2026-08-23, verified against the module source (`android/src/ti/game/*.java` and `engine/*.java`, mirrored by `ios/Classes/TG*`). Defaults come from the engine fields, not from prose. The manifest reads **`0.4.0`** since 2026-08-20, and that bump matters: the text engine (`createFont`/`createText`), `screenFixed`, `swept`, `collisionend`, `followPath`, animation chaining, `raycast`, `findPath`, the game-clock timers, `scrollFactor` and the `multiply`/`screen` blend modes all landed while the manifest still said `0.3.0`, so a build calling itself 0.3.0 has none of them. The version number is not a feature list either: `hitboxScaleX`/`hitboxScaleY`, text `maxWidth`, `SpriteSheet.unload()`/`Font.unload()` and the LiveView renderer lifecycle all landed on 2026-08-23 with the manifest still at `0.4.0`, so two builds calling themselves 0.4.0 can differ — check the build date, or feature-detect by reading the property **before** ever writing it (`typeof sprite.hitboxScaleX === 'undefined'` means the build predates it). Writing first proves nothing: an unknown property is stored on the Kroll proxy and reads back exactly as it was set.
+Complete JS surface of `ti.game` as of upstream `main` on 2026-08-26, verified against the module source (`android/src/ti/game/*.java` and `engine/*.java`, mirrored by `ios/Classes/TG*`). Defaults come from the engine fields, not from prose. The manifest reads **`0.4.0`** since 2026-08-20, and that bump matters: the text engine (`createFont`/`createText`), `screenFixed`, `swept`, `collisionend`, `followPath`, animation chaining, `raycast`, `findPath`, the game-clock timers, `scrollFactor` and the `multiply`/`screen` blend modes all landed while the manifest still said `0.3.0`, so a build calling itself 0.3.0 has none of them. The version number is not a feature list either: `hitboxScaleX`/`hitboxScaleY`, text `maxWidth`, `SpriteSheet.unload()`/`Font.unload()`, the LiveView renderer lifecycle (all 2026-08-23) and `attachTo`/`detach` (2026-08-26) landed with the manifest still at `0.4.0`, so two builds calling themselves 0.4.0 can differ — check the build date, or feature-detect by reading the property **before** ever writing it (`typeof sprite.hitboxScaleX === 'undefined'` means the build predates it). Writing first proves nothing: an unknown property is stored on the Kroll proxy and reads back exactly as it was set. Methods are the reliable probe — `typeof sprite.attachTo === 'function'` cannot be faked by a previous write.
 
 Every property listed is **live**: reading returns the current native value, even mid-drag or mid-tween. Every property can also be passed to its `create*` factory. All durations crossing the JS boundary are **milliseconds** (the engine converts to seconds internally).
 
+<!-- TOC-START -->
 ## Contents
 
 - [Module](#module)
@@ -18,6 +19,8 @@ Every property listed is **live**: reading returns the current native value, eve
 - [Events at a glance](#events-at-a-glance)
 - [Gotchas the property tables do not show](#gotchas-the-property-tables-do-not-show)
 
+<!-- TOC-END -->
+
 ## Module
 
 ```javascript
@@ -44,8 +47,8 @@ A normal Titanium view — add it to a window or any container, size it with the
 | Member | Type | Default | Notes |
 | --- | --- | --- | --- |
 | `add(object)` / `add([objects])` | method | — | Accepts Sprite, Emitter or Rope. An array crosses the bridge once and is committed under a single native scene lock — build a level into an array and add it in one call |
-| `remove(object)` | method | — | Remove one object from the scene |
-| `removeAllSprites()` | method | — | Clear the whole scene |
+| `remove(object)` | method | — | Remove one object from the scene — **and, recursively, every sprite attached to it** (see [Attachment](#attachment)) |
+| `removeAllSprites()` | method | — | Clear the whole scene, dropping every attachment with it |
 | `pause()` / `resume()` | method | — | Render loop control. The activity/app lifecycle already pauses and resumes automatically |
 | `backgroundColor` | string | — | GL clear color |
 | `maxFps` | int | `0` | Frame cap. `60` stops 120 Hz ProMotion displays from doubling render work; `0` = display refresh rate |
@@ -86,6 +89,8 @@ Vertical follow is always on. **Horizontal follow is off until you pass `leftMar
 
 Each call **resets every option to its default** before applying what you passed. Calling `follow(sprite)` with no options after configuring it wipes the configuration.
 
+Anything that is not a sprite — `null`, a plain object, a number — clears the follow instead of throwing, which is also what `stopFollow()` does. Since 2026-08-26 that is guaranteed on Android too: the binding takes an untyped argument and checks the type itself, because a typed proxy parameter aborts the whole app on the JNI type check when JS sends a plain object (it crosses as a `HashMap`). Passing an options dict where the sprite goes now silently stops the camera rather than killing the process — a real behaviour difference from older builds.
+
 ### `findPath(from, to, options)`
 
 | Option | Default | Effect |
@@ -120,7 +125,7 @@ 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 interior frame UVs by half a texel so magnified edges cannot sample the neighbouring frame; outer edges keep the exact 0..1 range so `tileRepeat` still wraps. Atlas frames come from the JSON untouched |
+| `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 |
 
 | Member | Notes |
@@ -261,9 +266,39 @@ Every sprite gets its own phase, and the wobble unwinds exactly when disabled. T
 | `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 |
+| `attachTo(target, options)` | Pin this sprite to another one natively — see [Attachment](#attachment) below. `options`: `offsetX`, `offsetY` (both `0`), `rotate` (`false`). `attachTo(null)` detaches |
+| `detach()` | Release the sprite where it is; `x`/`y` are writable again |
 
 `animate()` accepts exactly these keys — anything else is silently ignored: `x`, `y`, `scale`, `scaleX`, `scaleY`, `rotation`, `opacity`, `glowOpacity`, `duration` (ms), `delay` (ms), `easing`, `frame` (the sheet frame to set once the tween finishes). Re-calling `animate` from the `complete` handler is still how a ping-pong or a blink is built (there is no `repeat`/`yoyo` yet), but a fixed route is now `followPath` instead of a chain of tween legs.
 
+### Attachment
+
+Added 2026-08-26. `sprite.attachTo(target, { offsetX, offsetY, rotate })` pins a sprite to another sprite natively: every frame the engine writes the sprite's `x`/`y` from the target's **final** position plus the offset, with no per-frame JS. Name tags, health bars, shadows, turrets, a hitbox that must sit on a moving body.
+
+```javascript
+const tag = Game.createText({ text: 'PLAYER 1', zIndex: 6 });
+tag.attachTo(hero, { offsetY: -40 });   // 40 px above the hero's anchor
+gameView.add(tag);                      // still has to be in the scene
+```
+
+| Member | Notes |
+| --- | --- |
+| `attachTo(target, options)` | `options.offsetX` / `offsetY` (default `0`) are in the **attached sprite's** own coordinate space. `options.rotate` (default `false`) copies the target's `rotation` onto the sprite each frame *and* swings the offset around the target — a turret or a hat. Left `false`, the sprite stays upright while the target spins. Every call replaces the previous offset and flag; there is no partial update |
+| `detach()` | Stops the pinning, leaving the sprite where it was. Same as `attachTo(null)` |
+| `attachedTo` | **Read-only** property: the target sprite, or `null`. Setting it does nothing (it is a getter — the write lands on the Kroll proxy and is never read back by the engine) |
+
+Where it runs in the frame, and why it matters: after physics integration and solid resolution, before collision checks. So a tag never trails its owner by a frame — including an owner riding a moving platform — and an attached invisible hitbox is tested at the position it was just moved to, not the previous one.
+
+The rest of the contract, all read from the engine:
+
+- **The attached sprite must be in the scene** (`gameView.add(...)`). The pass iterates the scene's sprite list; a sprite that was never added is never repositioned. So is one whose *target* is not in the scene — it simply freezes where it stands.
+- **While attached, position is not yours.** Direct `x`/`y` writes, `velocityX`/`velocityY`, gravity and position tweens still run, and are then overwritten the same frame. `detach()` first if the sprite has to move on its own.
+- **A drag outranks the attachment.** While a finger holds the sprite (`draggable: true`, past the touch slop) the pinning is skipped, exactly as it is for a rider on a moving platform, and resumes when the finger lifts.
+- **Chains work**: attach a hat to a tag attached to a hero. Parents resolve first through recursion, with a depth cap of 8 that breaks accidental cycles — beyond eight links the far ancestor is not re-resolved that frame and the chain lags instead of hanging. Attaching a sprite to itself is ignored.
+- **Cross-space attach converts automatically.** A `screenFixed` sprite attached to a world sprite (or the reverse) has the target's position mapped through the camera first, so the offset stays in the sprite's own units.
+- **Removing the target removes everything attached to it**, recursively — a tag never outlives its owner, and a chain goes with it. `detach()` first to keep one alive. `removeAllSprites()` clears every attachment as it empties the scene.
+- **A non-sprite target detaches** instead of crashing (Android logs a warning; iOS is silent). Like `follow()`, the binding takes an untyped argument on purpose — a typed proxy parameter aborts the app on the JNI type check when JS sends a plain object.
+
 ### Sprite events
 
 | Event | Payload | Fires |
@@ -477,4 +512,9 @@ There is `collision` (enter) and `collisionend` (exit), but deliberately **no**
 - **Game-clock timers are not `setTimeout`.** `after`/`every` freeze at `timeScale: 0` and pause with the render loop — which is why spawn waves belong there — but a pause menu that needs a real countdown still needs `setTimeout`.
 - **`screenFixed` beats `scrollFactor`.** Setting both leaves the sprite screen-fixed; the parallax offset is skipped entirely.
 - **Ghost lines along a frame's edge are a filtering artifact, not bad art.** A magnified `smoothing: true` sheet samples past the frame border — 1px seams, or the next row's heads at the bottom. Grid sheets have inset UVs upstream since 2026-08-19; an atlas needs padding and extrude at pack time, and an older module build needs either `smoothing: false` or a rebuild.
+- **An animation that rocks side to side on a smoothed grid sheet dates the build.** Until 2026-08-24 the inset was applied only to the edge facing a neighbour, so the first and last frame of a strip came out half a texel wider than the rest with their centres a quarter texel to opposite sides — a cycle through them wobbles, most visibly on hard-edged art. Fixed by insetting both edges of any multi-frame axis. Unreachable with `smoothing: false`, which is why it went unnoticed for so long: check the build date before redrawing the art.
+- **An attached sprite matches its target's world `x`/`y`, not where the target is *drawn*.** Give the attachment the same `scrollFactor` as its target, or a tag on a parallax sprite drifts off it as the camera travels — the two are pinned in world space and then drawn at different offsets.
+- **A cross-space attachment is converted with the camera from the previous frame.** Attachments are applied before the camera update, so a `screenFixed` tag on a world sprite (or the reverse) lags by one frame while the camera is moving. Same-space attachments — the normal case — are exact.
+- **Removing a sprite removes everything attached to it.** Pooling the owner with `visible = false` does not, but `gameView.remove(owner)` takes the tag, the health bar and anything chained off them. `detach()` first to keep one.
+- **`attachedTo` is read-only.** Assigning to it stores a value on the proxy that the engine never reads — use `attachTo()` / `detach()`.
 - **`scrollFactor` does not move the sprite.** It shifts where the sprite is *drawn* and maps touch back to match. `x`, `y`, physics and collisions stay in world coordinates, so a `scrollFactor: 0.5` platform still collides where its world `x` says, not where it looks.

package/skills/ti-game/references/project-setup.md

@@ -2,6 +2,7 @@
 
 Installing the module, wiring it into Classic and Alloy projects, organizing art and sound, and the lifecycle work the engine does not do for you.
 
+<!-- TOC-START -->
 ## Contents
 
 - [Install the module](#install-the-module)
@@ -14,6 +15,8 @@ Installing the module, wiring it into Classic and Alloy projects, organizing art
 - [Debugging and tuning](#debugging-and-tuning)
 - [Platform differences](#platform-differences)
 
+<!-- TOC-END -->
+
 ## Install the module
 
 There is no registry and no `ti module install` command — Titanium modules are zips you drop into a project. Grab the platform zips from the module's `dist/` folders (or build them yourself) and put them where the CLI looks:
@@ -49,8 +52,10 @@ Pinning `version` is worth the extra attribute: with two module versions install
 | `0.3.0` before 2026-08-19 | also `followPath`, `play(name, { then })`, `raycast`, `after`/`every`, `scrollFactor`, `multiply`/`screen` blends |
 | `0.3.0` before 2026-08-19 16:00 UTC+2 | additionally bleeds at grid-frame edges on smoothed sheets |
 | `0.4.0` — including the 2026-08-20 release zip | `hitboxScaleX`/`hitboxScaleY`, text `maxWidth`, `SpriteSheet.unload()`/`Font.unload()` and the LiveView renderer lifecycle, all added on 2026-08-23 with the manifest untouched |
+| `0.4.0` built before 2026-08-24 | additionally rocks side to side through a multi-frame animation on a `smoothing: true` grid sheet — the half-texel inset was one-sided, so the end frames came out slightly wider and off-centre |
+| `0.4.0` built before 2026-08-26 | additionally `sprite.attachTo()` / `detach()` / `attachedTo`, and `gameView.follow()` still aborts the app on Android if it is handed anything that is not a sprite |
 
-The published releases are pre-releases and lag `main`: the newest one is `0.4.0` (2026-08-20). If a call that this skill documents is `undefined` at runtime, check the manifest version *and the build date* before hunting for a typo, and rebuild from upstream `main`. More reliable than either is feature-detecting in code: read the property **before** ever writing it (`typeof sprite.hitboxScaleX === 'undefined'` means the build predates it). Write-then-read always says yes, because an unknown property is stored on the Kroll proxy and reads back exactly as it was set.
+The published releases are pre-releases and lag `main`: the newest one is `0.4.0` (2026-08-20). If a call that this skill documents is `undefined` at runtime, check the manifest version *and the build date* before hunting for a typo, and rebuild from upstream `main`. More reliable than either is feature-detecting in code: read the property **before** ever writing it (`typeof sprite.hitboxScaleX === 'undefined'` means the build predates it). Write-then-read always says yes, because an unknown property is stored on the Kroll proxy and reads back exactly as it was set. A method has no such trap — `typeof sprite.attachTo === 'function'` is a clean probe whatever the app did earlier.
 
 Building the module from source:
 
@@ -62,7 +67,7 @@ ti build -p ios --build-only        # macOS only → ios/dist/ti.game-iphone-<ve
 
 ## Classic projects
 
-`require('ti.game')` anywhere and add the GameView to a window. The 24 demos in the module's `example/` folder are Classic, each one a CommonJS module exporting a start function:
+`require('ti.game')` anywhere and add the GameView to a window. The 26 demos in the module's `example/` folder are Classic, each one a CommonJS module exporting a start function (`app.js` is the launcher, not a demo):
 
 ```javascript
 // Resources/flappy.js
@@ -228,7 +233,7 @@ Practical rules:
 - **One sheet per scene if you can manage it.** Sprites sharing a texture batch into a single draw call. The endless-runner demo even draws its crash burst from the *player's* sheet to keep the whole scene on one texture.
 - **`smoothing: false` for pixel art.** Combine with `pixelSnap: true` on moving sprites when the texel phase must stay stable.
 - **Ship sheets as PNG, not JPG.** JPEG has no alpha channel, so every frame comes back on an opaque block, and its compression smears colour across frame borders — exactly where a sheet can least afford it. The module's own `basic.js` demo was converted from `hero.jpg` to `hero.png` on 2026-08-19 for this reason.
-- **Edge bleeding on a smoothed grid is fixed upstream, on grids only.** Linear filtering samples past a frame's edge when the sprite is magnified, which shows up as 1px ghost lines or the next row's heads peeking in at the bottom. Since 2026-08-19 a grid sheet with `smoothing: true` pulls its *interior* frame edges in by half a texel automatically; outer edges stay at the texture border, so full-texture `tileRepeat` frames still wrap seamlessly, and `smoothing: false` sheets skip the inset entirely (NEAREST cannot bleed, and pixel art at 1:1 needs exact UVs). **Atlas sheets are not covered** — their UVs come straight from the JSON, so prevent bleeding when packing instead: 2px padding and extrude in TexturePacker.
+- **Edge bleeding on a smoothed grid is fixed upstream, on grids only.** Linear filtering samples past a frame's edge when the sprite is magnified, which shows up as 1px ghost lines or the next row's heads peeking in at the bottom. Since 2026-08-19 a grid sheet with `smoothing: true` pulls its frame edges in by half a texel automatically, and since 2026-08-24 it does so on **both** edges of any axis that holds more than one frame — the first version inset only the side facing a neighbour, which left the end frames of a strip half a texel wider than the rest and their centres a quarter texel off, so an animation cycling through them visibly rocked. An axis with a single frame keeps the exact texture border, so full-texture `tileRepeat` frames still wrap seamlessly, and `smoothing: false` sheets skip the inset entirely (NEAREST cannot bleed, and pixel art at 1:1 needs exact UVs). **Atlas sheets are not covered** — their UVs come straight from the JSON, so prevent bleeding when packing instead: 2px padding and extrude in TexturePacker.
 - **`repeat: true` for tiling.** Required by sprites using `tileRepeat`, and it needs power-of-two texture dimensions on ES 2.0 — a 512×64 street strip tiles, a 500×60 one does not.
 - **White art plus `tint`** covers every color variant of a particle or effect with one small texture.
 

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

@@ -2,28 +2,31 @@
 
 Working patterns distilled from the 26 official demos in `example/` and from a shipped Alloy game (Titanium Lander). Each recipe shows the part that is specific to the genre; the shared scaffolding is in [The scaffolding](#the-scaffolding) and is not repeated.
 
-Every snippet uses only API that exists in upstream `main` at `df66122`, 2026-08-23 (manifest `0.4.0`, unchanged since 2026-08-20 — the version number stopped tracking the code). Check [roadmap.md](roadmap.md) before reaching for anything not shown here.
+Every snippet uses only API that exists in upstream `main` at `201bcf9`, 2026-08-26 (manifest `0.4.0`, unchanged since 2026-08-20 — the version number stopped tracking the code). Check [roadmap.md](roadmap.md) before reaching for anything not shown here.
 
+<!-- TOC-START -->
 ## Contents
 
 - [The 26 demos, and what each one is the reference for](#the-26-demos-and-what-each-one-is-the-reference-for)
 - [The scaffolding](#the-scaffolding)
-- [Cross-cutting patterns](#cross-cutting-patterns) — pooling, freeing textures, parallax, multitouch controls, HUD text, wrapped dialog, invisible triggers, seeing the hitbox, enter/exit zones, patrol routes, line of sight, pathfinding, game-clock timers, hit-stop
-- [Tap-to-flap](#tap-to-flap) (`flappy.js`)
-- [Platformer](#platformer) (`platformer.js`)
-- [Top-down / Zelda](#top-down--zelda) (`topdown.js`)
-- [Top-down racer](#top-down-racer) (`racing.js`)
-- [Asteroids / space shooter](#asteroids--space-shooter) (`asteroids.js`)
+- [Cross-cutting patterns](#cross-cutting-patterns)
+- [Tap-to-flap](#tap-to-flap)
+- [Platformer](#platformer)
+- [Top-down / Zelda](#top-down--zelda)
+- [Top-down racer](#top-down-racer)
+- [Asteroids / space shooter](#asteroids--space-shooter)
 - [Lunar lander](#lunar-lander)
-- [Endless runner](#endless-runner) (`skate.js`)
-- [Rhythm game](#rhythm-game) (`rhythm.js`)
-- [Ball sports / breakout physics](#ball-sports--breakout-physics) (`volley.js`)
-- [Cards and board games](#cards-and-board-games) (`cards.js`, `puzzle.js`)
-- [Point & click adventure](#point--click-adventure) (`pointclick.js`, `maze.js`)
-- [Particles](#particles) (`particles.js`)
-- [Ropes and chains](#ropes-and-chains) (`rope.js`)
-- [Camera work](#camera-work) (`camera.js`)
-- [Visual effects](#visual-effects) (`blend.js`, `flip.js`, `timescale.js`, `demoscene.js`)
+- [Endless runner](#endless-runner)
+- [Rhythm game](#rhythm-game)
+- [Ball sports / breakout physics](#ball-sports--breakout-physics)
+- [Cards and board games](#cards-and-board-games)
+- [Point & click adventure](#point--click-adventure)
+- [Particles](#particles)
+- [Ropes and chains](#ropes-and-chains)
+- [Camera work](#camera-work)
+- [Visual effects](#visual-effects)
+
+<!-- TOC-END -->
 
 ## The 26 demos, and what each one is the reference for
 
@@ -49,7 +52,7 @@ Every snippet uses only API that exists in upstream `main` at `df66122`, 2026-08
 | `flip.js` | `flipX`/`flipY` driven by movement; tap inverts gravity | [Visual effects](#visual-effects) |
 | `hitbox.js` | `debug: true` overlays, and why the per-axis hitbox scales exist | [Seeing the hitbox](#seeing-the-hitbox--hitboxjs) |
 | `blend.js` | The four blend modes side by side, `flash()` variants | [Visual effects](#visual-effects) |
-| `text.js` | Screen-fixed HUD, world-space labels, text buttons, wrapped dialog | [HUD](#hud--textjs-flappyjs) |
+| `text.js` | Screen-fixed HUD, world-space labels, text buttons, wrapped dialog, a name tag pinned with `attachTo` | [HUD](#hud--textjs-flappyjs), [Labels pinned to a sprite](#labels-bars-and-turrets-pinned-to-a-sprite--attachto-textjs) |
 | `swept.js` | `swept: true` vs tunneling, same bullets, rising speed | [Object pooling](#object-pooling) |
 | `path.js` | Smoothed circuits, sharp patrols, `play(name, { then })` chains | [Patrol routes and animation chains](#patrol-routes-and-animation-chains--pathjs) |
 | `raycast.js` | Line of sight, ledge probes, tap-fired hitscan | [Line of sight, ledge probes and hitscan](#line-of-sight-ledge-probes-and-hitscan--raycastjs) |
@@ -111,6 +114,8 @@ Sizing everything as a fraction of `W`/`H` is not cosmetic — a jump tuned in a
 
 ## Cross-cutting patterns
 
+The pieces every genre below reuses: pooling, freeing a level's textures, parallax, multitouch controls, HUD text, wrapped dialog, labels and bars attached to a sprite, invisible triggers, seeing the hitbox, enter/exit zones, patrol routes, line of sight, pathfinding, game-clock timers and hit-stop.
+
 ### Object pooling
 
 Create a fixed set once, recycle forever. `visible = false` also removes the sprite from collision, which is what makes this work.
@@ -337,6 +342,46 @@ dialog.addEventListener('tap', () => {
 
 Overlaid `Ti.UI.Label` views remain the answer for text the engine's font cannot draw (accents, system fonts, right-to-left) and for real UI: menus, dialogs, text inputs.
 
+### Labels, bars and turrets pinned to a sprite — `attachTo`, `text.js`
+
+A HUD is `screenFixed`; a name tag, a health bar or a shadow is the opposite — it belongs *on* a sprite that moves. `attachTo` is the native version of the JS everyone wrote before it: a timer copying `owner.x` into `tag.x`, one bridge round trip per tag per tick, and always a frame behind.
+
+```javascript
+const tag = Game.createText({ text: 'THE BALL', scale: UNIT, tintColor: '#7fd4ff', zIndex: 6 });
+tag.attachTo(ball, { offsetY: -(W * 0.09) });   // offset in the tag's own units
+gameView.add(tag);                              // the tag is still a scene sprite
+```
+
+The tag now tracks the ball through gravity, tweens, a moving platform and a finger drag, with no JS in the loop, and disappears with it — `gameView.remove(ball)` removes everything attached to the ball, recursively.
+
+A health bar is the same idea with two sprites, and shows what `attachTo` does *not* do:
+
+```javascript
+// blockSheet is any small opaque texture stretched and tinted — a sheet-less
+// sprite draws nothing at all, that is the invisible-trigger idiom below
+const barBack = Game.createSprite({ sheet: blockSheet, width: 40, height: 5, zIndex: 5, tintColor: '#222' });
+const barFill = Game.createSprite({ sheet: blockSheet, width: 40, height: 5, zIndex: 6, anchorX: 0, tintColor: '#3f6' });
+
+barBack.attachTo(hero, { offsetY: -34 });
+barFill.attachTo(hero, { offsetX: -20, offsetY: -34 });   // anchorX 0 → grows to the right
+gameView.add([barBack, barFill]);
+
+// on damage: only the width changes — scale, opacity and visibility are not inherited
+barFill.width = 40 * (hp / hpMax);
+```
+
+`rotate: true` is the other half: the offset swings around the target and the sprite copies its rotation, which is what a turret on a tank or a hat on a tumbling hero needs.
+
+```javascript
+turret.attachTo(tank, { offsetY: -12, rotate: true });
+```
+
+Three things to keep in mind:
+
+- **The attached sprite has to be added to the scene**, and so does its target. Neither pins otherwise — the sprite just sits at whatever `x`/`y` it was created with.
+- **Its position stops being yours.** Velocity, gravity and `animate({ x })` still run and are overwritten the same frame. To fling a tag off a dying enemy, `detach()` first, then give it velocity.
+- **Match `scrollFactor` between the two.** Attachment pins world coordinates; parallax changes only where a sprite is *drawn*. A tag at `scrollFactor: 1` on a background sprite at `0.5` stays pinned in world space and drifts across the screen anyway.
+
 ### Invisible triggers
 
 A sprite with `width`/`height` and no `sheet` renders nothing but still collides. This is how scores, goals, ceilings, kill floors, walls and checkpoints are built.

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

@@ -1,6 +1,6 @@
 # What does not exist yet — and what to do instead
 
-The most expensive mistake with `ti.game` is writing code against a feature that sounds like it should be there because Phaser, Godot or Cocos has it. This file is the guard rail: everything below is **absent from upstream `main` as of 2026-08-23** (`df66122`, manifest `0.4.0`), with the workaround that is idiomatic today.
+The most expensive mistake with `ti.game` is writing code against a feature that sounds like it should be there because Phaser, Godot or Cocos has it. This file is the guard rail: everything below is **absent from upstream `main` as of 2026-08-26** (`201bcf9`, manifest `0.4.0`), with the workaround that is idiomatic today.
 
 Planned items come from the module's `TODO.md`. Planned is not shipped — when a game needs one of these, use the workaround and keep the code isolated enough to swap later.
 
@@ -9,7 +9,7 @@ Planned items come from the module's `TODO.md`. Planned is not shipped — when
 | You might reach for | Status | What to do now |
 | --- | --- | --- |
 | A tilemap layer, Tiled JSON import, collision layer | Planned (priority 4) | One sprite per tile. Fine at 12×15, dead at 200×200. For large ground planes use a single `tileRepeat` sprite instead of a grid, and add sparse invisible solids for collision. `findPath` already rasterizes those per-tile sprites, so a tile maze pathfinds today — the planned collision layer is meant to feed the same grid |
-| `sprite.parent`, attaching a turret to a tank, a hat to a hero, multi-part bosses | Planned (priority 7), the biggest structural item | Move the parts together from JS on the same coarse tick, or bake the combination into sheet frames. There is no transform inheritance |
+| `sprite.parent` and full transform inheritance — a child that scales, fades and flips with its parent | Partly shipped, the rest still planned (priority 7) | **Position and rotation are done**: `attachTo(target, { offsetX, offsetY, rotate })` pins a sprite to another natively, chains included, so turrets, hats, name tags and health bars need no JS. What is *not* inherited is everything else — `scale`, `opacity`, `visible`, `flipX`/`flipY`, `tintColor` — and there is no `parent` property, no hit-test or `ySort` integration. Set those on each part yourself, on the coarse tick that changes them |
 | `gameView.panTo(x, y, { duration, easing })` for a cutscene camera move | Planned (priority 1) | `follow()` an invisible sprite and tween that sprite, then `follow()` the player again |
 | Ping-pong animation playback, a per-sprite animation speed multiplier, a random start offset | Planned (priority 9) | Author the ping-pong into the sheet as a longer animation. Desync a field of torches by giving each one its own `idleAnimation` timing, or start them from staggered timers |
 | Native virtual joystick or d-pad bound to a sprite | Planned (priority 6) | Overlaid Titanium views, one per button, writing `velocityX`/`steering`/`throttle` on `touchstart`/`touchend`. Sibling views get simultaneous pointers, so multitouch works |
@@ -60,7 +60,8 @@ Recent additions that are easy to miss and easy to reimplement badly in JS:
 - **`hitboxScaleX` / `hitboxScaleY`** (2026-08-23): per-axis corrections multiplied on top of `hitboxScale`, for art that fills its frame by a different fraction on each axis. The old workaround — settling for one compromise scale, or padding the frame so a single number fits — is obsolete.
 - **`spriteSheet.unload()` / `font.unload()`** (2026-08-23): frees a GL texture on the next frame instead of holding it until the context dies. Level streaming no longer needs a fresh window to reclaim GPU memory. Permanent — it is not a cache eviction.
 - **LiveView reloads retire the previous generation** (2026-08-23): stale render loops, the old `SoundPool`, `MediaPlayer`s and audio proxies are shut down by the module itself. Do not write your own reload guard, and do not read a scene stuttering after several reloads as an engine limit — it dates the build.
+- **`sprite.attachTo(target, { offsetX, offsetY, rotate })` / `detach()`** (2026-08-26): a sprite pinned to another sprite, resolved natively after physics and before collisions. Name tags, health bars, shadows, turrets and hitboxes that must sit on a moving body stop needing a per-frame JS copy of `x`/`y` — which is what everyone wrote before, one bridge round trip per tag per tick, always a frame late. Chains, `rotate: true` for an offset that swings with the target, automatic conversion between world and `screenFixed` space, and recursive removal so a tag never outlives its owner. It is not full parenting: only position and rotation are inherited.
 
 ## Checking the current state
 
-This file describes upstream `main` at `df66122` on 2026-08-23 — a moving target: thirteen items on this list shipped within a week of the skill being written, four of them in a single day, and the manifest tracks none of it precisely (`0.3.0` → `0.4.0` on 2026-08-20, after nine of them; word wrap, the per-axis hitbox, `unload()` and the LiveView lifecycle all landed on 2026-08-23 with the number unchanged). Before relying on any "planned" item being still absent — or on a workaround still being necessary — read `TODO.md` and `README.md` at https://github.com/m1ga/ti.game, the module's upstream repo. `README.md` there is the canonical API documentation; the `documentation/` folder only points at it. The priorities quoted above are the maintainer's, not a roadmap this skill decides.
+This file describes upstream `main` at `201bcf9` on 2026-08-26 — a moving target: fourteen items on this list shipped within ten days of the skill being written, four of them in a single day, and the manifest tracks none of it precisely (`0.3.0` → `0.4.0` on 2026-08-20, after nine of them; word wrap, the per-axis hitbox, `unload()` and the LiveView lifecycle landed on 2026-08-23 and `attachTo` on 2026-08-26, all with the number unchanged). `attachTo` is also the first entry to move *out* of the "not available" table rather than simply appearing in the shipped list — a planned item can land partly done, so read what it does not cover before treating the whole row as solved. Before relying on any "planned" item being still absent — or on a workaround still being necessary — read `TODO.md` and `README.md` at https://github.com/m1ga/ti.game, the module's upstream repo. `README.md` there is the canonical API documentation; the `documentation/` folder only points at it. The priorities quoted above are the maintainer's, not a roadmap this skill decides.