@maccesar/titools 4.1.0 → 4.4.0

package/skills/ti-expert/references/feedback-widget-contracts.md

@@ -0,0 +1,213 @@
+# Contracts for feedback Widgets
+
+Use these contracts for app-owned Snackbar, Dialog, and Bottom Sheet surfaces in
+Alloy. Namespaces and visual tokens belong to each app; behavior stays stable.
+
+## Contents
+
+- [Boundary and registration](#boundary-and-registration)
+- [Snackbar](#snackbar)
+- [Dialog](#dialog)
+- [Bottom Sheet](#bottom-sheet)
+- [Shared lifecycle contract](#shared-lifecycle-contract)
+- [PurgeTSS integration](#purgetss-integration)
+- [Widget, Require, state, or native UI](#widget-require-state-or-native-ui)
+
+## Boundary and registration
+
+Implement each surface as an independent Alloy Widget under `app/widgets/`.
+Each Widget owns its XML, controller, optional styles, assets, state, listeners,
+timers, and `widget.json`. Keep them independent from any third-party component
+library — including TiKit, the Alloy/PurgeTSS component set. A feedback surface
+must not require one to work, and must not be folded into one: its value comes
+from being installable and testable on its own.
+
+Register every Widget in `app/config.json`:
+
+```json
+{
+  "dependencies": {
+    "com.example.ui.bottomsheet": "1.0.0",
+    "com.example.ui.dialog": "1.0.0",
+    "com.example.ui.snackbar": "1.0.0"
+  }
+}
+```
+
+Use the app's reverse-domain namespace. The dependency key must match the `id`
+in that Widget's `widget.json`.
+
+Declare Widgets in XML, normally as the last visual children of the owning
+window so overlays render above screen content:
+
+```xml
+<Widget id="snackbar" src="com.example.ui.snackbar" />
+<Widget id="dialog" src="com.example.ui.dialog" />
+<Widget id="bottomSheet" src="com.example.ui.bottomsheet" />
+```
+
+Build the stable proxy tree in XML. JavaScript may update properties and supply
+`ListView` data; it must not reconstruct the complete surface imperatively.
+
+## Snackbar
+
+```javascript
+$.snackbar.show({
+  message,
+  tone: 'neutral', // neutral | success | warning | error
+  duration: 4500,
+  actionTitle,
+  onAction,
+  onDismiss
+})
+
+$.snackbar.dismiss()
+$.snackbar.destroy()
+```
+
+Contract:
+
+- A new message replaces the visible message and restarts the timer.
+- Default `duration` is 4500 ms; `duration: 0` remains visible until an action,
+  `dismiss()`, replacement, or destruction.
+- Allow at most one text action, such as Undo.
+- Invoke `onAction` once, then close the Snackbar.
+- Invoke `onDismiss` once with the reason `timeout`, `action`, `replaced`,
+  `programmatic`, or `destroy`.
+- Clear the old timer before replacement and on every close path.
+- Position above bottom navigation and inside the current safe area.
+- Queueing Snackbars is not the default. The newest relevant message wins.
+
+## Dialog
+
+```javascript
+$.dialog.attach(window)
+
+$.dialog.show({
+  title,
+  message,
+  tone: 'neutral', // neutral | warning | error
+  confirmTitle,
+  cancelTitle,
+  destructive: false,
+  onConfirm,
+  onCancel
+})
+
+$.dialog.dismiss('programmatic')
+$.dialog.destroy()
+```
+
+Contract:
+
+- Without `cancelTitle`, present an acknowledgement. With it, present a
+  confirmation.
+- Enqueue additional `show()` calls FIFO. Never stack two Dialogs visually.
+- Disable both buttons on the first accepted tap.
+- Invoke `onConfirm` or `onCancel` at most once; never both.
+- Cancel button, Android Back, or allowed backdrop dismissal invokes `onCancel`.
+  Android Back closes an acknowledgement as its single dismissal action.
+- A destructive confirmation must not close from a backdrop tap.
+- `dismiss('programmatic')` closes without treating the operation as a user
+  confirmation or cancellation.
+- `destroy()` clears the active request and queue without running business
+  callbacks.
+- Use platform-familiar safe/cancel ordering and a distinct destructive role;
+  do not hard-code one platform's button order for both.
+
+## Bottom Sheet
+
+```javascript
+$.bottomSheet.attach(window)
+
+$.bottomSheet.show({
+  title,
+  message,
+  items: [{
+    id,
+    title,
+    subtitle,
+    icon,
+    tone: 'neutral',
+    enabled: true
+  }],
+  selectedId,
+  onSelect,
+  onCancel
+})
+
+$.bottomSheet.dismiss('cancel')
+$.bottomSheet.destroy()
+```
+
+Contract:
+
+- Render items with a fixed `ListView` template and data objects. Support long
+  lists, disabled rows, optional subtitles/icons, and a selected marker.
+- Enqueue additional `show()` calls FIFO. Never stack sheets.
+- Accept the first enabled selection only, invoke `onSelect(item)` once, and
+  close.
+- Backdrop, Android Back, Cancel, or `dismiss('cancel')` invokes `onCancel` once.
+- Other programmatic dismissal and `destroy()` do not imply cancellation and do
+  not execute business callbacks.
+- Present from the bottom on phones. On tablets and large screens, use a centered,
+  width-limited action surface. Reserve `anchor` for a future anchored variant;
+  do not expose behavior that is not implemented.
+
+## Shared lifecycle contract
+
+- Prefer one instance of each needed Widget per window. Add a global coordinator
+  only after real cross-window requirements exist.
+- Call `attach(window)` after the host window/controller exists. Call `destroy()`
+  from the host's close cleanup.
+- Make `destroy()` idempotent. Remove listeners, clear timers, cancel pending
+  animation callbacks, clear queues, and release callback references.
+- Guard every asynchronous completion with the current presentation generation
+  so a stale timer or animation cannot dismiss a newer request.
+- Consume backdrop events and prevent them from bubbling to underlying controls.
+- Save the host's previous accessibility state, exclude underlying content while
+  modal, move focus to the surface, and restore the saved state on close.
+- Keep localized copy outside the Widget. Pass strings and business callbacks in
+  the public API.
+- Keep business logic out of the Widget. It reports a choice; the host performs
+  domain work.
+- Verify every callback path for exactly-once behavior: action, confirm, cancel,
+  Back, backdrop, timeout, replacement, programmatic dismissal, and destruction.
+
+## PurgeTSS integration
+
+When `purgetss/` or `purgetss/config.cjs` exists, load the `purgetss` skill before
+writing styles. `ti-expert` decides the component boundary; `purgetss` decides
+the verified utilities and configuration.
+
+Apply these architectural rules:
+
+- Set PurgeTSS `options.widgets` to `true` so Widget XML is scanned.
+- Express stable anatomy and utility classes in Widget XML.
+- Use semantic color names for surfaces, text, borders, accent, overlay, success,
+  warning, and error. Let Titanium resolve light/dark variants.
+- Do not edit generated `app/styles/app.tss`.
+- Use `widget.tss` only for properties that have no verified utility or that are
+  inherently specific to the Widget.
+- Declare animations as XML `Animation` proxies using `purgetss.ui`. Use explicit
+  `open()` and `close()` calls instead of toggle behavior.
+- After generation, inspect the final `app.tss` section for unused or unsupported
+  classes and resolve every new entry.
+
+Do not copy class inventories into this skill and do not guess Tailwind-like
+names. The installed PurgeTSS skill remains the source of truth.
+
+## Widget, Require, state, or native UI
+
+| Choose | When |
+| --- | --- |
+| Alloy Widget | Self-contained public API, state/lifecycle ownership, portable boundary, or reuse across apps/screens |
+| `<Require>` controller | App-specific view/controller composition that shares the host's domain and lifecycle |
+| Screen state in XML | Loading, empty, content, or error presentation belongs only to that screen |
+| TSS or PurgeTSS utilities | Repeated visual treatment has no behavior, state, or lifecycle |
+| Native/system UI | The operating system owns permissions, trust, files, sharing, identity, purchases, or another protected flow |
+
+Usage count is evidence, not a threshold. A component can deserve a Widget on
+its first use if it has a stable portable API and non-trivial lifecycle; three
+similar labels still do not deserve one.
+

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

@@ -1,29 +1,57 @@
 # Migration patterns for legacy Titanium apps
 
+<!-- TOC-START -->
+## Contents
+
+- [Assessment checklist](#assessment-checklist)
+- [Phase 1: styling-system organization](#phase-1-styling-system-organization)
+- [Phase 1B: feedback surfaces](#phase-1b-feedback-surfaces)
+- [Phase 2: service layer extraction](#phase-2-service-layer-extraction)
+- [Phase 3: event system migration](#phase-3-event-system-migration)
+- [Phase 4: navigation service](#phase-4-navigation-service)
+- [Phase 5: state management](#phase-5-state-management)
+- [Migration order](#migration-order)
+- [Rollback strategy](#rollback-strategy)
+- [Common migration pitfalls](#common-migration-pitfalls)
+
+<!-- TOC-END -->
+
 ## Assessment checklist
 
 Before migrating, evaluate the current codebase:
 
 | Area        | Signs of Legacy Code                               | Target State                                  |
 | ----------- | -------------------------------------------------- | --------------------------------------------- |
-| Styling     | Inline attributes, scattered styles                | Organized TSS files (per-controller + global) |
+| Styling     | Inline attributes, scattered styles                | PurgeTSS utilities when detected; otherwise organized Alloy TSS |
 | Controllers | 200+ lines, API calls, business logic              | Thin orchestrators (<100 lines)               |
 | Events      | `Ti.App.fireEvent` everywhere                      | Backbone.Events or StateStore                 |
 | Navigation  | Direct `Alloy.createController().getView().open()` | Navigation service                            |
 | Data        | Scattered `Ti.App.Properties`, no collections      | Centralized state + Collections               |
 
-## Phase 1: TSS organization
+## Phase 1: styling-system organization
+
+**Goal**: Migrate from inline and scattered styling into the styling system the
+project actually uses.
+
+### Step 0: detect PurgeTSS
+
+Check for `purgetss/` or `purgetss/config.cjs` before editing styles.
 
-**Goal**: Migrate from inline styling and scattered styles to well-organized TSS files.
+- **PurgeTSS detected:** invoke the `purgetss` skill, use verified utilities and
+  semantic colors, configure reusable rules in `config.cjs`, and never edit the
+  generated `app/styles/app.tss`.
+- **No PurgeTSS:** use standard per-controller TSS and a manually maintained
+  `app/styles/app.tss` for genuinely global selectors.
+
+Do not migrate a PurgeTSS application back into manual TSS by following a generic
+Alloy example.
 
 ### Step 1: audit existing styles
 
-Find all inline attributes and consolidate into TSS files:
+Find inline attributes and classify them for the detected styling system:
 ```bash
 # Find inline styling in XML views
-grep -r 'backgroundColor=' app/views/
-grep -r 'font=' app/views/
-grep -r 'color=' app/views/
+rg -n 'backgroundColor=|font=|color=' app/views/
 ```
 
 ### Step 2: move inline attributes to TSS
@@ -36,7 +64,7 @@ grep -r 'color=' app/views/
 ```
 
 ```xml
-<!-- AFTER: Clean XML + TSS file -->
+<!-- AFTER in standard Alloy: clean XML + TSS file -->
 <View id="header">
   <Label id="title" text="L('welcome')" />
 </View>
@@ -48,9 +76,11 @@ grep -r 'color=' app/views/
 "#title": { color: "#333", font: { fontSize: 18, fontWeight: "bold" } }
 ```
 
-### Step 3: organize TSS structure
+### Step 3: organize standard Alloy TSS
+
+This step applies only when PurgeTSS is not present.
 
-1. Use `app.tss` for global styles (shared across all views)
+1. Use `app.tss` for genuinely global styles shared across views
 2. Use per-controller TSS files for view-specific styles
 3. Use class selectors for reusable style patterns:
 ```tss
@@ -59,6 +89,18 @@ grep -r 'color=' app/views/
 ".btn-primary": { backgroundColor: '#2563eb', color: '#fff', height: 44, borderRadius: 8 }
 ```
 
+In either styling path, replace hard-coded visual colors with semantic roles as
+part of the migration. See [Theming and Dark Mode](theming.md).
+
+## Phase 1B: feedback surfaces
+
+Inventory native alerts, option dialogs, Toasts, and local overlays. Classify
+each occurrence before replacing it, then migrate one window at a time. Preserve
+system-owned pickers, permission prompts, sharing, and biometric UI.
+
+Use [Feedback Migration](feedback-migration.md) for the sequence, deliberate
+silence rules, and verification contract.
+
 ## Phase 2: service layer extraction
 
 **Goal**: Move business logic from controllers to services.
@@ -265,11 +307,12 @@ const { user } = appStore.getState()
 
 Recommended sequence to minimize risk:
 
-1. **TSS Organization** - Visual only, no logic changes
-2. **Service Layer** - Extract logic without changing behavior
-3. **Navigation Service** - Centralize with cleanup
-4. **Event System** - Replace Ti.App events
-5. **State Management** - Last, as it touches everything
+1. **Styling-system organization** - Establish semantic tokens and the correct PurgeTSS/Alloy path
+2. **Feedback surfaces** - Migrate one window without changing domain outcomes
+3. **Service Layer** - Extract logic without changing behavior
+4. **Navigation Service** - Centralize with cleanup
+5. **Event System** - Replace Ti.App events
+6. **State Management** - Last, as it touches everything
 
 ## Rollback strategy
 
@@ -278,16 +321,10 @@ For each phase:
 1. **Create a branch** before starting
 2. **Migrate one feature** completely
 3. **Test thoroughly** before moving to next feature
-4. **Keep legacy code** commented until stable
+4. **Delete the replaced implementation** after the vertical slice passes
 
-```javascript
-// Temporary: Keep both during migration
-// Legacy:
-// Ti.App.fireEvent('user:updated', data)
-
-// New:
-Alloy.Events.trigger('user:updated', data)
-```
+Use version control for rollback. Do not keep commented legacy implementations:
+they conceal duplicate listeners, stale callbacks, and incomplete migrations.
 
 ## Common migration pitfalls
 

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

@@ -1,5 +1,20 @@
 # Architectural patterns for Titanium + Alloy
 
+<!-- TOC-START -->
+## Contents
+
+- [1. Native module abstraction (Wrapper)](#1-native-module-abstraction-wrapper)
+- [2. Repository pattern for data](#2-repository-pattern-for-data)
+- [3. Service layer pattern](#3-service-layer-pattern)
+- [4. Event bus for decoupling](#4-event-bus-for-decoupling)
+- [5. Factory pattern for dynamic views](#5-factory-pattern-for-dynamic-views)
+- [6. Navigation service pattern](#6-navigation-service-pattern)
+- [7. Collection binding pattern](#7-collection-binding-pattern)
+- [8. Cleanup pattern](#8-cleanup-pattern)
+- [9. Singleton service pattern](#9-singleton-service-pattern)
+
+<!-- TOC-END -->
+
 ## 1. Native module abstraction (Wrapper)
 
 **Use when:** Using native modules like Maps, Biometrics, or specialized Media players.
@@ -446,3 +461,4 @@ class AnalyticsService {
 }
 
 exports.Analytics = new AnalyticsService()
+```

package/skills/ti-expert/references/performance-optimization.md

@@ -1,5 +1,22 @@
 # Performance optimization: bridge, memory, animation & timing
 
+<!-- TOC-START -->
+## Contents
+
+- [Bridge optimization](#bridge-optimization)
+- [Memory management](#memory-management)
+- [Image memory management](#image-memory-management)
+- [Lazy loading pattern](#lazy-loading-pattern)
+- [Database performance](#database-performance)
+- [Performance monitoring](#performance-monitoring)
+- [Animation performance](#animation-performance)
+- [Hardware-accelerated properties](#hardware-accelerated-properties)
+- [Animation cleanup](#animation-cleanup)
+- [Debouncing and throttling](#debouncing-and-throttling)
+- [Performance checklist](#performance-checklist)
+
+<!-- TOC-END -->
+
 ## Bridge optimization
 
 ### Minimize bridge crossings

package/skills/ti-expert/references/security-device.md

@@ -1,5 +1,18 @@
 # Device security: biometrics, deep links & integrity
 
+<!-- TOC-START -->
+## Contents
+
+- [Biometric authentication](#biometric-authentication)
+- [Biometric login flow](#biometric-login-flow)
+- [Deep link security](#deep-link-security)
+- [Registering deep link handler](#registering-deep-link-handler)
+- [Jailbreak/Root detection](#jailbreakroot-detection)
+- [Integrating security checks](#integrating-security-checks)
+- [Security checklist](#security-checklist)
+
+<!-- TOC-END -->
+
 ## Biometric authentication
 
 ### Using ti.identity module
@@ -92,6 +105,9 @@ const { TokenStorage } = require('services/tokenStorage')
 const { AuthService } = require('services/authService')
 
 function init() {
+  // The login view declares the app-owned Dialog Widget as its last child.
+  $.dialog.attach($.getView())
+
   // Check if biometric login is available and enabled
   const { available, type } = BiometricService.checkAvailability()
   const biometricEnabled = Ti.App.Properties.getBool('biometricEnabled', false)
@@ -130,22 +146,25 @@ async function onLoginSuccess(user) {
   if (available && !Ti.App.Properties.getBool('askedBiometric', false)) {
     Ti.App.Properties.setBool('askedBiometric', true)
 
-    // Ask user if they want to enable biometric login
-    const dialog = Ti.UI.createAlertDialog({
+    // The choice is app-owned; the later biometric authentication prompt remains native.
+    $.dialog.show({
       title: String.format(L('enable_biometric_title'), type),
       message: String.format(L('enable_biometric_msg'), type),
-      buttonNames: [L('not_now'), L('enable')]
-    })
-
-    dialog.addEventListener('click', (e) => {
-      if (e.index === 1) {
+      cancelTitle: L('not_now'),
+      confirmTitle: L('enable'),
+      onConfirm: () => {
         Ti.App.Properties.setBool('biometricEnabled', true)
       }
     })
-
-    dialog.show()
   }
 }
+
+function cleanup() {
+  $.dialog.destroy()
+  $.destroy()
+}
+
+$.cleanup = cleanup
 ```
 
 ## Deep link security
@@ -469,7 +488,9 @@ exports.SecurityService = {
   enforceSecurityPolicy() {
     const { compromised, reasons } = this.checkDeviceIntegrity()
 
-    if (!compromised) return true
+    if (!compromised) {
+      return { outcome: 'allow', reasons: [], restricted: false }
+    }
 
     // Log security event
     logger.error('Security', 'Compromised device detected', {
@@ -483,50 +504,16 @@ exports.SecurityService = {
 
     switch (policy) {
       case 'block':
-        // Prevent app usage
-        this._showBlockedScreen()
-        return false
+        return { outcome: 'block', reasons, restricted: true }
 
       case 'restrict':
-        // Disable sensitive features
         Ti.App.Properties.setBool('restrictedMode', true)
-        this._showWarning()
-        return true
+        return { outcome: 'warn', reasons, restricted: true }
 
       case 'warn':
       default:
-        // Just warn the user
-        this._showWarning()
-        return true
+        return { outcome: 'warn', reasons, restricted: false }
     }
-  },
-
-  _showBlockedScreen() {
-    // Note: iOS guidelines prohibit programmatically terminating an app.
-    // The best practice is to show a blocking dialog and prevent further interaction.
-    // On Android you can call Ti.Android.currentActivity.finish() to close the activity.
-    const dialog = Ti.UI.createAlertDialog({
-      title: L('security_blocked_title'),
-      message: L('security_blocked_msg'),
-      buttonNames: [L('close')]
-    })
-
-    dialog.addEventListener('click', () => {
-      if (OS_ANDROID) {
-        Ti.Android.currentActivity.finish()
-      }
-      // On iOS: leave the dialog visible — Apple guidelines prohibit force-quitting apps.
-    })
-
-    dialog.show()
-  },
-
-  _showWarning() {
-    Ti.UI.createAlertDialog({
-      title: L('security_warning_title'),
-      message: L('security_warning_msg'),
-      buttonNames: [L('i_understand')]
-    }).show()
   }
 }
 ```
@@ -537,18 +524,45 @@ exports.SecurityService = {
 // alloy.js
 const { SecurityService } = require('services/securityService')
 
-// Check device integrity at app start
-const securityCheck = SecurityService.enforceSecurityPolicy()
+// Services return policy; they do not create UI before the root exists.
+const securityDecision = SecurityService.enforceSecurityPolicy()
+const root = Alloy.createController('index', { securityDecision })
+root.getView().open()
+```
+
+```javascript
+// controllers/index.js
+const decision = $.args.securityDecision
+
+function init() {
+  $.dialog.attach($.indexWindow)
+
+  if (decision.outcome === 'block') {
+    // Show a dedicated blocking state in the root XML and do not initialize
+    // protected application content. Do not force-quit the app.
+    $.blockingState.visible = true
+    $.appContent.visible = false
+    return
+  }
+
+  initializeAppContent({ restricted: decision.restricted })
+
+  if (decision.outcome === 'warn') {
+    $.dialog.show({
+      title: L('security_warning_title'),
+      message: L('security_warning_msg'),
+      tone: 'warning',
+      confirmTitle: L('i_understand')
+    })
+  }
+}
 
-if (!securityCheck) {
-  // Don't initialize the app
-  return
+function cleanup() {
+  $.dialog.destroy()
+  $.destroy()
 }
 
-// Check again periodically (in case of runtime jailbreak tools)
-setInterval(() => {
-  SecurityService.checkDeviceIntegrity()
-}, 5 * 60 * 1000) // Every 5 minutes
+$.cleanup = cleanup
 ```
 
 ## Security checklist
@@ -565,3 +579,4 @@ setInterval(() => {
 | **Integrity**  | Check for jailbreak/root   | checkDeviceIntegrity()   |
 | **Integrity**  | Define security policy     | block/restrict/warn      |
 | **Integrity**  | Log security events        | Always log compromises   |
+| **Integrity UI** | Keep policy out of services | Root controller presents blocking state or Dialog |

package/skills/ti-expert/references/state-management.md

@@ -1,5 +1,21 @@
 # State management patterns
 
+<!-- TOC-START -->
+## Contents
+
+- [The problem](#the-problem)
+- [Solution: centralized state store](#solution-centralized-state-store)
+- [State store usage](#state-store-usage)
+- [Service layer state caching](#service-layer-state-caching)
+- [Collections vs state store](#collections-vs-state-store)
+- [State synchronization pattern](#state-synchronization-pattern)
+- [Anti-patterns](#anti-patterns)
+- [Persistence strategies](#persistence-strategies)
+- [State middleware](#state-middleware)
+- [State debugging](#state-debugging)
+
+<!-- TOC-END -->
+
 ## The problem
 
 As apps grow, state gets scattered:
@@ -730,6 +746,7 @@ appStore.use(debugMiddleware)
 // controllers/debug/stateViewer.js (Development only)
 const { StateDebug } = require('services/stateDebug')
 const { appStore } = require('services/stateStore')
+const { Navigation } = require('services/navigation')
 
 function init() {
   if (!Alloy.CFG.debug) {
@@ -763,12 +780,11 @@ function onHistoryItemClick(e) {
   const index = e.itemIndex
   const entry = StateDebug.getHistory()[index]
 
-  // Show diff
-  Ti.UI.createAlertDialog({
+  // Structured, potentially long content belongs in a scrollable debug screen.
+  Navigation.open('debug/stateDiff', {
     title: entry.action,
-    message: JSON.stringify(entry.diff, null, 2),
-    buttonNames: ['OK']
-  }).show()
+    content: JSON.stringify(entry.diff, null, 2)
+  })
 }
 
 function cleanup() {

package/skills/ti-expert/references/testing-e2e-ci.md

@@ -1,5 +1,22 @@
 # End-to-end testing & CI/CD
 
+<!-- TOC-START -->
+## Contents
+
+- [Appium setup](#appium-setup)
+- [Appium configuration](#appium-configuration)
+- [Webdriverio integration](#webdriverio-integration)
+- [E2E test example](#e2e-test-example)
+- [Adding accessibility IDs for testing](#adding-accessibility-ids-for-testing)
+- [Page object pattern](#page-object-pattern)
+- [CI/CD integration](#cicd-integration)
+- [Fastlane integration](#fastlane-integration)
+- [Package.json scripts](#packagejson-scripts)
+- [Branch protection rules](#branch-protection-rules)
+- [Testing best practices summary](#testing-best-practices-summary)
+
+<!-- TOC-END -->
+
 ## Appium setup
 
 ```bash