@symbiote-native/live-photo 0.0.0 → 0.1.0

package/README.md

@@ -4,44 +4,223 @@
 [SymbioteNative](../../README.md) adapter: React, Vue, Svelte, Solid and Angular. Shows a Live
 Photo, iOS only.
 
+Built the same way as [`@symbiote-native/clipboard`](../clipboard)'s `ClipboardPasteButton`, an
+`expo-modules-core` native view reached through `requireNativeViewManager` (see the
+`symbiote-expo-native-module` project skill: why `expo-modules-core` is depended on directly and never
+the `expo` meta-package, why the upstream JS is hand-ported into `core/`, and how autolinking finds the
+native module). One render function in `core/` returns a descriptor and every adapter only turns it into
+its own element.
+
 ## Install
 
+**New app:**
+
+```bash
+npx @symbiote-native/cli new my-app --live-photo
+```
+
+**Existing SymbioteNative app:**
+
+```bash
+npx @symbiote-native/cli add --live-photo
+```
+
+Either way: installs `@symbiote-native/live-photo` and wires the native autolinking automatically,
+see [`@symbiote-native/cli`](../cli).
+
+<details>
+<summary>Manual install (no CLI - installing and wiring native autolinking by hand)</summary>
+
 ```bash
-npx @symbiote-native/cli new my-app --live-photo   # new app
-npx @symbiote-native/cli add --live-photo          # existing app
+npm install @symbiote-native/live-photo
+```
+
+Depends on `expo-live-photo` and `expo-modules-core` directly (regular dependencies, pinned to exact
+versions, since this package's `core/` is hand-ported against one specific native API shape).
+Never install `expo-live-photo` yourself, and never add the `expo` package to this project: it bundles
+its own Metro/Babel pipeline that conflicts with this project's own.
+
+### Required one-time step: native autolinking wiring
+
+`expo-live-photo`'s native code is discovered by `expo-modules-autolinking`, not by RN's own
+`react-native.config.cjs` mechanism. Wire it into the native host app **once**, it covers this package
+and every other `expo-modules-core` package with zero further changes. The steps and the
+mechanics behind them are in the `symbiote-expo-native-module` skill and in
+[`@symbiote-native/network`](../network)'s README; the reference app is `examples/expo-react`.
+
+</details>
+
+## Shape
+
 ```
+src/core/                live-photo-view.ts - createLivePhotoViewHandle(getNode) and the render function.
+                         types.ts - ILivePhotoAsset, ILivePhotoViewHandle, ILivePhotoPlaybackStyle.
+src/react/               @symbiote-native/live-photo/react   - LivePhotoView (ref carries the handle)
+src/vue/                 @symbiote-native/live-photo/vue     - LivePhotoView (a template ref, the functions are exposed)
+src/svelte/              @symbiote-native/live-photo/svelte  - LivePhotoView (bind:this)
+src/solid/               @symbiote-native/live-photo/solid   - LivePhotoView (ref={fn})
+src/angular/             @symbiote-native/live-photo/angular - LivePhotoView (the functions are methods)
+```
+
+A native Expo view keeps its functions on its module's view prototypes and native finds the view by its
+native tag, so the engine's `defineExpoViewMethods` makes that call. Each adapter only hands over its host
+node. `native-link.json` carries only `ios.upstreamPackage`, upstream has no Android folder.
 
-Manual: `npm install @symbiote-native/live-photo`, then wire `expo-modules-autolinking` once per
-app. Never install `expo-live-photo` or the `expo` meta-package yourself.
+## Use it
 
-## Usage
+### React
 
 ```tsx
+import { useRef } from 'react';
 import { LivePhotoView, type ILivePhotoViewHandle } from '@symbiote-native/live-photo/react';
 
-const ref = useRef<ILivePhotoViewHandle>(null);
+const handle = useRef<ILivePhotoViewHandle>(null);
 
 <LivePhotoView
-  ref={ref}
+  ref={handle}
   style={{ width: 300, height: 400 }}
   source={{ photoUri, pairedVideoUri }}
-  contentFit="cover"
   onLoadError={error => console.warn(error.message)}
 />;
+<button title="Play" onPress={() => handle.current?.startPlayback('hint')} />;
+```
+
+### Vue
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { LivePhotoView, type ILivePhotoViewHandle } from '@symbiote-native/live-photo/vue';
+
+const handle = ref<ILivePhotoViewHandle | null>(null);
+</script>
+
+<template>
+  <LivePhotoView
+    ref="handle"
+    :style="{ width: 300, height: 400 }"
+    :source="{ photoUri, pairedVideoUri }"
+    @loadError="error => console.warn(error.message)"
+  />
+  <button title="Play" @press="handle?.startPlayback('hint')" />
+</template>
+```
+
+### Angular
+
+```ts
+import { Component } from '@angular/core';
+import { SYMBIOTE_ELEMENTS } from '@symbiote-native/angular';
+import { LivePhotoView } from '@symbiote-native/live-photo/angular';
 
-ref.current?.startPlayback('hint');
+@Component({
+  standalone: true,
+  imports: [LivePhotoView, SYMBIOTE_ELEMENTS],
+  template: `
+    <LivePhotoView
+      #view
+      [style]="{ width: 300, height: 400 }"
+      [source]="{ photoUri, pairedVideoUri }"
+      [onLoadError]="onLoadError"
+    />
+    <button title="Play" (press)="view.startPlayback('hint')" />
+  `,
+})
+export class LivePhotoCard {
+  readonly photoUri = '...';
+  readonly pairedVideoUri = '...';
+  readonly onLoadError = (error: { message: string }): void => console.warn(error.message);
+}
 ```
 
-The view takes `source`, `isMuted`, `contentFit`, `useDefaultGestureRecognizer`, the load and
-playback callbacks and the View surface. The handle has `startPlayback(style?)` and
-`stopPlayback()`. How the handle is reached follows each framework: a `ref` in React and Solid
-(`ref={fn}`), the exposed methods of a template ref in Vue, `bind:this` in Svelte and a
-`@ViewChild` in Angular.
+### Svelte
+
+```svelte
+<script lang="ts">
+  import { LivePhotoView, type ILivePhotoViewHandle } from '@symbiote-native/live-photo/svelte';
+
+  let handle = $state<ILivePhotoViewHandle | undefined>();
+</script>
+
+<LivePhotoView
+  bind:this={handle}
+  style={{ width: 300, height: 400 }}
+  source={{ photoUri, pairedVideoUri }}
+  onLoadError={error => console.warn(error.message)}
+/>
+<button title="Play" onPress={() => handle?.startPlayback('hint')} />
+```
+
+### Solid
+
+```tsx
+import { createSignal } from 'solid-js';
+import { LivePhotoView, type ILivePhotoViewHandle } from '@symbiote-native/live-photo/solid';
+
+const [handle, setHandle] = createSignal<ILivePhotoViewHandle>();
+
+<LivePhotoView
+  ref={setHandle}
+  style={{ width: 300, height: 400 }}
+  source={{ photoUri, pairedVideoUri }}
+  onLoadError={error => console.warn(error.message)}
+/>;
+<button title="Play" onPress={() => handle()?.startPlayback('hint')} />;
+```
+
+## API
+
+```ts
+<LivePhotoView source={{ photoUri, pairedVideoUri }} isMuted?={true} contentFit?={'contain' | 'cover'}
+               useDefaultGestureRecognizer?={true}
+               onLoadStart? onPreviewPhotoLoad? onLoadComplete? onLoadError?({ message }) onPlaybackStart? onPlaybackStop? />
+// handle:
+startPlayback(style?: 'full' | 'hint'): void     // default 'full'
+stopPlayback(): void
+```
+
+Off iOS the view renders nothing, with a warning in development, and the handle throws
+`UnavailabilityError`. Ported from upstream's `LivePhotoView.tsx`.
+
+## Notes
+
+- **iOS only.** Off iOS the view renders nothing, with a warning in development, and the handle
+  throws `UnavailabilityError`. Check `Platform.OS` before you render it.
+- **A Live Photo is two files.** The still photo and the paired video, and they must stay a pair:
+  the pairing lives in their metadata, so editing or recompressing either one breaks it.
+- **Playback style.** `startPlayback()` plays the full clip, `startPlayback('hint')` plays the short
+  preview you see when you press a photo in the Photos app.
+- **Muted by default.** `isMuted` is `true`, unmute it when the sound is part of the content.
+- **Press and hold plays** while `useDefaultGestureRecognizer` is `true`. Turn it off and call
+  `startPlayback` yourself if the photo has its own gestures.
+- **Not ported.** Nothing. Upstream ships no tests and no config plugin, the suites here are written against its behavior.
+
+## Common questions
+
+- **Where do the two URIs come from?** `@symbiote-native/image-picker` with
+  `mediaTypes: ['livePhotos']`: `assets[0].uri` and `assets[0].pairedVideoAsset?.uri`. A photo in
+  iCloud needs `shouldDownloadFromNetwork`.
+- **No Live Photo in the Simulator.** The Simulator cannot make one, use a real device.
+- **`onLoadError` or no playback.** The files are not one pair, or one was edited. Pass the two URIs
+  of one pick, untouched.
+- **Media library.** Resolving the still half was reported to throw for some assets, prefer the
+  picker.
+- **No sound.** `isMuted` defaults to `true`.
+- **Playback styles.** `startPlayback('full')` or `startPlayback('hint')`.
+- **Android.** Not available, the view renders nothing.
 
-Off iOS the view renders nothing (with a dev-only warning) and the handle throws
-`UnavailabilityError`.
+Sources: [Expo docs: LivePhoto](https://docs.expo.dev/versions/latest/sdk/live-photo/),
+[expo/expo#47730](https://github.com/expo/expo/issues/47730),
+[expo/expo#46512](https://github.com/expo/expo/issues/46512),
+[expo/expo#48658](https://github.com/expo/expo/issues/48658).
 
-## Not ported
+## Test it
 
-Nothing. Upstream ships no tests and no config plugin, the suites here are written against its
-behavior.
+No device is needed for the logic. The core tests (`src/core/*.test.ts`) replace `expo-modules-core`
+(`requireNativeViewManager`, `Platform`) and assert the descriptor a render function returns. The
+adapter tests (`src/{react,vue,solid,angular}/**/*.test.*`, `vitest`) render the real component over the
+recording Fabric with an injected view config and assert the committed payload, and Svelte's
+`*.smoke.test.ts` compile the `.svelte` files and mount them. Painting itself is verified on a device in
+the six `examples/expo-*` canary apps (`examples/expo-react`, `examples/expo-vue-sfc`,
+`examples/expo-vue-tsx`, `examples/expo-svelte`, `examples/expo-solid`, `examples/expo-angular`), see the
+parent [README](../../README.md).

package/build/react/live-photo-view.js

@@ -5,7 +5,9 @@ import { createLivePhotoViewHandle, renderLivePhotoView } from '../core/index.js
 /** React twin of `expo-live-photo`'s `LivePhotoView`, iOS only */
 export function LivePhotoView({ ref, ...props }) {
     const [host] = useState(createHostNodeHolder);
-    useImperativeHandle(ref, () => createLivePhotoViewHandle(host.getNode), [host]);
+    useImperativeHandle(ref, () => createLivePhotoViewHandle(host.getNode), [
+        host,
+    ]);
     const descriptor = renderLivePhotoView(props);
     return descriptor ? descriptorToReact(host.capture(descriptor)) : null;
 }

package/build-ngc/angular/live-photo-view/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/angular/live-photo-view/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAC1E,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE5E,OAAO,EAAE,yBAAyB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;;AAM5E,oEAAoE;AAUpE,MAAM,OAAO,aAAc,SAAQ,cAAc;IACtC,MAAM,CAAiC;IACvC,OAAO,CAAkC;IACzC,UAAU,CAAqC;IAExD,2BAA2B,CAAsD;IACxE,eAAe,CAA0C;IACzD,cAAc,CAAyC;IACvD,WAAW,CAAsC;IACjD,kBAAkB,CAA6C;IAC/D,cAAc,CAAyC;IACvD,WAAW,CAAsC;IAEzC,MAAM,GAAG,yBAAyB,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;IAE/C,SAAS,GAAG;QACtC,QAAQ;QACR,SAAS;QACT,YAAY;QACZ,6BAA6B;QAC7B,iBAAiB;QACjB,gBAAgB;QAChB,aAAa;QACb,oBAAoB;QACpB,gBAAgB;QAChB,aAAa;KACsC,CAAC;IAEnC,UAAU,CAAC,KAAa;QACzC,OAAO,mBAAmB,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC;IAED,aAAa,CAAC,aAAuC;QACnD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,aAAa,CAAC,CAAC;IAC3C,CAAC;IAED,YAAY;QACV,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC;IAC7B,CAAC;uGAtCU,aAAa;2FAAb,aAAa,kbAJd;;IAER,4DAJQ,gBAAgB;;2FAMf,aAAa;kBATzB,SAAS;mBAAC;oBACT,QAAQ,EAAE,eAAe;oBACzB,UAAU,EAAE,IAAI;oBAChB,OAAO,EAAE,CAAC,gBAAgB,CAAC;oBAC3B,eAAe,EAAE,uBAAuB,CAAC,MAAM;oBAC/C,QAAQ,EAAE;;IAER;iBACH;;sBAEE,KAAK;;sBACL,KAAK;;sBACL,KAAK;;sBACL,KAAK;;sBAEL,KAAK;;sBACL,KAAK;;sBACL,KAAK;;sBACL,KAAK;;sBACL,KAAK;;sBACL,KAAK"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/angular/live-photo-view/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAC1E,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE5E,OAAO,EAAE,yBAAyB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;;AAG5E,oEAAoE;AAUpE,MAAM,OAAO,aAAc,SAAQ,cAAc;IACtC,MAAM,CAAiC;IACvC,OAAO,CAAkC;IACzC,UAAU,CAAqC;IAExD,2BAA2B,CAAsD;IACxE,eAAe,CAA0C;IACzD,cAAc,CAAyC;IACvD,WAAW,CAAsC;IACjD,kBAAkB,CAA6C;IAC/D,cAAc,CAAyC;IACvD,WAAW,CAAsC;IAEzC,MAAM,GAAG,yBAAyB,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;IAE/C,SAAS,GAAG;QACtC,QAAQ;QACR,SAAS;QACT,YAAY;QACZ,6BAA6B;QAC7B,iBAAiB;QACjB,gBAAgB;QAChB,aAAa;QACb,oBAAoB;QACpB,gBAAgB;QAChB,aAAa;KACsC,CAAC;IAEnC,UAAU,CAAC,KAAa;QACzC,OAAO,mBAAmB,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC;IAED,aAAa,CAAC,aAAuC;QACnD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,aAAa,CAAC,CAAC;IAC3C,CAAC;IAED,YAAY;QACV,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC;IAC7B,CAAC;uGAtCU,aAAa;2FAAb,aAAa,kbAJd;;IAER,4DAJQ,gBAAgB;;2FAMf,aAAa;kBATzB,SAAS;mBAAC;oBACT,QAAQ,EAAE,eAAe;oBACzB,UAAU,EAAE,IAAI;oBAChB,OAAO,EAAE,CAAC,gBAAgB,CAAC;oBAC3B,eAAe,EAAE,uBAAuB,CAAC,MAAM;oBAC/C,QAAQ,EAAE;;IAER;iBACH;;sBAEE,KAAK;;sBACL,KAAK;;sBACL,KAAK;;sBACL,KAAK;;sBAEL,KAAK;;sBACL,KAAK;;sBACL,KAAK;;sBACL,KAAK;;sBACL,KAAK;;sBACL,KAAK"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@symbiote-native/live-photo",
-  "version": "0.0.0",
+  "version": "0.1.0",
   "description": "expo-live-photo wrapped for SymbioteNative — one framework-agnostic core, built once and reachable from the React, Vue, Svelte, Solid, and Angular adapters. Displays a Live Photo, iOS only.",
   "license": "MIT",
   "repository": {
@@ -67,7 +67,7 @@
   "dependencies": {
     "expo-live-photo": "57.0.2",
     "expo-modules-core": "57.0.20",
-    "@symbiote-native/components": "3.1.4"
+    "@symbiote-native/components": "3.2.0"
   },
   "peerDependencies": {
     "@angular/core": ">=20",
@@ -77,12 +77,12 @@
     "solid-js": ">=1.9.0",
     "svelte": ">=5.56.0",
     "vue": ">=3.5.0",
-    "@symbiote-native/angular": "^3.2.0",
-    "@symbiote-native/engine": "^1.5.0",
-    "@symbiote-native/react": "^3.2.0",
-    "@symbiote-native/svelte": "^3.1.0",
-    "@symbiote-native/solid": "^3.1.0",
-    "@symbiote-native/vue": "^3.2.0"
+    "@symbiote-native/angular": "^3.3.0",
+    "@symbiote-native/engine": "^1.6.0",
+    "@symbiote-native/react": "^3.3.0",
+    "@symbiote-native/solid": "^3.2.0",
+    "@symbiote-native/svelte": "^3.2.0",
+    "@symbiote-native/vue": "^3.3.0"
   },
   "peerDependenciesMeta": {
     "@symbiote-native/angular": {
@@ -130,13 +130,13 @@
     "solid-js": "^1.9.14",
     "svelte": "^5.56.0",
     "typescript": "~6.0.0",
-    "@symbiote-native/angular": "3.2.0",
-    "@symbiote-native/engine": "1.5.0",
-    "@symbiote-native/svelte": "3.1.0",
-    "@symbiote-native/test-utils": "0.4.6",
-    "@symbiote-native/solid": "3.1.0",
-    "@symbiote-native/vue": "3.2.0",
-    "@symbiote-native/react": "3.2.0"
+    "@symbiote-native/angular": "3.3.0",
+    "@symbiote-native/engine": "1.6.0",
+    "@symbiote-native/react": "3.3.0",
+    "@symbiote-native/solid": "3.2.0",
+    "@symbiote-native/svelte": "3.2.0",
+    "@symbiote-native/test-utils": "0.4.7",
+    "@symbiote-native/vue": "3.3.0"
   },
   "scripts": {
     "typecheck": "tsc --build",

package/src/angular/live-photo-view/index.ts

@@ -2,10 +2,7 @@ import { ChangeDetectionStrategy, Component, Input } from '@angular/core';
 import { DescriptorOutlet, NativeViewBase } from '@symbiote-native/angular';
 import type { IDescriptor } from '@symbiote-native/components';
 import { createLivePhotoViewHandle, renderLivePhotoView } from '../../core';
-import type {
-  ILivePhotoPlaybackStyle,
-  ILivePhotoViewProps,
-} from '../../core';
+import type { ILivePhotoPlaybackStyle, ILivePhotoViewProps } from '../../core';
 
 /** Angular twin of `expo-live-photo`'s `LivePhotoView`, iOS only */
 @Component({

package/src/react/live-photo-view.ts

@@ -16,7 +16,9 @@ export function LivePhotoView({
   ...props
 }: ILivePhotoViewReactProps): ReactElement | null {
   const [host] = useState(createHostNodeHolder);
-  useImperativeHandle(ref, () => createLivePhotoViewHandle(host.getNode), [host]);
+  useImperativeHandle(ref, () => createLivePhotoViewHandle(host.getNode), [
+    host,
+  ]);
   const descriptor = renderLivePhotoView(props);
   return descriptor ? descriptorToReact(host.capture(descriptor)) : null;
 }