@maccesar/titools 3.1.0 → 3.2.0

package/package.json

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

package/skills/purgetss/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: purgetss
-description: "Titanium PurgeTSS utility-first styling toolkit. Use when styling, reviewing, analyzing, or examining Titanium UI with utility classes, configuring config.cjs, creating dynamic components with $.UI.create(), building animations, using grid layouts, setting up icon fonts, or working with TSS styles. AUTO-DETECT: If purgetss/ folder or purgetss/config.cjs exists, this project uses PurgeTSS — invoke this skill BEFORE writing ANY styling code. All styling MUST use PurgeTSS utility classes in XML, NOT custom TSS. PurgeTSS classes look like Tailwind but are NOT Tailwind — verify every class exists before using it. Never use padding on Views (use margins on children), never use flexbox classes, never write manual TSS when a utility class exists."
+description: "Use when working with PurgeTSS, Titanium's utility-first styling toolkit — styling, reviewing, analyzing, or examining Titanium UI with utility classes, configuring config.cjs, creating dynamic components with $.UI.create(), building animations, grid layouts, icon fonts, or TSS styles. AUTO-DETECT: If purgetss/ folder or purgetss/config.cjs exists, invoke BEFORE writing ANY styling code. PurgeTSS classes look like Tailwind but are NOT Tailwind — verify every class exists. Never use padding on Views (use margins on children), never use flexbox classes, never write manual TSS when a utility class exists."
 argument-hint: "[class-name]"
 allowed-tools: Read, Grep, Glob, Edit, Write, Bash(purgetss *), Bash(node *)
 ---
@@ -9,6 +9,46 @@ allowed-tools: Read, Grep, Glob, Edit, Write, Bash(purgetss *), Bash(node *)
 
 Utility-first styling toolkit for Titanium/Alloy mobile apps.
 
+## Required workflow (read before responding)
+
+The SKILL.md alone is an **index** of references. The detail you need
+to give accurate answers lives in the reference files. **Reading this
+SKILL.md is not enough.**
+
+### Step 1 — Open the relevant reference files
+
+| Task involves | Required reading |
+|---|---|
+| Choosing utility classes | [references/class-index.md](references/class-index.md) |
+| Layout (horizontal/vertical/composite, grid) | [references/grid-layout.md](references/grid-layout.md), [references/ui-ux-design.md](references/ui-ux-design.md) |
+| Dynamic components in controllers | [references/dynamic-component-creation.md](references/dynamic-component-creation.md) |
+| Custom values / arbitrary syntax | [references/arbitrary-values.md](references/arbitrary-values.md) |
+| Platform-specific styles (`ios:`, `android:`) | [references/platform-modifiers.md](references/platform-modifiers.md) |
+| Dark/Light mode | [references/semantic-colors.md](references/semantic-colors.md), [references/appearance-module.md](references/appearance-module.md) |
+| Apply directive / class extraction | [references/apply-directive.md](references/apply-directive.md) |
+| Animations | [references/animation-system.md](references/animation-system.md) |
+
+### Step 2 — Output contract
+
+Every utility class you suggest and every styling pattern you describe
+MUST be backed by a citation in the form:
+
+`[source: references/<file>.md]`
+
+Example: *"Use `wh-12` to set width and height to 48px [source: references/class-index.md]"*
+
+### Step 3 — If you must answer from memory
+
+If you write a claim without having read the reference that backs it,
+prepend `FROM_MEMORY (unverified):` to that claim. Do not hide it.
+
+### Banned behaviors
+
+- ❌ Writing utility classes "from memory" without citing any reference
+- ❌ Confusing PurgeTSS classes with Tailwind — they share naming but differ
+- ❌ Marking the answer complete without listing which reference files you read
+- ❌ Suggesting a class without first verifying it exists in `class-index.md`
+
 ## Project Detection
 
 > **️ℹ️ AUTO-DETECTS PURGETSS PROJECTS**
@@ -112,62 +152,6 @@ 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`
-- Separate Android brand inputs — `logos.androidLauncher` / `--icon-logo` for Android launcher icons; `logos.androidSplash` / `--splash-logo` for Android 12+ splash artwork. Drop `logo-icon.*` and `logo-splash.*` into `purgetss/brand/`
-- `--android-adaptive-padding` (default `19%`) and `--android-legacy-padding` (default `10%`) replace the single `--padding`. The shortcut `--padding` now sets both Android paddings to the same value for one run
-- Legacy Android splash fallback regenerated — `app/assets/android/default.png` (Alloy) or `Resources/android/default.png` (Classic). `cleanup-legacy` no longer removes `default.png`
-- New official doc: [Values and Units](references/values-and-units.md) — explains `ti.ui.defaultunit` interpretation of PurgeTSS unitless values
-
-## What's New in v7.6.x
-
-- `brand` command — complete Titanium branding set (launcher icons, adaptive, iOS 18+ Dark/Tinted, marketplace) from logos in `./purgetss/brand/` (v7.6.0)
-- `images` command — multi-density UI images (Android res-*dpi + iPhone @1x/@2x/@3x) from `./purgetss/images/` (v7.6.0)
-- `semantic` command — Titanium semantic colors for Light/Dark mode (palette mode + single mode) (v7.6.0)
-- `brand:` and `images:` config sections auto-injected into older configs (v7.6.0)
-- Percentages as strings (`'15%'`) for self-documenting clarity in brand/images configs (v7.6.0)
-- Confirmation prompt for destructive writes in `brand` / `images` (`y` / `N` / `a`); auto-skipped on non-TTY, with `-y`, or `PURGETSS_YES=1` (v7.6.1)
-- `semantic` command works in Classic projects — writes to `Resources/semantic.colors.json` (v7.6.2)
-
-## What's New in v7.5.3
-
-- Appearance module — Light/Dark/System mode switching with persistence
-- Default font family classes (`font-sans`, `font-serif`, `font-mono`) generated automatically with platform-appropriate values
-- XML validation — detects illegal `--` inside XML comments during pre-validation
-
-## What's New in v7.5.0
-
-- `extend` support for Window, View, and ImageView in `config.cjs`
-- Shorthand `apply` directive normalization
-- Apply directive property deduplication
-- Automatic platform resolution in apply directives
-- Updated Font Awesome to 7.2.0
-- Fixed: `extend.Window` was silently ignored
-- Fixed: Array-type properties (`extendEdges`, `mediaTypes`) bracket notation
-
-## What's New in v7.4.0
-
-- 9 new Animation methods: `transition`, `pulse`, `sequence`, `swap`, `shake`, `snapTo`, `reorder`, `undraggable`, `detectCollisions` (module now has 15 methods total)
-- Snap behavior classes: `snap-back`, `snap-center`, `snap-magnet`
-- `keep-z-index` utility class
-- Enriched callback event object with `action`, `state`, `id`, `targetId`, `index`, `total`, `getTarget()`
-- Delta-based drag for views with rotate/scale transforms
-- Position normalization for draggable views
-- Property inheritance from Animation object for all new methods
-
 > **💡 NEW PROJECT: Clean Up Default app.tss**
 > For new projects created with `purgetss create`, the default `app/styles/app.tss` contains a large commented template.
 >
@@ -460,6 +444,9 @@ purgetss create 'MyApp' -d -v fa
 > - [Animation System](references/animation-system.md) - 15 methods including collision detection, transitions, and sequential animations
 > - [Animation Advanced](references/animation-advanced.md) - Property inheritance, utility classes, implementation rules, complex UI example
 >
+> ### Release Notes
+> - [Version History](references/version-history.md) - Release-by-release feature additions and behavior changes (v7.4.0 → v7.9.0)
+>
 > **💡 TEXT FONTS (Google Fonts, Roboto, etc.)**
 > For text fonts, see [CLI Commands → build-fonts](references/cli-commands.md#purgetss-build-fonts-alias-bf).
 >

package/skills/purgetss/references/EXAMPLES.md

@@ -272,7 +272,7 @@ alloy compile
 
 ### Square Brackets for Arbitrary Values
 
-**❌ WRONG (Using square brackets like Tailwind CSS):**
+**❌ WRONG (Square brackets are not supported):**
 ```xml
 <View class="w-[100px] bg-[#ff0000]" />
 ```
@@ -284,6 +284,13 @@ alloy compile
 
 **PurgeTSS syntax for arbitrary values uses `()` not `[]`.**
 
+> **🚨 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).
+
 **Examples:**
 - `w-(100px)` - Custom width
 - `bg-(#ff0000)` - Custom background color

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

@@ -1,6 +1,6 @@
 # App Icons & Branding
 
-The `purgetss brand` command (introduced in PurgeTSS v7.6.0, restructured in v7.7.0) generates the complete Titanium branding set from a single SVG or PNG logo — with optional Android-specific overrides when you need them: launcher icons across every Android density, the adaptive-icon trio (foreground + background + monochrome), iOS 18+ Dark and Tinted variants, marketplace artwork, and optional notification/splash icons. Alloy and Classic layouts are auto-detected.
+The `purgetss brand` command (introduced in PurgeTSS v7.6.0, restructured in v7.7.0, extended in v7.10.0 with the Google Play Feature Graphic) generates the complete Titanium branding set from a single SVG or PNG logo — with optional Android-specific overrides when you need them: launcher icons across every Android density, the adaptive-icon trio (foreground + background + monochrome), iOS 18+ Dark and Tinted variants, marketplace artwork (including the 1024×500 Feature Graphic for Google Play), and optional notification/splash icons. Alloy and Classic layouts are auto-detected.
 
 For the terse flag reference, see the [`brand` command reference](./cli-commands.md#brand-command). For sibling UI assets, see [Multi-Density Images](./multi-density-images.md).
 
@@ -45,7 +45,8 @@ purgetss/brand/
 ├── logo-mono.svg         optional — monochrome layer + notifications
 ├── logo-dark.svg         optional — iOS 18+ dark variant
 ├── logo-splash.svg       optional — Android 12+ splash icon override
-└── logo-tinted.svg       optional — iOS 18+ tinted variant
+├── logo-tinted.svg       optional — iOS 18+ tinted variant
+└── logo-feature.svg      optional — Google Play Feature Graphic (1024×500) override
 ```
 
 Only `logo.svg` (or `logo.png`) is required. Everything else is **opt-in refinement**:
@@ -58,6 +59,7 @@ Only `logo.svg` (or `logo.png`) is required. Everything else is **opt-in refinem
 | `logo-splash.svg` / `.png` | Optional | Android 12+ `splash_icon.png` artwork (only used when `--splash` / `android.splash: true`). | Falls back to the launcher artwork. |
 | `logo-dark.svg` / `.png` | Optional | iOS 18+ Dark appearance variant. | Main logo on a transparent background (Apple HIG default). |
 | `logo-tinted.svg` / `.png` | Optional | iOS 18+ Tinted appearance variant. | Grayscale of the main logo on black. |
+| `logo-feature.svg` / `.png` | Optional | Google Play Feature Graphic (1024×500). Use when the Play Store banner should differ from the main app icon (e.g. logo + tagline lockup that fills the wider rectangular canvas). | Main logo is centered inside the banner with configured vertical padding. |
 
 Provide a dedicated `logo-icon` when the main logo is a horizontal wordmark, a vertical lockup, or anything else that looks fine in a 1024×1024 branding canvas but feels cramped inside an Android launcher mask.
 
@@ -67,6 +69,8 @@ Provide a dedicated `logo-splash` when the Android 12+ splash should use a diffe
 
 Provide a dedicated `logo-dark` when dark-mode brand guidelines use a different lockup or color treatment; provide `logo-tinted` when you want a pre-simplified silhouette that tints better than a naive grayscale of the colored version.
 
+Provide a dedicated `logo-feature` when the Google Play Feature Graphic (1024×500) should use a different composition than the main app icon — for example a logo-plus-tagline lockup or a wider artwork that takes advantage of the rectangular canvas instead of being constrained to the centered square.
+
 > **INFO**
 >
 > Prefer SVG for the master
@@ -87,7 +91,8 @@ brand: {
   logos: {
     primary: './docs/snap-logo.svg',
     androidLauncher: './docs/snap-app-icon.svg',
-    monochrome: './docs/snap-logo-mono.svg'
+    monochrome: './docs/snap-logo-mono.svg',
+    featureGraphic: './docs/snap-feature.svg'   // optional — Google Play Feature Graphic
   }
 }
 ```
@@ -110,9 +115,10 @@ brand: {
     // iosTinted: './docs/logo-tinted.svg'
   },
   padding: {
-    ios: '4%',             // iOS aesthetic padding. Range 2-8%. No launcher mask.
-    androidLegacy: '10%',  // legacy ic_launcher.png padding %
-    androidAdaptive: '19%' // adaptive icon safe-zone %. Spec floor 19.44%.
+    ios: '4%',              // iOS aesthetic padding. Range 2-8%. No launcher mask.
+    androidLegacy: '10%',   // legacy ic_launcher.png padding %
+    androidAdaptive: '19%', // adaptive icon safe-zone %. Spec floor 19.44%.
+    featureGraphic: '12%'   // vertical padding for MarketplaceArtworkFeature.png (1024×500)
   },
   android: {
     splash: false,         // also generate splash_icon.png × 5
@@ -145,6 +151,7 @@ All `logos.*` keys are optional path overrides. If you omit them, PurgeTSS auto-
 | `logos.monochrome` | `purgetss/brand/logo-mono.svg` | Android themed icons + notification icons. |
 | `logos.iosDark` | `purgetss/brand/logo-dark.svg` | iOS dark variant. |
 | `logos.iosTinted` | `purgetss/brand/logo-tinted.svg` | iOS tinted variant. |
+| `logos.featureGraphic` | `purgetss/brand/logo-feature.svg` | Google Play Feature Graphic source (1024×500 rectangular canvas). |
 
 ### `brand.padding`
 
@@ -155,6 +162,7 @@ All padding values accept either numbers or percentage strings like `'19%'`.
 | `padding.ios` | `'4%'` | Visual inset for `DefaultIcon-ios.png`, `DefaultIcon-Dark.png`, `DefaultIcon-Tinted.png`, marketplace artwork. |
 | `padding.androidLegacy` | `'10%'` | Visual inset for legacy `ic_launcher.png`. |
 | `padding.androidAdaptive` | `'19%'` | Visual inset for adaptive Android foreground (`ic_launcher_foreground.png`). Adjust this first when icons look cropped inside launcher masks. |
+| `padding.featureGraphic` | `'12%'` | Vertical padding (top + bottom) for `MarketplaceArtworkFeature.png` (1024×500 Google Play banner). The logo is rendered as a square block of side `500 - 2 × pad` centered horizontally and vertically. Lower it for a more impactful banner; raise it if the logo looks cramped against the top or bottom edge on smaller Play Store crops. |
 
 ### `brand.android`
 
@@ -185,6 +193,35 @@ If omitted, PurgeTSS behaves as if `ios.dark = true`, `ios.tinted = true`, `ios.
 | --- | --- | --- |
 | `confirmOverwrites` | `true` | When `false`, the `[y/N/a]` prompt is skipped. |
 
+### Upgrading from pre-7.7.0 configs
+
+In v7.7.0, the `brand:` block was reorganized into grouped subsections (`logos`, `padding`, `android`, `ios`, `colors`). Since **v7.10.2**, if your `config.cjs` still uses the original flat layout, PurgeTSS auto-migrates it **in memory on every run** — your old config keeps working without any change on disk.
+
+| Pre-7.7.0 flat key | Current grouped key |
+| --- | --- |
+| `brand.padding: <number\|string>` (single value) | `brand.padding.androidLegacy` **and** `brand.padding.androidAdaptive` (same value applied to both) |
+| `brand.iosPadding` | `brand.padding.ios` |
+| `brand.bgColor` | `brand.colors.background` |
+| `brand.darkBgColor` | `brand.ios.darkBackground` |
+| `brand.notification` | `brand.android.notification` |
+| `brand.splash` | `brand.android.splash` |
+
+If both legacy and grouped keys are present for the same property, the **grouped key wins**.
+
+On first encounter per session, PurgeTSS prints a one-time deprecation notice listing the legacy keys it migrated:
+
+```text
+::PurgeTSS:: Legacy brand: schema detected in purgetss/config.cjs — auto-migrated in memory:
+     • brand.padding: 15 → brand.padding.androidLegacy + brand.padding.androidAdaptive
+     • brand.iosPadding → brand.padding.ios
+     • brand.bgColor → brand.colors.background
+     Update purgetss/config.cjs to the new grouped schema to silence this warning.
+```
+
+The notice is suppressed once you update the file to the grouped layout. Auto-migration is purely transitional and may be removed in a future major version, so a one-time update to your `config.cjs` is recommended.
+
+Prior to v7.10.2, projects on the flat layout crashed auto-purge with `TypeError: Cannot create property 'ios' on number '15'` because `brand.padding` was a number rather than an object. v7.10.2 normalizes the shape before defaults are applied.
+
 ## Overwrite confirmation
 
 `brand` writes directly into the project, so it asks before overwriting anything:
@@ -224,6 +261,7 @@ The output is automatically routed to the right directory for your project layou
 ├── DefaultIcon-Tinted.png          ← 1024×1024, iOS 18+ tinted (grayscale on black)
 ├── iTunesConnect.png               ← 1024×1024, App Store submission
 ├── MarketplaceArtwork.png          ← 512×512, Google Play submission
+├── MarketplaceArtworkFeature.png   ← 1024×500, Google Play Feature Graphic (v7.10.0)
 └── app/
     └── assets/android/
         ├── default.png             ← legacy Titanium Android splash fallback (v7.7.0)
@@ -243,6 +281,7 @@ The output is automatically routed to the right directory for your project layou
 ```text
 <project>/
 ├── DefaultIcon.png  DefaultIcon-ios.png  ...     ← same root-level files as Alloy
+├── MarketplaceArtworkFeature.png   ← 1024×500, Google Play Feature Graphic (v7.10.0)
 ├── Resources/
 │   └── android/default.png         ← legacy Titanium Android splash fallback (v7.7.0)
 └── platform/
@@ -343,9 +382,46 @@ purgetss brand --no-dark --no-tinted
 >
 > Until that PR lands, after your first iOS build you may need to add the two PNGs manually into `build/iphone/Assets.xcassets/AppIcon.appiconset/` in Xcode (via the "Appearance" column in the asset catalog editor). Once #14122 merges, the command becomes fully end-to-end.
 
+## Google Play Feature Graphic (v7.10.0)
+
+Since v7.10.0, `purgetss brand` also generates `MarketplaceArtworkFeature.png` — the **1024×500** banner that Google Play shows above the app description on the Play Store listing. It's submission artwork only: the file is written to the project root for upload via Play Console; it is **not** bundled into the APK.
+
+### How the source is chosen
+
+PurgeTSS resolves the Feature Graphic source in this order (first match wins):
+
+1. CLI `--feature-logo <path>` for the current run.
+2. `brand.logos.featureGraphic` in `config.cjs`.
+3. Auto-discovered `purgetss/brand/logo-feature.{svg,png}`.
+4. The main logo (centered inside the 1024×500 canvas with the configured vertical padding).
+
+```bash
+purgetss brand --feature-logo ./docs/feature.svg
+```
+
+Drop a dedicated logo when you want a logo + tagline lockup or a wider artwork that takes advantage of the rectangular canvas. Otherwise the main `logo.svg` is centered as a square block — fine for most apps.
+
+### Padding
+
+The default vertical padding is `12%` (top + bottom). Override per run with `--feature-graphic-padding <n>` (integer `0-40`), or persist it in `brand.padding.featureGraphic`:
+
+```bash
+purgetss brand --feature-graphic-padding 8
+```
+
+```javascript
+brand: {
+  padding: {
+    featureGraphic: '8%'
+  }
+}
+```
+
+The logo is rendered as a square block of side `500 - 2 × pad` and centered horizontally on the 1024-wide canvas. Lower the padding for a more impactful banner; raise it if the logo looks cramped against the top or bottom edge on smaller Play Store crops.
+
 ## Brand color
 
-The `--bg-color` flag (or `brand.bgColor` in config) controls three things at once:
+The `--bg-color` flag (or `brand.colors.background` in config) controls three things at once:
 
 1. The **Android adaptive background layer**: a solid color that fills the full 108dp canvas behind your logo.
 2. The **iOS alpha flatten** for `DefaultIcon-ios.png`. Apple rejects transparent App Store icons, so the logo is flattened on this color.
@@ -510,10 +586,11 @@ All 5 Android densities, marketplace artwork, and iOS variants regenerate in one
 | Flag | Purpose |
 | --- | --- |
 | `--bg-color <hex>` | Background color for Android adaptive + iOS/marketplace flatten. |
-| `--padding <n>` | Shortcut: sets BOTH Android paddings to the same value for one run. |
+| `--padding <n>` | Shortcut: sets BOTH Android paddings to the same value for one run. Fixed in v7.10.0 — previously only fed `androidAdaptivePadding`, leaving `androidLegacyPadding` at its own config value. |
 | `--android-adaptive-padding <n>` | Adaptive icon safe-zone % (default `19`). |
 | `--android-legacy-padding <n>` | Legacy `ic_launcher.png` padding % (default `10`). |
 | `--ios-padding <n>` | iOS aesthetic padding % (range `2–8`, default `4`). |
+| `--feature-graphic-padding <n>` | (v7.10.0) Vertical padding for `MarketplaceArtworkFeature.png` (range `0-40`, default `12`). |
 
 **Optional asset types**
 
@@ -532,6 +609,7 @@ All 5 Android densities, marketplace artwork, and iOS variants regenerate in one
 | `--dark-bg-color <hex>` | Opaque dark bg for `DefaultIcon-Dark.png` (default: transparent per Apple HIG). |
 | `--splash-logo <path>` | Override `purgetss/brand/logo-splash.{svg,png}` for Android 12+ splash artwork. |
 | `--tinted-logo <path>` | Override `purgetss/brand/logo-tinted.{svg,png}`. |
+| `--feature-logo <path>` | (v7.10.0) Override `purgetss/brand/logo-feature.{svg,png}` for the Google Play Feature Graphic. |
 | `--no-dark` | Skip `DefaultIcon-Dark.png`. |
 | `--no-tinted` | Skip `DefaultIcon-Tinted.png`. |
 
@@ -552,14 +630,16 @@ All 5 Android densities, marketplace artwork, and iOS variants regenerate in one
 ### Examples
 
 ```bash
-purgetss brand                                          # uses purgetss/brand/logo.svg + config
-purgetss brand --bg-color "#0B1326"                     # override bg color
-purgetss brand --icon-logo ./docs/app-icon.svg          # dedicated square Android launcher mark
-purgetss brand --splash --splash-logo ./docs/splash.svg # custom Android 12+ splash artwork
-purgetss brand --notification --splash                  # add notification + splash
-purgetss brand --no-tinted                              # skip iOS 18+ tinted variant
-purgetss brand --dry-run                                # preview without writing
-purgetss brand --cleanup-legacy --dry-run               # preview legacy cleanup
+purgetss brand                                            # uses purgetss/brand/logo.svg + config
+purgetss brand --bg-color "#0B1326"                       # override bg color
+purgetss brand --icon-logo ./docs/app-icon.svg            # dedicated square Android launcher mark
+purgetss brand --splash --splash-logo ./docs/splash.svg   # custom Android 12+ splash artwork
+purgetss brand --feature-logo ./docs/feature.svg          # custom Google Play Feature Graphic (v7.10.0)
+purgetss brand --feature-graphic-padding 8                # tighter Feature Graphic padding (v7.10.0)
+purgetss brand --notification --splash                    # add notification + splash
+purgetss brand --no-tinted                                # skip iOS 18+ tinted variant
+purgetss brand --dry-run                                  # preview without writing
+purgetss brand --cleanup-legacy --dry-run                 # preview legacy cleanup
 ```
 
 ## Community-Discovered Patterns

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

@@ -68,6 +68,31 @@ theme: {
 '.btn-primary': { backgroundColor: '#22c55e', borderColor: '#bbf7d0', color: '#dcfce7', textColor: '#dcfce7' }
 ```
 
+## Use Icon Font Classes (v7.10.0)
+
+Since v7.10.0, icon fonts bundled with PurgeTSS — FontAwesome (`fas`, `fab`, `fa-*`), Material Icons (`mi-*`), Material Symbols (`ms-*`), and Framework7 (`f7-*`) — can be referenced inside `apply` **without running `build-fonts` first**. The directive resolves these classes against the bundled `dist/*.tss` files, so the font family and the glyph are merged into the generated rule alongside the rest of the utilities.
+
+`./purgetss/config.cjs`
+```javascript
+module.exports = {
+  theme: {
+    '.close-button': {
+      apply: 'fas fa-times-circle wh-12 text-gray-700'
+    }
+  }
+};
+```
+
+`./purgetss/styles/utilities.tss`
+```tss
+'.close-button': { color: '#374151', textColor: '#374151', width: 48, height: 48, font: { fontFamily: 'FontAwesome7Free-Solid' }, text: '', title: '' }
+```
+
+The same lookup runs for `mi-*`, `ms-*`, and `f7-*` classes. If the project ships its own `purgetss/styles/fontawesome.tss` (for example, FontAwesome Pro or Beta), that file takes precedence over the bundled default — matching the precedence order used when the same icon class appears directly in XML.
+
+> **PRE-v7.10.0 BEHAVIOR**
+> Before v7.10.0, those icon font classes were silently dropped from `apply`-generated rules. `apply: 'fas fa-times-circle wh-12 ...'` produced every utility **except** the FontAwesome family and the icon glyph. If a project worked around this by running `build-fonts` first, that workaround is no longer required.
+
 ## Use Arbitrary Values
 
 You can use [Arbitrary Values](./arbitrary-values.md) to define your custom classes.
@@ -261,7 +286,7 @@ Use the explicit `default:` wrapper when you also need platform blocks (`ios:`,
 >
 > 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`:
+The three Ti Elements that ship with framework defaults — `Window`, `View`, and `ImageView` — support two declaration modes depending on where they are placed in `config.cjs`:
 
 - **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.

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

@@ -5,7 +5,7 @@ When you need a one-off value that is not in the defaults, use arbitrary values
 > **INFO**
 > To generate an arbitrary style, use parentheses notation with almost any default utility class.
 >
-> You cannot use square bracket notation like in Tailwind because Titanium handles platform and conditional statements in `.tss` files differently.
+> Square bracket notation (`[10px]`) is **not supported** because Titanium handles platform and conditional statements in `.tss` files differently. Use parentheses (`(10px)`) instead.
 
 ## Class syntax pre-validation
 
@@ -35,7 +35,7 @@ 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 |
+| Square-bracket notation       | `top-[10px]`    | `top-(10px)`  | PurgeTSS uses parentheses, not square brackets, for arbitrary values (v7.10.1 reworded the error from `Tailwind-style brackets "[ ]"` to `Square brackets "[ ]" are not supported`) |
 | 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             |
@@ -48,6 +48,76 @@ The pre-validator only fires on the five patterns above. Any other unknown class
 
 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.
 
+## Arbitrary nesting depth in `theme` objects (v7.10.0)
+
+Since v7.10.0, property emission walks nested `theme.*` values **recursively** instead of stopping at level 2, so deeply nested color families, gradients, and background gradients now flatten into class suffixes without being silently dropped.
+
+Before v7.10.0:
+
+```javascript
+// pre-v7.10.0 — only colors.brand was reached; .primary.500 was silently dropped
+theme: {
+  extend: {
+    colors: {
+      brand: {
+        primary: { 500: '#3b82f6', 700: '#1d4ed8' }
+      }
+    }
+  }
+}
+```
+
+The classes `bg-brand-primary-500`, `text-brand-primary-700`, etc. were **not** generated.
+
+From v7.10.0 onward:
+
+```javascript
+// v7.10.0+ — recursive walk emits the full path
+theme: {
+  extend: {
+    colors: {
+      brand: {
+        primary: { 500: '#3b82f6', 700: '#1d4ed8' }
+      }
+    }
+  }
+}
+```
+
+```tss
+/* utilities.tss */
+'.bg-brand-primary-500': { backgroundColor: '#3b82f6' }
+'.bg-brand-primary-700': { backgroundColor: '#1d4ed8' }
+'.text-brand-primary-500': { color: '#3b82f6', textColor: '#3b82f6' }
+/* ...and every other color property */
+```
+
+The same recursive emission applies to `backgroundGradient` and `backgroundSelectedGradient` definitions inside `theme.extend`.
+
+### Default modifier keys collapse silently
+
+Three special keys — `default`, `global`, `DEFAULT` — collapse without contributing to the class-name suffix. That lets you keep a default variant alongside named variants without polluting the class name:
+
+```javascript
+theme: {
+  extend: {
+    colors: {
+      surface: {
+        DEFAULT: '#f9fafb',  // emits .bg-surface (no suffix)
+        muted: '#e5e7eb'     // emits .bg-surface-muted
+      }
+    }
+  }
+}
+```
+
+```tss
+'.bg-surface':       { backgroundColor: '#f9fafb' }
+'.bg-surface-muted': { backgroundColor: '#e5e7eb' }
+```
+
+If you have a project that previously kept color shades only at depth ≤ 2 to avoid the silent-drop behavior, you can now restructure them by domain without paying for nesting.
+
 ## 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/class-categories.md

@@ -151,7 +151,7 @@ Complete inventory of all class prefixes organized by functional category. For n
 | `touch` | `touch-enabled`, `touch-enabled-false` | Boolean |
 | `clip` | `clip-enabled`, `clip-enabled-false` | Boolean (iOS) |
 | `interactive-dismiss` | `interactive-dismiss-mode-enabled`, `*-false` | Boolean (iOS) |
-| `large-title` | `large-title-enabled`, `large-title-enabled-false` | Boolean (iOS). Must pair with `extend-edges-all` and `auto-adjust-scroll-view-insets` when using ScrollView — see [apply-directive.md](apply-directive.md) Community-Discovered Patterns |
+| `large-title` | `large-title-enabled`, `large-title-enabled-false` | Boolean (iOS). Must pair with `extend-edges-all` and `auto-adjust-scroll-view-insets` when using ScrollView — full pattern, global-defaults recipe, TabGroup behavior, and the `content-w-screen` / `content-h-auto` ScrollView pairing live in [`ios-large-titles.md`](ios-large-titles.md). |
 | `overlay` | `overlay-enabled`, `overlay-enabled-false` | Boolean (iOS) |
 | `toolbar` | `toolbar-enabled`, `toolbar-enabled-false` | Boolean |
 | `submit` | `submit-enabled`, `submit-enabled-false` | Boolean |

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

@@ -221,10 +221,11 @@ purgetss brand path/to/logo.svg             # positional logo path override
 | Flag | Purpose |
 | --- | --- |
 | `--bg-color <hex>` | Background color for Android adaptive + iOS/marketplace flatten. |
-| `--padding <n>` | Shortcut: sets BOTH Android paddings to the same value for one run. |
+| `--padding <n>` | Shortcut: sets BOTH Android paddings to the same value for one run. Fixed in v7.10.0 — previously only fed `androidAdaptivePadding`, leaving `androidLegacyPadding` at its own config value. |
 | `--android-adaptive-padding <n>` | Adaptive icon safe-zone % (default `19`). |
 | `--android-legacy-padding <n>` | Legacy `ic_launcher.png` padding % (default `10`). |
 | `--ios-padding <n>` | iOS aesthetic padding % (range `2-8`, default `4`). |
+| `--feature-graphic-padding <n>` | (v7.10.0) Vertical padding for `MarketplaceArtworkFeature.png` (range `0-40`, default `12`). |
 
 **Optional asset types**
 
@@ -243,6 +244,7 @@ purgetss brand path/to/logo.svg             # positional logo path override
 | `--dark-bg-color <hex>` | Opaque dark bg for `DefaultIcon-Dark.png` (default: transparent per Apple HIG). |
 | `--splash-logo <path>` | Override `purgetss/brand/logo-splash.{svg,png}` for Android 12+ splash artwork. |
 | `--tinted-logo <path>` | Override `purgetss/brand/logo-tinted.{svg,png}`. |
+| `--feature-logo <path>` | (v7.10.0) Override `purgetss/brand/logo-feature.{svg,png}` for the Google Play Feature Graphic (1024×500). |
 | `--no-dark` | Skip `DefaultIcon-Dark.png`. |
 | `--no-tinted` | Skip `DefaultIcon-Tinted.png`. |
 
@@ -277,12 +279,14 @@ brand: {
     // androidSplash: './docs/splash.svg',
     // monochrome: './docs/logo-mono.svg',
     // iosDark: './docs/logo-dark.svg',
-    // iosTinted: './docs/logo-tinted.svg'
+    // iosTinted: './docs/logo-tinted.svg',
+    // featureGraphic: './docs/logo-feature.svg'  // Google Play 1024×500 banner (v7.10.0)
   },
   padding: {
-    ios: '4%',             // iOS aesthetic padding. Range 2-8%.
-    androidLegacy: '10%',  // legacy ic_launcher.png padding %
-    androidAdaptive: '19%' // adaptive icon safe-zone %. Spec floor 19.44%.
+    ios: '4%',              // iOS aesthetic padding. Range 2-8%.
+    androidLegacy: '10%',   // legacy ic_launcher.png padding %
+    androidAdaptive: '19%', // adaptive icon safe-zone %. Spec floor 19.44%.
+    featureGraphic: '12%'   // MarketplaceArtworkFeature.png vertical padding (v7.10.0)
   },
   android: {
     splash: false,         // also generate splash_icon.png × 5
@@ -309,14 +313,16 @@ The recommended workflow is convention-first: drop files in `purgetss/brand/`, l
 ### Examples
 
 ```bash
-purgetss brand                                          # uses purgetss/brand/logo.svg + config
-purgetss brand --bg-color "#0B1326"                     # override bg color
-purgetss brand --icon-logo ./docs/app-icon.svg          # dedicated square Android launcher mark
-purgetss brand --splash --splash-logo ./docs/splash.svg # custom Android 12+ splash artwork
-purgetss brand --notification --splash                  # add notification + splash
-purgetss brand --no-tinted                              # skip iOS 18+ tinted variant
-purgetss brand --dry-run                                # preview without writing
-purgetss brand --cleanup-legacy --dry-run               # preview legacy cleanup
+purgetss brand                                            # uses purgetss/brand/logo.svg + config
+purgetss brand --bg-color "#0B1326"                       # override bg color
+purgetss brand --icon-logo ./docs/app-icon.svg            # dedicated square Android launcher mark
+purgetss brand --splash --splash-logo ./docs/splash.svg   # custom Android 12+ splash artwork
+purgetss brand --feature-logo ./docs/feature.svg          # custom Google Play Feature Graphic (v7.10.0)
+purgetss brand --feature-graphic-padding 8                # tighter Feature Graphic padding (v7.10.0)
+purgetss brand --notification --splash                    # add notification + splash
+purgetss brand --no-tinted                                # skip iOS 18+ tinted variant
+purgetss brand --dry-run                                  # preview without writing
+purgetss brand --cleanup-legacy --dry-run                 # preview legacy cleanup
 ```
 
 ### Android output groups
@@ -349,6 +355,9 @@ purgetss images background/                           # re-process one subfolder
 | `--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]`. |
+| `--opacity <n>` | (v7.10.0) Multiply alpha of every density by `n/100`. Integer in `[0, 100]`. With `--format jpeg`, alpha flattens on white. |
+| `--padding <n>` | (v7.10.0) Shrink the rendered image inside each density canvas by `n%` symmetric borders. Integer in `[0, 40]`. |
+| `--output <relpath>` | (v7.10.0) Override the basename and subpath relative to each platform's `images/` root. |
 | `--dry-run` | Preview without writing any files. |
 | `--project <path>` | Project root (defaults to cwd). |
 | `-y, --yes` | Skip the overwrite confirmation prompt. |
@@ -364,6 +373,16 @@ Use `--width <n>` for SVG sources from vector editors with disproportionate view
 
 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.
 
+### When to use `--opacity`, `--padding`, `--output` (v7.10.0)
+
+The three v7.10.0 flags are designed for **placeholder / default ImageView** workflows where the source asset is a brand or logo you want to re-render at reduced opacity and/or with extra breathing room — without editing the source file itself.
+
+- `--opacity` is a runtime alpha multiplier. JPEG flattens the result on white; PNG/WebP/AVIF keep alpha.
+- `--padding` shrinks the rendered image inside each density canvas, keeping the canvas dimensions and filling the difference with transparent pixels.
+- `--output` retargets the basename and subpath, useful when the source lives outside `purgetss/images/` (e.g. `purgetss/brand/`).
+
+All three are **CLI-only by design** — no `config.cjs` equivalent — because they describe per-asset render decisions, not project-wide settings.
+
 ### Config block
 
 Defaults live under `images:` in `purgetss/config.cjs`:
@@ -387,6 +406,11 @@ purgetss images background/                            # re-process one subfolde
 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 logo.svg --opacity 50 --format png     # 50% alpha placeholder (v7.10.0)
+purgetss images logo.svg --padding 15 --format png     # add 15% breathing room (v7.10.0)
+purgetss images purgetss/brand/logo.svg \
+    --opacity 30 --padding 15 \
+    --output 'logos/default-image' --format png         # placeholder under custom path (v7.10.0)
 purgetss images --dry-run                              # preview
 ```
 

package/skills/purgetss/references/customization-deep-dive.md

@@ -37,9 +37,10 @@ module.exports = {
   brand: {
     logos: {},  // empty = auto-discovers from purgetss/brand/
     padding: {
-      ios: '4%',             // iOS aesthetic padding. Range 2-8%.
-      androidLegacy: '10%',  // legacy ic_launcher.png padding %
-      androidAdaptive: '19%' // adaptive icon safe-zone %. Spec floor 19.44%.
+      ios: '4%',              // iOS aesthetic padding. Range 2-8%.
+      androidLegacy: '10%',   // legacy ic_launcher.png padding %
+      androidAdaptive: '19%', // adaptive icon safe-zone %. Spec floor 19.44%.
+      featureGraphic: '12%'   // MarketplaceArtworkFeature.png vertical padding (v7.10.0)
     },
     android: {
       splash: false,         // also generate splash_icon.png × 5
@@ -59,6 +60,8 @@ module.exports = {
     quality: 85,             // JPEG/WebP/AVIF quality (0-100)
     format: null,            // null = keep original; 'webp' | 'jpeg' | 'png' to convert every image
     confirmOverwrites: true  // prompt before overwriting files (set false to skip)
+    // Note: --width (v7.8.0) and --opacity / --padding / --output (v7.10.0) are CLI-only
+    //       by design — those decisions are per-asset, not project-wide.
   },
   theme: {
     extend: {}
@@ -78,12 +81,15 @@ The config file has four main sections: `purge`, `brand`, `images`, and `theme`.
 
 For `brand`, the structure is grouped by purpose (introduced in v7.7.0, refined since):
 
-- `logos`: optional path overrides when you do not want to rely on `purgetss/brand/` auto-discovery
-- `padding`: visual sizing for iOS, Android legacy, and Android adaptive icons
+- `logos`: optional path overrides when you do not want to rely on `purgetss/brand/` auto-discovery — including `featureGraphic` for the Google Play 1024×500 banner (v7.10.0)
+- `padding`: visual sizing for iOS, Android legacy, Android adaptive icons, and the Feature Graphic banner (v7.10.0)
 - `android`: Android-only optional outputs such as `splash_icon.png` and notification icons
 - `ios`: iOS-only variant toggles (`dark`, `tinted`) and the optional `darkBackground` color
 - `colors`: shared color settings such as the adaptive background and iOS flatten color
 
+> **INFO — Pre-7.7.0 flat configs auto-migrate**
+> Since v7.10.2, projects on the flat `brand:` schema (`brand.padding: <number>`, `brand.iosPadding`, `brand.bgColor`, etc.) auto-migrate in memory on every run. The grouped key always wins when both forms coexist, and a one-time deprecation notice lists the migrated keys. Update `config.cjs` to the grouped schema to silence the notice. See [App Icons & Branding → Upgrading from pre-7.7.0 configs](./app-branding.md#upgrading-from-pre-7-7-0-configs).
+
 For the property-by-property reference, see [Configurable Properties](./configurable-properties.md).
 
 ### Overriding logo paths
@@ -94,12 +100,13 @@ By default, PurgeTSS auto-discovers logo files from `purgetss/brand/`. If you wa
 module.exports = {
   brand: {
     logos: {
-      primary: './my-logos/main.svg',         // overrides auto-discovered logo.svg
-      androidLauncher: './my-logos/icon.svg', // overrides auto-discovered logo-icon.svg
-      androidSplash: './my-logos/splash.svg', // overrides auto-discovered logo-splash.svg
-      monochrome: './my-logos/mono.svg',      // overrides auto-discovered logo-mono.svg
-      iosDark: './my-logos/dark.svg',         // overrides auto-discovered logo-dark.svg
-      iosTinted: './my-logos/tinted.svg'      // overrides auto-discovered logo-tinted.svg
+      primary: './my-logos/main.svg',          // overrides auto-discovered logo.svg
+      androidLauncher: './my-logos/icon.svg',  // overrides auto-discovered logo-icon.svg
+      androidSplash: './my-logos/splash.svg',  // overrides auto-discovered logo-splash.svg
+      monochrome: './my-logos/mono.svg',       // overrides auto-discovered logo-mono.svg
+      iosDark: './my-logos/dark.svg',          // overrides auto-discovered logo-dark.svg
+      iosTinted: './my-logos/tinted.svg',      // overrides auto-discovered logo-tinted.svg
+      featureGraphic: './my-logos/feature.svg' // overrides auto-discovered logo-feature.svg (v7.10.0)
     }
   }
 };

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

@@ -46,7 +46,6 @@ $.UI.create('ComponentType', {
 function createThemeCard(themeName, themeTitle, imagePath) {
   return $.UI.create('View', {
     // View properties
-    valor: themeName,
     title: themeTitle, // Add title for TTS support
 
     // PurgeTSS utility classes

package/skills/purgetss/references/migration-guide.md

@@ -1,11 +1,168 @@
 # Migration Guide
 
-This guide mirrors the official PurgeTSS changelog (see the project `README.md` / `docs/index.md`). It walks through the upgrade-relevant changes from v7.2.6 through v7.6.0, flags breaking changes, and links each section to the reference files that cover the new surface area in depth.
+This guide mirrors the official PurgeTSS changelog (see the project `README.md` / `docs/index.md`). It walks through the upgrade-relevant changes from v7.2.6 through v7.10.x, flags breaking changes, and links each section to the reference files that cover the new surface area in depth.
 
 Changelog source of truth: [https://github.com/macCesar/purgeTSS](https://github.com/macCesar/purgeTSS).
 
 ---
 
+## Upgrade to v7.10.x
+
+v7.10.0 through v7.10.2 are additive — **no breaking changes**. The notable shift is internal: configs written before v7.7.0 (the `brand:` regroup) now auto-migrate in memory on every run, so projects that never updated to the grouped `brand:` schema keep working without a `TypeError` crash. Full release notes in [`version-history.md`](./version-history.md).
+
+### Added in v7.10.0
+
+- **`purgetss images --opacity / --padding / --output`** — three CLI-only flags aimed at placeholder / default ImageView workflows. `--opacity` multiplies alpha; `--padding` shrinks the rendered image inside each density canvas; `--output` retargets the basename and subpath. See [`multi-density-images.md`](./multi-density-images.md).
+- **Google Play Feature Graphic in `brand`** — `purgetss brand` now generates `MarketplaceArtworkFeature.png` (1024×500). Auto-discovers `purgetss/brand/logo-feature.{svg,png}` or reuses the master logo. Tune with `--feature-graphic-padding <n>` (range `0-40`, default `12%`), `brand.padding.featureGraphic`, or `--feature-logo <path>`. See [`app-branding.md`](./app-branding.md).
+- **Arbitrary nesting depth in `theme` objects** — property emission walks nested values recursively instead of stopping at level 2. `theme.extend.colors.brand.primary.500` now flattens to `brand-primary-500` instead of being silently dropped. Default keys (`default`, `global`, `DEFAULT`) collapse without contributing to the suffix. See [`arbitrary-values.md`](./arbitrary-values.md).
+- **`apply:` resolves bundled icon fonts from `dist/`** — `apply: 'fas fa-times-circle wh-12 ...'` now merges the FontAwesome family and glyph automatically. Same lookup runs for `mi-*` (Material Icons), `ms-*` (Material Symbols), and `f7-*` (Framework7). Project-level `purgetss/styles/fontawesome.tss` still wins over the bundled default. See [`apply-directive.md`](./apply-directive.md).
+
+### Fixed in v7.10.0
+
+- **`borderRadius` arrays inside `apply:`** — the post-merge dedup step now tracks depth on `[]` alongside `{}`, so directional rules like `rounded-{t,b,l,r,tl,tr,bl,br}-*` no longer get split on internal commas.
+- **`brand --padding <n>` shortcut** — now applies to BOTH Android paddings (`androidAdaptivePadding` AND `androidLegacyPadding`) as the help text always promised. Previously only fed the adaptive one.
+
+### v7.10.1 — copy-only changes
+
+- **"Tailwind" framing dropped** from copy that did not document a functional integration. Error block now reports `Square brackets "[ ]" are not supported` (previously `Tailwind-style brackets "[ ]"`). The promotional `<Label>` injected into new projects by `purgetss create` changed from `"Tailwind-inspired utility classes for Titanium/Alloy"` to `"Utility-first styling for Titanium/Alloy"`.
+- **Functional integrations stay**: `tailwindcss@3` dependency installed by `install-dependencies` (drives the `defaultColors` / `defaultTheme` palette base AND the VSCode IntelliSense extension); `--tailwind` flag on `purgetss shades`; recommended `Tailwind CSS IntelliSense` and `Tailwind Raw Reorder (v4)` VSCode extensions.
+
+### v7.10.2 — pre-7.7.0 brand config auto-migration
+
+If your project still uses the **flat** `brand:` config that predates v7.7.0, v7.10.2 normalizes it in memory on every run before defaults are applied. Without this, the build crashed with `TypeError: Cannot create property 'ios' on number '15'` because `brand.padding` was a number, not an object.
+
+Mapping (see [`app-branding.md` → Upgrading from pre-7.7.0 configs](./app-branding.md#upgrading-from-pre-7-7-0-configs)):
+
+| Pre-7.7.0 flat key | Current grouped key |
+| --- | --- |
+| `brand.padding: <number\|string>` | `brand.padding.androidLegacy` AND `brand.padding.androidAdaptive` (same value applied to both) |
+| `brand.iosPadding` | `brand.padding.ios` |
+| `brand.bgColor` | `brand.colors.background` |
+| `brand.darkBgColor` | `brand.ios.darkBackground` |
+| `brand.notification` | `brand.android.notification` |
+| `brand.splash` | `brand.android.splash` |
+
+The grouped key always wins when both forms coexist. A one-time deprecation notice per session lists which legacy keys were migrated. Auto-migration is transitional and may be removed in a future major version — update `config.cjs` to the grouped schema to silence the notice and stay future-proof.
+
+### What to review
+
+- If you maintain a `brand:` block from pre-7.7.0, plan the one-time update to the grouped schema (`logos`, `padding`, `android`, `ios`, `colors`).
+- If you previously skipped `apply:` with icon fonts because they were silently dropped, that workaround is no longer needed in v7.10.0.
+- Deeply nested color families in `theme.extend.colors.*` that you flattened by hand to stay at depth ≤ 2 can be restructured by domain — the recursive emission now reaches every leaf.
+
+---
+
+## Upgrade to v7.9.0
+
+v7.9.0 ships one **breaking** path rename plus a behavior change for `theme.Window` / `theme.View` / `theme.ImageView` that can surface as a regression if a project depended on the framework defaults being merged in.
+
+### Breaking — glossary output path renamed
+
+The user-facing glossary output path moved 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 was added on purpose. The `--glossary` flag and command surface are unchanged.
+
+### Headline behavior change — replace mode for top-level `theme.Window` / `View` / `ImageView`
+
+Before v7.9.0, `theme.Window` (no `extend`) still merged with the framework defaults (white `backgroundColor`, `Ti.UI.SIZE` on `View`, iOS `hires: true` on `ImageView`), which produced gradient ghosting and similar overrides. v7.9.0 makes top-level configs behave as true **replace mode**.
+
+If you previously wrote:
+
+```javascript
+theme: {
+  Window: {
+    apply: 'bg-gradient-to-b from-blue-500 to-purple-600'
+  }
+}
+```
+
+…and **depended** on the implicit white background, the gradient now renders without that background underneath. Move the config under `theme.extend.Window` to keep the merged behavior, or add the previously-implicit utilities back into the `apply` string. See [`apply-directive.md` → Extend mode vs replace mode](./apply-directive.md#extend-mode-vs-replace-mode).
+
+### Added in v7.9.0
+
+- **Opacity modifiers on semantic colors** — `bg-surface/65` now works for any class mapped through `theme.extend.colors`. PurgeTSS auto-derives `<originalKey>_<alphaPercent>` entries in `semantic.colors.json` per mode (light/dark). **Native rebuild required** — Liveview hot-reload alone does not refresh `semantic.colors.json`. See [`semantic-colors.md`](./semantic-colors.md#opacity-modifier-auto-derivation).
+
+### Fixed in v7.9.0
+
+- Several fixes around semantic colors, gradients, and Ti Element defaults: tonal palette no longer inverts Light and Dark; gradient `from` / `to` color order is position-stable across `sort()`; `bg-gradient-to-X` direction is preserved when combined with `from-X to-Y` in the same `apply`; `theme.Window` / `theme.View` / `theme.ImageView` no longer ghost framework presets at the top level (see Headline behavior change above).
+
+---
+
+## Upgrade to v7.8.0
+
+v7.8.0 introduces a structured `Class Syntax Error` block that **halts the build** when it detects known class-name mistakes — previously these flowed silently into the `// Unused or unsupported classes` block of `app.tss`.
+
+### Added — Class Syntax Error pre-validation
+
+Five patterns are now caught and reported with file + line + suggested fix:
+
+| Pattern | Offending input | Fix |
+| --- | --- | --- |
+| Inverted negative sign | `top-(-10)` | `-top-(10)` |
+| Square-bracket notation | `top-[10px]` | `top-(10px)` |
+| Empty parentheses | `wh-()` | (flagged, no auto-fix) |
+| Whitespace inside parentheses | `wh-( 200 )` | `wh-(200)` |
+| Redundant `px` unit | `top-(10px)` | `top-(10)` |
+
+All offenders are reported in a single run. Generic unknown classes — typos, vendor utilities not enabled, custom classes not declared yet — continue to flow into `// Unused or unsupported classes`. See [`arbitrary-values.md` → Class syntax pre-validation](./arbitrary-values.md#class-syntax-pre-validation).
+
+### Added — `purgetss images --width <n>` (v7.8.0)
+
+Pins Android `mdpi` (= iPhone `@1x`) to `<n>` pixels wide. Larger scales derive as ×1.5, ×2, ×3, ×4 from that base. Range `[1, 8192]`. Most useful for SVG sources from vector editors (Affinity, Illustrator) with disproportionate viewBoxes. CLI-only — width is per-asset, not a project-wide setting. See [`multi-density-images.md`](./multi-density-images.md#pinning-the-output-width-with---width).
+
+### Fixed in v7.8.0
+
+- The arbitrary-value parser no longer crashes on negative values inside parentheses — `top-(-10)` is now recognized and reported as an inverted-negative-sign error instead of triggering a `Cannot read properties of null (reading 'pop')` exception.
+
+### What to review
+
+- Run the build once on the upgraded version and address every `Class Syntax Error` it surfaces. The offender list is exhaustive in one pass.
+- If a CI step depended on a malformed class quietly landing in the unused-classes block, it will now hard-fail — adjust the CI accordingly.
+
+---
+
+## Upgrade to v7.7.0
+
+v7.7.0 cleans up the `brand:` config before stabilizing it. **Pre-7.10.2** projects on the flat schema crashed; from v7.10.2 onward the flat schema auto-migrates in memory (see Upgrade to v7.10.x). The recommended migration is still a one-time update to the grouped schema.
+
+### Restructure — grouped `brand:` config
+
+Branding settings moved out of flat keys into purpose-based groups: `brand.logos`, `brand.padding`, `brand.android`, `brand.ios`, `brand.colors`.
+
+```javascript
+// Pre-7.7.0 — flat
+brand: {
+  padding: 15,
+  iosPadding: 4,
+  bgColor: '#FFFFFF',
+  notification: false,
+  splash: false
+}
+
+// v7.7.0+ — grouped
+brand: {
+  padding: {
+    ios: '4%',
+    androidLegacy: '10%',
+    androidAdaptive: '19%'
+  },
+  android: {
+    notification: false,
+    splash: false
+  },
+  colors: {
+    background: '#FFFFFF'
+  }
+}
+```
+
+### Added in v7.7.0
+
+- **Separate Android brand inputs** — `logos.androidLauncher` / `--icon-logo` for the Android launcher icon; `logos.androidSplash` / `--splash-logo` for Android 12+ splash artwork. Drop `logo-icon.*` / `logo-splash.*` into `purgetss/brand/` for auto-discovery.
+- **Independent Android paddings** — `--android-adaptive-padding` (default `19%`) and `--android-legacy-padding` (default `10%`) replace the single `--padding`. `--padding` is now a shortcut that sets both for one run (note: the shortcut bug where only `androidAdaptive` was applied was fixed in v7.10.0).
+- **Android splash fallback regenerated** — `app/assets/android/default.png` (Alloy) or `Resources/android/default.png` (Classic). `cleanup-legacy` no longer removes `default.png`.
+- **Values and Units doc** — new official reference explaining how `ti.ui.defaultunit` in `tiapp.xml` interprets PurgeTSS unitless values. See [`values-and-units.md`](./values-and-units.md).
+
+---
+
 ## Upgrade to v7.6.0
 
 v7.6.0 introduces three new CLI commands for app-asset generation plus two new `config.cjs` sections. None of the additions are breaking — existing projects continue to work untouched, and the new config sections are auto-injected on first run.
@@ -211,3 +368,7 @@ If you previously worked around this by inlining the gradient directly in TSS, r
 - After v7.5.0: diff generated `utilities.tss` to confirm property deduplication produces the expected output.
 - After v7.5.3: consider wiring `Appearance.init()` at app boot if you want runtime Light/Dark switching.
 - After v7.6.0: run `brand`, `images`, and `semantic` once in a scratch project before pointing them at production assets, so you can preview the output layout.
+- After v7.7.0: migrate the `brand:` block in `config.cjs` to the grouped schema (`logos`, `padding`, `android`, `ios`, `colors`). v7.10.2 auto-migrates flat configs in memory, but the one-time update is recommended to silence the deprecation notice.
+- After v7.8.0: run the build once and address every `Class Syntax Error` it surfaces. Update CI to handle the new hard-fail on malformed class names. Migrate any `top-[10px]` style square brackets to `top-(10px)` parentheses.
+- After v7.9.0: search for any `purgetss/experimental/tailwind-classes/` references in tooling/CI and update to `purgetss/glossary/tailwind-classes/`. If a project used top-level `theme.Window` / `View` / `ImageView` and depended on framework defaults being merged in, decide between moving the config under `theme.extend.*` or adding the previously-implicit utilities to the `apply` string.
+- After v7.10.0: deeply nested color families (`theme.extend.colors.brand.primary.500`) now emit recursively — restructure by domain if it improves readability. `apply:` with bundled icon fonts (`fas`, `mi-*`, `ms-*`, `f7-*`) no longer requires `build-fonts` first. The Google Play Feature Graphic ships automatically with `purgetss brand`.

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

@@ -304,6 +304,67 @@ purgetss images --format webp --quality 85
 
 Keep the default `format: null` when you need to stay in the same format as the source — for example PNG with alpha that shouldn't be flattened.
 
+## Reducing alpha across every density with `--opacity` (v7.10.0)
+
+Since v7.10.0, `--opacity <n>` multiplies the alpha channel of every generated density by `n/100`. Useful for placeholder or default ImageView images that render at reduced opacity (loading states, watermarks behind content, "image is loading" overlays).
+
+```bash
+purgetss images logo.svg --opacity 50 --format png
+```
+
+- `--opacity` accepts integers in `[0, 100]`. Out-of-range values exit immediately without writing anything (`Invalid --opacity '150'. Must be an integer between 0 and 100.`).
+- `--opacity 100` is a no-op — the compositing pass is skipped entirely.
+- `--opacity 0` produces a fully transparent output (technically valid, visually empty).
+
+### Format interactions
+
+- **PNG / WebP / AVIF:** alpha is preserved.
+- **JPEG:** JPEG has no alpha. The existing flatten-on-white step composites the semi-transparent image onto white before writing, so `--opacity 50 --format jpeg` produces a 50%-faded version **on white**, not a transparent JPEG.
+
+## Adding breathing room with `--padding` (v7.10.0)
+
+`--padding <n>` shrinks the rendered image inside each density canvas by `n%` symmetric borders. Useful when the source logo has no built-in padding and you want a placeholder with breathing room — without editing the source asset.
+
+```bash
+purgetss images purgetss/brand/logo.png --padding 15 --format png
+```
+
+Each density's output canvas keeps the same dimensions it would have without `--padding`, but the rendered image takes only `(1 − 2 × 0.15) = 70%` of that canvas (centered). The remaining 30% of the canvas (15% on each side) is transparent.
+
+- `--padding` accepts integers in `[0, 40]`. Out-of-range or negative values are rejected (`Invalid --padding '50'. Must be an integer between 0 and 40.`).
+- `--padding 0` is a no-op (skipped — no extend pass).
+
+### When *not* to use `--padding`
+
+If your source logo already has the breathing room you want baked in, you don't need `--padding` — it compounds the existing padding. Use `--padding` when:
+
+- the source is edge-to-edge (no built-in margin) and you want a centered placeholder
+- you need a fast way to produce a "loose" variant of a logo without touching the source file
+
+## Renaming the output with `--output` (v7.10.0)
+
+By default, the output basename comes from the source filename and the subfolder mirrors the source's location inside `purgetss/images/`. When you want a different output path — for example, sourcing a logo from `purgetss/brand/` and writing it as a placeholder under `images/logos/` — `--output <relpath>` overrides both:
+
+```bash
+purgetss images purgetss/brand/logo.svg --output logos/default-image
+```
+
+That writes `images/logos/default-image.png` (or `.jpg` / `.webp` depending on `--format`) across all densities, regardless of the source's location.
+
+### Combining `--opacity`, `--padding`, and `--output`
+
+The three flags compose for the canonical "transparent placeholder with padding under a custom path" use case:
+
+```bash
+purgetss images purgetss/brand/logo.svg \
+    --opacity 30 \
+    --padding 15 \
+    --output 'logos/default-image' \
+    --format png
+```
+
+Produces a 30% opacity, 15%-padded version of the brand logo at `images/logos/default-image.png` for every Android density and iPhone scale — a one-command way to ship a default ImageView placeholder.
+
 ## Full pipeline alongside `build`
 
 The typical sequence when iterating on an app:
@@ -348,6 +409,9 @@ If you only tweaked CSS classes (no image changes), you don't need to re-run `pu
 | `--format <ext>` | Convert all outputs to: `webp`, `jpeg`, `png`, `avif`, `gif`, `tiff`. Default: keep source format. |
 | `--quality <n>` | Quality `0–100` for lossy formats. Default `85`. |
 | `--width <n>` | (v7.8.0) Pin `mdpi` / `@1x` output width to `n` pixels; `[1, 8192]`. Other densities derive from this base (×1.5 / ×2 / ×3 / ×4). Most useful for SVG sources with non-standard viewBoxes. CLI-only — no `config.cjs` equivalent because width is per-asset. |
+| `--opacity <n>` | (v7.10.0) Multiply the alpha channel of every generated density by `n/100`. Range `[0, 100]`. Combine with `--format jpeg` and the alpha is flattened on white instead of producing a transparent JPEG. CLI-only. |
+| `--padding <n>` | (v7.10.0) Shrink the rendered image inside each density canvas by `n%` symmetric borders. Range `[0, 40]`. CLI-only. |
+| `--output <relpath>` | (v7.10.0) Override the basename and subpath relative to each platform's `images/` root. Lets a source from outside `purgetss/images/` (e.g. `purgetss/brand/`) write into a custom output folder like `images/logos/`. CLI-only. |
 
 **Project & output**
 
@@ -371,6 +435,11 @@ 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 --opacity 50 --format png              # 50% alpha placeholder (v7.10.0)
+purgetss images logo.svg --padding 15 --format png     # add 15% breathing room (v7.10.0)
+purgetss images purgetss/brand/logo.svg \
+    --opacity 30 --padding 15 \
+    --output 'logos/default-image' --format png         # placeholder under custom path (v7.10.0)
 purgetss images --dry-run                              # preview
 ```
 

package/skills/purgetss/references/version-history.md

@@ -0,0 +1,82 @@
+# PurgeTSS — Version History
+
+Release-by-release feature additions and behavior changes. The current behavior of PurgeTSS is documented in the main `SKILL.md` and its reference files; this page is the historical record.
+
+## What's New in v7.10.2
+
+- **Pre-7.7.0 brand config auto-migration.** Configs written before v7.7.0 (the `brand:` regroup) now auto-migrate in memory on every run. The legacy flat layout (`brand.padding: <number>`, `brand.iosPadding`, `brand.bgColor`, `brand.darkBgColor`, top-level `brand.notification` / `brand.splash`) used to crash auto-purge with `TypeError: Cannot create property 'ios' on number '15'`. `getConfigFile()` now normalizes legacy keys to the grouped layout (`brand.padding.{ios, androidLegacy, androidAdaptive}`, `brand.android.*`, `brand.ios.darkBackground`, `brand.colors.background`) before applying defaults. When both legacy and new keys coexist, the new key wins. A one-time deprecation notice per session lists the migrated keys. See [App Icons & Branding → Upgrading from pre-7.7.0 configs](app-branding.md).
+- **Internal logger fix.** `logger.warning` and `logger.success` are now defined. Across `brand`, `images`, `cleanup-legacy`, and `svg-utils`, ~30 callsites of `logger.warning` and ~10 of `logger.success` referenced methods that did not exist on the logger object — any opt-in command path that hit one used to throw `TypeError: logger.warning is not a function`. The auto-purge entry point most users hit did not reach those callsites, so the bug stayed latent until commands like `purgetss brand` or `purgetss images` were run.
+
+## What's New in v7.10.1
+
+- **"Tailwind" framing dropped from copy that did not document a functional integration.** The Class Syntax Error block now reports `'Square brackets "[ ]" are not supported'` instead of `'Tailwind-style brackets "[ ]" are not supported'`. The promotional `<Label>` injected into new projects by `purgetss create` changed from `"Tailwind-inspired utility classes for Titanium/Alloy"` to `"Utility-first styling for Titanium/Alloy"`.
+- **Functional integrations stay.** The `tailwindcss@3` dependency installed by `install-dependencies` (drives both the `defaultColors` / `defaultTheme` palette base AND the VSCode IntelliSense extension) still ships. The `--tailwind` flag on `purgetss shades` and the recommended `Tailwind CSS IntelliSense` / `Tailwind Raw Reorder (v4)` VSCode extensions are unchanged.
+
+## What's New in v7.10.0
+
+- **`purgetss images` got three CLI-only flags.**
+  - `--opacity <n>` (integer `0-100`) multiplies the alpha channel of every generated density by `n/100` — useful for placeholder or default ImageView images that render at reduced opacity (loading states, watermarks). With `--format jpeg`, the JPEG flatten-on-white step composites the semi-transparent image onto white instead of producing transparent JPEGs (JPEG has no alpha).
+  - `--padding <n>` (integer `0-40`) shrinks the rendered image inside each density canvas by symmetric percentage borders, preserving canvas size with transparent fill — useful for breathing room around an unpadded logo.
+  - `--output <relpath>` overrides the basename and subpath relative to each platform's `images/` root, so a logo from `purgetss/brand/` can be written as `images/logos/loading.png` across all densities in a single command.
+  - The three flags combine naturally for "transparent placeholder with padding under a custom path". See [Multi-Density Images](multi-density-images.md).
+- **`purgetss brand` now generates `MarketplaceArtworkFeature.png` (1024×500 Google Play Feature Graphic)** alongside the existing iTunesConnect and MarketplaceArtwork submission assets. Auto-discovers `purgetss/brand/logo-feature.{svg,png}` or reuses the master logo if not provided. Default vertical padding is `12%`; override with `--feature-graphic-padding <n>` (range `0-40`), config `brand.padding.featureGraphic`, or CLI `--feature-logo <path>` for a dedicated source. Submission artwork only — written to project root for upload to the Play Console, not bundled into the APK. See [App Icons & Branding](app-branding.md).
+- **Arbitrary nesting depth in `config.cjs` `theme` objects.** Property emission now walks nested values recursively instead of stopping at level 2, so `theme.extend.colors.brand.primary.500` flattens to `brand-primary-500` instead of being silently dropped. Same for `backgroundGradient` and `backgroundSelectedGradient`. Default modifier keys (`default`, `global`, `DEFAULT`) collapse without contributing to the suffix. See [Arbitrary Values](arbitrary-values.md).
+- **Fix:** `apply:` now resolves built-in icon font classes (`fas`, `fab`, `fa-*`, `mi-*`, `ms-*`, `f7-*`) from `dist/` for projects that don't run `build-fonts`. Previously those classes were silently dropped from generated rules — `apply: 'fas fa-times-circle wh-12 ...'` produced everything except the FontAwesome family and the icon glyph. See [Apply Directive → Use icon font classes](apply-directive.md).
+- **Fix:** `borderRadius: [...]` arrays no longer get truncated when combined with other utilities in an `apply:` string. The post-merge dedup step (from v7.9.0) tracked depth on `{}` only, so `borderRadius: [0, 0, 0, 16]` (emitted by directional `rounded-{t,b,l,r,tl,tr,bl,br}-*` utilities) was split on its internal commas. The depth tracker now respects `[]` alongside `{}`.
+- **Fix:** `brand --padding <n>` shortcut now applies to BOTH Android paddings as the help text always promised. Previously the shortcut only fed `androidAdaptivePadding` while `androidLegacyPadding` fell through to its own config value, so `purgetss brand --padding 17` actually produced `androidAdaptive=17, androidLegacy=10`.
+
+## 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](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](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](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](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`
+- Separate Android brand inputs — `logos.androidLauncher` / `--icon-logo` for Android launcher icons; `logos.androidSplash` / `--splash-logo` for Android 12+ splash artwork. Drop `logo-icon.*` and `logo-splash.*` into `purgetss/brand/`
+- `--android-adaptive-padding` (default `19%`) and `--android-legacy-padding` (default `10%`) replace the single `--padding`. The shortcut `--padding` now sets both Android paddings to the same value for one run
+- Legacy Android splash fallback regenerated — `app/assets/android/default.png` (Alloy) or `Resources/android/default.png` (Classic). `cleanup-legacy` no longer removes `default.png`
+- New official doc: [Values and Units](values-and-units.md) — explains `ti.ui.defaultunit` interpretation of PurgeTSS unitless values
+
+## What's New in v7.6.x
+
+- `brand` command — complete Titanium branding set (launcher icons, adaptive, iOS 18+ Dark/Tinted, marketplace) from logos in `./purgetss/brand/` (v7.6.0)
+- `images` command — multi-density UI images (Android res-*dpi + iPhone @1x/@2x/@3x) from `./purgetss/images/` (v7.6.0)
+- `semantic` command — Titanium semantic colors for Light/Dark mode (palette mode + single mode) (v7.6.0)
+- `brand:` and `images:` config sections auto-injected into older configs (v7.6.0)
+- Percentages as strings (`'15%'`) for self-documenting clarity in brand/images configs (v7.6.0)
+- Confirmation prompt for destructive writes in `brand` / `images` (`y` / `N` / `a`); auto-skipped on non-TTY, with `-y`, or `PURGETSS_YES=1` (v7.6.1)
+- `semantic` command works in Classic projects — writes to `Resources/semantic.colors.json` (v7.6.2)
+
+## What's New in v7.5.3
+
+- Appearance module — Light/Dark/System mode switching with persistence
+- Default font family classes (`font-sans`, `font-serif`, `font-mono`) generated automatically with platform-appropriate values
+- XML validation — detects illegal `--` inside XML comments during pre-validation
+
+## What's New in v7.5.0
+
+- `extend` support for Window, View, and ImageView in `config.cjs`
+- Shorthand `apply` directive normalization
+- Apply directive property deduplication
+- Automatic platform resolution in apply directives
+- Updated Font Awesome to 7.2.0
+- Fixed: `extend.Window` was silently ignored
+- Fixed: Array-type properties (`extendEdges`, `mediaTypes`) bracket notation
+
+## What's New in v7.4.0
+
+- 9 new Animation methods: `transition`, `pulse`, `sequence`, `swap`, `shake`, `snapTo`, `reorder`, `undraggable`, `detectCollisions` (module now has 15 methods total)
+- Snap behavior classes: `snap-back`, `snap-center`, `snap-magnet`
+- `keep-z-index` utility class
+- Enriched callback event object with `action`, `state`, `id`, `targetId`, `index`, `total`, `getTarget()`
+- Delta-based drag for views with rotate/scale transforms
+- Position normalization for draggable views
+- Property inheritance from Animation object for all new methods

package/skills/ti-expert/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ti-expert
-description: "Titanium SDK architecture and implementation expert. Use when designing, reviewing, analyzing, or examining Titanium project structure (Alloy or Classic), creating controllers/views/services, choosing models vs collections, implementing communication patterns, handling memory cleanup, testing, auditing code, migrating legacy apps, or building adaptive/responsive layouts for tablets, foldables, and large screens. AUTO-DETECT: If tiapp.xml exists, invoke this skill BEFORE making architectural decisions, creating new controllers/views, or restructuring code. Titanium has its own patterns for navigation (NavigationWindow, TabGroup), memory management, and event handling that differ from web frameworks."
+description: "Use when designing, reviewing, analyzing, or examining Titanium SDK architecture and implementation (Alloy or Classic) — creating controllers/views/services, choosing models vs collections, implementing communication patterns, handling memory cleanup, testing, auditing code, migrating legacy apps, or building adaptive/responsive layouts for tablets, foldables, and large screens. AUTO-DETECT: If tiapp.xml exists, invoke BEFORE making architectural decisions, creating new controllers/views, or restructuring code. Titanium has its own patterns for navigation (NavigationWindow, TabGroup), memory management, and event handling that differ from web frameworks."
 argument-hint: "[architecture-topic]"
 allowed-tools: Read, Grep, Glob, Edit, Write, Bash(git *), Bash(node *)
 ---

package/skills/ti-ui/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ti-ui
-description: "Titanium SDK UI/UX patterns and components expert. Use when working with, reviewing, analyzing, or examining Titanium layouts, ListView/TableView performance optimization, event handling and bubbling, gestures (swipe, pinch), animations, accessibility (VoiceOver/TalkBack), orientation changes, custom fonts/icons, app icons/splash screens, or platform-specific UI (Action Bar, Navigation Bar). AUTO-DETECT: If tiapp.xml exists, invoke this skill BEFORE creating or modifying any UI view, window, or layout. Titanium layouts (composite, vertical, horizontal) differ from web/CSS — never assume web layout behavior."
+description: "Use when working with, reviewing, analyzing, or examining Titanium SDK UI/UX patterns and components — Titanium layouts, ListView/TableView performance optimization, event handling and bubbling, gestures (swipe, pinch), animations, accessibility (VoiceOver/TalkBack), orientation changes, custom fonts/icons, app icons/splash screens, or platform-specific UI (Action Bar, Navigation Bar). AUTO-DETECT: If tiapp.xml exists, invoke BEFORE creating or modifying any UI view, window, or layout. Titanium layouts (composite, vertical, horizontal) differ from web/CSS — never assume web layout behavior."
 argument-hint: "[component]"
 allowed-tools: Read, Grep, Glob, Edit, Write, Bash(node *)
 ---