@symbiote-native/clipboard 0.0.1 → 0.2.0

package/README.md

@@ -1,44 +1,198 @@
 # @symbiote-native/clipboard
 
-**Status: skeleton only — not implemented, published early to reserve the npm name.**
+A wrapper package for [SymbioteNative](../../README.md) that makes
+[`expo-clipboard`](https://docs.expo.dev/versions/latest/sdk/clipboard/) — read/write clipboard
+text, URLs, and images, plus a clipboard-change listener — usable from **every** adapter, React,
+Vue, and Angular, not just React. Unlike `@symbiote-native/sensors`, which is all
+`DeviceSensor`-shaped classes plus one free-function module (`Pedometer`), clipboard is closer to
+`@symbiote-native/local-auth`'s shape — mostly stateless async functions — plus **one**
+listener-based subscription (`addClipboardListener`) that each adapter wraps in its own
+mount/unmount lifecycle (`useClipboard`).
 
-This package will be a port of [`expo-clipboard`](https://docs.expo.dev/versions/latest/sdk/clipboard/)
-for [SymbioteNative](../../README.md) — read/write clipboard text, URLs, and images, plus a
-clipboard-change listener, reachable from every adapter (React, Vue, Angular), not just React.
-Nothing beyond this `package.json` + `README.md` exists yet.
+## Install
 
-## Planned API
+```bash
+npm install @symbiote-native/clipboard
+```
+
+Depends on `expo-clipboard` and `expo-modules-core` directly (regular dependencies, pinned to an
+exact version — never a caret range, since this package's `core/` is hand-ported against one
+specific native API shape and a newer resolve could silently drift the two apart). Never install
+`expo-clipboard` yourself, and never add the `expo` meta-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
+
+Unlike a plain RN native module, `expo-clipboard`'s native code is discovered by
+`expo-modules-autolinking`, not RN's own `react-native.config.cjs` mechanism — this needs wiring
+into the native host app **once**, covering this package and every other `expo-modules-core`
+package (`@symbiote-native/sensors`, `@symbiote-native/local-auth`) with zero further changes:
+
+| Platform | Touches |
+|---|---|
+| iOS | `ios/Podfile` — add `use_expo_modules!` |
+| iOS | `AppDelegate.swift` — Expo's runtime-bootstrap hook |
+| Android | `settings.gradle` / `app/build.gradle` — resolve and include the Expo Gradle projects |
+| Android | `MainApplication.kt` — Expo's bootstrap hook, plus a hand-written native-module name map (there's no `expo` meta-package here to auto-generate one) |
+
+Full mechanics live in the `symbiote-expo-native-module` skill. Clipboard itself needs no
+`Info.plist`/`AndroidManifest.xml` permission entry on either platform — reading/writing the
+clipboard requires no platform permission string.
+
+## Shape
+
+```
+src/core/               getStringAsync/setStringAsync/hasStringAsync, getUrlAsync/setUrlAsync/
+                         hasUrlAsync (iOS only), getImageAsync/setImageAsync/hasImageAsync, and
+                         addClipboardListener/removeClipboardListener. native-module.ts resolves
+                         the ExpoClipboard native module via expo-modules-core's
+                         requireNativeModule.
+src/react/hooks/         @symbiote-native/clipboard/react   — useClipboard
+src/vue/composables/     @symbiote-native/clipboard/vue     — useClipboard (same name)
+src/angular/services/    @symbiote-native/clipboard/angular — ClipboardService
+```
+
+Every function except the listener is plain stateless async and re-exported as-is. The listener
+subscription (`addClipboardListener`) lives once in `core`, framework-agnostic; each adapter's
+`useClipboard` hook/composable/`ClipboardService.connect()` is a thin mount/unmount (or DI-scoped
+`effect()`, for Angular) wrapper around that same subscription — the plumbing is written once and
+shared by all three.
+
+## Use it
+
+```ts
+import { getStringAsync, setStringAsync, addClipboardListener } from '@symbiote-native/clipboard';
+```
+
+`useClipboard()`'s event only carries the clipboard's changed content *types*
+(`IClipboardEvent.contentTypes`), never the string itself — every adapter's demo screen treats a
+change as a cue to re-fetch via `getStringAsync()`, not a value to render directly.
+
+```tsx
+// React
+import { useEffect, useState } from 'react';
+import { getStringAsync, setStringAsync } from '@symbiote-native/clipboard';
+import { useClipboard } from '@symbiote-native/clipboard/react';
+
+function ClipboardScreen() {
+  const clipboardEvent = useClipboard(); // IClipboardEvent | null
+  const [text, setText] = useState<string | null>(null);
+
+  useEffect(() => {
+    getStringAsync().then(setText);
+  }, [clipboardEvent]);
+
+  const handleCopy = (input: string) => setStringAsync(input).then(() => getStringAsync().then(setText));
+
+  return <Text>{text ?? 'checking…'}</Text>;
+}
+```
+
+```vue
+<!-- Vue -->
+<script setup lang="ts">
+import { onMounted, ref, watch } from 'vue';
+import { getStringAsync, setStringAsync } from '@symbiote-native/clipboard';
+import { useClipboard } from '@symbiote-native/clipboard/vue';
+
+const text = ref('checking…');
+function refresh(): void {
+  void getStringAsync().then(value => { text.value = value; });
+}
+onMounted(refresh);
 
-Forward-looking reference only — signatures below are copied from upstream's
-`Clipboard.ts`/`Clipboard.types.ts`, not yet ported here.
+const clipboardEvent = useClipboard(); // Ref<IClipboardEvent | null>
+watch(clipboardEvent, event => { if (event) refresh(); });
+
+function handleCopy(input: string): void {
+  void setStringAsync(input).then(refresh);
+}
+</script>
+<template>
+  <Text>{{ text }}</Text>
+</template>
+```
 
 ```ts
-getStringAsync(options?: GetStringOptions): Promise<string>
-setStringAsync(text: string, options?: SetStringOptions): Promise<boolean>
+// Angular
+import { Component, Injector, effect, inject, signal } from '@angular/core';
+import { ClipboardService, getStringAsync, setStringAsync } from '@symbiote-native/clipboard/angular';
+
+@Component({ /* ... */ })
+export class ClipboardScreen {
+  private readonly injector = inject(Injector);
+  private readonly clipboardEvent = inject(ClipboardService).connect(); // Signal<IClipboardEvent | null>
+  readonly text = signal('checking…');
+
+  constructor() {
+    this.refresh();
+    effect(() => { if (this.clipboardEvent() !== null) this.refresh(); }, { injector: this.injector });
+  }
+
+  handleCopy(input: string): void {
+    setStringAsync(input).then(() => this.refresh());
+  }
+
+  private refresh(): void {
+    getStringAsync().then(value => this.text.set(value));
+  }
+}
+```
+
+These are trimmed from the real demo screens — `examples/expo-react/screens/ClipboardScreen.tsx`,
+`examples/expo-vue-sfc/screens/ClipboardScreen.vue`, `examples/expo-vue-tsx/screens/ClipboardScreen.tsx`,
+`examples/expo-angular/src/screens/ClipboardScreen.ts` — which additionally show `hasStringAsync()`
+status badges and, iOS-only, the `getUrlAsync`/`setUrlAsync`/`hasUrlAsync` URL surface.
+
+## API
+
+```ts
+getStringAsync(options?: IGetStringOptions): Promise<string>
+setStringAsync(text: string, options?: ISetStringOptions): Promise<boolean>
 hasStringAsync(): Promise<boolean>
 getUrlAsync(): Promise<string | null> // iOS only
 setUrlAsync(url: string): Promise<void> // iOS only
 hasUrlAsync(): Promise<boolean> // iOS only
-getImageAsync(options: GetImageOptions): Promise<ClipboardImage | null>
+getImageAsync(options: IGetImageOptions): Promise<IClipboardImage | null>
 setImageAsync(base64Image: string): Promise<void>
 hasImageAsync(): Promise<boolean>
-addClipboardListener(listener: (event: ClipboardEvent) => void): EventSubscription
+addClipboardListener(listener: (event: IClipboardEvent) => void): EventSubscription
 removeClipboardListener(subscription: EventSubscription) // deprecated, use subscription.remove()
 ```
 
-Plus `ContentType`, `StringFormat`, `GetStringOptions`, `SetStringOptions`, `GetImageOptions`,
-`ClipboardImage`, `ClipboardEvent` — ported from upstream's `Clipboard.types.ts`, renamed with
-this repo's `I`-prefix convention for exported types where applicable
-(`ts-js-best-practices`). Upstream also ships a `ClipboardPasteButton` component (native
-paste-button UI, iOS 16+) — whether that's in scope for this package's first real
-implementation is an open question for that later work, not decided here.
+Plus `ContentType`, `StringFormat`, `IGetStringOptions`, `ISetStringOptions`, `IGetImageOptions`,
+`IClipboardImage`, `IClipboardEvent` — ported from upstream's `Clipboard.types.ts`, renamed with
+this repo's `I`-prefix convention for exported types (`ts-js-best-practices`); `ContentType` and
+`StringFormat` stay unprefixed enums, matching `AuthenticationType`/`SecurityLevel` in
+`@symbiote-native/local-auth`.
+
+```ts
+// React
+import { useClipboard } from '@symbiote-native/clipboard/react';
+const clipboardEvent = useClipboard(); // IClipboardEvent | null
+
+// Vue
+import { useClipboard } from '@symbiote-native/clipboard/vue';
+const clipboardEvent = useClipboard(); // Ref<IClipboardEvent | null>
+
+// Angular
+import { ClipboardService } from '@symbiote-native/clipboard/angular';
+readonly clipboardEvent = inject(ClipboardService).connect(); // Signal<IClipboardEvent | null>
+```
+
+`ClipboardPasteButton` (upstream's native paste-button view component, iOS 16+) is **not**
+ported — out of scope for this pass. If it's ever wrapped, it follows
+`symbiote-third-party-native-view`, not this package's `expo-modules-core` recipe.
+
+## Test it
 
-## When this moves past skeleton
+Tests exercise the JS layer only, against a fake native module in place of the real
+`requireNativeModule` resolution (`src/core/**/*.test.ts`,
+`src/{react,vue,angular}/**/*.test.{ts,tsx}`) — no Fabric/Descriptor angle at all, since clipboard
+is a pure async-function + one-listener surface, never a view. Native rendering itself is verified
+on-device (see the parent [README](../../README.md) for the project's testing model).
 
-See [`@symbiote-native/local-auth`](../local-auth) as the reference shape for what this package
-will look like once implemented — same `expo-modules-core`-based wrapping pattern (no native
-view, a handful of async functions + an event listener), same core/react/vue/angular layout.
-The real wrapping mechanics (why `expo-modules-core` is depended on directly and never the
-`expo` meta-package, why upstream JS is hand-ported rather than imported, how autolinking picks
-up the native module) are documented in the
-[`symbiote-expo-native-module`](../../.claude/skills/symbiote-expo-native-module/SKILL.md) skill.
+Native autolinking wiring (Android's 3-layer registration, iOS Podfile/pod install) is done across
+all four `examples/expo-*` canary apps. It isn't wired into the public non-Expo canaries
+(`examples/react`, `examples/vue-sfc`, `examples/vue-tsx`, `examples/angular`) yet — those don't
+depend on any `expo-modules-core` package today.

package/build/angular/index.d.ts

@@ -0,0 +1,2 @@
+export { ClipboardService } from './services/clipboard.service';
+export * from '../core';

package/build/angular/index.js

@@ -0,0 +1,7 @@
+// @symbiote-native/clipboard/angular: the Angular entry over the framework-agnostic core.
+// Unlike @symbiote-native/local-auth (all stateless functions, plain re-export), clipboard has
+// one listener-based piece — ClipboardService.connect() is the Angular-only lifecycle half; the
+// addClipboardListener subscription plumbing all lives in core, shared with React/Vue. Mirrors
+// @symbiote-native/sensors' AccelerometerService.
+export { ClipboardService } from './services/clipboard.service/index.js';
+export * from '../core/index.js';

package/build/angular/services/clipboard.service/index.d.ts

@@ -0,0 +1,6 @@
+import { type Signal } from '@angular/core';
+import { type IClipboardEvent } from '../../../core';
+export declare class ClipboardService {
+    private readonly injector;
+    connect(): Signal<IClipboardEvent | null>;
+}

package/build/angular/services/clipboard.service/index.js

@@ -0,0 +1,77 @@
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+import { effect, inject, Injectable, Injector, signal } from '@angular/core';
+import { addClipboardListener } from '../../../core/index.js';
+// Angular twin of React's `useClipboard` hook and Vue's `useClipboard` composable. Angular has
+// no per-instance hook — state and lifecycle live in DI instead, so `connect()` stands in for
+// the hook's role: call it ONCE (typically from a component's field initializer, inside an
+// injection context).
+//
+//   readonly clipboardEvent = inject(ClipboardService).connect();
+//   // template: {{ clipboardEvent()?.contentTypes }}
+//
+// Mirrors AccelerometerService.connect() from @symbiote-native/sensors: the subscription doesn't
+// depend on anything the caller's own signals could change between renders, so a single
+// effect() that subscribes once and cleans up once is enough.
+let ClipboardService = (() => {
+    let _classDecorators = [Injectable({ providedIn: 'root' })];
+    let _classDescriptor;
+    let _classExtraInitializers = [];
+    let _classThis;
+    var ClipboardService = class {
+        static { _classThis = this; }
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(null) : void 0;
+            __esDecorate(null, _classDescriptor = { value: _classThis }, _classDecorators, { kind: "class", name: _classThis.name, metadata: _metadata }, null, _classExtraInitializers);
+            ClipboardService = _classThis = _classDescriptor.value;
+            if (_metadata) Object.defineProperty(_classThis, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+            __runInitializers(_classThis, _classExtraInitializers);
+        }
+        // Captured in the constructor (itself always run inside an injection context by Angular's own
+        // DI) so `connect()` can create an `effect()` even when called from plain field-initializer
+        // code that is not, on its own, an active injection context — mirrors AccelerometerService.
+        injector = inject(Injector);
+        connect() {
+            const event = signal(null);
+            effect(onCleanup => {
+                const subscription = addClipboardListener(next => event.set(next));
+                onCleanup(() => subscription.remove());
+            }, { injector: this.injector });
+            return event.asReadonly();
+        }
+    };
+    return ClipboardService = _classThis;
+})();
+export { ClipboardService };

package/build/core/clipboard.d.ts

@@ -0,0 +1,86 @@
+import type { EventSubscription } from 'expo-modules-core';
+import type { IClipboardEvent, IClipboardImage, IGetImageOptions, IGetStringOptions, ISetStringOptions } from './types';
+/**
+ * Gets the content of the user's clipboard.
+ *
+ * Note: On iOS 16+, if the user denies paste permission, this method returns an empty string.
+ * Due to iOS platform limitations, there is no way to distinguish between an empty clipboard
+ * and denied permission.
+ *
+ * @param options Options for the clipboard content to be retrieved.
+ * @returns A promise that resolves to the content of the clipboard, or an empty string if the
+ * clipboard is empty or permission was denied.
+ */
+export declare function getStringAsync(options?: IGetStringOptions): Promise<string>;
+/**
+ * Sets the content of the user's clipboard.
+ *
+ * @param text The string to save to the clipboard.
+ * @param options Options for the clipboard content to be set.
+ * @returns A promise that resolves to `true` once the string has been saved to the clipboard.
+ */
+export declare function setStringAsync(text: string, options?: ISetStringOptions): Promise<boolean>;
+/**
+ * Returns whether the clipboard has text content. Returns `true` for both plain text and rich
+ * text (e.g. HTML).
+ */
+export declare function hasStringAsync(): Promise<boolean>;
+/**
+ * Gets the URL from the user's clipboard.
+ *
+ * Note: On iOS 16+, if the user denies paste permission, this method returns `null`. Due to iOS
+ * platform limitations, there is no way to distinguish between no URL in clipboard and denied
+ * permission.
+ * @platform ios
+ */
+export declare function getUrlAsync(): Promise<string | null>;
+/**
+ * Sets a URL in the user's clipboard. Behaves the same as `setStringAsync`, except that it sets
+ * the clipboard content type to be a URL, letting your app or other apps know that the clipboard
+ * contains a URL and behave accordingly.
+ * @platform ios
+ */
+export declare function setUrlAsync(url: string): Promise<void>;
+/**
+ * Returns whether the clipboard has URL content.
+ * @platform ios
+ */
+export declare function hasUrlAsync(): Promise<boolean>;
+/**
+ * Gets the image from the user's clipboard and returns it in the specified format.
+ *
+ * Note: On iOS 16+, if the user denies paste permission, this method returns `null`. Due to iOS
+ * platform limitations, there is no way to distinguish between no image in clipboard and denied
+ * permission.
+ *
+ * @param options Specifies the desired format of the image.
+ * @returns If there was an image in the clipboard, resolves to an `IClipboardImage` object
+ * containing the base64 string and metadata of the image. Otherwise resolves to `null` (this
+ * includes cases where permission was denied).
+ */
+export declare function getImageAsync(options: IGetImageOptions): Promise<IClipboardImage | null>;
+/**
+ * Sets an image in the user's clipboard.
+ *
+ * @param base64Image Image encoded as a base64 string, without MIME type.
+ */
+export declare function setImageAsync(base64Image: string): Promise<void>;
+/**
+ * Returns whether the clipboard has image content.
+ */
+export declare function hasImageAsync(): Promise<boolean>;
+/**
+ * Adds a listener that fires whenever the content of the user's clipboard changes. Kept here at
+ * the core level, framework-agnostic, exactly like `Accelerometer.addListener` lives in
+ * `@symbiote-native/sensors`' core — each adapter's `useClipboard` hook/composable/service wraps
+ * this in its own mount/unmount lifecycle rather than reimplementing the subscription.
+ *
+ * @param listener Callback invoked with an `IClipboardEvent` describing the new clipboard
+ * content types whenever the clipboard changes.
+ */
+export declare function addClipboardListener(listener: (event: IClipboardEvent) => void): EventSubscription;
+/**
+ * Removes the listener added by `addClipboardListener`.
+ * @deprecated use `subscription.remove()` instead.
+ */
+export declare function removeClipboardListener(subscription: EventSubscription): void;

package/build/core/clipboard.js

@@ -0,0 +1,142 @@
+import { UnavailabilityError } from 'expo-modules-core';
+import { CLIPBOARD_CHANGED_EVENT_NAME, expoClipboard } from './native-module.js';
+// Matches the module name upstream's own Clipboard.ts passes to every UnavailabilityError.
+const NATIVE_MODULE_NAME = 'Clipboard';
+/**
+ * Gets the content of the user's clipboard.
+ *
+ * Note: On iOS 16+, if the user denies paste permission, this method returns an empty string.
+ * Due to iOS platform limitations, there is no way to distinguish between an empty clipboard
+ * and denied permission.
+ *
+ * @param options Options for the clipboard content to be retrieved.
+ * @returns A promise that resolves to the content of the clipboard, or an empty string if the
+ * clipboard is empty or permission was denied.
+ */
+export async function getStringAsync(options = {}) {
+    if (!expoClipboard.getStringAsync) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'getStringAsync');
+    }
+    return expoClipboard.getStringAsync(options);
+}
+/**
+ * Sets the content of the user's clipboard.
+ *
+ * @param text The string to save to the clipboard.
+ * @param options Options for the clipboard content to be set.
+ * @returns A promise that resolves to `true` once the string has been saved to the clipboard.
+ */
+export async function setStringAsync(text, options = {}) {
+    if (!expoClipboard.setStringAsync) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'setStringAsync');
+    }
+    return expoClipboard.setStringAsync(text, options);
+}
+/**
+ * Returns whether the clipboard has text content. Returns `true` for both plain text and rich
+ * text (e.g. HTML).
+ */
+// DELIBERATE DIVERGENCE from expo: Clipboard.ts:57 declares this one plain `function`, not
+// `async` like its 8 siblings, so on a build without the native method the UnavailabilityError
+// escapes synchronously at the call site and `hasStringAsync().catch(handler)` never catches it.
+// Parity would hand callers a guard that fires differently from every other method in this API,
+// so we add `async` here instead of tagging it. Everything else stays a verbatim port.
+export async function hasStringAsync() {
+    if (!expoClipboard.hasStringAsync) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'hasStringAsync');
+    }
+    return expoClipboard.hasStringAsync();
+}
+/**
+ * Gets the URL from the user's clipboard.
+ *
+ * Note: On iOS 16+, if the user denies paste permission, this method returns `null`. Due to iOS
+ * platform limitations, there is no way to distinguish between no URL in clipboard and denied
+ * permission.
+ * @platform ios
+ */
+export async function getUrlAsync() {
+    if (!expoClipboard.getUrlAsync) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'getUrlAsync');
+    }
+    return expoClipboard.getUrlAsync();
+}
+/**
+ * Sets a URL in the user's clipboard. Behaves the same as `setStringAsync`, except that it sets
+ * the clipboard content type to be a URL, letting your app or other apps know that the clipboard
+ * contains a URL and behave accordingly.
+ * @platform ios
+ */
+export async function setUrlAsync(url) {
+    if (!expoClipboard.setUrlAsync) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'setUrlAsync');
+    }
+    return expoClipboard.setUrlAsync(url);
+}
+/**
+ * Returns whether the clipboard has URL content.
+ * @platform ios
+ */
+export async function hasUrlAsync() {
+    if (!expoClipboard.hasUrlAsync) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'hasUrlAsync');
+    }
+    return expoClipboard.hasUrlAsync();
+}
+/**
+ * Gets the image from the user's clipboard and returns it in the specified format.
+ *
+ * Note: On iOS 16+, if the user denies paste permission, this method returns `null`. Due to iOS
+ * platform limitations, there is no way to distinguish between no image in clipboard and denied
+ * permission.
+ *
+ * @param options Specifies the desired format of the image.
+ * @returns If there was an image in the clipboard, resolves to an `IClipboardImage` object
+ * containing the base64 string and metadata of the image. Otherwise resolves to `null` (this
+ * includes cases where permission was denied).
+ */
+export async function getImageAsync(options) {
+    if (!expoClipboard.getImageAsync) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'getImageAsync');
+    }
+    return expoClipboard.getImageAsync(options);
+}
+/**
+ * Sets an image in the user's clipboard.
+ *
+ * @param base64Image Image encoded as a base64 string, without MIME type.
+ */
+export async function setImageAsync(base64Image) {
+    if (!expoClipboard.setImageAsync) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'setImageAsync');
+    }
+    return expoClipboard.setImageAsync(base64Image);
+}
+/**
+ * Returns whether the clipboard has image content.
+ */
+export async function hasImageAsync() {
+    if (!expoClipboard.hasImageAsync) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'hasImageAsync');
+    }
+    return expoClipboard.hasImageAsync();
+}
+/**
+ * Adds a listener that fires whenever the content of the user's clipboard changes. Kept here at
+ * the core level, framework-agnostic, exactly like `Accelerometer.addListener` lives in
+ * `@symbiote-native/sensors`' core — each adapter's `useClipboard` hook/composable/service wraps
+ * this in its own mount/unmount lifecycle rather than reimplementing the subscription.
+ *
+ * @param listener Callback invoked with an `IClipboardEvent` describing the new clipboard
+ * content types whenever the clipboard changes.
+ */
+export function addClipboardListener(listener) {
+    return expoClipboard.addListener(CLIPBOARD_CHANGED_EVENT_NAME, listener);
+}
+/**
+ * Removes the listener added by `addClipboardListener`.
+ * @deprecated use `subscription.remove()` instead.
+ */
+export function removeClipboardListener(subscription) {
+    subscription.remove();
+}

package/build/core/index.d.ts

@@ -0,0 +1,3 @@
+export { getStringAsync, setStringAsync, hasStringAsync, getUrlAsync, setUrlAsync, hasUrlAsync, getImageAsync, setImageAsync, hasImageAsync, addClipboardListener, removeClipboardListener, } from './clipboard';
+export { ContentType, StringFormat, type IGetStringOptions, type ISetStringOptions, type IGetImageOptions, type IClipboardImage, type IClipboardEvent, } from './types';
+export type { EventSubscription } from 'expo-modules-core';

package/build/core/index.js

@@ -0,0 +1,2 @@
+export { getStringAsync, setStringAsync, hasStringAsync, getUrlAsync, setUrlAsync, hasUrlAsync, getImageAsync, setImageAsync, hasImageAsync, addClipboardListener, removeClipboardListener, } from './clipboard.js';
+export { ContentType, StringFormat, } from './types.js';

package/build/core/native-module.d.ts

@@ -0,0 +1,17 @@
+import type { EventSubscription } from 'expo-modules-core';
+import type { IClipboardEvent, IClipboardImage, IGetImageOptions, IGetStringOptions, ISetStringOptions } from './types';
+export declare const CLIPBOARD_CHANGED_EVENT_NAME = "onClipboardChanged";
+export type INativeClipboardModule = {
+    addListener(eventName: typeof CLIPBOARD_CHANGED_EVENT_NAME, listener: (event: IClipboardEvent) => void): EventSubscription;
+    removeAllListeners(eventName: typeof CLIPBOARD_CHANGED_EVENT_NAME): void;
+    getStringAsync?(options?: IGetStringOptions): Promise<string>;
+    setStringAsync?(text: string, options?: ISetStringOptions): Promise<boolean>;
+    hasStringAsync?(): Promise<boolean>;
+    getUrlAsync?(): Promise<string | null>;
+    setUrlAsync?(url: string): Promise<void>;
+    hasUrlAsync?(): Promise<boolean>;
+    getImageAsync?(options: IGetImageOptions): Promise<IClipboardImage | null>;
+    setImageAsync?(base64Image: string): Promise<void>;
+    hasImageAsync?(): Promise<boolean>;
+};
+export declare const expoClipboard: INativeClipboardModule;

package/build/core/native-module.js

@@ -0,0 +1,7 @@
+import { requireNativeModule } from 'expo-modules-core';
+const EXPO_CLIPBOARD_MODULE_NAME = 'ExpoClipboard';
+// The event name upstream's own ExpoClipboard.ts pairs with the native module's event map —
+// kept here, next to the module resolution, since core/clipboard.ts's addClipboardListener is
+// the only caller.
+export const CLIPBOARD_CHANGED_EVENT_NAME = 'onClipboardChanged';
+export const expoClipboard = requireNativeModule(EXPO_CLIPBOARD_MODULE_NAME);

package/build/core/types.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Type used to define what type of data is stored in the clipboard.
+ */
+export declare enum ContentType {
+    PLAIN_TEXT = "plain-text",
+    HTML = "html",
+    IMAGE = "image",
+    /**
+     * @platform iOS
+     */
+    URL = "url"
+}
+/**
+ * Type used to determine string format stored in the clipboard.
+ */
+export declare enum StringFormat {
+    PLAIN_TEXT = "plainText",
+    HTML = "html"
+}
+export type IGetStringOptions = {
+    /**
+     * The target format of the clipboard string to be converted to, if possible.
+     * @default StringFormat.PLAIN_TEXT
+     */
+    preferredFormat?: StringFormat;
+};
+export type ISetStringOptions = {
+    /**
+     * The input format of the provided string. Adjusting this option can help other applications
+     * interpret copied string properly.
+     * @default StringFormat.PLAIN_TEXT
+     */
+    inputFormat?: StringFormat;
+};
+export type IGetImageOptions = {
+    /**
+     * The format of the clipboard image to be converted to.
+     */
+    format: 'png' | 'jpeg';
+    /**
+     * Specify the quality of the returned image, between `0` and `1`. Defaults to `1` (highest
+     * quality). Applicable only when `format` is set to `jpeg`, ignored otherwise.
+     * @default 1
+     */
+    jpegQuality?: number;
+};
+export type IClipboardImage = {
+    /**
+     * A Base64-encoded string of the image data, already prepended with a
+     * `data:image/png;base64,` or `data:image/jpeg;base64,` prefix. Its format depends on the
+     * `format` option passed to `getImageAsync`.
+     */
+    data: string;
+    /**
+     * Dimensions (`width` and `height`) of the image pasted from clipboard.
+     */
+    size: {
+        width: number;
+        height: number;
+    };
+};
+export type IClipboardEvent = {
+    /**
+     * An array of content types that are available on the clipboard.
+     */
+    contentTypes: ContentType[];
+};