@maccesar/titools 2.10.0 → 3.1.0

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

@@ -35,15 +35,7 @@ module.exports = {
     }
   },
   brand: {
-    logos: {
-      // Optional overrides. If omitted, PurgeTSS auto-discovers files from purgetss/brand/:
-      // primary: './docs/logo.svg',
-      // androidLauncher: './docs/app-icon.svg',
-      // androidSplash: './docs/splash.svg',
-      // monochrome: './docs/logo-mono.svg',
-      // iosDark: './docs/logo-dark.svg',
-      // iosTinted: './docs/logo-tinted.svg'
-    },
+    logos: {},  // empty = auto-discovers from purgetss/brand/
     padding: {
       ios: '4%',             // iOS aesthetic padding. Range 2-8%.
       androidLegacy: '10%',  // legacy ic_launcher.png padding %
@@ -53,15 +45,14 @@ module.exports = {
       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
     },
-    // Optional iOS overrides:
-    // ios: {
-    //   dark: false,           // skip DefaultIcon-Dark.png
-    //   tinted: false,         // skip DefaultIcon-Tinted.png
-    //   darkBackground: '#111' // opaque dark bg for DefaultIcon-Dark.png (null = transparent per Apple HIG)
-    // },
     confirmOverwrites: true  // prompt before overwriting files (set false to skip)
   },
   images: {
@@ -85,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
 

package/skills/purgetss/references/semantic-colors.md

@@ -302,6 +302,48 @@ Once the JSON and the `config.cjs` mapping are in place, you use the semantic cl
 
 When the appearance changes — whether from `Appearance.set(...)` or a system-level toggle — Titanium resolves each semantic color name to its `light` or `dark` value automatically. No event listeners, no manual repaint.
 
+### Opacity modifier auto-derivation
+
+As of PurgeTSS v7.9.0, you can apply the `/N` opacity modifier to **any class that resolves to a semantic name** in `semantic.colors.json`, and PurgeTSS will derive a new semantic key with that alpha pre-applied for both `light` and `dark` modes. This works for `bg-*`, `text-*`, `border-*`, and any other color-accepting utility whose class is mapped through `theme.extend.colors` in `config.cjs`.
+
+```xml
+<View class="bg-surface/65" />
+<Label class="text-on-surface/80" text="Subtle" />
+<View class="border border-accent/40" />
+```
+
+On the next `purgetss build` (or plain `purgetss`) run, the toolchain executes a three-step flow:
+
+1. **Detects the mapping** — PurgeTSS sees that, for example, `bg-surface` is mapped to the semantic name `surfaceColor` via `config.cjs`.
+2. **Derives a new key** — it adds `surfaceColor_65` (naming convention: `<originalKey>_<alphaPercent>`, underscore + integer percent) to `semantic.colors.json`, copying the original hex values for both modes and tagging each with `alpha: "65"`:
+
+   ```json
+   "surfaceColor_65": {
+     "light": { "color": "#F9FAFB", "alpha": "65" },
+     "dark":  { "color": "#0f172a", "alpha": "65" }
+   }
+   ```
+
+3. **Emits the rule against the derived key** — for example, `'.bg-surface/65': { backgroundColor: 'surfaceColor_65' }`. Light/Dark switching keeps working because Titanium handles the lookup like any other semantic color. The same flow runs for opacity inside an `apply:` string in `config.cjs`.
+
+#### Idempotency and the `Conflict` error
+
+Re-runs are idempotent: existing derived keys are reused, never duplicated. If you manually edit a derived key with values that disagree with what PurgeTSS would generate (different base color, different alpha, different shape), the next build halts with a `Conflict` error instead of silently overwriting your edits — you have to either revert the manual change or remove the derived key so it can be regenerated cleanly.
+
+> **DANGER**
+>
+> **Native rebuild required for new alpha entries**
+>
+> `semantic.colors.json` is read at **native build time**, not at runtime. The first time a brand-new opacity variant is auto-derived (a class like `bg-surface/65` you've never used before), the running app **will not see it** until the next full Titanium build. Liveview hot-reload alone does **not** refresh `semantic.colors.json` for the running app — only the native binary does.
+>
+> In practice: after introducing a new opacity class, run `purgetss build` once, then start a fresh native build (`appc run` / `ti build`) before resuming your usual Liveview cycle. Subsequent runs of the *same* `/N` value reuse the existing derived key and need no extra rebuild.
+
+#### Constraints
+
+- **Alpha range**: integer `0–100`, matching the standard opacity modifier syntax. Values outside this range are rejected.
+- **Base key must exist**: the semantic name behind the class (`surfaceColor` in the example) must already exist in `semantic.colors.json`. If it doesn't, PurgeTSS emits a warning for direct XML usage or throws an Error for `apply:` directives, with three concrete suggestions in the message.
+- **Naming is fixed**: the derived key is always `<originalKey>_<alphaPercent>` — underscore + integer percent. This mirrors the `/65` you typed and stays quote-free in `config.cjs` if you ever need to reference it manually.
+
 ## Using semantic colors in controllers
 
 Semantic colors also work from JavaScript. Three patterns cover the cases you'll hit.
@@ -368,10 +410,11 @@ A minimal semantic palette that covers most app surfaces:
 | Cards / elevated   | `surfaceHighColor`   | `#FFFFFF` | `#1e293b` | `bg-surface-high`          |
 | Primary text       | `textColor`          | `#111827` | `#f1f5f9` | `text-on-surface`          |
 | Secondary text     | `textSecondaryColor` | `#6B7280` | `#94a3b8` | `text-on-surface-variant`  |
+| Muted text         | `textMutedColor`     | `#9CA3AF` | `#64748b` | `text-muted`               |
 | Borders / dividers | `borderColor`        | `#E5E7EB` | `#334155` | `bg-border`                |
 | Accent             | `accentColor`        | `#3B82F6` | `#60a5fa` | `text-accent`, `bg-accent` |
 
-Start with these 5-6 colors and add more only when the design requires it. Fewer semantic colors means easier maintenance.
+Start with these 6-7 colors and add more only when the design requires it. Fewer semantic colors means easier maintenance.
 
 ## Related
 

package/skills/purgetss/references/tikit-components.md

@@ -316,9 +316,7 @@ Colors: `black`, `dark`, `light`, and `white` themes that affect background and
 
 Use this for code examples. Set `copy="true"` to add a copy button.
 
-> **Community-Discovered Pattern — Pro tip**
->
-> For best results, install a monospaced font (like Fira Code or JetBrains Mono) and configure `font-mono` in your PurgeTSS config.
+**Pro tip — recommended monospace fonts:** For best results, install a monospaced font (like Fira Code or JetBrains Mono) and configure `font-mono` in your PurgeTSS config. (Source: official tikit docs, `tikit.md` line ~390.)
 
 **Localization:** The copy button uses `L('copy', 'Copy')` for its title and `L('code_copied', 'Code copied!')` for the confirmation message. Add these keys to your `strings.xml` files for translation.