@maccesar/titools 4.17.1 → 4.19.0

package/skills/purgetss/references/app-branding.md

@@ -1,8 +1,8 @@
 # App Icons & Branding
 
-The `purgetss brand` command (introduced in v7.6.0, grouped config in v7.7.0, restructured into per-piece blocks in v7.13.0) regenerates **every image the Titanium template ships**, from one main SVG or PNG logo: launcher icons, adaptive icons, iOS 18+ Dark/Tinted variants, marketplace artwork, and both the iOS and Android splash sets. Per-piece overrides are there when you need them. Alloy and Classic layouts are auto-detected.
+The `purgetss brand` command generates the complete Titanium branding set from one main SVG or PNG logo: launcher icons, adaptive icons, iOS 18+ Dark/Tinted variants, marketplace artwork, and both splash sets. Per-piece overrides are available when needed. Alloy and Classic layouts are auto-detected, and since v7.14.0 a normal run follows the platforms enabled in `tiapp.xml`.
 
-The rule is simple: **if the template ships the file, `brand` updates it.** You should never have to know which API still reads which file to avoid shipping an app with the grey Alloy logo somewhere in it.
+The command also creates Titanium-consumed Classic paths that a fresh Classic template does not seed, including the 11 Android `Resources/android/images/res-*` splash variants. An explicit `--only` is an intentional override that can prepare assets for a disabled deployment target.
 
 For the terse flag reference, see the [`brand` command reference](./cli-commands.md#brand-command). For sibling UI assets, see [Multi-Density Images](./multi-density-images.md).
 
@@ -30,6 +30,7 @@ For the terse flag reference, see the [`brand` command reference](./cli-commands
 - [iOS 18+ Dark and Tinted variants](#ios-18-dark-and-tinted-variants)
 - [Brand color](#brand-color)
 - [Padding guidance](#padding-guidance)
+- [Rounded non-icon artwork](#rounded-non-icon-artwork)
 - [Cleanup legacy branding artifacts](#cleanup-legacy-branding-artifacts)
 - [Troubleshooting](#troubleshooting)
 - [Flag reference](#flag-reference)
@@ -51,9 +52,10 @@ purgetss brand
 
 On a first run the command:
 
-1. Creates the `brand:` section in `purgetss/config.cjs` with sensible defaults (if missing).
-2. Generates every branding file directly into the project (in-place).
-3. Prints a compact summary of what was written.
+1. Creates `purgetss/config.cjs` from the canonical template if the file is missing, including in standalone Classic projects.
+2. Creates or updates the `brand:` section with current defaults.
+3. Generates branding files for the enabled deployment targets directly into the project.
+4. Prints a compact summary of what was written.
 
 Pass `--dry-run` to preview without writing any files:
 
@@ -61,6 +63,8 @@ Pass `--dry-run` to preview without writing any files:
 purgetss brand --dry-run
 ```
 
+You may also pass a source directly. When a standalone Classic project has no canonical `purgetss/brand/logo.{svg,png}`, the confirmed run moves that positional source into the convention and reports the destination. An existing canonical logo is never replaced silently.
+
 ## The `purgetss/brand/` convention
 
 `init` creates `purgetss/brand/` (alongside `fonts/` and `images/`) so the folder is already there the first time you look for it, even before you've dropped in a logo.
@@ -140,13 +144,15 @@ On the first run, `purgetss brand` adds a `brand:` block to your existing `purge
 
 ```javascript
 brand: {
-  background: '#FFFFFF',   // inherited by every piece that doesn't set its own
-  confirmOverwrites: true, // prompt before overwriting files (set false to skip)
-  optimize: false,         // true = quantize the generated PNGs to a palette (lossy, ~71% smaller)
+  background: '#FFFFFF',      // inherited by every piece that doesn't set its own
+  artworkCornerRadius: '0%',  // rounded non-icon artwork: splashes, Feature Graphic and LaunchLogo
+  confirmOverwrites: true,    // prompt before overwriting files (set false to skip)
+  optimize: false,            // true = quantize the generated PNGs to a palette (lossy, ~71% smaller)
 
   // One block per piece. Artwork comes from purgetss/brand/logo-<piece>.{svg,png};
   // these keys are for numbers, colors and activation. Padding is never inherited.
-  icon:             { padding: '4%' },    // DefaultIcon.png + DefaultIcon-ios.png
+  // Only iosSplash, androidSplash, featureGraphic and launchLogo accept cornerRadius.
+  icon:             { padding: '0%' },    // DefaultIcon.png + DefaultIcon-ios.png
   dark:             { background: null }, // DefaultIcon-Dark.png
   tinted:           {},                   // DefaultIcon-Tinted.png
   iosSplash:        { padding: '26%' },   // assets/iphone/Default*.png × 16
@@ -155,7 +161,7 @@ brand: {
   featureGraphic:   { padding: '12%' },   // MarketplaceArtworkFeature.png (1024×500)
   adaptive:         { padding: '18%' },   // ic_launcher_{foreground,background,monochrome}.png × 5 + ic_launcher.xml
   legacyIcon:       { padding: '10%' },   // ic_launcher.png × 5
-  appicon:          {},                   // appicon.png (128×128)
+  appicon:          { padding: '10%' },   // appicon.png (128×128)
   androidSplash:    { padding: '26%' },   // assets/android/default.png + images/res-*/default.png × 11
 
   // Opt-in: inert until you edit the Android theme / FCM meta-data by hand.
@@ -167,6 +173,8 @@ brand: {
 
 Change only what you want to keep as a project default. CLI flags still win for one-off runs.
 
+Use flags for temporary artwork, geometry, the shared background, selection, activation, and optimization. Keep persistent choices such as `confirmOverwrites`, permanent `enabled` values, and exceptional per-piece backgrounds in `config.cjs`.
+
 ### Older configs update themselves
 
 PurgeTSS keeps `config.cjs` current the same way it renamed `config.js` to `config.cjs`: **on the file, once**. When the `brand:` block uses a shape from an earlier version, the next run rewrites it to the per-piece structure and carries over everything that had been customized (paddings, colors, logo paths, enabled flags), then lists each value it moved:
@@ -198,11 +206,12 @@ A key `brand:` does not define stops the run before a single file is written, at
 Unknown key(s) in the brand: section of purgetss/config.cjs:
   • brand.adaptive.paddig
 
-  Top-level keys: background, confirmOverwrites, logo, monochromeLogo
+  Top-level keys: background, artworkCornerRadius, splashCornerRadius, confirmOverwrites,
+                  optimize, logo, monochromeLogo
   Piece blocks:   icon, dark, tinted, iosSplash, launchLogo, marketplace, featureGraphic,
                   adaptive, legacyIcon, appicon, androidSplash, splashIcon,
                   notificationIcon, ninePatch
-  Inside a piece: logo, padding, background, enabled
+  Inside a piece: logo, padding, cornerRadius, background, enabled
 
   Check the spelling. Nothing was written.
 ```
@@ -211,12 +220,13 @@ A typo is deliberately **not** treated as an old structure: rewriting the block
 
 ## Brand config reference
 
-Every piece accepts the same four keys, where they apply:
+Every piece accepts the same five keys, where they apply:
 
 | Key | What it does |
 | --- | --- |
 | `logo` | Path to this piece's artwork, when it lives outside `purgetss/brand/`. |
 | `padding` | Inset per side, as a number or a percentage string like `'19%'`. **Never inherited.** |
+| `cornerRadius` | Rounded artwork corners, only for `iosSplash`, `androidSplash`, `featureGraphic`, and `launchLogo`; integer or percentage string from `0` through `50`. |
 | `background` | Hex color, or `null` for transparent. Inherited from `brand.background`. |
 | `enabled` | `false` turns a default piece off; `true` turns an opt-in piece on. |
 
@@ -225,6 +235,8 @@ And these live at the top level:
 | Key | Default | Purpose |
 | --- | --- | --- |
 | `background` | `'#FFFFFF'` | The background every piece inherits unless it declares its own: the Android adaptive background layer, the `DefaultIcon-ios.png` flatten, the splash canvases, and the marketplace flatten when a background is explicitly configured. |
+| `artworkCornerRadius` | `'0%'` | Shared radius for the four supported non-icon artwork pieces. It never changes store or launcher icons. |
+| `splashCornerRadius` | — | Optional splash-only override for `iosSplash` and `androidSplash`. |
 | `confirmOverwrites` | `true` | Whether `brand` asks before overwriting project files in place. |
 | `optimize` | `false` | Quantize the generated PNGs to a palette. Lossy — see [Shrinking the generated files](#shrinking-the-generated-files). |
 | `logo` | — | Path override for the main logo. |
@@ -234,12 +246,12 @@ And these live at the top level:
 
 | Piece | Config key | Generates | Default padding | On by default |
 | --- | --- | --- | --- | --- |
-| `icon` | `icon` | `DefaultIcon.png` + `DefaultIcon-ios.png` | `4%` | yes |
-| `dark` | `dark` | `DefaultIcon-Dark.png` | `4%` | yes |
-| `tinted` | `tinted` | `DefaultIcon-Tinted.png` | `4%` | yes |
+| `icon` | `icon` | `DefaultIcon.png` + `DefaultIcon-ios.png` | `0%` | yes |
+| `dark` | `dark` | `DefaultIcon-Dark.png` | `0%` | yes |
+| `tinted` | `tinted` | `DefaultIcon-Tinted.png` | `0%` | yes |
 | `ios-splash` | `iosSplash` | `assets/iphone/Default*.png` × 16 | `26%` | yes |
 | `launch-logo` | `launchLogo` | `LaunchLogo.png` (1024×1024) | `12%` | when `logo-launch.*` exists |
-| `marketplace` | `marketplace` | `iTunesConnect.png` + `MarketplaceArtwork.png` | `4%` | yes |
+| `marketplace` | `marketplace` | `iTunesConnect.png` + `MarketplaceArtwork.png` | `0%` | yes |
 | `feature-graphic` | `featureGraphic` | `MarketplaceArtworkFeature.png` (1024×500) | `12%` | yes |
 | `adaptive` | `adaptive` | `ic_launcher_{foreground,background,monochrome}.png` × 5 + `ic_launcher.xml` | `18%` | yes |
 | `legacy-icon` | `legacyIcon` | `ic_launcher.png` × 5 | `10%` | yes |
@@ -255,7 +267,7 @@ Only three pieces are opt-in, and for one reason: they produce nothing useful un
 
 ### `background` is inherited, `padding` is not
 
-Set `brand.background` once and every piece picks it up. Padding works the other way on purpose: the defaults answer to different constraints. The adaptive `18%` answers to the Android launcher mask, while the iOS `4%` is an aesthetic choice with no mask behind it. A single inherited number would let `8%` quietly break the launcher mask, so padding is set per piece or not at all.
+Set `brand.background` once and every piece picks it up. Padding works the other way on purpose: the adaptive `18%` answers to the Android launcher mask, while finished iOS/store artwork defaults to full-bleed `0%`. A single inherited number could quietly break the launcher mask or frame finished square artwork, so padding is set per piece or not at all.
 
 ## Overwrite confirmation
 
@@ -290,7 +302,7 @@ The output is automatically routed to the right directory for your project layou
 
 ```text
 <project>/
-├── DefaultIcon.png                 ← 1024×1024, universal fallback (Android-safe padding)
+├── DefaultIcon.png                 ← 1024×1024, universal fallback (brand.icon.padding)
 ├── DefaultIcon-ios.png             ← 1024×1024, iOS flattened on brand.background
 ├── DefaultIcon-Dark.png            ← 1024×1024, iOS 18+ dark (transparent per Apple HIG)
 ├── DefaultIcon-Tinted.png          ← 1024×1024, iOS 18+ tinted (grayscale on black)
@@ -326,7 +338,8 @@ The output is automatically routed to the right directory for your project layou
 │   ├── iphone/Default*.png         ← the launch images the template ships
 │   └── android/
 │       ├── appicon.png             ← 128×128
-│       └── default.png             ← Android <12 splash
+│       ├── default.png             ← Android <12 splash
+│       └── images/res-*/default.png ← 11 Titanium qualifier splashes
 └── platform/
     └── android/res/
         ├── mipmap-*/               ← same 5 densities as Alloy
@@ -334,7 +347,7 @@ The output is automatically routed to the right directory for your project layou
         └── mipmap-anydpi-v26/ic_launcher.xml
 ```
 
-A Classic project has no `images/res-*` folders, so the per-qualifier splashes are simply skipped there.
+A fresh Classic project may not contain `images/res-*`, but `brand` creates all 11 `Resources/android/images/res-*` variants because Titanium consumes those qualifier paths.
 
 The Android outputs are related, but they are not interchangeable:
 
@@ -475,7 +488,7 @@ Below Android 12 there is no system splash: the launch screen comes from the ima
 `brand` regenerates the whole set on every run. It is the `android-splash` piece, on by default:
 
 - `app/assets/android/default.png` (`Resources/android/default.png` in Classic)
-- `app/assets/android/images/res-*/default.png` — the 11 per-qualifier images the Alloy template ships
+- `app/assets/android/images/res-*/default.png` (`Resources/android/images/res-*/default.png` in Classic) — the 11 per-qualifier images Titanium consumes
 
 Earlier versions regenerated only the first file and hid the other 11 behind a `--legacy-splash` flag, which is why a freshly branded project could still flash the grey Alloy logo on an older phone. That flag is gone: its output is part of `android-splash` and always generated.
 
@@ -509,7 +522,7 @@ The output keeps its alpha, so the storyboard's `<default-background-color>` sho
 
 ## iPhone launch images
 
-The Alloy and Classic templates ship 16 `Default*.png` launch images under `assets/iphone/`, from the 320×480 original iPhone size up to 2688×1242. `brand` regenerates all of them, scaling the logo against the **shorter side** of each canvas so portrait and landscape carry the same visual weight.
+The Alloy and Classic templates ship 16 `Default*.png` launch images under `app/assets/iphone/` or `Resources/iphone/`, from the 320×480 original iPhone size up to 2688×1242. `brand` regenerates all of them, scaling the logo against the **shorter side** of each canvas so portrait and landscape carry the same visual weight.
 
 With `<enable-launch-screen-storyboard>` enabled (the default), iOS never reads these files. They are regenerated because they are in your project, they ship with the Alloy logo, and no one should have to audit their `tiapp.xml` to know whether that matters. If you are sure your project doesn't need them, [`--cleanup-legacy`](#cleanup-legacy-branding-artifacts) deletes them instead.
 
@@ -572,7 +585,8 @@ Padding belongs to the piece, not to the project. Each piece has its own key and
 | --- | --- | --- | --- |
 | `adaptive` | `brand.adaptive.padding` | `--android-adaptive-padding` | `18%` |
 | `legacy-icon` | `brand.legacyIcon.padding` | `--android-legacy-padding` | `10%` |
-| `icon` | `brand.icon.padding` | `--ios-padding` | `4%` |
+| `appicon` | `brand.appicon.padding` | `--appicon-padding` | `10%` |
+| `icon` | `brand.icon.padding` | `--ios-padding` | `0%` |
 | `feature-graphic` | `brand.featureGraphic.padding` | `--feature-graphic-padding` | `12%` |
 | `launch-logo` | `brand.launchLogo.padding` | `--launch-logo-padding` | `12%` |
 | `android-splash` | `brand.androidSplash.padding` | `--android-splash-padding` | `26%` |
@@ -580,7 +594,7 @@ Padding belongs to the piece, not to the project. Each piece has its own key and
 
 `--padding` is a shortcut for the two Android launcher paddings in a single run, and `--splash-padding` for the two splash paddings. `--ios-padding` moves the four square iOS/marketplace pieces together (`icon`, `dark`, `tinted`, `marketplace`); in config each of them has its own key.
 
-There is deliberately **no global padding value that cascades down**. The defaults answer to different constraints: `18%` answers to the Android launcher mask, while `4%` is an aesthetic choice for a canvas with no mask behind it. One inherited number would let a reasonable-looking `8%` silently break the launcher mask. `background`, which has no such trap, is inherited from `brand.background`.
+There is deliberately **no global padding value that cascades down**. The defaults answer to different constraints: `18%` answers to the Android launcher mask, while finished square iOS/store artwork stays full-bleed at `0%`. One inherited number could silently break the launcher mask or add an unwanted frame to finished artwork. `background`, which has no such trap, is inherited from `brand.background`.
 
 ### How the source is read, and how sharp the output is
 
@@ -615,6 +629,19 @@ The `26%` default is calibrated against the Titanium template itself: the Alloy
 
 Before v7.13.0 none of this was configurable: `default.png` used a hardcoded box of 72% × 26% of its own canvas, and the `res-*` set a separate hardcoded 60%. Two rules for the same piece, neither adjustable.
 
+## Rounded non-icon artwork
+
+`brand.artworkCornerRadius` rounds artwork only in the 16 iPhone launch images, Android `default.png` plus its 11 qualifier variants, `MarketplaceArtworkFeature.png`, and `LaunchLogo.png`. A piece may override it with `cornerRadius`; `brand.splashCornerRadius` is an optional shared override for the two legacy splash pieces.
+
+Values are integer numbers or percentage strings from `0` through `50`, measured against the shorter side of the resized artwork. `0%` preserves the previous output byte for byte; `50%` makes square artwork circular and a wordmark capsule-shaped. Normal and `--dry-run` summaries report the effective padding and radius.
+
+Precedence is:
+
+- Feature Graphic / LaunchLogo: piece-specific flag → `--artwork-corner-radius` → piece config → `brand.artworkCornerRadius` → `0%`.
+- Legacy splashes: platform flag → `--splash-corner-radius` → `--artwork-corner-radius` → piece config → `brand.splashCornerRadius` → `brand.artworkCornerRadius` → `0%`.
+
+Store and launcher icons remain unmasked for platform processing. `cornerRadius` is rejected in `DefaultIcon*`, `iTunesConnect.png`, `MarketplaceArtwork.png`, adaptive, legacy, and app icons, Android 12+ `splash_icon.png`, notification icons, and any other unsupported piece; invalid, fractional, negative, non-numeric, or greater-than-50 values also abort before files are written.
+
 ### Adaptive icon padding
 
 Android's adaptive canvas is 108 dp. The mask leaves roughly 72 dp visible, and the **guaranteed** safe area is a 66 dp circle inscribed in it. What each padding means in those terms:
@@ -749,7 +776,7 @@ All 5 Android densities, marketplace artwork, splash canvases, and iOS variants
 
 ## Flag reference
 
-Every flag lives in the terse reference: [`brand` command](./cli-commands.md#brand-command) — project & output, `--only`, padding, optional asset types, the `--<piece>-logo` overrides, `--optimize`, appearance, legacy cleanup and diagnostics, with examples.
+Every flag lives in the terse reference: [`brand` command](./cli-commands.md#brand-command) — project & output, `--only`, padding and corner radius, optional asset types, the `--<piece>-logo` overrides, `--optimize`, appearance, legacy cleanup and diagnostics, with examples.
 
 ## Community-Discovered Patterns
 

package/skills/purgetss/references/appearance-module.md

@@ -1,6 +1,6 @@
 # Appearance Module
 
-The `Appearance` export from `purgetss.ui` (added in **v7.5.3**) handles Light / Dark / System mode switching and persists the user's choice across app restarts. It is a thin, deterministic wrapper around Titanium's native `Ti.UI.overrideUserInterfaceStyle` plus `Ti.App.Properties`, exposed as a singleton so every controller in the app reads and writes the same state.
+The `Appearance` export from `purgetss.ui` (added in **v7.5.3**) handles Light / Dark / System mode switching and persists the user's choice across app restarts. It is a thin, deterministic wrapper around Titanium's native `Ti.UI.overrideUserInterfaceStyle` plus `Ti.App.Properties`, exposed as a singleton so every Alloy controller or Classic module reads and writes the same state.
 
 This reference follows the same workflow-first / API-second split the official PurgeTSS documentation now uses:
 
@@ -18,7 +18,7 @@ For the color wiring that actually makes the UI *respond* to mode changes, see [
 The Appearance module sits between three moving parts: a JS singleton, the OS-level interface style, and the semantic colors generated by PurgeTSS. The diagram below shows how a single `Appearance.init()` call at startup wires them together, and what happens when the user later picks a mode in Settings.
 
 ```
-┌─ app/lib/appearance.js (singleton from purgetss.ui) ─────────────────┐
+┌─ Appearance singleton from purgetss.ui ──────────────────────────────┐
 │                                                                      │
 │   Appearance.init()  ────► reads 'userInterfaceStyle'                │
 │                            from Ti.App.Properties                    │
@@ -160,16 +160,67 @@ The background, text, border, and icon colors in the XML come from semantic colo
 
 > **Why named functions in Alloy controllers?** Alloy resolves `onClick="selectDark"` by looking up a top-level identifier on the controller scope. Named function declarations (`function selectDark() { ... }`) hoist and are reliably resolvable; arrow functions assigned to `const` are not hoisted and tend to bite you when an XML attribute fires before the binding has executed. The official setup guide uses named functions for this reason.
 
+## Titanium Classic
+
+Classic loads the generated runtime from `Resources/lib/purgetss.ui.js` and keeps the native color catalog at `Resources/semantic.colors.json`:
+
+```json
+{
+  "surfaceColor": { "light": "#F8FAFC", "dark": "#0F172A" },
+  "textColor": { "light": "#0F172A", "dark": "#F8FAFC" },
+  "accentColor": { "light": "#2563EB", "dark": "#60A5FA" }
+}
+```
+
+Use those semantic names directly in native Titanium color properties. Classic does not need PurgeTSS utility classes, TSS, `purgetss/config.cjs`, or any Alloy runtime file.
+
+```javascript
+const { Appearance } = require('lib/purgetss.ui')
+
+Appearance.init()
+
+const window = Ti.UI.createWindow({ backgroundColor: 'surfaceColor' })
+const title = Ti.UI.createLabel({
+  text: `Mode: ${Appearance.get()}`,
+  color: 'textColor'
+})
+const toggleButton = Ti.UI.createButton({
+  title: 'Toggle appearance',
+  color: 'surfaceColor',
+  backgroundColor: 'accentColor'
+})
+
+function toggleAppearance() {
+  Appearance.toggle()
+  title.text = `Mode: ${Appearance.get()}`
+}
+
+function disposeWindow() {
+  toggleButton.removeEventListener('click', toggleAppearance)
+  window.removeEventListener('close', disposeWindow)
+}
+
+toggleButton.addEventListener('click', toggleAppearance)
+window.add(title)
+window.add(toggleButton)
+window.addEventListener('close', disposeWindow)
+window.open()
+```
+
+Run a full native build after adding or changing semantic keys. A LiveView reload alone does not refresh Titanium's native color catalog. The `purgetss semantic` command can create the JSON for a Classic project; it writes only `Resources/semantic.colors.json`, not `config.cjs`, TSS, or utility mappings.
+
+For animation and runtime lifecycle examples in the same Classic application, see [purgetss-ui-classic.md](./purgetss-ui-classic.md).
+
 ## API reference
 
 ### Methods
 
-| Method       | Description                                                                 |
-| ------------ | --------------------------------------------------------------------------- |
-| `init()`     | Restore the saved mode from `Ti.App.Properties` and apply it via `Ti.UI.overrideUserInterfaceStyle`. Call once at app startup before opening the first window. |
-| `set(mode)`  | Apply and persist a mode. Accepts `'system'`, `'light'`, or `'dark'`. Any other value is silently ignored. |
-| `get()`      | Returns the current mode as a string: `'system'`, `'light'`, or `'dark'`.   |
-| `toggle()`   | Switch between `'light'` and `'dark'`. Skips `'system'` — if current mode is `'system'` the next call produces `'dark'`. |
+| Method | Description | Return |
+| --- | --- | --- |
+| `init()` | Restore the saved mode from `Ti.App.Properties` and apply it via `Ti.UI.overrideUserInterfaceStyle`. Call once at app startup before opening the first window. | `undefined` |
+| `set(mode)` | Apply and persist a mode. Accepts `'system'`, `'light'`, or `'dark'`. Any other value is silently ignored. | `undefined` |
+| `get()` | Read the current mode as `'system'`, `'light'`, or `'dark'`. | Mode string |
+| `toggle()` | Switch between `'light'` and `'dark'`. Skips `'system'` — if current mode is `'system'` the next call produces `'dark'`. | `undefined` |
 
 All four methods are **synchronous**. They do not fire events; if you need to react to a mode change, call your update logic right after `Appearance.set(...)`.
 
@@ -210,10 +261,13 @@ app startup
 ## Related
 
 - [semantic-colors.md](./semantic-colors.md) — defining `app/assets/semantic.colors.json` and mapping the color names in `config.cjs` so views actually respond to mode changes.
-- [cli-commands.md#semantic-command](./cli-commands.md#semantic-command) — the `purgetss semantic` command, which writes both the JSON and the `config.cjs` mapping for you.
+- [cli-commands.md#semantic-command](./cli-commands.md#semantic-command) — the `purgetss semantic` command; Alloy also receives `config.cjs` mappings, while Classic receives only the native JSON.
 - [customization-deep-dive.md](./customization-deep-dive.md) — full `config.cjs` structure, including the `theme.extend.colors` section where semantic names are registered.
+- [purgetss-ui-classic.md](./purgetss-ui-classic.md) — generated module path, Classic animation factory, method contracts, and cleanup.
 
 ## Community-Discovered Patterns
 
+These field-tested patterns are now also confirmed by the official Appearance documentation:
+
 - **Always call `Appearance.init()` before opening the first window.** Opening the window first causes a visible flicker on cold launch as the UI repaints from the system default to the saved mode. The official best-practices guide puts `Appearance.init()` on line 3 of `app/controllers/index.js`, immediately before `$.navWin.open()`, for exactly this reason.
 - **`toggle()` is not a three-state cycle.** It only alternates between `'light'` and `'dark'`. If the saved mode is `'system'`, the first `toggle()` call lands on `'dark'`. Build a cycle yourself with `get()` + `set(...)` when you need one.

package/skills/purgetss/references/class-categories.md

@@ -193,8 +193,8 @@ Complete inventory of all class prefixes organized by functional category. For n
 | `duration-*` | 22 | `duration-0`, `duration-50` to `duration-5000` |
 | `delay-*` | 22 | `delay-0`, `delay-50` to `delay-5000` |
 | `repeat-*` | ~31 | `repeat-*` variants |
-| `snap-*` (v7.4.0+) | 6 | `snap-back`, `snap-back-false`, `snap-center`, `snap-center-false`, `snap-magnet`, `snap-magnet-false` — drop behaviors for draggable views |
-| `keep-z-index` (v7.4.0+) | 2 | `keep-z-index`, `keep-z-index-false` — preserves z-order during drag when using `transition` layouts |
+| `snap-*` runtime behavior (v7.4.0+) | 4 | `snap-back`, `snap-back-false`, `snap-center`, `snap-center-false` — implemented drop behaviors. Generated inventories may still contain `snap-magnet*`, but the runtime does not consume them |
+| `keep-z-index` (v7.4.0+) | 2 | `keep-z-index`, `keep-z-index-false` — prevents touch-start promotion; it does not stop `draggable(array)` from assigning index-based z-order |
 
 ### Shadows & Elevation
 

package/skills/purgetss/references/class-index.md

@@ -196,7 +196,7 @@ The rest of this document collects conventions, prohibitions, and insights surfa
 
 ## All 364 Unique Prefixes (Alphabetical)
 
-> **NOTE**: Recent additions — v7.4.0 introduced `snap-back`, `snap-back-false`, `snap-center`, `snap-center-false`, `snap-magnet`, `snap-magnet-false`, `keep-z-index`, and `keep-z-index-false` for the Animation module drop/drag system. v7.5.3 introduced font-family classes `font-sans`, `font-serif`, `font-mono` alongside the existing weight classes.
+> **NOTE**: v7.4.0 introduced `snap-back`, `snap-back-false`, `snap-center`, `snap-center-false`, `snap-magnet`, `snap-magnet-false`, `keep-z-index`, and `keep-z-index-false`. The current runtime implements back, center, and touch-start z-index preservation but does not read `snap.magnet`; do not suggest the generated magnet classes as working behavior. v7.5.3 added `font-sans`, `font-serif`, and `font-mono`.
 
 
 ```

package/skills/purgetss/references/classic-projects.md

@@ -0,0 +1,115 @@
+# Classic Project Support
+
+Since PurgeTSS 7.15, the utility-class lifecycle remains Alloy-only while independent asset and CommonJS commands can run in Titanium Classic projects. Detect the project layout before choosing a command or output path.
+
+Official source: <https://purgetss.com/docs/commands#alloy-and-classic-compatibility>
+
+## Compatibility Matrix
+
+| Command | Alloy | Classic | Classic behavior |
+| --- | :---: | :---: | --- |
+| `brand` | yes | yes | Writes branding assets to Classic paths and follows enabled `tiapp.xml` deployment targets; explicit `--only` overrides that filter. |
+| `images` | yes | yes | Writes density variants under `Resources/android/images/res-*/` and `Resources/iphone/images/`; follows deployment targets unless `--android` or `--ios` is explicit. |
+| `semantic` | yes | yes | Writes only `Resources/semantic.colors.json`; it does not create `purgetss/`, `config.cjs`, TSS, `app/`, or a hook. |
+| `shades` | yes | yes | Output-only modes work anywhere. On a fresh Classic project, saving creates only `purgetss/config.cjs`; if the color module already exists, it is regenerated. |
+| `color-module` | yes | yes | Writes `app/lib/purgetss.colors.js` or `Resources/lib/purgetss.colors.js`; Classic creates no unrelated empty source folders. |
+| `module` | yes | yes | Writes `app/lib/purgetss.ui.js` or `Resources/lib/purgetss.ui.js`. |
+| `icon-library` | yes | yes | Copies fonts to `Resources/fonts/` and optional modules to `Resources/lib/`; `--styles` is skipped in Classic. |
+| `build-fonts` | yes | yes | Copies fonts to `Resources/fonts/` and optionally writes `Resources/lib/purgetss.fonts.js`; it does not generate TSS in Classic. |
+| Root `purgetss`, `--all`, `init`, `create`, `install-dependencies`, `build`, `watch` | yes | no | These commands own the Alloy utility-class lifecycle. |
+| `update`, `sudo-update` | yes | yes | Global CLI maintenance; no project layout is required. |
+
+## The Hard Boundary
+
+A Classic project does not receive or need:
+
+- `app/`
+- `app/styles/app.tss`
+- `purgetss/styles/utilities.tss`
+- `purgetss/styles/fonts.tss`
+- `alloy.jmk`
+- utility classes in views or controllers
+- `$.UI.create()`
+- the PurgeTSS CLI/package during application compilation or as an app dependency (generated CommonJS modules execute normally)
+
+Files generated under `Resources/` are native Titanium resources. Compile the Classic app normally with `ti build`.
+
+Do not interpret the presence of `purgetss/config.cjs` in a Classic project as permission to use utilities. Commands such as `brand`, `images`, `shades`, and `color-module` may use that file as development-time input without installing the Alloy lifecycle.
+
+Classic `shades` and `color-module` do not scaffold the empty `purgetss/brand/`, `purgetss/fonts/`, or `purgetss/images/` conventions created by Alloy initialization. On a fresh project, `shades` creates only its config; `color-module` creates that config when missing plus its module. If the module already exists, saving a palette refreshes it automatically.
+
+## Layout and Output Routing
+
+| Artifact | Alloy | Classic |
+| --- | --- | --- |
+| Semantic colors | `app/assets/semantic.colors.json` | `Resources/semantic.colors.json` |
+| Android UI densities | `app/assets/android/images/res-*/` | `Resources/android/images/res-*/` |
+| iPhone UI scales | `app/assets/iphone/images/` | `Resources/iphone/images/` |
+| Font files | `app/assets/fonts/` | `Resources/fonts/` |
+| Color module | `app/lib/purgetss.colors.js` | `Resources/lib/purgetss.colors.js` |
+| UI module | `app/lib/purgetss.ui.js` | `Resources/lib/purgetss.ui.js` (see [`purgetss.ui` in Classic](./purgetss-ui-classic.md)) |
+| Custom-font module | `app/lib/purgetss.fonts.js` | `Resources/lib/purgetss.fonts.js` |
+
+## Loading Generated Modules in Classic
+
+Titanium resolves local CommonJS paths from `Resources/`. Omit both the `Resources/` prefix and the `.js` extension from `require()`.
+
+| Generated file | Classic `require()` path |
+| --- | --- |
+| `Resources/lib/purgetss.colors.js` | `require('lib/purgetss.colors')` |
+| `Resources/lib/purgetss.ui.js` | `require('lib/purgetss.ui')` |
+| `Resources/lib/purgetss.fonts.js` | `require('lib/purgetss.fonts')` |
+| `Resources/lib/fontawesome.js` | `require('lib/fontawesome')` |
+| `Resources/lib/materialicons.js` | `require('lib/materialicons')` |
+| `Resources/lib/materialsymbols.js` | `require('lib/materialsymbols')` |
+| `Resources/lib/framework7icons.js` | `require('lib/framework7icons')` |
+
+This follows Titanium's [CommonJS module path resolution](https://titaniumsdk.com/guide/Titanium_SDK/Titanium_SDK_Guide/Best_Practices_and_Recommendations/CommonJS_Modules_in_Titanium.html#javascript-module-path-resolution).
+
+## Deployment Targets
+
+`brand` and `images` read `<deployment-targets>` from `tiapp.xml` independently of whether the layout is Alloy or Classic.
+
+- A normal run generates only enabled platform families.
+- `images --android` and `images --ios` are explicit overrides.
+- `brand --only <piece-or-group>` is an explicit override and may prepare assets for a platform before that target is enabled.
+
+Do not assume that Classic means Android-only or that an Alloy project targets both platforms.
+
+## Standalone First-Run Behavior
+
+### `brand`
+
+In a Classic project without `purgetss/config.cjs`, `brand` creates the canonical config before resolving settings. If a positional PNG/SVG is supplied and no canonical `purgetss/brand/logo.{png,svg}` exists, the command moves the source into that convention after overwrite confirmation and reports the destination. It never replaces an existing canonical logo silently.
+
+Classic Android receives the 11 `Resources/android/images/res-*` splash variants even when a fresh `ti create` template did not seed those folders. Titanium consumes those qualifier paths.
+
+### `images`
+
+Running `images` without a positional source establishes the `purgetss/images/` convention. Passing an existing external file or directory does not create an empty `purgetss/images/` folder or a config file merely to process that source.
+
+### `semantic`
+
+Classic `semantic` is deliberately output-only: it writes the native JSON and does not bootstrap any other PurgeTSS artifact. Classic code uses semantic keys directly in Titanium color properties rather than through utility classes.
+
+## Audit Checklist
+
+When auditing a Classic project that uses PurgeTSS:
+
+1. Confirm every invoked command is marked Classic-compatible in the matrix.
+2. Confirm outputs use `Resources/`, never Alloy's `app/assets/` or `app/lib/`.
+3. Reject any added `alloy.jmk`, generated TSS, utility classes, or `$.UI.create()`.
+4. For `brand` and `images`, compare generated platform families with `tiapp.xml` deployment targets and any explicit override flags.
+5. Confirm `semantic` did not create unrelated PurgeTSS setup files.
+6. For `icon-library --styles`, expect Classic to skip TSS output.
+7. For `build-fonts`, expect font files and optional CommonJS output only; no `fonts.tss`.
+
+## Related References
+
+- [CLI Commands](./cli-commands.md)
+- [App Icons & Branding](./app-branding.md)
+- [Multi-Density Images](./multi-density-images.md)
+- [Semantic Colors](./semantic-colors.md)
+- [Icon Font Libraries](./icon-fonts.md)
+- [Custom Fonts](./custom-fonts.md)
+- [`purgetss.ui` in Titanium Classic](./purgetss-ui-classic.md)