@maccesar/titools 5.1.1 → 5.2.0

package/README.md

@@ -6,7 +6,7 @@
 
 </div>
 
-TiTools is a Titanium SDK toolkit for AI coding assistants. It ships 11 skills — 6 specialist skills (`ti-reuse-first`, `ti-expert`, `purgetss`, `ti-ui`, `ti-game`, `ti-synthengine`) plus 5 documentation-mirror skills (`ti-api`, `ti-guides`, `ti-howtos`, `alloy-guides`, `alloy-howtos`) — a research agent, and reference files covering reuse and simplification, Titanium architecture, API reference, native how-tos, Alloy MVC, PurgeTSS styling and resource automation, UI/UX patterns, 2D games, and native sound synthesis.
+TiTools is a Titanium SDK toolkit for AI coding assistants. It ships 13 skills — 8 specialist skills (`ti-reuse-first`, `ti-expert`, `purgetss`, `ti-ui`, `ti-game`, `ti-game-assets`, `ti-synthengine`, `ti-admob-unified`) plus 5 documentation-mirror skills (`ti-api`, `ti-guides`, `ti-howtos`, `alloy-guides`, `alloy-howtos`) — a research agent, and reference files covering reuse and simplification, Titanium architecture, API reference, native how-tos, Alloy MVC, PurgeTSS styling and resource automation, UI/UX patterns, 2D games, and native sound synthesis.
 
 The reference files are maintained against official documentation whenever an official source exists, so the assistant can retrieve current framework behavior instead of guessing from generic training data. As of v5.0.0 those sources are the Titanium SDK's own API definitions and the rewritten guides at [titaniumsdk.com](https://titaniumsdk.com). [Where the references come from](#where-the-references-come-from) has the detail.
 
@@ -36,7 +36,7 @@ The fastest way to get started with Claude Code. One command to add the marketpl
 ```
 
 What you get:
-- All 11 TiTools skills (`ti-reuse-first`, `ti-expert`, `purgetss`, `ti-ui`, `ti-game`, `ti-synthengine`, `ti-api`, `ti-guides`, `ti-howtos`, `alloy-guides`, `alloy-howtos`)
+- All 13 TiTools skills (`ti-reuse-first`, `ti-expert`, `purgetss`, `ti-ui`, `ti-game`, `ti-game-assets`, `ti-synthengine`, `ti-admob-unified`, `ti-api`, `ti-guides`, `ti-howtos`, `alloy-guides`, `alloy-howtos`)
 - ti-pro research agent
 - Session hook that auto-detects Titanium projects (`tiapp.xml`, Alloy, PurgeTSS, `ti.game`, `ti.synthengine`)
 - Slash commands: `/ti-check`, `/ti-new-screen`, `/ti-audit`
@@ -70,7 +70,7 @@ claude   # or gemini, or codex
 ```
 
 What gets installed:
-- The 10 TiTools skills to `~/.agents/skills/`
+- The 13 TiTools skills to `~/.agents/skills/`
 - ti-pro agent for Claude Code
 - Platform symlinks for Claude Code (Gemini CLI and Codex CLI auto-discover from `~/.agents/skills/` — no symlinks needed)
 - Knowledge index in your project's `AGENTS.md`/`CLAUDE.md`/`GEMINI.md`
@@ -179,7 +179,9 @@ The knowledge index is based on the latest Titanium SDK documentation. If your p
 | purgetss     | Alloy styling + asset automation    | Utility classes; Alloy/Classic branding, images, colors, fonts and modules |
 | ti-ui        | UI/UX patterns                      | Complex layouts, ListViews, platform UI |
 | ti-game      | 2D games with the `ti.game` module  | Sprites, physics, tile layers, wall jumps, pathfinding, text/performance HUDs, particles, camera |
-| ti-synthengine | Sound design with `ti.synthengine` | Tones, chords, retro/UI effects, alarms, sweeps, patterns, mixing and troubleshooting |
+| ti-game-assets | Visual and sound assets | Image generation/editing, synthesis variants, stereo placement, alpha cleanup, manifests, parallax and complete exports |
+| ti-synthengine | Sound design with `ti.synthengine` | Tones, chords, retro/UI effects, alarms, sweeps, patterns, ADSR envelopes, resonant filters, FM, detune, binaural positioning, engine statistics, mixing and troubleshooting |
+| ti-admob-unified | Advertising, privacy and mediation | Official `ti.admob.unified` guides, copy-ready library, banners/fullscreen, UMP/ATT and selected-provider configuration |
 | 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    |
@@ -187,10 +189,11 @@ The knowledge index is based on the latest Titanium SDK documentation. If your p
 | alloy-howtos | Alloy CLI, configuration, debugging | alloy.jmk, config.json, custom XML tags |
 
 Notes:
-- The first six (`ti-reuse-first`, `ti-expert`, `purgetss`, `ti-ui`, `ti-game`, `ti-synthengine`) are specialist workflow skills reflecting TiTools' Titanium conventions and native-module contracts.
+- The first eight (`ti-reuse-first`, `ti-expert`, `purgetss`, `ti-ui`, `ti-game`, `ti-game-assets`, `ti-synthengine`, `ti-admob-unified`) are specialist workflow skills reflecting TiTools' Titanium conventions and native-module contracts.
 - `ti-reuse-first` runs before the others. It asks whether a thing needs to exist and what already does it — a search order that stops at the first rung that holds — and sweeps an existing `app/` for near-identical controllers, single-listener events, wrappers around one call, and layout recomputed in JavaScript. It is deliberately two-sided: it says when adding a module or a Widget is the right answer, so the bias does not simply invert.
 - `ti-game` documents the `ti.game` native module (2D sprite engine on OpenGL ES 2.0, Android and iOS). Its API reference was verified against the module source and tracks upstream `main` (the module ships features ahead of its manifest version); it applies to Alloy and Classic projects alike and does not depend on PurgeTSS.
-- `ti-synthengine` translates aesthetic sound requests into strict, production-ready JavaScript for the cross-platform `ti.synthengine` 1.0.0 module. Seven references preserve the official documentation and an eighth adds curated retro, xylophone, memory-pad, polyphony and timer-ownership recipes; the API contract was cross-checked against both native implementations.
+- `ti-synthengine` translates aesthetic sound requests into strict, production-ready JavaScript for the cross-platform `ti.synthengine` 1.0.0 beta module. Eight references preserve official documentation, accompanied by raw statistics benchmark trials; curated recipes add retro effects, xylophone interaction, memory pads, polyphony and timer ownership. The reviewed source includes eleven public methods with optional diagnostics; feature detection remains necessary for older beta binaries. Maintenance notes and a hash manifest distinguish the reviewed working tree from its base commit and published packages, track preserved navigation and state audit limits.
+- `ti-game-assets` treats images and sounds as essential game assets. It coordinates integrated `image_gen` artwork with `ti-synthengine` sound design, variants and stereo placement, and ships Pillow helpers for conservative alpha cleanup and per-world visual/audio manifests.
 - The latter five are documentation-mirror skills, audited against official sources via the internal `titools-skill-auditor`. See [Where the references come from](#where-the-references-come-from).
 - `purgetss` reference files are audited against the official PurgeTSS documentation and against the package source (the CLI and the generated `utilities.tss`), but its workflow conventions are opinionated.
 
@@ -274,7 +277,7 @@ TiTools provides slash commands for common tasks. Both channels ship them: the p
 These commands automatically invoke the relevant skills:
 - `/ti-check` reads `tiapp.xml`, validates declared native modules, and reports project health
 - `/ti-new-screen` uses `ti-expert` + `purgetss` to create properly structured files
-- `/ti-audit` routes all 11 skills: the reuse sweep first, core Titanium checks always, Alloy/PurgeTSS checks when detected, integration how-tos when used, and `ti-game` / `ti-synthengine` checks when those modules are declared
+- `/ti-audit` routes all 13 skills: the reuse sweep first, core Titanium checks always, Alloy/PurgeTSS checks when detected, integration how-tos when used, `ti-game-assets` checks for game asset workflows, and `ti-game` / `ti-synthengine` / `ti-admob-unified` checks when those modules are declared
 
 ---
 
@@ -318,6 +321,8 @@ All skills include automatic project detection to ensure compatibility:
 | ti-expert | Alloy vs Classic      | Checks for `app/` (Alloy) vs `Resources/` (Classic) structure |
 | ti-ui     | Titanium projects     | Checks for `tiapp.xml` (both Alloy and Classic)               |
 | ti-game   | ti.game module        | Checks for `<module>ti.game</module>` in `tiapp.xml` or `require('ti.game')` |
+| ti-game-assets | Game art/sound workflows | Reads asset inventories, generation/export workflows and requested visual or sound assets; no module install required for drawings |
+| ti-admob-unified | ti.admob.unified and mediation | Declared core/complement modules or requested ad/privacy/provider integration |
 | ti-synthengine | ti.synthengine module | Checks for `<module>ti.synthengine</module>` in `tiapp.xml` or `require('ti.synthengine')` |
 
 Why this matters:
@@ -333,11 +338,12 @@ Why this matters:
 | --- | --- |
 | Whether to build it at all | `ti-reuse-first`, first |
 | Architecture and UI | `ti-expert`, `ti-ui`, `purgetss` when configured |
-| Native modules | `ti-game`, `ti-synthengine` when declared |
+| Game assets | `ti-game-assets` for visual and sound creation, preparation and integration |
+| Native modules | `ti-game`, `ti-synthengine`, `ti-admob-unified` when declared or requested |
 | Exact SDK/API guidance | `ti-api`, `ti-guides`, `ti-howtos` |
 | Alloy MVC and tooling | `alloy-guides`, `alloy-howtos` for Alloy projects |
 
-All eleven ship with TiTools; no second skill package is required.
+All thirteen ship with TiTools; no second skill package is required.
 
 ---
 
@@ -502,14 +508,37 @@ Key rules:
 
 ---
 
+### ti-game-assets
+
+Create game art and sound assets as a coherent set: transparent HD masters or strict logical-grid pixel art, animation states, three-layer parallax, synthesized effects/music/ambience, related sound variants and screen-position stereo. `ti-game` owns native game behavior and `ti-synthengine` owns the sound contract; the asset skill coordinates both.
+
+For the processing helpers and development tests, install Python dependencies in a virtual environment:
+
+```bash
+python3 -m venv /tmp/titools-assets-env
+/tmp/titools-assets-env/bin/pip install -r skills/ti-game-assets/scripts/requirements.txt
+TITOOLS_ASSETS_PYTHON=/tmp/titools-assets-env/bin/python npm test
+```
+
+Raster drawing generation/editing uses integrated `image_gen`. Authored SVG/procedural pipelines preserve editable sources and deterministically export PNG; offline synthesis can generate WAV. The bundled Python helpers validate alpha, SVG provenance, hashes and WAV headers/payloads. Cleaning writes new files and requires a reviewed protected region or an explicit defined-edge trial. Sound recipes remain source assets even without recorded audio files. Guides cover seamless texture/audio loops and responsible ad transitions through the separate `ti-admob-unified` skill. Technical checks, visual inspection and device listening are reported separately.
+
+### ti-admob-unified
+
+Integrate César's `ti.admob.unified` module in Alloy or Classic using its official documentation for installation, API, UMP/ATT, privacy options, banner layout, fullscreen lifecycle and mediation. The skill includes the official copy-ready application library and guides for AppLovin, Meta, InMobi, Unity and Liftoff. The module's first public 1.0.0 release is under preparation at this snapshot.
+
+Source commit, per-file hashes and rebased links are recorded. Future updates use the maintainer auditor's source map and the read-only check `node scripts/verify-module-snapshot.mjs --source /path/to/ti.admob.unified`; new, changed or removed docs are reported before updating. Community guidance remains separate from official mirrors.
+
+Installing an adapter does not configure a publisher account or prove delivery. The skill distinguishes build/linking, Google test ads, each provider's test delivery and physical-device acceptance; it preserves the game's selected frequency policy instead of enabling every format.
+
 ### ti-synthengine
 
-Cross-platform sound design and synthesis with the native `ti.synthengine` 1.0.0 module for Android and iOS.
+Cross-platform sound design and synthesis with the native `ti.synthengine` 1.0.0 beta module for Android and iOS.
 
 When it activates:
 - `tiapp.xml` declares `ti.synthengine`, or code calls `require('ti.synthengine')`
 - The app needs generated UI feedback, game cues, retro/chiptune effects, alarms, chords, pads, noise percussion, sweeps, panning, or vibrato
 - A synth call returns `false`, the first sound glitches, a pattern stops, a chord pumps, or output changes after a route switch
+- The app needs voice/queue/rejection counters, optional render-load/output meters, or help interpreting host benchmark evidence
 
 Example prompts:
 ```
@@ -527,6 +556,7 @@ Key rules:
 - `playTone` accepts `note` or `frequency`, never both; `playChord` accepts `notes` or `frequencies`, never both
 - `duration` includes attack, the full-level middle, and release, so explicit envelope times must intersect correctly
 - Use `frequencyEnd` for sweeps, `panEnd` for stereo movement, and `lfoFreq`/`lfoDepth` for pitch vibrato
+- Binaural headphone positioning uses `spatialX`/`spatialY` from -1 to 1, without pan fields. Omit both to keep stereo; check installed coordinate limits because older 1.0.0 builds lack this beta addition
 - Curated recipes cover retro effects, playable xylophone gestures, four-pad memory cues, controlled waveform comparisons, layered chords and cancellable repetition
 - Start after the first layout settles, keep one lifecycle owner, check Boolean returns, and call `shutdown()` on cleanup
 
@@ -627,7 +657,7 @@ Behavior depends on where you run it:
 | With `--local` flag        | Installs skills locally to `./.agents/skills/` in the current project |
 
 What it does:
-- Installs the 10 TiTools skills (global or local depending on context)
+- Installs the 13 TiTools skills (global or local depending on context)
 - Installs ti-pro agent for Claude Code
 - Installs the `/ti-check`, `/ti-new-screen` and `/ti-audit` slash commands into `~/.claude/commands/`
 - Detects installed AI platforms and lets you choose which to link (only Claude Code needs platform symlinks; Gemini CLI and Codex CLI auto-discover from `~/.agents/skills/`)
@@ -836,7 +866,9 @@ This pattern is documented across four bundled TiTools skills: `ti-ui`, `ti-expe
 | purgetss  | Setup + Critical Rules        | 34 files (Classic compatibility, grid, animations, icons, class-index, SVG pipeline, etc.) |
 | ti-ui     | UI Rules + Platform Diffs     | 14 files (layouts, lists, gestures, etc.)             |
 | ti-game   | Native 2D Game Workflow       | 9 files (API, setup, patterns, recipes, tile maps, debugging, roadmap) |
-| ti-synthengine | Native Sound Synthesis   | 8 files (API, sound design, lifecycle, engine, official examples, curated recipes, recommendations, troubleshooting) |
+| ti-game-assets | Visual and Sound Assets | 10 guides and a manifest example; alpha and contract validation scripts |
+| ti-admob-unified | Unified Advertising | 11 official module guides, source/hash update checks, official example library and game integration guidance |
+| ti-synthengine | Native Sound Synthesis   | 10 Markdown references (8 official, curated recipes, maintenance notes), raw statistics trials and a source hash manifest |
 
 ---
 

package/agents/ti-pro.md

@@ -7,7 +7,9 @@ skills:
   - purgetss
   - ti-ui
   - ti-game
+  - ti-game-assets
   - ti-synthengine
+  - ti-admob-unified
   - ti-api
   - ti-guides
   - ti-howtos
@@ -29,8 +31,10 @@ When invoked, research complex topics by consulting the applicable skills from t
 - `ti-expert` - Architecture, patterns, conventions
 - `purgetss` - Utility-first styling classes (optional add-on; use when the project already has it or the user asks about it)
 - `ti-ui` - UI/UX patterns, layouts, gestures
+- `ti-game-assets` - Visual and sound asset contracts, raster generation, alpha/export validation, synthesis variants and stereo coordination when assets are involved
 - `ti-game` - Native `ti.game` architecture and API when the module is declared
 - `ti-synthengine` - Native sound synthesis and strict `ti.synthengine` contract when the module is declared
+- `ti-admob-unified` - Official unified advertising/privacy/mediation module contract and provider setup when declared or requested
 - `ti-api`, `ti-guides`, `ti-howtos` - Exact Titanium APIs, SDK fundamentals and native integrations
 - `alloy-guides`, `alloy-howtos` - Alloy MVC, CLI, configuration and compiler workflows when the project is Alloy
 

package/commands/ti-audit.md

@@ -25,6 +25,10 @@ Native-module audit:
 10. If the project declares `ti.game`, invoke `ti-game` — check for sprites moved from timers instead of native properties, levels sized from `Ti.Platform.displayCaps` instead of the `resize` event, sprites added one by one instead of in one array, and timers or sounds left running when the window closes.
 11. If the project declares `ti.synthengine`, invoke `ti-synthengine` — check strict option names and types, mutually exclusive pitch fields, valid envelope intersections, checked Boolean results, one clear lifecycle owner, delayed startup after layout, app-owned timer cancellation, and `shutdown()` cleanup.
 
+12. If the project has game art/sound inventories or asset-generation/export workflows, invoke `ti-game-assets` — check contracts per set, master provenance/transparency, protected alpha cleanup, frame/pivot alignment, complete derived exports, parallax layers, sound variants and semantic event bindings. Consult `ti-game` and `ti-synthengine` equally in their applicable domains; do not require module installation or new sounds for an image-only task.
+
+13. If the project declares `ti.admob.unified`/mediation complements or implements an ad flow through this module, invoke `ti-admob-unified` — verify official module APIs, consent/request eligibility/initialization, test IDs, banner layout and refresh ownership, deliberate fullscreen presentation, callback cleanup and selected-provider mappings. Separate linking, Google test ads, provider delivery and physical acceptance. In games preserve native pause/audio/input ownership and the existing frequency policy.
+
 If a conditional skill does not apply, record it as `not applicable` with the detected reason instead of inventing findings from it.
 
 Report findings grouped by severity: critical, warning, info.

package/lib/config.js

@@ -35,7 +35,9 @@ export const SKILLS = [
   'purgetss',
   'ti-ui',
   'ti-game',
+  'ti-game-assets',
   'ti-synthengine',
+  'ti-admob-unified',
   'ti-api',
   'ti-guides',
   'ti-howtos',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maccesar/titools",
-  "version": "5.1.1",
+  "version": "5.2.0",
   "description": "Titanium SDK skills and agents for AI coding assistants, including native game and sound synthesis modules",
   "main": "lib/index.js",
   "type": "module",

package/skills/ti-admob-unified/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: ti-admob-unified
+description: "Use when a Titanium app declares ti.admob.unified or its mediation complements, imports require('ti.admob.unified'), or asks to integrate/configure AdMob banners, interstitials, rewarded or app-open ads, UMP/ATT, privacy options, lifecycle, ad frequency or AppLovin, Meta, InMobi, Unity and Liftoff mediation with this module. Applies to Alloy and Classic on Android/iOS."
+---
+
+# ti.admob.unified — ads, privacy and providers
+
+Integrate César's unified Titanium module using its official documentation and maintained application library. The local **1.0.0** contract is preparing for its first public release; do not claim a public release or usable production demand from these snapshots. Sources are pinned to **`5b4cbf9347a51c4f959dc262ac1500f82f28b4a0`**, copied 2026-10-11. See `references/source-snapshot.json` for paths/hashes and [references/source-notes.md](references/source-notes.md) for provenance and update checks. Check the installed build and current sources when behavior differs.
+
+## Required workflow
+
+Read the relevant references before proposing calls or configuration. Do not infer this API from old `ti.admob`, `ti.android.admob` or raw Google SDK examples.
+
+| Task | Read first |
+| --- | --- |
+| Install artifacts, app IDs, platform settings, first test request | [references/getting-started.md](references/getting-started.md) |
+| Ownership, navigation, layout, refresh, Alloy/Classic integration | [references/integration.md](references/integration.md), [references/library.md](references/library.md) |
+| Exact factories/methods/options/events/constants/payloads | [references/api-reference.md](references/api-reference.md) |
+| Consent-first startup, ATT, privacy options, request eligibility | [references/privacy.md](references/privacy.md) |
+| Fixed/adaptive banners, real reserved layout and pause/cleanup | [references/banners.md](references/banners.md) |
+| Interstitial/rewarded/app-open load/show, rewards and cleanup | [references/fullscreen.md](references/fullscreen.md) |
+| Select/install providers, publisher accounts, mappings, diagnostics | [references/mediation.md](references/mediation.md), [references/dependencies.md](references/dependencies.md) |
+| Replace legacy modules or internal builds | [references/migration.md](references/migration.md) |
+| Unsupported formats, extending providers, license/distribution | [references/roadmap.md](references/roadmap.md), [references/contributing.md](references/contributing.md), [references/third-party-notices.md](references/third-party-notices.md) |
+| Game experience and frequency decisions | [references/game-monetization.md](references/game-monetization.md), plus fullscreen/privacy |
+
+Cite factual guidance with `[source: references/<file>.md]`. If the relevant source is unavailable, mark the claim `FROM_MEMORY (unverified):` and do not invent a method or provider setting.
+
+## Integration invariants
+
+- Inspect `tiapp.xml`, installed artifacts, project type and existing ad owner before adding another boundary. Use `ti-guides`/`ti-howtos`, Alloy or UI skills as applicable.
+- Prefer the official copy-ready `assets/example/lib/ads.js`: copy unchanged to Alloy `app/lib/ads.js` or Classic `Resources/lib/ads.js`. Its documentation imports `require('lib/ads')`; preserve its path and provenance. `assets/example/library-usage.js` and `assets/example/app.js` are official integration evidence, not navigation templates to paste wholesale.
+- Follow the documented UMP → request eligibility → initialization sequence. `canRequestAds()` is the gate, not ATT status or a guessed personalization flag. Resolve requested ATT separately; do not request it without an actual use case. Preserve privacy options and named-listener cleanup.
+- Application IDs and ad-unit IDs are different. Use documented test IDs during development; do not switch to production IDs as an incidental fix.
+- Native activity/app lifecycle and SDK banner refresh belong to the module/Google. The app owns tab/window coverage and reserved layout. Do not add refresh timers or duplicate background handlers for banners.
+- Separate loading from deliberate fullscreen presentation. Do not show from a load callback. Coordinate game clock/audio/inputs and ad ownership; handle no-fill, failed presentation, actual close and destroyed screens without repeated ads or late navigation.
+- Install only selected mediation complements on each target platform. All application calls use `ti.admob.unified`. Configure provider accounts and AdMob mappings; neither a packaged adapter nor `ready` diagnostics nor a Google test ad proves provider delivery. Do not invent placeholder keys, manual provider initializers or an `enableMediation` option.
+- Consult the roadmap before suggesting native ads, rewarded interstitial or a network outside the distributed set. Supporting several formats does not justify enabling all of them in a game.
+
+## Acceptance
+
+Report separately: source/contract review, configuration/build/linking, Google test-ad behavior, each selected provider's own test delivery, and physical-device lifecycle/layout/visual acceptance. Use Ad Inspector as documented and re-check current Google/provider setup guidance before live configuration. A reported impression or passing stand-in test does not certify visible creative content or consent propagation. Do not click production ads to test delivery. No account creation, credentials, live ad activation or publishing is implied by ordinary integration work.
+
+For games, use `ti-game` for native pause/cleanup and `ti-game-assets` for audiovisual assets. Respect the existing game's presentation policy; defaults and quotas are product choices to measure, not optimal values certified by this module.

package/skills/ti-admob-unified/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Ti AdMob Unified"
+  short_description: "Configure ads, privacy and mediation in Titanium"
+  default_prompt: "Use $ti-admob-unified to integrate ads and configure the selected mediation providers for my Titanium app."