@maccesar/titools 5.2.5 → 5.4.0

package/skills/ti-howtos/SKILL.md

@@ -1,131 +1,31 @@
 ---
 name: ti-howtos
-description: 'Use when implementing Titanium SDK native integrations: location services, Google Maps v2 (Android) or Map Kit (iOS), push notifications (APNs/FCM), camera and gallery, media APIs, SQLite databases, HTTPClient networking, WKWebView, Android Intents, iOS Keychain/iCloud, WatchKit/Siri, Hyperloop native modules, or CI/CD with Fastlane and Appium. Triggers include `tiapp.xml` in the project root plus calls to `Ti.Geolocation`, `Ti.Media`, `Ti.Database`, `Ti.Network.HTTPClient`, `Ti.UI.WebView`, `Ti.Filesystem`, or third-party modules like `ti.map`, `ti.playservices`, `ti.identity`.'
+description: 'Use when implementing Titanium SDK device integrations, location and ti.map, local or push notifications, camera/gallery/audio/video, SQLite and files, HTTPClient, platform conventions, native modules, Hyperloop, CLI plugins, or debugging. Triggers include tiapp.xml and calls to Ti.Geolocation, Ti.Media, Ti.Database, Ti.Network or third-party modules.'
 ---
 
 # ti-howtos
 
-## Overview
+Practical guidance from the current official Titanium website. Load the matching reference before implementing a feature. Release API/compiler contracts resolve mistakes in guide examples; do not assume an unreleased SDK feature is available.
 
-Practical reference for Titanium SDK native integrations: device APIs, networking, persistence, native modules, platform-specific deep dives, and CI/CD. Reference-style — load the relevant file from `references/` for deeper detail.
-
-## When to use
-
-Use this skill when:
-
-- The project contains `tiapp.xml`
-- Implementing device features: GPS, camera, push notifications, sensors
-- Adding maps: Google Maps v2 on Android or Map Kit on iOS
-- Working with media: audio, video, image gallery, density assets
-- Persisting data: SQLite, Properties, Filesystem, encrypted storage
-- Networking: HTTPClient, sockets, SOAP, SSL/TLS, file uploads/downloads
-- Embedding web content: WKWebView, local HTML, JS bridges
-- Platform-specific work: Android Intents, iOS 17 privacy, Spotlight, iCloud, Core Motion, WatchKit, Siri
-- Extending Titanium: Hyperloop, native modules, AndroidX migration
-- CI/CD: Fastlane lanes, Appium UI tests, store deployment
-
-Do NOT use for:
-
-- Alloy MVC concepts, controllers, models, data binding (use `alloy-guides`)
-- Alloy CLI, conditional views, custom XML tags, build hooks (use `alloy-howtos`)
-- Titanium SDK fundamentals, `tiapp.xml` config basics, app distribution overview (use `ti-guides`)
-- Looking up specific Titanium API signatures (use `ti-api`)
-- Native module dependency updates (use `ti-module-update`)
-
-## Quick reference
-
-| Topic | Reference |
-|---|---|
-| GPS, distance filter, accuracy, geofencing | [location-and-maps.md](references/location-and-maps.md) |
-| Google Maps v2 on Android: API keys, Play Services | [google-maps-v2.md](references/google-maps-v2.md) |
-| iOS Map Kit: 3D camera, system buttons, callouts | [ios-map-kit.md](references/ios-map-kit.md) |
-| Push notifications (APNs / FCM), local alerts, interactive notifications | [notification-services.md](references/notification-services.md) |
-| HTTPClient lifecycle, JSON/XML, uploads, sockets, SOAP, SSL | [remote-data-sources.md](references/remote-data-sources.md) |
-| Filesystem, SQLite, Properties, persistence strategy | [local-data-sources.md](references/local-data-sources.md) |
-| Binary data with `Ti.Buffer`, `Ti.Codec`, streams | [buffer-codec-streams.md](references/buffer-codec-streams.md) |
-| Audio playback/recording, video, camera, gallery, density assets | [media-apis.md](references/media-apis.md) |
-| WKWebView, local/remote content, JS bridge | [web-content-integration.md](references/web-content-integration.md) |
-| Webpack build pipeline (Ti 9.1.0+), npm integration, `@` alias | [webpack-build-pipeline.md](references/webpack-build-pipeline.md) |
-| Android Intents, broadcast permissions, background services | [android-platform-deep-dives.md](references/android-platform-deep-dives.md) |
-| iOS 17 privacy, silent push, Spotlight, Handoff, iCloud, Core Motion, WatchKit, Siri | [ios-platform-deep-dives.md](references/ios-platform-deep-dives.md) |
-| Hyperloop, native Proxy/View modules, AndroidX migration | [extending-titanium.md](references/extending-titanium.md) |
-| Memory management, leak detection, native debugging tools | [debugging-profiling.md](references/debugging-profiling.md) |
-| Fastlane lanes, Appium UI testing, store deployment | [automation-fastlane-appium.md](references/automation-fastlane-appium.md) |
-| Cross-platform strategy: shared vs platform-specific code | [cross-platform-development.md](references/cross-platform-development.md) |
-| End-to-end tutorials: REST APIs, camera, geolocation, controller chaining, Fastlane | [tutorials.md](references/tutorials.md) |
-| Obtaining, installing, and configuring native modules | [using-modules.md](references/using-modules.md) |
-
-## Key practices
-
-### iOS permissions
-
-Required `tiapp.xml` keys for common features:
-
-- Location: `NSLocationWhenInUseUsageDescription` or `NSLocationAlwaysAndWhenInUseUsageDescription`
-- Motion activity: `NSMotionUsageDescription`
-- Camera: `NSCameraUsageDescription`
-- Photo library: `NSPhotoLibraryUsageDescription` (read) and `NSPhotoLibraryAddUsageDescription` (write)
-- Microphone: `NSMicrophoneUsageDescription`
-- iOS 17+: `PrivacyInfo.xcprivacy` for UserDefaults and File Timestamps (see [ios-platform-deep-dives.md](references/ios-platform-deep-dives.md))
-
-### Android resource management
-
-- Stop background services explicitly when no longer needed
-- Use `distanceFilter` and FusedLocationProvider (requires `ti.playservices`) for battery-efficient location
-- Intent filters: copy the root activity to `tiapp.xml`, then add action / data / category
-
-### Data and networking
-
-- HTTPClient: handle both `onload` and `onerror` — never just one
-- SQLite: close both `db` and `resultSet` to avoid locks
-- Filesystem: check `isExternalStoragePresent()` before using SD card storage
-- Binary data: use `Ti.Buffer` and `Ti.Codec` for byte-level work; `BufferStream` / `FileStream` / `BlobStream` for chunked I/O
-
-### Media and memory
-
-- Camera / gallery: use `imageAsResized` to reduce memory pressure
-- Audio: handle `pause` / `resume` for streaming interruptions
-- WebView: avoid embedding inside TableView; set `touchEnabled=false` if needed
-- Video: Android requires fullscreen; iOS supports embedded players
-
-### Platform-specific properties need modifiers
-
-Using `Ti.UI.iOS.*` or `Ti.UI.Android.*` without platform modifiers can break cross-platform builds.
-
-```javascript
-// Wrong — adds Ti.UI.iOS to Android build
-const win = Ti.UI.createWindow({
-  statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT
-});
-```
-
-TSS modifier (Alloy):
-
-```tss
-"#mainWindow[platform=ios]": {
-  statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT
-}
-```
-
-Conditional code:
-
-```javascript
-if (OS_IOS) {
-  $.mainWindow.statusBarStyle = Ti.UI.iOS.StatusBar.LIGHT_CONTENT;
-}
-```
-
-Common offenders:
-
-- iOS: `statusBarStyle`, `modalStyle`, `modalTransitionStyle`, any `Ti.UI.iOS.*` constant
-- Android: `actionBar` config, any `Ti.UI.Android.*` constant
-
-## Related skills
-
-| Task | Use this skill |
+| Task | Reference |
 |---|---|
-| Alloy MVC concepts, controllers, models, data binding | `alloy-guides` |
-| Alloy CLI, custom tags, build hooks, conditional views | `alloy-howtos` |
-| Titanium SDK fundamentals, `tiapp.xml`, app distribution | `ti-guides` |
-| Look up Titanium API properties, methods, events | `ti-api` |
-| Native module dependency updates | `ti-module-update` |
+| Location permission, one position, tracking, geocoding, ti.map | [location-and-maps.md](references/location-and-maps.md) |
+| Local notifications, Android channels, APNs/FCM boundaries | [notification-services.md](references/notification-services.md) |
+| HTTPClient, JSON, forms, files, progress, connection and TLS | [remote-data-sources.md](references/remote-data-sources.md) |
+| Properties, files, SQLite, seed databases and migrations | [local-data-sources.md](references/local-data-sources.md) |
+| Camera/gallery permissions, audio, video and cleanup | [media-apis.md](references/media-apis.md) |
+| Install/declare/require native modules and npm dependencies | [using-modules.md](references/using-modules.md) |
+| Logs, breakpoints, LiveView, build failures and profiling | [debugging-profiling.md](references/debugging-profiling.md) |
+| Navigation, Android Back, title bars, tabs and safe areas | [cross-platform-development.md](references/cross-platform-development.md) |
+| Native module development, Hyperloop and CLI build plugins | [extending-titanium.md](references/extending-titanium.md) |
+
+Use `ti-api` for exact signatures, `ti-guides` for project/toolchain/distribution configuration, and `alloy-guides` / `alloy-howtos` for Alloy MVC and CLI tasks. For details not published in current guides, consult their linked current reference; do not infer a complete recipe from a historical example.
+
+## Essential checks
+
+- Request the feature's permission and supply the matching iOS usage descriptions before using it. Handle denial and cancellation.
+- Remove global/location listeners and release owned media resources when the feature closes.
+- Handle both HTTP success and failure, malformed JSON, timeouts and server status; register callbacks before `open()`.
+- Bind SQL values and close result sets/databases after the operation completes.
+- Android notification permission and FCM token registration are separate operations; `ti.playservices` alone is not an FCM integration.
+- Native configuration/module changes require a real build; LiveView is for JavaScript iteration.

package/skills/ti-howtos/references/cross-platform-development.md

@@ -1,374 +1,169 @@
-# Cross-platform development
-
-Strategies for building Titanium apps that run on iOS and Android from a single codebase.
-
-<!-- TOC-START -->
-## Contents
-
-- [Philosophy](#philosophy)
-- [Platform identification](#platform-identification)
-- [Coding strategies](#coding-strategies)
-- [Platform-specific resources](#platform-specific-resources)
-- [5. Webpack build pipeline (TiSDK 9.1.0+)](#5-webpack-build-pipeline-tisdk-910)
-- [6. Internationalization (i18n)](#6-internationalization-i18n)
-- [Platform-specific APIs](#platform-specific-apis)
-- [Common cross-platform patterns](#common-cross-platform-patterns)
-- [Best practices](#best-practices)
-- [Resources](#resources)
-
-<!-- TOC-END -->
-
-## Philosophy
-
-### "Write once, adapt everywhere"
-Titanium is not "write once, run anywhere." It is "write once, adapt everywhere."
-
-Shared (90-100%):
-- Business logic
-- Networking code
-- Database operations
-- Event handling
-- Data models
-
-Different:
-- UI conventions (tab position, navigation)
-- Platform-specific features
-- Hardware capabilities
-- User expectations
-
-### Embrace the platform
-Good apps feel native on each platform:
-
-- iOS: bottom tabs, left navigation buttons, iOS-specific controls
-- Android: top tabs, Menu button (legacy), Action Bar, Material Design
-
-Develop for both platforms from day one. It is much easier than porting later.
-
-### Android platform key concepts
-- Screen sizes: small, normal, large, xlarge (measured in dp). Use density-independent resources.
-- Screen densities: ldpi (~120 dpi), mdpi (~160 dpi), hdpi (~240 dpi), xhdpi (~320 dpi), xxhdpi (~480 dpi), xxxhdpi (~640 dpi)
-- Activities: each heavyweight Window maps to an Android Activity. Titanium manages the Activity lifecycle.
-- Intents: for inter-app and intra-app communication. See `android-platform-deep-dives.md`.
-- Back button: hardware/software back closes the current Window by default. Override with `window.addEventListener('androidback', ...)`.
-
-### iOS platform key concepts
-- Human Interface Guidelines: Apple enforces design standards through App Store review. Follow iOS conventions for navigation, tab bars, and gestures.
-- One-button design: no hardware back or menu buttons. All navigation must be in the UI (NavigationWindow, back buttons).
-- Frameworks: Titanium wraps UIKit, Foundation, MapKit, and other Cocoa Touch frameworks. Use Hyperloop for additional frameworks.
-- Developer account: requires a paid Apple Developer Program membership for device testing and App Store distribution.
-
-## Platform identification
-
-### Platform properties
-
-```javascript
-// Platform name
-Ti.Platform.name          // "iPhone OS", "android", "mobileweb"
-Ti.Platform.osname        // "iphone", "ipad", "android", "mobileweb"
-Ti.Platform.model         // "iPhone 15", "Pixel 8", etc.
-```
-
-### Best practice: cache platform checks
-
-```javascript
-// Create aliases - query once, use many times
-const osname = Ti.Platform.osname;
-const isAndroid = (osname === 'android');
-const isIOS = (osname === 'iphone' || osname === 'ipad');
-const isMobileWeb = (osname === 'mobileweb');
-```
-
-### Anti-pattern: do not assume binary
-
-```javascript
-// BAD: Assumes if not Android, then iOS
-if (osname !== 'android') {
-  // Wrong! Could be mobile web or future platform
-}
-
-// GOOD: Explicit checks
-if (isAndroid) {
-  // Android code
-} else if (isIOS) {
-  // iOS code
-}
-```
+# Platform conventions
 
-## Coding strategies
+Based on the [current official guide](https://titaniumsdk.com/docs/build/ui/platform-conventions.md). Examples target released SDK 13.4.1; verify the selected SDK before adopting version-specific behavior.
 
-### 1. Branching (mostly similar code)
-Use when code is 90%+ the same with small differences.
+Titanium gives you one layout system and one API, and most of a screen is the
+same on both platforms. This page is for the places where that stops being
+true - where the platforms differ in *approach* rather than in a property name,
+and where writing one behaviour for both produces an app that feels wrong on
+one of them.
 
-```javascript
-const isAndroid = (Ti.Platform.osname === 'android');
-
-const win = Ti.UI.createWindow({
-  backgroundColor: 'white',
-  // Platform-specific property
-  softInputMode: isAndroid ? Ti.UI.Android.SOFT_INPUT_ADJUST_PAN : null
-});
-```
+Small differences are noted on the page they belong to. These are the
+structural ones.
 
-Tips:
-- Cache platform checks to avoid repeated bridge crossings
-- Group as much code as possible within branches
-- Defer loading to reduce performance impact
+## Navigating between screens
 
-### 2. Platform-specific files (mostly different code)
-Use when code differs significantly between platforms.
+**iOS stacks windows.** A `NavigationWindow` owns a stack, pushes a window on
+with `openWindow` and pops it with `closeWindow`, and draws a back button in
+the bar automatically.
 
-Structure:
-```
-Resources/
-├── ui.js              // Common code (optional)
-├── android/
-│   └── ui.js          // Android-specific (overrides)
-└── iphone/
-    └── ui.js          // iOS-specific (overrides)
-```
+**Android stacks activities.** Opening a window starts an activity, the
+hardware or gesture back closes it, and there is no navigation container to
+create.
 
-Usage:
-```javascript
-// Will automatically include the specific version
-const ui = require('ui');
-// Loads: /android/ui.js on Android, /iphone/ui.js on iOS
-```
+```js
+const android = Ti.Platform.osname === 'android';
 
-### 3. Execution contexts
-Titanium supports single-context and multi-context apps:
+const root = Ti.UI.createWindow({ title: 'List', backgroundColor: 'white' });
+const nav = android ? null : Ti.UI.createNavigationWindow({ window: root });
 
-- Single context (recommended): all windows share one JavaScript runtime. Use `require()` for modules and `Alloy.createController()` for views.
-- Multi-context (legacy): `Ti.UI.createWindow({ url: 'other.js' })` creates a separate JavaScript context. Variables are not shared between contexts.
-
-Avoid multi-context apps. Use CommonJS modules and `require()` instead. If you must communicate across contexts, use `Ti.App.fireEvent()` and `Ti.App.addEventListener()`.
-
-Avoid multiple contexts:
-```javascript
-// Creates a new context - variables from app.js are not available
-Ti.UI.createWindow({
-  url: 'window.js' // DO NOT DO THIS
-}).open();
-```
-
-Use instead:
-```javascript
-// Same context - all variables available
-const win = Ti.UI.createWindow({});
-require('window')(win);
-win.open();
-```
-
-## Platform-specific resources
-
-### Resource overrides system
+/** Opens a screen the way the platform expects. The one place that branches. */
+function push(win) {
+  if (nav) {
+    nav.openWindow(win);
+  } else {
+    win.open();
+  }
+}
 
-```javascript
-// Automatically uses the platform-specific version
-const image = Ti.UI.createImageView({
-  image: '/images/logo.png' // Will choose the correct file
+const open = Ti.UI.createButton({ title: 'Open detail' });
+open.addEventListener('click', () => {
+  push(Ti.UI.createWindow({ title: 'Detail', backgroundColor: 'white' }));
 });
-```
-
-### Assets (Alloy)
-
-```
-app/
-├── assets/
-│   └── images/
-│       └── logo.png      // Default
-├── assets/
-│   └── android/
-│       └── images/
-│           └── logo.png  // Android
-└── assets/
-    └── iphone/
-        └── images/
-            └── logo.png  // iOS
-```
-
-## 5. Webpack build pipeline (TiSDK 9.1.0+)
+root.add(open);
 
-Titanium's modern build engine optimizes packaging and allows using npm libraries natively.
-
-### `@` alias
-Use `@` to reference your code root regardless of the current folder depth.
-
-```javascript
-import MyModule from '@/utils/myModule'; // Points to app/lib or src
+(nav ?? root).open();
 ```
 
-### npm support
-Install any npm package in the project root and use it directly with `import`.
-
-For more details on optimization, diagnostics, and the build web UI, see `webpack-build-pipeline.md`.
-
-## 6. Internationalization (i18n)
+One `push` rather than a platform check at every call site.
 
-### i18n directory structure
-```
-i18n/
-├── en/
-│   ├── strings.xml      <!-- Default language -->
-│   └── app.xml          <!-- App name localization (Android) -->
-├── es/
-│   ├── strings.xml
-│   └── app.xml
-└── ja/
-    └── strings.xml
-```
+> [!IMPORTANT]
+> `NavigationWindow` exists on Android too, but using it there gives you an
+> iOS-shaped navigation inside an activity, and the system back button then
+> does not do what a user expects. Let Android use its own stack.
 
-Use ISO 639-1 language codes (en, es, ja) and optionally ISO 3166-1 region codes (en-GB, pt-BR).
+## The back button
 
-### strings.xml format
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<resources>
-  <string name="welcome_message">Welcome to my app</string>
-  <string name="login_button">Log In</string>
-</resources>
-```
+Android has one and iOS does not. That is a real difference in what a user can
+do, not a styling choice.
 
-### Using localized strings
+```js
+const win = Ti.UI.createWindow({ backgroundColor: 'white' });
+let unsaved = true;
 
-Basic usage:
-```javascript
-// Two equivalent methods
-const str1 = L('welcome_message');
-const str2 = Ti.Locale.getString('welcome_message');
+win.addEventListener('androidback', () => {
+  if (!unsaved) {
+    win.close();
+    return;
+  }
+  const ask = Ti.UI.createAlertDialog({
+    message: 'Discard changes?',
+    buttonNames: ['Cancel', 'Discard'],
+    cancel: 0
+  });
+  ask.addEventListener('click', (e) => {
+    if (e.index === 1) {
+      unsaved = false;
+      win.close();
+    }
+  });
+  ask.show();
+});
 
-// With a default fallback
-const withDefault = L('missing_key', 'Default text');
+win.open();
 ```
 
-In Alloy XML views, use `titleid` instead of `title`:
-```xml
-<Button titleid="login_button" />
-<Label textid="welcome_message" />
-```
+Adding an `androidback` listener replaces the default behaviour, so the window
+no longer closes unless you close it. That is the point of the event, and it is
+also the way to leave a user trapped on a screen if you forget the other
+branch.
 
-String formatting:
-```javascript
-// Simple replacement
-const formatted = String.format(L('format_test'), 'Kevin');
-// Result: "Your name is Kevin"
+The last window closing exits the app on Android. `exitOnClose` on the root
+window controls that.
 
-// Ordered replacement
-const formatted = String.format(L('ordered'), 'Jeff', 'Kevin');
-// Result: "Hi Jeff, my name is Kevin"
-```
+## Title bars
 
-### Localizing the app name
+iOS has a navigation bar owned by the stack; Android has an action bar owned by
+the activity. They take different properties.
 
-iOS (SDK 3.2.0+): set `<key>CFBundleDisplayName</key>` in `i18n/LANG/app.xml`
+| | iOS | Android |
+| --- | --- | --- |
+| Title | `Window.title` | `Window.title` |
+| Custom view | `Window.titleControl` | `ActionBar.customView` |
+| Hide it | `Window.navBarHidden` | `ActionBar.hide()` |
+| Back affordance | Automatic | `ActionBar.displayHomeAsUp` |
 
-Android: use `<string name="appname">Mi App</string>` in `i18n/LANG/strings.xml`
+`Window.title` is the one that works on both, which is why it is worth
+building screens that need nothing more.
 
-### Localizing images and files
+## Tabs
 
-Two approaches:
-1. Platform folders: place localized images in `app/assets/iphone/LANG.lproj/` (iOS) or `app/assets/android/images/` with language qualifiers (Android)
-2. Code-based: load different assets based on `Ti.Locale.currentLanguage`
+`TabGroup` is the same object on both platforms and lands in different places:
+a bottom tab bar on iOS, and tabs the platform places according to its own
+version on Android. Both are correct for their platform.
 
-### Date and currency formatting
+Use the tab behavior appropriate to the product and platform; do not treat a preferred tab position as an API restriction.
 
-```javascript
-// Date formatting
-const today = new Date();
-const dateStr = String.formatDate(today, 'long');
-const timeStr = String.formatTime(today, 'short');
+Three to five tabs. Both platforms handle more badly, in different ways.
 
-// Currency
-const price = String.formatCurrency(1234.56);
+## Menus and actions
 
-// Decimal
-const amount = String.formatDecimal(1234.56);
-```
+iOS puts secondary actions in the navigation bar or a toolbar. Android has an
+options menu in the action bar's overflow.
 
-Warning (Android): `String.formatDate()` may produce incorrect translations or field ordering on some Android versions. Consider using JavaScript `Date` methods as a workaround.
+There is no shared abstraction over the two. Either put the action somewhere
+that exists on both - a button in the content - or write the platform-specific
+version of each and pick with a check.
 
-### Testing localizations
+## Safe areas and system bars
 
-iOS:
-1. Settings → General → Language & Region
-2. Change iPhone Language
-3. Confirm and restart device
+iOS content runs under the notch and the home indicator unless told otherwise.
+`extendSafeArea` on the window controls it, and is a creation property. In SDK 13.4.1 its default is `true` on iOS (content extends under system/physical obstructions) and `false` on Android; choose and verify the required safe-area behavior explicitly.
 
-Android:
-1. Settings → Language & input
-2. Select Language
+Android draws behind the status bar in some themes and not others. Set
+`theme` on the window to choose.
 
-## Platform-specific APIs
+Test both on hardware with a notch or a cutout. A simulator in the default
+device rarely shows the problem.
 
-### Example: platform-specific properties
+## Which platform am I on
 
-```javascript
-const win = Ti.UI.createWindow({
-  // iOS-specific
-  barColor: isIOS ? '#007AFF' : null,
-  titlePrompt: isIOS ? 'Title' : null,
-
-  // Android-specific
-  softInputMode: isAndroid ? Ti.UI.Android.SOFT_INPUT_ADJUST_PAN : null,
-  exitOnClose: isAndroid ? true : false
-});
+```js
+if (Ti.Platform.osname === 'android') { /* ... */ }
 ```
 
-## Common cross-platform patterns
-
-### Tab groups
-
-```javascript
-const tabGroup = Ti.UI.createTabGroup();
-
-const tab1 = Ti.UI.createTab({
-  title: 'Tab 1',
-  icon: isIOS ? 'tab1.png' : null, // iOS uses icons
-  window: win1
-});
-
-tabGroup.addTab(tab1);
-tabGroup.open();
-```
+`Ti.Platform.osname` is `'android'`, `'iphone'` or `'ipad'` - so a test for iOS
+has to accept two values. In Alloy, `OS_IOS` and `OS_ANDROID` are compile-time
+constants and the branch not taken is removed from the build rather than
+evaluated at runtime.
 
-### Navigation
+In TSS and XML, a platform attribute does the same:
 
-```javascript
-if (isIOS) {
-  // iOS: navigation window with back button
-  const nav = Ti.UI.iOS.createNavigationWindow({
-    window: win
-  });
-  nav.open();
-} else if (isAndroid) {
-  // Android: open window, use physical button
-  win.open();
-}
+```xml
+<Alloy>
+  <Window>
+    <Button platform="android" title="Android only" />
+  </Window>
+</Alloy>
 ```
 
-### Platform-specific event handling
-
-```javascript
-if (isAndroid) {
-  // Android: handle physical Back button
-  win.addEventListener('androidback', (e) => {
-    // Custom behavior
-    alert('Back pressed!');
-  });
-}
-```
+Prefer those to a runtime check when the difference is layout rather than
+behaviour: the code for the other platform never ships.
 
-## Best practices
+![Two boxed screenshots labelled iOS and Android, one above the other, each showing the detail screen of the same app. On iOS a back chevron labelled Notes sits at the left of the navigation bar, with the title Shopping list centred. On Android a plain left arrow sits at the left of the action bar, with the title beside it rather than centred.](https://titaniumsdk.com/docs/guides/back-affordance.png)
 
-1. Test early on both platforms. Do not wait until "porting time".
-2. Use Alloy. It provides MVC structure and platform abstraction.
-3. Follow platform conventions. iOS apps should feel like iOS, Android like Android.
-4. Cache platform checks. Store in variables, do not call `Ti.Platform.osname` repeatedly.
-5. Use CommonJS modules. Better code organization and reuse.
-6. Leverage resource overrides. Avoid conditional code for images and assets.
-7. Think cross-platform from the design phase. UI should adapt gracefully.
+## Next
 
-## Resources
+[Working with data](https://titaniumsdk.com/docs/build/data.md) covers storing things between launches.
 
-- Alloy Framework - MVC framework for Titanium (see alloy-guides skill)
-- CommonJS Modules - module specification (see coding strategies above)
-- Platform API deep dives - iOS and Android platform-specific features
+Contract correction: [released Window safe-area defaults](https://github.com/tidev/titanium-sdk/blob/13_4_1_GA/apidoc/Titanium/UI/Window.yml).