@maccesar/titools 4.4.0 → 4.4.2

package/skills/ti-expert/references/file-type-association.md

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

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

@@ -30,21 +30,16 @@ Before migrating, evaluate the current codebase:
 
 ## Phase 1: styling-system organization
 
-**Goal**: Migrate from inline and scattered styling into the styling system the
-project actually uses.
+**Goal**: Migrate from inline and scattered styling into the styling system the project actually uses.
 
 ### Step 0: detect PurgeTSS
 
 Check for `purgetss/` or `purgetss/config.cjs` before editing styles.
 
-- **PurgeTSS detected:** invoke the `purgetss` skill, use verified utilities and
-  semantic colors, configure reusable rules in `config.cjs`, and never edit the
-  generated `app/styles/app.tss`.
-- **No PurgeTSS:** use standard per-controller TSS and a manually maintained
-  `app/styles/app.tss` for genuinely global selectors.
+- **PurgeTSS detected:** invoke the `purgetss` skill, use verified utilities and semantic colors, configure reusable rules in `config.cjs`, and never edit the generated `app/styles/app.tss`.
+- **No PurgeTSS:** use standard per-controller TSS and a manually maintained `app/styles/app.tss` for genuinely global selectors.
 
-Do not migrate a PurgeTSS application back into manual TSS by following a generic
-Alloy example.
+Do not migrate a PurgeTSS application back into manual TSS by following a generic Alloy example.
 
 ### Step 1: audit existing styles
 
@@ -89,17 +84,13 @@ This step applies only when PurgeTSS is not present.
 ".btn-primary": { backgroundColor: '#2563eb', color: '#fff', height: 44, borderRadius: 8 }
 ```
 
-In either styling path, replace hard-coded visual colors with semantic roles as
-part of the migration. See [Theming and Dark Mode](theming.md).
+In either styling path, replace hard-coded visual colors with semantic roles as part of the migration. See [Theming and Dark Mode](theming.md).
 
 ## Phase 1B: feedback surfaces
 
-Inventory native alerts, option dialogs, Toasts, and local overlays. Classify
-each occurrence before replacing it, then migrate one window at a time. Preserve
-system-owned pickers, permission prompts, sharing, and biometric UI.
+Inventory native alerts, option dialogs, Toasts, and local overlays. Classify each occurrence before replacing it, then migrate one window at a time. Preserve system-owned pickers, permission prompts, sharing, and biometric UI.
 
-Use [Feedback Migration](feedback-migration.md) for the sequence, deliberate
-silence rules, and verification contract.
+Use [Feedback Migration](feedback-migration.md) for the sequence, deliberate silence rules, and verification contract.
 
 ## Phase 2: service layer extraction
 
@@ -323,8 +314,7 @@ For each phase:
 3. **Test thoroughly** before moving to next feature
 4. **Delete the replaced implementation** after the vertical slice passes
 
-Use version control for rollback. Do not keep commented legacy implementations:
-they conceal duplicate listeners, stale callbacks, and incomplete migrations.
+Use version control for rollback. Do not keep commented legacy implementations: they conceal duplicate listeners, stale callbacks, and incomplete migrations.
 
 ## Common migration pitfalls
 

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

@@ -0,0 +1,227 @@
+# Sharing content out
+
+How to hand a link, a text or a file from your app to the rest of the system — the share sheet on iOS, the intent chooser on Android.
+
+The two platforms are not symmetric and have not been for years, which is the single fact that explains every confusing implementation you will find in an older codebase. Android does this with the core SDK and no module. iOS does not: the SDK exposes no wrapper for `UIActivityViewController`, so a native module is still required. Code written before that split settled tends to route both platforms through the module, or through a cross-platform helper that only ever needed to exist for iOS.
+
+This file is about sending content **out**. For receiving files — declaring a custom extension, UTIs, intent filters, `handleurl` — see [File type association](file-type-association.md).
+
+## Contents
+
+1. [The platform split](#1-the-platform-split)
+2. [Android: the core SDK is enough](#2-android-the-core-sdk-is-enough)
+3. [iOS: which module, and why one is still needed](#3-ios-which-module-and-why-one-is-still-needed)
+4. [Text is not a file](#4-text-is-not-a-file)
+5. [Do not pass text alongside a file](#5-do-not-pass-text-alongside-a-file)
+6. [iPad needs an anchor](#6-ipad-needs-an-anchor)
+7. [Knowing whether the user actually shared](#7-knowing-whether-the-user-actually-shared)
+8. [Failing without an exception](#8-failing-without-an-exception)
+9. [Verify instead of assuming](#9-verify-instead-of-assuming)
+10. [Symptom to cause](#10-symptom-to-cause)
+
+## 1. The platform split
+
+| | Text or link | File |
+| --- | --- | --- |
+| **Android** | `Ti.Android.createIntent` + `createIntentChooser` | Same, with `putExtraUri` |
+| **iOS** | Native module — no SDK API | Native module, or `DocumentViewer` if the type is previewable |
+
+The asymmetry is historical, not architectural. Sharing on Titanium used to go through `com.alcoapps.socialshare`, a CommonJS wrapper by Ricardo Alcocer that split by platform and drove the same iOS module underneath. Once Android could open the system sheet directly, the Android branch stopped needing anything and the module became iOS-only — but the wrapper stayed in projects, and with it a layer of indirection that no longer buys anything.
+
+**When you find one of those wrappers,** check what it still does. The usual finding is dead weight: version-comparison helpers, Facebook app-id variables, `image_blob` / `image_url` normalization for an argument shape nobody passes anymore. Adapting the old helper costs more than writing the two branches.
+
+## 2. Android: the core SDK is enough
+
+`Ti.Android.createIntent` and `Ti.Android.createIntentChooser` are core SDK APIs and are not deprecated. No module, no widget.
+
+```javascript
+function shareTextAndroid (text, chooserTitle) {
+  const activity = Ti.Android.rootActivity || Ti.Android.currentActivity
+
+  // No activity, no chooser to present. Calling startActivity on null throws in
+  // the face of whoever tapped Share.
+  if (!activity) {
+    return false
+  }
+
+  const intent = Ti.Android.createIntent({
+    action: Ti.Android.ACTION_SEND,
+    type: 'text/plain'
+  })
+
+  intent.putExtra(Ti.Android.EXTRA_TEXT, text)
+  activity.startActivity(Ti.Android.createIntentChooser(intent, chooserTitle))
+
+  return true
+}
+```
+
+For a file, two things change and both are mandatory:
+
+```javascript
+intent.putExtraUri(Ti.Android.EXTRA_STREAM, file.nativePath)
+intent.addFlags(Ti.Android.FLAG_GRANT_READ_URI_PERMISSION)
+```
+
+`putExtraUri` makes the SDK convert the path into a `content://` URI served by `TiFileProvider`, which ships declared in the merged manifest — nothing to configure. **Without `FLAG_GRANT_READ_URI_PERMISSION` the receiving app cannot read the file.** It is granted a URI it has no permission for, so the share appears to work and the other app shows an error or an empty attachment.
+
+Set `type` to the real MIME type rather than `*/*`. An unknown type falls back to `application/octet-stream`, which offers every app on the device instead of the ones that can do something useful.
+
+## 3. iOS: which module, and why one is still needed
+
+There is no share sheet API in the SDK. This is verifiable rather than folklore — see [Verify instead of assuming](#9-verify-instead-of-assuming). The SDK offers `Ti.UI.iOS.DocumentViewer`, which is a previewer, and `Ti.App.iOS.UserActivity`, which is Handoff. Neither presents `UIActivityViewController`.
+
+**The module is `dk.napp.social`**, and its provenance matters because the obvious repository is the wrong one:
+
+| Repository | Status |
+| --- | --- |
+| [viezel/TiSocial.Framework](https://github.com/viezel/TiSocial.Framework) | **Archived April 2021.** Last release 2.0.0. This is the one search engines surface. |
+| [hansemannn/TiSocial.Framework](https://github.com/hansemannn/TiSocial.Framework) | **The maintained fork.** Its 3.0.0 release states "Moved to this fork as the base repository". |
+
+Releases on the fork: 3.0.0 (macOS support), 3.0.1 (fixes a possible iPad crash), 3.0.2 (restores iOS 12 compatibility). **3.0.2 is the highest published version.** If a project declares something higher in `tiapp.xml`, that build came from somewhere other than a release — treat the local copy as irreplaceable and say so in the project's install instructions, because nobody can download it.
+
+```javascript
+function shareTextIos (text, subject) {
+  const social = require('dk.napp.social')
+
+  if (!social.isActivityViewSupported()) {
+    return false
+  }
+
+  social.activityView({ subject: subject || '', text }, [])
+  return true
+}
+```
+
+Require the module inside the iOS branch, not at the top of the file. A module-level `require` runs on Android too, where it resolves to nothing useful.
+
+## 4. Text is not a file
+
+`DocumentViewer` takes the URL of a file; there is no way to hand it a string. So a file has two possible routes on iOS and a text has one.
+
+**The file route via `DocumentViewer` works only when iOS can preview the type.** The viewer presents the document and its action button opens the real system sheet — no module involved. But "presents" is conditional: with a type the system cannot render, it presents nothing and reports no error. Silence, and the user sees a tap that did nothing.
+
+So the decision is about the type, not about the file:
+
+- **Type the system knows** (PDF, image, ZIP, plain text) → `DocumentViewer` is enough, and it saves you the module on this path.
+- **Opaque type** — anything conforming to `public.data`, which is what a custom document type usually declares so that Files hands it over instead of previewing it (see [File type association](file-type-association.md)) → the viewer has nothing to show. Use the module's `activityView({ file })`.
+
+This is the trap worth naming: **the same declaration that makes tapping the file open your app is what stops `DocumentViewer` from presenting it.** The two behaviors pull in opposite directions and both are correct.
+
+## 5. Do not pass text alongside a file
+
+When sharing a file, pass only the file. Adding `text` to the same payload makes iOS treat the string as a **second item** in the sheet, and "Save to Files" writes two files: the document, plus a `.txt` holding the caption.
+
+```javascript
+// wrong — "Save to Files" leaves the backup AND a stray text file
+social.activityView({ file: file.nativePath, text: title }, [])
+
+// right — the subject rides along without becoming an item
+social.activityView({ file: file.nativePath, subject: title }, [])
+```
+
+The symptom shows up only in destinations that write to disk. Sharing to a messaging app looks fine, which is why this survives testing.
+
+## 6. iPad needs an anchor
+
+On iPad the sheet is a popover and must be anchored to the view that was tapped, or it has nowhere to attach:
+
+```javascript
+if (Ti.Platform.osname === 'ipad') {
+  options.view = sourceView
+  social.activityPopover(options, [])
+  return true
+}
+
+social.activityView(options, [])
+```
+
+This means the controller has to pass the source view down to the sharing service — usually `event.source` from the tap handler. Services that take only a URL cannot support iPad without changing their signature, which is why the parameter is worth adding before the app ships on tablets.
+
+## 7. Knowing whether the user actually shared
+
+Both platforms open a sheet and return immediately. Neither the intent chooser nor a bare `activityView` call tells you what happened next.
+
+On iOS the module emits it:
+
+```javascript
+const social = require('dk.napp.social')
+
+social.addEventListener('complete', event => {
+  // event.activityName — where it went
+})
+
+social.addEventListener('cancelled', () => {})
+```
+
+Register these **once**, at module scope inside the iOS branch, not per share — re-adding on every tap leaks listeners.
+
+Android has no equivalent through the chooser. If the product needs to know, that asymmetry is the design constraint, and treating "sheet opened" as success is the honest fallback.
+
+Skip all of this when nothing depends on the answer. An analytics event or a "Shared!" confirmation is a reason; symmetry with iOS is not.
+
+## 8. Failing without an exception
+
+Sharing fails for reasons that are not bugs: no activity, a device without sheet support, a file that was deleted between the tap and the call. **Return a boolean and let the caller decide whether to warn.** Throwing from a share function means an exception reaches whoever tapped a button.
+
+```javascript
+function share (payload, sourceView) {
+  try {
+    return OS_ANDROID
+      ? shareAndroid(payload)
+      : shareIos(payload, sourceView)
+  } catch (error) {
+    Ti.API.error(`[sharing] Could not share: ${error.message}`)
+    return false
+  }
+}
+```
+
+The failure worth auditing in an existing codebase is a **mixed contract**: one branch returning `false` while its sibling throws or returns nothing. It usually means one path was hardened after a crash and the other was never revisited.
+
+## 9. Verify instead of assuming
+
+Whether the SDK exposes something is checkable in the installed SDK's API metadata, and takes less time than the argument about it:
+
+```bash
+JSCA=~/Library/Application\ Support/Titanium/mobilesdk/osx/<version>/api.jsca
+
+python3 - "$JSCA" <<'PY'
+import json, sys
+d = json.load(open(sys.argv[1]))
+for t in d.get('types', []):
+    if any(k in t['name'] for k in ('Activity', 'Share', 'Social', 'DocumentViewer')):
+        print(t['name'])
+PY
+```
+
+On 13.4.0.GA this returns `Titanium.UI.iOS.DocumentViewer`, `Titanium.App.iOS.UserActivity`, `Titanium.UI.ActivityIndicator` and the Android `Activity` types — and nothing wrapping `UIActivityViewController`. The same query tells you whether an API you are about to rely on is marked deprecated.
+
+For the module, check what is actually installed rather than what `tiapp.xml` claims:
+
+```bash
+ls ~/Library/Application\ Support/Titanium/modules/iphone/dk.napp.social/
+cat ~/Library/Application\ Support/Titanium/modules/iphone/dk.napp.social/*/manifest
+```
+
+**Do not verify a suspicion by comparing against a sibling project.** Two codebases that share a lineage share its mistakes, so agreement between them proves nothing. The control is the platform documentation or the SDK metadata.
+
+## 10. Symptom to cause
+
+| Symptom | Cause |
+| --- | --- |
+| Tapping Share does nothing on iOS, no error | File type is not previewable and the code used `DocumentViewer`. Use the module for opaque types. |
+| Receiving app shows an error or an empty attachment (Android) | Missing `FLAG_GRANT_READ_URI_PERMISSION`. |
+| "Save to Files" writes two files | `text` passed alongside `file`. Use `subject`. |
+| Sheet does not appear on iPad | `activityView` used instead of `activityPopover`, or no `view` anchor. |
+| Crash when tapping Share on Android | `startActivity` on a null activity. Guard `rootActivity || currentActivity`. |
+| Chooser offers every app on the device | `type` left as `*/*` or an unknown extension falling back to `application/octet-stream`. |
+| `Couldn't find module: dk.napp.social` | Module not installed, or `require` at file scope running on Android. |
+| Module version in `tiapp.xml` has no matching release | Locally built copy. It cannot be downloaded; document it as an install requirement. |
+
+## Sources
+
+- Titanium SDK 13.4.0.GA `api.jsca` — the absence of a share sheet API on iOS and the non-deprecated status of `Ti.Android.createIntentChooser`.
+- [hansemannn/TiSocial.Framework](https://github.com/hansemannn/TiSocial.Framework) — maintained fork, releases 3.0.0 through 3.0.2.
+- [viezel/TiSocial.Framework](https://github.com/viezel/TiSocial.Framework) — original, archived April 2021.
+- [ricardoalcocer/socialshare](https://github.com/ricardoalcocer/socialshare) — the historical cross-platform wrapper, for recognizing it in old code.