@maccesar/titools 3.3.0 → 4.0.0

package/skills/purgetss/references/cli-commands.md

@@ -116,6 +116,7 @@ The `create` command generates a new Alloy project with PurgeTSS already set up.
 
 - `-f, --force` to overwrite an existing project.
 - `-d, --dependencies` to install ESLint and Tailwind CSS.
+- `-m, --module` to install the `purgetss.ui.js` module in the project's `./app/lib/` folder.
 - `-v, --vendor [fa,mi,ms,f7]` to copy the selected fonts into your project and add the CommonJS module in `./app/lib/`. See the `icon-library` command for available fonts.
 
 If a project with the same name already exists, the command will prompt you to confirm whether you want to overwrite it.
@@ -559,6 +560,7 @@ purgetss s [hexcode] [name]
 - `-n, --name`: Specifies the name of the color.
 - `-q, --quotes`: Retains double quotes in the `config.cjs` file.
 - `-r, --random`: Generates shades from a random color.
+- `-o, --override`: Places the new shades in `theme.colors` (instead of `theme.extend.colors`) to override default colors.
 - `-s, --single`: Generates a single color definition.
 - `-t, --tailwind`: Logs the generated shades with a `tailwind.config.js` compatible structure.
 - `-l, --log`: Logs the generated shades instead of saving them.
@@ -685,6 +687,10 @@ purgetss b
 
 When `purgetss` runs (manually or via `watch`), it checks for changes in `config.cjs` and regenerates `utilities.tss` when needed.
 
+### Options
+
+- `--glossary`: Creates a glossary folder with all generated classes.
+
 ## `watch` Command
 
 The `watch` command runs PurgeTSS on each project compile. You do not need to run `build` manually after each change.
@@ -718,6 +724,15 @@ purgetss watch --off
 purgetss w -o
 ```
 
+To completely remove the Auto-Purging hook from `alloy.jmk`, use `-d, --delete`.
+
+```bash
+purgetss watch --delete
+
+# alias:
+purgetss w -d
+```
+
 ## `module` Command
 
 The `module` command installs `purgetss.ui.js` in the `lib` folder.

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

@@ -54,6 +54,9 @@ What it does:
 1. Creates `./purgetss/styles/fonts.tss` with one `fontFamily` class per file.
 2. Copies the font files into `./app/assets/fonts/`, renamed to their PostScript names so they work on both iOS and Android.
 
+> ℹ️ **INFO — How this differs from the official icon fonts**
+> Unlike the [official icon fonts](./icon-fonts.md), which PurgeTSS resolves automatically from its own bundled files and need no `.tss` in your project, custom fonts **do** generate `./purgetss/styles/fonts.tss`. That file is then folded into the generated `app/styles/app.tss` when you run `purgetss` (or compile your app) — that is where the final classes used by Alloy live.
+
 After running `purgetss build-fonts` with the Bevan and Dancing Script example above:
 
 `./purgetss/styles/fonts.tss`
@@ -133,19 +136,19 @@ After `purgetss build-fonts`, the generated `fonts.tss` includes the family clas
 /* To use your Icon Fonts in Buttons AND Labels each class sets 'text' and 'title' properties */
 
 /* map-icons/map-icons.css */
-'.map-icon-abseiling': { text: '', title: '' }
-'.map-icon-accounting': { text: '', title: '' }
-'.map-icon-airport': { text: '', title: '' }
-'.map-icon-amusement-park': { text: '', title: '' }
-'.map-icon-aquarium': { text: '', title: '' }
+'.map-icon-abseiling': { text: '\ue800', title: '\ue800' }
+'.map-icon-accounting': { text: '\ue801', title: '\ue801' }
+'.map-icon-airport': { text: '\ue802', title: '\ue802' }
+'.map-icon-amusement-park': { text: '\ue803', title: '\ue803' }
+'.map-icon-aquarium': { text: '\ue804', title: '\ue804' }
 /* ... */
 
 /* microns/microns.css */
-'.mu-arrow-left': { text: '', title: '' }
-'.mu-arrow-right': { text: '', title: '' }
-'.mu-arrow-up': { text: '', title: '' }
-'.mu-arrow-down': { text: '', title: '' }
-'.mu-left': { text: '', title: '' }
+'.mu-arrow-left': { text: '\ue700', title: '\ue700' }
+'.mu-arrow-right': { text: '\ue701', title: '\ue701' }
+'.mu-arrow-up': { text: '\ue702', title: '\ue702' }
+'.mu-arrow-down': { text: '\ue703', title: '\ue703' }
+'.mu-left': { text: '\ue704', title: '\ue704' }
 /* ... */
 ```
 
@@ -172,18 +175,18 @@ To avoid prefix conflicts between libraries, each icon keeps its prefix as a nes
 const icons = {
   // map-icons/map-icons.css
   'mapIcon': {
-    'abseiling': '',
-    'accounting': '',
-    'airport': '',
-    'amusementPark': '',
+    'abseiling': '\ue800',
+    'accounting': '\ue801',
+    'airport': '\ue802',
+    'amusementPark': '\ue803',
     // ...
   },
   // microns/microns.css
   'mu': {
-    'arrowLeft': '',
-    'arrowRight': '',
-    'arrowUp': '',
-    'arrowDown': '',
+    'arrowLeft': '\ue700',
+    'arrowRight': '\ue701',
+    'arrowUp': '\ue702',
+    'arrowDown': '\ue703',
     // ...
   }
 };
@@ -221,19 +224,19 @@ purgetss
 '.mic': { font: { fontFamily: 'microns' } }
 
 /* map-icons/mp.css */
-'.mp-abseiling': { text: '', title: '' }
-'.mp-accounting': { text: '', title: '' }
-'.mp-airport': { text: '', title: '' }
-'.mp-amusement-park': { text: '', title: '' }
-'.mp-aquarium': { text: '', title: '' }
+'.mp-abseiling': { text: '\ue800', title: '\ue800' }
+'.mp-accounting': { text: '\ue801', title: '\ue801' }
+'.mp-airport': { text: '\ue802', title: '\ue802' }
+'.mp-amusement-park': { text: '\ue803', title: '\ue803' }
+'.mp-aquarium': { text: '\ue804', title: '\ue804' }
 /* ... */
 
 /* microns/mc.css */
-'.mc-arrow-left': { text: '', title: '' }
-'.mc-arrow-right': { text: '', title: '' }
-'.mc-arrow-up': { text: '', title: '' }
-'.mc-arrow-down': { text: '', title: '' }
-'.mc-left': { text: '', title: '' }
+'.mc-arrow-left': { text: '\ue700', title: '\ue700' }
+'.mc-arrow-right': { text: '\ue701', title: '\ue701' }
+'.mc-arrow-up': { text: '\ue702', title: '\ue702' }
+'.mc-arrow-down': { text: '\ue703', title: '\ue703' }
+'.mc-left': { text: '\ue704', title: '\ue704' }
 /* ... */
 ```
 
@@ -242,18 +245,18 @@ purgetss
 const icons = {
   // map-icons/mp.css
   'mp': {
-    'abseiling': '',
-    'accounting': '',
-    'airport': '',
-    'amusementPark': '',
+    'abseiling': '\ue800',
+    'accounting': '\ue801',
+    'airport': '\ue802',
+    'amusementPark': '\ue803',
     // ...
   },
   // microns/mc.css
   'mc': {
-    'arrowLeft': '',
-    'arrowRight': '',
-    'arrowUp': '',
-    'arrowDown': '',
+    'arrowLeft': '\ue700',
+    'arrowRight': '\ue701',
+    'arrowUp': '\ue702',
+    'arrowDown': '\ue703',
     // ...
   }
 };

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

@@ -16,7 +16,7 @@ Whether you want to style a Ti Element (a markup element such as `Label`), a cus
 
 > **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:
+> 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 CommonJS-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.

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

@@ -57,9 +57,11 @@ module.exports = {
     confirmOverwrites: true  // prompt before overwriting files (set false to skip)
   },
   images: {
+    autoSync: true,          // false = SVG pipeline computes dims but doesn't write to images.files (v7.11.0)
     quality: 85,             // JPEG/WebP/AVIF quality (0-100)
     format: null,            // null = keep original; 'webp' | 'jpeg' | 'png' to convert every image
-    confirmOverwrites: true  // prompt before overwriting files (set false to skip)
+    confirmOverwrites: true, // prompt before overwriting files (set false to skip)
+    files: []                // per-file overrides: [{ filename, width, height? }] (v7.11.0)
     // Note: --width (v7.8.0) and --opacity / --padding / --output (v7.10.0) are CLI-only
     //       by design — those decisions are per-asset, not project-wide.
   },
@@ -270,6 +272,37 @@ module.exports = {
 };
 ```
 
+### Config Syntax Validation (v7.11.0)
+
+Since v7.11.0, PurgeTSS validates known fields in `config.cjs` at load time. On a type mismatch it prints a formatted `Config Syntax Error` block — file, JSON path, context, issue, and a fix snippet — instead of crashing downstream with a cryptic message like `rule.startsWith is not a function`.
+
+The validator runs on every config load and covers the case that trips up developers coming from Tailwind: `fontFamily` values must be a **string**, not a Tailwind-style array. It currently validates:
+
+- `theme.fontFamily.*` — expected a string.
+- `theme.extend.fontFamily.*` — expected a string.
+
+```javascript
+// ✗ Tailwind-style array — triggers a Config Syntax Error
+theme: {
+  extend: {
+    fontFamily: {
+      sans: ['Inter', 'sans-serif']
+    }
+  }
+}
+
+// ✓ Single font family per element (Titanium accepts one)
+theme: {
+  extend: {
+    fontFamily: {
+      sans: 'Inter-Regular'
+    }
+  }
+}
+```
+
+The scope is defined by the `FIELD_RULES` array in `src/shared/validation/config-validator.js`; additional fields can be added there. Today only the two `fontFamily` paths are validated.
+
 ## Overriding and Extending Properties
 
 By default, your project inherits values from the default theme. You have two options depending on your goal.
@@ -396,6 +429,36 @@ module.exports = {
 
 The nested keys are combined with the parent key to form class names like `bg-tahiti-400` or `text-tahiti-400`.
 
+### Nesting beyond one level
+
+Since v7.10.0, `theme` and `theme.extend` values are walked recursively, so you can group categories more than one level deep. Each level flattens into a kebab-case suffix on the generated class names:
+
+```javascript
+module.exports = {
+  theme: {
+    extend: {
+      colors: {
+        brand: {
+          primary: {
+            500: '#0ea5e9',
+            900: '#0c4a6e'
+          },
+          accent: '#f97316'
+        }
+      }
+    }
+  }
+};
+```
+
+```tss
+'.bg-brand-primary-500': { backgroundColor: '#0ea5e9' }
+'.bg-brand-primary-900': { backgroundColor: '#0c4a6e' }
+'.bg-brand-accent': { backgroundColor: '#f97316' }
+```
+
+Default modifier keys (`default`, `global`, `DEFAULT`) collapse without contributing to the suffix. The same flattening applies to other property categories that accept nested objects, including `backgroundGradient` and `backgroundSelectedGradient`. One-level configs behave exactly as before.
+
 ### Override a Default Color
 
 If you want to override one of the default colors but keep the rest, provide the new values in `theme.extend.colors`.

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

@@ -55,6 +55,8 @@ $ purgetss il -v=fa,mi,ms,f7
 
 > ℹ️ **INFO — You do not need the `.tss` files in `./purgetss/styles/`**
 > PurgeTSS already knows every official icon class and resolves them at compile time from its own bundled `dist/` files. You do not need `fontawesome.tss`, `materialsymbols.tss`, `materialicons.tss`, or `framework7icons.tss` inside `./purgetss/styles/` for `class="fas fa-home"` (or any other icon class) to work in your XML and controllers. Install the `.ttf` files with `icon-library` and the classes are ready.
+>
+> The resolved classes are written to the generated `app/styles/app.tss`, not to `purgetss/styles/utilities.tss`. If you go looking for a class like `.ms-home`, check `app.tss`.
 
 ### Optional flags
 

package/skills/purgetss/references/migration-guide.md

@@ -1,11 +1,62 @@
 # Migration Guide
 
-This guide mirrors the official PurgeTSS changelog (see the project `README.md` / `docs/index.md`). It walks through the upgrade-relevant changes from v7.2.6 through v7.10.x, flags breaking changes, and links each section to the reference files that cover the new surface area in depth.
+This guide mirrors the official PurgeTSS changelog (see the project `README.md` / `docs/index.md`). It walks through the upgrade-relevant changes from v7.2.6 through v7.11.x, flags breaking changes, and links each section to the reference files that cover the new surface area in depth.
 
 Changelog source of truth: [https://github.com/macCesar/purgeTSS](https://github.com/macCesar/purgeTSS).
 
 ---
 
+## Upgrade to v7.11.x
+
+v7.11.0 and v7.11.1 are additive — **no breaking changes**. The headline addition is a compile-time SVG image pipeline that runs automatically as a post-step of `purgetss`, plus a `config.cjs` syntax validator. Nothing new is required on upgrade; the new surface is opt-in. Full release notes in [`version-history.md`](./version-history.md).
+
+### Added in v7.11.0 — SVG compile-time image pipeline (opt-in)
+
+Reference an `.svg` in a view or controller with `image="/images/<sub>/<name>.svg"` (or `backgroundImage="..."`) **alongside** utility classes that resolve to a numeric width/height (`w-32`, `w-(300)`, `h-auto`, …), and after the regular purge finishes PurgeTSS compiles that SVG into the 8 Titanium density variants (5 Android + 3 iPhone PNGs), sizing them from the dimensions resolved in `app.tss`. Titanium loads the generated `.png` automatically at runtime even though the source still references `.svg` — the SVG attribute is never rewritten.
+
+- Cache lives at `purgetss/.cache/svg-images.json` — **add it to `.gitignore`**.
+- Projects that never reference `.svg` images with sizing classes see no change. This is entirely opt-in by usage.
+
+See [`multi-density-images.md`](./multi-density-images.md).
+
+### Added in v7.11.0 — `images.files` override array
+
+`config.cjs` accepts an `images.files` array to pin width/height for individual files in `purgetss/images/`:
+
+```javascript
+images: {
+  autoSync: true,
+  files: [
+    { filename: 'images/logos/logo.png', width: 128, height: 52 }
+  ]
+}
+```
+
+Entries override a source's natural dimensions when `purgetss images` runs; CLI `--width` still wins over both. SVGs detected by the purge pipeline populate entries automatically (subject to `images.autoSync`). Raster entries you add by hand survive subsequent runs untouched.
+
+### Added in v7.11.0 — `images.autoSync` opt-out
+
+`images.autoSync` (boolean, default `true`). When `false`, purge still computes dimensions and generates the density PNGs, but never writes back to `config.cjs` — for devs who manage `images.files` by hand.
+
+### Added in v7.11.0 — `config.cjs` syntax validator
+
+Type mismatches in known config fields now print a formatted `Config Syntax Error` block (file, JSON path, context, issue, and a fix snippet) instead of a cryptic downstream crash like `rule.startsWith is not a function`. Currently validated: `theme.fontFamily.*` and `theme.extend.fontFamily.*` — **each font-family value must be a string**. The validator runs at config load time.
+
+### Changed in v7.11.1 — symmetric cascade + current-run sync
+
+- **Symmetric width/height cascade** — a class can pin width-only, height-only, or both. The unpinned side stays `null` in `images.files` and is re-derived from the SVG viewBox on every run, so no stale auto-derived dimension gets frozen into config.
+- **`syncConfigImages` mirrors the current run** instead of taking `max()` across past runs. Shrinking a class (e.g. `h-52` → `h-16`) now propagates to `config.cjs` rather than freezing the entry at the larger past size. Pin manually with `images.autoSync: false`.
+- **`purgetss images` respects `--yes`** for overwrite confirmations — the prompt no longer reappears when `--yes` is supplied.
+- **SVGs listed in `images.files` always emit `.png`** regardless of `images.format`, because Titanium's `.svg → .png`-only runtime fallback means other formats wouldn't load. Raster files and SVGs not in `images.files` still honor `format`.
+
+### What to review
+
+- Add `purgetss/.cache/` to `.gitignore` before your next commit if you reference `.svg` images with sizing classes.
+- If your `config.cjs` sets `theme.fontFamily` or `theme.extend.fontFamily` to anything other than a string, fix it now — the validator will halt with a `Config Syntax Error` block.
+- If you manage `images.files` by hand and don't want purge overwriting your sizes, set `images.autoSync: false`.
+
+---
+
 ## Upgrade to v7.10.x
 
 v7.10.0 through v7.10.2 are additive — **no breaking changes**. The notable shift is internal: configs written before v7.7.0 (the `brand:` regroup) now auto-migrate in memory on every run, so projects that never updated to the grouped `brand:` schema keep working without a `TypeError` crash. Full release notes in [`version-history.md`](./version-history.md).
@@ -372,3 +423,4 @@ If you previously worked around this by inlining the gradient directly in TSS, r
 - After v7.8.0: run the build once and address every `Class Syntax Error` it surfaces. Update CI to handle the new hard-fail on malformed class names. Migrate any `top-[10px]` style square brackets to `top-(10px)` parentheses.
 - After v7.9.0: search for any `purgetss/experimental/tailwind-classes/` references in tooling/CI and update to `purgetss/glossary/tailwind-classes/`. If a project used top-level `theme.Window` / `View` / `ImageView` and depended on framework defaults being merged in, decide between moving the config under `theme.extend.*` or adding the previously-implicit utilities to the `apply` string.
 - After v7.10.0: deeply nested color families (`theme.extend.colors.brand.primary.500`) now emit recursively — restructure by domain if it improves readability. `apply:` with bundled icon fonts (`fas`, `mi-*`, `ms-*`, `f7-*`) no longer requires `build-fonts` first. The Google Play Feature Graphic ships automatically with `purgetss brand`.
+- After v7.11.0: reference `.svg` images with numeric `w-*`/`h-*` classes to opt into the compile-time SVG pipeline (add `purgetss/.cache/` to `.gitignore`). Ensure every `theme.fontFamily.*` value is a string, not a Tailwind-style array, or the new config validator hard-fails. Use `images.files` to pin per-file sizes and `images.autoSync: false` to stop the pipeline writing back to `config.cjs`.

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

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