@maccesar/titools 2.10.1 → 3.2.0

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 *)
 ---

package/skills/alloy-guides/SKILL.md

@@ -1,190 +0,0 @@
----
-name: alloy-guides
-description: "Titanium Alloy MVC official framework reference. Use when working with, reviewing, analyzing, or examining Alloy models, views, controllers, Backbone.js data binding, TSS styling, widgets, Alloy CLI, sync adapters, migrations, or MVC compilation. AUTO-DETECT: If the project has an app/views/ + app/controllers/ + app/styles/ folder structure, it is an Alloy project — invoke this skill BEFORE editing XML views, JS controllers, or TSS styles. Alloy XML is NOT HTML; TSS is NOT CSS; controllers follow Alloy-specific patterns, not web MVC."
-argument-hint: "[concept]"
-allowed-tools: Read, Grep, Glob, Edit, Write, Bash(node *)
----
-
-# Alloy MVC framework guide
-
-Reference for building Titanium mobile applications with the Alloy MVC framework and Backbone.js.
-
-## Project detection
-
-> **️ℹ️ AUTO-DETECTS ALLOY PROJECTS**
-> This skill automatically detects Alloy projects when invoked and provides framework-specific guidance.
->
-> **Detection occurs automatically** - no manual command needed.
->
-> **Alloy project indicators:**
-> - `app/` folder (MVC structure)
-> - `app/views/`, `app/controllers/` folders
-> - `app/models/` folder
->
-> **Behavior based on detection:**
-> - **Alloy detected** → Provides Alloy MVC documentation, Backbone.js patterns, TSS styling, widgets
-> - **Not detected** → Indicates this skill is for Alloy projects only, does not suggest Alloy-specific features
-
-## Quick reference
-
-| Topic                                            | Reference File                                                          |
-| ------------------------------------------------ | ----------------------------------------------------------------------- |
-| Core concepts, MVC, Backbone.js, conventions     | [CONCEPTS.md](references/CONCEPTS.md)                                   |
-| Controllers, events, conditional code, arguments | [CONTROLLERS.md](references/CONTROLLERS.md)                             |
-| Models, collections, data binding, migrations    | [MODELS.md](references/MODELS.md)                                       |
-| XML markup, elements, attributes, events         | [VIEWS_XML.md](references/VIEWS_XML.md)                                 |
-| TSS styling, themes, platform-specific styles    | [VIEWS_STYLES.md](references/VIEWS_STYLES.md)                           |
-| Dynamic styles, autostyle, runtime styling       | [VIEWS_DYNAMIC.md](references/VIEWS_DYNAMIC.md)                         |
-| Controllers-less views, patterns                 | [VIEWS_WITHOUT_CONTROLLERS.md](references/VIEWS_WITHOUT_CONTROLLERS.md) |
-| Creating and using widgets                       | [WIDGETS.md](references/WIDGETS.md)                                     |
-| CLI commands, code generation                    | [CLI_TASKS.md](references/CLI_TASKS.md)                                 |
-| PurgeTSS integration (optional addon)            | [PURGETSS.md](references/PURGETSS.md)                                   |
-
-## Project structure
-
-Standard Alloy project structure:
-
-```
-app/
-├── alloy.js              # Initializer file
-├── alloy.jmk             # Build configuration
-├── config.json           # Project configuration
-├── assets/               # Images, fonts, files (→ Resources/)
-├── controllers/          # Controller files (.js)
-├── i18n/                 # Localization strings (→ i18n/)
-├── lib/                  # CommonJS modules
-├── migrations/           # DB migrations (<DATETIME>_<name>.js)
-├── models/               # Model definitions (.js)
-├── platform/             # Platform-specific resources (→ platform/)
-├── specs/                # Test-only files (dev/test only)
-├── styles/               # TSS files (.tss)
-├── themes/               # Theme folders
-├── views/                # XML markup files (.xml)
-└── widgets/              # Widget components
-```
-
-## MVC quick start
-
-**Controller** (`app/controllers/index.js`):
-```javascript
-function doClick(e) {
-    alert($.label.text);
-}
-$.index.open();
-```
-
-**View** (`app/views/index.xml`):
-```xml
-<Alloy>
-    <Window class="container">
-        <Label id="label" onClick="doClick">Hello, World</Label>
-    </Window>
-</Alloy>
-```
-
-**Style** (`app/styles/index.tss`):
-```javascript
-".container": { backgroundColor: "white" }
-"Label": { color: "#000" }
-```
-
-## Key concepts
-
-- **Models/Collections**: Backbone.js objects with sync adapters (sql, properties)
-- **Views**: XML markup with TSS styling
-- **Controllers**: JavaScript logic with `$` reference to view components
-- **Data Binding**: Bind collections to UI components automatically
-- **Widgets**: Reusable components with MVC structure
-- **Conventions**: File naming and placement drive code generation
-
-## Critical rules
-
-### Platform-specific properties in TSS
-
-> **🚨 CRITICAL: Platform-specific properties require modifiers**
-> Using `Ti.UI.iOS.*` or `Ti.UI.Android.*` properties in TSS without platform modifiers causes cross-platform compilation failures.
->
-> Example of the failure:
-> ```tss
-> // WRONG - Adds Ti.UI.iOS to Android project
-> "#mainWindow": {
->   statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT  // FAILS on Android!
-> }
-> ```
->
-> Correct approach - use platform modifiers:
-> ```tss
-> // CORRECT - Only adds to iOS
-> "#mainWindow[platform=ios]": {
->   statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT
-> }
->
-> // CORRECT - Only adds to Android
-> "#mainWindow[platform=android]": {
->   actionBar: {
->     displayHomeAsUp: true
->   }
-> }
-> ```
->
-> Properties that always require platform modifiers:
-> - iOS: `statusBarStyle`, `modalStyle`, `modalTransitionStyle`, any `Ti.UI.iOS.*`
-> - Android: `actionBar` config, any `Ti.UI.Android.*` constant
->
-> **Available modifiers:** `[platform=ios]`, `[platform=android]`, `[formFactor=handheld]`, `[formFactor=tablet]`, `[if=Alloy.Globals.customVar]`
->
-> For more platform-specific patterns, see [Code conventions (ti-expert)](skills/ti-expert/references/code-conventions.md#platform--device-modifiers) or [Platform UI guides (ti-ui)](skills/ti-ui/references/platform-ui-ios.md).
-
-## Common patterns
-
-### Creating a model
-```bash
-alloy generate model book sql title:string author:string
-```
-
-### Data binding
-```xml
-<Collection src="book" />
-<TableView dataCollection="book">
-    <TableViewRow title="{title}" />
-</TableView>
-```
-
-### Platform-specific code
-```javascript
-if (OS_IOS) {
-    // iOS-only code
-}
-if (OS_ANDROID) {
-    // Android-only code
-}
-```
-
-### Widget usage
-```xml
-<Widget src="mywidget" id="foo" />
-```
-
-## Compilation process
-
-1. Cleanup: Resources folder cleaned
-2. Build Config: alloy.jmk loaded (pre:load task)
-3. Framework Files: Backbone.js, Underscore.js, sync adapters copied
-4. MVC Generation: Models, widgets, views, controllers compiled to JS
-5. Main App: app.js generated from template
-6. Optimization: UglifyJS optimization, platform-specific code removal
-
-## References
-
-Read detailed documentation from the reference files listed above based on your specific task.
-
-## Related skills
-
-For tasks beyond Alloy MVC basics, use these complementary skills:
-
-| Task                                           | Use This Skill |
-| ---------------------------------------------- | -------------- |
-| Modern architecture, services, patterns        | `ti-expert`    |
-| Alloy CLI, config files, debugging errors      | `alloy-howtos` |
-| Utility-first styling with PurgeTSS (optional) | `purgetss`     |
-| Native features (location, push, media)        | `ti-howtos`    |