# Mobile Surfaces

> The fastest way to ship Live Activities, Dynamic Island, widgets, and controls on iPhone. An Expo iOS reference architecture with a working harness, push SDK, contract types, and a 41-entry catalog of silent-failure traps. Requires iOS 17.2 or higher.

## Install

`npm create mobile-surfaces` (also works with pnpm, yarn, bun)

## Repository

https://github.com/glendonC/mobile-surfaces

## Full content

The full trap catalog is mirrored at [/llms-full.txt](https://mobile-surfaces.com/llms-full.txt) so you can fetch the entire reference without following GitHub links.

## Catalog

The trap catalog is 41 live rules (33 error, 2 warning, 6 info); 24 are enforced at PR time by `pnpm surface:check`. Treat every `error` rule as a hard invariant. The rendered per-rule catalog with symptom, fix, and enforcement script is at [/traps](https://mobile-surfaces.com/traps).

## Documentation

- [Quickstart](https://mobile-surfaces.com/docs/quickstart): Zero to a Live Activity on your Lock Screen in 30 minutes.
- [Adopt Mobile Surfaces](https://mobile-surfaces.com/docs/adopt): For teams already shipping iOS Live Activities. Add the contract and push client without forking your bridge.
- [Scenarios](https://mobile-surfaces.com/docs/scenarios): Canonical multi-step flows that exercise the ambient surface kinds from one shared shape.
- [Concepts](https://mobile-surfaces.com/docs/concepts): Contract-first model, native stack, adapter boundary, validation rules.
- [Surfaces](https://mobile-surfaces.com/docs/surfaces): Every kind value, what ships today, when to emit each, and the native target it drives.
- [Backend](https://mobile-surfaces.com/docs/backend): Domain event to snapshot to APNs walkthrough.
- [Push](https://mobile-surfaces.com/docs/push): Wire-layer reference, SDK, smoke script, token taxonomy, error reasons, channel push.
- [Observability](https://mobile-surfaces.com/docs/observability): Which catalog-bound errors are worth alerting on, hook signatures, recommended log shape.
- [iOS Environment](https://mobile-surfaces.com/docs/ios-environment): Dev builds, App Groups, generated native folders, simulator/device loops.
- [Building your app on Mobile Surfaces](https://mobile-surfaces.com/docs/building-your-app): How to move from the surface harness to a production app that emits real snapshots.
- [Compatibility](https://mobile-surfaces.com/docs/compatibility): Pinned Expo SDK, React Native, iOS, Xcode, and @bacons/apple-targets row.
- [Versioning Charter](https://mobile-surfaces.com/docs/stability): Linked release group, independent packages, deprecation timeline, schemaVersion policy.
- [Schema](https://mobile-surfaces.com/docs/schema): The current wire shape, snapshot validation, deprecation timeline, JSON Schema $id, future evolution policy.
- [Troubleshooting](https://mobile-surfaces.com/docs/troubleshooting): Symptom-to-fix recipes for silent iOS failures.
- [Mobile Surfaces and expo-live-activity](https://mobile-surfaces.com/docs/vs-expo-live-activity): Cooperative positioning: what each project owns, when to use both, and the decision matrix.

## Tech stack

- Expo SDK with Continuous Native Generation
- React Native
- TypeScript
- Zod (contract validation)
- @bacons/apple-targets (widget target management; pin exact version)
- iOS 17.2 or higher (push-to-start tokens require this floor)