@maccesar/titools 4.1.0 → 4.4.0

package/skills/ti-api/references/api-ui-extras.md

@@ -1,5 +1,24 @@
 # Ti.UI Extras API Reference
 
+<!-- TOC-START -->
+## Contents
+
+- [Ti.UI.Animation](#tiuianimation)
+- [Ti.UI.Matrix2D](#tiuimatrix2d)
+- [Ti.UI.Matrix3D](#tiuimatrix3d)
+- [Ti.UI.WebView](#tiuiwebview)
+- [Ti.UI.Toolbar](#tiuitoolbar)
+- [Ti.UI.ButtonBar](#tiuibuttonbar)
+- [Ti.UI.TabbedBar](#tiuitabbedbar)
+- [Ti.UI.OptionBar](#tiuioptionbar)
+- [Ti.UI.Shortcut](#tiuishortcut)
+- [Ti.UI.ShortcutItem](#tiuishortcutitem)
+- [Ti.UI.EmailDialog](#tiuiemaildialog)
+- [Ti.UI.DashboardView](#tiuidashboardview)
+- [Ti.UI.DashboardItem](#tiuidashboarditem)
+
+<!-- TOC-END -->
+
 ## Ti.UI.Animation
 > The `Animation` object defines an animation that can be applied to a view.
 > Extends Ti.Proxy
@@ -523,7 +542,6 @@ Google documents how to add static shortcuts
 [here](https://developer.android.com/guide/topics/ui/shortcuts/creating-shortcuts#static).
 
 In the `tiapp.xml` file, you will need to add a shortcuts `<meta-data/>` element to your main activity.
-``` xml
 
 ### Properties (unique: 6/9)
 | Property | Type | Default | Platform | Description |

package/skills/ti-api/references/api-ui-ios-animator.md

@@ -1,5 +1,19 @@
 # Ti.UI.iOS Animator & Physics API Reference
 
+<!-- TOC-START -->
+## Contents
+
+- [Ti.UI.iOS.AnchorAttachmentBehavior](#tiuiiosanchorattachmentbehavior)
+- [Ti.UI.iOS.Animator](#tiuiiosanimator)
+- [Ti.UI.iOS.CollisionBehavior](#tiuiioscollisionbehavior)
+- [Ti.UI.iOS.DynamicItemBehavior](#tiuiiosdynamicitembehavior)
+- [Ti.UI.iOS.GravityBehavior](#tiuiiosgravitybehavior)
+- [Ti.UI.iOS.PushBehavior](#tiuiiospushbehavior)
+- [Ti.UI.iOS.SnapBehavior](#tiuiiossnapbehavior)
+- [Ti.UI.iOS.ViewAttachmentBehavior](#tiuiiosviewattachmentbehavior)
+
+<!-- TOC-END -->
+
 ## Ti.UI.iOS.AnchorAttachmentBehavior
 > Dynamic behavior to support connections between an anchor point and an item.
 > Extends Ti.Proxy

package/skills/ti-api/references/api-ui-ios.md

@@ -1,5 +1,47 @@
 # Ti.UI.iOS API Reference
 
+<!-- TOC-START -->
+## Contents
+
+- [Ti.UI.iOS](#tiuiios)
+- [Ti.UI.iOS.AlertDialogStyle](#tiuiiosalertdialogstyle)
+- [Ti.UI.iOS.AnimationStyle](#tiuiiosanimationstyle)
+- [Ti.UI.iOS.ApplicationShortcuts](#tiuiiosapplicationshortcuts)
+- [Ti.UI.iOS.BlurView](#tiuiiosblurview)
+- [Ti.UI.iOS.ButtonConfiguration](#tiuiiosbuttonconfiguration)
+- [Ti.UI.iOS.CoverFlowView](#tiuiioscoverflowview)
+- [Ti.UI.iOS.DocumentViewer](#tiuiiosdocumentviewer)
+- [Ti.UI.iOS.FeedbackGenerator](#tiuiiosfeedbackgenerator)
+- [Ti.UI.iOS.ListViewCellSelectionStyle](#tiuiioslistviewcellselectionstyle)
+- [Ti.UI.iOS.ListViewScrollPosition](#tiuiioslistviewscrollposition)
+- [Ti.UI.iOS.ListViewStyle](#tiuiioslistviewstyle)
+- [Ti.UI.iOS.LivePhoto](#tiuiioslivephoto)
+- [Ti.UI.iOS.LivePhotoView](#tiuiioslivephotoview)
+- [Ti.UI.iOS.MenuPopup](#tiuiiosmenupopup)
+- [Ti.UI.iOS.NavigationWindow](#tiuiiosnavigationwindow)
+- [Ti.UI.iOS.PreviewAction](#tiuiiospreviewaction)
+- [Ti.UI.iOS.PreviewActionGroup](#tiuiiospreviewactiongroup)
+- [Ti.UI.iOS.PreviewContext](#tiuiiospreviewcontext)
+- [Ti.UI.iOS.ProgressBarStyle](#tiuiiosprogressbarstyle)
+- [Ti.UI.iOS.RowAnimationStyle](#tiuiiosrowanimationstyle)
+- [Ti.UI.iOS.ScrollIndicatorStyle](#tiuiiosscrollindicatorstyle)
+- [Ti.UI.iOS.SplitWindow](#tiuiiossplitwindow)
+- [Ti.UI.iOS.StatusBar](#tiuiiosstatusbar)
+- [Ti.UI.iOS.Stepper](#tiuiiosstepper)
+- [Ti.UI.iOS.SystemButton](#tiuiiossystembutton)
+- [Ti.UI.iOS.SystemIcon](#tiuiiossystemicon)
+- [Ti.UI.iOS.TabbedBar](#tiuiiostabbedbar)
+- [Ti.UI.iOS.TableViewCellSelectionStyle](#tiuiiostableviewcellselectionstyle)
+- [Ti.UI.iOS.TableViewScrollPosition](#tiuiiostableviewscrollposition)
+- [Ti.UI.iOS.TableViewStyle](#tiuiiostableviewstyle)
+- [Ti.UI.iOS.Toolbar](#tiuiiostoolbar)
+- [Ti.UI.iOS.TransitionAnimation](#tiuiiostransitionanimation)
+- [Ti.UI.iOS.WebViewConfiguration](#tiuiioswebviewconfiguration)
+- [Ti.UI.iOS.WebViewDecisionHandler](#tiuiioswebviewdecisionhandler)
+- [Ti.UI.iOS.WebViewProcessPool](#tiuiioswebviewprocesspool)
+
+<!-- TOC-END -->
+
 ## Ti.UI.iOS
 > Apple iOS specific UI capabilities.  All properties, methods and events in this namespace will only work on Apple iOS devices.
 > Extends Ti.Module

package/skills/ti-api/references/api-ui-lists.md

@@ -1,5 +1,19 @@
 # Ti.UI Lists & Tables API Reference
 
+<!-- TOC-START -->
+## Contents
+
+- [Ti.UI.ListView](#tiuilistview)
+- [Ti.UI.ListItem](#tiuilistitem)
+- [Ti.UI.ListSection](#tiuilistsection)
+- [Ti.UI.ListViewScrollPosition](#tiuilistviewscrollposition)
+- [Ti.UI.TableView](#tiuitableview)
+- [Ti.UI.TableViewRow](#tiuitableviewrow)
+- [Ti.UI.TableViewSection](#tiuitableviewsection)
+- [Ti.UI.TableViewScrollPosition](#tiuitableviewscrollposition)
+
+<!-- TOC-END -->
+
 ## Ti.UI.ListView
 > A list view is used to present information, organized in to sections and items, in a vertically-scrolling view.
 > Extends Ti.UI.View
@@ -15,7 +29,6 @@ A `ListView` object is a container for [ListSection](Titanium.UI.ListSection)
 objects that are, in turn, containers for [ListItem](Titanium.UI.ListItem) objects. This is
 easily visualized as an Alloy view:
 
-``` xml
 
 ### Properties (unique: 54/122)
 | Property | Type | Default | Platform | Description |
@@ -155,7 +168,6 @@ Alloy applications can use **`<ListItem>`** elements to create `ListItem` object
 must be nested inside a **`<ListSection>`** element, which itself is nested in a `<ListView>` element,
 as shown below:
 
-``` xml
 
 ### Properties (unique: 26/28)
 | Property | Type | Default | Platform | Description |

package/skills/ti-api/references/api-ui-text-input.md

@@ -1,5 +1,20 @@
 # Ti.UI Text & Input API Reference
 
+<!-- TOC-START -->
+## Contents
+
+- [Ti.UI.TextField](#tiuitextfield)
+- [Ti.UI.TextArea](#tiuitextarea)
+- [Ti.UI.SearchBar](#tiuisearchbar)
+- [Ti.UI.AttributedString](#tiuiattributedstring)
+- [Ti.UI.Color](#tiuicolor)
+- [Ti.UI.Clipboard](#tiuiclipboard)
+- [Ti.UI.Picker](#tiuipicker)
+- [Ti.UI.PickerColumn](#tiuipickercolumn)
+- [Ti.UI.PickerRow](#tiuipickerrow)
+
+<!-- TOC-END -->
+
 ## Ti.UI.TextField
 > A single line text field.
 > Extends Ti.UI.View

package/skills/ti-api/references/api-ui-views.md

@@ -1,5 +1,24 @@
 # Ti.UI Core Views API Reference
 
+<!-- TOC-START -->
+## Contents
+
+- [Ti.UI.View](#tiuiview)
+- [Ti.UI.Label](#tiuilabel)
+- [Ti.UI.Button](#tiuibutton)
+- [Ti.UI.ImageView](#tiuiimageview)
+- [Ti.UI.ScrollView](#tiuiscrollview)
+- [Ti.UI.ScrollableView](#tiuiscrollableview)
+- [Ti.UI.ActivityIndicator](#tiuiactivityindicator)
+- [Ti.UI.ActivityIndicatorStyle](#tiuiactivityindicatorstyle)
+- [Ti.UI.ProgressBar](#tiuiprogressbar)
+- [Ti.UI.Slider](#tiuislider)
+- [Ti.UI.Switch](#tiuiswitch)
+- [Ti.UI.MaskedImage](#tiuimaskedimage)
+- [Ti.UI.RefreshControl](#tiuirefreshcontrol)
+
+<!-- TOC-END -->
+
 ## Ti.UI.View
 > An empty drawing surface or container
 > Extends Ti.Proxy

package/skills/ti-api/references/api-ui-windows-navigation.md

@@ -1,5 +1,18 @@
 # Ti.UI Windows & Navigation API Reference
 
+<!-- TOC-START -->
+## Contents
+
+- [Ti.UI.Window](#tiuiwindow)
+- [Ti.UI.NavigationWindow](#tiuinavigationwindow)
+- [Ti.UI.TabGroup](#tiuitabgroup)
+- [Ti.UI.Tab](#tiuitab)
+- [Ti.UI.AlertDialog](#tiuialertdialog)
+- [Ti.UI.OptionDialog](#tiuioptiondialog)
+- [Ti.UI.Notification](#tiuinotification)
+
+<!-- TOC-END -->
+
 ## Ti.UI.Window
 > The Window is an empty drawing surface or container.
 > Extends Ti.UI.View

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

@@ -1,5 +1,36 @@
 # Ti.XML & Global API Reference
 
+<!-- TOC-START -->
+## Contents
+
+- [Ti.XML](#tixml)
+- [Ti.XML.Attr](#tixmlattr)
+- [Ti.XML.CDATASection](#tixmlcdatasection)
+- [Ti.XML.CharacterData](#tixmlcharacterdata)
+- [Ti.XML.Comment](#tixmlcomment)
+- [Ti.XML.DOMImplementation](#tixmldomimplementation)
+- [Ti.XML.Document](#tixmldocument)
+- [Ti.XML.DocumentFragment](#tixmldocumentfragment)
+- [Ti.XML.DocumentType](#tixmldocumenttype)
+- [Ti.XML.Element](#tixmlelement)
+- [Ti.XML.Entity](#tixmlentity)
+- [Ti.XML.EntityReference](#tixmlentityreference)
+- [Ti.XML.NamedNodeMap](#tixmlnamednodemap)
+- [Ti.XML.Node](#tixmlnode)
+- [Ti.XML.NodeList](#tixmlnodelist)
+- [Ti.XML.Notation](#tixmlnotation)
+- [Ti.XML.ProcessingInstruction](#tixmlprocessinginstruction)
+- [Ti.XML.Text](#tixmltext)
+- [Global](#global)
+- [Global.Console](#globalconsole)
+- [Global.Intl](#globalintl)
+- [Global.Intl.Collator](#globalintlcollator)
+- [Global.Intl.DateTimeFormat](#globalintldatetimeformat)
+- [Global.Intl.NumberFormat](#globalintlnumberformat)
+- [Global.String](#globalstring)
+
+<!-- TOC-END -->
+
 ## Ti.XML
 > The top level XML module.  The XML module is used for parsing and processing XML-based content.
 > Extends Ti.Module

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, analyzing, or examining 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, or building adaptive layouts for tablets, foldables, and large screens. 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,26 @@ 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) |
+| 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 +53,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 +105,12 @@ 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 +165,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 +185,9 @@ 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)
+- [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

@@ -4,6 +4,20 @@ Patterns for building responsive Titanium apps that work across phones, tablets,
 
 This reference is NOT derived from official Titanium documentation. It addresses Google's Android 17 resizability requirements and provides reusable patterns for adaptive UI in Titanium/Alloy apps.
 
+<!-- TOC-START -->
+## Contents
+
+- [1. Context: Android 17 resizability requirements](#1-context-android-17-resizability-requirements)
+- [2. Detecting window size](#2-detecting-window-size)
+- [3. Layout strategy](#3-layout-strategy)
+- [4. Controller pattern](#4-controller-pattern)
+- [5. Grid simulation](#5-grid-simulation)
+- [6. Anti-patterns](#6-anti-patterns)
+- [7. tiapp.xml configuration](#7-tiappxml-configuration)
+- [8. Quick reference](#8-quick-reference)
+
+<!-- TOC-END -->
+
 ## 1. Context: Android 17 resizability requirements
 
 Starting with Android 17 (API 37), on devices with screens >= 600dp (tablets, foldables, desktop mode), Google ignores these manifest attributes:

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

@@ -1,5 +1,20 @@
 # Alloy builtins & globals
 
+<!-- TOC-START -->
+## Contents
+
+- [Compiler directives](#compiler-directives)
+- [Alloy.Globals](#alloyglobals)
+- [Alloy.CFG](#alloycfg)
+- [Alloy.isTablet / Alloy.isHandheld](#alloyistablet-alloyishandheld)
+- [$.args , controller arguments](#args-controller-arguments)
+- [Alloy.createController / Alloy.createWidget](#alloycreatecontroller-alloycreatewidget)
+- [Alloy.createModel / Alloy.createCollection](#alloycreatemodel-alloycreatecollection)
+- [Conditional code in XML](#conditional-code-in-xml)
+- [Quick reference](#quick-reference)
+
+<!-- TOC-END -->
+
 ## Compiler directives
 
 Alloy provides compile-time constants that are replaced with `true`/`false` during build. Use them for platform-specific code without runtime cost.
@@ -60,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
@@ -85,27 +93,23 @@ 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

@@ -1,5 +1,20 @@
 # Alloy MVC structure reference
 
+<!-- TOC-START -->
+## Contents
+
+- [Standard project structure](#standard-project-structure)
+- [Organization strategy](#organization-strategy)
+- [lib/ folder and module require paths](#lib-folder-and-module-require-paths)
+- [Data layer: two approaches](#data-layer-two-approaches)
+- [Controller rules](#controller-rules)
+- [Navigation & cleanup pattern](#navigation-cleanup-pattern)
+- [i18n and accessibility rules](#i18n-and-accessibility-rules)
+- [Widget structure](#widget-structure)
+- [config.json reference](#configjson-reference)
+
+<!-- TOC-END -->
+
 ## Standard project structure
 
 ```
@@ -15,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
@@ -44,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
@@ -173,7 +188,8 @@ 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).
@@ -181,7 +197,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).
@@ -230,7 +246,10 @@ 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/
@@ -240,7 +259,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
 ```
 
@@ -261,6 +280,17 @@ 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>
@@ -275,10 +305,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)
@@ -337,8 +367,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
 
@@ -449,13 +483,18 @@ 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
 

package/skills/ti-expert/references/anti-patterns.md

@@ -67,14 +67,22 @@
 ## 13. Using `Ti.UI.createNotification`
 **Symptom:** `Ti.UI.createNotification({ message: 'Hi' }).show()`
 **Problem:** This API doesn't exist in Titanium. Causes "invalid method" error.
-**Solution:** Use `Ti.UI.createAlertDialog` for simple messages, or create custom toast views.
+**Solution:** Classify the feedback before choosing UI. Use the app's Snackbar
+Widget for transient foreground feedback, inline/Banner state for persistent
+conditions, and an app-owned Dialog only for blocking or critical information.
+Use the supported platform notification APIs only for actual OS notifications.
+See [Feedback Surfaces](feedback-surfaces.md).
 
 ## 14. Using nonexistent iOS share APIs
 **Symptom:** `Ti.UI.iOS.createActivityPopover` or `alloy/social` with wrong methods.
 **Problem:** These APIs either don't exist or have changed. Causes runtime errors.
 **Solution:**
-- iOS: Use `Ti.UI.iOS.createDocumentViewer` for files, or simple `Ti.UI.createOptionDialog` + `Ti.UI.Clipboard` for links
-- Android: Use `Ti.Android.createIntent` with ACTION_SEND
+- Keep sharing system-owned. Use the currently supported Titanium share/document
+  API or native module for the target platform and verify its current contract
+  with the `ti-api` skill.
+- Do not imitate a share sheet with an app-owned `OptionDialog`. A Bottom Sheet
+  may choose an app action such as an export format, but the OS share surface
+  owns the final destination.
 
 ## Community-Discovered Patterns
 
@@ -117,8 +125,8 @@ This applies to Windows inside both standalone NavigationWindow and TabGroup (wh
 | ----------------------- | ------------------------ | --------------------- |
 | `padding` on View       | No padding on containers | Margins on children   |
 | `layout: 'composite'`   | Already default          | Omit it               |
-| Inline style attributes | Scattered styling        | Define in TSS files   |
+| Inline style attributes | Scattered styling        | PurgeTSS utilities when detected; otherwise TSS |
 | `lib/` prefix           | lib/ is flattened        | Use path without lib/ |
 | `$.index.open()`        | Wrong ID reference       | Use actual Window ID  |
-| `createNotification`    | API doesn't exist        | `createAlertDialog`   |
+| `createNotification`    | API doesn't exist        | Classify feedback; Snackbar is the transient default |
 | `extendEdges` alone     | Content behind nav bar   | Add `autoAdjustScrollViewInsets: true` |