@maccesar/titools 3.3.0 → 4.0.0

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.