@maccesar/titools 4.3.0 → 4.4.2

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

@@ -0,0 +1,175 @@
+# 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/file-type-association.md

@@ -0,0 +1,265 @@
+# File type association
+
+How to make the OS hand your app a file — so a document with your extension opens your app when the user taps it, arrives over AirDrop or Quick Share, or is picked from another app's share sheet.
+
+This is a configuration problem more than a coding one, and it fails in a specific way that wastes days: the system gives no error, no warning, and no log line when a key is in the wrong place. The app simply never gets the file, and every symptom looks like "iOS/Android doesn't allow this", which is the wrong conclusion. Most of this file is about telling those failures apart.
+
+## Contents
+
+1. [Decide what you are declaring](#1-decide-what-you-are-declaring)
+2. [iOS: declaring the type](#2-ios-declaring-the-type)
+3. [iOS: claiming the documents](#3-ios-claiming-the-documents)
+4. [iOS: the root-level keys](#4-ios-the-root-level-keys)
+5. [iOS: receiving the file](#5-ios-receiving-the-file)
+6. [Android: the intent filter](#6-android-the-intent-filter)
+7. [Android: receiving the file](#7-android-receiving-the-file)
+8. [Document icons](#8-document-icons)
+9. [Verify instead of assuming](#9-verify-instead-of-assuming)
+10. [Symptom to cause](#10-symptom-to-cause)
+
+## 1. Decide what you are declaring
+
+Two questions decide everything downstream.
+
+**Is the type yours or someone else's?** A format your app invented is *exported* — you own the identifier and define what it means. A format that already exists (PDF, CSV, a competitor's format) is *imported* — you are declaring that you can handle a type someone else defined. On iOS these are different keys (`UTExportedTypeDeclarations` vs `UTImportedTypeDeclarations`); declaring someone else's type as exported is how two apps end up fighting over an identifier.
+
+**What is the file, as far as the system is concerned?** This matters more than it looks, and it is the first place people go wrong. A backup archive that happens to be a ZIP internally is *not* a ZIP as far as the user is concerned — it is your document. If you declare it as conforming to `public.zip-archive`, iOS Files treats it as an archive: tapping it lists the contents instead of handing it to your app, because that is what the system does with archives, and it is doing exactly what you told it.
+
+Conform to `public.data` for an opaque document whose internals are your business. The internal format is an implementation detail; the declared type is a user-facing contract.
+
+The same reasoning applies to the extension. `.zip` makes your app volunteer for every ZIP on the device; a distinct extension keeps the association narrow.
+
+## 2. iOS: declaring the type
+
+Goes inside `<ios><plist><dict>` in `tiapp.xml`:
+
+```xml
+<key>UTExportedTypeDeclarations</key>
+<array>
+  <dict>
+    <key>UTTypeIdentifier</key>
+    <string>com.example.myapp.mytype</string>
+    <key>UTTypeDescription</key>
+    <string>My App Document</string>
+    <key>UTTypeConformsTo</key>
+    <array>
+      <string>public.data</string>
+    </array>
+    <key>UTTypeTagSpecification</key>
+    <dict>
+      <key>public.filename-extension</key>
+      <array>
+        <string>mytype</string>
+      </array>
+    </dict>
+  </dict>
+</array>
+```
+
+Use reverse-DNS under your bundle id for the identifier. The extension in `UTTypeTagSpecification` carries no leading dot.
+
+For a type you did not invent, use `UTImportedTypeDeclarations` with the same structure and the identifier its owner published.
+
+## 3. iOS: claiming the documents
+
+Declaring a type says the type exists. `CFBundleDocumentTypes` says your app handles it:
+
+```xml
+<key>CFBundleDocumentTypes</key>
+<array>
+  <dict>
+    <key>CFBundleTypeName</key>
+    <string>My App Document</string>
+    <key>CFBundleTypeRole</key>
+    <string>Editor</string>
+    <key>LSHandlerRank</key>
+    <string>Owner</string>
+    <key>LSItemContentTypes</key>
+    <array>
+      <string>com.example.myapp.mytype</string>
+    </array>
+    <key>CFBundleTypeExtensions</key>
+    <array>
+      <string>mytype</string>
+    </array>
+  </dict>
+</array>
+```
+
+`LSHandlerRank` decides who wins when several apps claim the same type: `Owner` for a format you defined, `Alternate` for one you merely support, `Default` when no other app claims it. `CFBundleTypeRole` is `Editor` if your app can modify the file, `Viewer` if it only reads it.
+
+## 4. iOS: the root-level keys
+
+This is where the day gets lost, so it is worth stating plainly: **`LSSupportsOpeningDocumentsInPlace` is a root-level `Info.plist` key.** It is a sibling of `CFBundleDocumentTypes`, not a key inside its dictionary.
+
+Nesting it reads as natural — it describes how documents of that type are opened, so it looks like it belongs with the type. iOS does not read it there and says nothing about it. The resulting state is deceptive: the app *is* registered as owner of the type, so the system knows it exists, but nothing ever declared that the app can open it in place. Files falls back to previewing the document, and the behavior is indistinguishable from "iOS won't launch third-party apps from Files" — a conclusion people reach, write down, and design around.
+
+```xml
+<!-- correct: sibling of CFBundleDocumentTypes, at the root of the plist dict -->
+<key>CFBundleDocumentTypes</key>
+<array>...</array>
+
+<key>LSSupportsOpeningDocumentsInPlace</key>
+<true/>
+```
+
+Apple's own requirement makes this non-optional: when you declare `CFBundleDocumentTypes`, you must also set either `LSSupportsOpeningDocumentsInPlace` or `UISupportsDocumentBrowser` (the latter only if the app uses `UIDocumentBrowserViewController`). Omitting both also triggers the *Missing Document Configuration* warning from App Store Connect, which is often the first hint anyone gets that something is wrong.
+
+There is a second reason to set it beyond launching. Without it, iOS copies the document into the app's Inbox before delivering it — a full second copy on disk. For a document that carries photos or video, that is a real cost paid every time the user opens one.
+
+### The neighboring key that is not the same thing
+
+`UIFileSharingEnabled` (also root-level) exposes the app's entire `Documents` directory inside the Files app. It is unrelated to opening a document your app was handed, and it is not required for this to work.
+
+Enabling it makes every JSON file, cache and media asset the app keeps in `Documents` browsable by the user. That is a product decision — sometimes the right one, for an app whose documents *are* the user's files — but reaching for it while debugging a file association exposes the app's internals as a side effect of a fix that was never about that.
+
+## 5. iOS: receiving the file
+
+The app receives the document URL through the `handleurl` event on `Ti.App.iOS`:
+
+```javascript
+Ti.App.iOS.addEventListener('handleurl', event => {
+  const url = event.launchOptions && event.launchOptions.url
+  // resolve, validate, then adopt
+})
+```
+
+Register the listener at a point that survives the app being launched *by* the file rather than merely resumed — a cold launch delivers the event early. Store whatever identifies the last handled document, because the same launch payload can be read more than once during a lifecycle and reprocessing it silently imports the same file twice.
+
+**Validate before acting.** An intent filter or a UTI claim is a public invitation: any file with the right extension reaches your app, including one that is malformed or came from somewhere unexpected. Read the manifest, check the version, and fail with a message the user understands — never start writing over existing data on the strength of a filename.
+
+### Saving a file back out
+
+Two APIs are easy to confuse:
+
+- `Ti.UI.iOS.DocumentViewer` is a **previewer**. If the file type is not previewable it does not present and does not report an error.
+- `ti.documentpicker.export()` opens the system destination dialog — this is the one for "save a copy where the user chooses".
+
+## 6. Android: the intent filter
+
+Android associates by intent filter on the activity that should receive the file, declared inside `<android><manifest><application>` in `tiapp.xml`:
+
+```xml
+<activity android:name=".MyAppActivity">
+  <intent-filter>
+    <action android:name="android.intent.action.VIEW"/>
+    <category android:name="android.intent.category.DEFAULT"/>
+    <category android:name="android.intent.category.BROWSABLE"/>
+    <data android:scheme="content"/>
+    <data android:scheme="file"/>
+    <data android:mimeType="*/*"/>
+    <data android:host="*"/>
+    <data android:pathPattern=".*\\.mytype"/>
+    <data android:pathPattern=".*\\..*\\.mytype"/>
+    <data android:pathPattern=".*\\..*\\..*\\.mytype"/>
+  </intent-filter>
+</activity>
+```
+
+Three things in that block are not obvious.
+
+**`pathPattern` is not a regular expression.** It supports only `*` (zero or more of the preceding character) and `.` (any character), and the matching is greedy without backtracking. `.*\\.mytype` therefore fails on any filename containing an earlier dot — `my.backup.mytype` does not match — so the conventional fix is to repeat the pattern with one extra `.*\\.` per additional dot you want to tolerate. Three variants covers most real filenames. The backslash is doubled because the manifest is XML.
+
+**A custom extension usually has no registered MIME type**, so the file arrives as `application/octet-stream` or with whatever type the sending app guessed. `android:mimeType="*/*"` is what makes the filter reachable at all; the `pathPattern` entries are what keep it from volunteering for every file on the device. Both halves are load-bearing — `*/*` alone makes your app an option for opening anything.
+
+**Matching is by name, which has a consequence.** A `content://` URI whose path does not carry the filename will not match, no matter what its MIME type says. This is a real limit of the mechanism, not a misconfiguration to hunt down.
+
+### Whether to also filter ACTION_SEND
+
+`ACTION_VIEW` covers tapping the file — in a file manager, a messaging app, or a notification. `ACTION_SEND` covers another app sharing content *to* you, which is how Quick Share and most share buttons deliver.
+
+Adding `ACTION_SEND` has a side effect worth predicting: your app then appears in its own share sheet, offering to receive the file it just produced. If the app's only outbound flow is exporting a document, that is confusing enough to be worth skipping — tapping the received file still works through `ACTION_VIEW`.
+
+## 7. Android: receiving the file
+
+Read the intent from the current activity, falling back to the launch intent:
+
+```javascript
+const activity = Ti.Android.currentActivity || Ti.Android.rootActivity
+const intent = (activity && activity.intent) || Ti.App.Android.launchIntent
+const action = intent.getAction()
+
+// ACTION_VIEW  → intent.getData()
+// ACTION_SEND  → intent.getBlobExtra(Ti.Android.EXTRA_STREAM)
+```
+
+**A `content://` URI is not a path.** It is a handle into another app's content provider, valid only for as long as the grant lasts. Read the blob and write it to a file you own under `applicationDataDirectory` before doing anything else; code that treats it as a filesystem path works on some devices and fails on others, which is the worst kind of bug to inherit.
+
+Give that landing spot its own directory, separate from the working area your import routine clears at the start of a run — otherwise the incoming file deletes itself moments before it is read.
+
+As on iOS, the same launch intent can be read more than once during a lifecycle. Remember the last one handled.
+
+## 8. Document icons
+
+A document icon is what lets someone find their file months later without reading filenames. It is also the part most likely to be quietly ignored by the system, so it is worth confirming before producing a full set of images.
+
+**iOS derives one for free — check that before drawing anything.** With no icon keys declared at all, the Files app renders the document as a page with the app icon inside it (verified 2026-08-05 on a Titanium 13.4.0 app: no `UTTypeIconFiles`, no `CFBundleTypeIconFiles`, not a single document PNG in the project). For a type only your app produces, that is usually enough — it reads as "a document belonging to this app", which is the whole job, and it costs nothing to maintain.
+
+Note the sequencing this implies: the derived icon is only meaningful once the app icon is final, since it is built from it. Producing a document icon set before app identity is settled means judging a fallback that is itself a placeholder.
+
+If you do want a custom one, declare `UTTypeIconFiles` in the type declaration and `CFBundleTypeIconFiles` in the document type entry, both arrays of PNG filenames (with extension) placed in `app/assets/iphone/`. Confirm it is actually honored on a device before producing the full size set — there are long-standing developer reports of the system preferring its derived version anyway.
+
+**Android.** The icon belongs on the `intent-filter`, not on the data element:
+
+```xml
+<intent-filter android:icon="@drawable/mytype">
+```
+
+with the drawable under `platform/android/res/drawable/`. Android does not oblige file managers to use it, and several show their own icon based on MIME type — with `application/octet-stream`, expect some to render it generic no matter what you ship.
+
+Android has no derived-icon fallback, so the two platforms are not symmetrical: on iOS doing nothing produces something reasonable, while on Android doing nothing leaves the file generic. Decide them separately rather than as one task.
+
+## 9. Verify instead of assuming
+
+Every claim in this file is checkable in seconds, and the failure modes are silent enough that checking is the only way to know.
+
+**Confirm the built binary, not `tiapp.xml`.** The build normalizes and merges plists, so what you wrote is not necessarily what shipped:
+
+```bash
+# what the installed app actually declares
+plutil -extract LSSupportsOpeningDocumentsInPlace raw -o - "<App>.app/Info.plist"
+plutil -extract CFBundleDocumentTypes xml1 -o - "<App>.app/Info.plist"
+```
+
+A key in the wrong place returns *"No value at that key path"* — the same result as not declaring it at all, which is precisely the point.
+
+For a simulator build, locate the bundle with:
+
+```bash
+xcrun simctl get_app_container <device-udid> <bundle-id> app
+```
+
+**On Android, ask the package manager who claims the type:**
+
+```bash
+adb shell cmd package query-activities -a android.intent.action.VIEW \
+  -d "file:///sdcard/Download/test.mytype"
+```
+
+Run it twice — once with your extension and once with a neighbouring one (`.zip`, `.txt`) — to confirm the filter is both reachable *and* narrow. A filter that matches everything looks identical to a correct one until you test the negative case.
+
+**The final check is a person tapping the file.** Nothing above proves the OS routes it; it only proves the declaration is well formed. Test a cold launch (app not running) separately from a warm one — they take different paths through the launch handling and only one of them may be wired up.
+
+## 10. Symptom to cause
+
+| Symptom | Likely cause |
+| --- | --- |
+| iOS Files previews the document instead of launching the app | `LSSupportsOpeningDocumentsInPlace` missing from the **root** of `Info.plist`, or nested inside `CFBundleDocumentTypes` |
+| iOS Files lists the file's contents like a folder | Type conforms to `public.zip-archive` (or another archive type) instead of `public.data` |
+| App is offered for unrelated files of other apps | Extension or MIME type too broad (`.zip`, `application/zip`); on Android, `mimeType="*/*"` with no `pathPattern` |
+| App offers itself in its own share sheet | An `ACTION_SEND` filter that the app's own outbound flow matches |
+| Android: file with several dots in its name never opens the app | `pathPattern` variants missing for the extra dots |
+| Android: a `content://` file never opens the app | The URI path carries no filename — a limit of name-based matching, not a bug |
+| iOS: the same document imports twice | The launch payload was read more than once; no "last handled" guard |
+| *Missing Document Configuration* on App Store upload | `CFBundleDocumentTypes` declared without `LSSupportsOpeningDocumentsInPlace` or `UISupportsDocumentBrowser` |
+| Document icon stays generic | App icon not final (the fallback derives from it), or the file manager ignores the declared icon |
+
+## Sources
+
+- Verified 2026-08-05 on a shipping Titanium 13.4.0 app: moving `LSSupportsOpeningDocumentsInPlace` from inside the `CFBundleDocumentTypes` dict to the root of the plist changed `plutil -extract` from *"No value at that key path"* to `true`, and changed Files behavior from previewing the document to launching the app.
+- Verified on the same app: an exported type conforming to `public.zip-archive` made iOS Files list the archive contents; `public.data` did not.
+- Verified with `cmd package query-activities`: a narrow extension plus `pathPattern` stops the app being offered for unrelated archives.
+- Verified 2026-08-05 in the iOS Files app: with no icon keys declared, the document renders as a page with the app icon inside it.
+- `Ti.App.iOS` `handleurl` event — see `ti-api/references/api-app-platform.md`.
+- Apple, *Information Property List* reference, for `LSSupportsOpeningDocumentsInPlace`, `UIFileSharingEnabled` and `UISupportsDocumentBrowser`.
+- Icon key names and sizes come from Apple's archived *Registering the File Types Your App Supports*; confirm sizes against current documentation before producing a full set.

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

@@ -4,7 +4,8 @@
 ## Contents
 
 - [Assessment checklist](#assessment-checklist)
-- [Phase 1: TSS organization](#phase-1-tss-organization)
+- [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)
@@ -21,24 +22,31 @@ 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 styling and scattered styles to well-organized TSS files.
+**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.
+
+- **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
@@ -51,7 +59,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>
@@ -63,9 +71,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
@@ -74,6 +84,14 @@ 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.
@@ -280,11 +298,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
 
@@ -293,16 +312,9 @@ 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