@maccesar/titools 2.10.1 → 3.2.0

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