novahiz 0.1.0

package/bundled-skills/expo-migrate-module/references/migration-map.md

@@ -0,0 +1,306 @@
+# 1.0 to 2.0 Migration Map
+
+Use this reference while editing. Preserve behavior first; macro adoption is secondary.
+
+## Module and naming
+
+Convert the module class and remove `Name(...)` only when the paired core reads the macro-synthesized name:
+
+```swift
+// 1.0
+public final class CameraModule: Module {
+  public func definition() -> ModuleDefinition {
+    Name("Camera")
+  }
+}
+
+// 2.0
+@ExpoModule("Camera")
+public final class CameraModule: Module {}
+```
+
+Always carry a custom 1.0 name into `@ExpoModule("...")`. A stale `Name(...)` can override or conflict with the 2.0 name depending on the core revision. In mixed mode, remove `Name(...)` only after verifying the installed `_jsName` contract.
+
+## Functions
+
+Move a DSL closure into a real method and use `@JS("wireName")` when the Swift method name is different:
+
+```swift
+// 1.0
+Function("sum") { (a: Double, b: Double) -> Double in
+  return a + b
+}
+
+// 2.0
+@JS("sum")
+func add(a: Double, b: Double) -> Double {
+  return a + b
+}
+```
+
+Preserve:
+
+- the JS name
+- positional arity
+- optional arguments and Swift defaults
+- thrown errors and return type
+- whether the result is synchronous or a Promise
+
+Do not migrate functions that resolve to the same JS name unless the checked-out macro has overload grouping and collision diagnostics. Older 2.0 implementations install one property per declaration, so the last overload silently wins.
+
+Reject or keep in DSL any unsupported signature such as variadics, `inout`, unresolved generics, or closure parameters without verified callback support. A `Promise` parameter is also unsupported; refactor it as described under Async functions.
+
+### Async functions
+
+A `Promise` parameter is not supported in a `@JS` signature; 2.0 drops the trailing-`Promise` argument entirely. A Promise-returning function has three shapes in 2.0. Pick by how the underlying work produces its result.
+
+**1. Standard `async` method.** The common case. Swift `async` maps to a JS Promise:
+
+```swift
+// 1.0
+AsyncFunction("load") { (url: URL) -> String in
+  return try loadSynchronously(url)
+}
+
+// 2.0
+@JS
+func load(url: URL) async throws -> String {
+  return try await loadResource(url)
+}
+```
+
+**2. Checked continuation.** When the result arrives through a delegate or completion handler that fires once, wrap it with `withCheckedThrowingContinuation` (or `withCheckedContinuation` for non-throwing callbacks, or an `AsyncStream` for repeated values). This is the usual refactor for a 1.0 `AsyncFunction` that took a trailing `Promise` instance:
+
+```swift
+// 1.0
+AsyncFunction("start") { (promise: Promise) in
+  scanner.start(
+    onSuccess: { result in promise.resolve(result) },
+    onFailure: { error in promise.reject(error) }
+  )
+}
+
+// 2.0
+@JS
+func start() async throws -> ScanResult {
+  return try await withCheckedThrowingContinuation { continuation in
+    scanner.start(
+      onSuccess: { result in continuation.resume(returning: result) },
+      onFailure: { error in continuation.resume(throwing: error) }
+    )
+  }
+}
+```
+
+Resume the continuation exactly once on every path. If the callback API cannot guarantee that, or the refactor is otherwise unsafe, keep the function on the DSL instead of forcing it.
+
+**3. Synchronous method returning a `Task`.** The `Task` encodes to a promise that settles with its result. Use it when the work is naturally a `Task`, or when a promise is needed as a value nested inside another encoded result rather than as the function's own return:
+
+```swift
+// 2.0
+@JS
+func download(url: URL) -> Task<DownloadResult, any Error> {
+  return Task {
+    try await self.downloader.download(url)
+  }
+}
+```
+
+This shape requires the `JavaScriptEncodable` conformance for `Task` in the checked-out core (encode-only; a JS promise does not decode back into a `Task`). Verify it exists before using this shape; prefer shape 1 or 2 when it is absent.
+
+Do not assume scheduling is unchanged. 2.0 async members are `@JavaScriptActor`-isolated and begin on the JS thread until their first real suspension. A 1.0 `.runOnQueue(...)` function or a workload that relied on automatic background execution must not be migrated as-is. Never move blocking I/O directly onto the JS actor.
+
+For a queue-pinned 1.0 function, prefer restructuring the work onto the Swift Concurrency model (structured concurrency, an actor, or a detached task for blocking work). When that is not feasible because the queue itself is the contract, for example a library that must be called from one serial queue, convert to an `async` method that dispatches to that queue inside a checked continuation:
+
+```swift
+// 1.0
+AsyncFunction("process") { (input: String) -> String in
+  return try self.processor.process(input)
+}
+.runOnQueue(processingQueue)
+
+// 2.0
+@JS
+func process(input: String) async throws -> String {
+  return try await withCheckedThrowingContinuation { continuation in
+    processingQueue.async {
+      do {
+        continuation.resume(returning: try self.processor.process(input))
+      } catch {
+        continuation.resume(throwing: error)
+      }
+    }
+  }
+}
+```
+
+## Properties and constants
+
+Map a getter to a getter-only `@JS var`; map a getter/setter pair to a settable stored or computed `@JS var`:
+
+```swift
+// 1.0
+Property("volume") { self.volume }
+  .set { self.volume = $0 }
+
+// 2.0
+@JS
+var volume: Double = 1
+```
+
+Access control does not define JS mutability. Verify whether the declaration is syntactically settable; a stored `var` normally produces a JS setter.
+
+Map a 1.0 `Constant` to a `@JS let`; a `let` property is a natural constant and produces a read-only JS property:
+
+```swift
+// 1.0
+Constant("apiVersion") { 3 }
+
+// 2.0
+@JS
+let apiVersion = 3
+```
+
+Evaluation timing shifts: a 1.0 `Constant` closure runs lazily, while a `let` initializes with the module instance. When the value is expensive and must stay deferred, keep private lazy storage and expose a getter-only computed property (a `var` with a `{ }` getter body and no storage of its own), not a stored `lazy var`:
+
+```swift
+private lazy var cachedInfo = computeInfo()
+
+@JS
+var info: Info {  // computed: recomputes nothing, just returns the cached value
+  return cachedInfo
+}
+```
+
+Do not expose a cached value as a settable `lazy @JS var`.
+
+## Events
+
+Replace `Events(...)` plus `sendEvent(...)` with a typed function property:
+
+```swift
+@Record
+struct ProgressEvent {
+  var percent: Double
+}
+
+// Explicit string preserves the old wire name.
+@Event("onProgress")
+var onProgress: (ProgressEvent) -> Void
+
+func report(percent: Double) {
+  onProgress(ProgressEvent(percent: percent))
+}
+```
+
+The default `@Event` wire name strips a leading `on` and decapitalizes the remainder: Swift `onProgress` emits `progress`. 1.0 modules commonly expose `onProgress`. During migration, pass the original wire name explicitly unless an intentional JS breaking change was approved.
+
+Use `() -> Void` for no-payload events. For payloads, create or reuse a `JavaScriptEncodable` type instead of preserving an untyped dictionary. Migrate `OnStartObserving` and `OnStopObserving` to the `didStartListening(event:)`/`didStopListening(event:)` lifecycle hooks (see Views and lifecycle).
+
+Default `@Event` dispatch schedules onto the JS thread and is callable from other isolation contexts. Do not use `sync: true` unless core provides the matching `emitSync` overloads.
+
+## Shared objects
+
+Move instance behavior from a `Class(...)` block onto the `SharedObject` subclass:
+
+```swift
+// 2.0
+@SharedObject
+final class Download: SharedObject {
+  @JS
+  init(url: URL) {
+    self.url = url
+  }
+
+  @JS
+  func pause() {}
+
+  @JS
+  var progress: Double { currentProgress }
+
+  // Installs on the JS class (constructor) object, not the prototype.
+  @JS
+  static let maxConcurrent = 4
+}
+
+@ExpoModule(classes: [Download.self])
+final class DownloadModule: Module {}
+```
+
+Drop the leading owner argument used by instance DSL closures; use `self` in the real instance method. Preserve constructor arity and JS member names.
+
+Migrate only when the checked-out core supplies the shared-object decoration and construction hooks. Static properties migrate as Swift `static` or `class` properties and install on the JS class (constructor) object rather than the prototype; verify constructor-side routing for static functions before migrating them, since instance support does not imply static-function support. Never create both a 1.0 `Class(...)` entry and a 2.0 registration for the same class without confirming that core intentionally merges them.
+
+Static members belong to shared objects, not modules: a module is exported to JS as an instance, so Swift `static` members on a `Module` class are not useful there. Keep module-level values as instance `@JS` members.
+
+## Records
+
+Attach `@Record`, remove field wrappers, and encode requiredness in the declaration:
+
+```swift
+@Record
+struct Options {
+  var source: URL       // required
+  var retries: Int = 3  // omittable; default applies
+  var label: String?    // omittable and nullable
+}
+```
+
+Rules:
+
+- non-optional with no default: required
+- any property with a default: omittable
+- optional type: omittable and nullable
+
+Preserve the 1.0 contract exactly. For example, migrate `@Field var source: URL? = nil` to `var source: URL?`, not to `var source: URL`, unless the user approved a breaking change.
+
+Every stored property is part of the 2.0 record surface. If the old type contains stored bookkeeping that was not a 1.0 field, move it out of the record or leave the type on 1.0; there is no field opt-out. Verify that each field supports the required `JavaScriptDecodable`/`JavaScriptEncodable` direction.
+
+Do not adopt `@Union` until that macro and its coding witnesses exist in the target.
+
+## Views and lifecycle
+
+Keep UIKit `View`, `Prop`, view `Events`, and `OnViewDidUpdateProps` DSL entries until the target includes the complete `@ViewProps`/`@ExpoView` core contract. Macro declarations or expansion tests alone do not prove the runtime update path exists.
+
+Module lifecycle is core-owned rather than macro-generated. The DSL components map to hook methods with no-op defaults:
+
+| 1.0 | 2.0 |
+| --- | --- |
+| `OnCreate` | `didCreate()` |
+| `OnDestroy` | `willDestroy()` |
+| `OnStartObserving` | `didStartListening(event:)` |
+| `OnStopObserving` | `didStopListening(event:)` |
+
+Rules:
+
+- Use the `override` keyword when the class inherits `Module`/`BaseModule`; define the hooks directly (no `override`) when the conformance comes only from `@ExpoModule`. Hooks added only in a subclass of a macro module are not called; keep them on the class that declares the conformance.
+- The listening hooks receive the event name. A module-wide 1.0 `OnStartObserving` ignores the argument; a per-event `OnStartObserving("name")` becomes a comparison on it.
+- `didCreate()` runs after the module is registered, slightly later than 1.0 `OnCreate`, which fires before registration; `willDestroy()` runs at holder teardown. Verify nothing depends on the earlier timing before migrating `OnCreate`.
+- DSL lifecycle components can remain during an incremental migration and each fires exactly once, but do not implement a DSL component and its hook for the same behavior, or the work runs twice.
+
+There is no 2.0 replacement for every lifecycle component; for example, retain app-context teardown handling when no matching hook exists.
+
+## Mixed mode
+
+`@ExpoModule` may coexist with a non-empty `definition()` when the paired core supports merging the two surfaces. Keep only unsupported entries in the DSL and avoid duplicate names across macro and DSL registrations.
+
+Before deleting `definition()`, verify that it contains no:
+
+- views or view events
+- lifecycle or app-context listeners
+- queue-pinned functions
+- shared-object static functions or other unsupported definitions
+
+## Contract checklist
+
+For every migrated member compare before and after:
+
+| Concern | Must remain stable |
+| --- | --- |
+| Module | registration name and `requireNativeModule` key |
+| Function | JS name, accepted arity, omitted/default behavior, sync/Promise result |
+| Property | JS name, read/write behavior, evaluation/caching |
+| Event | listener string, payload shape, timing |
+| Record | field names, requiredness, nullability, defaults |
+| Shared object | constructor shape, prototype vs constructor placement, identity |
+| Execution | JS actor, main actor, background queue, ordering |

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

@@ -0,0 +1,151 @@
+---
+name: expo-module
+description: Framework (OSS). Guide for creating and writing Expo native modules and views using the Expo Modules API (Swift, Kotlin, TypeScript). Covers module definition DSL, native views, shared objects, config plugins, lifecycle hooks, autolinking, and type system. Use when building or modifying native modules for Expo. Not for migrating an existing Swift module from the definition DSL to the Expo Modules API 2.0 macros; use expo-migrate-module (from the expo-experiments plugin) for that.
+version: 1.0.0
+license: MIT
+---
+
+# Writing Expo Modules
+
+Complete reference for building native modules and views using the Expo Modules API. Covers Swift (iOS), Kotlin (Android), and TypeScript.
+
+## When to Use
+
+- Creating a new Expo native module or native view
+- Adding native functionality (camera, sensors, system APIs) to an Expo app
+- Wrapping platform SDKs for React Native consumption
+- Building config plugins that modify native project files
+- Adding Android, Apple, or web support to an existing Expo module
+- Editing `expo-module.config.json`, config plugins, or lifecycle hooks
+
+To migrate an existing Swift module from the definition DSL to the Expo Modules API 2.0 macros (`@ExpoModule`, `@JS`, `@Event`), use the `expo-migrate-module` skill (from the `expo-experiments` plugin) instead.
+
+## References
+
+Consult these resources as needed:
+
+```
+references/
+  create-expo-module.md      Scaffolding and add-platform-support workflow, defaults, and quirks
+  native-module.md           Module definition DSL: Name, Function, AsyncFunction, Property, Constant, Events, type system, shared objects
+  native-view.md             Native view components: View, Prop, EventDispatcher, view lifecycle, ref-based functions
+  lifecycle.md               Lifecycle hooks: module, iOS app/AppDelegate, Android activity/application listeners
+  config-plugin.md           Config plugins: modifying Info.plist, AndroidManifest.xml, reading values in native code
+  module-config.md           expo-module.config.json fields, file placement, and autolinking behavior
+```
+
+## Quick Start
+
+Prefer `create-expo-module` over manually creating native module files and directories. In practice, the best path is usually to create the scaffold first and then build on top of it. The scaffold sets up the expected layout, `expo-module.config.json`, podspec or Gradle files, TypeScript bindings, and the standalone example app flow.
+
+If an existing Expo module only needs another platform, use `create-expo-module add-platform-support` instead of manually copying native directories.
+
+See [references/create-expo-module.md](references/create-expo-module.md) before scaffolding or extending a module. It covers:
+
+- local vs standalone modules
+- `--platform`, `--features`, `--barrel`, `--package-manager`, and non-interactive mode
+- `expo.autolinking.nativeModulesDir`
+- `add-platform-support` behavior and quirks
+
+## Recommended Workflow
+
+1. Choose the scaffold type first:
+   - **Local module** for one app
+   - **Standalone module** for reuse, monorepos, or publishing
+2. Determine native `expo-module` features that you will need.
+   - Based on the user's instructions determine which feature scaffolding will be useful.
+   - Available features: `Constant`, `Function`, `AsyncFunction`, `Event`, `View`, `ViewEvent`, `SharedObject`
+3. Scaffold deliberately:
+   - pass an explicit slug or path
+   - choose `--platform` intentionally instead of relying on defaults
+   - use `--features` to choose code samples which you will modify in the next step to match the real implementation.
+4. Replace generated example code with the real implementation.
+5. If you add a new platform later, prefer `add-platform-support` over manual file copying.
+
+## Practical Scaffolding Rules
+
+- Feature examples are **opt-in**. A newly scaffolded module may be minimal if no features were selected.
+- `ViewEvent` implies `View`.
+- Local modules do **not** generate an `index.ts` barrel by default. Use `--barrel` only if you want one.
+- In non-interactive local scaffolding, pass the positional slug or path explicitly. `--name` changes the native class name, not the folder name.
+- Local modules live in `expo.autolinking.nativeModulesDir` when configured, otherwise in `modules/`.
+- Standalone modules have their own package metadata, scripts, and usually an example app. Local modules use the host app's tooling instead.
+
+## Core File Shapes
+
+The Swift and Kotlin DSL share the same structure. Swift is usually the clearest primary example; consult the references for feature-specific details.
+
+## Module Structure Reference
+
+The Swift and Kotlin DSL share the same structure. Both platforms are shown here for reference — in other reference files, Swift is shown as the primary language unless the Kotlin pattern meaningfully differs.
+
+**Swift (iOS):**
+
+```swift
+import ExpoModulesCore
+
+public class MyModule: Module {
+  public func definition() -> ModuleDefinition {
+    Name("MyModule")
+
+    Function("hello") { (name: String) -> String in
+      return "Hello \(name)!"
+    }
+  }
+}
+```
+
+**Kotlin (Android):**
+
+```kotlin
+package expo.modules.mymodule
+
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+
+class MyModule : Module() {
+  override fun definition() = ModuleDefinition {
+    Name("MyModule")
+
+    Function("hello") { name: String ->
+      "Hello $name!"
+    }
+  }
+}
+```
+
+**TypeScript:**
+
+```typescript
+import { requireNativeModule } from "expo";
+
+const MyModule = requireNativeModule("MyModule");
+
+export function hello(name: string): string {
+  return MyModule.hello(name);
+}
+```
+
+### expo-module.config.json
+
+```json
+{
+  "platforms": ["android", "apple"],
+  "apple": {
+    "modules": ["MyModule"]
+  },
+  "android": {
+    "modules": ["expo.modules.mymodule.MyModule"]
+  }
+}
+```
+
+Note: iOS uses just the class name; Android uses the fully-qualified class name (package + class). See `references/module-config.md` for all fields.
+
+## 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-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-module/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Expo Module"
+  short_description: "Build Expo native modules and native views with Swift, Kotlin, TypeScript, autolinking, and config plugins"
+  default_prompt: "Use $expo-module to scaffold, implement, clean up, or review Expo native modules, native views, shared objects, lifecycle hooks, autolinking configuration, and config plugins."

package/bundled-skills/expo-module/references/config-plugin.md

@@ -0,0 +1,90 @@
+# Config Plugins Reference
+
+Config plugins customize native Android and iOS projects generated with `npx expo prebuild`. They are synchronous functions that accept an `ExpoConfig` and return a modified version.
+
+## Plugin Structure
+
+```
+my-module/
+  plugin/
+    tsconfig.json
+    src/
+      index.ts
+  app.plugin.js         # Entry: module.exports = require('./plugin/build');
+```
+
+## Writing a Plugin
+
+Plugin functions follow the `with` prefix naming convention.
+
+```typescript
+import {
+  ConfigPlugin,
+  withInfoPlist,
+  withAndroidManifest,
+  AndroidConfig,
+} from "expo/config-plugins";
+
+const withMyConfig: ConfigPlugin<{ apiKey: string }> = (config, { apiKey }) => {
+  // iOS: modify Info.plist
+  config = withInfoPlist(config, (config) => {
+    config.modResults["MY_API_KEY"] = apiKey;
+    return config;
+  });
+
+  // Android: modify AndroidManifest.xml
+  config = withAndroidManifest(config, (config) => {
+    const mainApp =
+      AndroidConfig.Manifest.getMainApplicationOrThrow(config.modResults);
+    AndroidConfig.Manifest.addMetaDataItemToMainApplication(
+      mainApp,
+      "MY_API_KEY",
+      apiKey
+    );
+    return config;
+  });
+
+  return config;
+};
+
+export default withMyConfig;
+```
+
+## Using in app.json
+
+```json
+{
+  "expo": {
+    "plugins": [["my-module", { "apiKey": "secret_key" }]]
+  }
+}
+```
+
+## Reading Config Values in Native Code
+
+**Swift:**
+
+```swift
+Function("getApiKey") {
+  return Bundle.main.object(forInfoDictionaryKey: "MY_API_KEY") as? String
+}
+```
+
+**Kotlin:**
+
+```kotlin
+Function("getApiKey") {
+  val appInfo = appContext?.reactContext?.packageManager?.getApplicationInfo(
+    appContext?.reactContext?.packageName.toString(),
+    PackageManager.GET_META_DATA
+  )
+  return@Function appInfo?.metaData?.getString("MY_API_KEY")
+}
+```
+
+## Key Rules
+
+- Plugins must be synchronous; return values must be serializable (except `mods`)
+- `Mods` are async functions invoked during the prebuild "syncing" phase
+- Use `npm run build plugin` to compile TypeScript plugins
+- Test with `npx expo prebuild --clean`