@maccesar/titools 2.2.11 → 2.3.0

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

@@ -4,107 +4,90 @@
 
 **NEVER store tokens in:** `Ti.App.Properties` (plaintext), localStorage, or files.
 
-**USE platform-specific secure storage:**
+**USE the `ti.identity` module** — it handles iOS Keychain and Android Keystore through a unified API. Both platforms use `Identity.createKeychainItem()`.
 
 ```javascript
 // lib/services/tokenStorage.js
+const Identity = require('ti.identity')
+
+// Create a keychainItem once per identifier
+function createItem(identifier) {
+  return Identity.createKeychainItem({ identifier })
+}
+
 exports.TokenStorage = {
   save(token) {
-    if (Ti.Platform.osname === 'android') {
-      // Use Android KeyStore
-      const keyStore = Ti.Android.createKeyStore({
-        name: 'SecureKeyStore'
-      })
-      keyStore.addEntry('authToken', token)
-    } else {
-      // Use iOS Keychain
-      Ti.KeychainItem.setItem({
-        identifier: 'authToken',
-        value: token,
-        accessGroup: 'com.yourapp.keychain'
+    return new Promise((resolve, reject) => {
+      const item = createItem('authToken')
+      item.addEventListener('save', (e) => {
+        e.success ? resolve() : reject(new Error(e.error))
       })
-    }
+      item.save(token)
+    })
   },
 
   get() {
-    if (Ti.Platform.osname === 'android') {
-      const keyStore = Ti.Android.createKeyStore({
-        name: 'SecureKeyStore'
+    return new Promise((resolve, reject) => {
+      const item = createItem('authToken')
+      item.addEventListener('read', (e) => {
+        e.success ? resolve(e.value) : reject(new Error(e.error))
       })
-      return keyStore.getEntry('authToken')
-    } else {
-      return Ti.KeychainItem.getItem({
-        identifier: 'authToken',
-        accessGroup: 'com.yourapp.keychain'
-      })
-    }
+      item.read()
+    })
   },
 
   clear() {
-    if (Ti.Platform.osname === 'android') {
-      const keyStore = Ti.Android.createKeyStore({
-        name: 'SecureKeyStore'
-      })
-      keyStore.removeEntry('authToken')
-    } else {
-      Ti.KeychainItem.removeItem({
-        identifier: 'authToken',
-        accessGroup: 'com.yourapp.keychain'
+    return new Promise((resolve, reject) => {
+      const item = createItem('authToken')
+      item.addEventListener('reset', (e) => {
+        e.success ? resolve() : reject(new Error(e.error))
       })
-    }
+      item.reset()
+    })
   }
 }
 ```
 
+> Verified against official `ti.identity` module docs. `Identity.createKeychainItem({identifier})` is the cross-platform API — it maps to iOS Keychain and Android Keystore automatically. `Ti.Android.createKeyStore()` and `Ti.KeychainItem.setItem()` do NOT exist.
+
 ## Certificate pinning
 
-Prevent man-in-the-middle attacks by pinning SSL certificates:
+Prevent man-in-the-middle attacks by pinning SSL certificates using the **`ti.https` module** (community module — not built into the SDK):
 
 ```javascript
 // lib/api/pinnedClient.js
-exports.createPinnedClient = function() {
-  const client = Ti.Network.createHTTPClient({
-    // Security: Enable certificate pinning
-    certificatePinning: true,
+// Requires: ti.https module — install via npm or tiapp.xml modules section
+const HTTPS = require('ti.https')
+
+const securityManager = HTTPS.createX509CertificatePinningSecurityManager([
+  {
+    url: 'https://api.example.com',
+    serverCertificate: Ti.Filesystem.getFile(
+      Ti.Filesystem.resourcesDirectory, 'certificates/api-pin.pem'
+    ).read()
+  }
+])
 
-    // Specify allowed certificates
+exports.createPinnedClient = function(options = {}) {
+  return Ti.Network.createHTTPClient({
+    securityManager,           // must be set at creation time
     validatesSecureCertificate: true,
-
-    onload: () => {
-      // Success
-    },
-
-    onerror: (e) => {
-      // Certificate validation failed
-      if (e.error.indexOf('certificate') >= 0) {
-        Ti.API.error('Certificate pinning failed - possible MITM attack')
-      }
-    }
+    timeout: 10000,
+    ...options
   })
-
-  return client
 }
 ```
 
-**Add certificates to tiapp.xml:**
-
-```xml
-<ti:app>
-  <certificates>
-    <certificate>
-      <name>api.example.com</name>
-      <type>rsa</type>
-      <file>certificates/api-pin.pem</file>
-    </certificate>
-  </certificates>
-</ti:app>
-```
+> `certificatePinning: true` is NOT a valid `HTTPClient` property. Certificate pinning requires the `ti.https` module and must be set via the `securityManager` property when creating the client. Note that the `validatesSecureCertificate` property of `HTTPClient` is not honored for pinned URLs — the security manager takes precedence.
 
 ## Data encryption at rest
 
+> **Community pattern** — `ti.crypto` is a third-party community module (not part of the Titanium SDK core). Verify availability and compatibility before using in production.
+
 ```javascript
 // lib/services/encryption.js
 // AES-256 encryption for sensitive local data
+// Requires: ti.crypto community module
 
 const crypto = require('ti.crypto')
 
@@ -125,30 +108,6 @@ exports.decrypt = function(encryptedData, key) {
     options: { mode: crypto.CBC }
   })
 }
-
-// Usage: Secure cache of sensitive user data
-module.exports = class SecureCache {
-  constructor(encryptionKey) {
-    this.key = encryptionKey
-    this.cache = {}
-  }
-
-  set(key, value) {
-    const encrypted = encrypt(JSON.stringify(value), this.key)
-    this.cache[key] = encrypted
-  }
-
-  get(key) {
-    if (!this.cache[key]) return null
-
-    const decrypted = decrypt(this.cache[key], this.key)
-    return JSON.parse(decrypted)
-  }
-
-  clear() {
-    this.cache = {}
-  }
-}
 ```
 
 ## Secure HTTP communication
@@ -270,15 +229,15 @@ exports.Validator = {
 
 ## Owasp mobile security checklist
 
-| Category | Check | Implementation |
+| Category             | Check                       | Implementation                     |
 | -------------------- | --------------------------- | ---------------------------------- |
-| **Data Storage** | Credentials stored securely | Keychain/KeyStore for tokens |
-| **Data Storage** | Sensitive data encrypted | AES-256 for cached data |
-| **Communication** | HTTPS only | `validatesSecureCertificate: true` |
-| **Communication** | Certificate pinning | SSL pinning enabled |
-| **Authentication** | Token refresh | Auto-refresh before expiry |
-| **Authentication** | Session timeout | Auto-logout after inactivity |
-| **Input Validation** | Server-side validation | Never trust client input |
-| **Input Validation** | Sanitize user input | Remove XSS patterns |
-| **Cryptography** | No hardcoded keys | Keys from secure storage |
-| **Cryptography** | Use standard algorithms | AES-256, SHA-256 |
+| **Data Storage**     | Credentials stored securely | Keychain/KeyStore for tokens       |
+| **Data Storage**     | Sensitive data encrypted    | AES-256 for cached data            |
+| **Communication**    | HTTPS only                  | `validatesSecureCertificate: true` |
+| **Communication**    | Certificate pinning         | SSL pinning enabled                |
+| **Authentication**   | Token refresh               | Auto-refresh before expiry         |
+| **Authentication**   | Session timeout             | Auto-logout after inactivity       |
+| **Input Validation** | Server-side validation      | Never trust client input           |
+| **Input Validation** | Sanitize user input         | Remove XSS patterns                |
+| **Cryptography**     | No hardcoded keys           | Keys from secure storage           |
+| **Cryptography**     | Use standard algorithms     | AES-256, SHA-256                   |

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

@@ -20,6 +20,7 @@ Create a single source of truth using Backbone.Events:
 ```javascript
 // lib/services/stateStore.js
 const Backbone = require('alloy/backbone')
+const _ = require('alloy/underscore')._
 
 class StateStore {
   constructor() {
@@ -280,13 +281,13 @@ Ti.App.addEventListener('resume', () => {
 
 ## Anti-patterns
 
-| Anti-Pattern | Why It's Bad | Solution |
+| Anti-Pattern                          | Why It's Bad                 | Solution                                 |
 | ------------------------------------- | ---------------------------- | ---------------------------------------- |
-| `Ti.App.fireEvent` for state | No cleanup, memory leaks | Use StateStore with `offChange` |
-| Direct collection mutation | Bypasses reactivity | Use collection methods (`add`, `remove`) |
-| State in multiple places | Inconsistency bugs | Single source of truth |
-| Global variables (`Alloy.Globals`) | No reactivity, hard to track | Use StateStore |
-| Controller-to-controller direct calls | Tight coupling | Use StateStore or events |
+| `Ti.App.fireEvent` for state          | No cleanup, memory leaks     | Use StateStore with `offChange`          |
+| Direct collection mutation            | Bypasses reactivity          | Use collection methods (`add`, `remove`) |
+| State in multiple places              | Inconsistency bugs           | Single source of truth                   |
+| Global variables (`Alloy.Globals`)    | No reactivity, hard to track | Use StateStore                           |
+| Controller-to-controller direct calls | Tight coupling               | Use StateStore or events                 |
 
 ## Persistence strategies
 
@@ -472,14 +473,14 @@ exports.appStore = {
 
 ### Choosing a strategy
 
-| Data Type | Strategy | Reason |
-| ------------------ | ------------------- | ---------------------- |
-| User preferences | Ti.App.Properties | Simple main-value, fast |
-| Auth tokens | Keychain/KeyStore | Security |
-| User profile | Properties + Secure | Mixed sensitivity |
-| Lists (100+ items) | SQLite | Query, pagination |
-| Offline queue | SQLite | Durability, FIFO |
-| Cache | In-memory + SQLite | Speed + persistence |
+| Data Type          | Strategy            | Reason                  |
+| ------------------ | ------------------- | ----------------------- |
+| User preferences   | Ti.App.Properties   | Simple main-value, fast |
+| Auth tokens        | Keychain/KeyStore   | Security                |
+| User profile       | Properties + Secure | Mixed sensitivity       |
+| Lists (100+ items) | SQLite              | Query, pagination       |
+| Offline queue      | SQLite              | Durability, FIFO        |
+| Cache              | In-memory + SQLite  | Speed + persistence     |
 
 ## State middleware
 

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

@@ -127,21 +127,30 @@ describe('Login Flow', () => {
 
 ## Adding accessibility IDs for testing
 
+Appium uses accessibility identifiers to locate elements. The correct properties are:
+- **iOS**: `accessibilityIdentifier` — maps to `$('~id')` in WebdriverIO
+- **Android**: `contentDescription` — also maps to `$('~id')` in WebdriverIO
+
+`testId` is NOT an official Titanium view property. Use `accessibilityIdentifier` instead.
+
 ```xml
 <!-- views/auth/login.xml -->
-<Window testId="loginScreen">
-  <TextField id="emailField" testId="emailField" />
-  <TextField id="passwordField" testId="passwordField" />
-  <Button id="loginBtn" testId="loginButton" />
-  <Label id="errorLabel" testId="errorLabel" />
+<Window id="loginWindow" accessibilityIdentifier="loginScreen">
+  <TextField id="emailField" accessibilityIdentifier="emailField" />
+  <TextField id="passwordField" accessibilityIdentifier="passwordField" />
+  <Button id="loginBtn" accessibilityIdentifier="loginButton" />
+  <Label id="errorLabel" accessibilityIdentifier="errorLabel" />
 </Window>
 ```
 
 ```javascript
-// In controller or alloy.js - map testId to accessibilityLabel
-if (Alloy.CFG.debug) {
-  // Auto-set accessibilityLabel from testId during development
-  Ti.UI.defaultUnit = 'dp'
+// For Android, also set contentDescription to match the same value
+// since accessibilityIdentifier is iOS-specific.
+// In controller:
+if (OS_ANDROID) {
+  $.emailField.contentDescription = 'emailField'
+  $.passwordField.contentDescription = 'passwordField'
+  $.loginBtn.contentDescription = 'loginButton'
 }
 ```
 
@@ -412,21 +421,21 @@ end
 
 Configure in GitHub repository settings:
 
-| Rule | Setting |
+| Rule                              | Setting                                    |
 | --------------------------------- | ------------------------------------------ |
-| Require pull request reviews | 1 approval required |
-| Require status checks | lint, unit-tests, build-ios, build-android |
-| Require branches to be up to date | Yes |
-| Include administrators | Yes |
+| Require pull request reviews      | 1 approval required                        |
+| Require status checks             | lint, unit-tests, build-ios, build-android |
+| Require branches to be up to date | Yes                                        |
+| Include administrators            | Yes                                        |
 
 ## Testing best practices summary
 
-| Area | Practice |
+| Area                  | Practice                                   |
 | --------------------- | ------------------------------------------ |
-| **Unit Tests** | Test business logic in services/helpers |
+| **Unit Tests**        | Test business logic in services/helpers    |
 | **Integration Tests** | Test controller flows with mocked services |
-| **E2E Tests** | Test critical user journeys |
-| **Coverage** | Aim for 80%+ on services, 60%+ overall |
-| **CI Pipeline** | Run lint -> unit tests -> build -> E2E |
-| **Artifacts** | Save screenshots on failure |
-| **Notifications** | Slack/email on build failures |
+| **E2E Tests**         | Test critical user journeys                |
+| **Coverage**          | Aim for 80%+ on services, 60%+ overall     |
+| **CI Pipeline**       | Run lint -> unit tests -> build -> E2E     |
+| **Artifacts**         | Save screenshots on failure                |
+| **Notifications**     | Slack/email on build failures              |

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

@@ -41,9 +41,8 @@ Set the theme in `config.json`:
 }
 ```
 
-:::warning Theme is compile-time only
-Alloy themes are applied at **build time**. You cannot switch themes at runtime using this system alone. For runtime switching, use the Dynamic Theming approach below.
-:::
+> **⚠️ Theme is compile-time only**
+> Alloy themes are applied at **build time**. You cannot switch themes at runtime using this system alone. For runtime switching, use the Dynamic Theming approach below.
 
 ### Theme cascade
 
@@ -178,9 +177,8 @@ exports.ThemeService = {
 
 ### Step 4: respond to theme changes in controllers
 
-:::warning Theme change requires UI rebuild
-Since TSS is applied at controller creation time, changing `Alloy.Globals.theme` does NOT retroactively update already-rendered views. You must manually update visible elements or restart the root controller.
-:::
+> **⚠️ Theme change requires UI rebuild**
+> Since TSS is applied at controller creation time, changing `Alloy.Globals.theme` does NOT retroactively update already-rendered views. You must manually update visible elements or restart the root controller.
 
 **Approach A: Rebuild root controller (simplest)**
 
@@ -245,20 +243,15 @@ exports.ThemeService = {
 
   // Initialize system theme listener
   initSystemListener() {
-    // Detect current system theme
+    // Detect current system theme at startup
     this.followSystem()
 
-    // Listen for system theme changes
-    Ti.App.addEventListener('significantTimeChange', () => {
+    // Re-check on resume (user may have changed system Dark Mode while app was backgrounded)
+    // Note: Titanium does not fire a dedicated dark-mode-change event.
+    // `Ti.UI.semanticColorType` is the correct way to check the current setting.
+    Ti.App.addEventListener('resumed', () => {
       this.followSystem()
     })
-
-    // iOS: userInterfaceStyle change
-    if (OS_IOS) {
-      Ti.App.addEventListener('traitCollectionChange', () => {
-        this.followSystem()
-      })
-    }
   }
 }
 ```
@@ -322,10 +315,9 @@ $.container.backgroundColor = 'backgroundColor';
 - Alpha can be set from 0.0-100.0 (integer or float)
 - Light values can use hex with alpha via ARGB/AARRGGBB format
 
-:::tip When to use Semantic Colors vs Alloy.Globals
-- **Semantic Colors**: Built-in Dark Mode support, automatic switching, simpler setup. Works cross-platform.
-- **Alloy.Globals palette**: More control over when/how themes switch, easier to add custom themes beyond light/dark, runtime theme changes with UI rebuild.
-:::
+> **💡 When to use Semantic Colors vs Alloy.Globals**
+> - **Semantic Colors**: Built-in Dark Mode support, automatic switching, simpler setup. Works cross-platform.
+> - **Alloy.Globals palette**: More control over when/how themes switch, easier to add custom themes beyond light/dark, runtime theme changes with UI rebuild.
 
 ---
 

package/skills/ti-guides/SKILL.md

@@ -11,20 +11,19 @@ Use this skill to keep Titanium projects aligned with TiDev standards for stabil
 
 ## Project detection
 
-:::info Auto-detects Titanium projects
-This skill auto-detects Titanium projects. No manual command is needed.
-
-Titanium project indicator:
-- `tiapp.xml` file (definitive indicator)
-
-Applies to both:
-- Alloy projects (`app/` folder)
-- Classic projects (`Resources/` folder)
-
-Behavior:
-- If a Titanium project is detected, provide official Titanium SDK guidance, memory management best practices, and app distribution help.
-- If not detected, say this skill is only for Titanium projects.
-:::
+> **️ℹ️ Auto-detects Titanium projects**
+> This skill auto-detects Titanium projects. No manual command is needed.
+>
+> Titanium project indicator:
+> - `tiapp.xml` file (definitive indicator)
+>
+> Applies to both:
+> - Alloy projects (`app/` folder)
+> - Classic projects (`Resources/` folder)
+>
+> Behavior:
+> - If a Titanium project is detected, provide official Titanium SDK guidance, memory management best practices, and app distribution help.
+> - If not detected, say this skill is only for Titanium projects.
 
 ## Core workflow
 
@@ -52,9 +51,6 @@ Behavior:
 - Hyperloop Native Access (references/hyperloop-native-access.md): Objective-C/Swift/Java syntax, casting, debugging, XIB/Storyboards.
 - Style & Conventions (references/style-and-conventions.md): naming standards and formatting rules.
 - Reserved Words (references/reserved-words.md): ECMAScript, iOS, and Alloy reserved keywords to avoid.
-- Alloy CLI Reference (references/alloy-cli-advanced.md): extract-i18n, code generation, and build hooks.
-- Alloy Data Mastery (references/alloy-data-mastery.md): sync adapters, data binding, and Backbone collections.
-- Alloy Widgets & Themes (references/alloy-widgets-and-themes.md): widget structure, styling priorities, and theming.
 - Android Manifest (references/android-manifest.md): custom AndroidManifest.xml, permissions, and manifest merge.
 - App Distribution (references/app-distribution.md): Google Play (APK/AAB), App Store (IPA), certificates, provisioning, and deployment.
 - tiapp.xml Configuration (references/tiapp-config.md): complete reference for tiapp.xml and timodule.xml, including all elements, properties, and platform-specific settings.

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

@@ -15,6 +15,26 @@
   ```
 - 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
 
@@ -45,11 +65,11 @@ const addColumn = (dbname, tblName, newFieldName, colSpec) => {
 
 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) |
+| 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.
 
@@ -80,12 +100,12 @@ For flip-book animations, use `ImageView.images` with an array of PNG or optimiz
 
 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 |
+| Platform            | File types    | Tool        |
+| ------------------- | ------------- | ----------- |
+| Mac                 | PNG, JPG, GIF | ImageOptim  |
 | Mac, Windows, Linux | PNG, JPG, GIF | ImageMagick |
-| Windows/DOS | PNG | PNGCrush |
-| Windows | JPG | Nikkho |
+| Windows/DOS         | PNG           | PNGCrush    |
+| Windows             | JPG           | Nikkho      |
 
 ---
 

package/skills/ti-guides/references/application-frameworks.md

@@ -118,11 +118,11 @@ app.js:
 // Single namespace pattern
 const app = {};
 
-// Include components (Legacy)
-Ti.include('ui/ApplicationWindow.js');
+// Load components via require (Ti.include is deprecated)
+const AppWindow = require('ui/ApplicationWindow');
 
 // Create and open window
-app.mainWindow = app.ui.createApplicationWindow();
+app.mainWindow = AppWindow.createApplicationWindow();
 app.mainWindow.open();
 ```
 

package/skills/ti-guides/references/coding-best-practices.md

@@ -34,6 +34,8 @@ Ti.App.fireEvent('my_event')
 
 - Defer script loading. Only `require` modules when you need them.
 
+Defer loading to reduce startup time. Only `require` modules when you need them.
+
 Lazy script loading example:
 ```javascript
 // must be loaded at launch
@@ -56,8 +58,16 @@ win1.addEventListener('click', () => {
 });
 ```
 
-- Bridge efficiency: minimize requests for device properties like `Ti.Platform.osname`. Store them in a local variable.
-- Avoid extending the `Ti` namespace. `Ti` objects are proxies to native components. Properties set on them may not reach the native object, arrays return copies, and persistence across SDK versions is not guaranteed. Use modules instead.
+- Bridge efficiency: minimize requests for device properties like `Ti.Platform.osname`. Store them in a local variable:
+```javascript
+const isAndroid = (Ti.Platform.osname === 'android')
+if (isAndroid) { /* Android path */ } else { /* iOS path */ }
+```
+- Avoid extending the `Ti` namespace. Three reasons:
+  1. Ti objects are proxies to native OS components — your extensions may conflict with native functionality.
+  2. Arrays stored on the namespace may be immutable; objects may be null unexpectedly.
+  3. There is no guarantee properties persist across SDK versions.
+  Use your own namespace or CommonJS module instead of modifying `Ti`.
 
 ## 5. App architecture recommendations
 
@@ -85,6 +95,25 @@ const myModule = require('/MyModule');
 myModule.sayHello('User');
 ```
 
+### Namespace with deferred loading (alternative pattern)
+
+If not using CommonJS, you can still defer loading with a namespace:
+
+```javascript
+const someNameSpace = () => {
+  const API = {
+    init() {
+      // create UI or initialize
+    },
+    reset() {
+      // null objects, clean up
+    }
+  }
+  return API
+}
+const ns = new someNameSpace()
+```
+
 ### Custom objects as components
 
 Popular for rapid deployment. It uses a namespace hierarchy. This pattern is less efficient than CommonJS modules, and object references can persist after they are no longer needed.

package/skills/ti-guides/references/commonjs-advanced.md

@@ -162,7 +162,49 @@ const logger = require('logger')
 logger.info('some log statement with a timestamp')
 ```
 
-## 7. Inter-module state sharing
+## 7. Packages of related functionality
+
+Group related classes or helpers in a single module:
+
+```javascript
+// app/lib/geo.js
+class Point {
+  constructor(x, y) {
+    this.x = x
+    this.y = y
+  }
+}
+
+class Line {
+  constructor(start, end) {
+    this.start = start
+    this.end = end
+  }
+
+  slope() {
+    return (this.end.y - this.start.y) / (this.end.x - this.start.x)
+  }
+
+  yIntercept() {
+    return this.start.y - (this.slope() * this.start.x)
+  }
+}
+
+exports.Point = Point
+exports.Line = Line
+```
+
+Usage:
+```javascript
+const Geo = require('lib/geo')
+
+const start = new Geo.Point(1, -5)
+const end = new Geo.Point(10, 2)
+const line = new Geo.Line(start, end)
+Ti.API.info(line.slope())
+```
+
+## 8. Inter-module state sharing
 
 When a module assigns a primitive value to `exports`, the consumer gets a copy, not a live reference. Changes to the internal variable are not reflected in the exported property.
 
@@ -190,7 +232,7 @@ Ti.API.info(stateful.stepVal)        // 5  - still the original copy
 
 Rule: use getter/setter functions for stateful values. Direct property exports of primitives are snapshots at module load time.
 
-## 8. Antipatterns to avoid
+## 9. Antipatterns to avoid
 
 ### Do not assign directly to `exports`
 
@@ -217,7 +259,7 @@ exports.foo = 'bar'
 
 Any data a module needs should be passed during construction or initialization. Avoid globals shared across modules.
 
-## 9. Security and scope
+## 10. Security and scope
 
 All modules have private scope. Variables declared within the module are private unless added to `exports`.
 
@@ -230,7 +272,7 @@ exports.publicMethod = () => {
 }
 ```
 
-## 10. Node.js compatibility
+## 11. Node.js compatibility
 
 Titanium supports Node.js module patterns and `require()` resolution. Node.js modules can often be used directly.