[codex] Add iOS contextual strings fallback docs

[riderx]

What

• Add contextualStrings to SpeechRecognitionStartOptions.
• Pass contextualStrings into the iOS SFSpeechRecognizer request path.
• Document the iOS fallback behavior: SFSpeechRecognizer remains the default, older iOS versions use it, and useOnDeviceRecognition only opts into SpeechAnalyzer when supported.
• Make the packed example CI helper sync existing Android/iOS platforms instead of failing on cap add when the example app already includes native projects.
• Add a narrow SwiftLint directive for the existing oversized plugin class so CI lint can complete without a broad refactor.

Why

• Fixes feat: Support older iOS versions with SFSpeechRecognizer and contextualStrings #8.
• Older iOS users need the legacy recognizer path documented and available.
• Apps can now bias iOS recognition toward domain-specific words when using the SFSpeechRecognizer path.
• The existing packed-example CI script could fail before validating the package because native platform folders already exist.

How

• Parse, trim, and drop empty contextualStrings values from the Capacitor call.
• Set SFSpeechAudioBufferRecognitionRequest.contextualStrings before starting the legacy recognition task.
• Regenerate README API docs through docgen.
• Use cap sync for existing example platforms and cap add only when the platform directory is missing.

Testing

• bun run fmt
• JAVA_HOME=/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home ANDROID_HOME=/Users/martindonadieu/Library/Android/sdk ANDROID_SDK_ROOT=/Users/martindonadieu/Library/Android/sdk bun run lint
• JAVA_HOME=/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home ANDROID_HOME=/Users/martindonadieu/Library/Android/sdk ANDROID_SDK_ROOT=/Users/martindonadieu/Library/Android/sdk bun run verify
• bun run check:wiring
• bash .github/scripts/verify-packed-example.sh web
• JAVA_HOME=/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home ANDROID_HOME=/Users/martindonadieu/Library/Android/sdk ANDROID_SDK_ROOT=/Users/martindonadieu/Library/Android/sdk bash .github/scripts/verify-packed-example.sh android
• bash .github/scripts/verify-packed-example.sh ios

Not Tested

• Live iOS microphone recognition with a real contextualStrings vocabulary on device.

Summary by CodeRabbit

• New Features

  • Added contextualStrings option to provide contextual phrases that bias speech recognition results on iOS

• Documentation

  • Updated documentation explaining iOS fallback to legacy SFSpeechRecognizer when on-device recognition is unavailable
  • Documented new contextualStrings option with platform-specific behavior details

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 9df99818-d0ef-48a4-a5f7-f71ccb7ad85a

📥 Commits

Reviewing files that changed from the base of the PR and between 0b6099d and 18dc18c.

📒 Files selected for processing (4)

• .github/scripts/verify-packed-example.sh
• README.md
• ios/Sources/SpeechRecognitionPlugin/SpeechRecognitionPlugin.swift
• src/definitions.ts

---

📝 Walkthrough

Walkthrough

Adds optional contextualStrings configuration to improve iOS speech recognition on the legacy SFSpeechRecognizer path. The plugin now reads and sanitizes contextual phrases from the API call and applies them when available. Documentation clarifies fallback behavior when on-device recognition is unavailable on older iOS versions or unsupported locales.

Changes

iOS Contextual Strings and Fallback Support

Layer / File(s)	Summary
API Contract and Type Definition src/definitions.ts	SpeechRecognitionStartOptions adds optional contextualStrings?: string[] with platform-specific documentation. useOnDeviceRecognition documentation is expanded to describe iOS fallback to SFSpeechRecognizer on older versions or unsupported locales.
iOS Plugin Implementation ios/Sources/SpeechRecognitionPlugin/SpeechRecognitionPlugin.swift	Plugin.start reads contextualStrings from the Capacitor call, sanitizes by trimming whitespace and filtering empty values, then stores in RecognitionOptions. Legacy recognition path conditionally assigns contextual strings to SFSpeechAudioBufferRecognitionRequest.contextualStrings when non-empty. SwiftLint type_body_length is disabled/re-enabled to accommodate the expanded struct.
Documentation and API Reference README.md	New subsection documents iOS fallback to SFSpeechRecognizer when on-device path is unavailable, explains contextualStrings usage, and includes an example start call. On-device recognition bullet list updated to state fallback condition. API reference table for SpeechRecognitionStartOptions adds contextualStrings entry and expands option descriptions for platform-specific behavior.
Build Script Platform Setup Refactoring .github/scripts/verify-packed-example.sh	Introduces sync_or_add_platform helper that checks platform directory existence and runs bunx cap sync (if exists) or bunx cap add (if new). Android and iOS case branches now call this helper instead of unconditional platform commands.

Estimated Code Review Effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 Whispers from the warren, clear and true,
Old iOS paths find words anew,
ContextualStrings dance with grace,
Recognition blooms in every place! 🌱✨

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Out of Scope Changes check	❓ Inconclusive	The PR includes a refactoring of the packed-example CI helper script to use sync_or_add_platform logic, which is outside the scope of the iOS contextual strings feature and fallback documentation but appears to be a supporting CI improvement.	Clarify whether the packed-example script refactoring is necessary for the PR objectives or should be separated into a distinct change.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title refers to adding iOS contextual strings fallback docs, which is a real part of the changeset covering documentation updates and contextualStrings support, but understates the full scope including the implementation of contextualStrings feature and packed-example CI helper refactoring.
Linked Issues check	✅ Passed	The PR successfully implements both requirements from issue #8: provides SFSpeechRecognizer as a fallback for older iOS versions via conditional logic and documents useOnDeviceRecognition behavior, and adds contextualStrings support with proper parsing and passing to the legacy recognition path.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/issue-8-sfspeech-fallback

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

src/definitions.ts

Oops! Something went wrong! :(

ESLint: 8.57.1

ESLint couldn't find the plugin "@typescript-eslint/eslint-plugin".

(The package "@typescript-eslint/eslint-plugin" was not found when loaded as a Node module from the directory "".)

It's likely that the plugin isn't installed correctly. Try reinstalling by running the following:

npm install `@typescript-eslint/eslint-plugin`@latest --save-dev

The plugin "@typescript-eslint/eslint-plugin" was referenced from the config file in "package.json » @ionic/eslint-config/recommended » ./index".

If you still can't figure out the problem, please stop by https://eslint.org/chat/help to chat with the team.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

Beta npm build

Maintainers can publish this PR to npm for fast testing.

Comment /publish-beta after the PR checks are green.

The workflow will:

• publish a prerelease package on the beta tag
• add a pinned pr-9 dist-tag for this exact PR build
• update this comment with the install command

Security note: beta publish is only enabled for branches inside this repository.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.