opencode-skills-collection 3.1.12 → 3.1.13

package/bundled-skills/expo-module/references/native-module.md

@@ -0,0 +1,286 @@
+# Native Module DSL Reference
+
+Swift is shown as the primary language. Kotlin follows the same DSL structure (see SKILL.md for both). Kotlin-specific syntax is noted where it meaningfully differs.
+
+## Name
+
+Sets the module identifier used in JavaScript.
+
+```swift
+Name("MyModule")
+```
+
+## Constant
+
+Computed once on first access, then cached.
+
+```swift
+Constant("PI") { 3.14159 }
+```
+
+## Function (Synchronous)
+
+Blocks the JS thread until completion. Supports up to 8 arguments.
+
+```swift
+Function("add") { (a: Int, b: Int) -> Int in
+  return a + b
+}
+```
+
+## AsyncFunction
+
+Returns a Promise. Runs on a background thread by default.
+
+```swift
+AsyncFunction("fetchData") { (url: URL) -> String in
+  let data = try Data(contentsOf: url)
+  return String(data: data, encoding: .utf8) ?? ""
+}
+
+// Force main queue execution
+AsyncFunction("updateUI") { () -> Void in
+  // UI work
+}.runOnQueue(.main)
+```
+
+**Kotlin differences:**
+
+```kotlin
+// Supports Kotlin coroutines
+AsyncFunction("fetchData") Coroutine { url: java.net.URL ->
+  withContext(Dispatchers.IO) {
+    url.readText()
+  }
+}
+```
+
+## Property
+
+Getter/setter for JS object properties.
+
+```swift
+// Read-only
+Property("version") { "1.0.0" }
+
+// Read-write
+Property("volume")
+  .get { () -> Float in self.volume }
+  .set { (newValue: Float) in self.volume = newValue }
+```
+
+## Events
+
+Declares events the module can send to JS. Must be declared before using `sendEvent`.
+
+```swift
+// Declaration
+Events("onChange", "onError")
+
+// Sending from native (Swift)
+sendEvent("onChange", ["value": newValue])
+```
+
+**Kotlin difference** — uses `bundleOf`:
+
+```kotlin
+sendEvent("onChange", bundleOf("value" to newValue))
+```
+
+**JS subscription:**
+
+```typescript
+import { useEvent } from "expo";
+import MyModule from "./MyModule";
+
+// Hook-based (recommended)
+const event = useEvent(MyModule, "onChange");
+
+// Manual subscription
+const subscription = MyModule.addListener("onChange", (event) => {
+  console.log(event.value);
+});
+// Clean up: subscription.remove()
+```
+
+### OnStartObserving / OnStopObserving
+
+Called when the first listener attaches / last listener detaches. Can be scoped to specific events.
+
+```swift
+OnStartObserving("onChange") {
+  // Start producing events
+}
+
+OnStopObserving("onChange") {
+  // Stop producing events
+}
+```
+
+---
+
+## Type System
+
+### Primitives
+
+| Swift | Kotlin | JS |
+|-------|--------|----|
+| `Bool` | `Boolean` | `boolean` |
+| `Int`, `Int32` | `Int` | `number` |
+| `Int64` | `Long` | `number` |
+| `Float`, `Float32` | `Float` | `number` |
+| `Double` | `Double` | `number` |
+| `String` | `String` | `string` |
+| `URL` | `java.net.URL` / `android.net.Uri` | `string` |
+| `CGPoint` | - | `{ x, y }` |
+| `CGSize` | - | `{ width, height }` |
+| `CGRect` | - | `{ x, y, width, height }` |
+| `UIColor` / `CGColor` | `android.graphics.Color` | `string` (ProcessedColorValue) |
+| `Data` | `kotlin.ByteArray` | `Uint8Array` |
+
+### Records (Struct-like types)
+
+```swift
+struct UserRecord: Record {
+  @Field var name: String = ""
+  @Field var age: Int = 0
+  @Field var email: String?
+}
+
+Function("createUser") { (user: UserRecord) -> Bool in
+  return true
+}
+```
+
+**Kotlin difference** — uses `class` instead of `struct`, optional fields need explicit `= null`:
+
+```kotlin
+class UserRecord : Record {
+  @Field var name: String = ""
+  @Field var age: Int = 0
+  @Field var email: String? = null
+}
+```
+
+### Enums (Enumerable)
+
+```swift
+enum Theme: String, Enumerable {
+  case light
+  case dark
+  case system
+}
+
+Function("setTheme") { (theme: Theme) in
+  // type-safe enum value
+}
+```
+
+**Kotlin difference** — uses `enum class` with explicit `value` property:
+
+```kotlin
+enum class Theme(val value: String) : Enumerable {
+  LIGHT("light"),
+  DARK("dark"),
+  SYSTEM("system")
+}
+```
+
+### Either Types (Union types)
+
+```swift
+Function("process") { (input: Either<String, Int>) in
+  if let str = input.get(String.self) {
+    // handle string
+  } else if let num = input.get(Int.self) {
+    // handle number
+  }
+}
+```
+
+Also available: `EitherOfThree<A, B, C>`, `EitherOfFour<A, B, C, D>`.
+
+### JavaScript Values (Direct JS manipulation)
+
+For advanced use in synchronous functions running on JS thread:
+
+```swift
+Function("callback") { (fn: JavaScriptFunction<String>) in
+  let result = fn("arg1", "arg2")
+}
+```
+
+---
+
+## Shared Objects
+
+Bridge native class instances to JS with automatic lifecycle management. Instances are deallocated when neither JS nor native code holds a reference.
+
+### Defining a Shared Object
+
+```swift
+class ImageContext: SharedObject {
+  private var image: UIImage
+
+  init(image: UIImage) {
+    self.image = image
+    super.init()
+  }
+
+  func rotate(degrees: Double) {
+    image = image.rotated(degrees: degrees)
+  }
+}
+```
+
+**Kotlin difference** — takes `RuntimeContext` in constructor, override `sharedObjectDidRelease()` for cleanup:
+
+```kotlin
+class ImageContext(
+  runtimeContext: RuntimeContext,
+  private var bitmap: Bitmap
+) : SharedObject(runtimeContext) {
+
+  fun rotate(degrees: Float) { /* ... */ }
+
+  override fun sharedObjectDidRelease() {
+    if (!bitmap.isRecycled) bitmap.recycle()
+  }
+}
+```
+
+### Exposing via Class DSL
+
+```swift
+Class("Context", ImageContext.self) {
+  Constructor { (path: String) -> ImageContext in
+    return ImageContext(image: UIImage(contentsOfFile: path)!)
+  }
+
+  Function("rotate") { (ctx: ImageContext, degrees: Double) -> ImageContext in
+    ctx.rotate(degrees: degrees)
+    return ctx
+  }
+
+  Property("width")
+    .get { (ctx: ImageContext) -> Int in ctx.width }
+}
+```
+
+Other Class DSL components: `StaticFunction`, `StaticAsyncFunction`, `AsyncFunction`.
+
+### SharedRef
+
+Specialized shared reference for passing typed objects between modules:
+
+```swift
+final class ImageRef: SharedRef<UIImage> {}
+```
+
+### JS Usage
+
+```typescript
+const ctx = await ImageModule.create("/path/to/image.png");
+ctx.rotate(90);
+console.log(ctx.width);
+```

package/bundled-skills/expo-module/references/native-view.md

@@ -0,0 +1,171 @@
+# Native View Reference
+
+Native views let you render platform UI components (UIView on iOS, Android View on Android) as React components.
+
+## Defining a View
+
+**Swift:**
+
+```swift
+public class MyViewModule: Module {
+  public func definition() -> ModuleDefinition {
+    Name("MyView")
+
+    View(MyNativeView.self) {
+      Prop("title") { (view: MyNativeView, title: String) in
+        view.titleLabel.text = title
+      }
+
+      Events("onPress", "onLoad")
+
+      AsyncFunction("reset") { (view: MyNativeView) in
+        view.reset()
+      }
+    }
+  }
+}
+
+class MyNativeView: ExpoView {
+  let titleLabel = UILabel()
+
+  required init(appContext: AppContext) {
+    super.init(appContext: appContext)
+    clipsToBounds = true
+    addSubview(titleLabel)
+  }
+
+  override func layoutSubviews() {
+    super.layoutSubviews()
+    titleLabel.frame = bounds
+  }
+}
+```
+
+**Kotlin:**
+
+```kotlin
+class MyViewModule : Module() {
+  override fun definition() = ModuleDefinition {
+    Name("MyView")
+
+    View(MyNativeView::class) {
+      Prop("title") { view: MyNativeView, title: String ->
+        view.titleView.text = title
+      }
+
+      Events("onPress", "onLoad")
+
+      AsyncFunction("reset") { view: MyNativeView ->
+        view.reset()
+      }
+    }
+  }
+}
+
+class MyNativeView(context: Context, appContext: AppContext) : ExpoView(context, appContext) {
+  val titleView = TextView(context).also {
+    addView(it, LayoutParams(LayoutParams.MATCH_PARENT, LayoutParams.MATCH_PARENT))
+  }
+}
+```
+
+**TypeScript:**
+
+```typescript
+import { requireNativeView } from "expo";
+
+export type MyViewProps = {
+  title?: string;
+  onPress?: (event: { nativeEvent: { x: number; y: number } }) => void;
+  onLoad?: () => void;
+} & ViewProps;
+
+const NativeView = requireNativeView<MyViewProps>("MyView");
+
+export function MyView(props: MyViewProps) {
+  return <NativeView {...props} />;
+}
+```
+
+## View Event Dispatching
+
+**Swift:**
+
+```swift
+class MyNativeView: ExpoView {
+  let onPress = EventDispatcher()
+
+  func handleTap(at point: CGPoint) {
+    onPress(["x": point.x, "y": point.y])
+  }
+}
+```
+
+**Kotlin:**
+
+```kotlin
+class MyNativeView(context: Context, appContext: AppContext) : ExpoView(context, appContext) {
+  private val onPress by EventDispatcher()
+
+  fun handleTap(x: Float, y: Float) {
+    onPress(mapOf("x" to x, "y" to y))
+  }
+}
+```
+
+## View Lifecycle
+
+```swift
+// Called after all props have been set
+OnViewDidUpdateProps { (view: MyNativeView) in
+  view.applyChanges()
+}
+```
+
+```kotlin
+// Android only - called when view is no longer used
+OnViewDestroys { view: MyNativeView ->
+  view.cleanup()
+}
+```
+
+## AsyncFunction on Views
+
+Functions defined inside `View` are accessible via React ref:
+
+```typescript
+const ref = useRef<MyView>(null);
+// Call native function
+await ref.current?.reset();
+```
+
+## PropGroup (Android)
+
+Batch-register multiple props with shared setter logic:
+
+```kotlin
+View(MyNativeView::class) {
+  PropGroup("border", "width" to Float::class, "color" to Int::class) { view, index, value ->
+    when (index) {
+      0 -> view.borderWidth = value as Float
+      1 -> view.borderColor = value as Int
+    }
+  }
+}
+```
+
+## GroupView (Android)
+
+Enable view group functionality for managing child views:
+
+```kotlin
+View(MyContainerView::class) {
+  GroupView {
+    AddChildView { parent, child, index -> parent.addView(child, index) }
+    GetChildCount { parent -> parent.childCount }
+    GetChildViewAt { parent, index -> parent.getChildAt(index) }
+    RemoveChildView { parent, child -> parent.removeView(child) }
+    RemoveChildViewAt { parent, index -> parent.removeViewAt(index) }
+  }
+}
+```

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

@@ -0,0 +1,44 @@
+---
+name: expo-observe
+description: Use for anything related to EAS Observe — adding `expo-observe` to an Expo project (AppMetricsRoot/ObserveRoot HOC, markInteractive, the useObserve hook, and the Expo Router / React Navigation integrations for per-route metrics), querying via the EAS CLI (`eas observe:metrics-summary`,...
+risk: unknown
+source: https://github.com/expo/skills/tree/main/plugins/expo/skills/expo-observe
+source_repo: expo/skills
+source_type: official
+date_added: 2026-07-01
+license: MIT
+license_source: https://github.com/expo/skills/blob/main/LICENSE
+---
+
+# EAS Observe
+## When to Use
+
+Use this skill when you need use for anything related to EAS Observe — adding `expo-observe` to an Expo project (AppMetricsRoot/ObserveRoot HOC, markInteractive, the useObserve hook, and the Expo Router / React Navigation integrations for per-route metrics), querying via the EAS CLI (`eas observe:metrics-summary`,...
+
+
+EAS Observe tracks startup, navigation, and custom-event performance from production Expo apps.
+
+> **Source of truth:** https://docs.expo.dev/eas/observe/ — always consult the canonical docs when API details matter, especially get-started, configuration, integrations, and the metrics reference. EAS Observe is evolving; this skill's references are written to stay accurate but may lag the docs.
+
+## Which reference to read
+
+The three reference files in `./references/` cover the three things people typically need this skill for:
+
+- **Adding EAS Observe to a project** → [`./references/setup.md`](./references/setup.md). Install, wrap the root layout (`AppMetricsRoot` on SDK 55, `ObserveRoot` on SDK 56+), call `markInteractive()` (global on SDK 55, via the `useObserve()` hook on SDK 56+), and optional per-route navigation metrics through the Expo Router / React Navigation integrations.
+- **Querying metrics from the terminal** → [`./references/queries.md`](./references/queries.md). The five `eas observe:*` commands — `metrics-summary`, `metrics`, `routes`, `events`, `versions` — with flags, table layouts, JSON shapes, and common workflows.
+- **Reading a dashboard or CLI output** → [`./references/metrics.md`](./references/metrics.md). Target thresholds per metric, what the TTI `frameRate.*` params mean, and diagnostic patterns for telling slow-but-smooth startup apart from main-thread contention or hard blocks.
+
+## Quick links to the docs
+
+- Get started: https://docs.expo.dev/eas/observe/get-started/
+- Dashboard guide: https://docs.expo.dev/eas/observe/dashboard/
+- Metrics reference: https://docs.expo.dev/eas/observe/reference/metrics/
+- Expo Router integration: https://docs.expo.dev/eas/observe/integrations/expo-router/
+- React Navigation integration: https://docs.expo.dev/eas/observe/integrations/react-navigation/
+- Configuration: https://docs.expo.dev/eas/observe/configuration/
+
+## Limitations
+
+- Use this skill only when the task clearly matches its upstream product or API scope.
+- Verify commands, API behavior, pricing, quotas, credentials, and deployment effects against current official documentation before making changes.
+- Do not treat generated examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.

package/bundled-skills/expo-observe/references/metrics.md

@@ -0,0 +1,47 @@
+# EAS Observe metrics — interpretation cheatsheet
+
+Quick reference for reading EAS Observe dashboards and CLI output.
+
+> Source: https://docs.expo.dev/eas/observe/reference/metrics/ — this is the canonical reference for metrics. Consult this page for the latest guidance, full prose definitions, optimization tips, and rationale.
+
+All durations are in seconds. Data is retained for 90 days. All durations are in seconds. By default, every installation dispatches all of its events. Apps with high volumes can opt into per-installation sampling via configure({ sampleRate }). See [Sampling](https://docs.expo.dev/eas/observe/configuration/#sampling).
+
+## Target thresholds
+
+| Metric | Full name | Target | Auto-collected? |
+|---|---|---|---|
+| Cold launch | `expo.app_startup.cold_launch_time` | **< 1.5s** | Yes (native-only — JS code does not affect it) |
+| Warm launch | `expo.app_startup.warm_launch_time` | **< 0.5s** | Yes (OS decides when warm vs cold happens) |
+| Bundle load | `expo.app_startup.bundle_load_time` | **< 0.3s** | Yes (JS load + evaluation, before `runApplication`) |
+| Time to first render (TTR) | `expo.app_startup.ttr` | **< 2s** incl. cold launch | Yes when root is wrapped with `AppMetricsRoot` (SDK 55) / `ObserveRoot` (SDK 56+) |
+| Time to interactive (TTI) | `expo.app_startup.tti` | **< 3s** incl. cold launch | **No** — call `markInteractive()` once the screen is genuinely usable |
+
+Both TTR and TTI are measured *from native launch* through the React render, so the cold-launch portion counts against them.
+
+## Interpreting TTI events (frameRate params)
+
+Every TTI event carries three frame-rate params. The pattern of high/low values across them tells you *what kind* of slowness you're seeing.
+
+| Param | Definition | What it indicates |
+|---|---|---|
+| `expo.frameRate.slowFrames` | Count of frames ≥ 17ms | Main thread consistently busy during launch (heavy layout, sync bridge calls, too many components rendering) |
+| `expo.frameRate.frozenFrames` | Count of frames ≥ 700ms | Hard freezes. Even one during startup is a serious issue (sync I/O, large JSON parsing, blocking network) |
+| `expo.frameRate.totalDelay` | Total accumulated time (seconds) frames exceeded their target duration | Best single "smoothness" number — compare to TTI |
+
+**Diagnostic patterns:**
+
+- **High TTI + low totalDelay** → slow but smooth. The launch sequence itself is long. Optimize bundle size, data-fetch waterfalls, initialization chains.
+- **High TTI + high totalDelay + many slowFrames** → main-thread contention. Offload work, simplify the initial render tree.
+- **High TTI + high totalDelay + any frozenFrames** → something is blocking hard. Look for synchronous I/O, large JSON parsing, or blocking network calls.
+
+## Dispatch caveats
+
+- **Debug builds** (native debug OR JS bundle with `__DEV__` = true) do **not** dispatch metrics unless `configure({ dispatchInDebug: true })` is set.
+- The `environment` tag (defaults to `process.env.NODE_ENV`) is metadata only — it does not gate dispatch by itself.
+- Offline events are buffered on-device and flushed when the app backgrounds or `Observe.dispatchEvents()` is called.
+
+## Cross-references
+
+- Full metric definitions and optimization guidance: https://docs.expo.dev/eas/observe/reference/metrics/
+- Setup steps (`AppMetricsRoot` / `ObserveRoot`, `markInteractive`): see [`./setup.md`](./setup.md).
+- Querying metrics via the EAS CLI: see [`./queries.md`](./queries.md).