Skip to content

microsoft/power-platform-skills / plugins/mobile-apps/skills/add-native

add-native

Unverified

Public entry point for native device capabilities and native controls — camera, image picker, barcode/QR scanner, document picker, file picker, secure storage, file system, sharing, haptic feedback, PDF generation/viewing, pen/signature capture, background GPS/geolocation tracking, or supported local file workflows — in a Power Apps mobile app. Also owns routing to internal camera/PDF/pen/geolocation implementation helpers and the guidance boundary between native wrappers and Dataverse File/Image host controls.

Plugin check: Run node "${PLUGIN_ROOT}/scripts/check-version.js" - if it outputs a message, show it to the user before proceeding.

📋 Shared instructions: shared-instructions.md — read first.

Working directory: before any project read or command, execute native-artifact-compatibility.md Step 0. Resolve --working-dir / owner context there; use the resolved absolute root for every shell call and file tool, not a previous shell's cwd.

Add Native Capability

Entry routing: use the shared App feature entry points preflight before the workflow below.

Generate a typed wrapper under src/native/ for a native capability in the app's verified release context. Screens import the wrapper instead of touching native packages directly. Read native controls for conditional aggregate adoption, legacy imports, permission boundaries, and location ownership.

Hard rules — do NOT cross these lines

  1. Never run npx expo install, npm install, or yarn add for a native module. Native support is fixed by the app-matched verified release and selected player/base, not the newest bundled template or the customer's manifest.
  2. Never edit app.config.js — plugins, ios.infoPlist, android.permissions, or anything else. Native config belongs to the verified fixed-capability base; arbitrary additions cannot be honored at rewrap time.
  3. Never edit package.json dependencies for native modules. Native means the package ships platform source/projects, a podspec, codegen, an Expo module/config plugin, or react-native.config.js; a package-name prefix alone is not proof. Pure-JavaScript dependencies are out of scope for /add-native and are installed from an approved JavaScript Dependencies plan by /create-mobile-app or /edit-app.
  4. If release resolution fails, or package/version/native inventory disagree — STOP before native mutation. A dependency being present is necessary, not sufficient. Do not install the controls aggregate or newer leaf to repair an older binary.
  5. Keep inclusion, declarations, grants, and usage separate. The base owns OS declarations. Dependency/config toggles do not remove unused default Android permissions; different declarations require another verified base. Optional permission wrapping is deferred.

Routing — /add-native is the public entry point

Some capabilities have a dedicated implementation helper that does more than a plain wrapper (camera writes scanner/upload helpers; PDF report/viewer helpers enforce local-vs-HTTPS boundaries; pen has native-control-specific validation). Users should still call /add-native <capability> for native controls. When a dedicated implementation exists, run it internally and do not ask the user to run that helper directly.

Lookup convention: after normalizing the capability, first check the internal-helper map below. For camera, image-picker, barcode-scanner, and qr-scanner, read and execute ${PLUGIN_ROOT}/skills/add-native/add-camera/SKILL.md inside this /add-native invocation. For pdf-report, read and execute ${PLUGIN_ROOT}/skills/add-native/add-pdf-report/SKILL.md. For pdf-viewer, read and execute ${PLUGIN_ROOT}/skills/add-native/add-pdf-viewer/SKILL.md. For pen-input, read and execute ${PLUGIN_ROOT}/skills/add-native/add-pen-input/SKILL.md. For geolocation, read and execute ${PLUGIN_ROOT}/skills/add-native/add-geolocation/SKILL.md. If no helper exists, fall through to this skill's inline wrapper flow.

Current dedicated implementations:

CapabilityDedicated skillWhy dedicated
camera, take-photo, photo, expo-camera, image-picker, gallery, expo-image-picker, barcode-scanner, qr-scanner, scanneradd-camera internal helperOwns photo capture, gallery image picking, and barcode/QR scanner controls backed by expo-camera / expo-image-picker
pdf-report, pdf-export, generate-pdf, print-report, evidence-packetadd-pdf-report internal helperGenerates app-owned local PDFs with expo-print and shares them only when expo-sharing is present
pdf-viewer, native-pdf-viewer, pdf-control, open-pdf, @microsoft/power-apps-native-pdf-vieweradd-pdf-viewer internal helperEnforces https:// / file:// viewer inputs and native viewer result handling
pen-input, signature, ink, draw, @microsoft/power-apps-native-pen-inputadd-pen-input internal helperCaptures PNG data URI and documents Dataverse Image/File persistence
location, geolocation, location-tracking, background-location, gps-tracking, geo-tracking, @microsoft/power-apps-native-bglocationadd-geolocation internal helperSeparate one-shot coordinate reads from continuous tracking and durable Dataverse sync

For every other capability listed below, this skill writes the wrapper directly.

Native capability gate

Before adding any native control or wrapper, verify the project and run the package-contract resolver in Step 1.

Use its sanitized tuple as the shared resolved context for helpers/planners/builders. Unknown/missing published contracts block native mutations, not permission to assume a runtime. No separate skills release list is required. Classify the intent, resolve the exact package and version from this app's inventory, confirm it is not runtime-banned, and verify input/output/storage constraints. The newest bundled template is never a runtime allowlist. Every “present” requirement below means present in both this release context and the installed app, with compatible native support; manifest presence alone cannot pass the gate.

For controls, select aggregate subpaths or legacy leaves using the version-conditional import contract. enableNativeControls is permitted only on a verified supporting host release; published host 0.4.0 lacks it. No root barrel or barcode subpath is available.

User intentAdd/useRequired package or controlDo not use / fallback
Form field bound to a Dataverse File columnHost <FilePicker> in screen JSX@microsoft/power-apps-native-host host controlDo not generate document-picker/file-system/sharing wrappers for this field
Form field bound to a Dataverse Image columnHost <ImagePicker> in screen JSX@microsoft/power-apps-native-host host controlDo not use camera/image-picker wrappers for normal form-bound image fields
Dedicated photo/gallery/scanner workflow/add-native camera, image-picker, or barcode-scannerexpo-image-picker for photo/gallery; expo-camera for scanner; both for combined requestsIf packages are absent, stop with missing-package guidance
Pick/import/upload a user-selected PDF/document/add-native document-picker, or host <FilePicker> for Dataverse File fieldsexpo-document-picker present, or host File controlDo not treat this as pdf-report or native PDF viewer
Generate/export/print an app-owned report PDF/add-native pdf-reportexpo-print presentIf expo-print is absent, do not add PDF report capability
Share a generated local PDFpdfReport.ts share helperexpo-sharing presentIf expo-sharing is absent, do not render sharing UI
Open/preview an HTTPS or local file PDF/add-native pdf-viewerResolved controls /pdf or matching legacy PDF leaf with file URI support (0.2.9+)Do not pass content://, blob:, or http:// URIs to the viewer
Capture signature, ink, drawing, or sign-off/add-native pen-inputResolved controls /pen or matching legacy pen leafIf persisted, plan Dataverse Image/File/child Evidence target first
One-shot foreground coordinate/add-native locationResolved controls /geolocation or matching background-location leaf; expo-location only if independently verifiedNo app_id, data source, target table, or startTracking for BgLocationClient.getCurrentLocation()
Continuous/background GPS tracking with durable Dataverse upload/add-native geolocationResolved controls /geolocation or matching legacy background-location leafDo not use a one-shot read for tracking; background-location 0.2.3 tracking uses background permissions even with trackInBackground: false
Tactile feedback for presses, selections, and operation results/add-native hapticsexpo-haptics presentUse the typed wrapper and pair every haptic with visible UI feedback
Store generated PDF/signature artifactGenerated Dataverse services after parent row existsFile/Image column or child Evidence/Attachment table existsNever put File bytes in create/update JSON
Native capability not listed in this tableResolve from the app-matched native inventory, then add an inline wrapper only when installed and not runtime-bannedExact relevant package/version in the verified releaseIf no relevant package exists, or the package is runtime-banned, add a transparency note and stop

Handle multi-part requests row-by-row. Example: "capture signature and attach signed report PDF" requires pen-input, pdf-report, Dataverse artifact storage, and possibly sharing; do not add only the native capability while leaving storage or screen states undefined. The map is not closed: for new shipped packages, resolve by capability semantics, use the directly matching package when safe, and ask once only if multiple installed packages plausibly match.

File/Image Picker Ownership

This skill owns native file capability mechanics. Screen builders own only the final JSX placement.

There are two different cases:

CaseCorrect implementationOwner
Dataverse File columnUse <FilePicker> from @microsoft/power-apps-native-hostscreen-builder JSX rule, documented here
Dataverse Image columnUse <ImagePicker> from @microsoft/power-apps-native-hostscreen-builder JSX rule, documented here
Local device document/file workflow not bound to a Dataverse columnGenerate/use src/native/documentPicker.ts, src/native/fileSystem.ts, and/or src/native/sharing.ts wrappers/add-native
App-generated PDF report workflow/add-native routes internally to add-pdf-report; uses expo-print and optionally expo-sharing only if present/add-native
Camera capture, gallery image selection, barcode scanner, or QR scanner workflow/add-native routes internally to add-camera/add-native

Dataverse File/Image columns use host controls, not raw Expo modules and not app-specific native wrappers. When a form field binds to a Dataverse File column (FileAttributeMetadata), render <FilePicker> from @microsoft/power-apps-native-host. When it binds to a Dataverse Image column (ImageAttributeMetadata), render <ImagePicker> from @microsoft/power-apps-native-host. These controls read accent, surface, and text colors from PowerAppsProvider / ThemeProvider and produce Dataverse-compatible payloads.

import { FilePicker, ImagePicker } from '@microsoft/power-apps-native-host';
import type { PickedFileInfo, PickedImageInfo } from '@microsoft/power-apps-native-host';

// Image column — seed preview from Dataverse bytes/base64 and capture upload-ready payload.
<ImagePicker
  label="Site Photo"
  initialBase64={imageBase64}
  onImageChange={(image: PickedImageInfo | null) => { /* store image for upload */ }}
/>

// File column — edit-only pick/replace.
<FilePicker
  label="Specification Sheet"
  fileName={record.cr123_specsheet_name}
  onChange={(file: PickedFileInfo) => { /* store file for save */ }}
/>

// File column — view + replace.
<FilePicker
  label="Specification Sheet"
  fileName={record.cr123_specsheet_name}
  onDownload={() => Cr123_inspectionService.downloadFile(id, 'cr123_specsheet')}
  onChange={(file: PickedFileInfo) => { /* store file for save */ }}
/>

Save/read pattern for host picker-bound Dataverse columns:

// FILE/IMAGE columns: do not include picker bytes in the PATCH body.
// Save normal fields first, then upload through generated service helpers.
await Cr123_inspectionService.update(id, { cr123_name: name.trim() });
await Cr123_inspectionService.upload(id, 'cr123_specsheet', file.file, file.name);
await Cr123_inspectionService.upload(id, 'cr123_sitephoto', image.file, image.name);

// Download helpers are used for read/view scenarios.
const fileBytes = await Cr123_inspectionService.downloadFile(id, 'cr123_specsheet');
const imageBytes = await Cr123_inspectionService.downloadImage(id, 'cr123_sitephoto');

Use host ImagePicker / FilePicker with generated upload(...) for persistence and downloadFile(...) / downloadImage(...) for read/view. Do not use Service.update(...{ <imageColumn>: base64 }) for picker-driven image/file persistence.

Do not use raw expo-document-picker, expo-image-picker, expo-file-system, or expo-sharing to build custom UI for Dataverse File/Image columns. Host FilePicker and ImagePicker already handle permissions, reading, sharing/download affordances, and Dataverse-compatible payload shape.

Use /add-native wrappers only when the workflow is not a Dataverse File/Image column, for example importing a local PDF for offline parsing, exporting a generated report, saving a local draft packet, or opening a share sheet for an app-generated summary.

Supported capabilities

Apply the Native capability gate above. This is a capability map, not release evidence. Legacy leaf names below are aliases only; use aggregate subpaths when the resolved release includes controls, and keep a leaf import only when that release includes the matching leaf. Read installed public docs/types first.

CapabilityModuleWrapper to generateNotes
camera, take-photo, photo, expo-cameraexpo-image-pickersrc/native/camera.ts/add-native routes internally to add-camera for the photo artifact; expo-camera is a capability alias, not its required package
image-picker, gallery, expo-image-pickerexpo-image-pickersrc/native/camera.ts (pickImage)/add-native routes internally to add-camera; preserve compatible existing re-exports
barcode-scanner, qr-scanner, scanner, barcode, qrexpo-camerasrc/native/barcodeScanner.tsx/add-native routes internally to add-camera
document-pickerexpo-document-pickersrc/native/documentPicker.tsPicks/imports user-selected files (PDF, docs, etc.) from the device
pdf-viewer, native-pdf-viewer, pdf-control, open-pdf, @microsoft/power-apps-native-pdf-viewerControls /pdf or verified legacy PDF leafsrc/native/pdfViewer.ts/add-native routes internally to add-pdf-viewer; require the resolved contract's HTTPS/file URI support
pdf-report, pdf-export, generate-pdf, print-report, evidence-packetexpo-print (+ optional expo-sharing)src/native/pdfReport.ts/add-native routes internally to add-pdf-report; generated local files are shared only when expo-sharing is present, or uploaded to Dataverse
pen-input, signature, ink, draw, @microsoft/power-apps-native-pen-inputControls /pen or verified legacy pen leafsrc/native/penInput.ts/add-native routes internally to add-pen-input; captures PNG data URI
geolocation, location-tracking, background-location, gps-tracking, geo-tracking, @microsoft/power-apps-native-bglocationControls /geolocation or verified background-location leafsrc/native/geolocation.ts/add-native routes internally to add-geolocation; tracking + durable Dataverse sync, distinct from one-shot location
secure-storeexpo-secure-storesrc/native/secureStore.ts
file-systemexpo-file-systemsrc/native/fileSystem.ts
sharingexpo-sharingsrc/native/sharing.ts
locationResolved controls /geolocation or matching leaf; independently verified expo-location if applicablesrc/native/location.tsOne-shot only; geolocation helper skips tracking/table setup
biometrics, local-authenticationexpo-local-authenticationsrc/native/biometrics.tsUse only when included in the app's verified release
clipboardexpo-clipboardsrc/native/clipboard.tsUse only when included in the app's verified release
mail-composer, email-draftexpo-mail-composersrc/native/mailComposer.tsOpens native mail compose when the package is present; connectors still own server-side email sends
audioexpo-audiosrc/native/audio.tsUse for audio recording/playback only when package is present
videoexpo-videosrc/native/video.tsUse for video playback only when package is present
sensorsexpo-sensorssrc/native/sensors.tsUse only for sensor APIs exposed by the installed package
screen-orientationexpo-screen-orientationsrc/native/screenOrientation.tsUse only when package is present; do not edit native config
haptics, vibration-feedback, impact-feedback, selection-feedback, notification-feedbackexpo-hapticssrc/native/haptics.tsImpact, selection, and success/warning/error notification feedback
device-infoexpo-device / expo-application / expo-cellularsrc/native/deviceInfo.tsRead-only device/app/cellular metadata wrappers
date-time-picker@react-native-community/datetimepickerscreen-level component usageUse directly in form screens per screen-builder rules; no /add-native wrapper required

For custom workflows outside Dataverse File/Image form fields, use the image-picker capability via /add-native image-picker for user-selected photos and videos, or the document-picker capability via /add-native document-picker for documents and other files. These wrappers use scoped system-picker flows. Dataverse File/Image form fields remain the exception: use host <FilePicker> / <ImagePicker> controls as described above, not /add-native wrappers or raw Expo module imports.

PDF / pen routing rules

  • Do not treat every PDF request as document-picker.
  • Use document-picker when the user wants to pick, import, or upload a local PDF/document. This remains supported and should still be used for that use case.
  • Use pdf-report when the app generates a PDF from records, evidence, inspection data, certificates, receipts, or reports, but only if expo-print is present in package.json.
  • Use native-pdf-viewer / pdf-control for HTTPS or local file:// PDFs using the resolved /pdf or matching legacy contract (PDF 0.2.9+ file support). content://, blob:, and http:// URIs are unsupported.
  • If a request says "view/open PDF" but the Power Apps viewer package is absent, fall back to pdf-report only when the app is generating its own report and expo-print is present. Do not claim generic PDF viewing support through expo-print; it generates local files, it does not view arbitrary PDFs.
  • Use pen-input only for signatures, drawn approvals, ink notes, sketches, and handwritten sign-off through the resolved /pen or matching legacy contract.
  • For other use cases, use the relevant Expo module or other dependency already present in package.json; do not force the Power Apps extensions into unrelated flows.
  • For generated local PDFs from expo-print, use native PDF viewer 0.2.9+ for open/preview, expo-sharing for sharing, and Dataverse File storage for retention. Do not require expo-sharing merely to preview a local PDF.
  • Host FilePicker and ImagePicker are still correct for user-selected Dataverse File/Image form fields. Generated PDFs and pen captures use native wrappers first, then Dataverse persistence helpers.

Dataverse artifact persistence rules

  • Pen input returns a PNG data URI like data:image/png;base64,....
  • For Dataverse Image columns, normalize the data URI to the generated service payload shape. If raw base64 is required, strip the data:image/png;base64, prefix.
  • For Dataverse File columns, convert the generated PDF or signature PNG into upload bytes/File, save or update the parent row first, then upload through the generated service helper.
  • Never put File column bytes in the create/update JSON body. File bytes are uploaded only after the parent row ID exists.
  • Screens must handle unsupported, cancelled, upload failed, and viewer failed states explicitly. Pen cancellation is a non-error result that screens can ignore.

Missing or gated packages: the resolved release, installed versions, and matching native runtime are authoritative together. If any evidence is missing, stop with a transparency note; never claim native readiness from TypeScript alone.

Workflow

  1. Verify project → 2. Resolve release and capability → 3. Auto-route to dedicated skill if one exists → 4. Verify package in resolved release → 5. Write wrapper → 6. Type-check → 7. Summary

Step 1 — Verify project

cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
test -f app.config.js && test -f power.config.json && test -f package.json || { echo "BLOCKED: working_dir is not an initialized app" >&2; exit 1; }

After the project gate succeeds, resolve its native contract:

cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
node "${PLUGIN_ROOT}/scripts/resolve-mobile-release.js" --project-root '<working_dir>'

Step 2 — Resolve capability

Telemetry checkpoint: resolve_native_capability

If $ARGUMENTS includes a capability name, package name, or control name, use it. Otherwise look for a ## Native Capabilities section in native-app-plan.md and present the planned capabilities for confirmation. If neither exists, prompt the user with the supported-capabilities list above plus any relevant installed package from package.json that directly matches their request.

Normalize the capability name to lowercase, hyphenated form (e.g., Camera → camera, ImagePicker → image-picker, SecureStore → secure-store). Also normalize aliases: take-photo / photo / camera-control / expo-camera → camera; gallery / pick-image / expo-image-picker → image-picker; scanner / barcode / qr → barcode-scanner; open-pdf / view-pdf / pdf-control / pdf-viewer-control / @microsoft/power-apps-native-pdf-viewer → pdf-viewer; native-pdf-viewer → pdf-viewer; generate-pdf / pdf-export → pdf-report; signature / sign-off / ink / draw / pen-control / @microsoft/power-apps-native-pen-input → pen-input; location-tracking / background-location / gps-tracking / geo-tracking / track-location / power-apps-native-bglocation / @microsoft/power-apps-native-bglocation → geolocation; vibration / vibration-feedback / impact-feedback / selection-feedback / notification-feedback / expo-haptics → haptics.

When the user asks for "location" or "GPS", disambiguate by intent: continuous/background tracking or durable Dataverse upload → geolocation; a single foreground coordinate read → location. Both route to the geolocation helper with the mode preserved. The one-shot path has no app_id, data source, table verification, or tracking startup. If the intent is unclear, ask once. Normalize @microsoft/power-apps-native-controls/pdf, /pen, and /geolocation to their matching capability; resolve location mode separately.

If the user names something not in the supported table, apply the Native capability gate: resolve the relevant package from package.json, continue only when present and not runtime-banned, otherwise stop with a transparency note.

Step 3 — Route to nested helpers or inline wrappers

Telemetry checkpoint: dispatch_native_capability

For normalized camera, image-picker, barcode-scanner, qr-scanner, pdf-report, pdf-viewer, pen-input, location, or geolocation, do not fall through to the generic wrapper flow and do not tell the user to run another slash command. Read the nested helper and follow its steps inside this /add-native invocation:

cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
case "<capability>" in
  camera|image-picker|barcode-scanner|qr-scanner) test -f "${PLUGIN_ROOT}/skills/add-native/add-camera/SKILL.md" && echo "INTERNAL_HELPER:add-camera" ;;
  pdf-report) test -f "${PLUGIN_ROOT}/skills/add-native/add-pdf-report/SKILL.md" && echo "INTERNAL_HELPER:add-pdf-report" ;;
  pdf-viewer) test -f "${PLUGIN_ROOT}/skills/add-native/add-pdf-viewer/SKILL.md" && echo "INTERNAL_HELPER:add-pdf-viewer" ;;
  pen-input) test -f "${PLUGIN_ROOT}/skills/add-native/add-pen-input/SKILL.md" && echo "INTERNAL_HELPER:add-pen-input" ;;
  location|geolocation) test -f "${PLUGIN_ROOT}/skills/add-native/add-geolocation/SKILL.md" && echo "INTERNAL_HELPER:add-geolocation" ;;
  *) echo "INLINE" ;;
esac
  • INTERNAL_HELPER: read the printed helper file and execute its workflow with the same absolute working_dir, arguments, supplied answers, mode flags, and current owner/phase/approved_scope. The helper must bind every operation to that root using Step 0, even if launched from another directory. Each helper must execute native-artifact-compatibility.md before its writes/reuse and before its success summary; outer Step 5 is not reached on this branch. Propagate NEEDS_CONTEXT/BLOCKED and the artifact result to the owner, then STOP this leaf, not the owning workflow. Do not fall through to inline generation or report success for a partial helper result. /add-native remains the only user-facing command for these controls.
  • INLINE: continue to Step 4.

Step 4 — Verify module in the resolved release

Require a successful release resolution before this installed-manifest check. Confirm the exact installed version against the resolved inventory and read its public docs/types. A matching package name alone does not prove compatibility.

cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
node -e "const p = require('./package.json'); const m = '<resolved-package-name>'; if (!p.dependencies?.[m]) { console.error('MISSING: ' + m + '. Stop and reconcile the app with its verified release; do not install native packages or re-scaffold an existing app.'); process.exit(1); }"

If the check fails, STOP. Do not run npx expo install. Print the error verbatim.

Step 5 — Write wrapper

Telemetry checkpoint: generate_native_wrapper

Print before starting:

"→ Writing src/native/.ts (typed wrapper with discriminated-union result + iOS/Android platform guards)…"

Read and execute native-artifact-compatibility.md Steps 1–3 for the inline capability row before writing or reusing output. Create src/native/<wrapper-filename>.ts only when missing and in scope. If the file already exists, inspect its exports against the approved capability contract, including behavior and storage. Reuse it unchanged when compatible; make a scoped update without re-asking when already approved. Otherwise return NEEDS_CONTEXT to the owner (or ask standalone) before updating; never silently skip the feature or overwrite custom code.

Each wrapper exports:

  • request<Capability>Permission(): Promise<boolean> — only when the underlying API has a permission model (location, biometrics, notifications). Skip for capabilities without one (secure-store, file-system, sharing, clipboard).
  • One or two domain methods returning typed results.

The contract screen-builder agents rely on:

  • All wrappers return a discriminated-union result ({ ok: true, ... } | { ok: false, reason, message? }) — never throw
  • Unsupported runtime/platform states gracefully degrade or return { ok: false, reason: 'unsupported' } — never crash
  • Native controls guard the native platform before a lazy import inside try/catch; never eagerly evaluate controls in web. Expo APIs with documented web implementations retain their supported platform behavior.
  • Screens import these wrappers only for non-Dataverse native workflows. Dataverse File/Image fields use @microsoft/power-apps-native-host controls from the File/Image Picker Ownership section above.

Haptics wrapper

For normalized capability haptics, generate src/native/haptics.ts with this contract:

import { Platform } from 'react-native';

export type HapticImpactStyle = 'light' | 'medium' | 'heavy' | 'soft' | 'rigid';
export type HapticNotificationType = 'success' | 'warning' | 'error';
export type HapticResult =
  | { ok: true }
  | { ok: false; reason: 'unsupported' | 'error'; message: string };

async function runHaptic(
  effect: (haptics: typeof import('expo-haptics')) => Promise<void>,
): Promise<HapticResult> {
  if (Platform.OS !== 'ios' && Platform.OS !== 'android') {
    return {
      ok: false,
      reason: 'unsupported',
      message: 'Haptic feedback is available only on iOS and Android.',
    };
  }

  try {
    const Haptics = await import('expo-haptics');
    await effect(Haptics);
    return { ok: true };
  } catch (error) {
    return {
      ok: false,
      reason: 'error',
      message: error instanceof Error ? error.message : 'The native haptic call failed.',
    };
  }
}

export function triggerImpact(style: HapticImpactStyle = 'medium'): Promise<HapticResult> {
  return runHaptic((Haptics) => {
    const impactStyles = {
      light: Haptics.ImpactFeedbackStyle.Light,
      medium: Haptics.ImpactFeedbackStyle.Medium,
      heavy: Haptics.ImpactFeedbackStyle.Heavy,
      soft: Haptics.ImpactFeedbackStyle.Soft,
      rigid: Haptics.ImpactFeedbackStyle.Rigid,
    };
    return Haptics.impactAsync(impactStyles[style]);
  });
}

export function triggerNotification(
  type: HapticNotificationType = 'success'
): Promise<HapticResult> {
  return runHaptic((Haptics) => {
    const notificationTypes = {
      success: Haptics.NotificationFeedbackType.Success,
      warning: Haptics.NotificationFeedbackType.Warning,
      error: Haptics.NotificationFeedbackType.Error,
    };
    return Haptics.notificationAsync(notificationTypes[type]);
  });
}

export function triggerSelection(): Promise<HapticResult> {
  return runHaptic((Haptics) => Haptics.selectionAsync());
}

Screens call the wrapper only when haptics appear in the approved native-capabilities and per-screen plan. Choose feedback by semantics:

  • triggerImpact('light' | 'medium' | 'heavy' | 'soft' | 'rigid') for deliberate presses or physical-feeling actions.
  • triggerSelection() when a picker, segmented control, or other selection changes.
  • triggerNotification('success' | 'warning' | 'error') after the corresponding outcome is known.
  • Keep visual feedback as the primary signal. Inspect non-OK results and log them, but do not turn an otherwise successful business operation into a failure because tactile feedback is unavailable.

Screen usage after a successful operation:

setSaveState({ kind: 'success', message: 'Saved' });
const hapticResult = await triggerNotification('success');
if (!hapticResult.ok) {
  console.warn('[haptics] success feedback unavailable', hapticResult);
}

No permission request or app.config.js change is required for expo-haptics.

Other inline wrappers

Consult the module's published API docs (linked from its npm page) for method signatures and permission patterns. Use the secure-store skeleton below as the canonical example of the discriminated-union shape, then translate it to the target module's API.

Secure-store canonical skeleton:

// src/native/secureStore.ts
import { Platform } from 'react-native';

export type SecureResult<T> =
  | { ok: true; value: T }
  | { ok: false; reason: 'unsupported' | 'not-found' | 'error'; message?: string };

export async function getSecret(key: string): Promise<SecureResult<string>> {
  if (Platform.OS !== 'ios' && Platform.OS !== 'android') {
    return { ok: false, reason: 'unsupported', message: 'SecureStore is not available on this platform.' };
  }
  try {
    const SecureStore = await import('expo-secure-store');
    const value = await SecureStore.getItemAsync(key);
    if (value === null) return { ok: false, reason: 'not-found' };
    return { ok: true, value };
  } catch (e: any) {
    return { ok: false, reason: 'error', message: e?.message };
  }
}

export async function setSecret(key: string, value: string): Promise<SecureResult<true>> {
  if (Platform.OS !== 'ios' && Platform.OS !== 'android') {
    return { ok: false, reason: 'unsupported', message: 'SecureStore is not available on this platform.' };
  }
  try {
    const SecureStore = await import('expo-secure-store');
    await SecureStore.setItemAsync(key, value);
    return { ok: true, value: true };
  } catch (e: any) {
    return { ok: false, reason: 'error', message: e?.message };
  }
}

Step 6 — Type-check

Telemetry checkpoint: validate_native_wrapper

Print before starting:

"→ Running tsc to verify wrapper compiles (~10–20 seconds)."

cd -- '<working_dir>' || { echo "BLOCKED: cannot enter working_dir" >&2; exit 1; }
npx --no-install tsc --noEmit

Fix only in-scope wrapper-side errors. Execute the shared compatibility contract's Step 4 after type-checking: recheck all requested artifacts, API/behavior, and storage obligations before returning success. Type-check success alone is insufficient. Do not run platform-specific native build commands during normal /add-native use because the module is already part of the current template binary. When a template/base maintainer first adds expo-haptics or changes its version, that release must rebuild the Android and iOS base binaries so Expo autolinking includes the module.

Type-check success is not native device validation. Native package changes require a separately approved host migration and matching native binaries, not customer-side linking.

Step 7 — Summary

Return the shared compatibility result before the summary; use the actual created/updated/reused paths and do not claim completion for unresolved artifacts.

✅ Native wrapper generated: <capability>
─────────────────────────────────────────────
Module (release-matched)  : <package>@<resolved-version>
Release context          : <verified-release-id>
Wrapper created           : src/native/<capability>.ts
package.json              : unchanged ✓
app.config.js             : unchanged ✓

Type-check: PASS

Sample usage:

  import { takePhoto } from '../../src/native/camera';

  const result = await takePhoto();
  if (result.ok) {
    setPhotoUri(result.uri);
  } else if (result.reason === 'permission-denied') {
    showToast('Camera permission required');
  }

⚠️  No local native build performed. Wrapper edits use the matching verified
    player/base; package changes require a verified release migration.
    Type-check alone does not prove native execution or permission grants.
─────────────────────────────────────────────

Notes

  • This skill never modifies package.json, app.config.js, src/playerConfig.ts, src/generated/, or any screen file.
  • For unlisted capabilities, resolve against the app's verified native inventory. Missing support requires another verified release, not a new dependency or configuration toggle. Do NOT install or configure native modules yourself.
  • Pure-JavaScript libraries are out of scope for this skill. /create-mobile-app or /edit-app selects and installs them through shared/references/javascript-dependency-planning.md; no native wrapper or Android/iOS rebuild is needed. The prohibition above applies only to packages with native source/config.
canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill.Stars: 196kUpdated Claude CodeCodexVerifiedInstall