react-native-photo-video-editor 0.1.0

package/docs/roadmap.md

@@ -0,0 +1,12 @@
+# Roadmap
+
+1. Foundation and native contract. **Complete**
+2. Full-screen native presentation, navigation, and theming. **Complete and Gradle-built for Android (`assembleDebug` passes offline); iOS implemented, not locally built (no macOS/Xcode in this environment)**
+3. Single-photo crop, rotate, flip, straighten, adjustments (brightness/contrast/saturation/exposure/gamma/temperature/tint/highlights/shadows/sharpen/blur/pixelate/mirror), original preset filters, and JPEG/PNG/WebP export. **Complete and Gradle-built for Android (`assembleDebug` passes offline); iOS implemented with matching architecture and formulas, not locally built (no macOS/Xcode in this environment).**
+4. Photo layers: text, stickers, shapes, freehand drawing, selection/transform/duplicate/lock/hide/reorder/delete, and undo/redo. **Complete and Gradle-built for Android (`assembleDebug` passes offline); iOS implemented with matching architecture, not locally built.** Font-file registration (`EditorOptions.fonts`) is accepted but not yet wired to load custom font files — text layers only resolve system font names today. See `docs/photo-editor.md` for the full gap list.
+5. Single-video preview, trim, mute, cover-frame selection, rotate/flip, and H.264/AAC MP4 export. **Complete and Gradle-built for Android against Media3 1.4.1 (resolved live — this environment has network access); iOS implemented via AVFoundation (`AVMutableComposition`/`AVAssetExportSession`), not locally built.** Aspect-ratio crop is Android-only — scoped out on iOS as unverifiable transform math without a device. See `docs/video-editor.md` for the full gap list.
+6. Video overlays, speed, filters, and adjustments; cancellation, background behavior, drafts, and recovery. **Complete on Android; one iOS gap remaining.** Playback speed (0.5x/1x/1.5x/2x) is implemented for preview on both platforms (export does not yet honor it — documented scope cut, Media3 1.4.1 lacks the needed `SpeedProvider` API). Timed text/sticker/shape overlays are implemented with full selection/transform (Scale/Rotate/Opacity)/time-range editing (Start/End) and undo/redo, reusing the same `LayerOverlayView` built for photo layers, Gradle-built for Android including the Media3 `OverlayEffect` export path (genuinely time-aware, respecting each overlay's range); iOS implements the same editing UI via `AVVideoCompositionCoreAnimationTool` but its export still burns in overlays for the whole clip regardless of range — a custom `AVVideoCompositing` implementation would be needed to fix that, not locally built either way. Video-level Brightness/Contrast/Saturation filters are implemented and Gradle-built for Android (export-only, verified against actual Media3 bytecode); iOS scoped out for the same `AVVideoCompositing` reason. See `docs/video-editor.md` for the full gap list.
+7. Multi-clip timeline, audio, transitions, and advanced GPU effects. **Multi-clip timeline complete on both platforms (audio tracks and transitions deferred — see below).** A `VideoClip` list (id/source/trim) replaces the single implicit video; a clip strip UI supports Split (at the playhead)/Duplicate/Delete/Move-Left/Move-Right, and the trim range view rebinds to whichever clip is selected. Android is Gradle-built: ExoPlayer now plays a multi-item playlist (`player.setMediaItems`) with a `VideoEditSession.globalPositionMs()`/`seekToGlobalMs()` pair bridging the composed timeline and the player's own per-item position; export concatenates every clip into one `EditedMediaItemSequence`/`Composition`, verified against the actual Media3 1.4.1 bytecode (`javap`) before writing the code — `EditedMediaItemSequence(List<EditedMediaItem>)`, `Composition.Builder(EditedMediaItemSequence, ...)`, and `Transformer.start(Composition, String)` all confirmed to exist. iOS takes a simpler, architecture-appropriate path: both preview and export concatenate every clip's trimmed range into one `AVMutableComposition` via `insertTimeRange(_:of:at:)` (which supports multi-segment concatenation natively), so `player.currentTime()`/`.seek(to:)` already are the composed-timeline position with no separate global-position bookkeeping needed — not locally built (no macOS/Xcode here). Every clip in this pass shares one source file (created via Split/Duplicate); importing separate additional source files from a system picker, audio tracks, and transitions remain deferred to a follow-up slice of this milestone, per the master spec's own guidance to stabilize gapless multi-clip export first.
+8. Compatibility matrix, benchmarks, and stable 1.0 API.
+
+Milestones exclude multi-clip timelines, speculative GPU/FFmpeg dependencies, background exporting, and broad storage permissions until Milestone 7.

package/docs/technology-decisions.md

@@ -0,0 +1,17 @@
+# Technology decisions
+
+The SDK remains an original implementation and does not install or wrap a commercial editor. Android uses Canvas/Bitmap/ColorMatrix for photo work (Milestones 2–4). iOS uses UIKit, Core Graphics, and hand-implemented per-pixel formulas for the same (chosen deliberately over Core Image so both platforms compute identical math and stay visually close, and so the exact filters applied are auditable rather than opaque built-in kernels).
+
+## Video (Milestone 5)
+
+| Concern | Android | iOS |
+| --- | --- | --- |
+| Preview playback | Media3 `ExoPlayer` + `PlayerView` | `AVPlayer` + `AVPlayerViewController` |
+| Thumbnail strip | `MediaMetadataRetriever` (background thread) | `AVAssetImageGenerator` (background queue) |
+| Trim/mute/rotate/flip export | Media3 `Transformer` + `EditedMediaItem` + `Effects` | `AVMutableComposition` + `AVMutableVideoComposition` + `AVAssetExportSession` |
+| Aspect-ratio crop | `Presentation.createForAspectRatio` | **Not implemented** — see `docs/video-editor.md` |
+| Output codec | H.264 video / AAC audio, MP4 | H.264 video / AAC audio, MP4 (`AVAssetExportPresetHighestQuality`) |
+
+**Why Media3 over FFmpeg or a custom `MediaCodec` pipeline**: Media3 is Apache-2.0, actively maintained by Google, targets Android 7+ (well under this package's `minSdk 24`), and its `Transformer` API is purpose-built for exactly this job (trim, effects, re-encode) without hand-rolling codec plumbing. It resolves live from Google's Maven (`androidx.media3:*:1.4.1`) — this development environment has network access, so this was verified by an actual successful Gradle dependency resolution and compile, not assumed. FFmpeg remains excluded: no LGPL/GPL binary-size or store-compliance review has been done, and Media3 covers Milestone 5's requirements without it.
+
+**Why AVFoundation over a custom `AVAssetWriter` pipeline on iOS**: `AVAssetExportSession` is the standard, stable, high-level API for exactly this class of edit (trim + composition + re-encode) and needs far less state-machine code than driving `AVAssetReader`/`AVAssetWriter` directly — lower risk to get right without a device to test on. The tradeoff is less control (e.g., no live progress `Timer`-free callback, hence the 0.3s polling loop, and no straightforward path to combining crop with rotation that was verifiable without a device — see the aspect-ratio gap above).

package/docs/video-editor.md

@@ -0,0 +1,76 @@
+# Video editor
+
+## Milestone 5 — single-video preview, trim, mute, cover frame, and export
+
+- **Playback** — a custom player (Media3 `ExoPlayer`/`PlayerView` on Android, `AVPlayer`/`AVPlayerViewController` on iOS) with Play/Pause, a scrubber, and a current-time/duration label, polled every ~250ms (no push-based position API on either platform).
+- **Trim** — a dual-handle range bar below the player, backed by a 12-thumbnail strip generated off the main thread (`MediaMetadataRetriever` / `AVAssetImageGenerator`). Dragging a handle updates the trim range live; a minimum-length gap between handles is enforced.
+- **Mute** — toggles live preview volume and excludes the audio track at export.
+- **Cover frame** — tap **Cover** while scrubbed to the desired frame to record it as `coverFrameMs`. The frame itself is not yet extracted to an image file — the timestamp is tracked but not returned on `EditorResult` yet (a small follow-up).
+- **Rotate** — cycles 90° increments, applied at export via a rotation transform; the preview shows a live `rotation`/`transform` approximation on the player view rather than a full re-render.
+- **Flip** — horizontal flip, same live-approximation preview treatment as rotate.
+- **Aspect-ratio crop** (Original/1:1/4:5/9:16/16:9) — **Android only.** On iOS this is scoped out for now: combining a crop with the source's own orientation-correcting transform and an additional rotation inside `AVMutableVideoCompositionLayerInstruction`'s coordinate space is easy to get subtly wrong, and there is no device available in this environment to verify the pixel math, so it was not shipped unverified. Selecting a preset on iOS shows a toast noting the gap rather than silently doing nothing.
+- **Export** — H.264 video / AAC audio MP4, via Media3 `Transformer` (Android) or `AVAssetExportSession` with `AVMutableComposition`/`AVMutableVideoComposition` (iOS). Progress is polled (~300ms) and shown as an indeterminate spinner with a **Cancel export** button; cancellation deletes the partial output file. `EditorResult` returns real `width`/`height`/`duration`/`fileSize`/`mimeType`.
+
+## Milestone 6 — playback speed, timed overlays, and overlay editing
+
+- **Speed** — cycles 0.5x → 1x → 1.5x → 2x → 0.5x…, applied live to the preview player (`ExoPlayer.setPlaybackSpeed` / `AVPlayer.rate`) and shown on the toolbar button itself (e.g. "Speed 1.5x") rather than a highlight, since it's a cycling value, not an on/off mode.
+- **Export does not yet honor speed** — this is a deliberate, documented scope cut, not an oversight. Changing output speed correctly (video timestamp remapping + audio pitch-preserving time-stretch) is a meaningfully different problem from trim/mute/rotate/flip, with real risk of getting the Media3 `SpeedProvider`/`TimestampAdjustment` or AVFoundation `scaleTimeRange` math wrong without a device to verify against. Exporting after setting a non-1x speed currently produces a normal-speed file — the UI does not yet warn about this mismatch (a follow-up).
+- **Text/Sticker/Shape overlays** — tap **Text** or **Stickers** on the video toolbar (the sticker picker also offers Rectangle/Oval/Line shapes) to add an overlay, reusing the exact same `PhotoLayer`/`PhotoLayerStack`/`PhotoLayerRenderer` machinery built for photo layers (Milestone 4) rather than a parallel system. `PhotoLayer` gained `startMs`/`endMs` fields for time-ranging, with an `isActiveAt`/`isActive(atMs:)` helper.
+  - Preview: active overlays (those whose time range contains the current playhead) are rendered onto a transparent image placed over the player, refreshed on the same ~250ms position-poll tick already used for the scrubber.
+  - Export: burned in via Media3 `OverlayEffect`/`BitmapOverlay` (Android) or `AVVideoCompositionCoreAnimationTool` (iOS).
+  - Header Undo/Redo now works for video overlays too, same 50-entry snapshot history as photo layers.
+- **Overlay selection, transform, and time-range editing** — tap an overlay on the video preview to select it (reuses the same `LayerOverlayView` built for photo layers: dashed bounding box, tap-to-select, drag-to-move). Once selected, a mini toolbar offers Scale/Rotate/Opacity (shared slider, same pattern as photo) plus **Start**/**End** chips that scrub the overlay's time range against the video's duration, and Delete.
+  - Android export now genuinely respects per-overlay time ranges: `BitmapOverlay.getBitmap(presentationTimeUs:)` recomputes the active layer set per callback (cached by an active-layer-ID signature so it only re-renders when that set actually changes, not on every frame). **One unverified detail**: this assumes Transformer's effect callbacks receive presentation timestamps rebased to the trimmed output's own zero point, so `trimStartMs` is added back before comparing against `startMs`/`endMs` (which are authored against the untrimmed source's timeline) — there's no device here to confirm this assumption.
+  - **iOS export does not yet respect time ranges** — every overlay is still burned in for the whole clip regardless of its configured range, even though the editor UI lets you set one. `AVVideoCompositionCoreAnimationTool` only composites a fixed `CALayer` tree; making it time-varying like Android's per-frame callback needs a custom `AVVideoCompositing` implementation, a distinctly bigger change than anything else in this pass. This is the one remaining gap in Milestone 6.
+- **Video-level filters** (Brightness/Contrast/Saturation) — **Android only, export-only (no live preview)**. Verified against the actual Media3 1.4.1 bytecode (via `javap`, not guessed) before writing any code: `androidx.media3.effect.Brightness(Float)`, `Contrast(Float)`, and `HslAdjustment.Builder().adjustSaturation(Float)` all exist and implement `Effect` in this exact version. iOS is scoped out: applying per-frame color filters requires `AVMutableVideoComposition(asset:applyingCIFiltersWithHandler:)`, which creates its own composition and conflicts architecturally with the manual `AVVideoCompositionLayerInstruction`-based composition already used here for rotate/flip/crop — combining them needs the same custom `AVVideoCompositing` implementation noted above. Tapping Filters on iOS video shows a "coming in a later milestone" message.
+- A real API-version lesson from this pass: an attempt to also apply `speed` at export via `SpeedProvider`/`TimestampAdjustment(SpeedProvider)` found that API doesn't exist in Media3 1.4.1. Bumping the dependency to 1.9.4 to get it broke three other already-verified call sites (`Transformer.Builder.setTransformationRequest`, `OverlayEffect`'s constructor list type, and `SpeedProvider` still wasn't found even there). The version bump was reverted rather than chased further mid-session — `speed` stays preview-only, documented above, and 1.4.1 remains pinned since everything else against it is verified working.
+
+**Still stubs**: Filters on video (iOS only — Android has it, see above).
+
+### Known gaps
+
+- iOS aspect-ratio crop is not implemented (see above) — Android has it.
+- iOS video-level filters (Brightness/Contrast/Saturation) are not implemented (see above) — Android has it, export-only.
+- **iOS video overlay export does not respect per-overlay time ranges** (see above) — the editor UI supports setting them on both platforms, but only Android's export honors them. This is the one remaining Milestone 6 gap.
+- Cover-frame image extraction (saving the selected frame as a JPEG and returning its URI) is not implemented yet; only the timestamp is tracked internally.
+- Playback speed is preview-only on both platforms; export ignores it (see above for why).
+- Export progress is a spinner, not wired to the JS `addExportProgressListener` event bridge yet — consistent with how photo export currently works, but a real gap for a later milestone.
+- No variable-frame-rate handling beyond what each platform's default export pipeline does automatically.
+- `cancelExport()` (the public JS API) is still a no-op stub — cancellation only works via the in-editor Cancel button while the exporter is running inside the native UI.
+
+**Verification status**: Android is compiled and built via Gradle (`:react-native-photo-video-editor:assembleDebug`, `:app:assembleDebug`) against Media3 1.4.1, resolved live from Google's Maven (this environment has network access, unlike the fully-offline assumption of earlier milestones), including the `OverlayEffect`/`BitmapOverlay` overlay export path (now time-aware) and the `Brightness`/`Contrast`/`HslAdjustment` filter export path. It has not been exercised on an emulator/device with a real video file — in particular, the presentation-timestamp-rebasing assumption in the overlay time-range logic is unverified. iOS mirrors the overlay selection/transform/time-range UI (minus time-range-aware export, aspect crop, and video-level filters) using AVFoundation but is unverified — no macOS/Xcode toolchain is available here.
+
+## Milestone 7 (partial) — multi-clip timeline
+
+The single implicit video is replaced by an ordered `VideoClip` list (`id`, `sourceUri`, `originalDurationMs`, `trimStartMs`/`trimEndMs`). Every clip in this pass shares one source file — new clips only come from **Split** and **Duplicate**, not from importing separate additional source files (a follow-up). Audio tracks and transitions, the other two pieces the master spec bundles into Milestone 7, are **deliberately deferred** — per the spec's own guidance to add transitions only after gapless multi-clip export is stable.
+
+- **Clip strip** — a horizontal strip below the trim range view lists every clip as a chip (`Clip N` + trimmed duration); tapping one selects it, seeks the player to its start, and rebinds the trim range view to that clip's own `originalDurationMs` (previously the trim view was bound to the whole video).
+- **Split** — cuts the selected clip into two at the current playhead position, both sharing the original source file and together covering the exact same trimmed range as before the split.
+- **Duplicate** — inserts a copy of the selected clip immediately after itself (new `id`, same source/trim).
+- **Delete** — removes the selected clip; refuses to leave the timeline with zero clips.
+- **Move Left / Move Right** — reorders the selected clip by one position.
+- **Trim** — now edits whichever clip is selected (fractions relative to that clip's own `originalDurationMs`), not the whole video.
+
+### Android
+
+ExoPlayer plays a genuine multi-item playlist (`player.setMediaItems(List<MediaItem>)`, one `MediaItem` per clip with its own `ClippingConfiguration`). Because ExoPlayer's own `currentPosition`/`seekTo` are per-item, `VideoEditSession` adds `globalPositionMs()` (preceding clips' trimmed durations + position in the current item) and `seekToGlobalMs(Long)` (the inverse) so the rest of the UI — scrubber, time label, cover-frame, overlay-preview timing — can keep working against one composed timeline exactly as before. `coverFrameMs` and overlay `startMs`/`endMs` are now authored against this global timeline.
+
+Export concatenates every clip into a single `EditedMediaItemSequence` passed to `Composition`, replacing the old single-`EditedMediaItem` call. Verified against the actual Media3 1.4.1 bytecode (`javap` on the real `media3-transformer-1.4.1.aar`, not guessed) before writing the code:
+- `EditedMediaItemSequence(EditedMediaItem, EditedMediaItem...)` and `EditedMediaItemSequence(List<EditedMediaItem>)` both exist.
+- `Composition.Builder(EditedMediaItemSequence, EditedMediaItemSequence...)` and `Composition.Builder(List<EditedMediaItemSequence>)` both exist.
+- `Transformer.start(Composition, String)` exists alongside the previously-used `start(EditedMediaItem, String)`.
+
+Each clip becomes its own `EditedMediaItem` with the same global rotate/flip/aspect/filter effects; the per-overlay time-range `BitmapOverlay` callback now offsets its own item-local `presentationTimeUs` by the summed trimmed duration of the preceding clips to recover the global position that overlay `startMs`/`endMs` are authored against — the same unverified-without-a-device rebasing assumption carried over from Milestone 6, just generalized to per-clip offsets instead of one global `trimStartMs`.
+
+Gradle-built: `:react-native-photo-video-editor:compileDebugKotlin`, `:react-native-photo-video-editor:assembleDebug`, and `:app:assembleDebug` all pass. Not exercised on an emulator/device with a real multi-clip export.
+
+### iOS
+
+Takes an architecturally simpler path than Android: rather than a multi-item player, **both preview and export concatenate every clip's trimmed range into a single `AVMutableComposition`** via `insertTimeRange(_:of:at:)`, which supports multi-segment concatenation natively. This means `player.currentTime()`/`.seek(to:)` already **are** the composed-timeline position — there is no separate global-vs-per-item position to reconcile, unlike Android's playlist approach, so no `globalPositionMs()`/`seekToGlobalMs()` equivalent was needed. This is a deliberate, documented platform difference, not an inconsistency. `VideoEditSession.asset(for:)` resolves any one clip's own `AVURLAsset` (used for natural-size lookups and per-clip thumbnail generation). Not locally built — no macOS/Xcode toolchain here.
+
+### Known gaps (this slice)
+
+- All clips share one source file — no system file picker to import additional separate videos yet.
+- Audio tracks (adding/mixing separate audio) — deferred, not started.
+- Transitions between clips — deferred, not started; the master spec recommends only adding these once gapless export is stable, which this slice establishes.
+- Android's per-clip overlay-offset rebasing and iOS's whole-timeline composition are both unverified on-device, same caveat as every other Transformer/AVFoundation timing assumption in this project so far.

package/ios/Editor/DesignTokens.swift

@@ -0,0 +1,75 @@
+import UIKit
+
+/// Default values for the "Studio Violet" design system used by the native editor
+/// shell, matching the Stitch-exported mockups under
+/// stitch_react_native_photo_editor_sdk/studio_violet_creative_sdk/DESIGN.md.
+/// Mirrors `DesignTokens.kt`. These are FALLBACKS only — every color a consumer
+/// can already override via `EditorOptions.theme` still wins; this object just
+/// changes what the editor looks like when no override is given.
+enum DesignTokens {
+  // Surface hierarchy
+  static let surfaceDim = UIColor(red: 0x13 / 255, green: 0x13 / 255, blue: 0x16 / 255, alpha: 1)
+  static let surface = surfaceDim
+  static let surfaceContainerLowest = UIColor(red: 0x0E / 255, green: 0x0E / 255, blue: 0x11 / 255, alpha: 1)
+  static let surfaceContainerLow = UIColor(red: 0x1B / 255, green: 0x1B / 255, blue: 0x1E / 255, alpha: 1)
+  static let surfaceContainer = UIColor(red: 0x1F / 255, green: 0x1F / 255, blue: 0x22 / 255, alpha: 1)
+  static let surfaceContainerHigh = UIColor(red: 0x2A / 255, green: 0x2A / 255, blue: 0x2D / 255, alpha: 1)
+  static let surfaceContainerHighest = UIColor(red: 0x35 / 255, green: 0x34 / 255, blue: 0x38 / 255, alpha: 1)
+  static let surfaceVariant = surfaceContainerHighest
+  static let surfaceBright = UIColor(red: 0x39 / 255, green: 0x39 / 255, blue: 0x3C / 255, alpha: 1)
+
+  // Content
+  static let onSurface = UIColor(red: 0xE4 / 255, green: 0xE1 / 255, blue: 0xE6 / 255, alpha: 1)
+  static let onSurfaceVariant = UIColor(red: 0xCC / 255, green: 0xC3 / 255, blue: 0xD8 / 255, alpha: 1)
+  static let outline = UIColor(red: 0x95 / 255, green: 0x8D / 255, blue: 0xA1 / 255, alpha: 1)
+  static let outlineVariant = UIColor(red: 0x4A / 255, green: 0x44 / 255, blue: 0x55 / 255, alpha: 1)
+
+  // Accents
+  static let primary = UIColor(red: 0xD2 / 255, green: 0xBB / 255, blue: 0xFF / 255, alpha: 1)
+  static let onPrimary = UIColor(red: 0x3F / 255, green: 0x00 / 255, blue: 0x8E / 255, alpha: 1)
+  static let primaryContainer = UIColor(red: 0x7C / 255, green: 0x3A / 255, blue: 0xED / 255, alpha: 1)
+  static let onPrimaryContainer = UIColor(red: 0xED / 255, green: 0xE0 / 255, blue: 0xFF / 255, alpha: 1)
+  static let secondary = UIColor(red: 0xC0 / 255, green: 0xC1 / 255, blue: 0xFF / 255, alpha: 1)
+  static let tertiary = UIColor(red: 0xD0 / 255, green: 0xBC / 255, blue: 0xFF / 255, alpha: 1)
+
+  // Literal Stitch accent hexes (DESIGN.md "Primary Accents & Active States"), used by the
+  // new EditorUI components where the exact mockup hue matters more than the M3 mapping.
+  static let accentViolet = UIColor(red: 0x7C / 255, green: 0x3A / 255, blue: 0xED / 255, alpha: 1)
+  static let accentIndigo = UIColor(red: 0x63 / 255, green: 0x66 / 255, blue: 0xF1 / 255, alpha: 1)
+  static let accentHighlightViolet = UIColor(red: 0x8B / 255, green: 0x5C / 255, blue: 0xF6 / 255, alpha: 1)
+
+  // Literal Stitch surface hexes (DESIGN.md "Canvas & Surface Hierarchy").
+  static let canvasViewport = UIColor(red: 0x09 / 255, green: 0x09 / 255, blue: 0x0B / 255, alpha: 1)
+  static let editorSurface = UIColor(red: 0x12 / 255, green: 0x12 / 255, blue: 0x14 / 255, alpha: 1)
+  static let elevatedPanel = UIColor(red: 0x18 / 255, green: 0x18 / 255, blue: 0x1B / 255, alpha: 1)
+  static let interactiveNeutral = UIColor(red: 0x27 / 255, green: 0x27 / 255, blue: 0x2A / 255, alpha: 1)
+  static let mutedBorderColor = UIColor(red: 0x3F / 255, green: 0x3F / 255, blue: 0x46 / 255, alpha: 1)
+
+  // Literal Stitch text hexes (DESIGN.md "Typography & Content Grayscale").
+  static let textPrimary = UIColor.white
+  static let textSecondary = UIColor(red: 0xA1 / 255, green: 0xA1 / 255, blue: 0xAA / 255, alpha: 1)
+  static let textSubtle = UIColor(red: 0x71 / 255, green: 0x71 / 255, blue: 0x7A / 255, alpha: 1)
+
+  // Spacing (points), matching DESIGN.md's `space-*` scale.
+  static let spaceXs: CGFloat = 4
+  static let spaceSm: CGFloat = 8
+  static let spaceMd: CGFloat = 12
+  static let spaceLg: CGFloat = 16
+  static let spaceXl: CGFloat = 20
+  static let space2xl: CGFloat = 24
+  static let space3xl: CGFloat = 32
+  static let touchTargetMin: CGFloat = 44
+
+  // Corner radii (points)
+  static let radiusSm: CGFloat = 4
+  static let radiusMd: CGFloat = 8
+  static let radiusLg: CGFloat = 12
+  static let radiusXl: CGFloat = 16
+  static let radiusSheet: CGFloat = 24
+
+  // Elevation tiers (DESIGN.md "Elevation & Depth"): background color + opacity to composite
+  // persistent chrome / floating trays / popovers over the canvas.
+  enum ElevationTier1 { static let color = editorSurface; static let opacity: CGFloat = 0.92 }
+  enum ElevationTier2 { static let color = elevatedPanel; static let opacity: CGFloat = 0.88 }
+  enum ElevationTier3 { static let color = interactiveNeutral; static let opacity: CGFloat = 1.0 }
+}

package/ios/Editor/PhotoVideoEditorOutcome.swift

@@ -0,0 +1,9 @@
+import Foundation
+
+/// What the native editor produced when it finished. `.success` metadata is
+/// populated for photo and video exports alike; `durationMs` is video-only.
+enum PhotoVideoEditorOutcome {
+  case cancelled
+  case success(uri: String, mimeType: String?, width: Int?, height: Int?, fileSize: Int?, durationMs: Int64? = nil)
+  case failure(code: String, message: String)
+}