@maccesar/titools 3.2.0 → 4.0.0

package/skills/purgetss/references/svg-pipeline.md

@@ -0,0 +1,249 @@
+# SVG-Aware Compile-Time Image Pipeline
+
+Added in PurgeTSS v7.11.0 (refined in v7.11.1), the SVG pipeline runs as a **post-step of `purgetss`** — after the regular purge finishes and `app.tss` is finalized. It scans your views and controllers for SVG references, resolves each SVG's display size from the utility classes on the same node, and generates the matching multi-density PNGs. You do **not** call `purgetss images` separately or declare dimensions anywhere else. The cascade of `w-*` / `h-*` classes in your XML decides the size.
+
+For the standalone `purgetss images` command (all files under `purgetss/images/`, CLI flags, format conversion), see [Multi-density images](./multi-density-images.md).
+
+> **INFO — At a glance**
+>
+> Drop an SVG into `purgetss/images/`, reference it from a view as `image="/images/<sub>/<name>.svg"` with a numeric `w-*` or `h-*` class, and run `purgetss`. The pipeline emits 8 density variants (5 Android + 3 iPhone PNGs). Titanium loads the generated `.png` at runtime even though your XML still says `.svg`. The SVG attribute in your source is never rewritten.
+
+## Why this exists
+
+Titanium doesn't load `.svg` files natively in `Ti.UI.ImageView`. Without help you have two options, both manual:
+
+1. Hand-rasterize every SVG into `app/assets/{iphone,android}/images/.../*.png` for every density. Tedious, easy to get wrong, and easy to forget when you swap a logo.
+2. Run `purgetss images` manually after every SVG edit. Better, but still manual, and you have to know the dimensions in advance.
+
+The SVG pipeline removes both chores: you reference the `.svg` from a view, size it with the same utility classes you use everywhere else, and `purgetss` generates the PNGs on the next run.
+
+## The runtime trick
+
+When a view requests `image="/foo.svg"` and Titanium cannot use that file as SVG, the image loader falls back to a `.png` with the same basename in the platform assets folder. If PurgeTSS writes `foo.png` plus `@2x`, `@3x`, and the Android densities, the view loads correctly even though the XML still references `.svg`. The pipeline never touches the `.svg` string in your source.
+
+## How it works (the short version)
+
+```text
+purgetss
+├─ regular purge → writes app.tss with .w-32, .h-auto, .w-(300), etc.
+└─ SVG post-step:
+   1. Parse app.tss → class → props map
+   2. Scan views (.xml) and controllers (.js) for SVG references
+   3. For each SVG, resolve width/height by applying its classes against app.tss
+   4. Sync images.files in config.cjs (autoSync ON)
+   5. Generate PNGs with Sharp, using a hash-based cache to skip unchanged files
+```
+
+The pipeline only touches SVGs you actually reference from views or controllers. Files that sit in `purgetss/images/` but are not referenced anywhere are ignored by the pipeline (the standalone `purgetss images` command still processes them).
+
+## What gets detected
+
+**XML views:** any node attribute ending in `.svg` is captured along with its `class=""` attribute:
+
+```xml
+<ImageView class="w-32 h-auto" image="/images/logos/logo.svg" />
+<ImageView class="w-(300) bg-red-500" image="/images/banners/hero.svg" />
+<View backgroundImage="/images/textures/grain.svg" class="wh-screen" />
+```
+
+Both `image` and `backgroundImage` (and any other attribute whose value ends in `.svg`) are picked up.
+
+**Controllers:** objects passed to `$.UI.create(...)` (or similar) that mix `image: '...svg'` and `classes: '...'` are captured by an AST walker:
+
+```javascript
+$.UI.create('ImageView', {
+  image: '/images/logos/logo.svg',
+  classes: 'w-(300) bg-red-500'
+})
+```
+
+### Static-scanner limitation
+
+The scanner sees **literal string values only**, not computed paths. Dynamically composed paths are not detected:
+
+```javascript
+// NOT detected — path is concatenated at runtime
+image: '/images/' + variant + '.svg'
+```
+
+For dynamic references, pin the dimensions manually under `images.files` (see [Manual pinning](#manual-pinning-for-undetected-references)) so the pipeline still generates the PNGs.
+
+## How dimensions get resolved
+
+For each SVG reference, the cascade of classes is applied against `app.tss` in declaration order (later-wins, matching Alloy semantics). The pipeline pulls the final `width` and `height` numbers:
+
+| Class on the view              | What `app.tss` resolves            | What the pipeline pins                                          |
+| ------------------------------ | ---------------------------------- | -------------------------------------------------------------- |
+| `class="w-32"`                 | `width: 128`                       | `widthDp = 128`                                                |
+| `class="w-40 h-12"`            | `width: 160`, `height: 48`         | `widthDp = 160`, `heightDp = 48`                               |
+| `class="w-(300)"`              | `width: 300` (arbitrary value)     | `widthDp = 300`                                                |
+| `class="h-44"` (no `w-*`)      | `height: 176`                      | `heightDp = 176`; width derived from viewBox at generation time |
+| `class="w-32 h-auto"`          | `width: 128`, `height: Ti.UI.SIZE` | `widthDp = 128`; height derived from viewBox                   |
+| `class="w-full"` (non-numeric) | `width: Ti.UI.FILL`                | skipped with a warning; no usable dim                          |
+
+Note the spacing convention: PurgeTSS multiplies the Tailwind-style numeric scale, so `w-32` resolves to `width: 128` (128 dp), not 32.
+
+### Auto-derived dimensions stay out of config
+
+If you used `h-auto` (or no `h-*`), the height field does **not** appear in the `images.files` entry. The generator re-derives it from the SVG's `viewBox` on every run. The same applies to width when only `h-*` is pinned. This keeps stale values out of `config.cjs` — the unpinned side stays `null` and is always recomputed from the current viewBox.
+
+## Multiple references to the same SVG
+
+If two views reference the same SVG with different classes, the pipeline takes the **max of each dimension across all references**. The generated PNGs are then sharp enough for the largest use:
+
+```xml
+<!-- view A -->
+<ImageView class="w-32" image="/images/logos/logo.svg" />
+<!-- view B -->
+<ImageView class="w-(800)" image="/images/logos/logo.svg" />
+```
+
+Resolved: `widthDp = 800`. The generated PNGs cover both views; the smaller one just downsamples at runtime.
+
+## How `config.cjs` is synced (autoSync ON)
+
+After resolving dimensions, the pipeline upserts an entry in `images.files`:
+
+```javascript title="./purgetss/config.cjs"
+images: {
+  autoSync: true,
+  files: [
+    { filename: 'images/logos/logo.svg', width: 176 }
+  ]
+}
+```
+
+### The current run wins (v7.11.1 cascade policy)
+
+Policy in plain terms: **the current run's cascade wins.** If you change `w-32` to `w-40`, the entry updates to `width: 160`. If you bump back to `w-32`, it updates back to `128`. On every run, the entry mirrors what the views ask for.
+
+This is **not** a high-water mark. The old (pre-7.11.1) policy used `max(existing, derived)`, which froze sizes when you shrank a class — for example `h-52` → `h-16` kept the 208 dp height cemented in config. The 7.11.1 policy follows the cascade, so shrinks propagate correctly. Manual pinning is still available via `autoSync: false`.
+
+### Symmetric width/height cascade (v7.11.1)
+
+`deriveDimensions` accepts width-only, height-only, or both. The unpinned side stays `null` in `images.files`, and `gen-scales` derives it from the SVG viewBox on every run — no more stale auto-derived heights cemented in config. For a height-only source, `gen-scales` computes the width from the inverse aspect ratio.
+
+### No gratuitous rewrites (v7.11.1)
+
+If a run is byte-identical to the previous one (no inserts, no updates — `inserted === 0 && updated === 0`), `config.cjs` is **not** rewritten. Its `mtime` does not change, so downstream `utilities.tss` rebuilds are not triggered for nothing.
+
+### Manual mode: `autoSync: false`
+
+```javascript title="./purgetss/config.cjs"
+images: {
+  autoSync: false,
+  files: [
+    { filename: 'images/logos/logo.svg', width: 1024 }
+  ]
+}
+```
+
+With `autoSync: false`:
+
+- The pipeline still derives dimensions and generates PNGs, using the values you wrote in `images.files` — or the cascade fallback for files not listed.
+- `config.cjs` is **never** written. Those entries are yours to maintain.
+
+Use this when you want to pin sizes by hand and not have PurgeTSS overwrite your work.
+
+## Force-PNG output
+
+The SVG pipeline **always emits `.png`**, regardless of `images.format`. This is deliberate:
+
+1. Titanium's `image="/foo.svg"` fallback resolves to `.png` only. `.webp`, `.jpeg`, and `.avif` are not picked up through the `.svg` reference.
+2. Having a sibling `.webp` (or any non-`.png`) next to `.png` on disk for the same basename **breaks the fallback entirely**. Titanium then shows nothing.
+
+So even if you set `format: 'webp'` (which is honored by `purgetss images` for raster sources and unlisted SVGs), the post-purge pipeline emits `.png` for every SVG it processes. The `--debug` output line reads `png (forced; ignores format: webp)`.
+
+If you genuinely want a `.webp` of an SVG, reference it as `image="/.../foo.webp"` in your XML, not as `.svg`. The standalone `purgetss images` command will then generate `.webp` for that file. See the [WebP and SVG warning](./multi-density-images.md) in the multi-density reference.
+
+## The PNG cache
+
+PurgeTSS keeps a cache at `purgetss/.cache/svg-images.json`:
+
+```json
+{
+  "logos/logo.svg": {
+    "svgHash": "<sha1>",
+    "widthDp": 176,
+    "heightDp": null,
+    "targets": [
+      "app/assets/android/images/res-mdpi/logos/logo.png",
+      "app/assets/iphone/images/logos/logo@2x.png",
+      "..."
+    ]
+  }
+}
+```
+
+A cached entry is reused, and Sharp is **not** invoked, when all of these hold:
+
+- The SVG's bytes haven't changed (SHA-1 match).
+- `widthDp` resolved is the same as cached.
+- `heightDp` resolved is the same as cached.
+- Every target PNG path matches and exists on disk.
+
+Otherwise, PurgeTSS regenerates the image. If you `git clean`, delete a PNG by hand, or change a class in XML/JS, the next run regenerates only the affected SVGs. Unaffected entries stay cached.
+
+> **Add `purgetss/.cache/` to `.gitignore`.** It is a per-machine artifact.
+
+## Manual pinning for undetected references
+
+When the static scanner cannot see a reference (dynamic/concatenated paths) or a view has no resolvable `w-*` / `h-*` class, pin the entry by hand so the pipeline still generates the PNGs:
+
+```javascript title="./purgetss/config.cjs"
+images: {
+  files: [
+    { filename: 'images/<sub>/<name>.svg', width: 256 }
+  ]
+}
+```
+
+## Standalone command vs post-purge pipeline
+
+| Aspect                  | `purgetss` (post-purge SVG pipeline) | `purgetss images` (standalone)                    |
+| ----------------------- | ------------------------------------ | ------------------------------------------------- |
+| What it processes       | Only SVGs referenced from XML/JS     | All files under `purgetss/images/`                |
+| Source of dimensions    | Class cascade in `app.tss`           | CLI `--width` > `images.files` > viewBox / source |
+| Touches `images.files`? | Yes (autoSync ON)                    | No; only reads it as overrides                    |
+| Output format for SVGs  | Always PNG                           | PNG for SVGs in `files`; `format` otherwise       |
+| When to run             | Automatic on every `purgetss`        | Manual, after raster source edits                 |
+
+Both share the same `images.files` array and the same generation engine (`gen-scales`). They do not fight each other: the pipeline edits `images.files`; the standalone command reads it as overrides. Run either, or both.
+
+## Troubleshooting
+
+### "no class resolved width or height to a number; skipping"
+
+The SVG is referenced from a view with no resolvable `w-*` or `h-*` class (just `w-full`, `w-screen`, `bg-*`, etc.). Add a numeric `w-*` or `h-*` utility, or pin the size manually in `images.files`:
+
+```javascript
+files: [
+  { filename: 'images/<sub>/<name>.svg', width: 256 }
+]
+```
+
+### My change to a class didn't update the PNG
+
+Check that the class actually exists in `app.tss` after purging. The Tailwind-style spacing scale skips numbers like `h-50`; only `h-48`, `h-52`, `h-56` are emitted by default. Add custom values under `theme.extend.spacing` if you need them, or use arbitrary values: `h-(50)`, `h-(200px)`, `h-(12.5rem)`.
+
+If the class is correct but the image didn't refresh on device, it might be the Titanium simulator's image cache. Do a clean build.
+
+### The pipeline didn't detect my SVG reference
+
+The static scanner sees literal string values, not computed paths. Concatenated strings (`'/images/' + variant + '.svg'`) are not detected. Pin the entry in `images.files` manually so the pipeline still generates the PNGs.
+
+### `<ImageView image="/.../foo.svg" />` shows nothing
+
+Two common causes:
+
+1. There is no `.png` next to the `.svg`. Titanium falls back from `.svg` references to `.png` siblings; if the pipeline hasn't generated them yet, the fallback can't fire. Run `purgetss` (or `purgetss images`) and verify the `.png` exists under `app/assets/iphone/images/` and `app/assets/android/images/res-*/`.
+2. Both `.png` and `.webp` (or another non-png) sit next to each other for the same basename. That breaks the fallback entirely. Delete the non-`.png` siblings, or let the force-PNG pipeline own the SVG.
+
+### I want to opt out for a specific run
+
+Switch `autoSync: false` and manage the `images.files` entries yourself, or delete the SVG cache entry. The pipeline still derives dimensions and generates the PNGs so views keep working, but it does not write to `config.cjs`.
+
+## See also
+
+- [Multi-density images](./multi-density-images.md) — the standalone `purgetss images` command, `--width`, format conversion, and `images.files` overrides.
+- [PurgeTSS Configuration Deep Dive](./customization-deep-dive.md) — the `images:` config block and the config syntax validator.

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

@@ -316,7 +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.
 
-**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.)
+**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: the official tikit docs.)
 
 **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.
 
@@ -512,4 +512,4 @@ You can mix and match icons from different libraries throughout your app.
 
 ## License
 
-TiKit UI Components is open source under the MIT License (Copyright 2023-2025 Cesar Estrada).
+TiKit UI Components is open source under the MIT License (Copyright (c) 2023-2025 César Estrada).

package/skills/purgetss/references/titanium-resets.md

@@ -30,7 +30,7 @@ The most important reset is for the `View` element. By default, `View` is set to
 - Grow to accommodate explicit dimensions (`w-64`, `h-32`, etc.)
 - Expand to fill margins (`m-4`, `mx-2`, `mt-6 mb-4`, etc.)
 
-> **See also**: the "Explicit SIZE vs native undefined" callout under [Community-Discovered Patterns](#community-discovered-patterns) explains when to use `h-auto`, `w-auto`, and `wh-auto` to prevent unwanted stretching.
+> **See also**: [Width/Height Inheritance](#widthheight-inheritance) explains when to use `h-auto`, `w-auto`, and `wh-auto` to prevent unwanted stretching.
 
 ### Practical Examples
 
@@ -264,7 +264,7 @@ This generates classes for ALL color properties:
 When PurgeTSS generates your `app.tss`, these resets appear first:
 
 ```tss
-/* PurgeTSS v7.6.0 */
+/* PurgeTSS v7.11.1 */
 /* Created by César Estrada */
 /* https://purgetss.com */
 

package/skills/purgetss/references/ui-ux-design.md

@@ -75,7 +75,8 @@ The catalog below collects real-world UI patterns verified against Titanium's co
 ```xml
 <View class="horizontal border-b border-gray-200 bg-white">
   <View class="ml-4 my-4 rounded-full-12 bg-blue-500">
-    <Label class="center text-lg font-bold text-white" text="JD" />
+    <!-- A child with no top/left centers itself in a composite parent -->
+    <Label class="text-lg font-bold text-white" text="JD" />
   </View>
 
   <View class="vertical ml-3 my-4">
@@ -93,7 +94,7 @@ The catalog below collects real-world UI patterns verified against Titanium's co
     <ItemTemplate name="cardTemplate" class="h-20">
       <View bindId="container" class="horizontal mx-4 my-2 rounded-lg bg-white shadow-lg">
         <View bindId="iconWrap" class="ml-4 my-4 rounded-full-10 bg-blue-100">
-          <Label bindId="icon" class="center fas fa-home text-blue-500" />
+          <Label bindId="icon" class="fas fa-home text-blue-500" />
         </View>
 
         <View class="vertical ml-3 my-4">
@@ -190,8 +191,9 @@ For an icon-with-text pair, use a horizontal `View` containing an icon `Label` a
 
 ```xml
 <View class="h-14 w-screen bg-white border-b border-gray-200">
-  <Label class="left-4 center text-lg font-bold text-gray-800" text="Dashboard" />
-  <Label class="right-4 center fas fa-bars text-gray-700" />
+  <!-- Omitting top/bottom lets each child center vertically in the composite bar -->
+  <Label class="left-4 text-lg font-bold text-gray-800" text="Dashboard" />
+  <Label class="right-4 fas fa-bars text-gray-700" />
 </View>
 ```
 
@@ -267,7 +269,7 @@ For an icon-with-text pair, use a horizontal `View` containing an icon `Label` a
 <Window class="bg-gray-100">
   <View class="vertical h-screen w-screen">
     <View class="h-14 w-screen border-b border-gray-200 bg-white">
-      <Label class="left-4 center text-xl font-bold text-gray-800" text="Screen Title" />
+      <Label class="left-4 text-xl font-bold text-gray-800" text="Screen Title" />
     </View>
 
     <ScrollView class="vertical content-w-screen content-h-auto">

package/skills/purgetss/references/version-history.md

@@ -1,82 +1,71 @@
-# PurgeTSS — Version History
-
-Release-by-release feature additions and behavior changes. The current behavior of PurgeTSS is documented in the main `SKILL.md` and its reference files; this page is the historical record.
-
-## What's New in v7.10.2
-
-- **Pre-7.7.0 brand config auto-migration.** Configs written before v7.7.0 (the `brand:` regroup) now auto-migrate in memory on every run. The legacy flat layout (`brand.padding: <number>`, `brand.iosPadding`, `brand.bgColor`, `brand.darkBgColor`, top-level `brand.notification` / `brand.splash`) used to crash auto-purge with `TypeError: Cannot create property 'ios' on number '15'`. `getConfigFile()` now normalizes legacy keys to the grouped layout (`brand.padding.{ios, androidLegacy, androidAdaptive}`, `brand.android.*`, `brand.ios.darkBackground`, `brand.colors.background`) before applying defaults. When both legacy and new keys coexist, the new key wins. A one-time deprecation notice per session lists the migrated keys. See [App Icons & Branding → Upgrading from pre-7.7.0 configs](app-branding.md).
-- **Internal logger fix.** `logger.warning` and `logger.success` are now defined. Across `brand`, `images`, `cleanup-legacy`, and `svg-utils`, ~30 callsites of `logger.warning` and ~10 of `logger.success` referenced methods that did not exist on the logger object — any opt-in command path that hit one used to throw `TypeError: logger.warning is not a function`. The auto-purge entry point most users hit did not reach those callsites, so the bug stayed latent until commands like `purgetss brand` or `purgetss images` were run.
-
-## What's New in v7.10.1
-
-- **"Tailwind" framing dropped from copy that did not document a functional integration.** The Class Syntax Error block now reports `'Square brackets "[ ]" are not supported'` instead of `'Tailwind-style brackets "[ ]" are not supported'`. The promotional `<Label>` injected into new projects by `purgetss create` changed from `"Tailwind-inspired utility classes for Titanium/Alloy"` to `"Utility-first styling for Titanium/Alloy"`.
-- **Functional integrations stay.** The `tailwindcss@3` dependency installed by `install-dependencies` (drives both the `defaultColors` / `defaultTheme` palette base AND the VSCode IntelliSense extension) still ships. The `--tailwind` flag on `purgetss shades` and the recommended `Tailwind CSS IntelliSense` / `Tailwind Raw Reorder (v4)` VSCode extensions are unchanged.
-
-## What's New in v7.10.0
-
-- **`purgetss images` got three CLI-only flags.**
-  - `--opacity <n>` (integer `0-100`) multiplies the alpha channel of every generated density by `n/100` — useful for placeholder or default ImageView images that render at reduced opacity (loading states, watermarks). With `--format jpeg`, the JPEG flatten-on-white step composites the semi-transparent image onto white instead of producing transparent JPEGs (JPEG has no alpha).
-  - `--padding <n>` (integer `0-40`) shrinks the rendered image inside each density canvas by symmetric percentage borders, preserving canvas size with transparent fill — useful for breathing room around an unpadded logo.
-  - `--output <relpath>` overrides the basename and subpath relative to each platform's `images/` root, so a logo from `purgetss/brand/` can be written as `images/logos/loading.png` across all densities in a single command.
-  - The three flags combine naturally for "transparent placeholder with padding under a custom path". See [Multi-Density Images](multi-density-images.md).
-- **`purgetss brand` now generates `MarketplaceArtworkFeature.png` (1024×500 Google Play Feature Graphic)** alongside the existing iTunesConnect and MarketplaceArtwork submission assets. Auto-discovers `purgetss/brand/logo-feature.{svg,png}` or reuses the master logo if not provided. Default vertical padding is `12%`; override with `--feature-graphic-padding <n>` (range `0-40`), config `brand.padding.featureGraphic`, or CLI `--feature-logo <path>` for a dedicated source. Submission artwork only — written to project root for upload to the Play Console, not bundled into the APK. See [App Icons & Branding](app-branding.md).
-- **Arbitrary nesting depth in `config.cjs` `theme` objects.** Property emission now walks nested values recursively instead of stopping at level 2, so `theme.extend.colors.brand.primary.500` flattens to `brand-primary-500` instead of being silently dropped. Same for `backgroundGradient` and `backgroundSelectedGradient`. Default modifier keys (`default`, `global`, `DEFAULT`) collapse without contributing to the suffix. See [Arbitrary Values](arbitrary-values.md).
-- **Fix:** `apply:` now resolves built-in icon font classes (`fas`, `fab`, `fa-*`, `mi-*`, `ms-*`, `f7-*`) from `dist/` for projects that don't run `build-fonts`. Previously those classes were silently dropped from generated rules — `apply: 'fas fa-times-circle wh-12 ...'` produced everything except the FontAwesome family and the icon glyph. See [Apply Directive → Use icon font classes](apply-directive.md).
-- **Fix:** `borderRadius: [...]` arrays no longer get truncated when combined with other utilities in an `apply:` string. The post-merge dedup step (from v7.9.0) tracked depth on `{}` only, so `borderRadius: [0, 0, 0, 16]` (emitted by directional `rounded-{t,b,l,r,tl,tr,bl,br}-*` utilities) was split on its internal commas. The depth tracker now respects `[]` alongside `{}`.
-- **Fix:** `brand --padding <n>` shortcut now applies to BOTH Android paddings as the help text always promised. Previously the shortcut only fed `androidAdaptivePadding` while `androidLegacyPadding` fell through to its own config value, so `purgetss brand --padding 17` actually produced `androidAdaptive=17, androidLegacy=10`.
-
-## What's New in v7.9.0
-
-- Opacity modifier on semantic colors — `bg-surface/65` syntax now works for any class mapped through `theme.extend.colors`. PurgeTSS auto-derives `<originalKey>_<alphaPercent>` entries in `semantic.colors.json` per mode (light/dark). See [Semantic Colors → Opacity modifier auto-derivation](semantic-colors.md#opacity-modifier-auto-derivation). **Native rebuild required** — Liveview hot-reload alone does not refresh `semantic.colors.json`
-- `theme.Window` / `theme.View` / `theme.ImageView` presets now use **replace mode** — they no longer carry framework defaults (white background, `Ti.UI.SIZE`, iOS `hires: true`). This fixes gradient ghosting where a preset Window with `bg-gradient-*` apply was being covered by the implicit `backgroundColor: '#FFFFFF'`. Use `theme.extend.Window` / `theme.extend.View` / `theme.extend.ImageView` when you want **extend mode** (merge with defaults). See [Apply Directive → Extend mode vs replace mode](apply-directive.md#extend-mode-vs-replace-mode)
-- Glossary path renamed: `purgetss/experimental/tailwind-classes/` → `purgetss/glossary/tailwind-classes/`
-
-## What's New in v7.8.0
-
-- `purgetss images --width <n>` — pin SVG output to a specific base width; PurgeTSS derives per-density assets from the multiplier scale (×1 / ×1.5 / ×2 / ×3 / ×4). Range `[1, 8192]`. CLI-only (no `images:` config equivalent — width is per-asset). See [Multi-Density Images → Pinning the output width with --width](multi-density-images.md#pinning-the-output-width-with---width)
-- Class syntax pre-validation — the build now emits a `Class Syntax Error` block (file path + line + `Fix:` suggestion) for 5 detected patterns: inverted negative sign (`top-(-10)` → `-top-(10)`), Tailwind brackets (`top-[10px]` → `top-(10px)`), empty parens (`wh-()`), whitespace inside parens (`wh-( 200 )` → `wh-(200)`), redundant `px` unit (`top-(10px)` → `top-(10)`). See [Arbitrary Values → Class syntax pre-validation](arbitrary-values.md#class-syntax-pre-validation)
-- Parser fix for negative values inside parentheses — `top-(-10)` is now correctly flagged as inverted-negative-sign instead of silently misparsed
-
-## What's New in v7.7.0
-
-- `brand:` config restructured — flat keys replaced by purpose-based groups: `brand.logos`, `brand.padding`, `brand.android`, `brand.ios`, `brand.colors`
-- Separate Android brand inputs — `logos.androidLauncher` / `--icon-logo` for Android launcher icons; `logos.androidSplash` / `--splash-logo` for Android 12+ splash artwork. Drop `logo-icon.*` and `logo-splash.*` into `purgetss/brand/`
-- `--android-adaptive-padding` (default `19%`) and `--android-legacy-padding` (default `10%`) replace the single `--padding`. The shortcut `--padding` now sets both Android paddings to the same value for one run
-- Legacy Android splash fallback regenerated — `app/assets/android/default.png` (Alloy) or `Resources/android/default.png` (Classic). `cleanup-legacy` no longer removes `default.png`
-- New official doc: [Values and Units](values-and-units.md) — explains `ti.ui.defaultunit` interpretation of PurgeTSS unitless values
-
-## What's New in v7.6.x
-
-- `brand` command — complete Titanium branding set (launcher icons, adaptive, iOS 18+ Dark/Tinted, marketplace) from logos in `./purgetss/brand/` (v7.6.0)
-- `images` command — multi-density UI images (Android res-*dpi + iPhone @1x/@2x/@3x) from `./purgetss/images/` (v7.6.0)
-- `semantic` command — Titanium semantic colors for Light/Dark mode (palette mode + single mode) (v7.6.0)
-- `brand:` and `images:` config sections auto-injected into older configs (v7.6.0)
-- Percentages as strings (`'15%'`) for self-documenting clarity in brand/images configs (v7.6.0)
-- Confirmation prompt for destructive writes in `brand` / `images` (`y` / `N` / `a`); auto-skipped on non-TTY, with `-y`, or `PURGETSS_YES=1` (v7.6.1)
-- `semantic` command works in Classic projects — writes to `Resources/semantic.colors.json` (v7.6.2)
-
-## What's New in v7.5.3
-
-- Appearance module — Light/Dark/System mode switching with persistence
-- Default font family classes (`font-sans`, `font-serif`, `font-mono`) generated automatically with platform-appropriate values
-- XML validation — detects illegal `--` inside XML comments during pre-validation
-
-## What's New in v7.5.0
-
-- `extend` support for Window, View, and ImageView in `config.cjs`
-- Shorthand `apply` directive normalization
-- Apply directive property deduplication
-- Automatic platform resolution in apply directives
-- Updated Font Awesome to 7.2.0
-- Fixed: `extend.Window` was silently ignored
-- Fixed: Array-type properties (`extendEdges`, `mediaTypes`) bracket notation
-
-## What's New in v7.4.0
-
-- 9 new Animation methods: `transition`, `pulse`, `sequence`, `swap`, `shake`, `snapTo`, `reorder`, `undraggable`, `detectCollisions` (module now has 15 methods total)
-- Snap behavior classes: `snap-back`, `snap-center`, `snap-magnet`
-- `keep-z-index` utility class
-- Enriched callback event object with `action`, `state`, `id`, `targetId`, `index`, `total`, `getTarget()`
-- Delta-based drag for views with rotate/scale transforms
-- Position normalization for draggable views
-- Property inheritance from Animation object for all new methods
+# PurgeTSS — Version History (agent summary)
+
+Terse, agent-facing summary of changes that affect how the skill suggests utilities, configures `config.cjs`, or invokes commands. **Not** a full changelog.
+
+**Canonical source:** <https://purgetss.com/changelog> (full release notes, internal fixes, parser changes, dependency bumps).
+
+When in doubt about whether a class, flag, or config key exists in the user's installed version, consult the canonical changelog or grep `./purgetss/styles/utilities.tss` in the project.
+
+---
+
+## v7.11.1
+- Symmetric width/height cascade in the SVG image pipeline: 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 (no stale auto-derived dimensions frozen in 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`. Pin manually with `images.autoSync: false`.
+- Fix: `purgetss images` respects `--yes` for overwrite confirmations (prompt no longer reappears).
+- Fix: SVGs listed in `images.files` always emit `.png` regardless of `images.format` (Titanium's `.svg → .png`-only runtime fallback). Raster files and SVGs not in `images.files` still honor `format`.
+
+## v7.11.0
+- SVG-aware compile-time image pipeline runs as a `purgetss` post-step. When XML/controllers reference `image="/images/x.svg"` (or `backgroundImage`) alongside utility classes that resolve to numeric width/height (`w-32`, `w-(300)`, `h-auto`), purge compiles the SVG into the 8 Titanium density PNGs (5 Android + 3 iPhone) using dimensions resolved from `app.tss`. Titanium loads the generated `.png` at runtime; the `.svg` attribute in your source is never rewritten. Cache: `purgetss/.cache/svg-images.json` (add to `.gitignore`). See [multi-density-images.md](multi-density-images.md).
+- `images.files` array in `config.cjs` — per-file width/height override: `[{ filename: 'images/logos/logo.png', width: 128, height: 52 }]`. CLI `--width` still wins over entries. SVGs detected by the pipeline populate entries automatically (subject to `images.autoSync`); hand-added raster entries survive untouched.
+- `images.autoSync` boolean (default `true`) — opt-out for devs managing `images.files` by hand. When `false`, purge still computes dimensions and generates PNGs but never writes back to `config.cjs`.
+- `config.cjs` syntax validator emits a formatted `Config Syntax Error` block (file, JSON path, context, issue, fix snippet) for type mismatches in known fields, currently `theme.fontFamily.*` — must be a **string** — replacing cryptic crashes like `rule.startsWith is not a function`.
+
+## v7.10.2
+- Pre-v7.7.0 `brand:` configs (flat layout: `brand.padding: <number>`, `brand.iosPadding`, `brand.bgColor`, top-level `brand.notification`/`brand.splash`) auto-migrate to the grouped layout in memory. A one-time per-session notice lists the migrated keys.
+
+## v7.10.1
+- "Tailwind" framing dropped from non-functional copy (Class Syntax Error message, `purgetss create` injected Label). Functional integrations (`tailwindcss@3` dep, `shades --tailwind`, VSCode IntelliSense extension) still ship.
+
+## v7.10.0
+- `purgetss images` gains `--opacity <0-100>`, `--padding <0-40>`, `--output <relpath>`. CLI-only (no `config.cjs` equivalent). See [multi-density-images.md](multi-density-images.md).
+- `purgetss brand` generates `MarketplaceArtworkFeature.png` (1024×500 Google Play Feature Graphic). Override via `--feature-logo <path>` or `--feature-graphic-padding <n>` (default 12%). See [app-branding.md](app-branding.md).
+- `theme` objects in `config.cjs` walk recursively at any depth — `theme.extend.colors.brand.primary.500` flattens to class `bg-brand-primary-500`. Default modifier keys (`default`, `global`, `DEFAULT`) collapse. Same for `backgroundGradient` / `backgroundSelectedGradient`. See [arbitrary-values.md](arbitrary-values.md).
+- Fix: `apply:` now resolves built-in icon font classes (`fas`, `fab`, `fa-*`, `mi-*`, `ms-*`, `f7-*`) from `dist/` even without `build-fonts`.
+- Fix: `brand --padding <n>` shortcut applies to BOTH Android paddings.
+
+## v7.9.0
+- Opacity modifiers work on semantic colors: `bg-surface/65` auto-derives `surface_65` in `semantic.colors.json` with light/dark + alpha. **Native rebuild required** (Liveview alone does not refresh `semantic.colors.json`). See [semantic-colors.md](semantic-colors.md).
+- `theme.Window` / `theme.View` / `theme.ImageView` at top level = **replace mode** (no framework defaults). Use `theme.extend.Window` for **extend mode** (merge with defaults). See [apply-directive.md](apply-directive.md).
+- **Breaking:** glossary path renamed `purgetss/experimental/tailwind-classes/` → `purgetss/glossary/tailwind-classes/`. No transition shim.
+
+## v7.8.0
+- `purgetss images --width <n>` pins Android `mdpi` / iPhone `@1x` to `<n>` pixels for SVG sources with disproportionate viewBoxes (Affinity, Illustrator). CLI-only.
+- Class syntax pre-validation emits `Class Syntax Error` blocks for 5 patterns: inverted negative (`top-(-10)` → `-top-(10)`), brackets (`top-[10px]` → `top-(10px)`), empty parens (`wh-()`), whitespace in parens, redundant `px` unit. Generic unknown classes still flow into `// Unused or unsupported classes`.
+
+## v7.7.0
+- `brand:` config restructured into grouped sections: `brand.logos`, `brand.padding`, `brand.android`, `brand.ios`, `brand.colors`. Old projects keep working; new configs use grouped form. See [app-branding.md](app-branding.md).
+- Separate Android brand inputs: `logos.androidLauncher` / `--icon-logo` and `logos.androidSplash` / `--splash-logo`.
+- Android splash fallback `default.png` regenerated (Alloy: `app/assets/android/`, Classic: `Resources/android/`). `cleanup-legacy` preserves it.
+- New ref: [values-and-units.md](values-and-units.md) — `ti.ui.defaultunit` interpretation of unitless PurgeTSS values.
+
+## v7.6.x
+- `purgetss brand` (v7.6.0) — full Titanium branding set from `purgetss/brand/` logos. See [app-branding.md](app-branding.md).
+- `purgetss images` (v7.6.0) — multi-density UI images (Android `res-*` + iPhone `@1x`/`@2x`/`@3x`). See [multi-density-images.md](multi-density-images.md).
+- `purgetss semantic` (v7.6.0) — Titanium semantic colors for Light/Dark, palette mode or `--single` purpose-based. Classic projects supported since v7.6.2. See [semantic-colors.md](semantic-colors.md).
+- `brand:` and `images:` config sections auto-injected. Percentages may be quoted strings (`'15%'`) or plain numbers.
+- `brand` / `images` ask `[y/N/a]` before overwriting (skip with `-y`, `PURGETSS_YES=1`, or non-TTY) (v7.6.1).
+
+## v7.5.3
+- `Appearance` module — Light/Dark/System mode switching with persistence (`init()`, `set()`, `get()`, `toggle()`). See [appearance-module.md](appearance-module.md).
+- Default font family classes (`font-sans`, `font-serif`, `font-mono`) auto-generated with platform-appropriate values.
+
+## v7.5.0
+- `theme.extend.Window` / `theme.extend.View` / `theme.extend.ImageView` — customize Ti element defaults.
+- Shorthand `apply:` directive — `{ apply: '...' }` auto-normalizes; `default:` wrapper optional.
+- Apply directive property deduplication — applied values win over static defaults.
+- Automatic platform resolution inside `ios:` / `android:` blocks.
+
+## v7.4.0
+- Animation module: 9 new methods (`transition`, `pulse`, `sequence`, `swap`, `shake`, `snapTo`, `reorder`, `undraggable`, `detectCollisions`). 15 methods total. See [animation-system.md](animation-system.md).
+- New utility classes: `snap-back`, `snap-center`, `snap-magnet`, `keep-z-index`.
+- Delta-based drag for transformed views; property inheritance from Animation object.