react-smart-copy 1.1.1 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/core.d.cts CHANGED
@@ -67,15 +67,34 @@ export declare function describeCopyError(error: CopyError): string;
67
67
  /** Default English, user-facing sentence for a paste error. Replace for i18n. */
68
68
  export declare function describePasteError(error: CopyError): string;
69
69
  //#endregion
70
+ //#region src/core/machine-shared.d.ts
71
+ /**
72
+ * Internals shared by the copy and paste state machines. Kept in one module so
73
+ * apps that use both don't ship two copies.
74
+ */
75
+ export declare const DEFAULT_MAX_RETRIES = 3;
76
+ /**
77
+ * Passed to adapters and lazy sources as their last argument. `signal` aborts
78
+ * when the operation is superseded, `reset()`, or its host unmounts, so
79
+ * expensive work (rasterising, decoding) can stop early.
80
+ */
81
+ interface OperationContext {
82
+ readonly signal: AbortSignal;
83
+ }
84
+ export declare function resolveMaxRetries(value: number | undefined): number;
85
+ //#endregion
70
86
  //#region src/core/payload.d.ts
71
87
  /** The only image MIME type with reliable cross-browser clipboard write support. */
72
88
  export declare const IMAGE_MIME_TYPE = "image/png";
73
89
  /**
74
90
  * An image as a Blob, a promise of one, or a function producing one.
75
91
  * Prefer the function form: it is invoked synchronously inside the user
76
- * gesture, which Safari requires for async image generation.
92
+ * gesture, which Safari requires for async image generation. The browser
93
+ * adapter always passes an `OperationContext`: stop work once
94
+ * `context.signal` aborts (reset, superseded, unmount). Optional in the type
95
+ * so adapters that call sources themselves keep compiling.
77
96
  */
78
- export type BlobSource = Blob | PromiseLike<Blob> | (() => Blob | PromiseLike<Blob>);
97
+ export type BlobSource = Blob | PromiseLike<Blob> | ((context?: OperationContext) => Blob | PromiseLike<Blob>);
79
98
  export interface TextPayload {
80
99
  readonly kind: 'text';
81
100
  readonly value: string;
@@ -171,10 +190,11 @@ export interface ClipboardEnvironment {
171
190
  *
172
191
  * Contract: start the platform write synchronously (before any `await`) so the
173
192
  * browser still sees the user gesture, and reject with a `CopyFailure` when you
174
- * can classify the error.
193
+ * can classify the error. `context.signal` aborts when the copy is reset or its
194
+ * host unmounts; honour it to stop expensive work early.
175
195
  */
176
196
  export interface ClipboardAdapter {
177
- write(payload: CopyPayload): Promise<void>;
197
+ write(payload: CopyPayload, context?: OperationContext): Promise<void>;
178
198
  }
179
199
  export interface BrowserClipboardAdapterOptions {
180
200
  /** Defaults to `window`, read lazily at copy time (SSR-safe). */
@@ -212,7 +232,6 @@ export declare function createCopyCoordinator(): CopyCoordinator;
212
232
  //#endregion
213
233
  //#region src/core/copy-machine.d.ts
214
234
  export declare const DEFAULT_RESET_AFTER_MS = 2000;
215
- export declare const DEFAULT_MAX_RETRIES = 3;
216
235
  export interface IdleState {
217
236
  readonly status: 'idle';
218
237
  }
@@ -236,7 +255,16 @@ export interface ErrorState {
236
255
  }
237
256
  export type CopyState = IdleState | CopyingState | CopiedState | ErrorState;
238
257
  export type CopyStatus = CopyState['status'];
239
- export type CopyIgnoredReason = 'in-flight' | 'nothing-to-retry' | 'not-retryable';
258
+ /**
259
+ * `cancelled`: the copy was reset or its host unmounted before it finished,
260
+ * so its work was aborted. Nothing to report to the user.
261
+ */
262
+ export type CopyIgnoredReason = 'in-flight' | 'nothing-to-retry' | 'not-retryable' | 'cancelled';
263
+ /**
264
+ * Why an in-flight copy was cancelled: `reset` (`reset()` was called) or
265
+ * `disconnect` (its host disconnected, e.g. the React component unmounted).
266
+ */
267
+ export type CopyCancelReason = 'reset' | 'disconnect';
240
268
  /** What `copy()`/`retry()` resolve to. They never reject. */
241
269
  export type CopyOutcome = {
242
270
  readonly status: 'copied';
@@ -265,6 +293,18 @@ export interface CopyMachineOptions {
265
293
  readonly coordinator?: CopyCoordinator | null;
266
294
  readonly onCopy?: (payload: CopyPayload) => void;
267
295
  readonly onError?: (error: CopyError, payload: CopyPayload | null) => void;
296
+ /**
297
+ * `reset()` moved the machine back to `idle` from any other state. Not
298
+ * called for the automatic return after `resetAfterMs`, for a `<CopyGroup>`
299
+ * handing "Copied" to another member, or when already `idle`.
300
+ */
301
+ readonly onReset?: () => void;
302
+ /**
303
+ * A copy in flight was cancelled before it settled: its `signal` aborted
304
+ * and its result will not reach state or `onCopy` / `onError`. Fires
305
+ * before `onReset` when `reset()` cancels a copy.
306
+ */
307
+ readonly onCancel?: (reason: CopyCancelReason) => void;
268
308
  /** Clock injection for tests and deterministic environments. */
269
309
  readonly now?: () => number;
270
310
  }
@@ -275,16 +315,17 @@ export interface CopyMachine {
275
315
  readonly subscribe: (listener: () => void) => () => void;
276
316
  readonly copy: (source: CopySource) => Promise<CopyOutcome>;
277
317
  readonly retry: () => Promise<CopyOutcome>;
318
+ /** Back to `idle`. Discards any in-flight result and aborts its `signal`. */
278
319
  readonly reset: () => void;
279
320
  /**
280
321
  * Lifecycle hook for hosts. Re-arms a pending auto-reset; the returned
281
- * cleanup clears timers, drops in-flight results and unsticks `copying`.
322
+ * cleanup clears timers, drops in-flight results, aborts in-flight work and
323
+ * unsticks `copying`.
282
324
  * Safe to call repeatedly (React StrictMode).
283
325
  */
284
326
  readonly connect: () => () => void;
285
327
  }
286
328
  export declare const IDLE_STATE: IdleState;
287
- export declare function resolveMaxRetries(value: number | undefined): number;
288
329
  /** Pure helper: can `retry()` do anything from this state? */
289
330
  export declare function canRetryState(state: CopyState, maxRetries?: number): boolean;
290
331
  /** Framework-agnostic copy state machine. */
@@ -300,7 +341,11 @@ type PasteAcceptShorthand = 'text' | 'html' | 'image' | 'any';
300
341
  */
301
342
  type PasteAccept = PasteAcceptShorthand | `${string}/${string}`;
302
343
  interface PasteLimits {
303
- /** Total size cap across all accepted items. Strings count UTF-16 code units. Default 32 MiB. */
344
+ /**
345
+ * Total size cap across all accepted items, in UTF-8 bytes. Strings are measured as
346
+ * they would be encoded, matching `Blob.size`, so every paste path counts the same way.
347
+ * Default 32 MiB.
348
+ */
304
349
  readonly maxBytes?: number;
305
350
  /** Max number of accepted items (types + files). Default 32. */
306
351
  readonly maxItems?: number;
@@ -339,7 +384,14 @@ interface PasteResult {
339
384
  readonly images: readonly Blob[];
340
385
  /** Files from a paste event (e.g. copied in the OS file manager). Includes image files. */
341
386
  readonly files: readonly File[];
387
+ /**
388
+ * The entries of `files` that are also in `images`: verified image files, keeping their
389
+ * names, ready for `FormData`. Derived by the paste machine, so it is always consistent.
390
+ */
391
+ readonly imageFiles: readonly File[];
342
392
  }
393
+ /** What a {@link PasteAdapter} resolves with. `imageFiles` is derived from it by the machine. */
394
+ type PasteReadResult = Omit<PasteResult, 'imageFiles'>;
343
395
  export declare const DEFAULT_PASTE_ACCEPT: readonly PasteAccept[];
344
396
  export declare const DEFAULT_PASTE_MAX_BYTES: number;
345
397
  export declare const DEFAULT_PASTE_MAX_ITEMS = 32;
@@ -374,9 +426,11 @@ interface PasteEnvironment {
374
426
  *
375
427
  * Contract: call the platform API synchronously (before any `await`) so the
376
428
  * browser still sees the user gesture, and reject with a `CopyFailure`.
429
+ * `context.signal` aborts when the read is superseded, reset, or its host
430
+ * unmounts; honour it to stop decoding early.
377
431
  */
378
432
  interface PasteAdapter {
379
- read(options: ResolvedPasteReadOptions): Promise<PasteResult>;
433
+ read(options: ResolvedPasteReadOptions, context?: OperationContext): Promise<PasteReadResult>;
380
434
  }
381
435
  interface BrowserPasteAdapterOptions {
382
436
  /** Defaults to `window`, read lazily at paste time (SSR-safe). */
@@ -401,11 +455,25 @@ export interface PasteReadState {
401
455
  export interface PasteErrorState {
402
456
  readonly status: 'error';
403
457
  readonly error: CopyError;
458
+ /** Where the failed read came from. Only `'clipboard'` reads can be retried. */
459
+ readonly source: PasteSource;
460
+ /** `retry()` calls made since the last fresh `paste()`. */
461
+ readonly retryCount: number;
404
462
  }
405
463
  export type PasteState = PasteIdleState | PasteReadingState | PasteReadState | PasteErrorState;
406
464
  export type PasteStatus = PasteState['status'];
407
- export type PasteIgnoredReason = 'in-flight' | 'no-accepted-content';
408
- /** What `paste()` / `pasteEvent()` resolve to. They never reject. */
465
+ /**
466
+ * `cancelled`: the read was superseded, reset, or its host unmounted before it
467
+ * finished, so its work was aborted. Nothing to report to the user.
468
+ */
469
+ export type PasteIgnoredReason = 'in-flight' | 'no-accepted-content' | 'nothing-to-retry' | 'not-retryable' | 'cancelled';
470
+ /**
471
+ * Why an in-flight read was cancelled: `reset` (`reset()` was called),
472
+ * `disconnect` (its host disconnected, e.g. the React component unmounted) or
473
+ * `superseded` (a paste event arrived while a clipboard read was pending).
474
+ */
475
+ export type PasteCancelReason = 'reset' | 'disconnect' | 'superseded';
476
+ /** What `paste()` / `pasteEvent()` / `retry()` resolve to. They never reject. */
409
477
  export type PasteOutcome = {
410
478
  readonly status: 'read';
411
479
  readonly result: PasteResult;
@@ -431,8 +499,24 @@ export interface PasteMachineOptions extends PasteReadOptions {
431
499
  * accepted content, so the browser doesn't also insert it. Default `true`.
432
500
  */
433
501
  readonly preventDefault?: boolean;
502
+ /**
503
+ * Max `retry()` calls after a failed clipboard read. Default 3. `0`
504
+ * disables retry; `Infinity` allows unlimited retries.
505
+ */
506
+ readonly maxRetries?: number;
434
507
  readonly onPaste?: (result: PasteResult) => void;
435
508
  readonly onError?: (error: CopyError) => void;
509
+ /**
510
+ * `reset()` moved the machine back to `idle` from any other state. Not
511
+ * called for the automatic return after `resetAfterMs`, or when already `idle`.
512
+ */
513
+ readonly onReset?: () => void;
514
+ /**
515
+ * A read in flight was cancelled before it settled: its `signal` aborted
516
+ * and its result will not reach state or `onPaste` / `onError`. Fires
517
+ * before `onReset` when `reset()` cancels a read.
518
+ */
519
+ readonly onCancel?: (reason: PasteCancelReason) => void;
436
520
  /** Clock injection for tests and deterministic environments. */
437
521
  readonly now?: () => number;
438
522
  }
@@ -452,18 +536,27 @@ export interface PasteMachine {
452
536
  * accepted content are ignored and left untouched for the browser.
453
537
  */
454
538
  readonly pasteEvent: (event: PasteEventLike) => Promise<PasteOutcome>;
455
- /** Back to `idle`, discarding any in-flight result. */
539
+ /**
540
+ * Re-reads the clipboard after a retryable failure (e.g. permission denied,
541
+ * page not focused), up to `maxRetries`. Call it from a user gesture.
542
+ * Paste-event failures can't be retried: their data is gone after dispatch.
543
+ */
544
+ readonly retry: () => Promise<PasteOutcome>;
545
+ /** Back to `idle`. Discards any in-flight result and aborts its `signal`. */
456
546
  readonly reset: () => void;
457
547
  /**
458
548
  * Lifecycle hook for hosts. Re-arms a pending auto-reset; the returned
459
- * cleanup clears timers, drops in-flight results and unsticks `reading`.
549
+ * cleanup clears timers, drops in-flight results, aborts in-flight work and
550
+ * unsticks `reading`.
460
551
  * Safe to call repeatedly (React StrictMode).
461
552
  */
462
553
  readonly connect: () => () => void;
463
554
  }
464
555
  export declare const PASTE_IDLE_STATE: PasteIdleState;
556
+ /** Pure helper: can `retry()` do anything from this state? */
557
+ export declare function canRetryPasteState(state: PasteState, maxRetries?: number): boolean;
465
558
  /** Framework-agnostic paste state machine. */
466
559
  export declare function createPasteMachine(options?: PasteMachineOptionsSource): PasteMachine;
467
560
  //#endregion
468
- export type { BrowserPasteAdapterOptions, ClipboardItemLike, DataTransferLike, PasteAccept, PasteAcceptShorthand, PasteAdapter, PasteClipboardLike, PasteEnvironment, PasteItem, PasteLimits, PasteReadOptions, PasteResult, PasteSource, ResolvedPasteReadOptions };
561
+ export type { BrowserPasteAdapterOptions, ClipboardItemLike, DataTransferLike, OperationContext, PasteAccept, PasteAcceptShorthand, PasteAdapter, PasteClipboardLike, PasteEnvironment, PasteItem, PasteLimits, PasteReadOptions, PasteReadResult, PasteResult, PasteSource, ResolvedPasteReadOptions };
469
562
  //# sourceMappingURL=core.d.cts.map
package/dist/core.d.ts CHANGED
@@ -67,15 +67,34 @@ export declare function describeCopyError(error: CopyError): string;
67
67
  /** Default English, user-facing sentence for a paste error. Replace for i18n. */
68
68
  export declare function describePasteError(error: CopyError): string;
69
69
  //#endregion
70
+ //#region src/core/machine-shared.d.ts
71
+ /**
72
+ * Internals shared by the copy and paste state machines. Kept in one module so
73
+ * apps that use both don't ship two copies.
74
+ */
75
+ export declare const DEFAULT_MAX_RETRIES = 3;
76
+ /**
77
+ * Passed to adapters and lazy sources as their last argument. `signal` aborts
78
+ * when the operation is superseded, `reset()`, or its host unmounts, so
79
+ * expensive work (rasterising, decoding) can stop early.
80
+ */
81
+ interface OperationContext {
82
+ readonly signal: AbortSignal;
83
+ }
84
+ export declare function resolveMaxRetries(value: number | undefined): number;
85
+ //#endregion
70
86
  //#region src/core/payload.d.ts
71
87
  /** The only image MIME type with reliable cross-browser clipboard write support. */
72
88
  export declare const IMAGE_MIME_TYPE = "image/png";
73
89
  /**
74
90
  * An image as a Blob, a promise of one, or a function producing one.
75
91
  * Prefer the function form: it is invoked synchronously inside the user
76
- * gesture, which Safari requires for async image generation.
92
+ * gesture, which Safari requires for async image generation. The browser
93
+ * adapter always passes an `OperationContext`: stop work once
94
+ * `context.signal` aborts (reset, superseded, unmount). Optional in the type
95
+ * so adapters that call sources themselves keep compiling.
77
96
  */
78
- export type BlobSource = Blob | PromiseLike<Blob> | (() => Blob | PromiseLike<Blob>);
97
+ export type BlobSource = Blob | PromiseLike<Blob> | ((context?: OperationContext) => Blob | PromiseLike<Blob>);
79
98
  export interface TextPayload {
80
99
  readonly kind: 'text';
81
100
  readonly value: string;
@@ -171,10 +190,11 @@ export interface ClipboardEnvironment {
171
190
  *
172
191
  * Contract: start the platform write synchronously (before any `await`) so the
173
192
  * browser still sees the user gesture, and reject with a `CopyFailure` when you
174
- * can classify the error.
193
+ * can classify the error. `context.signal` aborts when the copy is reset or its
194
+ * host unmounts; honour it to stop expensive work early.
175
195
  */
176
196
  export interface ClipboardAdapter {
177
- write(payload: CopyPayload): Promise<void>;
197
+ write(payload: CopyPayload, context?: OperationContext): Promise<void>;
178
198
  }
179
199
  export interface BrowserClipboardAdapterOptions {
180
200
  /** Defaults to `window`, read lazily at copy time (SSR-safe). */
@@ -212,7 +232,6 @@ export declare function createCopyCoordinator(): CopyCoordinator;
212
232
  //#endregion
213
233
  //#region src/core/copy-machine.d.ts
214
234
  export declare const DEFAULT_RESET_AFTER_MS = 2000;
215
- export declare const DEFAULT_MAX_RETRIES = 3;
216
235
  export interface IdleState {
217
236
  readonly status: 'idle';
218
237
  }
@@ -236,7 +255,16 @@ export interface ErrorState {
236
255
  }
237
256
  export type CopyState = IdleState | CopyingState | CopiedState | ErrorState;
238
257
  export type CopyStatus = CopyState['status'];
239
- export type CopyIgnoredReason = 'in-flight' | 'nothing-to-retry' | 'not-retryable';
258
+ /**
259
+ * `cancelled`: the copy was reset or its host unmounted before it finished,
260
+ * so its work was aborted. Nothing to report to the user.
261
+ */
262
+ export type CopyIgnoredReason = 'in-flight' | 'nothing-to-retry' | 'not-retryable' | 'cancelled';
263
+ /**
264
+ * Why an in-flight copy was cancelled: `reset` (`reset()` was called) or
265
+ * `disconnect` (its host disconnected, e.g. the React component unmounted).
266
+ */
267
+ export type CopyCancelReason = 'reset' | 'disconnect';
240
268
  /** What `copy()`/`retry()` resolve to. They never reject. */
241
269
  export type CopyOutcome = {
242
270
  readonly status: 'copied';
@@ -265,6 +293,18 @@ export interface CopyMachineOptions {
265
293
  readonly coordinator?: CopyCoordinator | null;
266
294
  readonly onCopy?: (payload: CopyPayload) => void;
267
295
  readonly onError?: (error: CopyError, payload: CopyPayload | null) => void;
296
+ /**
297
+ * `reset()` moved the machine back to `idle` from any other state. Not
298
+ * called for the automatic return after `resetAfterMs`, for a `<CopyGroup>`
299
+ * handing "Copied" to another member, or when already `idle`.
300
+ */
301
+ readonly onReset?: () => void;
302
+ /**
303
+ * A copy in flight was cancelled before it settled: its `signal` aborted
304
+ * and its result will not reach state or `onCopy` / `onError`. Fires
305
+ * before `onReset` when `reset()` cancels a copy.
306
+ */
307
+ readonly onCancel?: (reason: CopyCancelReason) => void;
268
308
  /** Clock injection for tests and deterministic environments. */
269
309
  readonly now?: () => number;
270
310
  }
@@ -275,16 +315,17 @@ export interface CopyMachine {
275
315
  readonly subscribe: (listener: () => void) => () => void;
276
316
  readonly copy: (source: CopySource) => Promise<CopyOutcome>;
277
317
  readonly retry: () => Promise<CopyOutcome>;
318
+ /** Back to `idle`. Discards any in-flight result and aborts its `signal`. */
278
319
  readonly reset: () => void;
279
320
  /**
280
321
  * Lifecycle hook for hosts. Re-arms a pending auto-reset; the returned
281
- * cleanup clears timers, drops in-flight results and unsticks `copying`.
322
+ * cleanup clears timers, drops in-flight results, aborts in-flight work and
323
+ * unsticks `copying`.
282
324
  * Safe to call repeatedly (React StrictMode).
283
325
  */
284
326
  readonly connect: () => () => void;
285
327
  }
286
328
  export declare const IDLE_STATE: IdleState;
287
- export declare function resolveMaxRetries(value: number | undefined): number;
288
329
  /** Pure helper: can `retry()` do anything from this state? */
289
330
  export declare function canRetryState(state: CopyState, maxRetries?: number): boolean;
290
331
  /** Framework-agnostic copy state machine. */
@@ -300,7 +341,11 @@ type PasteAcceptShorthand = 'text' | 'html' | 'image' | 'any';
300
341
  */
301
342
  type PasteAccept = PasteAcceptShorthand | `${string}/${string}`;
302
343
  interface PasteLimits {
303
- /** Total size cap across all accepted items. Strings count UTF-16 code units. Default 32 MiB. */
344
+ /**
345
+ * Total size cap across all accepted items, in UTF-8 bytes. Strings are measured as
346
+ * they would be encoded, matching `Blob.size`, so every paste path counts the same way.
347
+ * Default 32 MiB.
348
+ */
304
349
  readonly maxBytes?: number;
305
350
  /** Max number of accepted items (types + files). Default 32. */
306
351
  readonly maxItems?: number;
@@ -339,7 +384,14 @@ interface PasteResult {
339
384
  readonly images: readonly Blob[];
340
385
  /** Files from a paste event (e.g. copied in the OS file manager). Includes image files. */
341
386
  readonly files: readonly File[];
387
+ /**
388
+ * The entries of `files` that are also in `images`: verified image files, keeping their
389
+ * names, ready for `FormData`. Derived by the paste machine, so it is always consistent.
390
+ */
391
+ readonly imageFiles: readonly File[];
342
392
  }
393
+ /** What a {@link PasteAdapter} resolves with. `imageFiles` is derived from it by the machine. */
394
+ type PasteReadResult = Omit<PasteResult, 'imageFiles'>;
343
395
  export declare const DEFAULT_PASTE_ACCEPT: readonly PasteAccept[];
344
396
  export declare const DEFAULT_PASTE_MAX_BYTES: number;
345
397
  export declare const DEFAULT_PASTE_MAX_ITEMS = 32;
@@ -374,9 +426,11 @@ interface PasteEnvironment {
374
426
  *
375
427
  * Contract: call the platform API synchronously (before any `await`) so the
376
428
  * browser still sees the user gesture, and reject with a `CopyFailure`.
429
+ * `context.signal` aborts when the read is superseded, reset, or its host
430
+ * unmounts; honour it to stop decoding early.
377
431
  */
378
432
  interface PasteAdapter {
379
- read(options: ResolvedPasteReadOptions): Promise<PasteResult>;
433
+ read(options: ResolvedPasteReadOptions, context?: OperationContext): Promise<PasteReadResult>;
380
434
  }
381
435
  interface BrowserPasteAdapterOptions {
382
436
  /** Defaults to `window`, read lazily at paste time (SSR-safe). */
@@ -401,11 +455,25 @@ export interface PasteReadState {
401
455
  export interface PasteErrorState {
402
456
  readonly status: 'error';
403
457
  readonly error: CopyError;
458
+ /** Where the failed read came from. Only `'clipboard'` reads can be retried. */
459
+ readonly source: PasteSource;
460
+ /** `retry()` calls made since the last fresh `paste()`. */
461
+ readonly retryCount: number;
404
462
  }
405
463
  export type PasteState = PasteIdleState | PasteReadingState | PasteReadState | PasteErrorState;
406
464
  export type PasteStatus = PasteState['status'];
407
- export type PasteIgnoredReason = 'in-flight' | 'no-accepted-content';
408
- /** What `paste()` / `pasteEvent()` resolve to. They never reject. */
465
+ /**
466
+ * `cancelled`: the read was superseded, reset, or its host unmounted before it
467
+ * finished, so its work was aborted. Nothing to report to the user.
468
+ */
469
+ export type PasteIgnoredReason = 'in-flight' | 'no-accepted-content' | 'nothing-to-retry' | 'not-retryable' | 'cancelled';
470
+ /**
471
+ * Why an in-flight read was cancelled: `reset` (`reset()` was called),
472
+ * `disconnect` (its host disconnected, e.g. the React component unmounted) or
473
+ * `superseded` (a paste event arrived while a clipboard read was pending).
474
+ */
475
+ export type PasteCancelReason = 'reset' | 'disconnect' | 'superseded';
476
+ /** What `paste()` / `pasteEvent()` / `retry()` resolve to. They never reject. */
409
477
  export type PasteOutcome = {
410
478
  readonly status: 'read';
411
479
  readonly result: PasteResult;
@@ -431,8 +499,24 @@ export interface PasteMachineOptions extends PasteReadOptions {
431
499
  * accepted content, so the browser doesn't also insert it. Default `true`.
432
500
  */
433
501
  readonly preventDefault?: boolean;
502
+ /**
503
+ * Max `retry()` calls after a failed clipboard read. Default 3. `0`
504
+ * disables retry; `Infinity` allows unlimited retries.
505
+ */
506
+ readonly maxRetries?: number;
434
507
  readonly onPaste?: (result: PasteResult) => void;
435
508
  readonly onError?: (error: CopyError) => void;
509
+ /**
510
+ * `reset()` moved the machine back to `idle` from any other state. Not
511
+ * called for the automatic return after `resetAfterMs`, or when already `idle`.
512
+ */
513
+ readonly onReset?: () => void;
514
+ /**
515
+ * A read in flight was cancelled before it settled: its `signal` aborted
516
+ * and its result will not reach state or `onPaste` / `onError`. Fires
517
+ * before `onReset` when `reset()` cancels a read.
518
+ */
519
+ readonly onCancel?: (reason: PasteCancelReason) => void;
436
520
  /** Clock injection for tests and deterministic environments. */
437
521
  readonly now?: () => number;
438
522
  }
@@ -452,18 +536,27 @@ export interface PasteMachine {
452
536
  * accepted content are ignored and left untouched for the browser.
453
537
  */
454
538
  readonly pasteEvent: (event: PasteEventLike) => Promise<PasteOutcome>;
455
- /** Back to `idle`, discarding any in-flight result. */
539
+ /**
540
+ * Re-reads the clipboard after a retryable failure (e.g. permission denied,
541
+ * page not focused), up to `maxRetries`. Call it from a user gesture.
542
+ * Paste-event failures can't be retried: their data is gone after dispatch.
543
+ */
544
+ readonly retry: () => Promise<PasteOutcome>;
545
+ /** Back to `idle`. Discards any in-flight result and aborts its `signal`. */
456
546
  readonly reset: () => void;
457
547
  /**
458
548
  * Lifecycle hook for hosts. Re-arms a pending auto-reset; the returned
459
- * cleanup clears timers, drops in-flight results and unsticks `reading`.
549
+ * cleanup clears timers, drops in-flight results, aborts in-flight work and
550
+ * unsticks `reading`.
460
551
  * Safe to call repeatedly (React StrictMode).
461
552
  */
462
553
  readonly connect: () => () => void;
463
554
  }
464
555
  export declare const PASTE_IDLE_STATE: PasteIdleState;
556
+ /** Pure helper: can `retry()` do anything from this state? */
557
+ export declare function canRetryPasteState(state: PasteState, maxRetries?: number): boolean;
465
558
  /** Framework-agnostic paste state machine. */
466
559
  export declare function createPasteMachine(options?: PasteMachineOptionsSource): PasteMachine;
467
560
  //#endregion
468
- export type { BrowserPasteAdapterOptions, ClipboardItemLike, DataTransferLike, PasteAccept, PasteAcceptShorthand, PasteAdapter, PasteClipboardLike, PasteEnvironment, PasteItem, PasteLimits, PasteReadOptions, PasteResult, PasteSource, ResolvedPasteReadOptions };
561
+ export type { BrowserPasteAdapterOptions, ClipboardItemLike, DataTransferLike, OperationContext, PasteAccept, PasteAcceptShorthand, PasteAdapter, PasteClipboardLike, PasteEnvironment, PasteItem, PasteLimits, PasteReadOptions, PasteReadResult, PasteResult, PasteSource, ResolvedPasteReadOptions };
469
562
  //# sourceMappingURL=core.d.ts.map