@maccesar/titools 2.7.2 → 2.9.0

package/README.md

@@ -8,7 +8,7 @@
 
 </div>
 
-TiTools is a Titanium SDK toolkit for AI coding assistants. It provides 9 skills, a research agent, and 100+ reference files for Titanium SDK, Alloy MVC, and PurgeTSS.
+TiTools is a Titanium SDK toolkit for AI coding assistants. It provides 8 skills, a research agent, and 100+ reference files for Titanium SDK, Alloy MVC, and PurgeTSS.
 
 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.
 
@@ -20,15 +20,9 @@ Vercel's AGENTS.md evaluation reports a 100% pass rate for the knowledge index a
 
 ## Safety and disclaimer
 
-TiTools modifies files in your Titanium project. In particular, the `ti-branding` skill can write branding assets into `app/platform/android/res/` and, when invoked with the `--cleanup-legacy` flag, **delete** obsolete branding artifacts (iOS launch images, Android legacy splash, density fossil folders, etc.).
+TiTools installs documentation skills and a research agent into your AI coding assistant's skill directories and, when you run `titools sync`, injects a knowledge index block into your project's `AGENTS.md`/`CLAUDE.md`/`GEMINI.md`.
 
-Recommendations before running destructive operations:
-
-- **Commit your project with git** so you can `git restore` if anything looks wrong.
-- **Always run with `--dry-run` first** when using `--cleanup-legacy` or replacing icons. The skill prints every target and its safety reasoning before touching anything.
-- **Review the staging directory** (`.ti-branding/`) before copying generated assets into your project.
-
-The maintainers of TiTools accept no responsibility for data loss, build breakage, or any other damage caused by the use of the CLI, skills, or generated scripts. The tool is provided AS IS under the MIT License — see [`LICENSE`](./LICENSE) for the full terms. Use at your own risk.
+The maintainers of TiTools accept no responsibility for data loss, build breakage, or any other damage caused by the use of the CLI, skills, or the AI assistant's code suggestions. The tool is provided AS IS under the MIT License — see [`LICENSE`](./LICENSE) for the full terms. Use at your own risk.
 
 ---
 
@@ -44,7 +38,7 @@ The fastest way to get started with Claude Code. One command to add the marketpl
 ```
 
 What you get:
-- All 9 Titanium skills
+- All 8 Titanium skills
 - ti-pro research agent
 - Session hook that auto-detects Titanium projects (`tiapp.xml`, Alloy, PurgeTSS)
 - Slash commands: `/ti-check`, `/ti-new-screen`, `/ti-audit`
@@ -78,7 +72,7 @@ claude   # or gemini, or codex
 ```
 
 What gets installed:
-- All 9 titanium-related skills to `~/.agents/skills/`
+- All 8 titanium-related skills to `~/.agents/skills/`
 - ti-pro agent for Claude Code
 - Platform symlinks (Claude Code, Gemini CLI, Codex CLI)
 - Knowledge index in your project's `AGENTS.md`/`CLAUDE.md`/`GEMINI.md`
@@ -184,7 +178,6 @@ The knowledge index is based on the latest Titanium SDK documentation. If your p
 | alloy-howtos | Alloy CLI and debugging         | Project setup, CLI commands, errors                                             |
 | purgetss     | Utility-first styling           | UI styling and animations                                                       |
 | ti-api       | Complete API reference          | Properties, methods, events, constants                                          |
-| ti-branding  | Icon and splash generator       | App icons, adaptive icons, splash, notifications, store artwork, legacy cleanup |
 | ti-expert    | Architecture and implementation | Starting point for most tasks                                                   |
 | ti-guides    | SDK fundamentals                | Hyperloop, distribution, configuration                                          |
 | ti-howtos    | Native feature integration      | Location, Push, Media, Platform APIs                                            |
@@ -643,7 +636,7 @@ Behavior depends on where you run it:
 | With `--local` flag        | Installs skills locally to `./.agents/skills/` in the current project |
 
 What it does:
-- Installs all 7 titanium-related skills (global or local depending on context)
+- Installs all 8 titanium-related skills (global or local depending on context)
 - Installs ti-pro agent for Claude Code
 - Detects installed AI platforms and lets you choose which to link
 - Creates symlinks from platform directories to central skills

package/lib/config.js

@@ -38,11 +38,11 @@ export const SKILLS = [
   'ti-guides',
   'alloy-guides',
   'alloy-howtos',
-  'ti-branding',
 ];
 // Legacy skills to remove during updates/uninstall
 export const LEGACY_SKILLS = [
   'alloy-expert',
+  'ti-branding',
 ];
 
 // Agents to install

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maccesar/titools",
-  "version": "2.7.2",
+  "version": "2.9.0",
   "description": "Titanium SDK skills and agents for AI coding assistants (Claude Code, Gemini CLI, Codex CLI)",
   "main": "lib/index.js",
   "type": "module",

package/skills/purgetss/SKILL.md

@@ -112,6 +112,20 @@ purgetss create 'MyApp' -d -v fa
 # -v: Copy icon fonts (fa, mi, ms, f7)
 ```
 
+## What's New in v7.6.0
+
+- `brand` command — complete Titanium branding set (launcher icons, adaptive, iOS 18+ Dark/Tinted, marketplace) from logos in `./purgetss/brand/`
+- `images` command — multi-density UI images (Android res-*dpi + iPhone @1x/@2x/@3x) from `./purgetss/images/`
+- `semantic` command — Titanium semantic colors for Light/Dark mode (palette mode + single mode)
+- `brand:` and `images:` config sections auto-injected into older configs
+- Percentages as strings (`'15%'`) for self-documenting clarity in brand/images configs
+
+## 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`
@@ -380,6 +394,8 @@ purgetss create 'MyApp' -d -v fa
 > - **[Class Index](references/class-index.md)** - Naming conventions, 416-property table, prohibited classes, verification commands (LOAD FIRST when unsure about a class)
 > - **[Class Categories](references/class-categories.md)** - Complete prefix inventory by category (layout, colors, typography, states, etc.)
 > - **[Dynamic Component Creation](references/dynamic-component-creation.md)** - `$.UI.create()` and `Alloy.createStyle()` for creating components in Controllers (READ FIRST for dynamic components)
+> - **[Appearance Module](references/appearance-module.md)** - Light/Dark/System mode switching with persistence (v7.5.3)
+> - **[Semantic Colors](references/semantic-colors.md)** - Titanium semantic colors for Light/Dark mode via `semantic` command (v7.6.0)
 >
 > ### Setup & Configuration
 > - [Installation & Setup](references/installation-setup.md) - First run, VS Code, LiveView
@@ -392,6 +408,10 @@ purgetss create 'MyApp' -d -v fa
 > - [Apply Directive](references/apply-directive.md) - Extracting utility combinations
 > - [Configurable Properties](references/configurable-properties.md) - All 80+ customizable properties
 >
+> ### Appearance & Theming
+> - **[Appearance Module](references/appearance-module.md)** - Light/Dark/System mode switching with persistence (v7.5.3)
+> - **[Semantic Colors](references/semantic-colors.md)** - `semantic` command + runtime usage for Light/Dark mode (v7.6.0)
+>
 > ### Layout & Styling
 > - **[UI/UX Design Patterns](references/ui-ux-design.md)** - Complete guide to mobile UI components with PurgeTSS (cards, lists, forms, buttons, navigation, modals, accessibility)
 > - [Grid Layout System](references/grid-layout.md) - 12-column grid, responsive layouts
@@ -400,6 +420,11 @@ purgetss create 'MyApp' -d -v fa
 > - [Platform Modifiers](references/platform-modifiers.md) - ios:, android:, tablet:, handheld:
 > - [Opacity Modifier](references/opacity-modifier.md) - Color transparency with /50 syntax
 > - [Titanium Resets](references/titanium-resets.md) - Default styles for Ti elements
+> - [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 for launcher icons, adaptive, iOS 18+ Dark/Tinted, marketplace assets (v7.6.0)
+> - [Multi-Density Images](references/multi-density-images.md) - `images` command for Android res-*dpi + iPhone @1x/@2x/@3x UI images (v7.6.0)
 >
 > ### Performance
 > - [Performance Tips](references/performance-tips.md) - Optimizing PurgeTSS apps (bridge crossings, ListView, animations)

package/skills/purgetss/references/EXAMPLES.md

@@ -2,7 +2,11 @@
 
 Complete examples of common patterns with anti-patterns and correct implementations.
 
-## Titanium Layout Patterns
+## Community-Discovered Patterns
+
+The examples below catalog anti-patterns observed in real Titanium + PurgeTSS projects, paired with the correct approach. They are not exhaustive rules from official docs — they reflect pitfalls the community has hit often enough to warrant dedicated guidance.
+
+### Titanium Layout Patterns
 
 > **🚨 NO FLEXBOX IN TITANIUM**
 > Titanium does NOT support CSS Flexbox. All examples use `horizontal`, `vertical`, or `composite` layouts.
@@ -108,7 +112,7 @@ Complete examples of common patterns with anti-patterns and correct implementati
 
 ---
 
-## Manual .tss Files Anti-Pattern
+### Manual .tss Files Anti-Pattern
 
 **❌ WRONG (Creating manual .tss files):**
 ```xml
@@ -158,7 +162,7 @@ alloy compile
 
 ---
 
-## Grid with Percentages
+### Grid with Percentages
 
 **❌ WRONG (Children with % widths, parent without w-screen):**
 ```xml
@@ -179,7 +183,7 @@ alloy compile
 
 ---
 
-## Gap Usage
+### Gap Usage
 
 **❌ WRONG (gap adds margin all around, breaks % widths):**
 ```xml
@@ -200,7 +204,7 @@ alloy compile
 
 ---
 
-## Padding on Container Views
+### Padding on Container Views
 
 **❌ WRONG (Padding on Views doesn't work in Titanium):**
 ```xml
@@ -220,7 +224,7 @@ alloy compile
 
 ---
 
-## `w-full` vs `w-screen`
+### `w-full` vs `w-screen`
 
 **❌ WRONG (Using percentage-based width):**
 ```xml
@@ -244,7 +248,7 @@ alloy compile
 
 ---
 
-## `rounded-full` Without Size
+### `rounded-full` Without Size
 
 **❌ WRONG (rounded-full alone doesn't exist):**
 ```xml
@@ -266,7 +270,7 @@ alloy compile
 
 ---
 
-## Square Brackets for Arbitrary Values
+### Square Brackets for Arbitrary Values
 
 **❌ WRONG (Using square brackets like Tailwind CSS):**
 ```xml
@@ -288,7 +292,7 @@ alloy compile
 
 ---
 
-## Layout Defaults
+### Layout Defaults
 
 **❌ WRONG (Explicit composite class):**
 ```xml
@@ -318,18 +322,76 @@ alloy compile
 
 ---
 
-## Quick Reference Table
-
-| Anti-Pattern          | Why It Fails             | Correct Approach         |
-| --------------------- | ------------------------ | ------------------------ |
-| `flex-row`            | Flexbox not supported    | `horizontal`             |
-| `flex-col`            | Flexbox not supported    | `vertical`               |
-| `justify-*`           | Flexbox not supported    | Use margins/positioning  |
-| `items-center`        | Flexbox mental model     | Use layout + positioning |
-| `p-4` on View         | No padding on containers | `m-4` on children        |
-| `w-full`              | Percentage-based         | `w-screen` (Ti.UI.FILL)  |
-| `rounded-full`        | Needs size suffix        | `rounded-full-12`        |
-| `composite` class     | Already default          | Omit it                  |
-| `w-[100px]`           | Wrong syntax             | `w-(100px)`              |
-| Manual `.tss`         | Overwritten by PurgeTSS  | Use utility classes      |
-| `gap` with `%` widths | Total exceeds 100%       | Use explicit margins     |
+### ScrollView Without `content-w-screen` / `content-h-auto`
+
+**WRONG (ScrollView with children that overflow horizontally or never scroll vertically):**
+```xml
+<ScrollView class="w-screen h-screen">
+  <View class="vertical">
+    <Label text="Very long content..." />
+    <!-- many items -->
+  </View>
+</ScrollView>
+```
+
+**CORRECT (Explicit content sizing on the ScrollView itself):**
+```xml
+<ScrollView class="w-screen h-screen content-w-screen content-h-auto">
+  <View class="vertical">
+    <Label text="Very long content..." />
+    <!-- many items -->
+  </View>
+</ScrollView>
+```
+
+**Why:** `content-w-screen` sets `contentWidth: Ti.UI.FILL` so the scroll area matches the viewport horizontally; `content-h-auto` sets `contentHeight: Ti.UI.SIZE` so vertical scroll expands to fit children. Omitting these often produces a ScrollView that never scrolls or clips content unexpectedly.
+
+---
+
+### Deprecated `theme.View.DEFAULT` vs `theme.extend.View`
+
+**WRONG (old shape — deprecated in recent PurgeTSS):**
+```javascript
+// purgetss/config.cjs
+module.exports = {
+  theme: {
+    View: {
+      DEFAULT: { backgroundColor: '#ffffff' }
+    }
+  }
+}
+```
+
+**CORRECT (new `extend` shape):**
+```javascript
+// purgetss/config.cjs
+module.exports = {
+  theme: {
+    extend: {
+      View: { backgroundColor: '#ffffff' }
+    }
+  }
+}
+```
+
+**Why:** The nested `DEFAULT` key is a legacy artifact. Component-level theme overrides now live directly under `theme.extend.<Component>` and are merged with built-in defaults. Using the old shape silently produces unexpected styles on newer PurgeTSS versions.
+
+---
+
+### Quick Reference Table
+
+| Anti-Pattern                          | Why It Fails                         | Correct Approach                             |
+| ------------------------------------- | ------------------------------------ | -------------------------------------------- |
+| `flex-row`                            | Flexbox not supported                | `horizontal`                                 |
+| `flex-col`                            | Flexbox not supported                | `vertical`                                   |
+| `justify-*`                           | Flexbox not supported                | Use margins/positioning                      |
+| `items-center`                        | Flexbox mental model                 | Use layout + positioning                     |
+| `p-4` on View                         | No padding on containers             | `m-4` on children                            |
+| `w-full`                              | Percentage-based                     | `w-screen` (Ti.UI.FILL)                      |
+| `rounded-full`                        | Needs size suffix                    | `rounded-full-12`                            |
+| `composite` class                     | Already default                      | Omit it                                      |
+| `w-[100px]`                           | Wrong syntax                         | `w-(100px)`                                  |
+| Manual `.tss`                         | Overwritten by PurgeTSS              | Use utility classes                          |
+| `gap` with `%` widths                 | Total exceeds 100%                   | Use explicit margins                         |
+| ScrollView without `content-*` sizing | No/unexpected scroll                 | Add `content-w-screen` + `content-h-auto`    |
+| `theme.View.DEFAULT`                  | Legacy shape in newer PurgeTSS       | `theme.extend.View`                          |