@maccesar/titools 5.0.0 → 5.1.0

package/README.md

@@ -8,7 +8,7 @@
 
 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.
 
-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.
+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.
 
 Without TiTools, assistants rely on general training data. That data can be outdated or too generic for Titanium work. With TiTools, the assistant can look up Alloy architecture, memory cleanup patterns, PurgeTSS utility classes, and platform-specific APIs.
 
@@ -191,8 +191,31 @@ Notes:
 - `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.
-- The latter five are documentation-mirror skills, audited via the internal `titools-skill-auditor` against three sources: `ti-api` against the API definitions in `tidev/titanium-sdk` (`apidoc/`, anchored to the newest GA tag), the guide skills against the rewritten guides in `tidev/titaniumsdk.com` (`content/docs/`), and both against the frozen `tidev/titanium-docs` corpus as an archive. The archive is additive: TiDev condensed 336 legacy pages into 62, and the material it left behind is kept here rather than deleted.
-- `purgetss` reference files are audited against the official PurgeTSS documentation, but its workflow conventions are opinionated.
+- 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.
+
+---
+
+## Where the references come from
+
+The Titanium documentation was rewritten during 2026, and v5.0.0 moved TiTools onto the new sources. No skill, command or flag was renamed and the references answer the same questions. What changed is what they are checked against.
+
+| Source | Feeds | Why it is the one |
+|---|---|---|
+| [`tidev/titanium-sdk`](https://github.com/tidev/titanium-sdk) → `apidoc/*.yml` | `ti-api` | The API definitions the SDK team edits. Every other copy of the API is compiled from these. |
+| [`tidev/titaniumsdk.com`](https://github.com/tidev/titaniumsdk.com) → `content/docs/` | `ti-guides`, `ti-howtos`, `alloy-guides`, `alloy-howtos` | The rewritten guides, and what [titaniumsdk.com](https://titaniumsdk.com) serves. |
+| `tidev/titaniumsdk.com` → `registry/sdk/<version>/` | `ti-api`, as a cross-check | The API compiled per published release. It answers which version actually shipped an API, which the YAML alone cannot. |
+| [`tidev/titanium-docs`](https://github.com/tidev/titanium-docs) | all five, as an archive | The previous corpus, now frozen. Kept for what the rewrite left out. |
+
+### Why the API comes from the SDK
+
+The website does not write API documentation. It compiles it from `apidoc/*.yml` and commits the result, so it trails the SDK by construction. `ti-api` reads the YAML for what exists and the compiled registry for which release shipped it, and documents the newest GA rather than `main`. An API merged into the SDK today reaches these references when the release carrying it ships, because until then you cannot call it.
+
+### The archive is additive
+
+`tidev/titanium-docs` is frozen and being archived upstream. TiDev's own migration audit classifies its 336 guide pages as 121 rewritten, 121 merged, 2 kept and 92 archived. Of those 92, 91 are release notes and the last is the discontinued Atom package, so no guide topic was dropped. The difference is density: 1390 KB of legacy prose became 219 KB.
+
+TiTools keeps the full corpus. The archive never overrides a live source on a question of fact, and nothing is deleted from a reference merely because the rewritten site no longer covers it. These skills still answer questions the official guides have not been rewritten to cover yet, such as the conditional `if=` attribute in Alloy XML and TSS, custom XML tags via `app/lib/`, and `alloy compile`.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maccesar/titools",
-  "version": "5.0.0",
+  "version": "5.1.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/purgetss/SKILL.md

@@ -44,7 +44,7 @@ Every utility class you suggest and every styling pattern you describe MUST be b
 
 `[source: references/<file>.md]`
 
-Example: *"Use `wh-12` to set width and height to 48px [source: references/class-index.md]"*
+Example: *"Use `wh-12` to set width and height to 48 [source: references/class-index.md]"*
 
 ### Step 4 — If you must answer from memory
 
@@ -205,7 +205,7 @@ purgetss create 'MyApp' -d -v fa
 ### 🚨 RESPECT USER FILES
 **NEVER delete any existing `.tss` files** (like `index.tss`, `detail.tss`) or other project files without explicit user consent.
 
-**How to handle migration to PurgeTSS:**
+**How to handle migration to PurgeTSS** (full workflow and translation tables in [adopting-purgetss.md](references/adopting-purgetss.md)):
 1. **ONLY** replace custom classes with PurgeTSS utility classes if the user explicitly requests it.
 2. When requested:
     - Analyze the definitions in the existing `.tss` files.
@@ -241,17 +241,16 @@ purgetss create 'MyApp' -d -v fa
 > **`horizontal`** - Arrange elements left to right:
 > ```xml
 > <View class="horizontal w-screen">
->   <Label text="Left" />
->   <View class="w-screen" />  <!-- Spacer -->
->   <Label text="Right" />
+>   <Label text="First" />
+>   <Label class="ml-4" text="Second" />  <!-- ml-4 = 16 after the previous sibling -->
 > </View>
 > ```
 >
-> **`composite`** (default) - Absolute positioning with `top`, `left`, etc.:
+> **`composite`** (default) - Absolute positioning with `top`, `left`, etc. (to pin one child left and another right, use a composite parent with `left-0` / `right-0`):
 > ```xml
 > <View class="h-screen w-screen">
->   <View class="wh-12 absolute left-0 top-0 bg-red-500" />
->   <View class="wh-12 absolute bottom-0 right-0 bg-blue-500" />
+>   <View class="wh-12 left-0 top-0 bg-red-500" />
+>   <View class="wh-12 bottom-0 right-0 bg-blue-500" />
 > </View>
 > ```
 >
@@ -280,8 +279,11 @@ purgetss create 'MyApp' -d -v fa
 >
 > **OR use PurgeTSS platform modifier classes:**
 > ```xml
-> <!-- ✅ GOOD - Platform-specific classes -->
-> <Window class="ios:status-bar-light android:status-bar-dark">
+> <!-- ✅ GOOD - status-bar-* classes are already emitted as [platform=ios] -->
+> <Window class="status-bar-light">
+>
+> <!-- ✅ GOOD - ios: / android: scope any other class to one platform -->
+> <Window class="ios:bg-white android:bg-gray-100">
 > ```
 >
 > **Properties that ALWAYS require platform modifiers:**
@@ -300,7 +302,7 @@ purgetss create 'MyApp' -d -v fa
 
 - **NO `p-` padding classes**: Titanium does NOT support a native `padding` property on `View`, `Window`, `ScrollView`, or `TableView`. Always use **margins on children** (`m-`) to simulate internal spacing.
 - **View defaults to `SIZE`**: Use `w-screen`/`h-screen` to fill space when needed.
-- **`rounded-full`**: To get a perfect circle, use `rounded-full-XX` (where XX is the width/height of the square element).
+- **`rounded-full`**: On its own it is a fixed 8×8 circle (`width: 8, height: 8, borderRadius: 4`). For any other size, use `rounded-full-XX` (where XX is the spacing-scale size of the square element).
 - **`rounded-full-XX` includes size**: These classes already set `width`, `height`, and `borderRadius`. Do **not** add `w-XX h-XX`/`wh-XX` unless you need to override.
 - **`m-xx` on FILL elements**: Adding `m-4` to a `w-screen` element pins it to all four edges (top, bottom, left, right). This will **stretch the component vertically** to fill the parent unless you explicitly add `h-auto` (`Ti.UI.SIZE`) to constrain it to its content.
 - **`w-XX` + `h-XX` → `wh-XX`**: If both width and height use the same scale value, prefer a single `wh-XX` (order doesn't matter: `w-10 h-10` and `h-10 w-10` are equivalent).
@@ -327,7 +329,7 @@ purgetss create 'MyApp' -d -v fa
 > ```
 
 - **NEVER add `composite` class explicitly** - That's the default, use `horizontal`/`vertical` when needed
-- **Arbitrary values use parentheses**: `w-(100px)`, `bg-(#ff0000)` - NO square brackets
+- **Arbitrary values use parentheses**: `w-(100)`, `bg-(#ff0000)` - NO square brackets, and no `px` unit (unitless values are pixels; since v7.8.0 `w-(100px)` stops the build with a `Class Syntax Error`)
 - **`mode: 'all'` required** in `config.cjs` for Ti Elements styling
 - **Classes use `kebab-case`**: `.my-class`, IDs use `camelCase`: `#myId`
 
@@ -400,12 +402,12 @@ PurgeTSS shares naming with some CSS Frameworks but has DIFFERENT classes for Ti
 | ----------------------- | ------------------------------------- |
 | `keyboard-type-email`   | `hintText` (use attribute)            |
 | `return-key-type-next`  | `passwordMask` (use attribute)        |
-| `text-center`           | `autocorrect` (use attribute)         |
-| `bg-blue-500`           | `autocapitalization` (use attribute)  |
-| `w-screen`              | `flex-row` → use `horizontal`         |
-| `wh-16`                 | `justify-between` → use margins       |
-| `rounded-lg`            | `w-full` → use `w-screen`             |
-| `m-4`, `gap-4`          | `p-4` on View → use `m-4` on children |
+| `text-center`           | `flex-row` → use `horizontal`         |
+| `bg-blue-500`           | `justify-between` → use positioning   |
+| `w-screen` (`Ti.UI.FILL`), `w-full` (`'100%'`) | `p-4` on View → use `m-4` on children |
+| `wh-16`, `rounded-lg`, `m-4`, `gap-4` |                         |
+| `autocorrect`, `autocorrect-false` |                            |
+| `autocapitalization-text-none` (also `normal-case`, `uppercase`, `capitalize`, `sentences`) | |
 
 > **💡 TIP**
 > When in doubt, prefer using the search command above to verify. It's better to spend 5 seconds verifying than suggesting a class that doesn't exist and will appear in the "unused classes" warning.
@@ -416,16 +418,16 @@ Load these only when needed:
 
 ### Essential References
 - **[Class Index](references/class-index.md)** - Naming conventions, prohibited classes, prefix inventory, verification commands (LOAD FIRST when unsure about a class)
-- **[Class Index — Properties (A–Z)](references/class-index-properties.md)** - Full A–Z table of every Titanium property and its PurgeTSS class prefix
-- **[Class Categories](references/class-categories.md)** - Complete prefix inventory by category (layout, colors, typography, states, etc.)
+- **[Class Index — Properties (A–Z)](references/class-index-properties.md)** - Every Titanium property with the class families that set it, generated from `utilities.tss`
+- **[Class Categories](references/class-categories.md)** - Every class family grouped by kind of value: colors, dimensions, constants, booleans
 - **[Dynamic Component Creation](references/dynamic-component-creation.md)** - `$.UI.create()` and `Alloy.createStyle()` for creating components in Controllers (READ FIRST for dynamic components)
-- **[Appearance Module](references/appearance-module.md)** - Light/Dark/System mode switching with persistence (v7.5.3)
-- **[Semantic Colors](references/semantic-colors.md)** - Titanium semantic colors for Light/Dark mode via `semantic` command (v7.6.0)
 
 ### Setup & Configuration
 - [Installation & Setup](references/installation-setup.md) - First run, VS Code, LiveView
 - [CLI Commands](references/cli-commands.md) - All `purgetss` commands
-- [Migration Guide](references/migration-guide.md) - Migrating existing apps from manual TSS to PurgeTSS
+- [Color Commands](references/color-commands.md) - `semantic`, `shades` and `color-module`: Light/Dark semantic colors, palettes in `config.cjs`, and the CommonJS color module
+- [Adopting PurgeTSS](references/adopting-purgetss.md) - Moving an existing Alloy app from hand-written `.tss` files to utility classes: the style-priority trap, view-by-view workflow, and property-to-class translation tables
+- [Migration Guide](references/migration-guide.md) - Upgrading between PurgeTSS versions (v7.2.6 → v7.17.1): breaking changes and what to review after each upgrade
 - **[Values and Units](references/values-and-units.md)** - How `ti.ui.defaultunit` in `tiapp.xml` interprets the unitless numeric values PurgeTSS writes (foundational concept for spacing, sizes, typography)
 
 ### Customization
@@ -449,7 +451,8 @@ Load these only when needed:
 - [iOS Large Titles](references/ios-large-titles.md) - Best practice for iOS Large Title navigation
 
 ### App Assets
-- [App Branding](references/app-branding.md) - `brand` command: 14 pieces, per-piece config, selection, optimization, appicon padding, and rounded non-icon artwork (v7.16.0)
+- [App Branding](references/app-branding.md) - `brand` command: 14 pieces, per-piece config, selection, optimization, launch assets, FCM notification icon, and troubleshooting
+- [Brand Padding & Geometry](references/brand-padding-geometry.md) - Per-piece padding, master sizing, splash sizing rule, rounded non-icon artwork (v7.16.0), and adaptive-mask math for `brand`
 - [Launch Background](references/launch-background.md) - Carrying `brand.background` into the iOS LaunchScreen and a launcher-only Android theme (`--notes` output)
 - [Multi-Density Images](references/multi-density-images.md) - `images` command for Android res-*dpi + iPhone @1x/@2x/@3x UI images (v7.6.0)
 - [SVG Pipeline](references/svg-pipeline.md) - SVG-aware compile-time image pipeline: `.svg` refs + numeric `w-*`/`h-*` classes compile to 8 density PNGs; `images.files`/`images.autoSync` (v7.11.0–v7.11.1)

package/skills/purgetss/references/EXAMPLES.md

@@ -17,11 +17,11 @@ Complete examples of common patterns with anti-patterns and correct implementati
   - [Gap Usage](#gap-usage)
   - [Padding on Container Views](#padding-on-container-views)
   - [`w-full` vs `w-screen`](#w-full-vs-w-screen)
-  - [`rounded-full` Without Size](#rounded-full-without-size)
+  - [`rounded-full` Is a Fixed 8×8 Circle](#rounded-full-is-a-fixed-88-circle)
   - [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)
-  - [Deprecated `theme.View.DEFAULT` vs `theme.extend.View`](#deprecated-themeviewdefault-vs-themeextendview)
+  - [`theme.View` (Replace) vs `theme.extend.View` (Merge)](#themeview-replace-vs-themeextendview-merge)
   - [Quick Reference Table](#quick-reference-table)
 
 <!-- TOC-END -->
@@ -45,18 +45,19 @@ The examples below catalog anti-patterns observed in real Titanium + PurgeTSS pr
 </View>
 ```
 
-**✅ CORRECT (Use horizontal layout + spacer):**
+**✅ CORRECT (Composite parent + edge positioning):**
 ```xml
-<View class="horizontal w-screen">
-  <Label text="Left" />
-  <View class="w-screen" />  <!-- Spacer -->
-  <Label text="Right" />
+<!-- Parent defaults to composite; each child is pinned to one edge -->
+<View class="w-screen">
+  <Label text="Left" class="left-0" />
+  <Label text="Right" class="right-0" />
 </View>
 ```
 
 **✅ ALTERNATIVE (Use margins):**
 ```xml
-<View class="horizontal w-screen">
+<!-- In a composite parent, ml-4 emits left: 16 and mr-4 emits right: 16 -->
+<View class="w-screen">
   <Label text="Left" class="ml-4" />
   <Label text="Right" class="mr-4" />
 </View>
@@ -172,8 +173,8 @@ The examples below catalog anti-patterns observed in real Titanium + PurgeTSS pr
 ```
 
 ```bash
-# Then run:
-purgetss build
+# Then run (bare command = purge; `purgetss build` only regenerates utilities.tss):
+purgetss
 # OR just compile:
 alloy compile
 ```
@@ -193,8 +194,8 @@ alloy compile
 **❌ WRONG (Children with % widths, parent without w-screen):**
 ```xml
 <View class="horizontal m-4">
-  <View class="w-(48%)">...</view>
-  <View class="w-(48%)">...</view>
+  <View class="w-(48%)">...</View>
+  <View class="w-(48%)">...</View>
 </View>
 <!-- Parent doesn't have w-screen, % calculations may fail -->
 ```
@@ -202,8 +203,8 @@ alloy compile
 **✅ CORRECT (Parent has w-screen):**
 ```xml
 <View class="horizontal m-4 w-screen">
-  <View class="w-(48%)">...</view>
-  <View class="w-(48%)">...</view>
+  <View class="w-(48%)">...</View>
+  <View class="w-(48%)">...</View>
 </View>
 ```
 
@@ -211,20 +212,32 @@ alloy compile
 
 ### Gap Usage
 
-**❌ WRONG (gap adds margin all around, breaks % widths):**
+**❌ WRONG (gap on the column itself: margins add to the % width):**
 ```xml
-<View class="grid grid-cols-2 gap-4">
-  <View class="col-span-6">...</view>  <!-- 50% + 16px margins -->
-  <View class="col-span-6">...</view>  <!-- 50% + 16px margins -->
+<View class="grid">
+  <View class="grid-cols-2 gap-4">...</View>  <!-- 50% + 16 left + 16 right -->
+  <View class="grid-cols-2 gap-4">...</View>  <!-- 50% + 16 left + 16 right -->
 </View>
 <!-- Total > 100%, elements wrap or overflow -->
 ```
 
-**✅ CORRECT (Use explicit margins):**
+**✅ CORRECT (Official grid pattern: gap on an inner View inside each column):**
+```xml
+<View class="grid">
+  <View class="grid-cols-2">
+    <View class="gap-4">...</View>
+  </View>
+  <View class="grid-cols-2">
+    <View class="gap-4">...</View>
+  </View>
+</View>
+```
+
+**✅ ALTERNATIVE (Use explicit margins):**
 ```xml
 <View class="horizontal mb-4 w-screen">
-  <View class="w-(48%) mr-2">...</view>
-  <View class="w-(48%) ml-2">...</view>
+  <View class="w-(48%) mr-2">...</View>
+  <View class="w-(48%) ml-2">...</View>
 </View>
 ```
 
@@ -274,9 +287,9 @@ alloy compile
 
 ---
 
-### `rounded-full` Without Size
+### `rounded-full` Is a Fixed 8×8 Circle
 
-**❌ WRONG (rounded-full alone doesn't exist):**
+**❌ WRONG (`rounded-full` emits `width: 8, height: 8, borderRadius: 4`, which conflicts with `w-12 h-12`; at 48×48 a radius of 4 is not a circle):**
 ```xml
 <View class="h-12 w-12 rounded-full" />
 ```
@@ -300,25 +313,25 @@ alloy compile
 
 **❌ WRONG (Square brackets are not supported):**
 ```xml
-<View class="w-[100px] bg-[#ff0000]" />
+<View class="w-[100] bg-[#ff0000]" />
 ```
 
 **✅ CORRECT (PurgeTSS uses parentheses):**
 ```xml
-<View class="w-(100px) bg-(#ff0000)" />
+<View class="w-(100) bg-(#ff0000)" />
 ```
 
-**PurgeTSS syntax for arbitrary values uses `()` not `[]`.**
+**PurgeTSS syntax for arbitrary values uses `()` not `[]`, and pixel values are written without a unit: `w-(100px)` also stops the build (`Explicit "px" unit is redundant`).**
 
 > **🚨 v7.8.0+ HARD-FAILS THE BUILD ON SQUARE BRACKETS**
 > Since v7.8.0, the build stops with a structured `Class Syntax Error` block (file path + line number + `Fix:` suggestion) the moment it spots `top-[10px]`, `wh-[12]`, or any other square-bracket utility. Pre-v7.8.0, those classes silently dropped into the `// Unused or unsupported classes` block of `app.tss` — easy to miss. Now they're loud and actionable.
 >
 > v7.10.1 reworded the error message from `'Tailwind-style brackets "[ ]" are not supported'` to `'Square brackets "[ ]" are not supported'`. Same enforcement, less framing.
 >
-> See [Arbitrary Values → Class syntax pre-validation](arbitrary-values.md#class-syntax-pre-validation) for the full list of patterns the pre-validator catches (5 total, including inverted negative sign and whitespace inside parentheses).
+> See [Arbitrary Values → Class syntax pre-validation](arbitrary-values.md#class-syntax-pre-validation) for the full list of patterns the pre-validator catches (5 total, including inverted negative sign, whitespace inside parentheses, and redundant `px` units).
 
 **Examples:**
-- `w-(100px)` - Custom width
+- `w-(100)` - Custom width
 - `bg-(#ff0000)` - Custom background color
 - `mt-(20dp)` - Custom margin top
 - `text-(#333333)` - Custom text color
@@ -381,33 +394,31 @@ alloy compile
 
 ---
 
-### Deprecated `theme.View.DEFAULT` vs `theme.extend.View`
+### `theme.View` (Replace) vs `theme.extend.View` (Merge)
 
-**WRONG (old shape — deprecated in recent PurgeTSS):**
+**Replace mode (`theme.View`, no `extend`) — the framework default `Ti.UI.SIZE` for View is dropped:**
 ```javascript
 // purgetss/config.cjs
 module.exports = {
   theme: {
-    View: {
-      DEFAULT: { backgroundColor: '#ffffff' }
-    }
+    View: { apply: 'bg-white' }
   }
 }
 ```
 
-**CORRECT (new `extend` shape):**
+**Extend mode (`theme.extend.View`) — merges with the built-in defaults:**
 ```javascript
 // purgetss/config.cjs
 module.exports = {
   theme: {
     extend: {
-      View: { backgroundColor: '#ffffff' }
+      View: { apply: 'bg-white' }
     }
   }
 }
 ```
 
-**Why:** The nested `DEFAULT` key is a legacy artifact. Component-level theme overrides now live directly under `theme.extend.<Component>` and are merged with built-in defaults. Using the old shape silently produces unexpected styles on newer PurgeTSS versions.
+**Why:** `Window`, `View`, and `ImageView` have built-in defaults (white Window background, `Ti.UI.SIZE` on View, iOS `hires: true` on ImageView). Under `theme.extend` your customization merges with them; at the top level of `theme` your config replaces them. The `DEFAULT` / `default` wrapper is not deprecated: `View: { apply: '...' }` and `View: { default: { apply: '...' } }` produce the same TSS, and the explicit wrapper is how you add `ios:` / `android:` blocks next to it.
 
 ---
 
@@ -421,10 +432,10 @@ module.exports = {
 | `items-center`                        | Exists but maps to fill, not centering — avoid for centering | Use layout + positioning         |
 | `p-4` on View                         | No padding on containers             | `m-4` on children                            |
 | `w-full`                              | Percentage-based                     | `w-screen` (Ti.UI.FILL)                      |
-| `rounded-full`                        | Needs size suffix                    | `rounded-full-12`                            |
+| `rounded-full` with `w-*`/`h-*`       | Fixed 8×8 circle, conflicts on size  | `rounded-full-12`                            |
 | `composite` class                     | Already default                      | Omit it                                      |
-| `w-[100px]`                           | Wrong syntax                         | `w-(100px)`                                  |
-| Manual `.tss`                         | Overwritten by PurgeTSS              | Use utility classes                          |
-| `gap` with `%` widths                 | Total exceeds 100%                   | Use explicit margins                         |
+| `w-[100]`, `w-(100px)`                | Stops the build (v7.8.0+)            | `w-(100)`                                    |
+| Manual `.tss`                         | Duplicates classes; its rules override `app.tss` | Use utility classes (`app.tss` itself is rewritten on every run) |
+| `gap` on a `%`-width column           | Total exceeds 100%                   | `gap-*` on an inner View, or explicit margins |
 | ScrollView without `content-*` sizing | No/unexpected scroll                 | Add `content-w-screen` + `content-h-auto`    |
-| `theme.View.DEFAULT`                  | Legacy shape in newer PurgeTSS       | `theme.extend.View`                          |
+| `theme.View` to tweak one default     | Replaces all View defaults           | `theme.extend.View`                          |

package/skills/purgetss/references/adopting-purgetss.md

@@ -0,0 +1,137 @@
+# Adopting PurgeTSS in an Existing Alloy App
+
+How to move an Alloy app whose styles live in hand-written `.tss` files (per-controller files, `#id` rules, inline XML attributes) to PurgeTSS utility classes. For upgrading a project that already uses PurgeTSS from one version to another, see [migration-guide.md](migration-guide.md) instead.
+
+> **Source note:** the official PurgeTSS docs have no adoption guide. This page is TiTools author guidance, assembled from behavior verified in the PurgeTSS source (v7.17.1), the Alloy style-priority rules and `utilities.tss`. Every class in the tables below exists in `utilities.tss` with the value shown.
+
+## Ground Rules
+
+- **Never delete the user's `.tss` files without explicit consent.** Convert a view, show the result, and wait for confirmation before removing the old rules (see `SKILL.md` § "RESPECT USER FILES").
+- **One view at a time.** Convert, compile, check on both platforms, then move on.
+- **Alloy only.** The utility-class workflow does not exist in Classic projects; see [classic-projects.md](classic-projects.md).
+
+## What PurgeTSS Does to Your Styles
+
+| File | What happens |
+| --- | --- |
+| `app/styles/app.tss` | On the first run it is backed up to `app/styles/_app.tss`. From then on PurgeTSS **rewrites `app.tss` on every run**: resets, then the contents of `_app.tss`, then only the utility classes your views use. Never edit `app.tss` directly. |
+| `app/styles/_app.tss` | Your original global styles. Keep custom global classes here; they are copied into `app.tss` on each run. |
+| `app/styles/<controller>.tss` | Not touched. PurgeTSS reads these files only so the classes they define are not reported as missing. |
+| `alloy.jmk` | The first run adds a hook so `purgetss` runs on every Alloy compile. See [installation-setup.md](installation-setup.md). |
+
+### The Priority Trap
+
+Alloy applies styles from lowest to highest priority: `styles/app.tss` (global), then `styles/<controller>.tss`, then attributes in the XML markup, with theme and platform-specific files layered in between (Alloy guide, "Style Priorities"). PurgeTSS classes land in `app.tss`, the **lowest** layer. During a partial migration this means:
+
+- A leftover rule in `styles/index.tss` for the same element beats the utility class, silently.
+- An inline attribute such as `backgroundColor="#fff"` beats both.
+
+When a class "does nothing" mid-migration, look for a leftover rule in the controller's `.tss` or an attribute on the XML tag before suspecting PurgeTSS.
+
+## Workflow
+
+### 1. Set up
+
+```bash
+cd your-app
+purgetss init   # creates ./purgetss/config.cjs
+purgetss        # first purge: backs up app.tss to _app.tss and installs the alloy.jmk hook
+```
+
+Commit (or branch) before this step so the backup and the hook are easy to review.
+
+### 2. Convert one view
+
+Before:
+
+```xml
+<!-- app/views/index.xml -->
+<View id="header">
+  <Label id="title" text="Welcome" />
+</View>
+```
+
+```tss
+// app/styles/index.tss
+'#header': { backgroundColor: '#ffffff', height: 64, top: 0 }
+'#title': { color: '#1f2937', font: { fontSize: 18, fontWeight: 'bold' } }
+```
+
+After:
+
+```xml
+<!-- app/views/index.xml -->
+<View class="top-0 h-16 bg-white">
+  <Label class="text-lg font-bold text-gray-800" text="Welcome" />
+</View>
+```
+
+Keep the `id` attributes if controller code uses them (`$.header`); only the style rules move.
+
+### 3. Remove the old rules (with consent)
+
+Once the converted view looks right on both platforms, and the user agrees:
+
+1. Delete the converted rules from `app/styles/index.tss`. Remove the file only if nothing is left in it.
+2. Move any global class still needed from `_app.tss` into utility classes, or leave it in `_app.tss`.
+3. Run `purgetss` (or compile) to regenerate `app.tss`.
+
+## Translation Tables
+
+### Properties
+
+| Hand-written TSS | PurgeTSS class |
+| --- | --- |
+| `backgroundColor: '#ffffff'` | `bg-white` |
+| `backgroundColor: '#f3f4f6'` | `bg-gray-100` |
+| `color: '#1f2937'` | `text-gray-800` (sets `color` and `textColor`) |
+| `font: { fontSize: 18 }` | `text-lg` |
+| `font: { fontWeight: 'bold' }` | `font-bold` |
+| `width: Ti.UI.FILL` | `w-screen` |
+| `width: '100%'` | `w-full` |
+| `height: Ti.UI.SIZE` | `h-auto` |
+| `height: 64` | `h-16` |
+| `height: 60` (not on the scale) | `h-(60)` |
+| `top: 0` | `top-0` |
+| `top: 16` | `mt-4` |
+| `left: 16, right: 16` | `mx-4` |
+| `borderRadius: 8` | `rounded-lg` |
+| `borderWidth: 1, borderColor: '#e5e7eb'` | `border border-gray-200` |
+| `opacity: 0.5` | `opacity-50` |
+| `visible: false` | `hidden` |
+| `layout: 'horizontal'` | `horizontal` |
+| `layout: 'vertical'` | `vertical` |
+| `elevation: 4` | `elevation-1` (the scale is ×4: `elevation-4` is `16`) |
+
+Spacing classes multiply by 4 (`mt-4` = 16), and the numbers are unitless: Titanium resolves them with `ti.ui.defaultunit` (see [values-and-units.md](values-and-units.md)). For a value off the scale use an arbitrary value **without a unit**: `h-(60)`, not `h-(60px)`, which stops the build since v7.8.0 (see [arbitrary-values.md](arbitrary-values.md)). Colors in your brand palette belong in `config.cjs` (see [customization-deep-dive.md](customization-deep-dive.md)), not in arbitrary `bg-(#hex)` classes repeated across views.
+
+### Platform and device conditionals
+
+| Hand-written code | PurgeTSS |
+| --- | --- |
+| `if (OS_IOS) { $.box.top = 40 } else { $.box.top = 20 }` | `class="ios:mt-10 mt-5"` |
+| `if (OS_ANDROID) { $.card.elevation = 4 }` | `class="android:elevation-1"` |
+| Tablet width set in the controller | `class="tablet:w-6/12 w-screen"` |
+
+See [platform-modifiers.md](platform-modifiers.md) for the full modifier list.
+
+### Animations
+
+| Hand-written animation | PurgeTSS Animation module |
+| --- | --- |
+| `Ti.UI.createAnimation({ opacity: 0, duration: 300 })` toggled by hand | `<Animation module="purgetss.ui" id="fade" class="close:opacity-0 open:opacity-100 duration-300" />` and `$.fade.play($.box)` |
+| A scale-down press effect | `class="close:scale-100 open:scale-95 duration-150"` |
+
+See [animation-system.md](animation-system.md).
+
+## Pitfalls
+
+| Pitfall | Consequence | Prevention |
+| --- | --- | --- |
+| Editing `app.tss` directly | Overwritten on the next run | Put custom global styles in `_app.tss` |
+| Leaving the old rule in `<controller>.tss` | It overrides the utility class | Remove converted rules once the user agrees |
+| Keeping inline attributes (`backgroundColor="…"`) | They override every class | Move them into classes |
+| Flexbox classes (`flex-row`, `justify-between`) | Classes don't exist | `horizontal` / `vertical` layouts |
+| `p-*` on a `View` or `Window` | No effect: `padding` exists only on `TextField`, `TextArea` and Android `CardView` | Margins on the children |
+| `w-[100]` or `w-(100px)` | Stops the build | `w-(100)` |
+| Converting every view at once | Hard to find what broke | One view per step, tested on both platforms |

package/skills/purgetss/references/animation-advanced.md

@@ -138,7 +138,7 @@ Values: `repeat-0` through `repeat-12`.
 
 ### rotate-* and -rotate-*
 
-Rotation in degrees. Range: **0** to **180**, positive and negative.
+Rotation in degrees. Range: **0** to **360**, positive and negative.
 
 ```css
 '.rotate-0': { rotate: 0 }
@@ -149,7 +149,12 @@ Rotation in degrees. Range: **0** to **180**, positive and negative.
 '.rotate-12': { rotate: 12 }
 '.rotate-45': { rotate: 45 }
 '.rotate-90': { rotate: 90 }
+'.rotate-135': { rotate: 135 }
 '.rotate-180': { rotate: 180 }
+'.rotate-225': { rotate: 225 }
+'.rotate-270': { rotate: 270 }
+'.rotate-315': { rotate: 315 }
+'.rotate-360': { rotate: 360 }
 '.-rotate-0': { rotate: 0 }
 '.-rotate-1': { rotate: -1 }
 '.-rotate-2': { rotate: -2 }
@@ -158,7 +163,12 @@ Rotation in degrees. Range: **0** to **180**, positive and negative.
 '.-rotate-12': { rotate: -12 }
 '.-rotate-45': { rotate: -45 }
 '.-rotate-90': { rotate: -90 }
+'.-rotate-135': { rotate: -135 }
 '.-rotate-180': { rotate: -180 }
+'.-rotate-225': { rotate: -225 }
+'.-rotate-270': { rotate: -270 }
+'.-rotate-315': { rotate: -315 }
+'.-rotate-360': { rotate: -360 }
 ```
 
 ### scale-*
@@ -180,6 +190,7 @@ Scales the matrix by the specified factor. Same value for horizontal and vertica
 '.scale-110': { scale: 1.1 }
 '.scale-125': { scale: 1.25 }
 '.scale-150': { scale: 1.5 }
+'.scale-200': { scale: 2 }
 ```
 
 ### Snap Classes
@@ -221,7 +232,7 @@ Prevents the drag system from promoting the active view on touch start. It does
 
 ### zoom-in-* / zoom-out-*
 
-Animates zoom in and zoom out. Sets the View's scale to the specified value, then animates it back to 1. Range: **0** to **150**.
+Animates zoom in and zoom out. Sets the View's scale to the specified value, then animates it back to 1. Range: **0** to **200**.
 
 ```css
 '.zoom-in-0': { animationProperties: { open: { scale: 0 }, complete: { scale: 1 } } }
@@ -234,7 +245,7 @@ Animates zoom in and zoom out. Sets the View's scale to the specified value, the
 '.zoom-out-110': { animationProperties: { close: { scale: 1.1 }, complete: { scale: 1 } } }
 ```
 
-Full range: `zoom-in-0`, `zoom-in-1`, `zoom-in-5`, `zoom-in-10`, `zoom-in-25`, `zoom-in-50`, `zoom-in-75`, `zoom-in-90`, `zoom-in-95`, `zoom-in-100`, `zoom-in-105`, `zoom-in-110`, `zoom-in-125`, `zoom-in-150` (and same for `zoom-out-*`).
+Full range: `zoom-in-0`, `zoom-in-1`, `zoom-in-5`, `zoom-in-10`, `zoom-in-25`, `zoom-in-50`, `zoom-in-75`, `zoom-in-90`, `zoom-in-95`, `zoom-in-100`, `zoom-in-105`, `zoom-in-110`, `zoom-in-125`, `zoom-in-150`, `zoom-in-200` (and same for `zoom-out-*`).
 
 ---
 
@@ -278,7 +289,7 @@ At construction time, top-level `scale`, `rotate`, and `anchorPoint` are convert
 
 `play()`, `toggle()`, `apply()`, and `sequence()` toggle internal open/close state. `open()` and `close()` set it explicitly. The active state is merged into the current base object when `animationProperties` exists.
 
-After a top-level `play`, `toggle`, `open`, or `close`, `animationProperties.complete` starts as a second animation. `apply()` applies `complete` immediately. The public callback belongs to the base play/apply operation; it does not wait for the second top-level `complete` animation.
+After a top-level `play`, `toggle`, `open`, or `close`, and after each view of a `sequence()`, `animationProperties.complete` starts as a second animation. `apply()` applies `complete` immediately. The public callback belongs to the base play/apply operation; it does not wait for the second top-level `complete` animation.
 
 For each direct child with an active state, merge precedence is:
 
@@ -308,7 +319,7 @@ Drag precedence is precise:
 - `snap.center` invokes `snapTo()` after a valid drop; `snap.back` returns a missed drop to its captured origin.
 - No `snap.magnet` behavior exists.
 
-Collision detection uses the dragged view's center. On release, the last non-null hover target is a fallback when the final hit test returns `null`.
+Collision detection uses the dragged view's center and runs only for views registered with `detectCollisions()`, so register the dragged views as well as the targets. Hit testing during movement runs only when a `dragCB` was supplied; in that case the last non-null hover target is a fallback when the final hit test at release returns `null`. `dragCB(source, null)` is also called whenever a registered view is released.
 
 `draggable(array)` immediately assigns each view `zIndex` from its array index. `keepZIndex` only disables later touch-start promotion. `swap()` restores z-order by the current draggable-registry order, not by arbitrary values present before registration.
 
@@ -423,3 +434,5 @@ function doAction(event) {
 ```
 
 This demonstrates: `play` for sidebar/card toggle, `open:`/`close:` modifiers for different states, `draggable` with `bounds:` modifier, and multiple Animation objects controlling different UI elements.
+
+If this window can close, add an `onClose` handler that calls `$.draggableAnimation.undraggable($.myCard)` so the global `orientationchange` listener is removed.