@maccesar/titools 3.3.0 → 4.1.0

package/skills/ti-expert/SKILL.md

@@ -149,7 +149,7 @@ For the complete reference with examples, see [Alloy builtins and globals](refer
 - [Contracts & Communication](references/contracts.md)
 - [State Management](references/state-management.md)
 - [Anti-patterns to Avoid](references/anti-patterns.md)
-- [Adaptive Layouts](references/adaptive-layouts.md) (responsive breakpoints, tablet/foldable/desktop support, Android 17 resizability compliance)
+- [Adaptive Layouts](references/adaptive-layouts.md) (responsive breakpoints, tablet/foldable/desktop support, Android 16/17 resizability compliance, orientation locks and which Android activities they must cover)
 
 ### Implementation & API
 - [Alloy Builtins & Globals](references/alloy-builtins.md)

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

@@ -19,6 +19,26 @@ Scope: Only affects screens >= 600dp. Phones (< 600dp) and games (`android:appCa
 
 What this means: portrait-only apps will be forced into landscape/resized on large screens. If the UI doesn't support it, it will break.
 
+### It already started in Android 16 (API 36)
+
+This is usually described as an API 37 change, but it lands one release earlier: an app
+targeting **API 36** already has `android:screenOrientation` ignored on >= 600dp displays
+running Android 16. The difference is that API 36 still ships an opt-out:
+
+```xml
+<!-- inside <application>, or on an individual <activity> -->
+<property
+  android:name="android.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY"
+  android:value="true"/>
+```
+
+The opt-out stops working the moment you target API 37, so treat it as a bridge while the
+layout is made adaptive — not as a fix. Source: [Android 16 behavior changes](https://developer.android.com/about/versions/16/behavior-changes-16).
+
+Worth knowing when debugging: this only kicks in at >= 600dp. If a **phone** is rotating
+despite a portrait lock, the cause is in the app, not in Android — see the orientation
+debugging recipe in section 7.
+
 ### Related: edge-to-edge (API 36)
 
 Before the resizability requirement (API 37), Android SDK 36 removes the opt-out for edge-to-edge rendering, causing Titanium layouts to overlap system navigation bars. The Titanium core team has a PR to handle this at the SDK level: tidev/titanium-sdk#14399 — adds an `EdgeToEdgeHelper` with correct padding so existing apps work without code changes.
@@ -343,6 +363,24 @@ const dpWidth = $.win.size.width / density  // WRONG: halves the value
 Ti.Gesture.isPortrait()   // TypeError!
 Ti.Gesture.portrait       // correct — boolean property
 
+// ❌ Setting orientation imperatively — silently overrides the manifest
+$.win.activity.requestedOrientation = Ti.Android.SCREEN_ORIENTATION_PORTRAIT
+// The manifest value is applied in onCreate; this runs afterwards and always wins.
+// Nothing in tiapp.xml can beat it, which makes it invisible when debugging.
+// Declare `orientationModes` on the window instead (see section 7).
+
+// ❌ Detecting tablets with a pixel threshold
+Math.min(displayCaps.platformWidth, displayCaps.platformHeight) >= 600
+// platformWidth returns PIXELS on Android. A 720x1604 @xhdpi phone is 360dp wide,
+// but 720 >= 600 reports "tablet". Use Alloy.isTablet / the formFactor query, which
+// read Ti.Platform.Android.physicalSizeCategory instead of raw pixels.
+
+// ❌ Passing an empty orientationModes array to mean "no preference"
+orientationModes: []
+// An empty array maps to SCREEN_ORIENTATION_SENSOR (TiWindowProxy.setOrientationModes),
+// so it doesn't clear the setting — it actively unlocks rotation, overriding the manifest.
+// To leave orientation alone, don't set the property at all.
+
 // ❌ Using gap property — does NOT exist in Titanium
 { layout: 'horizontal', gap: 10 }
 
@@ -373,7 +411,129 @@ Titanium generates the main activity name as `<app-id>.<Appname>Activity`. For e
 </android>
 ```
 
-To verify the exact generated activity name, check `build/android/AndroidManifest.xml` after a build.
+To verify the exact generated activity name, check `build/android/app/src/main/AndroidManifest.xml` after a build.
+
+### Which activities a lock has to cover
+
+`android:screenOrientation` is per-activity — it is not inherited from `<application>`. Every
+window the app opens runs inside one of a small, fixed set of activities declared by the
+Titanium AAR, so read the canonical list from the SDK instead of memorising it:
+
+```bash
+cat ~/.gradle/caches/*/transforms/*/transformed/jetified-titanium-*/AndroidManifest.xml
+```
+
+As of 13.4.0 there are exactly six, and `android:name` takes the fully-qualified form:
+
+```
+org.appcelerator.titanium.TiActivity
+org.appcelerator.titanium.TiTranslucentActivity
+ti.modules.titanium.media.TiCameraActivity
+ti.modules.titanium.media.TiCameraXActivity
+ti.modules.titanium.media.TiVideoActivity
+ti.modules.titanium.ui.android.TiPreferencesActivity
+```
+
+The seventh is the app's own root activity, generated from the `<name>` in tiapp.xml (see the
+derivation rule above). Which one hosts what:
+
+| What the app does | Activity |
+|---|---|
+| `Window.open()`, Tab, TabGroup, NavigationWindow | `org.appcelerator.titanium.TiActivity` |
+| Window with `modal:true`, `opacity`, or a `backgroundColor` with alpha < 255 | `org.appcelerator.titanium.TiTranslucentActivity` |
+| `showCamera({ overlay })` | `ti.modules.titanium.media.TiCameraActivity` (`TiCameraXActivity` when `useCameraX:true`) |
+| `showCamera()` with no overlay | none of yours — Titanium launches the system camera app |
+| VideoPlayer added to a regular Window | `org.appcelerator.titanium.TiActivity` |
+
+Two things are better left undeclared:
+
+- **`android:configChanges`.** The CLI strips it before the merge even happens — `_build.js`
+  keeps a list of the `TiBaseActivity`-derived activities and calls
+  `removeActivityAttribute(name, 'android:configChanges')` on each, with the reason spelled out
+  in the source: *"Most devs don't set this right, causing UI to disappear when a config change
+  occurs for a missing setting."* So a hand-written subset is not dangerous, just dead weight —
+  Titanium's full list always wins.
+- **A lock on `TiTranslucentActivity`.** Android 8–11 throws `IllegalStateException` ("Only
+  fullscreen opaque activities can request orientation") when a translucent activity requests a
+  fixed orientation. Declaring `orientationModes` on those windows is safer: the SDK applies it
+  inside a try/catch (`TiWindowProxy.setOrientationModes`), so the worst case is a modal that
+  rotates instead of an app that crashes.
+
+### Prefer orientationModes over the manifest
+
+`orientationModes` is defined on `TiWindowProxy`, so the same declaration works on `Window`,
+`TabGroup` and `NavigationWindow`. Being per-window it also composes with form-factor queries,
+which is what you usually want:
+
+```xml
+<!-- PurgeTSS -->
+<TabGroup class="handheld:portrait tablet:landscape">
+```
+
+```tss
+/* plain TSS equivalent */
+'#tabs[formFactor=handheld]': { orientationModes: [ Ti.UI.PORTRAIT ] }
+```
+
+Alloy resolves `formFactor` from `Ti.Platform.Android.physicalSizeCategory`, which is why this
+is more reliable than any width comparison you could write yourself.
+
+Keep the manifest for what Alloy cannot reach: the root activity, which shows the splash before
+any JS runs, and optionally `TiActivity` as a blanket fallback for windows that carry no class.
+
+A single Ti Element rule covers every window in the app without touching a single view, which
+is usually all an Alloy app needs:
+
+```javascript
+// purgetss/config.cjs
+module.exports = {
+  theme: { extend: {} },
+  'Window': { handheld: { apply: 'portrait' } }
+}
+```
+
+```tss
+/* generated — applies to every Window, including modal ones */
+'Window[formFactor=handheld]': { orientationModes: [ Ti.UI.PORTRAIT ] }
+```
+
+Note it matches `Window` only, so a `TabGroup` still needs its own class. And because the
+declaration is per-window, it does nothing for the splash — that one stays in the manifest.
+
+### Debugging a rotation that shouldn't happen
+
+Ask the system for the effective value instead of re-reading the manifest:
+
+```bash
+adb shell dumpsys activity activities | grep -E "topResumedActivity|requestedOrientation"
+```
+
+If `requestedOrientation` disagrees with what tiapp.xml declares, something overrode it at
+runtime — grep the app for `requestedOrientation` and `orientationModes` before touching the
+manifest again. Note that an *existing* `orientationModes` can be the bug rather than the fix:
+an empty array unlocks rotation (see the anti-patterns above).
+
+Before blaming the OS, let the SDK tell you. Titanium logs a warning when Android drops the
+request on a large screen, so this either hits or rules that cause out immediately:
+
+```bash
+adb logcat | grep "Orientation request will be ignored"
+# Fixed orientation is not supported on large screens (smallest width: <N>dp).
+# Orientation request will be ignored on Android 16+.
+```
+
+And to see the size bucket the device actually reports — `normal` means a phone, so the >= 600dp
+rule does not apply and the cause is in the app:
+
+```bash
+adb shell am get-config    # e.g. ...-sw360dp-w360dp-h802dp-normal-...
+```
+
+To confirm what actually shipped in the binary:
+
+```bash
+aapt2 dump xmltree --file AndroidManifest.xml <apk> | grep -A2 "E: activity"
+```
 
 ### iOS: support all orientations on iPad
 
@@ -405,6 +565,9 @@ To verify the exact generated activity name, check `build/android/AndroidManifes
 | Device screen size | `Ti.Platform.displayCaps.platformWidth` — pixels on Android, needs `/logicalDensityFactor` |
 | Orientation (boolean) | `Ti.Gesture.portrait`, `Ti.Gesture.landscape` — properties, not methods |
 | Orientation event | `Ti.Gesture.addEventListener('orientationchange', handler)` |
+| Lock orientation | `orientationModes` on the window — not `activity.requestedOrientation` |
+| Tablet detection | `Alloy.isTablet` / `[formFactor=tablet]` — never a pixel threshold |
+| Effective orientation at runtime | `adb shell dumpsys activity activities \| grep requestedOrientation` |
 | Window resize event | `$.win.addEventListener('postlayout', handler)` — fires on rotation, split-screen, resize |
 | Auto-size | `Ti.UI.SIZE` (fit content), `Ti.UI.FILL` (fill remaining) |
 | Percentages | `width: '50%'` relative to parent |

package/skills/ti-guides/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: ti-guides
+description: 'Use when working on Titanium SDK fundamentals: project configuration (`tiapp.xml`, `timodule.xml`), CommonJS modules, Hyperloop native access, app distribution (App Store / Google Play, certificates, provisioning), Titanium CLI usage, memory management, bridge optimization, SQLite transactions, image memory, or coding standards. Triggers include `tiapp.xml` in the project root, for either Alloy (`app/`) or Classic (`Resources/`) Titanium projects.'
+---
+
+# ti-guides
+
+## Overview
+
+Reference for Titanium SDK fundamentals: project configuration, distribution, native access via Hyperloop, CommonJS module patterns, memory and bridge optimization, and TiDev coding standards. Applies to both Alloy and Classic projects.
+
+## When to use
+
+Use this skill when:
+
+- The project contains `tiapp.xml` (definitive Titanium project indicator)
+- Configuring `tiapp.xml` or `timodule.xml`
+- Setting up app distribution (App Store / Google Play, certificates, provisioning, AAB / IPA)
+- Using Hyperloop to call native APIs (Objective-C / Swift / Java)
+- Optimizing memory: removing global listeners, caching native properties, image memory footprints
+- Working with the Titanium CLI (`ti build`, `ti sdk install`, `ti sdk select`)
+- Writing CommonJS modules (stateful caching, ES6+ patterns, antipatterns)
+- Authoring `AndroidManifest.xml` overrides
+- Following TiDev style and naming conventions
+
+Do NOT use for:
+
+- Alloy MVC concepts, controllers, models (use `alloy-guides`)
+- Alloy CLI usage and configuration files (use `alloy-howtos`)
+- Looking up specific Titanium API surfaces (use `ti-api`)
+- Native module dependency updates (use `ti-module-update`)
+
+## Quick reference
+
+| Topic | Reference |
+|---|---|
+| Project creation, structure, getting started (Alloy or Classic) | [hello-world.md](references/hello-world.md) |
+| JavaScript fundamentals, learning resources, ES6+ features | [javascript-primer.md](references/javascript-primer.md) |
+| Alloy vs Classic Titanium, framework selection | [application-frameworks.md](references/application-frameworks.md) |
+| Memory leaks, bridge efficiency, event naming, security, lazy loading | [coding-best-practices.md](references/coding-best-practices.md) |
+| Stateful modules, caching, ES6+ support, antipatterns | [commonjs-advanced.md](references/commonjs-advanced.md) |
+| SQLite transactions and image memory optimization | [advanced-data-and-images.md](references/advanced-data-and-images.md) |
+| Hyperloop: Objective-C / Swift / Java syntax, casting, debugging, XIB / Storyboards | [hyperloop-native-access.md](references/hyperloop-native-access.md) |
+| Naming standards and formatting rules | [style-and-conventions.md](references/style-and-conventions.md) |
+| ECMAScript, iOS, and Alloy reserved keywords to avoid | [reserved-words.md](references/reserved-words.md) |
+| Custom `AndroidManifest.xml`, permissions, manifest merge | [android-manifest.md](references/android-manifest.md) |
+| Google Play (APK / AAB), App Store (IPA), certificates, provisioning, deployment | [app-distribution.md](references/app-distribution.md) |
+| Complete `tiapp.xml` and `timodule.xml` reference | [tiapp-config.md](references/tiapp-config.md) |
+| Titanium CLI commands, options, tasks, configuration, build processes | [cli-reference.md](references/cli-reference.md) |
+| Community support, modules, sample code, Slack, learning materials | [resources.md](references/resources.md) |
+
+## Core practices
+
+1. Validate that the project follows a modular pattern (CommonJS or Alloy).
+2. Ensure global listeners are removed and heavy objects are nulled during cleanup.
+3. Cache frequently accessed native properties to reduce bridge crossings.
+4. Use Hyperloop for specialized native functionality and handle casting and threading correctly.
+5. Use transactions for database work and manage image memory footprints.
+
+## Procedural rules
+
+- Always remove `Ti.App` and `Ti.Geolocation` listeners during controller cleanup.
+- Do not access `Ti.Platform` or `Ti.DisplayCaps` inside loops. Store values in local variables.
+- Concatenate Hyperloop selectors accurately (for example, `addAttribute:value:range:` → `addAttributeValueRange`).
+- Close result sets and database handles after every transaction block.
+
+## Response format
+
+When answering Titanium SDK questions:
+
+1. **Technical recommendation** — cite the specific TiDev best practice.
+2. **Optimized implementation** — provide modern ES6+ code.
+3. **Rationale** — briefly explain the performance or memory impact.
+
+## Related skills
+
+| Task | Use this skill |
+|---|---|
+| Alloy MVC concepts, controllers, models, data binding | `alloy-guides` |
+| Alloy CLI, `alloy.jmk`, `config.json`, debugging | `alloy-howtos` |
+| Titanium API lookup (Ti.UI, Ti.Network, modules) | `ti-api` |
+| Native module dependency updates | `ti-module-update` |

package/skills/ti-guides/references/advanced-data-and-images.md

@@ -0,0 +1,155 @@
+# Advanced database and image best practices
+
+## 1. SQLite optimization
+
+- Close result sets and the database after each operation to avoid locks and memory growth. SQLite allows one writer at a time, and leaving a connection open after `INSERT` or `UPDATE` can trigger `DatabaseObjectNotClosed` on the next write.
+- Use transactions for batch inserts. If any statement fails, SQLite rolls back the entire batch.
+  ```javascript
+  const db = Ti.Database.open('myDatabase');
+  db.execute('BEGIN');
+  for (const item of playlist) {
+    db.execute('INSERT INTO albums (disc, artist, rating) VALUES (?, ?, ?)', item.disc, item.artist, item.rating);
+  }
+  db.execute('COMMIT');
+  db.close();
+  ```
+- Do not ship large pre-populated databases. Ship a small skeleton and download data on first boot to reduce IPA/APK size. The `Resources` directory is read-only, so installing a database copies it to `applicationDataDirectory`, which creates two copies on the device.
+  - Android note: in Android 2.2 and earlier, the installer could not uncompress assets over 1 MB. One workaround was to rename the file with a `.mp3` extension to prevent `aapt` compression.
+  - Pattern for downloading a replacement database on first boot:
+  ```javascript
+  const updateDatabase = (newData) => {
+    // delete existing content and rehydrate from downloaded JSON
+  }
+  downloadButton.addEventListener('click', () => {
+    const client = Ti.Network.createHTTPClient({
+      timeout: 10000,
+      onload() {
+        updateDatabase(this.responseData)
+        Ti.UI.createAlertDialog({ title: 'Info', message: 'Database installed' }).show()
+      },
+      onerror(e) {
+        Ti.UI.createAlertDialog({ title: 'Error', message: e.error }).show()
+      }
+    })
+    client.open('GET', 'https://example.com/data.json')
+    client.send()
+  })
+  ```
+
+### Database version management
+
+Store a version number in your database so you can detect upgrades and run migrations. If you do not have a version table, use `PRAGMA TABLE_INFO` to detect column presence:
+
+```javascript
+const addColumn = (dbname, tblName, newFieldName, colSpec) => {
+  const db = Ti.Database.open(dbname);
+  let fieldExists = false;
+  const resultSet = db.execute(`PRAGMA TABLE_INFO(${tblName})`);
+  while (resultSet.isValidRow()) {
+    if (resultSet.field(1) === newFieldName) {
+      fieldExists = true;
+    }
+    resultSet.next();
+  }
+  resultSet.close();
+  if (!fieldExists) {
+    db.execute(`ALTER TABLE ${tblName} ADD COLUMN ${newFieldName} ${colSpec}`);
+  }
+  db.close();
+};
+```
+
+---
+
+## 2. Image format selection
+
+Choose the right format for each use case:
+
+| Format | Compression           | Best for                       | Avoid for                                                          |
+| ------ | --------------------- | ------------------------------ | ------------------------------------------------------------------ |
+| PNG    | Lossless              | Icons, text, line art, buttons | Photos (large files)                                               |
+| JPG    | Lossy                 | Photographs                    | Text, icons, line drawings (artifacts)                             |
+| GIF    | Lossless (256 colors) | Rare cases                     | Most cases (limited colors, animated GIF not supported everywhere) |
+
+For flip-book animations, use `ImageView.images` with an array of PNG or optimized JPG files instead of animated GIFs.
+
+---
+
+## 3. Image memory management
+
+- A JPG is small on disk but expands to `width * height * 3 bytes` in RAM. Each pixel uses 24 bits (8 bits per R/G/B channel).
+  - Example: `(640 × 480 × 3) / 1024 = 900 KB` in memory for a single image
+  - Device RAM available to your app can be as low as 12 MB, shared with your code and the Titanium framework
+- Unloading:
+  - `view.remove(imageView)` removes it from the view hierarchy and lets the OS free memory
+  - `imageView = null` releases the native proxy object
+- Resizing: resize images to their display dimensions using `imageAsResized` or `imageAsCropped` (both on `Ti.Blob`) before setting the `image` property. Do not display a 1024×768 image on a 640×480 screen.
+- Placeholder: set `defaultImage` on ImageView to show a local placeholder while a remote image downloads:
+  ```javascript
+  const imageView = Ti.UI.createImageView({
+    image: 'https://example.com/photo.jpg',
+    defaultImage: '/images/placeholder.png',
+    width: 300,
+    height: 200
+  });
+  ```
+
+---
+
+## 4. Image optimization tools
+
+Resize and compress images before including them in your app to reduce IPA/APK size and network usage.
+
+| Platform            | File types    | Tool        |
+| ------------------- | ------------- | ----------- |
+| Mac                 | PNG, JPG, GIF | ImageOptim  |
+| Mac, Windows, Linux | PNG, JPG, GIF | ImageMagick |
+| Windows/DOS         | PNG           | PNGCrush    |
+| Windows             | JPG           | Nikkho      |
+
+---
+
+## 5. Caching remote images
+
+Remote images are cached automatically on iOS, Android, and Windows.
+
+Platform differences:
+- Android: cache limited to 25 MB, persists for the lifetime of the app (while installed)
+- iOS: cache size not fixed, cleared by iOS when the device needs storage
+
+To manually clean the cache, delete files in `applicationCacheDirectory`.
+
+Android 6+ requirement: call `Ti.Filesystem.requestStoragePermissions()` before loading remote images.
+
+### Manual caching utility
+
+For critical assets, cache manually in `applicationDataDirectory` for more predictable behavior:
+
+```javascript
+const CacheUtils = {
+  getExtension: (fn) => {
+    const match = /(?:\.([^.]+))?$/.exec(fn);
+    return match[1] || '';
+  },
+
+  createCachedImageView: (options) => {
+    const md5 = Ti.Utils.md5HexDigest(options.image) + CacheUtils.getExtension(options.image);
+    const savedFile = Ti.Filesystem.getFile(Ti.Filesystem.applicationDataDirectory, md5);
+
+    if (savedFile.exists()) {
+      options.image = savedFile;
+      return Ti.UI.createImageView(options);
+    }
+
+    const imageView = Ti.UI.createImageView(options);
+    const saveImage = () => {
+      imageView.removeEventListener('load', saveImage);
+      savedFile.write(
+        Ti.UI.createImageView({ image: imageView.image, width: Ti.UI.FILL, height: Ti.UI.FILL }).toImage()
+      );
+    };
+    imageView.addEventListener('load', saveImage);
+    return imageView;
+  }
+};
+```

package/skills/ti-guides/references/android-manifest.md

@@ -0,0 +1,97 @@
+# Custom AndroidManifest.xml
+
+For most Android manifest settings, use `tiapp.xml`. Only create a custom manifest when you really need it.
+
+## Preferred method: tiapp.xml
+
+Add manifest entries in `tiapp.xml` inside the `<android>` section:
+
+```xml
+<android xmlns:android="http://schemas.android.com/apk/res/android">
+    <manifest>
+        <!-- SDK version -->
+        <uses-sdk android:minSdkVersion="21" android:targetSdkVersion="34" />
+
+        <!-- Screen support -->
+        <supports-screens
+            android:smallScreens="false"
+            android:normalScreens="true"
+            android:largeScreens="true"
+            android:xlargeScreens="true"
+        />
+
+        <!-- Permissions -->
+        <uses-permission android:name="android.permission.CAMERA" />
+        <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
+
+        <!-- Application attributes (merged, not replaced) -->
+        <application android:debuggable="true" />
+    </manifest>
+</android>
+```
+
+## How merging works
+
+- Most elements are replaced by your entry.
+- The `<application>` element is merged additively by attribute.
+- Activities and services are added to existing ones.
+
+## Custom manifest (rare cases)
+
+If you need full control, create `platform/android/AndroidManifest.xml`:
+
+```
+MyApp/
+├── app/
+├── platform/
+│   └── android/
+│       └── AndroidManifest.xml  # Custom manifest
+└── tiapp.xml
+```
+
+Warning: you must maintain this file manually through SDK updates.
+
+## Common use cases
+
+### Camera permission
+```xml
+<uses-permission android:name="android.permission.CAMERA" />
+```
+
+### Hardware requirements
+```xml
+<uses-feature android:name="android.hardware.camera" android:required="false" />
+```
+
+### Launch mode
+```xml
+<application android:launchMode="singleTask" />
+```
+
+### Deep links
+```xml
+<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="myapp" android:host="path" />
+</intent-filter>
+```
+
+## Debugging
+
+To see the generated manifest:
+```bash
+ti build -p android
+# Check: build/android/AndroidManifest.xml.gen
+```
+
+## Enable manifest merge (CLI 7.0+)
+
+If you use a custom manifest, enable merge in `tiapp.xml`:
+
+```bash
+ti config android.mergeCustomAndroidManifest true
+```
+
+This merges your custom manifest with the generated one instead of replacing it.