@maccesar/titools 4.3.0 → 4.4.2

package/skills/ti-api/references/api-xml-global.md

@@ -39,8 +39,7 @@
 
 The API for this module is based on the W3C DOM specification.
 
-Android and iOS implement the [DOM Level 2](https://www.w3.org/TR/DOM-Level-2-Core/core.html) specification
-with some non-standard extensions, which are documented in the appropriate places.
+Android and iOS implement the [DOM Level 2](https://www.w3.org/TR/DOM-Level-2-Core/core.html) specification with some non-standard extensions, which are documented in the appropriate places.
 
 Both iOS and Android lack DTD support.
 
@@ -59,8 +58,7 @@ Both iOS and Android lack DTD support.
 > Extends Ti.XML.Node
 > Platforms: both
 
-Implements the [DOM Level 2 API](https://www.w3.org/TR/DOM-Level-2-Core/core.html#ID-637646024) on
-Android and iOS.
+Implements the [DOM Level 2 API](https://www.w3.org/TR/DOM-Level-2-Core/core.html#ID-637646024) on Android and iOS.
 
 ### Properties (unique: 4/35)
 | Property | Type | Default | Platform | Description |
@@ -80,8 +78,7 @@ Android and iOS.
 > Extends Ti.XML.Text
 > Platforms: both
 
-Implements the [DOM Level 2 API](https://www.w3.org/TR/DOM-Level-2-Core/core.html#ID-667469212) on
-Android and iOS with some non-standard extensions.
+Implements the [DOM Level 2 API](https://www.w3.org/TR/DOM-Level-2-Core/core.html#ID-667469212) on Android and iOS with some non-standard extensions.
 
 
 
@@ -117,8 +114,7 @@ Android and iOS with some non-standard extensions.
 > Extends Ti.XML.CharacterData
 > Platforms: both
 
-Implements the [DOM Level 2 API](https://www.w3.org/TR/DOM-Level-2-Core/core.html#ID-1728279322) on
-Android and iOS with some non-standard extensions.
+Implements the [DOM Level 2 API](https://www.w3.org/TR/DOM-Level-2-Core/core.html#ID-1728279322) on Android and iOS with some non-standard extensions.
 
 
 
@@ -146,12 +142,9 @@ Android and iOS with some non-standard extensions.
 > Extends Ti.XML.Node
 > Platforms: both
 
-Implements the [DOM Level 2 API](https://www.w3.org/TR/DOM-Level-2-Core/core.html#i-Document) on
-Android and iOS.
+Implements the [DOM Level 2 API](https://www.w3.org/TR/DOM-Level-2-Core/core.html#i-Document) on Android and iOS.
 
-As of version 3.1, Android does not truly support DTDs.  A document with a DTD can be
-parsed, however it is not validated, its default attributes are not be automatically
-added into the DOM tree, and so on.
+As of version 3.1, Android does not truly support DTDs.  A document with a DTD can be parsed, however it is not validated, its default attributes are not be automatically added into the DOM tree, and so on.
 
 This has been reported as [Android Issue #7395](http://code.google.com/p/android/issues/detail?id=7395).
 
@@ -189,11 +182,9 @@ This has been reported as [Android Issue #7395](http://code.google.com/p/android
 > Extends Ti.XML.Node
 > Platforms: both
 
-When a `DocumentFragment` is inserted into a DOM tree, children of the `DocumentFragment` are
-added, not the `DocumentFragment` itself.
+When a `DocumentFragment` is inserted into a DOM tree, children of the `DocumentFragment` are added, not the `DocumentFragment` itself.
 
-Implements the [DOM Level 2 API](https://www.w3.org/TR/DOM-Level-2-Core/core.html#ID-B63ED1A3) on
-Android and iOS with some non-standard extensions.
+Implements the [DOM Level 2 API](https://www.w3.org/TR/DOM-Level-2-Core/core.html#ID-B63ED1A3) on Android and iOS with some non-standard extensions.
 
 
 
@@ -205,12 +196,9 @@ Android and iOS with some non-standard extensions.
 > Extends Ti.XML.Node
 > Platforms: both
 
-This provides an interface to the list of entities that are defined for the document. Implements the
-[DOM Level 2 API](https://www.w3.org/TR/DOM-Level-2-Core/core.html#ID-412266927) on Android and iOS.
+This provides an interface to the list of entities that are defined for the document. Implements the [DOM Level 2 API](https://www.w3.org/TR/DOM-Level-2-Core/core.html#ID-412266927) on Android and iOS.
 
-As of version 3.1, Android still does not truly support DTDs.  A document with a DTD can be
-parsed, however it is not validated, none of its default attributes will automatically be put
-into the tree, etc.  [Google is aware of the issue](http://code.google.com/p/android/issues/detail?id=7395).
+As of version 3.1, Android still does not truly support DTDs.  A document with a DTD can be parsed, however it is not validated, none of its default attributes will automatically be put into the tree, etc.  [Google is aware of the issue](http://code.google.com/p/android/issues/detail?id=7395).
 
 ### Properties (unique: 6/37)
 | Property | Type | Default | Platform | Description |
@@ -284,8 +272,7 @@ into the tree, etc.  [Google is aware of the issue](http://code.google.com/p/and
 > Extends Ti.XML.Node
 > Platforms: both
 
-Implements the [DOM Level 2 API](https://www.w3.org/TR/DOM-Level-2-Core/core.html#ID-11C98490)
-on Android and iOS.
+Implements the [DOM Level 2 API](https://www.w3.org/TR/DOM-Level-2-Core/core.html#ID-11C98490) on Android and iOS.
 
 
 
@@ -322,13 +309,9 @@ on Android and iOS.
 > Extends Ti.Proxy
 > Platforms: both
 
-Implements the [DOM Level 2 API](https://www.w3.org/TR/DOM-Level-2-Core/core.html#ID-1950641247)
-on Android and iOS.
+Implements the [DOM Level 2 API](https://www.w3.org/TR/DOM-Level-2-Core/core.html#ID-1950641247) on Android and iOS.
 
-Note that on iOS, only [Element](Titanium.XML.Element) nodes are mutable. This means
-that the methods `appendChild`, `insertBefore`, `removeChild`, and
-`replaceChild` only work on `Element` objects. If one of these methods is called on
-another type of node, it throws an exception.
+Note that on iOS, only [Element](Titanium.XML.Element) nodes are mutable. This means that the methods `appendChild`, `insertBefore`, `removeChild`, and `replaceChild` only work on `Element` objects. If one of these methods is called on another type of node, it throws an exception.
 
 ### Properties (unique: 16/31)
 | Property | Type | Default | Platform | Description |
@@ -461,13 +444,11 @@ Titanium provides a number of global built-in objects, detailed below.
 
 ### String Utilities
 
-Titanium includes several extra utility functions for formatting text, attached to the
-global [String](Global.String) object.
+Titanium includes several extra utility functions for formatting text, attached to the global [String](Global.String) object.
 
 ### console
 
-Titanium provides [console](Global.Console) support familiar to many JavaScript developers
-for logging at the toplevel, in addition to the [Titanium](Titanium.API) logging facilities.
+Titanium provides [console](Global.Console) support familiar to many JavaScript developers for logging at the toplevel, in addition to the [Titanium](Titanium.API) logging facilities.
 
 ### Timers
 
@@ -551,13 +532,9 @@ Titanium has built-in support for one-off and repeating timers:
 > Platforms: both
 > Type: module
 
-The toplevel `console` support is intended to supplement <Titanium.API>
-and make it easier for developers to port existing JavaScript code
-(especially CommonJS modules) to Titanium.
+The toplevel `console` support is intended to supplement <Titanium.API> and make it easier for developers to port existing JavaScript code (especially CommonJS modules) to Titanium.
 
-Note that `console` does not currently implement the complete
-[Console](https://developer.mozilla.org/de/docs/Web/API/Console) specification.
-See the following supported methods for details and submit a pull request to add more!
+Note that `console` does not currently implement the complete [Console](https://developer.mozilla.org/de/docs/Web/API/Console) specification. See the following supported methods for details and submit a pull request to add more!
 
 
 ### Methods (15)
@@ -588,11 +565,9 @@ See the following supported methods for details and submit a pull request to add
 > Platforms: both
 > Type: module
 
-Provides support for localized number formatting, date/time formatting,
-and language sensitive string comparisons.
+Provides support for localized number formatting, date/time formatting, and language sensitive string comparisons.
 
-For more detail, see the MDN website about
-[Intl](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl).
+For more detail, see the MDN website about [Intl](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl).
 
 
 ### Methods (1)
@@ -611,8 +586,7 @@ For more detail, see the MDN website about
 
 A collator is used to perform a localized string compare or sort using a given language locale.
 
-For more detail, see the MDN website about
-[Intl.Collator](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator).
+For more detail, see the MDN website about [Intl.Collator](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator).
 
 ### Properties (unique: 1/1)
 | Property | Type | Default | Platform | Description |
@@ -650,13 +624,9 @@ For more detail, see the MDN website about
 > Platforms: both
 > Type: module
 
-A `DateTimeFormat` object is used to format a `Date` object to a localized date and/or time string.
-This will respect the system's current language setting when outputting a full month or weekday name.
-It will also respect the current locale's date component ordering such as Month/Day/Year,
-Day/Month/Year, and Year/Month/Day.
+A `DateTimeFormat` object is used to format a `Date` object to a localized date and/or time string. This will respect the system's current language setting when outputting a full month or weekday name. It will also respect the current locale's date component ordering such as Month/Day/Year, Day/Month/Year, and Year/Month/Day.
 
-For more detail, see the MDN website about
-[Intl.DateTimeFormat](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat).
+For more detail, see the MDN website about [Intl.DateTimeFormat](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat).
 
 ### Properties (unique: 1/1)
 | Property | Type | Default | Platform | Description |
@@ -707,13 +677,9 @@ For more detail, see the MDN website about
 > Platforms: both
 > Type: module
 
-A `NumberFormat` object is used to convert a `Number` value to a localized numeric string.
-It provides various formatting options controlling the number of integer and fractional digits
-to be displayed. It can also output currency values, percentage based values, and
-scientific notation.
+A `NumberFormat` object is used to convert a `Number` value to a localized numeric string. It provides various formatting options controlling the number of integer and fractional digits to be displayed. It can also output currency values, percentage based values, and scientific notation.
 
-For more detail, see the MDN website about
-[Intl.NumberFormat](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat).
+For more detail, see the MDN website about [Intl.NumberFormat](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat).
 
 ### Properties (unique: 1/1)
 | Property | Type | Default | Platform | Description |
@@ -756,8 +722,7 @@ For more detail, see the MDN website about
 > Platforms: both
 > Type: module
 
-This module contains Titanium-only extensions for formatting data into locale-specific strings. 
-The target locale is configured by the user in the device's system Settings.
+This module contains Titanium-only extensions for formatting data into locale-specific strings. The target locale is configured by the user in the device's system Settings.
 
 
 ### Methods (5)

package/skills/ti-expert/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ti-expert
-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."
+description: "Use when designing, reviewing, auditing, or analyzing Titanium SDK architecture and implementation (Alloy or Classic) — creating controllers/views/services, choosing models vs collections, deciding between app-owned and system UI, designing reusable Widgets or feedback/modality patterns, hunting memory leaks and cleanup gaps, testing, migrating legacy apps, building adaptive layouts for tablets, foldables and large screens, or moving documents in and out of the app: custom file types, UTIs, CFBundleDocumentTypes, Android intent filters, AirDrop/Quick Share, document icons, sharing a link or file via the iOS share sheet or Android intent chooser. AUTO-DETECT: If tiapp.xml exists, invoke BEFORE architectural decisions, new controllers/views, feedback components, or restructuring. Titanium navigation, memory, event, and modal patterns differ from web frameworks."
 argument-hint: "[architecture-topic]"
 allowed-tools: Read, Grep, Glob, Edit, Write, Bash(git *), Bash(node *)
 ---
@@ -9,6 +9,25 @@ allowed-tools: Read, Grep, Glob, Edit, Write, Bash(git *), Bash(node *)
 
 Practical architecture and implementation guidance for Titanium SDK apps (Alloy and Classic). Focus on maintainability, clear boundaries, and low-friction testing.
 
+## Required workflow
+
+This file is an index. Read the references that govern the task before making a recommendation or changing code.
+
+| Task | Required reading |
+| --- | --- |
+| Architecture tier, folders, or boundaries | [Architecture tiers](references/architecture-tiers.md), [Alloy structure](references/alloy-structure.md) |
+| Feedback, alerts, choices, or app-owned versus system UI | [Feedback surfaces](references/feedback-surfaces.md) |
+| Reusable Snackbar, Dialog, Bottom Sheet, Widget, or `<Require>` | [Feedback Widget contracts](references/feedback-widget-contracts.md), [Alloy structure](references/alloy-structure.md) |
+| Migrating native dialogs, Toasts, or local overlays | [Feedback migration](references/feedback-migration.md), [Migration patterns](references/migration-patterns.md) |
+| Theme or dark mode | [Theming](references/theming.md); if PurgeTSS is detected, invoke the `purgetss` skill before styling |
+| Tablet, foldable, large screen, or responsive behavior | [Adaptive layouts](references/adaptive-layouts.md) |
+| Opening or receiving files: custom extensions, UTIs, intent filters, AirDrop, Quick Share, document icons | [File type association](references/file-type-association.md) |
+| Sending content out: share sheet, intent chooser, sharing a link or a file, `dk.napp.social`, `com.alcoapps.socialshare` | [Sharing content out](references/sharing.md) |
+| Security architecture | [Security fundamentals](references/security-fundamentals.md), [Device security](references/security-device.md) |
+| Testing or performance | Load the matching guide under Quality & Performance below |
+
+Support recommendations with `[source: references/<file>.md]`. If a claim cannot be verified from the loaded references or inspected project, prefix it with `FROM_MEMORY (unverified):` and do not present it as a settled project fact.
+
 ## Project detection
 
 > **️ℹ️ Auto-detects Alloy vs Classic projects**
@@ -33,9 +52,10 @@ Practical architecture and implementation guidance for Titanium SDK apps (Alloy
 1. Architecture: define structure by technical type with flat folders (`lib/api`, `lib/services`, `lib/actions`, `lib/repositories`, `lib/helpers`)
 2. Data strategy: choose Models (SQLite) or Collections (API)
 3. Contracts: define I/O specs between layers
-4. Implementation: write XML views and ES6+ controllers
-5. Quality: testing, error handling, logging, performance
-6. Cleanup: implement a `cleanup()` pattern for memory management
+4. UI ownership: classify app-owned feedback, screen state, and system-owned flows
+5. Implementation: write XML views and ES6+ controllers
+6. Quality: testing, error handling, logging, performance
+7. Cleanup: implement a `cleanup()` pattern for memory management
 
 ## Architectural Maturity Tiers
 
@@ -84,6 +104,8 @@ Detailed examples and full implementation samples are available in: [Architectur
 
 ## Titanium style sheets rules (low freedom)
 
+Before styling, detect `purgetss/` or `purgetss/config.cjs`. If present, invoke the `purgetss` skill, verify every utility, and never edit the generated `app/styles/app.tss`. Without PurgeTSS, use standard Alloy TSS files. In either case, keep behavior in XML/controllers and use semantic colors for app-owned surfaces when the project supports them.
+
 > **🚨 Critical: platform-specific properties require modifiers**
 > Using `Ti.UI.iOS.*` or `Ti.UI.Android.*` properties without platform modifiers breaks cross-platform builds.
 >
@@ -138,7 +160,10 @@ For the complete reference with examples, see [Alloy builtins and globals](refer
 | Models or Collections?             | Collections for API data, Models for SQLite persistence        |
 | Ti.App.fireEvent or EventBus?      | Always EventBus (Backbone.Events)                              |
 | Direct navigation or service?      | Always Navigation service (auto cleanup)                       |
-| Inline styles or TSS files?        | Always TSS files (per-controller + `app.tss` for global)       |
+| Snackbar, Dialog, or Bottom Sheet? | Classify urgency, persistence, reversibility, and choice first |
+| Widget or `<Require>`?             | Widget for a self-contained API/lifecycle; `<Require>` for app composition |
+| App-owned or native UI?            | Keep OS trust/protected flows native; style app-owned feedback |
+| Inline styles or style system?     | PurgeTSS utilities when detected; otherwise Alloy TSS          |
 
 ## Reference guides (progressive disclosure)
 
@@ -155,6 +180,11 @@ For the complete reference with examples, see [Alloy builtins and globals](refer
 - [Alloy Builtins & Globals](references/alloy-builtins.md)
 - [Code Conventions](references/code-conventions.md)
 - [Controller Patterns](references/controller-patterns.md)
+- [File Type Association](references/file-type-association.md) (custom extensions and UTIs, `CFBundleDocumentTypes`, Android intent filters, receiving files from AirDrop/Quick Share, document icons)
+- [Sharing Content Out](references/sharing.md) (share sheet and intent chooser, why iOS still needs `dk.napp.social` and Android does not, text versus file, iPad popovers)
+- [Feedback Surfaces & App-Owned UI](references/feedback-surfaces.md)
+- [Feedback Widget Contracts](references/feedback-widget-contracts.md)
+- [Feedback Migration](references/feedback-migration.md)
 - [Theming & Dark Mode](references/theming.md)
 - [Migration Patterns](references/migration-patterns.md)
 - [Examples Collection](references/examples.md)

package/skills/ti-expert/references/adaptive-layouts.md

@@ -35,9 +35,7 @@ What this means: portrait-only apps will be forced into landscape/resized on lar
 
 ### It already started in Android 16 (API 36)
 
-This is usually described as an API 37 change, but it lands one release earlier: an app
-targeting **API 36** already has `android:screenOrientation` ignored on >= 600dp displays
-running Android 16. The difference is that API 36 still ships an opt-out:
+This is usually described as an API 37 change, but it lands one release earlier: an app targeting **API 36** already has `android:screenOrientation` ignored on >= 600dp displays running Android 16. The difference is that API 36 still ships an opt-out:
 
 ```xml
 <!-- inside <application>, or on an individual <activity> -->
@@ -46,12 +44,9 @@ running Android 16. The difference is that API 36 still ships an opt-out:
   android:value="true"/>
 ```
 
-The opt-out stops working the moment you target API 37, so treat it as a bridge while the
-layout is made adaptive — not as a fix. Source: [Android 16 behavior changes](https://developer.android.com/about/versions/16/behavior-changes-16).
+The opt-out stops working the moment you target API 37, so treat it as a bridge while the layout is made adaptive — not as a fix. Source: [Android 16 behavior changes](https://developer.android.com/about/versions/16/behavior-changes-16).
 
-Worth knowing when debugging: this only kicks in at >= 600dp. If a **phone** is rotating
-despite a portrait lock, the cause is in the app, not in Android — see the orientation
-debugging recipe in section 7.
+Worth knowing when debugging: this only kicks in at >= 600dp. If a **phone** is rotating despite a portrait lock, the cause is in the app, not in Android — see the orientation debugging recipe in section 7.
 
 ### Related: edge-to-edge (API 36)
 
@@ -429,9 +424,7 @@ To verify the exact generated activity name, check `build/android/app/src/main/A
 
 ### Which activities a lock has to cover
 
-`android:screenOrientation` is per-activity — it is not inherited from `<application>`. Every
-window the app opens runs inside one of a small, fixed set of activities declared by the
-Titanium AAR, so read the canonical list from the SDK instead of memorising it:
+`android:screenOrientation` is per-activity — it is not inherited from `<application>`. Every window the app opens runs inside one of a small, fixed set of activities declared by the Titanium AAR, so read the canonical list from the SDK instead of memorising it:
 
 ```bash
 cat ~/.gradle/caches/*/transforms/*/transformed/jetified-titanium-*/AndroidManifest.xml
@@ -448,8 +441,7 @@ ti.modules.titanium.media.TiVideoActivity
 ti.modules.titanium.ui.android.TiPreferencesActivity
 ```
 
-The seventh is the app's own root activity, generated from the `<name>` in tiapp.xml (see the
-derivation rule above). Which one hosts what:
+The seventh is the app's own root activity, generated from the `<name>` in tiapp.xml (see the derivation rule above). Which one hosts what:
 
 | What the app does | Activity |
 |---|---|
@@ -461,23 +453,12 @@ derivation rule above). Which one hosts what:
 
 Two things are better left undeclared:
 
-- **`android:configChanges`.** The CLI strips it before the merge even happens — `_build.js`
-  keeps a list of the `TiBaseActivity`-derived activities and calls
-  `removeActivityAttribute(name, 'android:configChanges')` on each, with the reason spelled out
-  in the source: *"Most devs don't set this right, causing UI to disappear when a config change
-  occurs for a missing setting."* So a hand-written subset is not dangerous, just dead weight —
-  Titanium's full list always wins.
-- **A lock on `TiTranslucentActivity`.** Android 8–11 throws `IllegalStateException` ("Only
-  fullscreen opaque activities can request orientation") when a translucent activity requests a
-  fixed orientation. Declaring `orientationModes` on those windows is safer: the SDK applies it
-  inside a try/catch (`TiWindowProxy.setOrientationModes`), so the worst case is a modal that
-  rotates instead of an app that crashes.
+- **`android:configChanges`.** The CLI strips it before the merge even happens — `_build.js` keeps a list of the `TiBaseActivity`-derived activities and calls `removeActivityAttribute(name, 'android:configChanges')` on each, with the reason spelled out in the source: *"Most devs don't set this right, causing UI to disappear when a config change occurs for a missing setting."* So a hand-written subset is not dangerous, just dead weight — Titanium's full list always wins.
+- **A lock on `TiTranslucentActivity`.** Android 8–11 throws `IllegalStateException` ("Only fullscreen opaque activities can request orientation") when a translucent activity requests a fixed orientation. Declaring `orientationModes` on those windows is safer: the SDK applies it inside a try/catch (`TiWindowProxy.setOrientationModes`), so the worst case is a modal that rotates instead of an app that crashes.
 
 ### Prefer orientationModes over the manifest
 
-`orientationModes` is defined on `TiWindowProxy`, so the same declaration works on `Window`,
-`TabGroup` and `NavigationWindow`. Being per-window it also composes with form-factor queries,
-which is what you usually want:
+`orientationModes` is defined on `TiWindowProxy`, so the same declaration works on `Window`, `TabGroup` and `NavigationWindow`. Being per-window it also composes with form-factor queries, which is what you usually want:
 
 ```xml
 <!-- PurgeTSS -->
@@ -489,14 +470,11 @@ which is what you usually want:
 '#tabs[formFactor=handheld]': { orientationModes: [ Ti.UI.PORTRAIT ] }
 ```
 
-Alloy resolves `formFactor` from `Ti.Platform.Android.physicalSizeCategory`, which is why this
-is more reliable than any width comparison you could write yourself.
+Alloy resolves `formFactor` from `Ti.Platform.Android.physicalSizeCategory`, which is why this is more reliable than any width comparison you could write yourself.
 
-Keep the manifest for what Alloy cannot reach: the root activity, which shows the splash before
-any JS runs, and optionally `TiActivity` as a blanket fallback for windows that carry no class.
+Keep the manifest for what Alloy cannot reach: the root activity, which shows the splash before any JS runs, and optionally `TiActivity` as a blanket fallback for windows that carry no class.
 
-A single Ti Element rule covers every window in the app without touching a single view, which
-is usually all an Alloy app needs:
+A single Ti Element rule covers every window in the app without touching a single view, which is usually all an Alloy app needs:
 
 ```javascript
 // purgetss/config.cjs
@@ -511,8 +489,7 @@ module.exports = {
 'Window[formFactor=handheld]': { orientationModes: [ Ti.UI.PORTRAIT ] }
 ```
 
-Note it matches `Window` only, so a `TabGroup` still needs its own class. And because the
-declaration is per-window, it does nothing for the splash — that one stays in the manifest.
+Note it matches `Window` only, so a `TabGroup` still needs its own class. And because the declaration is per-window, it does nothing for the splash — that one stays in the manifest.
 
 ### Debugging a rotation that shouldn't happen
 
@@ -522,13 +499,9 @@ Ask the system for the effective value instead of re-reading the manifest:
 adb shell dumpsys activity activities | grep -E "topResumedActivity|requestedOrientation"
 ```
 
-If `requestedOrientation` disagrees with what tiapp.xml declares, something overrode it at
-runtime — grep the app for `requestedOrientation` and `orientationModes` before touching the
-manifest again. Note that an *existing* `orientationModes` can be the bug rather than the fix:
-an empty array unlocks rotation (see the anti-patterns above).
+If `requestedOrientation` disagrees with what tiapp.xml declares, something overrode it at runtime — grep the app for `requestedOrientation` and `orientationModes` before touching the manifest again. Note that an *existing* `orientationModes` can be the bug rather than the fix: an empty array unlocks rotation (see the anti-patterns above).
 
-Before blaming the OS, let the SDK tell you. Titanium logs a warning when Android drops the
-request on a large screen, so this either hits or rules that cause out immediately:
+Before blaming the OS, let the SDK tell you. Titanium logs a warning when Android drops the request on a large screen, so this either hits or rules that cause out immediately:
 
 ```bash
 adb logcat | grep "Orientation request will be ignored"
@@ -536,8 +509,7 @@ adb logcat | grep "Orientation request will be ignored"
 # Orientation request will be ignored on Android 16+.
 ```
 
-And to see the size bucket the device actually reports — `normal` means a phone, so the >= 600dp
-rule does not apply and the cause is in the app:
+And to see the size bucket the device actually reports — `normal` means a phone, so the >= 600dp rule does not apply and the cause is in the app:
 
 ```bash
 adb shell am get-config    # e.g. ...-sw360dp-w360dp-h802dp-normal-...

package/skills/ti-expert/references/alloy-builtins.md

@@ -75,13 +75,6 @@ Shared state and utilities accessible from any controller or lib file. Set in `a
 // alloy.js
 const Backbone = require('alloy/backbone')
 
-// --- Theme / Design Tokens ---
-Alloy.Globals.theme = {
-  primary: '#2563eb',
-  bg: '#ffffff',
-  text: '#111827'
-}
-
 // --- Device Info (cached once) ---
 Alloy.Globals.isTablet = Alloy.isTablet
 Alloy.Globals.screenWidth = Ti.Platform.displayCaps.platformWidth
@@ -100,27 +93,20 @@ Alloy.Collections.notifications = new Backbone.Collection()
 ### Access from anywhere
 
 ```javascript
-// In any controller
-const theme = Alloy.Globals.theme
-$.label.color = theme.primary
-
-// In TSS (evaluated at compile time for controller creation)
-"#header": {
-  backgroundColor: Alloy.Globals.theme.primary
-}
-
 // In XML with conditional binding
 // <View if="Alloy.Globals.isLoggedIn">
 ```
 
+Do not use `Alloy.Globals` as the default dark-mode palette. Prefer Titanium semantic colors; when PurgeTSS is detected, use its semantic color and Appearance workflow. Reserve a global runtime palette for custom theme requirements that semantic light/dark/system roles cannot model. See [Theming](theming.md).
+
 ### Globals vs services
 
-| Use `Alloy.Globals` for            | Use a Service for             |
-| ---------------------------------- | ----------------------------- |
-| Static config (theme, device info) | Business logic                |
-| Simple flags (isLoggedIn)          | Complex state with listeners  |
-| Values set once in `alloy.js`      | Values that change frequently |
-| Read-only data                     | Data with side effects        |
+| Use `Alloy.Globals` for               | Use a Service for             |
+| ------------------------------------- | ----------------------------- |
+| Immutable device/build facts          | Business logic                |
+| Framework-level shared registries     | Complex state with listeners  |
+| Values initialized once in `alloy.js` | Values that change frequently |
+| Read-only interoperability data       | Data with side effects        |
 
 ---
 

package/skills/ti-expert/references/alloy-structure.md

@@ -30,7 +30,7 @@ app/
 │   ├── home.xml
 │   └── userProfile.xml
 ├── styles/               # TSS styles (one per view + global)
-│   ├── app.tss           # Global application styles
+│   ├── app.tss           # Standard Alloy global styles or PurgeTSS generated output
 │   ├── index.tss         # Styles for index view
 │   ├── home.tss
 │   └── userProfile.tss
@@ -59,7 +59,7 @@ app/
 │   └── providers/
 │       ├── containerProvider.js
 │       └── loggerProvider.js
-├── widgets/              # Truly reusable components (used in 3+ places)
+├── widgets/              # Self-contained components with an API/lifecycle boundary
 │   └── customButton/
 ├── config.json           # Alloy configuration
 └── alloy.js              # Collections & Global services
@@ -188,7 +188,7 @@ api.getFrames()
 ## Controller rules
 
 **DO:**
-- Define styles in TSS files (per-controller + `app.tss` for global).
+- Use verified PurgeTSS utilities when detected; otherwise define styles in per-controller TSS and manually maintained global TSS.
 - Orchestrate view and model/collection interactions.
 - Handle UI events and delegate to services.
 - Format data for display (simple cases).
@@ -196,7 +196,7 @@ api.getFrames()
 - Keep `lib` modules flat and easy to locate.
 
 **DON'T:**
-- Use inline style attributes in XML (define in TSS files).
+- Scatter visual properties inline when the active style system can express them.
 - Make direct API calls (use lib/api/ or lib/services/).
 - Contain heavy business logic.
 - Call native modules directly (use a service wrapper).
@@ -245,7 +245,7 @@ See [ControllerAutoCleanup.js](../assets/ControllerAutoCleanup.js) for the compl
 
 ## Widget structure
 
-Widgets are self-contained, reusable components used in 3+ places across the app.
+Widgets are self-contained components with their own public API, state, assets, and lifecycle. Choose one for a portable boundary, not after an arbitrary number of usages. A first-use component with timers, modal state, and cleanup can merit a Widget; repeated static styling does not.
 
 ```
 app/widgets/
@@ -255,7 +255,7 @@ app/widgets/
     ├── views/
     │   └── widget.xml     # Main widget view
     ├── styles/
-    │   └── widget.tss     # Widget-specific styles
+    │   └── widget.tss     # Optional component-specific styles
     └── widget.json        # Widget manifest
 ```
 
@@ -276,6 +276,16 @@ app/widgets/
 }
 ```
 
+Register the Widget in the app's `app/config.json`; the dependency key must match the manifest `id`:
+
+```json
+{
+  "dependencies": {
+    "com.app.loadingOverlay": "1.0.0"
+  }
+}
+```
+
 ### Widget view (widget.xml)
 ```xml
 <Alloy>
@@ -290,10 +300,10 @@ app/widgets/
 
 ```tss
 /* styles/widget.tss */
-"#container": { width: Ti.UI.FILL, height: Ti.UI.FILL, visible: false, backgroundColor: 'rgba(0,0,0,0.5)' }
-"#box": { width: 128, height: 128, layout: 'vertical', borderRadius: 16, backgroundColor: '#fff' }
+"#container": { width: Ti.UI.FILL, height: Ti.UI.FILL, visible: false, backgroundColor: 'overlayColor' }
+"#box": { width: 128, height: 128, layout: 'vertical', borderRadius: 16, backgroundColor: 'surfaceColor' }
 "#spinner": { top: 24 }
-"#messageLabel": { left: 16, right: 16, top: 16, font: { fontSize: 14 }, color: '#4b5563' }
+"#messageLabel": { left: 16, right: 16, top: 16, font: { fontSize: 14 }, color: 'textColor' }
 ```
 
 ### Widget controller (widget.js)
@@ -352,8 +362,12 @@ const loadData = () => {
 }
 ```
 
-> **💡 Widget Styles**
-> Widgets have their own `styles/widget.tss` file. Define all widget-specific styles there to keep them self-contained and portable.
+> **Widget styles**
+> In a standard Alloy project, keep component-specific properties in
+> `styles/widget.tss` and consume semantic colors. If PurgeTSS is detected, load
+> its skill first, enable Widget scanning, place verified utilities in XML, and
+> reserve `widget.tss` for properties with no utility. Never edit the generated
+> `app/styles/app.tss`.
 
 ### Widget ↔ controller communication
 
@@ -464,13 +478,15 @@ render()
 
 ### When to use widget vs require
 
-| Use `<Widget>` when                   | Use `<Require>` when            |
-| ------------------------------------- | ------------------------------- |
-| Component is used in 3+ places        | Component is used in 1-2 places |
-| Needs its own self-contained styles   | Shares styles with parent       |
-| Has public API (show/hide/setValue)   | Just renders, no API needed     |
-| Could be extracted to another project | Specific to this app            |
-| Needs its own `widget.json` manifest  | Lightweight, no manifest needed |
+| Use `<Widget>` when                   | Use `<Require>` when                 |
+| ------------------------------------- | ------------------------------------ |
+| Owns a stable public API              | Composes an app-specific controller  |
+| Owns state, timers, listeners, or cleanup | Shares the host's lifecycle       |
+| Has a portable design-system boundary | Shares the host's domain and styling |
+| Could be extracted to another project | Has no independent package contract  |
+| Needs its own `widget.json` manifest  | Remains lightweight and app-local    |
+
+Usage count is supporting evidence only. Also consider a screen-local XML state for loading/empty/error content, a style class for appearance without behavior, or native UI when the operating system owns the workflow. See [Feedback Widget Contracts](feedback-widget-contracts.md).
 
 ## config.json reference