@maccesar/titools 3.1.0 → 3.3.0

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

@@ -304,6 +304,67 @@ 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.
 
+## 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).
+
+```bash
+purgetss images logo.svg --opacity 50 --format png
+```
+
+- `--opacity` accepts integers in `[0, 100]`. Out-of-range values exit immediately without writing anything (`Invalid --opacity '150'. Must be an integer between 0 and 100.`).
+- `--opacity 100` is a no-op — the compositing pass is skipped entirely.
+- `--opacity 0` produces a fully transparent output (technically valid, visually empty).
+
+### Format interactions
+
+- **PNG / WebP / AVIF:** alpha is preserved.
+- **JPEG:** JPEG has no alpha. The existing flatten-on-white step composites the semi-transparent image onto white before writing, so `--opacity 50 --format jpeg` produces a 50%-faded version **on white**, not a transparent JPEG.
+
+## Adding breathing room with `--padding` (v7.10.0)
+
+`--padding <n>` shrinks the rendered image inside each density canvas by `n%` symmetric borders. Useful when the source logo has no built-in padding and you want a placeholder with breathing room — without editing the source asset.
+
+```bash
+purgetss images purgetss/brand/logo.png --padding 15 --format png
+```
+
+Each density's output canvas keeps the same dimensions it would have without `--padding`, but the rendered image takes only `(1 − 2 × 0.15) = 70%` of that canvas (centered). The remaining 30% of the canvas (15% on each side) is transparent.
+
+- `--padding` accepts integers in `[0, 40]`. Out-of-range or negative values are rejected (`Invalid --padding '50'. Must be an integer between 0 and 40.`).
+- `--padding 0` is a no-op (skipped — no extend pass).
+
+### When *not* to use `--padding`
+
+If your source logo already has the breathing room you want baked in, you don't need `--padding` — it compounds the existing padding. Use `--padding` when:
+
+- the source is edge-to-edge (no built-in margin) and you want a centered placeholder
+- you need a fast way to produce a "loose" variant of a logo without touching the source file
+
+## Renaming the output with `--output` (v7.10.0)
+
+By default, the output basename comes from the source filename and the subfolder mirrors the source's location inside `purgetss/images/`. When you want a different output path — for example, sourcing a logo from `purgetss/brand/` and writing it as a placeholder under `images/logos/` — `--output <relpath>` overrides both:
+
+```bash
+purgetss images purgetss/brand/logo.svg --output logos/default-image
+```
+
+That writes `images/logos/default-image.png` (or `.jpg` / `.webp` depending on `--format`) across all densities, regardless of the source's location.
+
+### Combining `--opacity`, `--padding`, and `--output`
+
+The three flags compose for the canonical "transparent placeholder with padding under a custom path" use case:
+
+```bash
+purgetss images purgetss/brand/logo.svg \
+    --opacity 30 \
+    --padding 15 \
+    --output 'logos/default-image' \
+    --format png
+```
+
+Produces a 30% opacity, 15%-padded version of the brand logo at `images/logos/default-image.png` for every Android density and iPhone scale — a one-command way to ship a default ImageView placeholder.
+
 ## Full pipeline alongside `build`
 
 The typical sequence when iterating on an app:
@@ -348,6 +409,9 @@ If you only tweaked CSS classes (no image changes), you don't need to re-run `pu
 | `--format <ext>` | Convert all outputs to: `webp`, `jpeg`, `png`, `avif`, `gif`, `tiff`. Default: keep source format. |
 | `--quality <n>` | Quality `0–100` for lossy formats. Default `85`. |
 | `--width <n>` | (v7.8.0) Pin `mdpi` / `@1x` output width to `n` pixels; `[1, 8192]`. Other densities derive from this base (×1.5 / ×2 / ×3 / ×4). Most useful for SVG sources with non-standard viewBoxes. CLI-only — no `config.cjs` equivalent because width is per-asset. |
+| `--opacity <n>` | (v7.10.0) Multiply the alpha channel of every generated density by `n/100`. Range `[0, 100]`. Combine with `--format jpeg` and the alpha is flattened on white instead of producing a transparent JPEG. CLI-only. |
+| `--padding <n>` | (v7.10.0) Shrink the rendered image inside each density canvas by `n%` symmetric borders. Range `[0, 40]`. CLI-only. |
+| `--output <relpath>` | (v7.10.0) Override the basename and subpath relative to each platform's `images/` root. Lets a source from outside `purgetss/images/` (e.g. `purgetss/brand/`) write into a custom output folder like `images/logos/`. CLI-only. |
 
 **Project & output**
 
@@ -371,6 +435,11 @@ purgetss images background/pink-texture.png            # re-process one file (sh
 purgetss images background/                            # re-process one subfolder
 purgetss images --android                              # only Android densities
 purgetss images --format webp --quality 90             # convert all outputs to WebP
+purgetss images --opacity 50 --format png              # 50% alpha placeholder (v7.10.0)
+purgetss images logo.svg --padding 15 --format png     # add 15% breathing room (v7.10.0)
+purgetss images purgetss/brand/logo.svg \
+    --opacity 30 --padding 15 \
+    --output 'logos/default-image' --format png         # placeholder under custom path (v7.10.0)
 purgetss images --dry-run                              # preview
 ```
 

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

@@ -0,0 +1,59 @@
+# PurgeTSS — Version History (agent summary)
+
+Terse, agent-facing summary of changes that affect how the skill suggests utilities, configures `config.cjs`, or invokes commands. **Not** a full changelog.
+
+**Canonical source:** <https://purgetss.com/changelog> (full release notes, internal fixes, parser changes, dependency bumps).
+
+When in doubt about whether a class, flag, or config key exists in the user's installed version, consult the canonical changelog or grep `./purgetss/styles/utilities.tss` in the project.
+
+---
+
+## v7.10.2
+- Pre-v7.7.0 `brand:` configs (flat layout: `brand.padding: <number>`, `brand.iosPadding`, `brand.bgColor`, top-level `brand.notification`/`brand.splash`) auto-migrate to the grouped layout in memory. A one-time per-session notice lists the migrated keys.
+
+## v7.10.1
+- "Tailwind" framing dropped from non-functional copy (Class Syntax Error message, `purgetss create` injected Label). Functional integrations (`tailwindcss@3` dep, `shades --tailwind`, VSCode IntelliSense extension) still ship.
+
+## v7.10.0
+- `purgetss images` gains `--opacity <0-100>`, `--padding <0-40>`, `--output <relpath>`. CLI-only (no `config.cjs` equivalent). See [multi-density-images.md](multi-density-images.md).
+- `purgetss brand` generates `MarketplaceArtworkFeature.png` (1024×500 Google Play Feature Graphic). Override via `--feature-logo <path>` or `--feature-graphic-padding <n>` (default 12%). See [app-branding.md](app-branding.md).
+- `theme` objects in `config.cjs` walk recursively at any depth — `theme.extend.colors.brand.primary.500` flattens to class `bg-brand-primary-500`. Default modifier keys (`default`, `global`, `DEFAULT`) collapse. Same for `backgroundGradient` / `backgroundSelectedGradient`. See [arbitrary-values.md](arbitrary-values.md).
+- Fix: `apply:` now resolves built-in icon font classes (`fas`, `fab`, `fa-*`, `mi-*`, `ms-*`, `f7-*`) from `dist/` even without `build-fonts`.
+- Fix: `brand --padding <n>` shortcut applies to BOTH Android paddings.
+
+## v7.9.0
+- Opacity modifiers work on semantic colors: `bg-surface/65` auto-derives `surface_65` in `semantic.colors.json` with light/dark + alpha. **Native rebuild required** (Liveview alone does not refresh `semantic.colors.json`). See [semantic-colors.md](semantic-colors.md).
+- `theme.Window` / `theme.View` / `theme.ImageView` at top level = **replace mode** (no framework defaults). Use `theme.extend.Window` for **extend mode** (merge with defaults). See [apply-directive.md](apply-directive.md).
+- **Breaking:** glossary path renamed `purgetss/experimental/tailwind-classes/` → `purgetss/glossary/tailwind-classes/`. No transition shim.
+
+## v7.8.0
+- `purgetss images --width <n>` pins Android `mdpi` / iPhone `@1x` to `<n>` pixels for SVG sources with disproportionate viewBoxes (Affinity, Illustrator). CLI-only.
+- Class syntax pre-validation emits `Class Syntax Error` blocks for 5 patterns: inverted negative (`top-(-10)` → `-top-(10)`), brackets (`top-[10px]` → `top-(10px)`), empty parens (`wh-()`), whitespace in parens, redundant `px` unit. Generic unknown classes still flow into `// Unused or unsupported classes`.
+
+## v7.7.0
+- `brand:` config restructured into grouped sections: `brand.logos`, `brand.padding`, `brand.android`, `brand.ios`, `brand.colors`. Old projects keep working; new configs use grouped form. See [app-branding.md](app-branding.md).
+- Separate Android brand inputs: `logos.androidLauncher` / `--icon-logo` and `logos.androidSplash` / `--splash-logo`.
+- Android splash fallback `default.png` regenerated (Alloy: `app/assets/android/`, Classic: `Resources/android/`). `cleanup-legacy` preserves it.
+- New ref: [values-and-units.md](values-and-units.md) — `ti.ui.defaultunit` interpretation of unitless PurgeTSS values.
+
+## v7.6.x
+- `purgetss brand` (v7.6.0) — full Titanium branding set from `purgetss/brand/` logos. See [app-branding.md](app-branding.md).
+- `purgetss images` (v7.6.0) — multi-density UI images (Android `res-*` + iPhone `@1x`/`@2x`/`@3x`). See [multi-density-images.md](multi-density-images.md).
+- `purgetss semantic` (v7.6.0) — Titanium semantic colors for Light/Dark, palette mode or `--single` purpose-based. Classic projects supported since v7.6.2. See [semantic-colors.md](semantic-colors.md).
+- `brand:` and `images:` config sections auto-injected. Percentages may be quoted strings (`'15%'`) or plain numbers.
+- `brand` / `images` ask `[y/N/a]` before overwriting (skip with `-y`, `PURGETSS_YES=1`, or non-TTY) (v7.6.1).
+
+## v7.5.3
+- `Appearance` module — Light/Dark/System mode switching with persistence (`init()`, `set()`, `get()`, `toggle()`). See [appearance-module.md](appearance-module.md).
+- Default font family classes (`font-sans`, `font-serif`, `font-mono`) auto-generated with platform-appropriate values.
+
+## v7.5.0
+- `theme.extend.Window` / `theme.extend.View` / `theme.extend.ImageView` — customize Ti element defaults.
+- Shorthand `apply:` directive — `{ apply: '...' }` auto-normalizes; `default:` wrapper optional.
+- Apply directive property deduplication — applied values win over static defaults.
+- Automatic platform resolution inside `ios:` / `android:` blocks.
+
+## v7.4.0
+- Animation module: 9 new methods (`transition`, `pulse`, `sequence`, `swap`, `shake`, `snapTo`, `reorder`, `undraggable`, `detectCollisions`). 15 methods total. See [animation-system.md](animation-system.md).
+- New utility classes: `snap-back`, `snap-center`, `snap-magnet`, `keep-z-index`.
+- Delta-based drag for transformed views; property inheritance from Animation object.

package/skills/ti-expert/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ti-expert
-description: "Titanium SDK architecture and implementation expert. Use when designing, reviewing, analyzing, or examining Titanium project structure (Alloy or Classic), creating controllers/views/services, choosing models vs collections, implementing communication patterns, handling memory cleanup, testing, auditing code, migrating legacy apps, or building adaptive/responsive layouts for tablets, foldables, and large screens. AUTO-DETECT: If tiapp.xml exists, invoke this skill BEFORE making architectural decisions, creating new controllers/views, or restructuring code. Titanium has its own patterns for navigation (NavigationWindow, TabGroup), memory management, and event handling that differ from web frameworks."
+description: "Use when designing, reviewing, analyzing, or examining Titanium SDK architecture and implementation (Alloy or Classic) — creating controllers/views/services, choosing models vs collections, implementing communication patterns, handling memory cleanup, testing, auditing code, migrating legacy apps, or building adaptive/responsive layouts for tablets, foldables, and large screens. AUTO-DETECT: If tiapp.xml exists, invoke BEFORE making architectural decisions, creating new controllers/views, or restructuring code. Titanium has its own patterns for navigation (NavigationWindow, TabGroup), memory management, and event handling that differ from web frameworks."
 argument-hint: "[architecture-topic]"
 allowed-tools: Read, Grep, Glob, Edit, Write, Bash(git *), Bash(node *)
 ---

package/skills/ti-ui/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ti-ui
-description: "Titanium SDK UI/UX patterns and components expert. Use when working with, reviewing, analyzing, or examining Titanium layouts, ListView/TableView performance optimization, event handling and bubbling, gestures (swipe, pinch), animations, accessibility (VoiceOver/TalkBack), orientation changes, custom fonts/icons, app icons/splash screens, or platform-specific UI (Action Bar, Navigation Bar). AUTO-DETECT: If tiapp.xml exists, invoke this skill BEFORE creating or modifying any UI view, window, or layout. Titanium layouts (composite, vertical, horizontal) differ from web/CSS — never assume web layout behavior."
+description: "Use when working with, reviewing, analyzing, or examining Titanium SDK UI/UX patterns and components — Titanium layouts, ListView/TableView performance optimization, event handling and bubbling, gestures (swipe, pinch), animations, accessibility (VoiceOver/TalkBack), orientation changes, custom fonts/icons, app icons/splash screens, or platform-specific UI (Action Bar, Navigation Bar). AUTO-DETECT: If tiapp.xml exists, invoke BEFORE creating or modifying any UI view, window, or layout. Titanium layouts (composite, vertical, horizontal) differ from web/CSS — never assume web layout behavior."
 argument-hint: "[component]"
 allowed-tools: Read, Grep, Glob, Edit, Write, Bash(node *)
 ---