@maccesar/titools 3.1.0 → 3.3.0

package/skills/purgetss/references/icon-fonts.md

@@ -1,176 +1,264 @@
 # Icon Font Libraries
 
+PurgeTSS ships with four official icon font families, each preconfigured with the TSS classes and `fontFamily` mappings you need to drop icons into Buttons, Labels, and TextFields.
+
+For user-defined fonts (Google Fonts, brand typefaces, community icon libraries like map-icons or microns), see [Custom Fonts](./custom-fonts.md) — those use `build-fonts`, not `icon-library`.
+
 > ℹ️ **INFO — Official Icon Fonts for PurgeTSS**
->
-> Older versions of PurgeTSS bundled additional icon font libraries — Bootstrap Icons, Boxicons, LineIcons, and Tabler Icons among them. **Those libraries have been deprecated and removed from the official distribution** to keep maintenance under control. They are still usable, but you must rebuild them yourself with `build-fonts` (see below).
->
-> The icon fonts officially supported and shipped by PurgeTSS today are:
->
 > - [Font Awesome 7 Free](https://fontawesome.com) (upgrade with `purgetss il -v=fa`)
-> - [Framework 7](https://framework7.io/icons/)
+> - [Framework 7 Icons](https://framework7.io/icons/)
 > - [Material Icons](https://fonts.google.com/icons?icon.set=Material+Icons)
 > - [Material Symbols](https://fonts.google.com/icons?icon.set=Material+Symbols)
+>
+> Older versions of PurgeTSS bundled additional libraries (Bootstrap Icons, Boxicons, LineIcons, Tabler Icons). They were removed to keep maintenance under control, but you can [recreate them at the bottom of this page](#recreating-removed-icon-libraries).
 
-For the official install flow for the supported vendors, see [CLI Commands](./cli-commands.md#icon-library-command).
+## Icon families reference
 
-## Recreate Removed Libraries
+Each family ships one or more variant classes, each pointing to a specific font file. Combine a variant class with an icon class to render a glyph. For example, `msr ms-home` uses the Material Symbols Rounded font with the `home` icon.
 
-You can recreate any deprecated library using the `build-fonts` command.
+| Family | Variant | Class | `fontFamily` |
+|---|---|---|---|
+| **Material Symbols** | Outlined (default) | `.ms` | `MaterialSymbolsOutlined-Regular` |
+| Material Symbols | Outlined (alias) | `.mso` | `MaterialSymbolsOutlined-Regular` |
+| Material Symbols | Rounded | `.msr` | `MaterialSymbolsRounded-Regular` |
+| Material Symbols | Sharp | `.mss` | `MaterialSymbolsSharp-Regular` |
+| **Font Awesome** | Solid (default) | `.fa` | `FontAwesome7Free-Solid` |
+| Font Awesome | Solid (alias) | `.fas` | `FontAwesome7Free-Solid` |
+| Font Awesome | Regular | `.far` | `FontAwesome7Free-Regular` |
+| Font Awesome | Brands | `.fab` | `FontAwesome7Brands-Regular` |
+| **Material Icons** | Regular | `.mi` | `MaterialIcons-Regular` |
+| **Framework 7** | Regular | `.f7` | `Framework7-Icons` |
 
-### 1. Download the Libraries
+> 💡 **TIP — Icon class names**
+> Across a family, the icon class is shared by every variant. For Material Symbols, there is one `ms-home` class; pair it with `.ms`, `.mso`, `.msr`, or `.mss` to pick the shape (outlined, rounded, or sharp). FontAwesome works the same way: `fa-home` pairs with `.fa`/`.fas` (Solid) or `.far` (Regular), while brand icons like `fa-github` need `.fab`. **The variant class chooses the font file. The icon class chooses the glyph.**
 
-Start by downloading the libraries from their official websites:
+### Full class lists
 
-- [Bootstrap Icons](https://icons.getbootstrap.com)
-- [Boxicons](https://boxicons.com)
-- [LineIcons](https://lineicons.com/icons/?type=free)
-- [Tabler Icons](https://tabler-icons.io)
+The complete class definitions live in the PurgeTSS `dist/` folder:
 
-### 2. The `fonts` Folder
+- [fontawesome.tss](https://github.com/macCesar/purgeTSS/blob/main/dist/fontawesome.tss)
+- [materialicons.tss](https://github.com/macCesar/purgeTSS/blob/main/dist/materialicons.tss)
+- [materialsymbols.tss](https://github.com/macCesar/purgeTSS/blob/main/dist/materialsymbols.tss)
+- [framework7icons.tss](https://github.com/macCesar/purgeTSS/blob/main/dist/framework7icons.tss)
 
-Put the desired libraries in the `./purgetss/fonts` folder.
+## Installing the icon fonts
 
-> ℹ️ **INFO**
-> Copy the TrueType or OpenType font files and the `.css` file.
+Run `icon-library` to copy the `.ttf` files into `./app/assets/fonts/`. That is the only step you need. Once the fonts are in place, the icon classes from the table above work out of the box.
 
 ```bash
-purgetss
-└─ fonts
-   └─ boxicons
-      ├─ boxicons.css
-      └─ boxicons.ttf
-   └─ lineicons
-      ├─ lineicons.css
-      └─ lineicons.ttf
+# All four families
+$ purgetss icon-library
+
+# Selective install
+$ purgetss il -v=fa,mi,ms,f7
 ```
 
-### 3. The `build-fonts` Command
+> ℹ️ **INFO — You do not need the `.tss` files in `./purgetss/styles/`**
+> PurgeTSS already knows every official icon class and resolves them at compile time from its own bundled `dist/` files. You do not need `fontawesome.tss`, `materialsymbols.tss`, `materialicons.tss`, or `framework7icons.tss` inside `./purgetss/styles/` for `class="fas fa-home"` (or any other icon class) to work in your XML and controllers. Install the `.ttf` files with `icon-library` and the classes are ready.
+
+### Optional flags
 
-Run the `build-fonts` command to create a custom `fonts.tss` file.
+Two optional flags adjust what `icon-library` copies into your project:
+
+- `-s, --styles`: copies the official `.tss` source files into `./purgetss/styles/` for reference only. Useful if you want to grep the full class list, see how a class is defined, or override a specific class in your own project.
+- `-m, --module`: copies the matching CommonJS module into `./app/lib/`, which exposes each icon's Unicode string to JavaScript. Handy when you set `label.text` from a controller and prefer a friendly name like `icons.fa.home` over a raw ``.
 
 ```bash
-purgetss build-fonts [--modules]
+# Add either flag when you want them
+$ purgetss il -s
+$ purgetss il -m
+$ purgetss il -m -s
+```
+
+### Vendor aliases
+
+`--vendor` accepts the short or long forms:
+
+- `fa`, `fontawesome` = Font Awesome Icons
+- `mi`, `materialicons` = Material Icons
+- `ms`, `materialsymbol` = Material Symbols
+- `f7`, `framework7` = Framework7 Icons
+
+## Using icons in XML
+
+The variant class sets the `fontFamily`. The icon class sets the glyph (`text` / `title`). Apply both together:
+
+`index.xml`
+```xml
+<Alloy>
+  <Window>
+    <View class="grid">
+      <View class="vertical mx-auto grid-cols-2 gap-y-2">
+        <!-- Material Symbols variants -->
+        <Label class="mt-2 text-gray-700" text="Material Symbols" />
+        <Button class="ms ms-home my-1 h-10 w-10 text-xl text-blue-500" />
+        <Button class="msr ms-home my-1 h-10 w-10 text-xl text-blue-500" />
+        <Button class="mss ms-home my-1 h-10 w-10 text-xl text-blue-500" />
+      </View>
+
+      <View class="vertical mx-auto grid-cols-2 gap-y-2">
+        <!-- FontAwesome variants -->
+        <Label class="mt-2 text-gray-700" text="Font Awesome" />
+        <Button class="fas fa-home my-1 h-10 w-10 text-xl text-blue-500" />
+        <Button class="far fa-bell my-1 h-10 w-10 text-xl text-blue-500" />
+        <Button class="fab fa-github my-1 h-10 w-10 text-xl text-blue-500" />
+      </View>
+    </View>
+  </Window>
+</Alloy>
+```
 
-# alias:
-purgetss bf [-m]
+## Complete example with all four families
+
+A side-by-side example using all four official families.
+
+To use this file:
+
+- Copy the content of `index.xml` into a new Alloy project.
+- Install the official icon font files using `purgetss icon-library` (without `--vendor`, PurgeTSS copies all official icon fonts).
+- Run `purgetss` once to generate the required files.
+- Compile your app as usual.
+- Use `liveview` if you want faster testing.
+
+`index.xml`
+```xml
+<Alloy>
+  <Window>
+    <View class="grid">
+      <View class="vertical mx-auto grid-cols-2 gap-y-2">
+        <!-- FontAwesome -->
+        <Label class="mt-2 text-gray-700" text="FontAwesome" />
+        <Button class="fa fa-home my-1 h-10 w-10 text-xl text-blue-500" />
+        <Button class="fa fa-home my-1 h-10 w-10 rounded bg-blue-500 text-xl text-white" />
+      </View>
+
+      <View class="vertical mx-auto grid-cols-2 gap-y-2">
+        <!-- Material Icons -->
+        <Label class="mt-2 text-gray-700" text="Material Icons" />
+        <Button class="mi mi-home my-1 h-10 w-10 text-xl text-blue-500" />
+        <Button class="mi mi-home my-1 h-10 w-10 rounded bg-blue-500 text-xl text-white" />
+      </View>
+
+      <View class="vertical mx-auto grid-cols-2 gap-y-2">
+        <!-- Material Symbols -->
+        <Label class="mt-2 text-gray-700" text="Material Symbol" />
+        <Button class="ms ms-home my-1 h-10 w-10 text-xl text-blue-500" />
+        <Button class="ms ms-home my-1 h-10 w-10 rounded bg-blue-500 text-xl text-white" />
+      </View>
+
+      <View class="vertical mx-auto grid-cols-2 gap-y-2">
+        <!-- Framework7-Icons -->
+        <Label class="mt-2 text-gray-700" text="Framework7-Icons" />
+        <Button class="f7 f7-house my-1 h-10 w-10 text-xl text-blue-500" />
+        <Button class="f7 f7-house my-1 h-10 w-10 rounded bg-blue-500 text-xl text-white" />
+      </View>
+    </View>
+  </Window>
+</Alloy>
 ```
 
-### The `fonts.tss` File
+Generated `app.tss` excerpt:
+```css
+// PurgeTSS v7.10.2
+// Created by César Estrada
+// https://purgetss.com
 
-The `build-fonts` command generates `./purgetss/styles/fonts.tss` with Unicode characters and style rules.
+/* Ti Elements */
+'View': { width: Ti.UI.SIZE, height: Ti.UI.SIZE }
+'Window': { backgroundColor: '#FFFFFF' }
 
-`./purgetss/styles/fonts.tss`
-```tss
-'.boxicons': { font: { fontFamily: 'boxicons' } }
-'.lineicons': { font: { fontFamily: 'LineIcons' } }
+/* Default Font Awesome */
+'.fa': { font: { fontFamily: 'FontAwesome7Free-Solid' } }
+'.fa-home': { text: '', title: '' }
 
-/* Unicode Characters */
-/* To use your Icon Fonts in Buttons AND Labels each class sets 'text' and 'title' properties */
+/* Material Icons */
+'.mi': { font: { fontFamily: 'MaterialIcons-Regular' } }
+'.mi-home': { text: '', title: '' }
 
-/* boxicons.css */
-'.bxl-meta': { text: '', title: '' }
-'.bx-lemon': { text: '', title: '' }
-/* ... */
+/* Material Symbols */
+'.ms': { font: { fontFamily: 'MaterialSymbolsOutlined-Regular' } }
+'.ms-home': { text: '', title: '' }
 
-/* lineicons.css */
-'.lni-500px': { text: '', title: '' }
-'.lni-add-files': { text: '', title: '' }
-/* ... */
+/* Framework7 */
+'.f7': { font: { fontFamily: 'Framework7-Icons' } }
+'.f7-house': { text: 'house', title: 'house' }
 ```
 
-### Rename the Style Rule Name
+## Customizing Font Awesome
 
-PurgeTSS uses the font file name as the style rule name. You can change it by renaming the font file.
+If you have a [Font Awesome Pro account](https://fontawesome.com/pro) or want to try the Beta, PurgeTSS can generate a custom `./purgetss/styles/fontawesome.tss` with the Pro or Beta classes.
 
-`./purgetss/fonts/`
-```bash
-purgetss
-└─ fonts
-   └─ boxicons
-      └─ bx.ttf
-```
+### Font Awesome Pro
 
-New style rule name: `'.bx'`
+After setting the [@fortawesome scope](https://fontawesome.com/how-to-use/on-the-web/setup/using-package-managers#installing-pro) with your token, install it in your project's root folder with `npm init` and `npm install --save-dev @fortawesome/fontawesome-pro` (current version 7.1.0).
 
-```tss
-'.bx': { font: { fontFamily: 'boxicons' } }
-```
+To generate a new `purgetss/styles/fontawesome.tss`, run `purgetss build`. It also copies the Pro font files into `./app/assets/fonts` if needed.
 
-### The `assets/fonts` Folder
+Note: Titanium cannot use Font Awesome duotone icons because each icon uses two glyphs.
 
-The `build-fonts` command copies the font files to `./app/assets/fonts` and renames them to their PostScript names so they work on both iOS and Android.
+### Font Awesome 7 Beta
 
-```bash
-app
-└─ assets
-   └─ fonts
-      ├─ boxicons.ttf
-      └─ LineIcons.ttf
-```
+To generate a custom `fontawesome.tss` file from [Font Awesome 7 Beta](https://fontawesome.com/download):
 
-### The `--modules` Option
-
-When you use the `--modules` option, it generates a `./app/lib/purgetss.fonts.js` CommonJS module file.
-
-`./app/lib/purgetss.fonts.js`
-```javascript
-const icons = {
-  /* boxicons */
-  boxicons: {
-    bxlMeta: '',
-    bxLemon: ''
-    /* ... */
-  },
-  /* lineicons */
-  lni: {
-    '500px': '',
-    addFiles: ''
-    /* ... */
-  }
-};
-exports.icons = icons;
-```
+Move the `css` and `webfonts` folders from `fontawesome-pro-7.0.0-beta3-web/`:
 
-### The `--prefix` Option
+```bash
+fontawesome-pro-7.0.0-beta3-web
+└─ css
+└─ webfonts
+```
 
-PurgeTSS determines the group's prefix for each icon family and class name. Use `--prefix` to apply the style's filename as the prefix for class names in `fonts.tss` and property names in `purgetss.fonts.js`.
+Into `./purgetss/fontawesome-beta`:
 
-`./purgetss/fonts/`
 ```bash
 purgetss
-└─ fonts
-   └─ lineicons
-      └─ li.css
+└─ fontawesome-beta
+   ├─ css
+   └─ webfonts
 ```
 
-New group prefix: `li`
+Then run `purgetss build` to generate your custom `fontawesome.tss` file and test the new icons.
+
+## Recreating removed icon libraries
+
+Older versions of PurgeTSS bundled Bootstrap Icons, Boxicons, LineIcons, and Tabler Icons. The list was trimmed to make maintenance easier, but you can rebuild any of them:
+
+1. Download the library from its official site:
+   - [Bootstrap Icons](https://icons.getbootstrap.com)
+   - [Boxicons](https://boxicons.com)
+   - [LineIcons](https://lineicons.com/icons/?type=free)
+   - [Tabler Icons](https://tabler-icons.io)
+2. Place the `.ttf`/`.otf` and `.css` files into `./purgetss/fonts/<library>/`.
+3. Run `purgetss build-fonts`.
+
+For the underlying mechanics (how `build-fonts` reads the `.css`, options like `-m` and `-f`), see [Custom Fonts](./custom-fonts.md).
+
+### `fonts.tss` example
+
+```css
+'.boxicons': { font: { fontFamily: 'boxicons' } }
+'.lineicons': { font: { fontFamily: 'LineIcons' } }
+
+/* Unicode Characters */
+/* To use your Icon Fonts in Buttons AND Labels each class sets 'text' and 'title' properties */
 
-`./purgetss/styles/fonts.tss`
-```tss
-/* lineicons/li.css */
-'.li-zoom-out': { text: '', title: '' }
-'.li-zoom-in': { text: '', title: '' }
+/* boxicons.css */
+'.bxl-meta': { text: '', title: '' }
+'.bx-lemon': { text: '', title: '' }
 /* ... */
-```
 
-`./app/lib/purgetss.fonts.js`
-```javascript
-const icons = {
-  /* lineicons/li.css */
-  li: {
-    /* ... */
-  }
-};
-exports.icons = icons;
+/* lineicons.css */
+'.lni-500px': { text: '', title: '' }
+'.lni-add-files': { text: '', title: '' }
+/* ... */
 ```
 
-> 🛑 **DANGER**
->
-> Make sure the new prefix stays unique so it does not collide with other class prefixes. A duplicate prefix will silently overwrite earlier rules in the generated `fonts.tss`, leaving you with icons that render the wrong glyph at runtime.
-
 ## Community-Discovered Patterns
 
 The following note reflects community experience working with icon fonts that depend on multiple glyphs per icon.
 
 > 🛑 **DANGER — Font Awesome Duotone**
 > Titanium cannot render Font Awesome duotone icons correctly because each icon uses two glyphs. If you work with Font Awesome Pro, avoid documenting duotone as supported.
+
+> 💡 **Mixing variant + icon in `class=`**
+> A common mistake is omitting the variant class and writing just `class="fa-github"`. The icon class only sets `text`/`title` (the glyph) — without the variant class (`.fa`, `.fas`, `.fab`, etc.) the `fontFamily` is missing and the glyph renders as the system font's fallback character. Always include both: `class="fab fa-github"` or `class="msr ms-home"`.

package/skills/purgetss/references/installation-setup.md

@@ -88,7 +88,7 @@ purgetss
 
 - `fonts`
 
-  Place icon, serif, sans-serif, or monospace font files here. See the [`build-fonts` command](./cli-commands.md#purgetss-build-fonts-alias-bf) for instructions.
+  Place icon, serif, sans-serif, or monospace font files here. See [Custom Fonts](./custom-fonts.md) for the full guide, or [`build-fonts` Command](./cli-commands.md#build-fonts-command) for the terse flag reference.
 
 > **CAUTION**
 > **PurgeTSS overwrites your existing `app.tss` file.**
@@ -152,9 +152,9 @@ To use the example files:
 > Every time `purgetss` runs, it copies the content of `_app.tss` to `app.tss`.
 
 ```tss
-/* PurgeTSS v7.2.7 */
-/* Created by César Estrada */
-/* https://github.com/macCesar/purgeTSS */
+// PurgeTSS v7.10.2
+// Created by César Estrada
+// https://purgetss.com
 
 /* _app.tss styles */
 '.bg-primary': {

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