novahiz 0.1.0

package/bundled-skills/expo-examples/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: expo-examples
+description: Framework (OSS). Expo's official example projects - the expo/examples repo of ~70 `with-*` integrations (Stripe, Clerk, Supabase, OpenAI, maps, Reanimated, SQLite, Skia, NativeWind, and more). Use when integrating a third-party library or service into an existing Expo app and you want the canonical, version-matched pattern to adapt, or when scaffolding a new project from one with `npx create-expo --example`.
+allowed-tools: "Read,Bash(gh api:*),Bash(git clone:*),Bash(npx create-expo:*),Bash(npx degit:*),Bash(bun create:*)"
+version: 1.0.0
+license: MIT
+---
+
+# Expo Examples
+
+[expo/examples](https://github.com/expo/examples) is Expo's official library of ~70 **integration examples** — directories named `with-<library>` (e.g. `with-stripe`, `with-maps`), each built around **one** library or service. These are not full apps: they're **managed** projects (no `ios/`/`android/` dirs — native setup is via config plugins), and the typical one is a **single screen of ~100–200 lines**. Mine them for the canonical integration *pattern* — the dependency set, `app.json` config plugins, and minimal wiring Expo maintains against the current SDK — and adapt that into the user's app. Don't expect to lift an application architecture from them.
+
+Reach for an example before hand-rolling an integration. (Kinds — full-stack, showcases, starters — are noted in `./references/catalog.md`.)
+
+## Two modes
+
+1. **Inspiration / adapt** (most common) — the user already has a project. Find the matching example, read its key files, and apply the *pattern* to their code.
+2. **Scaffold** — greenfield. Start a fresh project directly from the example.
+
+## Workflow
+
+### 1. Find the right example
+
+Map the user's need to an example name (e.g. payments → `with-stripe`, auth → `with-clerk`). `./references/catalog.md` is a categorized snapshot for fast triage — but it drifts, so confirm against the live list:
+
+```bash
+# Live example names:
+gh api repos/expo/examples/contents --jq '.[] | select(.type=="dir" and (.name|startswith(".")|not)) | .name'
+# Aliases (renamed) + deprecated (dead/moved) examples — check before recommending:
+gh api repos/expo/examples/contents/meta.json --jq '.content' | base64 -d
+```
+
+`meta.json` is the source of truth for what's renamed or dead (deprecated examples are removed from the repo tree but still listed here, each with a `message`). If an example is in its `deprecated` map, don't recommend it — follow the `message` to the modern path. If it's in `aliases`, use the `destination`.
+
+### 2a. Inspiration mode — study without touching the user's project
+
+The common case: the user already has an app and wants to see how Expo does something. Read the example as **reference** and apply the patterns by hand — never scaffold an example on top of their project.
+
+**First, list the whole example in one call.** Integration code is often nested (e.g. Stripe's server routes live in `app/api/`), so a one-level listing misses the important files:
+
+```bash
+gh api 'repos/expo/examples/git/trees/master?recursive=1' \
+  --jq '.tree[].path | select(startswith("with-stripe/"))'
+```
+
+**Then read the high-signal files first:** `README.md` (setup) → `package.json` (deps) → `app.json` (config plugins / permissions) → the integration code the manifest revealed → `.env` (required secrets). Per file:
+
+```bash
+gh api repos/expo/examples/contents/with-stripe/utils/stripe-server.ts --jq '.content' | base64 -d
+# No gh? Raw URL (branch is master):
+curl -s https://raw.githubusercontent.com/expo/examples/master/with-stripe/utils/stripe-server.ts
+```
+
+**Reading more than a couple of files?** Many integrations are spread across server routes, a client provider, and config (Stripe is). Skip the per-file calls — pull the whole example into a **throwaway/gitignored dir (not the user's project)** and read it freely with Grep/Read, then apply by hand:
+
+```bash
+npx degit expo/examples/with-stripe /tmp/expo-ref/with-stripe   # clean copy, no git history
+# fallback without degit (sparse-checkout, no full ~64 MB clone):
+git clone --depth 1 --filter=blob:none --sparse https://github.com/expo/examples.git /tmp/expo-ref/examples \
+  && (cd /tmp/expo-ref/examples && git sparse-checkout set with-stripe)
+```
+
+Read from there with Grep/Read; delete the scratch dir when done.
+
+### 2b. Scaffold mode — new project from an example
+
+```bash
+npx create-expo --example with-stripe   # short form:  npx create-expo -e with-stripe
+bun create expo --example with-stripe    # with bun
+```
+
+### 3. Adapt into the user's app — non-destructively (critical)
+
+When the user already has an app, **add only what the example introduces; never overwrite their setup.**
+
+- **Version-align — don't copy pinned versions.** Examples track the **latest** SDK, so their `package.json` pins won't match an older project. Add only the *missing* deps with `npx expo install <pkg>` (it resolves SDK-correct versions) instead of copying exact versions.
+- **Merge config, don't replace it.** Add only the `app.json`/`app.config.*` plugins and permissions the example introduces that the user lacks — keep their existing config block intact.
+- **Port the integration code.**
+- **Recreate env vars** from the example's `.env` shape — it holds placeholders, never working secrets.
+
+**Done when** the integration code is ported and every dependency, config plugin, permission, and env var it needs is accounted for in the user's app — not when it merely *looks* wired up.
+
+## Gotchas
+
+- **Default branch is `master`,** not `main` (matters for raw URLs and sparse checkout).
+- **Single-click deploy.** Every example has a launch URL: `https://launch.expo.dev/?github=https://github.com/expo/examples/tree/master/<example>`.
+
+## Related skills
+
+- Native UI components (@expo/ui package) → `expo-ui`
+- Styling and native-feeling screens → `expo-native-ui`
+- Navigation and routing → `expo-router`
+- Authoring a native module → `expo-module`
+- Upgrade the SDK before adopting a latest-SDK example → `expo-upgrade`
+
+## References
+
+- `./references/catalog.md` — categorized snapshot of the example library for fast triage.
+
+## Submitting Feedback
+If you encounter errors, misleading or outdated information in this skill, report it so Expo can improve:
+```bash
+npx --yes submit-expo-feedback@latest --category skills --subject "expo-examples" "<actionable feedback>"
+```
+Only submit when you have something specific and actionable to report. Include as much relevant context as possible.
+If an AI agent repeatedly failed or the user had to take over an Expo task, load the expo-skill-feedback skill and follow its eval-candidate flow instead of reusing the command above.

package/bundled-skills/expo-examples/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Expo Examples"
+  short_description: "Adapt or scaffold from the expo/examples repo of with-* integrations (Stripe, Clerk, Supabase, maps, SQLite, and more)"
+  default_prompt: "Use $expo-examples when integrating a third-party library or service into an Expo app to find the canonical with-* example to adapt, or to scaffold a new project with npx create-expo --example."

package/bundled-skills/expo-examples/references/catalog.md

@@ -0,0 +1,105 @@
+# Example catalog (snapshot)
+
+A categorized view of [expo/examples](https://github.com/expo/examples) for fast triage. Each entry is a **single-concern integration demo** (one library/service, managed project, usually one screen) — not a full app. This snapshot drifts — the **live repo is the source of truth**. Confirm the exact name against `gh api repos/expo/examples/contents` and check `meta.json` for aliases/deprecations (see SKILL.md step 1) before recommending or scaffolding.
+
+Use any name with `npx create-expo --example <name>` (scaffold) or inspect it via `gh api repos/expo/examples/contents/<name>/<file>`.
+
+Most are single-screen integrations; a few differ:
+
+- **Full-stack** (include Expo Router `+api` routes — a backend too): `with-stripe`, `with-clerk`, `with-better-auth`, `with-openai`, `with-router-ai`, `with-graphql`, `with-s3`, `with-satori`.
+- **Larger showcases:** `with-shadcn`, `with-router-tv`, `with-router-menus`, `with-react-navigation`, `with-webgpu`.
+- **Starters (not integrations):** `blank`, `stickersmash`.
+
+## Auth & identity
+- `with-clerk` — Clerk authentication
+- `with-auth0` — Auth0 login
+- `with-better-auth` — Better Auth
+- `with-magic` — Magic passwordless auth
+- `with-facebook-auth` — Facebook login
+- `with-firebase-saml-login` — Firebase SAML SSO
+
+## Payments
+- `with-stripe` — Stripe payments (native + web)
+
+## Backend, data & storage
+- `with-convex` — Convex realtime backend
+- `with-legend-state-supabase` — Supabase + Legend-State sync
+- `with-firebase-storage-upload` — Firebase Storage uploads
+- `with-aws-storage-upload`, `with-s3` — AWS / S3 file uploads
+- `with-apollo`, `with-graphql` — GraphQL clients
+- `with-formdata-image-upload` — multipart image upload
+
+## Local database & state
+- `with-sqlite` — expo-sqlite
+- `with-libsql` — libSQL / Turso
+- `with-tinybase` — TinyBase local-first store
+- `with-zustand` — Zustand state management
+
+## Navigation & routing
+- `with-router` — Expo Router basics
+- `with-react-navigation` — React Navigation (stacks + tabs)
+- `with-drawer-navigation` — drawer navigator
+- `with-router-menus` — native context menus with Router
+- `with-router-uniwind` — Router + Uniwind styling
+- `with-router-ai` — Router + AI chat UI
+- `with-router-tv` — Router on TV
+- `with-react-router` — React Router (web)
+
+## Styling & UI
+- `with-tailwindcss` — Tailwind / NativeWind
+- `with-styled-components` — styled-components
+- `with-shadcn` — shadcn-style components
+- `with-moti` — Moti animations
+- `with-custom-font` — custom fonts
+- `with-svg` — react-native-svg
+- `with-icons` — icon sets
+- `with-splash-screen` — custom splash screen
+- `with-video-background` — full-screen video background
+
+## Animation & graphics
+- `with-reanimated` — Reanimated
+- `with-skia` — React Native Skia 2D graphics
+- `with-three`, `with-react-three-fiber` — three.js / R3F 3D
+- `with-webgpu` — WebGPU
+- `with-processing` — Processing-style sketches
+- `with-react-flow` — node/flow diagrams
+- `with-victory-native` — charts
+
+## AI & ML
+- `with-openai` — OpenAI API
+- `with-router-ai` — AI chat app with Expo Router
+- `with-google-vision` — Google Cloud Vision
+- `with-tfjs-camera` — TensorFlow.js on the camera
+
+## Media & device
+- `with-camera` — expo-camera
+- `with-maps` — react-native-maps
+- `with-webrtc` — WebRTC
+- `with-pdf` — render / view PDFs
+
+## Web & rendering
+- `with-nextjs` — Next.js + Expo
+- `with-rsc` — React Server Components
+- `with-react-strict-dom` — React Strict DOM
+- `with-react-compiler` — React Compiler
+- `with-html` — render raw HTML
+- `with-satori` — OG image generation with Satori
+- `with-workbox` — service worker / PWA
+- `with-webbrowser-redirect` — expo-web-browser auth redirect
+
+## Platform: TV, widgets
+- `with-tv` — Apple TV / Android TV
+- `with-widgets` — iOS / Android home-screen widgets
+
+## Tooling, testing & monorepo
+- `with-typescript` — TypeScript baseline
+- `with-yarn-workspaces` — Yarn monorepo
+- `with-storybook` — Storybook
+- `with-maestro` — Maestro E2E tests
+- `with-sentry` — Sentry error monitoring
+- `with-socket-io` — Socket.IO realtime
+- `with-github-remote-build-cache-provider` — remote build cache on GitHub
+
+## Starters
+- `blank` — minimal app
+- `stickersmash` — the tutorial app

package/bundled-skills/expo-migrate-module/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: expo-migrate-module
+description: Framework (OSS). Migrate an existing Apple/Swift Expo native module from the Expo Modules API 1.0 definition DSL to the 2.0 macro API (sometimes called v2) while preserving its JavaScript and TypeScript contract. Use when converting or incrementally adopting @ExpoModule, @JS, @Event, @SharedObject, or @Record in an existing module. Do not use for creating a new module, general Expo SDK upgrades, or Android/Kotlin migrations.
+version: 1.0.0
+license: MIT
+---
+
+# Migrate an Expo Module
+
+Migrate the Swift side of an existing Expo module without changing its observable JS API. Treat the current JS/TypeScript surface and tests as the compatibility contract. Leave Kotlin on the 1.0 DSL unless the user explicitly expands the task.
+
+## Prerequisite
+
+The Expo Modules API 2.0 macros require `expo` `57.0.7` or newer. Before editing, check the target's installed version (`expo` in `package.json`/lockfile, or `npm ls expo`). If it is older, stop and tell the user to upgrade first; do not attempt the migration against an unsupported version. This is a floor, not a guarantee: the exact macro and core surface still varies within `57.x`, so step 2 must still verify the checked-out source.
+
+## References
+
+- Read `references/migration-map.md` before changing source. It contains the 1.0-to-2.0 mappings, semantic traps, and mixed-mode rules.
+- Read `references/example.md` for a full before/after walkthrough of one module through mixed mode to a complete migration. Consult it when you need to see how the per-member rules compose.
+- Read `references/compatibility.md` when the checked-out `expo-modules-core` version or branch is not known to support every requested macro. It explains how to verify the actual compile-time and runtime surface instead of guessing from an SDK number.
+
+## Workflow
+
+### 1. Establish the contract
+
+Inspect repository instructions and the worktree before editing. Locate the Swift module classes, records, shared objects, native views, JS/TS bindings, tests, example app, podspec, and installed or checked-out `expo-modules-core`.
+
+Inventory every exported item before rewriting it:
+
+- module and shared-object JS names
+- function names, arity, labels, defaults, nullability, sync/async behavior, errors, and queue semantics
+- property names, mutability, and constant caching behavior
+- event wire names and payload shapes
+- record field names, defaults, requiredness, and nullability
+- shared-object constructors and instance/static placement
+- lifecycle hooks and views
+
+Use the TypeScript declarations and JS call sites to resolve ambiguity. Do not silently "improve" requiredness, rename an event, or change sync behavior during a syntax migration.
+
+### 2. Verify the available 2.0 surface
+
+Inspect the macro declarations and matching core hooks in the dependency actually used by the target. Do not assume that all items in the 2.0 design are present because one macro compiles.
+
+Classify each 1.0 item as:
+
+- **Migrate:** both its macro and required core runtime support exist.
+- **Keep in DSL:** mixed mode preserves it safely, or 2.0 lacks an equivalent.
+- **Blocked:** migration would alter the JS contract or requires unavailable runtime support.
+
+Prefer an incremental mixed-mode result over speculative generated code. Keep `definition()` for any remaining DSL elements; delete it only when it is empty and the resolved module name is preserved by `@ExpoModule`.
+
+### 3. Apply the migration
+
+Migrate one semantic group at a time: module naming, functions, properties/constants, events, shared objects, then records. Keep the diff narrow.
+
+Follow these invariants:
+
+- Preserve every existing JS-visible name explicitly when Swift naming rules or macro defaults differ.
+- Keep original optional/default behavior. An optional 1.0 record field must not become required merely because 2.0 can express required fields.
+- Do not migrate same-JS-name overloads unless the checked-out macro groups and dispatches them.
+- Do not migrate queue-pinned DSL functions as-is; restructure onto Swift Concurrency or dispatch to the original queue via a continuation, per the async-function rules in `references/migration-map.md`.
+- Do not migrate views, unions, synchronous events, or shared-object static functions without verified support.
+- Do not change Kotlin, JS wrappers, or public `.d.ts` files unless the user requested an API change.
+
+After each group, search for old DSL entries and call sites that should have moved. Avoid broad formatting or unrelated cleanup.
+
+### When a 2.0 equivalent is missing or a group fails
+
+When step 2 classified an item as **Blocked**, or a migrated group fails to build or breaks the contract, do not force it. Stop on that group and:
+
+1. **Ask the user how to proceed** for that item, with two options:
+   - **Co-exist:** keep the item in the 1.0 `definition()` DSL alongside the migrated `@ExpoModule` (mixed mode) and continue with the other groups.
+   - **Revert:** back out the group's edits, leaving it untouched on 1.0, and move on.
+
+   Default to co-existence when mixed mode is verified safe, since it preserves the most progress. Revert when the half-applied change left the module in a non-building state and cannot be salvaged incrementally.
+
+2. **Open a tracking issue on `expo/expo`** noting the functionality that 2.0 does not yet cover, so the gap is recorded rather than silently worked around. Use `gh issue create --repo expo/expo` and confirm with the user before posting (per repo conventions, do not post outward-facing comments without approval). Include:
+   - the 1.0 member and its JS contract
+   - the specific macro or core hook that is missing (cite the evidence gap from `references/compatibility.md`)
+   - the `expo-modules-core` version/branch checked out
+
+   Reference the issue in the handoff so the remaining DSL entry is traceable to a known limitation.
+
+Keep going with the groups that do migrate cleanly; one blocked member does not block the rest.
+
+### 4. Verify behavior
+
+Run the narrowest available checks first, then the real integration surface:
+
+1. Build or type-check the Apple module against the target `expo-modules-core`.
+2. Run native unit tests and JS/TS tests.
+3. Build and launch the example app when the repository provides one.
+4. Compare the final exported surface with the inventory from step 1.
+5. Search for stale `Name`, migrated `Function`/`Property`/`Constant`/`Events` entries, old `sendEvent` calls, `@Field`, and duplicate registrations.
+
+Expansion tests alone are insufficient: generated macro code can look correct while failing against mismatched core symbols. If dependencies changed or macro plugin flags are missing, reinstall JS dependencies as appropriate, run the repository's CocoaPods installation workflow, and restart Xcode before diagnosing plugin communication failures.
+
+## Handoff
+
+Report:
+
+- which members moved to 2.0
+- which members intentionally remain in the 1.0 DSL and why
+- any compatibility-sensitive choices, especially event names, record requiredness, constants, and queues
+- the commands run and any verification not completed
+
+## Submitting Feedback
+If you encounter errors, misleading or outdated information in this skill, report it so Expo can improve:
+```bash
+npx --yes submit-expo-feedback@latest --category skills --subject "expo-migrate-module" "<actionable feedback>"
+```
+Only submit when you have something specific and actionable to report. Include as much relevant context as possible.
+If an AI agent repeatedly failed or the user had to take over an Expo task, load the expo-skill-feedback skill and follow its eval-candidate flow instead of reusing the command above.

package/bundled-skills/expo-migrate-module/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Migrate Expo Module"
+  short_description: "Migrate Swift Expo modules from 1.0 DSL to 2.0"
+  default_prompt: "Use $expo-migrate-module to migrate this Expo module's Swift implementation from the 1.0 definition DSL to the 2.0 macro API without changing its JavaScript contract."

package/bundled-skills/expo-migrate-module/references/compatibility.md

@@ -0,0 +1,73 @@
+# Expo Modules API 2.0 Compatibility Checks
+
+The Expo Modules API 2.0 design and implementation evolve across the macros plugin and `expo-modules-core`. Verify the checked-out dependency instead of relying on an SDK-number claim.
+
+## Find the actual declarations
+
+Locate `ExpoModulesMacros.swift` in the target repository or installed dependencies (use your search tool, or portable shell commands - do not assume `rg` is installed):
+
+```bash
+find . -name 'ExpoModulesMacros.swift' -not -path '*/node_modules/.cache/*'
+```
+
+Inspect the declarations that the user's source can import:
+
+```bash
+grep -nE 'public macro (ExpoModule|JS|Event|SharedObject|Record|Union|ViewProps|ExpoView)' <path-to-ExpoModulesMacros.swift>
+```
+
+A declaration proves only that Swift recognizes the attribute. Also inspect the corresponding macro implementation and core runtime hooks.
+
+## Check paired core support
+
+Search the actual core source for the feature being migrated:
+
+```bash
+grep -rnE '_decorateModule|_decorateSharedObject|_constructSharedObject|_jsName|EventEmitter|emitSync|StaticProperty|AnyViewProps|PropsDiff|_updateViewProps|didCreate|__expo_onStartListeningToEvent' <expo-modules-core>
+```
+
+Use compile errors and symbol call sites to confirm signatures. The macros plugin and core can drift independently; a successful macro expansion does not prove the generated code compiles or is called at runtime.
+
+## Capability gates
+
+Treat these as independent capabilities:
+
+| Capability | Evidence required before migration |
+| --- | --- |
+| Module functions/properties | `@ExpoModule`/`@JS`, generated `_decorateModule`, and the core call site |
+| Module name | generated `_jsName` and core registration/name lookup that reads it |
+| Records | `@Record`, coding conformance/assertions, and field decode/encode support |
+| Async events | `@Event`, `EventEmitter`, and `BaseModule`/`SharedObject` conformance |
+| Shared-object instances | `_decorateSharedObject`, construction hook, and core invocation |
+| Shared-object static functions | constructor object passed to decoration and static function routing |
+| Synchronous events | `@Event(sync:)` plus core `emitSync` overloads |
+| Task-returning functions | `JavaScriptEncodable` conformance for `Task` in core (encode-only) |
+| Views | `@ViewProps`/`@ExpoView` plus the complete typed props update and event runtime |
+| Module lifecycle methods | `AnyModule` requirements/base implementations and holder call sites |
+
+If any required evidence is absent, keep that item in the 1.0 DSL.
+
+## Known migration hazards in the July 2026 plan
+
+Use this only as a warning list; checked-out source wins.
+
+- Same-JS-name `@JS` overload grouping/dispatch was designed but not built; duplicate bindings could silently overwrite each other.
+- `@Union` was not built.
+- Decode errors lacked the 1.0 argument-index wrapper. This affects diagnostics rather than call semantics, but tests asserting exact messages may fail.
+- `@ViewProps` had only an initial pure-macro slice; the UIKit typed props runtime and `@ExpoView` contract were still gated on core.
+- Shared-object instance functions, properties, setters, construction, and static properties were implemented; verify constructor-side routing before migrating static functions.
+- `@Event(sync: true)` macro generation existed, but core `emitSync` was still required.
+- Default asynchronous `@Event` was supported after core added `EventEmitter` to modules and shared objects.
+- `@JS` functions/properties, range-based arity, default/optional-aware calls, `@Record` field synthesis, async `@JavaScriptActor`, and instance shared-object decoration had landed in the macros work.
+
+## Integration verification
+
+Use the target project's own commands. A robust sequence is:
+
+1. Run macro/unit tests if working inside the macros package.
+2. Compile the migrated native module against the paired core checkout.
+3. Re-run CocoaPods installation when plugin dependencies or injection changed.
+4. Restart Xcode after swapping a macro plugin binary; cleaning DerivedData alone may not reload it.
+5. Build the example app and execute existing JS/TS behavior tests.
+
+Do not report a migration complete based only on textual expansion tests.

package/bundled-skills/expo-migrate-module/references/example.md

@@ -0,0 +1,212 @@
+# Worked Example: Full Module Migration
+
+This walks a single small module from the 1.0 DSL through mixed mode to a fully migrated 2.0 form. Every per-member rule lives in `migration-map.md`; this shows how they compose and how mixed mode is an intermediate state, not a failure.
+
+The module below is representative: a name, a sync function, two async functions (one that suspends, one that blocks), a settable property, a constant, an event with observing hooks, and a record.
+
+## Starting point: 1.0 DSL
+
+```swift
+import ExpoModulesCore
+
+@Record
+struct DownloadOptions {
+  var url: URL              // required
+  var retries: Int = 3      // omittable, default 3
+  var label: String?        // omittable and nullable
+}
+
+public final class DownloaderModule: Module {
+  private var volume: Double = 1
+
+  public func definition() -> ModuleDefinition {
+    Name("Downloader")
+
+    Events("onProgress")
+
+    OnStartObserving {
+      self.beginProgressUpdates()
+    }
+
+    OnStopObserving {
+      self.stopProgressUpdates()
+    }
+
+    Constant("buildInfo") { computeBuildInfo() }
+
+    Function("clamp") { (value: Double) -> Double in
+      return min(max(value, 0), 1)
+    }
+
+    Property("volume") { self.volume }
+      .set { self.volume = $0 }
+
+    AsyncFunction("download") { (options: DownloadOptions) -> String in
+      return try await self.performDownload(options)
+    }
+
+    AsyncFunction("clearCache") {
+      try FileManager.default.removeItem(at: self.cacheDirectory)
+    }
+  }
+
+  private func report(percent: Double) {
+    sendEvent("onProgress", ["percent": percent])
+  }
+}
+```
+
+The observable contract to preserve:
+
+| Member | JS name | Contract |
+| --- | --- | --- |
+| Module | `Downloader` | `requireNativeModule("Downloader")` |
+| `clamp` | `clamp` | sync, 1 arg, returns number |
+| `volume` | `volume` | read/write number |
+| `buildInfo` | `buildInfo` | read-only constant |
+| `download` | `download` | async, 1 record arg, returns string |
+| `clearCache` | `clearCache` | async, no args, blocking work runs off the JS thread |
+| `onProgress` | `onProgress` | event, payload `{ percent }` |
+| observing hooks | n/a | progress updates start/stop with the listener count |
+| `DownloadOptions` | n/a | `url` required; `retries` default 3; `label` nullable |
+
+## Intermediate: mixed mode
+
+Suppose the checked-out core supports everything used above: `@ExpoModule`, `@JS` functions/properties/constants, async `@JavaScriptActor`, `@Record`, default async `@Event`, and the module lifecycle hooks. One member is still blocked, by semantics rather than support: `clearCache` has a body that blocks and never suspends, and a 1.0 `AsyncFunction` runs it on a background queue automatically, while a 2.0 async member starts on the JS actor. Migrating it as-is would move blocking I/O onto the JS thread, so it stays in the DSL.
+
+The record migrates first because it is a pure data type and the function that consumes it depends on it. Its shape is already correct, so migration is just verifying each field decodes: `url`, `retries`, `label` all map cleanly, so `@Record` stays as-is (it was already using the macro here).
+
+```swift
+import ExpoModulesCore
+
+@Record
+struct DownloadOptions {
+  var url: URL
+  var retries: Int = 3
+  var label: String?
+}
+
+@ExpoModule("Downloader")
+public final class DownloaderModule: Module {
+  // Explicit wire name: default @Event would strip "on" and emit "progress".
+  @Event("onProgress")
+  var onProgress: (ProgressEvent) -> Void
+
+  @JS("clamp")
+  func clamp(value: Double) -> Double {
+    return min(max(value, 0), 1)
+  }
+
+  // Stored var -> JS getter + setter, matching the 1.0 get/set pair.
+  @JS
+  var volume: Double = 1
+
+  // A let is a natural constant: read-only from JS.
+  @JS
+  let buildInfo = computeBuildInfo()
+
+  @JS
+  func download(options: DownloadOptions) async throws -> String {
+    return try await performDownload(options)
+  }
+
+  // override: the hooks are inherited from the Module base class.
+  override func didStartListening(event: String) {
+    beginProgressUpdates()
+  }
+
+  override func didStopListening(event: String) {
+    stopProgressUpdates()
+  }
+
+  // Kept on the DSL: the body blocks without suspending, and a 2.0 async
+  // member would start it on the JS actor instead of a background queue.
+  public func definition() -> ModuleDefinition {
+    AsyncFunction("clearCache") {
+      try FileManager.default.removeItem(at: self.cacheDirectory)
+    }
+  }
+
+  private func report(percent: Double) {
+    onProgress(ProgressEvent(percent: percent))
+  }
+}
+
+@Record
+struct ProgressEvent {
+  var percent: Double
+}
+```
+
+Notes on the choices, each traceable to `migration-map.md`:
+
+- `Name("Downloader")` moved into `@ExpoModule("Downloader")`; the custom name is carried explicitly, never dropped.
+- `@Event("onProgress")` uses the explicit wire name to avoid the `on`-stripping default; the untyped dictionary became a typed `ProgressEvent`.
+- The duplicate `private var volume` field was removed once `@JS var volume` became the single source of truth. Watch for this: a 1.0 backing field plus a migrated `@JS var` of the same name is a double-declaration.
+- `Constant("buildInfo")` became `@JS let buildInfo`. Evaluation moves from the lazy 1.0 closure to module initialization, acceptable here because `computeBuildInfo()` is cheap; an expensive value would keep lazy storage behind a getter-only computed `@JS var`.
+- `OnStartObserving`/`OnStopObserving` became the `didStartListening(event:)`/`didStopListening(event:)` hooks, with `override` because the class inherits `Module`. The 1.0 hooks were module-wide, so the event argument is ignored.
+- `definition()` remains but now holds only the queue-sensitive `clearCache`. It is not deleted because it is non-empty.
+
+## Fully migrated (after explicitly moving the blocking work off the JS actor)
+
+The DSL entry for `clearCache` was the semantics-preserving default. To finish the migration, replace the implicit background queue with an explicit hop so the blocking work still never runs on the JS thread, then delete the empty `definition()`.
+
+```swift
+import ExpoModulesCore
+
+@Record
+struct DownloadOptions {
+  var url: URL
+  var retries: Int = 3
+  var label: String?
+}
+
+@Record
+struct ProgressEvent {
+  var percent: Double
+}
+
+@ExpoModule("Downloader")
+public final class DownloaderModule: Module {
+  @Event("onProgress")
+  var onProgress: (ProgressEvent) -> Void
+
+  @JS("clamp")
+  func clamp(value: Double) -> Double {
+    return min(max(value, 0), 1)
+  }
+
+  @JS
+  var volume: Double = 1
+
+  @JS
+  let buildInfo = computeBuildInfo()
+
+  @JS
+  func download(options: DownloadOptions) async throws -> String {
+    return try await performDownload(options)
+  }
+
+  @JS
+  func clearCache() async throws {
+    // Explicit hop: the body blocks, so it must not run on the JS actor.
+    try await Task.detached {
+      try FileManager.default.removeItem(at: self.cacheDirectory)
+    }.value
+  }
+
+  override func didStartListening(event: String) {
+    beginProgressUpdates()
+  }
+
+  override func didStopListening(event: String) {
+    stopProgressUpdates()
+  }
+
+  private func report(percent: Double) {
+    onProgress(ProgressEvent(percent: percent))
+  }
+}
+```
+
+`definition()` is gone only because it was empty and `@ExpoModule("Downloader")` preserves the resolved name. If any member had stayed blocked or unverified, the mixed-mode form above is the correct place to stop, not a broken end state.