@maccesar/titools 2.10.0 → 3.1.0

package/skills/purgetss/SKILL.md

@@ -112,6 +112,18 @@ purgetss create 'MyApp' -d -v fa
 # -v: Copy icon fonts (fa, mi, ms, f7)
 ```
 
+## What's New in v7.9.0
+
+- Opacity modifier on semantic colors — `bg-surface/65` syntax now works for any class mapped through `theme.extend.colors`. PurgeTSS auto-derives `<originalKey>_<alphaPercent>` entries in `semantic.colors.json` per mode (light/dark). See [Semantic Colors → Opacity modifier auto-derivation](references/semantic-colors.md#opacity-modifier-auto-derivation). **Native rebuild required** — Liveview hot-reload alone does not refresh `semantic.colors.json`
+- `theme.Window` / `theme.View` / `theme.ImageView` presets now use **replace mode** — they no longer carry framework defaults (white background, `Ti.UI.SIZE`, iOS `hires: true`). This fixes gradient ghosting where a preset Window with `bg-gradient-*` apply was being covered by the implicit `backgroundColor: '#FFFFFF'`. Use `theme.extend.Window` / `theme.extend.View` / `theme.extend.ImageView` when you want **extend mode** (merge with defaults). See [Apply Directive → Extend mode vs replace mode](references/apply-directive.md#extend-mode-vs-replace-mode)
+- Glossary path renamed: `purgetss/experimental/tailwind-classes/` → `purgetss/glossary/tailwind-classes/`
+
+## What's New in v7.8.0
+
+- `purgetss images --width <n>` — pin SVG output to a specific base width; PurgeTSS derives per-density assets from the multiplier scale (×1 / ×1.5 / ×2 / ×3 / ×4). Range `[1, 8192]`. CLI-only (no `images:` config equivalent — width is per-asset). See [Multi-Density Images → Pinning the output width with --width](references/multi-density-images.md#pinning-the-output-width-with---width)
+- Class syntax pre-validation — the build now emits a `Class Syntax Error` block (file path + line + `Fix:` suggestion) for 5 detected patterns: inverted negative sign (`top-(-10)` → `-top-(10)`), Tailwind brackets (`top-[10px]` → `top-(10px)`), empty parens (`wh-()`), whitespace inside parens (`wh-( 200 )` → `wh-(200)`), redundant `px` unit (`top-(10px)` → `top-(10)`). See [Arbitrary Values → Class syntax pre-validation](references/arbitrary-values.md#class-syntax-pre-validation)
+- Parser fix for negative values inside parentheses — `top-(-10)` is now correctly flagged as inverted-negative-sign instead of silently misparsed
+
 ## What's New in v7.7.0
 
 - `brand:` config restructured — flat keys replaced by purpose-based groups: `brand.logos`, `brand.padding`, `brand.android`, `brand.ios`, `brand.colors`

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

@@ -238,15 +238,6 @@ const { saveComponent } = require('purgetss.ui')
 saveComponent({ source: $.myView, directory: 'screenshots' })
 ```
 
-### createAnimation(args)
-
-Factory function to create Animation objects programmatically.
-
-```javascript
-const { createAnimation } = require('purgetss.ui')
-const anim = createAnimation({ duration: 300, curve: Ti.UI.ANIMATION_CURVE_EASE_IN_OUT })
-```
-
 ---
 
 ## Implementation Rules

package/skills/purgetss/references/app-branding.md

@@ -301,6 +301,16 @@ brand: {
 >
 > Generating `splash_icon.png` does not automatically switch Titanium to use it for the Android 12+ system splash. Titanium still needs a custom splash theme that points `android:windowSplashScreenAnimatedIcon` to `@drawable/splash_icon`. If you do nothing, Android keeps using `ic_launcher`.
 
+> **WARNING**
+>
+> Merge splash settings into the existing Android theme
+> If your app already has a custom Android theme block in `tiapp.xml`, **merge** the new splash settings (the `android:windowSplashScreenAnimatedIcon` entry and any sibling theme attributes) into that existing theme. Do **not** append a second `<application>` element or a duplicate theme block — Titanium will only honor one theme definition, and the duplicate silently shadows or overrides the original, leading to "my settings were ignored" debugging sessions. Always edit the existing `<application>` / theme block in place.
+
+> **INFO**
+>
+> A brief flash on splash exit is usually the system, not your PNGs
+> If you still see a brief flash or abrupt exit transition during splash dismissal even with correct assets in place, **do not assume the PNGs PurgeTSS generates are wrong**. That artifact commonly comes from Android 12+'s system splash exit transition (or from Titanium's splash theme handoff to your first window), not from the splash icon files themselves. Regenerating `splash_icon.png` will not change it — the fix lives in the splash theme animation, not in the icon assets.
+
 ## Android legacy splash fallback
 
 Since v7.7.0, PurgeTSS regenerates `app/assets/android/default.png` in Alloy projects and `Resources/android/default.png` in Classic projects.
@@ -411,6 +421,16 @@ purgetss brand --cleanup-legacy --aggressive
 > Commit first
 > `--cleanup-legacy` deletes files permanently. Commit your project to git before running without `--dry-run` so `git restore` is available as a rollback.
 
+> **INFO**
+>
+> Files kept on purpose
+> `--cleanup-legacy` intentionally does **not** remove the following files, even when modern adaptive launcher icons and splash assets are already in place:
+>
+> - `app/assets/android/default.png` (Alloy projects)
+> - `Resources/android/default.png` (Classic projects)
+>
+> These remain because they are still required by Titanium framework defaults — older Android splash code paths fall back to `default.png`, and removing it can cause build warnings or a missing-asset error on certain Titanium SDK versions even when modern splash assets exist. Treat them as part of the baseline asset set, not as legacy clutter.
+
 ## Troubleshooting
 
 ### The icon looks cropped or cramped on my phone

package/skills/purgetss/references/appearance-module.md

@@ -2,15 +2,71 @@
 
 The `Appearance` export from `purgetss.ui` (added in **v7.5.3**) handles Light / Dark / System mode switching and persists the user's choice across app restarts. It is a thin, deterministic wrapper around Titanium's native `Ti.UI.overrideUserInterfaceStyle` plus `Ti.App.Properties`, exposed as a singleton so every controller in the app reads and writes the same state.
 
-This file covers the four public methods, the required setup, a full Settings-view example, and the lifecycle that keeps the saved mode in sync with the UI. For the color wiring that actually makes the UI *respond* to mode changes, see [semantic-colors.md](./semantic-colors.md).
+This reference follows the same workflow-first / API-second split the official PurgeTSS documentation now uses:
+
+- **Workflow** — initialize at startup, then build a Settings view that calls `Appearance.set(...)` (mirrors `best-practices/1-appearance-setup.md`).
+- **API reference** — the four public methods, exact signatures, and lifecycle (mirrors `purgetss-ui/10-appearance.md`).
+
+For the color wiring that actually makes the UI *respond* to mode changes, see [semantic-colors.md](./semantic-colors.md).
 
 > **INFO**
 >
 > Requires PurgeTSS **>= 7.5.3**. On older versions the `Appearance` export does not exist — the `require('purgetss.ui')` call will succeed, but `Appearance` will be `undefined`. Run `purgetss --version` in the project root to confirm.
 
-## Setup
+## How it fits together
+
+The Appearance module sits between three moving parts: a JS singleton, the OS-level interface style, and the semantic colors generated by PurgeTSS. The diagram below shows how a single `Appearance.init()` call at startup wires them together, and what happens when the user later picks a mode in Settings.
+
+```
+┌─ app/lib/appearance.js (singleton from purgetss.ui) ─────────────────┐
+│                                                                      │
+│   Appearance.init()  ────► reads 'userInterfaceStyle'                │
+│                            from Ti.App.Properties                    │
+│                            applies Ti.UI.overrideUserInterfaceStyle  │
+│                                                                      │
+│   Appearance.set(m)  ────► writes Ti.App.Properties                  │
+│                            applies Ti.UI.overrideUserInterfaceStyle  │
+│                                                                      │
+│   Appearance.get()   ────► returns 'system' | 'light' | 'dark'       │
+│   Appearance.toggle()────► flips between 'light' and 'dark'          │
+│                                                                      │
+└──────────────────────────────────────────────────────────────────────┘
+                               │
+                               ▼
+┌─ Ti.UI.semanticColorType (runtime) ──────────────────────────────────┐
+│                                                                      │
+│   Light mode  ─►  resolves bg-surface       to surfaceColor.light    │
+│                   resolves text-on-surface  to textColor.light       │
+│                                                                      │
+│   Dark mode   ─►  resolves bg-surface       to surfaceColor.dark     │
+│                   resolves text-on-surface  to textColor.dark        │
+│                                                                      │
+└──────────────────────────────────────────────────────────────────────┘
+                               │
+                               ▼
+┌─ Utility classes in views ───────────────────────────────────────────┐
+│                                                                      │
+│   bg-surface, text-on-surface, bg-border, bg-surface-high, ...       │
+│   Repaint instantly on every Appearance.set(...) call.               │
+│                                                                      │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+`Ti.App.Properties` is the persistence layer — the value written during `set(...)` is what `init()` reads on the next launch. Clearing app storage or reinstalling resets to `'system'`.
+
+## Workflow
+
+The fastest path from zero to a working Light / Dark toggle is three steps. Each one maps to one section of the official `best-practices/1-appearance-setup.md` guide.
 
-Call `Appearance.init()` **once** at app startup, before opening the first window. The standard place is the top of `app/controllers/index.js`.
+### 1. Define semantic colors
+
+Create `app/assets/semantic.colors.json` and register the color names under `theme.extend.colors` in `purgetss/config.cjs`. The class names you use in XML (`bg-surface`, `text-on-surface`, `bg-border`, ...) come from this mapping.
+
+See [semantic-colors.md](./semantic-colors.md) for the JSON schema, the `config.cjs` mapping, nesting rules, and alpha transparency.
+
+### 2. Initialize Appearance at startup
+
+Call `Appearance.init()` **once** before opening the first window. The standard place is the top of `app/controllers/index.js`:
 
 `app/controllers/index.js`
 ```js
@@ -27,22 +83,11 @@ $.navWin.open()
 >
 > Call `Appearance.init()` **before** `$.navWin.open()` (or whichever window you open first). If the window opens first, it will render once against the system default and then flicker to the saved mode when `init()` runs — a visible flash on cold launch.
 
-## Methods
-
-| Method       | Description                                                                 |
-| ------------ | --------------------------------------------------------------------------- |
-| `init()`     | Restore the saved mode from `Ti.App.Properties` and apply it via `Ti.UI.overrideUserInterfaceStyle`. Call once at app startup before opening the first window. |
-| `set(mode)`  | Apply and persist a mode. Accepts `'system'`, `'light'`, or `'dark'`. Any other value is silently ignored. |
-| `get()`      | Returns the current mode as a string: `'system'`, `'light'`, or `'dark'`.   |
-| `toggle()`   | Switch between `'light'` and `'dark'`. Skips `'system'` — if current mode is `'system'` the next call produces `'dark'`. |
-
-All four methods are **synchronous**. They do not fire events; if you need to react to a mode change, call your update logic right after `Appearance.set(...)`.
-
-## Full Settings-view example
+### 3. Build an Appearance toggle
 
-A three-row settings panel — System / Light / Dark — where each row shows a `fa-solid fa-circle-check` icon next to the currently active mode. Tapping a row calls `Appearance.set(...)` and updates the check icons.
+Build a Settings view where users pick `System`, `Light`, or `Dark`. Tapping a row calls `Appearance.set(...)` and updates the check icons.
 
-### View
+#### View
 
 `app/views/settings.xml`
 ```xml
@@ -86,7 +131,7 @@ A three-row settings panel — System / Light / Dark — where each row shows a
 </Alloy>
 ```
 
-### Controller
+#### Controller
 
 `app/controllers/settings.js`
 ```js
@@ -95,16 +140,16 @@ const { Appearance } = require('purgetss.ui')
 // Sync check icons with the mode saved at app startup.
 updateUI(Appearance.get())
 
-const selectDark   = () => selectAppearance('dark')
-const selectLight  = () => selectAppearance('light')
-const selectSystem = () => selectAppearance('system')
+function selectDark()   { selectAppearance('dark') }
+function selectLight()  { selectAppearance('light') }
+function selectSystem() { selectAppearance('system') }
 
-const selectAppearance = (value) => {
+function selectAppearance(value) {
   Appearance.set(value)
   updateUI(value)
 }
 
-const updateUI = (value) => {
+function updateUI(value) {
   $.themeDarkCheck.visible   = (value === 'dark')
   $.themeLightCheck.visible  = (value === 'light')
   $.themeSystemCheck.visible = (value === 'system')
@@ -113,9 +158,24 @@ const updateUI = (value) => {
 
 The background, text, border, and icon colors in the XML come from semantic color classes (`bg-surface`, `bg-surface-high`, `text-on-surface`, `bg-border`, etc.) — see [semantic-colors.md](./semantic-colors.md) for how to wire those up so the whole view flips when `Appearance.set('dark')` fires.
 
-## Lifecycle
+> **Why named functions in Alloy controllers?** Alloy resolves `onClick="selectDark"` by looking up a top-level identifier on the controller scope. Named function declarations (`function selectDark() { ... }`) hoist and are reliably resolvable; arrow functions assigned to `const` are not hoisted and tend to bite you when an XML attribute fires before the binding has executed. The official setup guide uses named functions for this reason.
 
-How the four moving parts — `Appearance.init()`, `Ti.App.Properties`, `Ti.UI.overrideUserInterfaceStyle`, and semantic colors — cooperate:
+## API reference
+
+### Methods
+
+| Method       | Description                                                                 |
+| ------------ | --------------------------------------------------------------------------- |
+| `init()`     | Restore the saved mode from `Ti.App.Properties` and apply it via `Ti.UI.overrideUserInterfaceStyle`. Call once at app startup before opening the first window. |
+| `set(mode)`  | Apply and persist a mode. Accepts `'system'`, `'light'`, or `'dark'`. Any other value is silently ignored. |
+| `get()`      | Returns the current mode as a string: `'system'`, `'light'`, or `'dark'`.   |
+| `toggle()`   | Switch between `'light'` and `'dark'`. Skips `'system'` — if current mode is `'system'` the next call produces `'dark'`. |
+
+All four methods are **synchronous**. They do not fire events; if you need to react to a mode change, call your update logic right after `Appearance.set(...)`.
+
+### Lifecycle
+
+How the four moving parts — `Appearance.init()`, `Ti.App.Properties`, `Ti.UI.overrideUserInterfaceStyle`, and semantic colors — cooperate during a typical session:
 
 ```
 app startup
@@ -143,8 +203,6 @@ app startup
           +-- Preference survives the next cold launch
 ```
 
-`Ti.App.Properties` is the persistence layer — the value written during `set(...)` is what `init()` reads on the next launch. Clearing app storage or reinstalling resets to `'system'`.
-
 > **INFO**
 >
 > `toggle()` intentionally skips `'system'`. If the current mode is `'system'`, calling `toggle()` produces `'dark'`. If you want a three-way cycle (System -> Light -> Dark -> System), build it in userland with `Appearance.get()` + `Appearance.set(...)`; do not expect `toggle()` to do it.

package/skills/purgetss/references/apply-directive.md

@@ -254,6 +254,66 @@ Window: { default: { apply: 'exit-on-close-false bg-blue-500' } }
 
 Use the explicit `default:` wrapper when you also need platform blocks (`ios:`, `android:`) next to it. For the common case of one bundle of defaults, the shorthand reads better.
 
+### Extend mode vs replace mode
+
+> **HEADLINE CHANGE — v7.9.0**
+> This is the headline change of PurgeTSS v7.9.0. Before v7.9.0, `theme.Window` / `theme.View` / `theme.ImageView` still had the framework defaults merged in, which caused gradient ghosting and other surprising overrides. v7.9.0 makes top-level (non-`extend`) configs behave as true replace mode.
+>
+> If you previously used `theme.Window` (no `extend`) and depended on the white background or the iOS `hires: true` / `Ti.UI.SIZE` defaults still being there, you will need to either move that config under `theme.extend.Window` (extend mode) or add the previously-implicit utilities back into your `apply` string.
+
+PurgeTSS follows the Tailwind convention for the three Ti Elements that ship with framework defaults — `Window`, `View`, and `ImageView`:
+
+- **Extend mode** — `theme.extend.Window`, `theme.extend.View`, `theme.extend.ImageView`. Your customization **merges** with the framework defaults. The white Window `backgroundColor`, `Ti.UI.SIZE` width/height on `View`, and iOS `hires: true` on `ImageView` stay in place unless you override them with `apply`. Use this when you want to add to the defaults, not replace them.
+- **Replace mode** — `theme.Window`, `theme.View`, `theme.ImageView` (top level, no `extend`). Your config **replaces** the framework defaults entirely. The white Window background is omitted, the `Ti.UI.SIZE` width/height on `View` is omitted, and the iOS `hires: true` on `ImageView` is omitted. Your `apply` becomes the source of truth for that Ti Element.
+
+Use replace mode when you want full control and do not want a preset mixed in. The canonical case is a Window declared at `theme.Window` with a `backgroundGradient`, where the previously-merged white `backgroundColor` would render on top of the gradient and produce a "ghost" white wash.
+
+`./purgetss/config.cjs - replace mode (v7.9.0+)`
+```javascript
+module.exports = {
+  theme: {
+    Window: {
+      apply: 'bg-gradient-to-b from-blue-500 to-purple-600'
+    }
+  }
+};
+```
+
+`./purgetss/styles/utilities.tss`
+```tss
+'Window': { backgroundGradient: { type: 'linear', colors: [...], startPoint: ..., endPoint: ... } }
+```
+
+Note the missing `backgroundColor: '#FFFFFF'`. Replace mode skipped the framework default, so the gradient renders cleanly. Before v7.9.0 the same config produced:
+
+```tss
+/* Pre-v7.9.0 — ghost white background covering the gradient */
+'Window': { backgroundColor: '#FFFFFF', backgroundGradient: { type: 'linear', colors: [...] } }
+```
+
+If you wanted the framework white background **and** something else on top, that is what extend mode is for:
+
+`./purgetss/config.cjs - extend mode`
+```javascript
+module.exports = {
+  theme: {
+    extend: {
+      Window: {
+        apply: 'exit-on-close-false'
+      }
+    }
+  }
+};
+```
+
+`./purgetss/styles/utilities.tss`
+```tss
+/* Framework default backgroundColor is preserved, exitOnClose merged in */
+'Window': { backgroundColor: '#FFFFFF', exitOnClose: false }
+```
+
+The same extend-vs-replace distinction applies to `View` (`Ti.UI.SIZE` width/height defaults) and `ImageView` (iOS `hires: true` default).
+
 ### Apply Wins Over Static Defaults
 
 If `apply` sets a property that the component already has as a built-in default, the applied value replaces the original instead of both ending up in the final TSS:

package/skills/purgetss/references/arbitrary-values.md

@@ -7,6 +7,47 @@ When you need a one-off value that is not in the defaults, use arbitrary values
 >
 > You cannot use square bracket notation like in Tailwind because Titanium handles platform and conditional statements in `.tss` files differently.
 
+## Class syntax pre-validation
+
+Starting with PurgeTSS v7.8.0, the build runs a pre-validation pass over class names found in XML views and JS controllers before purging. When it spots a malformed arbitrary-value utility, it stops and prints a structured `Class Syntax Error` block so the offending class can be fixed before any TSS is generated. If multiple errors are present, all of them are reported in the same run.
+
+Each error block includes:
+
+- The file path where the offending class lives
+- The line number inside that file
+- The offending class name (as authored)
+- A `Fix:` suggestion with the corrected class name
+
+Example shape:
+
+```
+Class Syntax Error
+  File: app/views/index.xml
+  Line: 12
+  Found: top-(-10)
+  Fix:   -top-(10)
+```
+
+### Detected patterns
+
+The validator catches five narrow, actionable mistakes:
+
+| Pattern                       | Offending input | Suggested fix | Notes                                                            |
+| ----------------------------- | --------------- | ------------- | ---------------------------------------------------------------- |
+| Inverted negative sign        | `top-(-10)`     | `-top-(10)`   | The `-` prefix goes before the rule, not inside the value        |
+| Tailwind-style brackets       | `top-[10px]`    | `top-(10px)`  | PurgeTSS uses parentheses, not square brackets, for arbitrary values |
+| Empty parentheses             | `wh-()`         | (flagged, no auto-fix) | Add a value such as `wh-(10)`                           |
+| Whitespace inside parentheses | `wh-( 200 )`    | `wh-(200)`    | No spaces allowed between `(`, the value, and `)`                |
+| Redundant `px` unit           | `top-(10px)`    | `top-(10)`    | PurgeTSS treats unit-less arbitrary values as pixels             |
+
+### Unknown classes are still silently dropped
+
+The pre-validator only fires on the five patterns above. Any other unknown class — typos, custom utilities not yet declared, vendor classes that are not enabled in `config.cjs` — is **not** reported as a `Class Syntax Error`. Those classes continue to flow into the `// Unused or unsupported classes` comment block in `app.tss`, exactly like before. This keeps the validator focused on actionable mistakes and avoids noise while you sketch out class names.
+
+### v7.8.0 parser fix for negatives inside parentheses
+
+Before v7.8.0, an inverted negative such as `top-(-10)` could be silently misparsed by the arbitrary-value pipeline (the `-` inside the parentheses confused the token matcher, producing wrong or missing TSS output without any warning). v7.8.0 hardens that path: the parser now correctly recognizes `top-(-10)` as authored, classifies it as an inverted-negative-sign error, and surfaces the `Class Syntax Error` block with the `-top-(10)` fix instead of producing silent garbage.
+
 ## Color Properties
 
 You can set arbitrary color values for all available color properties using `hex`, `rgb`, or `rgba` values, directly in XML files or in `config.cjs`.

package/skills/purgetss/references/cli-commands.md

@@ -1,6 +1,12 @@
 # PurgeTSS CLI Commands
 
-> **Info: What's new in v7.5.3 / v7.6.x / v7.7.0**
+> **Info: What's new in v7.5.3 / v7.6.x / v7.7.0 / v7.8.0 / v7.9.0**
+> - **Opacity modifiers on semantic colors (v7.9.0)** — writing `bg-surface/65` (or any opacity modifier on a class mapped to a name in `semantic.colors.json`) now produces a working rule with Light/Dark switching preserved. PurgeTSS auto-derives a `<originalKey>_<alphaPercent>` entry in `semantic.colors.json` with the original `light`/`dark` hex values plus the requested alpha for both modes, then emits the rule against the derived key. Re-runs are idempotent; manual edits with conflicting values halt the build with a `Conflict` error. New alpha entries require one full Titanium build to be picked up — Liveview hot-reload alone does not refresh `semantic.colors.json`.
+> - **Gradient + Window/View/ImageView preset fixes (v7.9.0)** — `theme.Window` / `theme.View` / `theme.ImageView` no longer leak the framework presets (white background, `Ti.UI.SIZE`, iOS `hires: true`) when defined at the top level (replace mode), so a Window declared at `theme.Window` with a `backgroundGradient` no longer ghosts on top of a default `backgroundColor: '#FFFFFF'`. `theme.extend.Window` keeps merging with the defaults as before. Also fixed: tonal palette inversion bug, position-dependent `from`/`to` color ordering after `sort()`, and `bg-gradient-to-X` direction silently dropped when combined with `from-X to-Y` colors.
+> - **Glossary path renamed (v7.9.0, breaking)** — the user-facing glossary output path was renamed from `purgetss/experimental/tailwind-classes/` to `purgetss/glossary/tailwind-classes/`. Tooling or CI that reads from the old path needs updating on upgrade — no transition shim. The `--glossary` flag and command surface are unchanged.
+> - **`images --width <n>` flag (v7.8.0)** — pins Android `mdpi` (= iPhone `@1x`) to a specific pixel width, with larger scales deriving as ×1.5, ×2, ×3, ×4 from that base. Use it for SVG sources from vector editors with disproportionate viewBoxes (Affinity, Illustrator). CLI-only; there is no matching `images:` config property because the right width is per-asset. See [`images` Command](#images-command).
+> - **Class syntax pre-validation (v7.8.0)** — `purgetss` now stops with a structured `Class Syntax Error` block (file + line + suggested fix) when it detects known class-name mistakes: inverted negative sign (`top-(-10)` → `-top-(10)`), Tailwind-style brackets (`top-[10px]` → `top-(10px)`), empty parentheses (`wh-()`), whitespace inside parentheses (`wh-( 200 )`), and redundant `px` unit (`top-(10px)` → `top-(10)`). All offenders are reported in one run. Generic unknown classes still flow into the `// Unused or unsupported classes` block in `app.tss`.
+> - **Negative-values-in-parens parser fix (v7.8.0)** — classes like `top-(-10)`, `mt-(-5)`, and `origin-(-10,-20)` no longer crash with `Cannot read properties of null (reading 'pop')`. The parser now extracts the `(...)` portion first, so a `-` inside the value does not break the split.
 > - **`brand:` config grouped (v7.7.0)** — the flat `brand:` block from v7.6.0 was reorganized into purpose-based sections: `brand.logos`, `brand.padding`, `brand.android`, `brand.ios`, and `brand.colors`. Old projects keep working — newly-generated configs use the grouped form.
 > - **Separate Android brand inputs (v7.7.0)** — `brand` can now use one logo for the general brand set, another for Android launcher icons (`logos.androidLauncher` / `--icon-logo`), and another for Android 12+ splash artwork (`logos.androidSplash` / `--splash-logo`). Drop `logo-icon.*` and `logo-splash.*` into `purgetss/brand/` or set the paths in `config.cjs`.
 > - **Legacy Android splash fallback (v7.7.0)** — `purgetss brand` now regenerates `app/assets/android/default.png` (Alloy) or `Resources/android/default.png` (Classic). `cleanup-legacy` no longer removes `default.png`.
@@ -91,15 +97,14 @@ module.exports = {
       splash: false,         // also generate splash_icon.png × 5
       notification: false    // also generate ic_stat_notify.png × 5
     },
+    ios: {
+      dark: true,            // emit DefaultIcon-Dark.png (set false to skip)
+      tinted: true,          // emit DefaultIcon-Tinted.png (set false to skip)
+      darkBackground: null   // null = transparent per Apple HIG; set a hex like '#111111' for an opaque dark bg
+    },
     colors: {
       background: '#FFFFFF'  // Android adaptive bg + iOS/marketplace flatten
     },
-    // Optional iOS overrides:
-    // ios: {
-    //   dark: false,
-    //   tinted: false,
-    //   darkBackground: '#111111'
-    // },
     confirmOverwrites: true  // prompt before overwriting files (set false to skip)
   },
   images: {
@@ -283,15 +288,14 @@ brand: {
     splash: false,         // also generate splash_icon.png × 5
     notification: false    // also generate ic_stat_notify.png × 5
   },
+  ios: {
+    dark: true,            // emit DefaultIcon-Dark.png (set false to skip)
+    tinted: true,          // emit DefaultIcon-Tinted.png (set false to skip)
+    darkBackground: null   // null = transparent per Apple HIG; set a hex like '#111' for an opaque dark bg
+  },
   colors: {
     background: '#FFFFFF'  // Android adaptive bg + iOS/marketplace flatten
   },
-  // Optional iOS overrides:
-  // ios: {
-  //   dark: false,           // skip DefaultIcon-Dark.png
-  //   tinted: false,         // skip DefaultIcon-Tinted.png
-  //   darkBackground: '#111' // opaque dark bg for DefaultIcon-Dark.png
-  // },
   confirmOverwrites: true  // prompt before overwriting files
 }
 ```
@@ -344,6 +348,7 @@ purgetss images background/                           # re-process one subfolder
 | `--ios` | Only emit iPhone scale variants. Mutually exclusive with `--android`. |
 | `--format <ext>` | Convert all outputs to `webp`, `jpeg`, `png`, `avif`, `gif`, or `tiff`. Default: keep source format. |
 | `--quality <n>` | Quality `0-100` for lossy formats. Default `85`. |
+| `--width <n>` | (v7.8.0) Pin Android `mdpi` (= iPhone `@1x`) to `<n>` pixels wide. Larger scales derive as ×1.5, ×2, ×3, ×4 from that base; height stays proportional to the source's aspect ratio. Integer in `[1, 8192]`. |
 | `--dry-run` | Preview without writing any files. |
 | `--project <path>` | Project root (defaults to cwd). |
 | `-y, --yes` | Skip the overwrite confirmation prompt. |
@@ -353,6 +358,12 @@ purgetss images background/                           # re-process one subfolder
 
 - `[source]` (optional) — path to override auto-discovery. Resolves first against `purgetss/images/` (short paths like `buttons/btn.png`), then against cwd.
 
+### When to use `--width`
+
+Use `--width <n>` for SVG sources from vector editors with disproportionate viewBoxes — common in Affinity, Illustrator, and other design tools where the viewBox does not match the intended display size. Without the flag, every scale derives from the source's natural pixel size as a 4× master, which can produce unexpected output sizes.
+
+When you pass an SVG without `--width`, the command prints a one-time hint and falls back to the legacy 4× behavior. This is CLI-only; there is no matching `images:` config property because the right width is per-asset.
+
 ### Config block
 
 Defaults live under `images:` in `purgetss/config.cjs`:
@@ -375,6 +386,7 @@ purgetss images background/pink-texture.png            # re-process one file (sh
 purgetss images background/                            # re-process one subfolder
 purgetss images --android                              # only Android densities
 purgetss images --format webp --quality 90             # convert all outputs to WebP
+purgetss images logo.svg --width 256                   # pin SVG output to 256 px @1x/mdpi
 purgetss images --dry-run                              # preview
 ```
 
@@ -412,6 +424,29 @@ purgetss semantic --single '#000000' overlayColor     --alpha 50
 
 When `--dark` is omitted, it defaults to the light hex — useful for overlays/glass surfaces where alpha is the only variation.
 
+### Customizing the class name
+
+The auto-mapping uses the most literal Titanium-style transform: strip `Color`, then kebab-case the rest (e.g. `surfaceColor` → `surface`, `textSecondaryColor` → `text-secondary`). If your design system prefers different names — for example `on-surface` instead of `text`, or nesting the surface family under `DEFAULT` / `high` — edit `config.cjs` after running the `--single` batch:
+
+`./purgetss/config.cjs`
+```javascript
+theme: {
+  extend: {
+    colors: {
+      surface: { DEFAULT: 'surfaceColor', high: 'surfaceHighColor' },
+      'on-surface': 'textColor',
+      'on-surface-variant': 'textSecondaryColor',
+      muted: 'textMutedColor',
+      border: 'borderColor',
+      accent: 'accentColor',
+      overlay: 'overlayColor'
+    }
+  }
+}
+```
+
+The next `purgetss build` picks up the renamed classes. Editing one generated mapping is faster than typing the whole structure from scratch. See [semantic-colors.md](./semantic-colors.md) for the full nested-vs-flat discussion (including the `[object Object]` pitfall when nesting without `DEFAULT`).
+
 ### Smart in-place updates
 
 If a `--single` name matches an existing palette shade — e.g. `purgetss semantic --single '#000' amazon500` while palette `amazon` exists — PurgeTSS narrows the operation to an in-place JSON value edit. The entry stays in its original position, and `config.cjs` is left untouched (the palette already maps to that key).
@@ -482,10 +517,10 @@ After copying the fonts, you can use them in Buttons and Labels. For example, fo
 
 ### Available Font Classes
 
-- [fontawesome.tss](https://github.com/macCesar/purgeTSS/blob/master/dist/fontawesome.tss)
-- [materialicons.tss](https://github.com/macCesar/purgeTSS/blob/master/dist/materialicons.tss)
-- [materialsymbols.tss](https://github.com/macCesar/purgeTSS/blob/master/dist/materialsymbols.tss)
-- [framework7icons.tss](https://github.com/macCesar/purgeTSS/blob/master/dist/framework7icons.tss)
+- [fontawesome.tss](https://github.com/macCesar/purgeTSS/blob/main/dist/fontawesome.tss)
+- [materialicons.tss](https://github.com/macCesar/purgeTSS/blob/main/dist/materialicons.tss)
+- [materialsymbols.tss](https://github.com/macCesar/purgeTSS/blob/main/dist/materialsymbols.tss)
+- [framework7icons.tss](https://github.com/macCesar/purgeTSS/blob/main/dist/framework7icons.tss)
 
 ### Copying Specific Font Vendors
 

package/skills/purgetss/references/custom-rules.md

@@ -1,35 +1,49 @@
 # Custom Rules
 
-Custom rules in PurgeTSS let you style Titanium elements, IDs, and classes in `config.cjs`. You can also target specific platforms, devices, or conditional blocks using global variables. Handy when a project spans iOS and Android and you want to keep styles in one place.
+Custom rules in PurgeTSS let you style Titanium elements, IDs, and classes from `config.cjs`. They are the bridge between the utility-first classes you write in XML and the platform-, device-, or condition-specific overrides Titanium projects often need. Because everything lives in a single `config.cjs`, projects that span iOS and Android can keep one source of truth for styling instead of fragmenting rules across multiple `.tss` files.
+
+This file mirrors the official rewrite — section names, examples, and ordering match the upstream docs so cross-referencing stays cheap.
 
 ## Classes, IDs, and Ti Elements
 
-Whether you want to style a Ti Element (also known as a markup element), a custom ID prefixed with a hash (`#`), or a custom class prefixed with a period (`.`), the structure is the same.
+Whether you want to style a Ti Element (a markup element such as `Label`), a custom ID prefixed with `#`, or a custom class prefixed with `.`, the structure inside `config.cjs` is the same. You always declare a key (the selector) whose value is an object containing one or more block keys (`DEFAULT`, `ios`, `android`, `tablet`, `handheld`, or `[if=...]`).
 
 ### Modifier Key
 
-- For Titanium elements, use the exact name of the element, such as `Label`, `Button`, or `ScrollView`.
-- For IDs, use `camelCase` to match the JavaScript convention.
-- For classes, use `kebab-case` to stay compatible with PurgeTSS v6.x and above. For example, use `.my-custom-class-name` instead of `.myCustomClassName`.
-
-> **CAUTION -- PurgeTSS v5 or Earlier Projects**
-> If your project started on PurgeTSS v5 or earlier and you now use 7.x.x or later, set `purge.options.missing` to `true` in `config.cjs`. It will report missing classes at the end of `app.tss` so you can update them to the new naming convention.
+- For Titanium elements, use the **exact name** of the element, such as `Label`, `Button`, or `ScrollView`. The casing must match Titanium's API (e.g. `TextField`, not `textfield` or `Text Field`).
+- For IDs, use `camelCase` to match Alloy's JavaScript convention (e.g. `mainBanner` referenced in XML as `id="mainBanner"`). The selector key inside `config.cjs` includes the `#` prefix.
+- For classes, use `kebab-case` to stay compatible with PurgeTSS v6.x and above. Use `.my-custom-class-name`, not `.myCustomClassName`. The kebab-case requirement is what most legacy projects trip over when they upgrade.
+
+> **CAUTION — Migrating from PurgeTSS v4 or v5 to v7+**
+>
+> If your project started on PurgeTSS v5 or earlier and you are now on 7.x.x or later, the class-naming convention changed (`camelCase` -> `kebab-case`) and the config moved to ESM-style `config.cjs`. The recommended upgrade path is:
+>
+> 1. **Audit current usage.** Set `purge.options.missing` to `true` in `config.cjs`. PurgeTSS will append a list of missing classes at the end of `app.tss` after the next compile — every entry is a class name you still need to migrate.
+> 2. **Rename selectors.** Convert every `.myCustomClassName` to `.my-custom-class-name` in both XML markup and `config.cjs`. The old camelCase names will not match anymore.
+> 3. **Convert config to `.cjs`.** If your project still uses `purgetss.config.js` or a CommonJS-style file with the old layout, rename the file to `config.cjs` and ensure it sits in `./purgetss/`. The single export must be `module.exports = { theme: { ... } }`.
+> 4. **Re-run `purgetss build`.** Verify the missing-classes list at the end of `app.tss` is empty before turning `missing` back off.
+>
+> Skipping any of these steps tends to surface as silently dropped styles at runtime — the app compiles, but selectors no longer match.
 
 ### Default, Platform, Device, or Conditional Blocks
 
-- To generate a global style, use either the lowercase `default` or the uppercase `DEFAULT` keyword.
-- To target a specific platform, use the `ios` or `android` keywords.
-- To target a specific device, use the `tablet` or `handheld` keywords.
-- To target a condition with a global variable, use the `[if=globalVariableName]` keyword.
+Inside any selector you can declare one or more of the following block keys. They translate to TSS query suffixes at compile time:
+
+- **Global style**: use either the lowercase `default` or the uppercase `DEFAULT` keyword. This becomes the bare selector with no platform/device qualifier.
+- **Specific platform**: use `ios` or `android`. These compile to `[platform=ios]` and `[platform=android]` query suffixes.
+- **Specific device**: use `tablet` or `handheld`. These compile to `[formFactor=tablet]` and `[formFactor=handheld]`.
+- **Conditional via global variable**: use `[if=globalVariableName]`. The exact key is preserved in the generated TSS, so you can reference any `Alloy.Globals.*` boolean.
 
 ### Property Values
 
-- For `Titanium` constants, `Alloy Configuration Values`, or `Global Variables`, always enclose them in quotes.
-- For `color` values, you can use `hex`, `8-digit hex`, `rgb(R,G,B)`, `rgba(R,G,B,A)`, `transparent`, or any of the standard color names. Use hex values if you want to avoid issues with the opacity modifier.
-- For `spacing` values, you can use different types of units: `em`, `rem`, `%`, `px`, `dp`, `cm`, or `in`.
-  - `%`, `px`, `cm`, or `in` are passed through without conversion.
-  - `em` or `rem` values are converted with this formula: `value * 16`.
-  - `dp` removes the unit and keeps the value as-is.
+The way you write property values determines how PurgeTSS emits them in the generated TSS. Pay particular attention to quoting — it is the single most common source of confusion.
+
+- For `Titanium` constants, `Alloy` configuration values, or global variables, **always enclose them in quotes** in `config.cjs` (e.g. `'Ti.UI.SIZE'`, `'Alloy.CFG.iPhoneXNotchSize'`). The quotes are stripped in the generated TSS so the constant resolves at runtime — without them, JavaScript would try to evaluate the constant inside `config.cjs`, which fails because Titanium's globals are not available there.
+- For `color` values, you can use `hex`, `8-digit hex` (with alpha), `rgb(R,G,B)`, `rgba(R,G,B,A)`, `transparent`, or any standard color name. Prefer hex values when you plan to use opacity modifiers — `rgba()` and named colors interact awkwardly with opacity utilities.
+- For `spacing` values you can mix unit types. Each unit follows a specific conversion rule:
+  - `%`, `px`, `cm`, and `in` are passed through to TSS without conversion.
+  - `em` and `rem` values are converted with the formula `value * 16` (so `1rem` becomes `16`).
+  - `dp` removes the unit and keeps the numeric value as-is, since Titanium treats unit-less numeric values as density-independent pixels by default.
 
 ## `config.cjs` File Example
 
@@ -81,7 +95,10 @@ module.exports = {
 };
 ```
 
-`./purgetss/styles/utilities.tss`
+## Custom `./purgetss/styles/utilities.tss` File
+
+PurgeTSS reads `config.cjs` and emits a single `utilities.tss` file that Alloy then merges with the rest of the project's styling. The file below shows what the example above generates — note how block keys translate into TSS query suffixes (`[platform=android]`, `[formFactor=tablet]`, `[if=...]`).
+
 ```tss
 /* Property: TextField */
 /* Description: A single line text field. */