@maccesar/titools 4.17.1 → 4.19.0

package/README.md

@@ -6,7 +6,7 @@
 
 </div>
 
-TiTools is a Titanium SDK toolkit for AI coding assistants. It ships 10 skills — 5 specialist skills (`ti-expert`, `purgetss`, `ti-ui`, `ti-game`, `ti-synthengine`) plus 5 documentation-mirror skills (`ti-api`, `ti-guides`, `ti-howtos`, `alloy-guides`, `alloy-howtos`) — a research agent, and reference files covering Titanium architecture, API reference, native how-tos, Alloy MVC, PurgeTSS styling, UI/UX patterns, 2D games, and native sound synthesis.
+TiTools is a Titanium SDK toolkit for AI coding assistants. It ships 10 skills — 5 specialist skills (`ti-expert`, `purgetss`, `ti-ui`, `ti-game`, `ti-synthengine`) plus 5 documentation-mirror skills (`ti-api`, `ti-guides`, `ti-howtos`, `alloy-guides`, `alloy-howtos`) — a research agent, and reference files covering Titanium architecture, API reference, native how-tos, Alloy MVC, PurgeTSS styling and resource automation, UI/UX patterns, 2D games, and native sound synthesis.
 
 The reference files are maintained against official documentation whenever an official source exists, so the assistant can retrieve current framework behavior instead of guessing from generic training data.
 
@@ -175,7 +175,7 @@ The knowledge index is based on the latest Titanium SDK documentation. If your p
 | Skill        | Purpose                             | Best For                                |
 | ------------ | ----------------------------------- | --------------------------------------- |
 | ti-expert    | Architecture and implementation     | Starting point for most tasks           |
-| purgetss     | Utility-first styling               | UI styling and animations               |
+| purgetss     | Alloy styling + asset automation    | Utility classes; Alloy/Classic branding, images, colors, fonts and modules |
 | ti-ui        | UI/UX patterns                      | Complex layouts, ListViews, platform UI |
 | ti-game      | 2D games with the `ti.game` module  | Sprites, physics, tile layers, wall jumps, pathfinding, text/performance HUDs, particles, camera |
 | ti-synthengine | Sound design with `ti.synthengine` | Tones, chords, retro/UI effects, alarms, sweeps, patterns, mixing and troubleshooting |
@@ -277,7 +277,7 @@ Skills are automatically activated based on your questions. Just ask naturally:
 
 The AI will automatically use:
 - `ti-expert` -> Architecture and controller structure
-- `purgetss` -> Styling classes and animations (if PurgeTSS detected)
+- `purgetss` -> Alloy styling, or supported asset/CommonJS commands in Alloy and Classic (if PurgeTSS is detected or requested)
 - `ti-howtos` -> Secure token storage and native integration guidance
 
 You do not need to call skills explicitly. The AI reads skill descriptions and loads the appropriate knowledge when needed.
@@ -288,14 +288,14 @@ All skills include automatic project detection to ensure compatibility:
 
 | Skill     | What It Detects       | How It Works                                                  |
 | --------- | --------------------- | ------------------------------------------------------------- |
-| purgetss  | PurgeTSS installation | Checks for `purgetss/` folder, `config.cjs`, `utilities.tss`  |
+| purgetss  | PurgeTSS mode and project type | Checks PurgeTSS markers, then separates Alloy utilities from Classic standalone commands |
 | ti-expert | Alloy vs Classic      | Checks for `app/` (Alloy) vs `Resources/` (Classic) structure |
 | ti-ui     | Titanium projects     | Checks for `tiapp.xml` (both Alloy and Classic)               |
 | ti-game   | ti.game module        | Checks for `<module>ti.game</module>` in `tiapp.xml` or `require('ti.game')` |
 | ti-synthengine | ti.synthengine module | Checks for `<module>ti.synthengine</module>` in `tiapp.xml` or `require('ti.synthengine')` |
 
 Why this matters:
-- PurgeTSS suggestions are only provided if PurgeTSS is installed
+- PurgeTSS suggestions are provided when its project markers are detected or the user explicitly requests a standalone command
 - Alloy-specific patterns are only suggested for Alloy projects
 - Classic Titanium projects will not receive inappropriate Alloy advice
 
@@ -359,7 +359,7 @@ Key features:
 
 ### purgetss
 
-Utility-first styling toolkit for Titanium/Alloy.
+Utility-first styling for Titanium Alloy plus standalone asset and CommonJS commands for Alloy and Classic.
 
 When it activates:
 - Setting up PurgeTSS in a project
@@ -369,6 +369,7 @@ When it activates:
 - Custom color palettes
 - Platform-specific styling
 - config.cjs configuration
+- Classic `Resources/` outputs for branding, density images, semantic colors, fonts, and modules
 
 Example prompts:
 ```
@@ -378,6 +379,8 @@ Example prompts:
 "How do I configure custom colors in config.cjs?"
 "How do I use Font Awesome 7 icons?"
 "Style this button differently on iOS vs Android."
+"Generate image densities for this Classic Titanium app without converting it to Alloy."
+"Install Font Awesome and its CommonJS module under Resources in my Classic app."
 ```
 
 Rules:
@@ -802,7 +805,7 @@ This pattern is documented across four bundled TiTools skills: `ti-ui`, `ti-expe
 | Skill     | SKILL.md                      | References                                            |
 | --------- | ----------------------------- | ----------------------------------------------------- |
 | ti-expert | Architecture + Implementation | 26 files (patterns, feedback surfaces, file type association, sharing, testing, security, etc.) |
-| purgetss  | Setup + Critical Rules        | 33 files (grid, animations, icons, class-index, SVG pipeline, etc.) |
+| purgetss  | Setup + Critical Rules        | 34 files (Classic compatibility, grid, animations, icons, class-index, SVG pipeline, etc.) |
 | ti-ui     | UI Rules + Platform Diffs     | 14 files (layouts, lists, gestures, etc.)             |
 | ti-game   | Native 2D Game Workflow       | 9 files (API, setup, patterns, recipes, tile maps, debugging, roadmap) |
 | ti-synthengine | Native Sound Synthesis   | 8 files (API, sound design, lifecycle, engine, official examples, curated recipes, recommendations, troubleshooting) |
@@ -831,7 +834,8 @@ If the AI suggests patterns you don't use (for example, PurgeTSS when you're not
 If the purgetss skill doesn't activate for your PurgeTSS project:
 1. Verify `purgetss/` folder exists in project root
 2. Check that `purgetss/config.cjs` exists
-3. Mention "PurgeTSS" explicitly in your prompt
+3. In Classic, check for generated `Resources/lib/purgetss.*.js` modules
+4. Mention "PurgeTSS" explicitly in your prompt
 
 ### Wrong advice?
 

package/commands/ti-audit.md

@@ -17,7 +17,7 @@ Project-type audit:
 
 6. If the project is Alloy (`app/views/`, `app/controllers/`, `app/styles/`), invoke `alloy-guides` — check controllers, XML/TSS, models, collections, widgets, sync adapters and cleanup patterns.
 7. If the Alloy project uses `alloy.jmk`, `config.json`, `widget.json`, conditional views, custom XML tags or Alloy CLI workflows, invoke `alloy-howtos` — check configuration precedence, build hooks, generated structures and compilation/debugging conventions.
-8. If the project uses PurgeTSS (`purgetss/` or `purgetss/config.cjs`), invoke `purgetss` before evaluating styling — check unsupported utility classes, padding on Views, unnecessary manual TSS, dynamic components, grids, icons and animations.
+8. If the project uses PurgeTSS (`purgetss/`, `purgetss/config.cjs`, a PurgeTSS-generated `app.tss`, or `purgetss.{ui,colors,fonts}.js`), invoke `purgetss` and detect Alloy vs. Classic before applying findings. In Alloy, audit unsupported utility classes, padding on Views, unnecessary manual TSS, dynamic components, grids, icons and animations. In Classic, audit only the supported standalone asset/CommonJS commands and their `Resources/` outputs; do not require or recommend `alloy.jmk`, generated TSS, utility classes, or `$.UI.create()`.
 
 Native-module audit:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maccesar/titools",
-  "version": "4.17.1",
+  "version": "4.19.0",
   "description": "Titanium SDK skills and agents for AI coding assistants, including native game and sound synthesis modules",
   "main": "lib/index.js",
   "type": "module",

package/skills/purgetss/SKILL.md

@@ -1,33 +1,44 @@
 ---
 name: purgetss
-description: "Use when working with PurgeTSS, Titanium's utility-first styling toolkit — styling, reviewing, analyzing, or examining Titanium UI with utility classes, configuring config.cjs, creating dynamic components with $.UI.create(), building animations, grid layouts, icon fonts, or TSS styles. AUTO-DETECT: If purgetss/ folder or purgetss/config.cjs exists, invoke BEFORE writing ANY styling code. PurgeTSS classes look like Tailwind but are NOT Tailwind — verify every class exists. Never use padding on Views (use margins on children), never use flexbox classes, never write manual TSS when a utility class exists."
-argument-hint: "[class-name]"
+description: "Use when a Titanium project uses PurgeTSS utility classes, purgetss/config.cjs, $.UI.create(), generated app.tss, or PurgeTSS asset, color, font, branding, and CommonJS commands. Detect Alloy vs. Classic first: the utility-class workflow is Alloy-only, while selected standalone commands write native Resources/ files in Classic. PurgeTSS resembles Tailwind but has a different class contract, so verify every suggested class."
 allowed-tools: Read, Grep, Glob, Edit, Write, Bash(purgetss *), Bash(node *)
 ---
 
 # PurgeTSS Expert
 
-Utility-first styling toolkit for Titanium/Alloy mobile apps.
+PurgeTSS is a utility-first styling toolkit for Titanium Alloy and a standalone asset/CommonJS generator for Alloy and Classic projects. The project layout determines which half of the toolkit is valid.
 
 ## Required workflow (read before responding)
 
 The SKILL.md alone is an **index** of references. The detail you need to give accurate answers lives in the reference files. **Reading this SKILL.md is not enough.**
 
-### Step 1 — Open the relevant reference files
+### Step 1 — Detect the project type
+
+Before recommending a command, class, output path, `$.UI.create()`, TSS file, or build hook, determine whether the project is Alloy (`app/views/`, `app/controllers/`, `app/styles/`) or Classic (`Resources/` without the Alloy tree).
+
+- **Alloy:** utility classes and every standalone command are available.
+- **Classic:** only the supported standalone commands are available. Do not introduce `app/`, `alloy.jmk`, generated TSS, utility classes, or `$.UI.create()`.
+
+### Step 2 — Open the relevant reference files
 
 | Task involves | Required reading |
 |---|---|
+| Alloy vs. Classic support or output paths | [references/classic-projects.md](references/classic-projects.md), [references/cli-commands.md](references/cli-commands.md) |
+| Setup, auto-purge, or `watch` diagnostics | [references/installation-setup.md](references/installation-setup.md), [references/cli-commands.md](references/cli-commands.md) |
 | Choosing utility classes | [references/class-index.md](references/class-index.md) |
 | Layout (horizontal/vertical/composite, grid) | [references/grid-layout.md](references/grid-layout.md), [references/ui-ux-design.md](references/ui-ux-design.md) |
 | Dynamic components in controllers | [references/dynamic-component-creation.md](references/dynamic-component-creation.md) |
+| App branding or artwork geometry | [references/app-branding.md](references/app-branding.md), [references/cli-commands.md](references/cli-commands.md) |
 | SVG / multi-density image assets | [references/svg-pipeline.md](references/svg-pipeline.md), [references/multi-density-images.md](references/multi-density-images.md) |
 | Custom values / arbitrary syntax | [references/arbitrary-values.md](references/arbitrary-values.md) |
 | Platform-specific styles (`ios:`, `android:`) | [references/platform-modifiers.md](references/platform-modifiers.md) |
 | Dark/Light mode | [references/semantic-colors.md](references/semantic-colors.md), [references/appearance-module.md](references/appearance-module.md) |
 | Apply directive / class extraction | [references/apply-directive.md](references/apply-directive.md) |
-| Animations | [references/animation-system.md](references/animation-system.md) |
+| Custom or icon fonts | [references/custom-fonts.md](references/custom-fonts.md), [references/icon-fonts.md](references/icon-fonts.md) |
+| Animations in Alloy | [references/animation-system.md](references/animation-system.md), [references/animation-advanced.md](references/animation-advanced.md) |
+| `purgetss.ui` in Classic | [references/purgetss-ui-classic.md](references/purgetss-ui-classic.md), [references/classic-projects.md](references/classic-projects.md) |
 
-### Step 2 — Output contract
+### Step 3 — Output contract
 
 Every utility class you suggest and every styling pattern you describe MUST be backed by a citation in the form:
 
@@ -35,7 +46,7 @@ Every utility class you suggest and every styling pattern you describe MUST be b
 
 Example: *"Use `wh-12` to set width and height to 48px [source: references/class-index.md]"*
 
-### Step 3 — If you must answer from memory
+### Step 4 — If you must answer from memory
 
 If you write a claim without having read the reference that backs it, prepend `FROM_MEMORY (unverified):` to that claim. Do not hide it.
 
@@ -45,31 +56,42 @@ If you write a claim without having read the reference that backs it, prepend `F
 - ❌ Confusing PurgeTSS classes with Tailwind — they share naming but differ
 - ❌ Marking the answer complete without listing which reference files you read
 - ❌ Suggesting a class without first verifying it exists in `class-index.md`
+- ❌ Applying Alloy utility classes, generated TSS, `alloy.jmk`, or `$.UI.create()` to a Classic project
 
-## Project Detection
+## Project Detection and Mode Selection
 
 > **️ℹ️ AUTO-DETECTS PURGETSS PROJECTS**
 > This skill automatically detects PurgeTSS usage when invoked and provides utility-first styling guidance.
 >
 > **Detection occurs automatically** - no manual command needed.
 >
-> **PurgeTSS project indicators:**
+> **PurgeTSS indicators:**
 > - `purgetss/` folder
 > - `purgetss/config.cjs` configuration file
 > - `purgetss/styles/utilities.tss` utility classes
-> - `app/styles/app.tss` (auto-generated)
+> - A generated `app/styles/app.tss` whose header names PurgeTSS
+> - `app/lib/purgetss.{ui,colors,fonts}.js` or `Resources/lib/purgetss.{ui,colors,fonts}.js`
+>
+> `app/styles/app.tss` by itself is not proof: ordinary Alloy projects can have that file.
 >
-> **Behavior based on detection:**
-> - **PurgeTSS detected** → Provides PurgeTSS-specific guidance, recommends utility classes, suggests `$.UI.create()` for dynamic components
+> **Behavior based on detection and layout:**
+> - **Alloy + PurgeTSS utility lifecycle detected** → Provides utility-class guidance and may suggest `$.UI.create()` for dynamic components
+> - **Classic + PurgeTSS standalone command detected/requested** → Provides only asset, color, font, branding, or CommonJS command guidance with `Resources/` destinations
 > - **Not detected** → Does NOT suggest PurgeTSS utility classes, does NOT recommend `$.UI.create()`, does NOT reference PurgeTSS-specific patterns
 
-## Core Workflow
+## Core Workflows
+
+### Alloy utility-class workflow
+
+1. **Setup**: `purgetss create 'name'` or `purgetss init` for an existing Alloy project.
+2. **Build**: Write Alloy XML/controller classes; PurgeTSS generates `app/styles/app.tss`.
+3. **Configure**: Customize utilities through `purgetss/config.cjs`.
+
+### Classic standalone workflow
 
-1. **Setup**: `purgetss create 'name'` or `purgetss init` for existing projects
-2. **Build**: Write XML with utility classes → PurgeTSS auto-generates `app.tss`
-3. **Configure**: Customize via `purgetss/config.cjs`
+Run only a command marked Classic-compatible in [Classic Project Support](references/classic-projects.md). Generated files are ordinary Titanium resources under `Resources/`; the app does not need a PurgeTSS hook or runtime dependency.
 
-## Project Structure
+## Alloy Utility Project Structure
 
 ```bash
 ./purgetss/
@@ -141,7 +163,7 @@ If you write a claim without having read the reference that backs it, prepend `F
 >
 > If a class appears in "Unused or unsupported classes" in `app.tss`, it means it's truly not defined anywhere - not even in your `config.cjs` customizations.
 
-## Quick Start
+## Alloy Quick Start
 
 ```bash
 purgetss create 'MyApp' -d -v fa
@@ -158,7 +180,7 @@ purgetss create 'MyApp' -d -v fa
 
 ## Critical Rules (Low Freedom)
 
-### ⭐ PREFER `$.UI.create()` for Dynamic Components
+### ⭐ ALLOY ONLY: Prefer `$.UI.create()` for Dynamic Components
 
 > **💡 RECOMMENDED FOR DYNAMIC COMPONENTS**
 > When creating components dynamically in Controllers, **use `$.UI.create()` instead of `Ti.UI.create()`** to get full PurgeTSS utility class support:
@@ -427,7 +449,7 @@ Load these only when needed:
 - [iOS Large Titles](references/ios-large-titles.md) - Best practice for iOS Large Title navigation
 
 ### App Assets
-- [App Branding](references/app-branding.md) - `brand` command: the 14 pieces it regenerates (launcher, adaptive, iOS 18+ Dark/Tinted, marketplace, both splash sets), the per-piece `brand:` config, `--only`, `--optimize` (v7.13.0)
+- [App Branding](references/app-branding.md) - `brand` command: 14 pieces, per-piece config, selection, optimization, appicon padding, and rounded non-icon artwork (v7.16.0)
 - [Launch Background](references/launch-background.md) - Carrying `brand.background` into the iOS LaunchScreen and a launcher-only Android theme (`--notes` output)
 - [Multi-Density Images](references/multi-density-images.md) - `images` command for Android res-*dpi + iPhone @1x/@2x/@3x UI images (v7.6.0)
 - [SVG Pipeline](references/svg-pipeline.md) - SVG-aware compile-time image pipeline: `.svg` refs + numeric `w-*`/`h-*` classes compile to 8 density PNGs; `images.files`/`images.autoSync` (v7.11.0–v7.11.1)
@@ -442,10 +464,11 @@ Load these only when needed:
 - [Custom Fonts](references/custom-fonts.md) - `build-fonts` command for Google Fonts, brand typefaces, and community icon fonts (.ttf + .css)
 - [Icon Fonts](references/icon-fonts.md) - The 4 official families (Font Awesome 7, Material Icons, Material Symbols, Framework7) — variant tables + `icon-library` install flow + recreating removed libraries
 - [Animation System](references/animation-system.md) - 15 methods including collision detection, transitions, and sequential animations
-- [Animation Advanced](references/animation-advanced.md) - Property inheritance, utility classes, implementation rules, complex UI example
+- [Animation Advanced](references/animation-advanced.md) - Property forwarding, runtime rules, utility classes, and platform behavior
+- [PurgeTSS UI in Classic](references/purgetss-ui-classic.md) - Native JavaScript setup, public exports, animation objects, cleanup, and platform notes
 
 ### Release Notes
-- [Version History](references/version-history.md) - Release-by-release feature additions and behavior changes (v7.4.0 → v7.13.1)
+- [Version History](references/version-history.md) - Release-by-release feature additions and behavior changes (v7.4.0 → v7.16.2)
 
 > **💡 TEXT FONTS (Google Fonts, Roboto, etc.)**
 > For text fonts, see [Custom Fonts](references/custom-fonts.md).