@maccesar/titools 3.2.0 → 4.0.0

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

@@ -1,176 +1,266 @@
 # 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.
+>
+> The resolved classes are written to the generated `app/styles/app.tss`, not to `purgetss/styles/utilities.tss`. If you go looking for a class like `.ms-home`, check `app.tss`.
+
+### 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
+```
 
-# alias:
-purgetss bf [-m]
+### 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>
 ```
 
-### The `fonts.tss` File
+## 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 `build-fonts` command generates `./purgetss/styles/fonts.tss` with Unicode characters and style rules.
+Generated `app.tss` excerpt:
+```css
+// PurgeTSS v7.10.2
+// Created by César Estrada
+// https://purgetss.com
 
-`./purgetss/styles/fonts.tss`
-```tss
-'.boxicons': { font: { fontFamily: 'boxicons' } }
-'.lineicons': { font: { fontFamily: 'LineIcons' } }
+/* Ti Elements */
+'View': { width: Ti.UI.SIZE, height: Ti.UI.SIZE }
+'Window': { backgroundColor: '#FFFFFF' }
 
-/* Unicode Characters */
-/* To use your Icon Fonts in Buttons AND Labels each class sets 'text' and 'title' properties */
+/* Default Font Awesome */
+'.fa': { font: { fontFamily: 'FontAwesome7Free-Solid' } }
+'.fa-home': { text: '', title: '' }
 
-/* boxicons.css */
-'.bxl-meta': { text: '', title: '' }
-'.bx-lemon': { text: '', title: '' }
-/* ... */
+/* Material Icons */
+'.mi': { font: { fontFamily: 'MaterialIcons-Regular' } }
+'.mi-home': { text: '', title: '' }
 
-/* lineicons.css */
-'.lni-500px': { text: '', title: '' }
-'.lni-add-files': { text: '', title: '' }
-/* ... */
+/* Material Symbols */
+'.ms': { font: { fontFamily: 'MaterialSymbolsOutlined-Regular' } }
+'.ms-home': { 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,62 @@
 # 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.10.x, 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.11.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.11.x
+
+v7.11.0 and v7.11.1 are additive — **no breaking changes**. The headline addition is a compile-time SVG image pipeline that runs automatically as a post-step of `purgetss`, plus a `config.cjs` syntax validator. Nothing new is required on upgrade; the new surface is opt-in. Full release notes in [`version-history.md`](./version-history.md).
+
+### Added in v7.11.0 — SVG compile-time image pipeline (opt-in)
+
+Reference an `.svg` in a view or controller with `image="/images/<sub>/<name>.svg"` (or `backgroundImage="..."`) **alongside** utility classes that resolve to a numeric width/height (`w-32`, `w-(300)`, `h-auto`, …), and after the regular purge finishes PurgeTSS compiles that SVG into the 8 Titanium density variants (5 Android + 3 iPhone PNGs), sizing them from the dimensions resolved in `app.tss`. Titanium loads the generated `.png` automatically at runtime even though the source still references `.svg` — the SVG attribute is never rewritten.
+
+- Cache lives at `purgetss/.cache/svg-images.json` — **add it to `.gitignore`**.
+- Projects that never reference `.svg` images with sizing classes see no change. This is entirely opt-in by usage.
+
+See [`multi-density-images.md`](./multi-density-images.md).
+
+### Added in v7.11.0 — `images.files` override array
+
+`config.cjs` accepts an `images.files` array to pin width/height for individual files in `purgetss/images/`:
+
+```javascript
+images: {
+  autoSync: true,
+  files: [
+    { filename: 'images/logos/logo.png', width: 128, height: 52 }
+  ]
+}
+```
+
+Entries override a source's natural dimensions when `purgetss images` runs; CLI `--width` still wins over both. SVGs detected by the purge pipeline populate entries automatically (subject to `images.autoSync`). Raster entries you add by hand survive subsequent runs untouched.
+
+### Added in v7.11.0 — `images.autoSync` opt-out
+
+`images.autoSync` (boolean, default `true`). When `false`, purge still computes dimensions and generates the density PNGs, but never writes back to `config.cjs` — for devs who manage `images.files` by hand.
+
+### Added in v7.11.0 — `config.cjs` syntax validator
+
+Type mismatches in known config fields now print a formatted `Config Syntax Error` block (file, JSON path, context, issue, and a fix snippet) instead of a cryptic downstream crash like `rule.startsWith is not a function`. Currently validated: `theme.fontFamily.*` and `theme.extend.fontFamily.*` — **each font-family value must be a string**. The validator runs at config load time.
+
+### Changed in v7.11.1 — symmetric cascade + current-run sync
+
+- **Symmetric width/height cascade** — a class can pin width-only, height-only, or both. The unpinned side stays `null` in `images.files` and is re-derived from the SVG viewBox on every run, so no stale auto-derived dimension gets frozen into config.
+- **`syncConfigImages` mirrors the current run** instead of taking `max()` across past runs. Shrinking a class (e.g. `h-52` → `h-16`) now propagates to `config.cjs` rather than freezing the entry at the larger past size. Pin manually with `images.autoSync: false`.
+- **`purgetss images` respects `--yes`** for overwrite confirmations — the prompt no longer reappears when `--yes` is supplied.
+- **SVGs listed in `images.files` always emit `.png`** regardless of `images.format`, because Titanium's `.svg → .png`-only runtime fallback means other formats wouldn't load. Raster files and SVGs not in `images.files` still honor `format`.
+
+### What to review
+
+- Add `purgetss/.cache/` to `.gitignore` before your next commit if you reference `.svg` images with sizing classes.
+- If your `config.cjs` sets `theme.fontFamily` or `theme.extend.fontFamily` to anything other than a string, fix it now — the validator will halt with a `Config Syntax Error` block.
+- If you manage `images.files` by hand and don't want purge overwriting your sizes, set `images.autoSync: false`.
+
+---
+
 ## 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).
@@ -372,3 +423,4 @@ If you previously worked around this by inlining the gradient directly in TSS, r
 - 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`.
+- After v7.11.0: reference `.svg` images with numeric `w-*`/`h-*` classes to opt into the compile-time SVG pipeline (add `purgetss/.cache/` to `.gitignore`). Ensure every `theme.fontFamily.*` value is a string, not a Tailwind-style array, or the new config validator hard-fails. Use `images.files` to pin per-file sizes and `images.autoSync: false` to stop the pipeline writing back to `config.cjs`.

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

@@ -163,19 +163,56 @@ On the first run, `purgetss images` injects an `images:` block into your existin
 
 ```javascript
 images: {
+  autoSync: true,          // false = SVG pipeline computes dims but doesn't write to images.files
   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)
+  confirmOverwrites: true, // prompt before overwriting files (set false to skip)
+  files: []                // per-file overrides: [{ filename: 'images/<sub>/<name>.<ext>', width, height? }]
 }
 ```
 
 | Key | Default | Purpose |
 | --- | --- | --- |
+| `autoSync` | `true` | When `false`, the SVG pipeline still computes dimensions and generates PNGs but never writes back to `images.files`. See [SVG-aware compile-time pipeline](./svg-pipeline.md). |
 | `quality` | `85` | Quality for lossy formats (JPEG, WebP, AVIF). Range `0–100`. |
 | `format` | `null` | `null` keeps each source's original format. Set `'webp'`, `'jpeg'`, or `'png'` to convert every output. |
 | `confirmOverwrites` | `true` | When `false`, the `[y/N/a]` prompt is skipped. |
+| `files` | `[]` | Per-file dimension overrides. See [Per-file overrides](#per-file-overrides-with-imagesfiles). |
 
-Change whatever you want to override globally; CLI flags still win for one-off runs.
+Change whatever you want to override globally; CLI flags still win for one-off runs. `autoSync` and `files` arrived in v7.11.0 to support the [SVG-aware compile-time pipeline](./svg-pipeline.md).
+
+## Per-file overrides with `images.files`
+
+`images.files` (v7.11.0) is an array of per-file dimension pins. It does **not** filter which images get processed — `purgetss images` always walks every supported file under `purgetss/images/`. Entries in `files` only override the source and derived sizing for files whose `filename` matches.
+
+```javascript
+images: {
+  // ...
+  files: [
+    { filename: 'images/logos/logo.svg',    width: 256 },              // SVG: width pins @1x/mdpi
+    { filename: 'images/buttons/hero.svg',  width: 512, height: 128 }, // both dims pinned
+    { filename: 'images/photos/banner.jpg', width: 800 }               // raster: behaves like --width 800
+  ]
+}
+```
+
+Precedence is the same for every file processed:
+
+1. CLI `--width <n>` wins.
+2. Otherwise, the matching entry in `images.files` (if any).
+3. Otherwise, the source's natural size: `viewBox` for SVG, intrinsic pixel size for rasters (treated as 4× master).
+
+| Source | In `files`? | Width source | Output format |
+| --- | --- | --- | --- |
+| `logos/logo.svg` | yes | 256 px @1x (from `files`) | `png` (forced; see below) |
+| `buttons/hero.svg` | yes | 512×128 pinned | `png` (forced) |
+| `photos/banner.jpg` | yes | 800 px @1x | jpg (or `format` if set) |
+| `icons/cart.svg` (not listed) | no | from SVG viewBox | follows `format` |
+| `backgrounds/sunset.png` (not listed) | no | source as 4× master | png (or `format`) |
+
+**SVGs in `files` always emit `.png`.** PurgeTSS detects that the file is a vector source whose entry exists because the developer pinned it from a view/controller reference (`image="/.../foo.svg"`). Titanium's runtime only falls back from `.svg` references to `.png`, never `.webp`, `.jpeg`, or another format. Emitting anything else here would silently produce files Titanium cannot load.
+
+Raster entries you add by hand survive subsequent runs untouched. For SVGs detected by the [post-purge pipeline](./svg-pipeline.md), entries populate automatically — set `autoSync: false` if you do not want the pipeline writing into this section.
 
 ## Output layouts
 
@@ -304,6 +341,19 @@ 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.
 
+> **WARNING — WebP and SVG references don't mix**
+>
+> Titanium's runtime fallback for `image="/.../foo.svg"` resolves to `.png` **only** (verified empirically). Other formats — `.webp`, `.jpeg`, `.avif` — are not picked up through the `.svg` reference.
+>
+> If both `.png` and `.webp` of the same basename live next to each other on disk, the `.svg` fallback **breaks entirely**. Titanium then shows nothing for that view.
+>
+> PurgeTSS protects you in two places:
+>
+> - SVGs listed in `images.files` always emit `.png`, even with `format: 'webp'`. The output line says `png (forced; ignores format: webp)`.
+> - The post-purge [SVG pipeline](./svg-pipeline.md) always emits `.png` regardless of `format`.
+>
+> `format` only applies to raster sources and SVGs not listed in `files` — the ones you reference directly as `.webp` in XML instead of through `.svg`.
+
 ## 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).
@@ -485,5 +535,6 @@ Shows every file that would be written, no side effects.
 
 ## See also
 
+- [SVG-aware compile-time pipeline](./svg-pipeline.md) — the post-purge SVG pipeline that auto-generates density PNGs from `image="/.../foo.svg"` references sized by utility classes.
 - [`images` command reference](./cli-commands.md#images-command) — terse flag list.
 - [App Icons & Branding](./app-branding.md) — sibling `brand` command for launcher icons and marketplace artwork.