@maccesar/titools 2.9.0 → 2.10.1

package/skills/purgetss/references/custom-rules.md

@@ -1,35 +1,49 @@
 # Custom Rules
 
-Custom rules in PurgeTSS let you style Titanium elements, IDs, and classes in `config.cjs`. You can also target specific platforms, devices, or conditional blocks using global variables. Handy when a project spans iOS and Android and you want to keep styles in one place.
+Custom rules in PurgeTSS let you style Titanium elements, IDs, and classes from `config.cjs`. They are the bridge between the utility-first classes you write in XML and the platform-, device-, or condition-specific overrides Titanium projects often need. Because everything lives in a single `config.cjs`, projects that span iOS and Android can keep one source of truth for styling instead of fragmenting rules across multiple `.tss` files.
+
+This file mirrors the official rewrite — section names, examples, and ordering match the upstream docs so cross-referencing stays cheap.
 
 ## Classes, IDs, and Ti Elements
 
-Whether you want to style a Ti Element (also known as a markup element), a custom ID prefixed with a hash (`#`), or a custom class prefixed with a period (`.`), the structure is the same.
+Whether you want to style a Ti Element (a markup element such as `Label`), a custom ID prefixed with `#`, or a custom class prefixed with `.`, the structure inside `config.cjs` is the same. You always declare a key (the selector) whose value is an object containing one or more block keys (`DEFAULT`, `ios`, `android`, `tablet`, `handheld`, or `[if=...]`).
 
 ### Modifier Key
 
-- For Titanium elements, use the exact name of the element, such as `Label`, `Button`, or `ScrollView`.
-- For IDs, use `camelCase` to match the JavaScript convention.
-- For classes, use `kebab-case` to stay compatible with PurgeTSS v6.x and above. For example, use `.my-custom-class-name` instead of `.myCustomClassName`.
-
-> **CAUTION -- PurgeTSS v5 or Earlier Projects**
-> If your project started on PurgeTSS v5 or earlier and you now use 7.x.x or later, set `purge.options.missing` to `true` in `config.cjs`. It will report missing classes at the end of `app.tss` so you can update them to the new naming convention.
+- For Titanium elements, use the **exact name** of the element, such as `Label`, `Button`, or `ScrollView`. The casing must match Titanium's API (e.g. `TextField`, not `textfield` or `Text Field`).
+- For IDs, use `camelCase` to match Alloy's JavaScript convention (e.g. `mainBanner` referenced in XML as `id="mainBanner"`). The selector key inside `config.cjs` includes the `#` prefix.
+- For classes, use `kebab-case` to stay compatible with PurgeTSS v6.x and above. Use `.my-custom-class-name`, not `.myCustomClassName`. The kebab-case requirement is what most legacy projects trip over when they upgrade.
+
+> **CAUTION — Migrating from PurgeTSS v4 or v5 to v7+**
+>
+> If your project started on PurgeTSS v5 or earlier and you are now on 7.x.x or later, the class-naming convention changed (`camelCase` -> `kebab-case`) and the config moved to ESM-style `config.cjs`. The recommended upgrade path is:
+>
+> 1. **Audit current usage.** Set `purge.options.missing` to `true` in `config.cjs`. PurgeTSS will append a list of missing classes at the end of `app.tss` after the next compile — every entry is a class name you still need to migrate.
+> 2. **Rename selectors.** Convert every `.myCustomClassName` to `.my-custom-class-name` in both XML markup and `config.cjs`. The old camelCase names will not match anymore.
+> 3. **Convert config to `.cjs`.** If your project still uses `purgetss.config.js` or a CommonJS-style file with the old layout, rename the file to `config.cjs` and ensure it sits in `./purgetss/`. The single export must be `module.exports = { theme: { ... } }`.
+> 4. **Re-run `purgetss build`.** Verify the missing-classes list at the end of `app.tss` is empty before turning `missing` back off.
+>
+> Skipping any of these steps tends to surface as silently dropped styles at runtime — the app compiles, but selectors no longer match.
 
 ### Default, Platform, Device, or Conditional Blocks
 
-- To generate a global style, use either the lowercase `default` or the uppercase `DEFAULT` keyword.
-- To target a specific platform, use the `ios` or `android` keywords.
-- To target a specific device, use the `tablet` or `handheld` keywords.
-- To target a condition with a global variable, use the `[if=globalVariableName]` keyword.
+Inside any selector you can declare one or more of the following block keys. They translate to TSS query suffixes at compile time:
+
+- **Global style**: use either the lowercase `default` or the uppercase `DEFAULT` keyword. This becomes the bare selector with no platform/device qualifier.
+- **Specific platform**: use `ios` or `android`. These compile to `[platform=ios]` and `[platform=android]` query suffixes.
+- **Specific device**: use `tablet` or `handheld`. These compile to `[formFactor=tablet]` and `[formFactor=handheld]`.
+- **Conditional via global variable**: use `[if=globalVariableName]`. The exact key is preserved in the generated TSS, so you can reference any `Alloy.Globals.*` boolean.
 
 ### Property Values
 
-- For `Titanium` constants, `Alloy Configuration Values`, or `Global Variables`, always enclose them in quotes.
-- For `color` values, you can use `hex`, `8-digit hex`, `rgb(R,G,B)`, `rgba(R,G,B,A)`, `transparent`, or any of the standard color names. Use hex values if you want to avoid issues with the opacity modifier.
-- For `spacing` values, you can use different types of units: `em`, `rem`, `%`, `px`, `dp`, `cm`, or `in`.
-  - `%`, `px`, `cm`, or `in` are passed through without conversion.
-  - `em` or `rem` values are converted with this formula: `value * 16`.
-  - `dp` removes the unit and keeps the value as-is.
+The way you write property values determines how PurgeTSS emits them in the generated TSS. Pay particular attention to quoting — it is the single most common source of confusion.
+
+- For `Titanium` constants, `Alloy` configuration values, or global variables, **always enclose them in quotes** in `config.cjs` (e.g. `'Ti.UI.SIZE'`, `'Alloy.CFG.iPhoneXNotchSize'`). The quotes are stripped in the generated TSS so the constant resolves at runtime — without them, JavaScript would try to evaluate the constant inside `config.cjs`, which fails because Titanium's globals are not available there.
+- For `color` values, you can use `hex`, `8-digit hex` (with alpha), `rgb(R,G,B)`, `rgba(R,G,B,A)`, `transparent`, or any standard color name. Prefer hex values when you plan to use opacity modifiers — `rgba()` and named colors interact awkwardly with opacity utilities.
+- For `spacing` values you can mix unit types. Each unit follows a specific conversion rule:
+  - `%`, `px`, `cm`, and `in` are passed through to TSS without conversion.
+  - `em` and `rem` values are converted with the formula `value * 16` (so `1rem` becomes `16`).
+  - `dp` removes the unit and keeps the numeric value as-is, since Titanium treats unit-less numeric values as density-independent pixels by default.
 
 ## `config.cjs` File Example
 
@@ -81,7 +95,10 @@ module.exports = {
 };
 ```
 
-`./purgetss/styles/utilities.tss`
+## Custom `./purgetss/styles/utilities.tss` File
+
+PurgeTSS reads `config.cjs` and emits a single `utilities.tss` file that Alloy then merges with the rest of the project's styling. The file below shows what the example above generates — note how block keys translate into TSS query suffixes (`[platform=android]`, `[formFactor=tablet]`, `[if=...]`).
+
 ```tss
 /* Property: TextField */
 /* Description: A single line text field. */

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

@@ -35,12 +35,24 @@ module.exports = {
     }
   },
   brand: {
-    splash: false,           // also generate splash_icon.png × 5
-    padding: '15%',          // Android safe-zone. Range: 12% tight (mature logos) — 20% conservative. Spec floor 19.44%.
-    iosPadding: '4%',        // iOS aesthetic. Range: 2% bold — 8% conservative. No launcher mask.
-    darkBgColor: null,       // opaque dark bg for DefaultIcon-Dark.png (null = transparent per Apple HIG)
-    bgColor: '#FFFFFF',      // Android adaptive bg + iOS/marketplace flatten
-    notification: false,     // also generate ic_stat_notify.png × 5
+    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%.
+    },
+    android: {
+      splash: false,         // also generate splash_icon.png × 5
+      notification: false    // also generate ic_stat_notify.png × 5
+    },
+    ios: {
+      dark: true,            // generate DefaultIcon-Dark.png
+      tinted: true,          // generate DefaultIcon-Tinted.png
+      darkBackground: null   // null = transparent per Apple HIG
+    },
+    colors: {
+      background: '#FFFFFF'  // Android adaptive bg + iOS/marketplace flatten
+    },
     confirmOverwrites: true  // prompt before overwriting files (set false to skip)
   },
   images: {
@@ -64,6 +76,37 @@ The config file has four main sections: `purge`, `brand`, `images`, and `theme`.
 
 `brand:` and `images:` configure the matching CLI commands — see [CLI Commands: `brand`](./cli-commands.md#brand-command) and [CLI Commands: `images`](./cli-commands.md#images-command) for the full option lists. The rest of this page covers `purge` 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
+- `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
+
+For the property-by-property reference, see [Configurable Properties](./configurable-properties.md).
+
+### Overriding logo paths
+
+By default, PurgeTSS auto-discovers logo files from `purgetss/brand/`. If you want to use custom paths, add them to `brand.logos`:
+
+```javascript
+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
+    }
+  }
+};
+```
+
+You only need to override the ones you're using. Missing overrides still auto-discover from `purgetss/brand/`.
+
 ### `purge` Section
 
 The `purge` section controls how PurgeTSS removes unused classes or keeps the ones you want.

package/skills/purgetss/references/grid-layout.md

@@ -23,6 +23,9 @@ The snippet below shows the simplest layout. From there, you can mix columns and
 </Alloy>
 ```
 
+> **Visual Reference**
+> The official PurgeTSS docs ship a screenshot at `images/grid-system-example.png` (in the docs source repo) that visualizes how columns, rows, and spans render in a real Alloy view. Consult it when you need a quick mental model of the layout primitives — it is not embedded here, only referenced.
+
 ## Column Grid
 
 ### `grid-cols-{n}`
@@ -49,21 +52,7 @@ If a view uses `.row-span-3`, you can add three more views of the same height to
 
 ## Available Utilities
 
-These are the available utilities to control the grid.
-
-### Gutter Utilities
-
-- `gap-{size}`: Change the gap between rows and columns.
-- `gap-x-{size}` and `gap-y-{size}`: Change the gap between rows and columns independently.
-- `gap-{side}-{size}`: Change the gap on a specific side (t=top, r=right, b=bottom, l=left).
-
-### Column Span Utilities
-
-- `col-span-{n}`: Make an element span `n` columns.
-
-### Row Span Utilities
-
-- `row-span-{n}`: Make an element span `n` rows.
+The official source organizes the grid utilities into these categories. The structure below mirrors the official rewrite so you can map directly between this reference and the upstream docs.
 
 ### Direction Utilities
 
@@ -78,18 +67,48 @@ These are the available utilities to control the grid.
 
 - `grid-rows-{n}`: Create grids with `n` equally sized rows.
 
+### Column Span Utilities
+
+- `col-span-{n}`: Make an element span `n` columns inside a 12-column grid.
+
+### Row Span Utilities
+
+- `row-span-{n}`: Make an element span `n` rows inside a 12-row grid.
+
+### Gutter Utilities
+
+- `gap-{size}`: Change the gap between rows and columns.
+- `gap-x-{size}` and `gap-y-{size}`: Change the gap between rows and columns independently.
+- `gap-{side}-{size}`: Change the gap on a specific side (`t`=top, `r`=right, `b`=bottom, `l`=left).
+
 ### Row Placement Utilities
 
-Control horizontal alignment of elements within a row:
+Control horizontal placement of children inside a row:
 
-| Class | Effect |
-| --- | --- |
-| `start` | Align to the start of the row |
-| `end` | Align to the end of the row |
-| `center` | Align to the center of the row |
+| Class    | Effect                            |
+| -------- | --------------------------------- |
+| `start`  | Align to the start of the row     |
+| `end`    | Align to the end of the row       |
+| `center` | Align to the center of the row    |
 
 These apply to child views inside a `grid-cols-*` container and control horizontal placement within the grid cell.
 
+## Row Placement Use Cases
+
+Combining `row-span-{n}` with `grid-rows-{n}` lets you describe how an element occupies vertical space inside a grid column. The table below covers the most common combinations a Titanium UI tends to need. Every entry is verified against the `grid-rows-{n}` and `row-span-{n}` utilities described in the official source.
+
+| Pattern                                  | Example classes                          | Result                                                                                                  |
+| ---------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| Full-height column item                  | `grid-rows-1` + `row-span-1`             | One element fills the entire vertical space of the column.                                              |
+| Two equal stacked items                  | `grid-rows-2` + two children no span     | Two views stack vertically, each taking 50% of the column height.                                       |
+| Tall hero on top, short footer at bottom | `grid-rows-12` + `row-span-9`, `row-span-3` | Hero takes 75% of the column height, footer takes 25%.                                                  |
+| 3-6-3 vertical split                     | `grid-rows-12` + `row-span-3`, `row-span-6`, `row-span-3` | Header / body / footer split. Mirrors the 3-6-3 horizontal split shown for `col-span-{n}`.              |
+| Sidebar that spans every row             | `grid-rows-4` + child with `row-span-4`  | Element occupies the full height of a 4-row column. Useful for vertical separators or full-height nav.  |
+| Two short rows above a tall row          | `grid-rows-12` + `row-span-3`, `row-span-3`, `row-span-6` | Two preview cards above a larger detail panel.                                                          |
+
+> **Note**
+> Just like `col-span-{n}`, the spans you write must add up to the value declared in `grid-rows-{n}` for the layout to fill the column without leftover space.
+
 ## Community-Discovered Patterns
 
 The following notes come from community experience using the PurgeTSS grid system in Titanium projects. They clarify how the grid relates to Titanium's layout engine (not CSS Grid) and offer common use cases for row placement.
@@ -99,8 +118,8 @@ The following notes come from community experience using the PurgeTSS grid syste
 
 ### Common Use Cases for Row Placement
 
-| Class | Use case |
-| --- | --- |
-| `start` | Left-aligned content |
-| `end` | Right-aligned buttons or labels |
-| `center` | Centered content blocks |
+| Class    | Use case                          |
+| -------- | --------------------------------- |
+| `start`  | Left-aligned content              |
+| `end`    | Right-aligned buttons or labels   |
+| `center` | Centered content blocks           |

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

@@ -1,20 +1,21 @@
 # Icon Font Libraries
 
-> **Official Icon Fonts for PurgeTSS**
-> Previous versions of PurgeTSS included several icon font libraries such as Bootstrap Icons, Boxicons, LineIcons, and Tabler Icons. The list was reduced to keep maintenance manageable.
+> ℹ️ **INFO — Official Icon Fonts for PurgeTSS**
 >
-> These are the official icon fonts supported by 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`)
-> - [Framework7](https://framework7.io/icons/)
+> - [Framework 7](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)
 
-For the official install flow for those vendors, see [CLI Commands](./cli-commands.md#icon-library-command).
+For the official install flow for the supported vendors, see [CLI Commands](./cli-commands.md#icon-library-command).
 
 ## Recreate Removed Libraries
 
-You can recreate removed libraries using the `build-fonts` command.
+You can recreate any deprecated library using the `build-fonts` command.
 
 ### 1. Download the Libraries
 
@@ -29,7 +30,7 @@ Start by downloading the libraries from their official websites:
 
 Put the desired libraries in the `./purgetss/fonts` folder.
 
-> **INFO**
+> ℹ️ **INFO**
 > Copy the TrueType or OpenType font files and the `.css` file.
 
 ```bash
@@ -67,14 +68,14 @@ The `build-fonts` command generates `./purgetss/styles/fonts.tss` with Unicode c
 /* To use your Icon Fonts in Buttons AND Labels each class sets 'text' and 'title' properties */
 
 /* boxicons.css */
-'.bxl-meta': { text: '\uef27', title: '\uef27' }
-'.bx-lemon': { text: '\uef28', title: '\uef28' }
-'.bxs-lemon': { text: '\uef29', title: '\uef29' }
+'.bxl-meta': { text: '', title: '' }
+'.bx-lemon': { text: '', title: '' }
+/* ... */
 
 /* lineicons.css */
-'.lni-500px': { text: '\uea03', title: '\uea03' }
-'.lni-add-files': { text: '\uea01', title: '\uea01' }
-'.lni-adobe': { text: '\uea06', title: '\uea06' }
+'.lni-500px': { text: '', title: '' }
+'.lni-add-files': { text: '', title: '' }
+/* ... */
 ```
 
 ### Rename the Style Rule Name
@@ -116,15 +117,15 @@ When you use the `--modules` option, it generates a `./app/lib/purgetss.fonts.js
 const icons = {
   /* boxicons */
   boxicons: {
-    bxlMeta: '\uef27',
-    bxLemon: '\uef28',
-    bxsLemon: '\uef29'
+    bxlMeta: '',
+    bxLemon: ''
+    /* ... */
   },
   /* lineicons */
   lni: {
-    '500px': '\uea03',
-    addFiles: '\uea01',
-    adobe: '\uea06'
+    '500px': '',
+    addFiles: ''
+    /* ... */
   }
 };
 exports.icons = icons;
@@ -147,9 +148,9 @@ New group prefix: `li`
 `./purgetss/styles/fonts.tss`
 ```tss
 /* lineicons/li.css */
-'.li-zoom-out': { text: '\uea02', title: '\uea02' }
-'.li-zoom-in': { text: '\uea03', title: '\uea03' }
-'.li-zip': { text: '\uea04', title: '\uea04' }
+'.li-zoom-out': { text: '', title: '' }
+'.li-zoom-in': { text: '', title: '' }
+/* ... */
 ```
 
 `./app/lib/purgetss.fonts.js`
@@ -163,12 +164,13 @@ const icons = {
 exports.icons = icons;
 ```
 
-> **DANGER**
-> Make sure the new prefix remains unique to avoid conflicts with other class prefixes.
+> 🛑 **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.
 
-> **Font Awesome Duotone**
+> 🛑 **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.

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

@@ -14,9 +14,35 @@ Install PurgeTSS globally on your machine using [NPM](https://www.npmjs.com/).
 
 ## XML Validation
 
-PurgeTSS v7.5.3 added XML validation that flags any `--` (double-dash) sequence inside XML comments. Titanium's XML parser treats `--` in comments as invalid, and PurgeTSS now detects those sequences before they break the compile step.
+Before purging, PurgeTSS pre-checks every XML file in your project. One case worth calling out: double dashes (`--`) are not allowed inside XML comments. That restriction comes from the XML spec itself, not from PurgeTSS, but many people only run into it once a tool actually parses the file.
 
-If you see a validation warning from PurgeTSS pointing at a view file, replace the offending comment with an alternative marker (for example, `//` or `==`) and re-run the build.
+### Bad comment example
+
+```xml
+<!-- Options: --flag or --value -->
+```
+
+The `--flag` inside that comment is illegal. PurgeTSS stops with a pointer to the offending line:
+
+```text
+XML comment contains illegal "--" sequence ("--flag")
+Fix: Replace "--" with an em dash or reword the comment to avoid double dashes
+```
+
+### Why it fails
+
+Per the XML 1.0 specification, the two-character sequence `--` is reserved as the close-comment indicator (`-->`). It cannot appear anywhere inside a comment body, even mid-string. Any conforming XML parser will reject the document, so catching it up front is more helpful than a confusing TSS output later.
+
+### How to fix
+
+Pick whichever of these reads best:
+
+- Replace `--` with a single Unicode em dash (`—`) so the sequence is no longer two ASCII hyphens.
+- Spell out the dashes (for example, write `dash-dash flag` instead of `--flag`).
+- Move the option list outside the comment — for instance, into a sibling `<!-- Options -->` header followed by documentation in your README or `config.cjs` notes.
+- Rephrase so the two dashes simply do not sit next to each other.
+
+Any of those approaches keeps the comment readable and produces a document that every XML parser will accept.
 
 ## Run PurgeTSS the First Time
 

package/skills/purgetss/references/ios-large-titles.md

@@ -2,13 +2,25 @@
 
 Enabling Large Titles on a Window is not a single-property change. When you pair `largeTitleEnabled` with a `ScrollView` inside a `NavigationWindow` or `TabGroup`, **three interdependent iOS Window properties** must work together — otherwise you get either content hidden behind the nav bar or a visible rendering delay when the window opens.
 
-| Property | Value | Why it matters |
-| --- | --- | --- |
-| `autoAdjustScrollViewInsets` | `true` | iOS automatically adjusts the ScrollView content insets so content starts below the nav bar instead of behind it. |
-| `extendEdges` | `[Ti.UI.EXTEND_EDGE_ALL]` | Content extends under the nav/tab bars, producing the translucent blur effect Large Titles depend on. |
-| `largeTitleEnabled` | `true` | Shows the large title that collapses to the standard nav bar title as the user scrolls. |
+## The problem
+
+Setting `largeTitleEnabled: true` in isolation looks like it should be enough — Apple's docs suggest a single switch. In practice, omitting the two companion properties produces three distinct visual bugs that are easy to attribute to "iOS being weird" but really come from the layout engine not having enough information:
+
+1. **Content overlaps behind the nav bar.** The ScrollView starts at `y=0`, hidden under the translucent navigation bar. Users see the top of the list cut off and assume content is missing. This happens when `largeTitleEnabled` is set but `autoAdjustScrollViewInsets` is not.
+2. **The large title flashes / renders with a delay.** On window open, the nav bar region paints empty for a frame or two, then the title pops in. With all three properties present, iOS has the layout it needs *before* the first paint, so the title is there from frame zero. Without `extendEdges`, there is a measurable shadow flash as the system recomputes the layout.
+3. **Collapse glitches on scroll.** The large title shrinks to standard size as the user scrolls down — that is the whole point. But if `extendEdges` is missing, the collapse animation can stutter or skip frames because iOS has to recompute the safe-area inset for every scroll event instead of treating the nav bar as part of the content area.
+
+The fix is not to pick the "right" property. It is to set all three together.
 
-Using only `largeTitleEnabled` causes the nav bar region to render empty for a moment before the title draws. Using `extendEdges` without `autoAdjustScrollViewInsets` pushes content behind the nav bar without compensating the ScrollView insets. All three must be present.
+## The solution: 3 interdependent properties
+
+| Property                     | Value                     | What it does                                                                                                                                |
+| ---------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `autoAdjustScrollViewInsets` | `true`                    | iOS automatically adjusts the ScrollView content insets so content starts below the nav bar instead of behind it. Without this, the ScrollView's first item sits hidden behind the translucent nav bar. |
+| `extendEdges`                | `[Ti.UI.EXTEND_EDGE_ALL]` | Content extends under the nav and tab bars, producing the translucent blur/refraction effect Large Titles depend on. Skipping this causes the shadow flash on open and stutters the collapse animation. |
+| `largeTitleEnabled`          | `true`                    | Shows the oversized title in the navigation bar that collapses to standard size as the user scrolls. This is the master switch — the other two are required for it to render correctly. |
+
+Without `autoAdjustScrollViewInsets`, `extendEdges` pushes the content behind the nav bar without compensating the ScrollView insets. Without `extendEdges` + `autoAdjustScrollViewInsets`, using only `largeTitleEnabled` causes the large title to render with a visible delay: the empty nav bar area appears first, then the title draws. With all three properties, iOS calculates the layout before displaying the window.
 
 ## iOS-only — use the `ios:` modifier
 
@@ -39,7 +51,7 @@ Generated style in `./purgetss/styles/utilities.tss`:
 
 Individual windows now only need to override `largeTitleDisplayMode` when they want different collapse behavior (e.g. detail windows).
 
-> **Why an `ios:` block and not an inline `ios:` prefix?** `auto-adjust-scroll-view-insets` and `extend-edges-all` are platform-specific classes — they only exist with `[platform=ios]` suffix in `utilities.tss`. The `ios:` block ensures PurgeTSS resolves the platform-suffixed version. See [apply-directive.md](apply-directive.md) → "Platform-Specific Classes".
+> **Why an `ios:` block and not an inline `ios:` prefix?** `auto-adjust-scroll-view-insets` and `extend-edges-all` are platform-specific classes — they only exist with `[platform=ios]` suffix in `utilities.tss`. The `ios:` block ensures PurgeTSS resolves the platform-suffixed version. See [apply-directive.md](./apply-directive.md) → "Platform-Specific Classes".
 
 ## NavigationWindow example
 
@@ -77,15 +89,15 @@ On iOS, `TabGroup` wraps each `Tab`'s Window in an **implicit NavigationWindow**
 </Alloy>
 ```
 
-## Controlling the collapse behavior: `largeTitleDisplayMode`
+## Controlling large title display
 
-`largeTitleDisplayMode` controls how the title behaves in the navigation stack:
+`largeTitleDisplayMode` controls how the title behaves in the navigation stack — whether it stays large, always shrinks to standard size, or follows the previous window. Combine the three base properties (which make Large Titles render correctly at all) with `largeTitleDisplayMode` per window to get the per-screen behavior you want.
 
-| Mode | Constant | Behavior |
-| --- | --- | --- |
-| Automatic | `Ti.UI.iOS.LARGE_TITLE_DISPLAY_MODE_AUTOMATIC` | Inherits from previous window; collapses on scroll. |
-| Always | `Ti.UI.iOS.LARGE_TITLE_DISPLAY_MODE_ALWAYS` | Title stays large regardless of scroll position. |
-| Never | `Ti.UI.iOS.LARGE_TITLE_DISPLAY_MODE_NEVER` | Always uses the standard (small) title size. |
+| Mode      | Constant                                       | Behavior                                                                                                       |
+| --------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| Automatic | `Ti.UI.iOS.LARGE_TITLE_DISPLAY_MODE_AUTOMATIC` | Inherits the display mode from the previous window in the navigation stack and collapses on scroll. The default. |
+| Always    | `Ti.UI.iOS.LARGE_TITLE_DISPLAY_MODE_ALWAYS`    | Title stays large regardless of scroll position. Useful for top-level screens that should never collapse.       |
+| Never     | `Ti.UI.iOS.LARGE_TITLE_DISPLAY_MODE_NEVER`     | Always uses the standard (small) title size. The right choice for detail windows pushed via `openWindow()`.     |
 
 ### Detail windows: use `large-title-display-mode-never`
 
@@ -126,6 +138,10 @@ Sizing the content height to `Ti.UI.SIZE` is what lets iOS determine whether the
 | `content-w-screen` | `contentWidth` | `Ti.UI.FILL` |
 | `content-h-auto` | `contentHeight` | `Ti.UI.SIZE` |
 
+> 💡 **TIP**
+>
+> Set the three base properties (`autoAdjustScrollViewInsets`, `extendEdges`, `largeTitleEnabled`) as global defaults in `config.cjs`, then override `largeTitleDisplayMode` per window only when needed.
+
 ## Community-Discovered Patterns
 
 ### TabGroup implicit-NavigationWindow wrapping
@@ -138,4 +154,4 @@ When `theme.Window.ios.apply` sets `large-title-enabled` as a default, every pus
 
 ### Cross-reference
 
-The three-property pairing (`autoAdjustScrollViewInsets` + `extendEdges` + `largeTitleEnabled`) is also documented as a reusable global-defaults recipe in [apply-directive.md](apply-directive.md) under *Community-Discovered Patterns → Global Window defaults for Large Titles + ScrollView (iOS)*. Prefer that recipe over per-window repetition whenever the whole app uses Large Titles.
+The three-property pairing (`autoAdjustScrollViewInsets` + `extendEdges` + `largeTitleEnabled`) is also documented as a reusable global-defaults recipe in [apply-directive.md](./apply-directive.md) under *Community-Discovered Patterns → Global Window defaults for Large Titles + ScrollView (iOS)*. Prefer that recipe over per-window repetition whenever the whole app uses Large Titles.

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

@@ -101,6 +101,62 @@ Recommended sizes for common UI elements (in source pixels, assumed 4×):
 - **List-row thumbnail**: at least `320×320`
 - **Button background**: match the intended display size × 4
 
+## Pinning the output width with `--width`
+
+The 4× master convention works well for raster sources (`.png`, `.jpg`, `.webp`) because the file's pixel dimensions usually reflect the intended 4× size. **SVGs are different.** Their logical size comes from the `viewBox`, and vector editors (Affinity Designer, Illustrator, Figma exports) frequently emit viewBoxes in points or with disproportionate values — a logo can ship with `viewBox="0 0 29559 13542"` and `purgetss images` would happily scale every density from that base, producing files far too large for any UI surface.
+
+`--width <n>` (added in PurgeTSS v7.8.0) is the escape hatch: it pins the **`mdpi` / `@1x`** output width to exactly `n` pixels, then derives every other density from that base. Height stays proportional to the source aspect ratio — you only specify width.
+
+```bash
+purgetss images logo.svg --width 256
+```
+
+### Multiplier table
+
+The pinned width drives the scale for every density:
+
+| Scale | Multiplier | Width if `--width 256` |
+| --- | --- | --- |
+| `mdpi` / `@1x` | ×1 | 256 |
+| `hdpi` | ×1.5 | 384 |
+| `xhdpi` / `@2x` | ×2 | 512 |
+| `xxhdpi` / `@3x` | ×3 | 768 |
+| `xxxhdpi` | ×4 | 1024 |
+
+### Validation
+
+`--width` accepts integers in `[1, 8192]`. Out-of-range values are rejected immediately and the command exits without writing anything:
+
+```bash
+purgetss images logo.svg --width 0
+# Invalid --width '0'. Must be an integer between 1 and 8192.
+
+purgetss images logo.svg --width 9000
+# Invalid --width '9000'. Must be an integer between 1 and 8192.
+
+purgetss images logo.svg --width abc
+# Invalid --width 'NaN'. Must be an integer between 1 and 8192.
+```
+
+The upper bound of `8192` exists because `--width 8192` already produces a `xxxhdpi` output of 32 768 px — that's Sharp's render ceiling and well beyond anything a Titanium UI needs.
+
+### The hint message for unflagged SVGs
+
+Whenever you run `purgetss images` against an SVG **without** `--width`, PurgeTSS prints a one-time hint:
+
+```text
+⚠  SVG source detected without --width. Output sizes will be derived from
+   each SVG's viewBox (treated as a 4× master).
+   For SVGs from vector editors with disproportionate viewBoxes, pass
+   --width <n> (e.g. --width 256) to pin the @1x/mdpi width.
+```
+
+This is a hint, **not an error**. The legacy 4×-from-viewBox behavior still runs in the same invocation. If your SVG has a sensible viewBox (`300×150` for a 300px-wide logo at 1×, etc.), the default is fine. If the viewBox is in points or noticeably larger than expected, re-run with `--width <n>` for predictable scaling.
+
+### Why CLI-only (no `images:` config equivalent)
+
+`--width` deliberately has **no matching property** in the `images:` block of `purgetss/config.cjs`. The reason: width is a **per-asset** decision, not a project-wide setting. A hero illustration, an inline icon, and a logo each need different widths — pinning a single value globally would make most outputs wrong. Project-wide settings like `quality` or `format` belong in `config.cjs`; per-invocation values like `--width` only make sense as CLI flags passed against the specific source you're regenerating.
+
 ## The `images:` config section
 
 On the first run, `purgetss images` injects an `images:` block into your existing `purgetss/config.cjs` (between `brand:` and `theme:`) with these defaults:
@@ -291,6 +347,7 @@ 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. |
 
 **Project & output**
 

package/skills/purgetss/references/opacity-modifier.md

@@ -53,8 +53,17 @@ module.exports = {
 '.bg-primary': { backgroundColor: '#ce10cc' }
 ```
 
-> **CAUTION -- Semantic Colors**
-> Semantic colors cannot be modified with the opacity modifier because they are defined as an object with light and dark values.
+## Semantic colors
+
+Since v7.9.0, opacity modifiers also work on classes that resolve to a semantic color. Any class mapped to a semantic color entry can use `/<percent>` syntax.
+
+```xml
+<View class="bg-surface/65" />
+```
+
+PurgeTSS detects that `bg-surface` maps to the semantic name `surfaceColor`, then derives a new semantic key (`surfaceColor_65`) with the original `light` and `dark` hex values plus the requested alpha for both modes. It writes that key back to `semantic.colors.json` and emits the rule against the derived key. Light/Dark switching still works.
+
+See [Semantic colors — Opacity modifier auto-derivation](./semantic-colors.md#opacity-modifier-auto-derivation) for the full mechanics.
 
 ## Community-Discovered Patterns