@maccesar/titools 4.23.1 → 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 sourced from the official Titanium SDK docs (`tidev/titanium-docs`) and audited against them via the internal `titools-skill-auditor`.
-- `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": "4.23.1",
+  "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/alloy-guides/references/MODELS.md

@@ -291,7 +291,7 @@ In Alloy, collection data can be synchronized to a view object, or a single mode
 
 #### Collection-View Binding
 
-To enable collection-view binding, create a global singleton or controller-specific collection using the [Collection tag](https://titaniumsdk.com/guide/Alloy_Framework/Alloy_Guide/Alloy_Views/Alloy_XML_Markup.html#collection-element) in the XML markup of the main view, then add the view object you want to bind data to. The following Titanium view objects support binding to a Collection:
+To enable collection-view binding, create a global singleton or controller-specific collection using the [Collection tag](https://titaniumsdk.com/docs/alloy/views) in the XML markup of the main view, then add the view object you want to bind data to. The following Titanium view objects support binding to a Collection:
 
 | View Object    | Since Alloy version | Add data binding attributes to...              | Repeater Object to map model attributes to view properties                     |
 | -------------- | ------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------ |
@@ -416,7 +416,7 @@ The application is now setup for basic collection-view binding. When any new dat
 
 #### Model-View Binding
 
-To bind a single model to a component, create a global singleton or controller-specific model using the [Model tag](https://titaniumsdk.com/guide/Alloy_Framework/Alloy_Guide/Alloy_Views/Alloy_XML_Markup.html#model-element) in the XML markup of the main view and map the model attribute to the view component. To map the attribute to the view component, prefix the model name or id to the attribute, then enclose it with curly brackets or braces ('{' and '}').
+To bind a single model to a component, create a global singleton or controller-specific model using the [Model tag](https://titaniumsdk.com/docs/alloy/views) in the XML markup of the main view and map the model attribute to the view component. To map the attribute to the view component, prefix the model name or id to the attribute, then enclose it with curly brackets or braces ('{' and '}').
 
 To do complex transformations on the model attributes, extend the model prototype with a `transform()` function. It should return the modified model as a JSON object.
 

package/skills/alloy-guides/references/MODELS_ADVANCED.md

@@ -33,7 +33,7 @@ In Alloy, a sync adapter allows you to store and load your models to a persisten
 
 #### Backbone Sync
 
-Backbone syncs your models to persistent storage devices based on the implementation of the [Backbone.sync method](https://titaniumsdk.com/guide/Alloy_Framework/Alloy_Guide/Alloy_Models/Alloy_Sync_Adapters_and_Migrations.html). Since Backbone's primary use is for web applications, by default, the Backbone.sync method executes RESTful JSON requests to a URL specified by the Model.urlRoot or Collection.url attribute, when these classes are created.
+Backbone syncs your models to persistent storage devices based on the implementation of the [Backbone.sync method](https://titaniumsdk.com/docs/alloy/models). Since Backbone's primary use is for web applications, by default, the Backbone.sync method executes RESTful JSON requests to a URL specified by the Model.urlRoot or Collection.url attribute, when these classes are created.
 
 Models are accessed from persistent storage based on the `id` attribute. To override this, set the `idAttribute` property of the model. The `cid` (client ID) is a special property of models that is automatically assigned when they are first created. Client IDs are useful when the model has not yet been saved to the server and does not have its real `id` yet.
 

package/skills/alloy-guides/references/VIEWS_XML.md

@@ -584,16 +584,16 @@ If you have a collection of model data that needs to be automatically updated to
 
 Some Titanium view elements use special syntax. Refer to the **Alloy XML Markup** examples in the Titanium API Guides site for the following view objects:
 
-* [AlertDialog](https://titaniumsdk.com/api/titanium/ui/alertdialog.html)
-* [ButtonBar](https://titaniumsdk.com/api/titanium/ui/buttonbar.html)
-* [CoverFlowView](https://titaniumsdk.com/api/titanium/ui/ios/coverflowview.html)
-* [DashboardView](https://titaniumsdk.com/api/titanium/ui/dashboardview.html)
-* [ListView](https://titaniumsdk.com/api/titanium/ui/listview.html)
-* [Map](https://titaniumsdk.com/api/modules/map.html)
-* [Menu](https://titaniumsdk.com/api/titanium/android/menu.html)
-* [OptionBar](https://titaniumsdk.com/api/titanium/ui/optionbar.html)
-* [OptionDialog](https://titaniumsdk.com/api/titanium/ui/optiondialog.html)
-* [Picker](https://titaniumsdk.com/api/titanium/ui/picker.html)
-* [SplitWindow](https://titaniumsdk.com/api/titanium/ui/ios/splitwindow.html)
-* [TabbedBar](https://titaniumsdk.com/api/titanium/ui/ios/tabbedbar.html)
-* [Toolbar](https://titaniumsdk.com/api/titanium/ui/toolbar.html)
+* [AlertDialog](https://titaniumsdk.com/docs/sdk/Titanium.UI.AlertDialog)
+* [ButtonBar](https://titaniumsdk.com/docs/sdk/Titanium.UI.ButtonBar)
+* [CoverFlowView](https://titaniumsdk.com/docs/sdk/Titanium.UI.iOS.CoverFlowView)
+* [DashboardView](https://titaniumsdk.com/docs/sdk/Titanium.UI.DashboardView)
+* [ListView](https://titaniumsdk.com/docs/sdk/Titanium.UI.ListView)
+* [Map](https://titaniumsdk.com/modules/ti.map)
+* [Menu](https://titaniumsdk.com/docs/sdk/Titanium.Android.Menu)
+* [OptionBar](https://titaniumsdk.com/docs/sdk/Titanium.UI.OptionBar)
+* [OptionDialog](https://titaniumsdk.com/docs/sdk/Titanium.UI.OptionDialog)
+* [Picker](https://titaniumsdk.com/docs/sdk/Titanium.UI.Picker)
+* [SplitWindow](https://titaniumsdk.com/docs/sdk/Titanium.UI.iOS.SplitWindow)
+* [TabbedBar](https://titaniumsdk.com/docs/sdk/Titanium.UI.iOS.TabbedBar)
+* [Toolbar](https://titaniumsdk.com/docs/sdk/Titanium.UI.Toolbar)

package/skills/alloy-howtos/references/best_practices.md

@@ -1,6 +1,6 @@
 # Alloy best practices and recommendations
 
-Recommendations for writing Alloy apps. This supplements the Titanium SDK [Best Practices and Recommendations](https://titaniumsdk.com/guide/Titanium_SDK/Titanium_SDK_Guide/Best_Practices_and_Recommendations/) guide and focuses on coding style and conventions.
+Recommendations for writing Alloy apps. This supplements the Titanium SDK [Best Practices and Recommendations](https://titaniumsdk.com/docs/build) guide and focuses on coding style and conventions.
 
 ## Titanium-to-Alloy Guidance
 
@@ -29,7 +29,7 @@ Decide whether to adapt Alloy to your existing structure, or to adopt Alloy's st
 ### Naming Conventions
 
 - **Do not use double underscore prefixes** on variables, properties, or function names (e.g., `__foo`). They are reserved for Alloy and may cause conflicts and unexpected behavior.
-- **Do not use JavaScript reserved words as IDs.** See [Titanium SDK Reserved Words](https://titaniumsdk.com/guide/Titanium_SDK/Titanium_SDK_Guide/Best_Practices_and_Recommendations/Reserved_Words/) for the complete list.
+- **Do not use JavaScript reserved words as IDs.** See [Titanium SDK Reserved Words](https://titaniumsdk.com/docs/buildReserved_Words/) for the complete list.
 
 ### Global Variables
 

package/skills/alloy-howtos/references/cli_reference.md

@@ -123,7 +123,7 @@ Compiler options reference the `event.alloyConfig` object in [Build Configuratio
 
 ### run
 
-Use `titanium build` command to run Alloy projects. See [Titanium Command-Line Interface Reference](https://titaniumsdk.com/guide/Titanium_SDK/Titanium_SDK_Guide/Titanium_Command-Line_Interface_Reference/).
+Use `titanium build` command to run Alloy projects. See [Titanium Command-Line Interface Reference](https://titaniumsdk.com/docs/reference/cli).
 
 > **💡 Common ti build pitfalls**
 >

package/skills/alloy-howtos/references/debugging_troubleshooting.md

@@ -75,4 +75,4 @@ Search [existing issues](https://github.com/tidev/alloy/issues) first to avoid d
 - Include Alloy version (`alloy --version`)
 - Include environment information
 
-For detailed instructions, see [How to Report a Bug or Make a Feature Request](https://titaniumsdk.com/guide/Titanium_SDK/Titanium_SDK_Guide/Contributing_to_Titanium/How_to_Report_a_Bug_or_Make_a_Feature_Request/).
+For detailed instructions, see [How to Report a Bug or Make a Feature Request](https://titaniumsdk.com/contribute).

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`                          |