lib/clipboard-sync

Client/server clipboard synchronization, shared by both transports.

The pieces are factories the cores compose: createClipboardSync owns the server-clipboard cache and the change-only signature (unchanged content never re-crosses the transport in either direction), createMultipartClipboardState reassembles multipart server pushes, createTaggedClipboardFetch marks the connect-time cache-only fetch, createLocalClipboardSender is the focus-driven local-to-server path, createDeferredClipboardWriter lands server pushes on engines that reject clipboard writes outside a user activation, localClipboardBlocker names what stops a local write at all, and createClipboardGestures wires the copy and paste keystrokes. The transports differ only in the hooks they inject: how a request or payload is sent and the enablement gates, which are closures re-read per event so runtime settings changes apply immediately.

Interfaces

MultipartClipboardState

Defined in: lib/clipboard-sync.js:200

Properties

begin

begin: (mime, total) => void;

Defined in: lib/clipboard-sync.js:201

Arms a transfer.

Parameters

Returns

void

push

push: (b64) => void;

Defined in: lib/clipboard-sync.js:202

Hands one base64 chunk to the worker.

Parameters

Returns

void

finish

finish: () => Promise<{
  result: any;
  mimeType: string;
  byteLength: number;
}>;

Defined in: lib/clipboard-sync.js:203

Resolves with the decoded payload and resets; rejects when no transfer is in progress.

Returns

Promise<{ result: any; mimeType: string; byteLength: number; }>

reset

reset: () => void;

Defined in: lib/clipboard-sync.js:206

Drops the transfer.

Returns

void

inProgress

inProgress: boolean;

Defined in: lib/clipboard-sync.js:207

mimeType

mimeType: string;

Defined in: lib/clipboard-sync.js:208

totalSize

totalSize: number;

Defined in: lib/clipboard-sync.js:209

Declared size in bytes.

receivedSize

receivedSize: number;

Defined in: lib/clipboard-sync.js:210

Decoded bytes accumulated so far.

TaggedClipboardFetch

Defined in: lib/clipboard-sync.js:279

Properties

arm

arm: () => void;

Defined in: lib/clipboard-sync.js:280

Records that the server tags the reply.

Returns

void

armLegacyWindow

armLegacyWindow: (ms) => void;

Defined in: lib/clipboard-sync.js:281

Starts the timed fallback after sending cr.

Parameters

Returns

void

consume

consume: () => boolean;

Defined in: lib/clipboard-sync.js:283

Whether the next payload is the fetch reply.

Returns

boolean

LocalClipboardSender

Defined in: lib/clipboard-sync.js:331

Properties

readAndSend

readAndSend: () => Promise<void>;

Defined in: lib/clipboard-sync.js:332

Reads the local clipboard and pushes any content to the server.

Returns

Promise<void>

sendExplicit

sendExplicit: (data, mime?, onSkip?) => Promise<void>;

Defined in: lib/clipboard-sync.js:334

Pushes content the user named, outranking a concurrent readAndSend.

Parameters

Returns

Promise<void>

maybeInitial

maybeInitial: () => Promise<void>;

Defined in: lib/clipboard-sync.js:336

The connect-time one-shot send.

Returns

Promise<void>

getSendInFlight

getSendInFlight: () => Promise<void>;

Defined in: lib/clipboard-sync.js:337

The send the paste-ordering hold awaits, or null.

Returns

Promise<void>

DeferredClipboardWriter

Defined in: lib/clipboard-sync.js:492

Properties

write

write: (attempt, callbacks?) => Promise<boolean>;

Defined in: lib/clipboard-sync.js:493

Runs an async clipboard write now, stashing it for the next gesture on an activation rejection.

Parameters

Returns

Promise<boolean>

flush

flush: () => void;

Defined in: lib/clipboard-sync.js:496

Retries the stashed write.

Returns

void

getInFlight

getInFlight: () => Promise<boolean>;

Defined in: lib/clipboard-sync.js:497

The most recent attempt, immediate or flushed, or null.

Returns

Promise<boolean>

ClipboardSync

Defined in: lib/clipboard-sync.js:608

Properties

sig

sig: (data, mime?) => string;

Defined in: lib/clipboard-sync.js:609

Content signature.

Parameters

Returns

string

shouldSend

shouldSend: (data, mime?) => boolean;

Defined in: lib/clipboard-sync.js:611

Change-only gate.

Parameters

Returns

boolean

markSynced

markSynced: (data, mime?) => void;

Defined in: lib/clipboard-sync.js:613

Records content as synced, on transfer success.

Parameters

Returns

void

resolveServer

resolveServer: (text?, blob?, mime?, bytes?) => void;

Defined in: lib/clipboard-sync.js:615

Caches fresh server data and settles pending requests.

Parameters

Returns

void

captureLocalImageSig

captureLocalImageSig: () => Promise<void>;

Defined in: lib/clipboard-sync.js:617

Records the browser's re-encoded form of the image just written locally, digesting it through the worker where the caller supplied one.

Returns

Promise<void>

request

request: (wantBinary) => Promise<string | Blob>;

Defined in: lib/clipboard-sync.js:620

Requests the server clipboard.

Parameters

Returns

Promise<string | Blob>

copyViaExecCommand

copyViaExecCommand: (textPromise) => Promise<void>;

Defined in: lib/clipboard-sync.js:622

Last-resort copy through execCommand.

Parameters

Returns

Promise<void>

lastText

lastText: string;

Defined in: lib/clipboard-sync.js:624

lastBlob

lastBlob: Blob;

Defined in: lib/clipboard-sync.js:625

lastMime

lastMime: string;

Defined in: lib/clipboard-sync.js:626

Type Aliases

LocalClipboardContent

type LocalClipboardContent = 
  | {
  kind: "text";
  text: string;
}
  | {
  kind: "image";
  blob: Blob;
  mime: string;
};

Defined in: lib/clipboard-sync.js:25

Type Parameters

Variables

CLIPBOARD_FLAVOURS_MIME

const CLIPBOARD_FLAVOURS_MIME: "application/x-selkies-clipboard-flavours" = 'application/x-selkies-clipboard-flavours';

Defined in: lib/clipboard-sync.js:116

Wire type for a copy carrying more than one flavour: the markup and the plain text its source wrote for it, as a JSON object of mime to content. It never reaches a clipboard itself; the flavours inside it do.

CLIPBOARD_PREVIEW_LIMIT

const CLIPBOARD_PREVIEW_LIMIT: number;

Defined in: lib/clipboard-sync.js:584

Longest server clipboard text the dashboards are shown, in characters.

Functions

digestedPayload()

function digestedPayload(byteLength, hash): object;

Defined in: lib/clipboard-sync.js:40

A payload the clipboard worker has already digested, standing in for its bytes wherever a signature is taken.

The worker walks every byte of a clipboard payload anyway, to decode or encode it, and digests it on the way through; passing the result here is what keeps the page from running the same per-byte loop over a payload of any size, several times per transfer.

Parameters

Returns

object

byteLength

byteLength: number;

hash

hash: number;

reencodeBlobAsPng()

function reencodeBlobAsPng(blob): Promise<Blob>;

Defined in: lib/clipboard-sync.js:54

Re-encodes a raster blob as PNG.

Chromium's async clipboard accepts only image/png on write, but a source may offer only JPEG, BMP or WebP, so the blob is decoded with the browser's own decoders and re-encoded first.

Parameters

Returns

Promise<Blob>

The PNG.

Throws

When the blob is undecodable (a dimensionless SVG) or the encode fails.

localClipboardBlocker()

function localClipboardBlocker(): string;

Defined in: lib/clipboard-sync.js:78

Why the browser cannot be asked to write the local clipboard, or null when it can.

Both engines expose navigator.clipboard in a secure context only, so a deployment served over http:// on anything but localhost has no clipboard API at all: a server image then lands nowhere, and saying so is the difference between a bug report and a certificate.

Returns

string

The reason, ready to show.

writeImageToLocalClipboard()

function writeImageToLocalClipboard(
   blob, 
   mime, 
   toPng
): Promise<void>;

Defined in: lib/clipboard-sync.js:100

Writes a server image to the local clipboard, PNG-normalized.

The conversion is handed to toPng when the caller has a worker to run it on, since decoding and re-encoding a large image costs the better part of a second on the thread that also presents video and dispatches input. The ClipboardItem takes the promise rather than the finished blob, so the write is issued while the gesture that permits it is still current however long the encode runs.

Parameters

Returns

Promise<void>

Throws

When the type is undecodable or the clipboard write fails.

packClipboardFlavours()

function packClipboardFlavours(__namedParameters): ArrayBuffer;

Defined in: lib/clipboard-sync.js:119

The wire payload for one copy's flavours.

Parameters

Returns

ArrayBuffer

unpackClipboardFlavours()

function unpackClipboardFlavours(bytes): object;

Defined in: lib/clipboard-sync.js:126

The flavours a wire payload carries, as {html, text}.

Parameters

Returns

object

html

html: any;

text

text: any;

clipboardItemForFlavours()

function clipboardItemForFlavours(__namedParameters): ClipboardItem;

Defined in: lib/clipboard-sync.js:136

One copy's flavours as a single clipboard item, so pasting into a rich editor takes the markup and pasting into a plain field takes the text the session itself held rather than a rendering of the markup.

Parameters

Returns

ClipboardItem

writeFlavoursToLocalClipboard()

function writeFlavoursToLocalClipboard(flavours): Promise<void>;

Defined in: lib/clipboard-sync.js:143

The same flavours, written to the local clipboard.

Parameters

Returns

Promise<void>

readLocalClipboard()

function readLocalClipboard(binaryEnabled): Promise<LocalClipboardContent>;

Defined in: lib/clipboard-sync.js:157

Reads the local clipboard for the focus and gesture send path.

Chromium's read()/getType() throw DataError on large text and some images while readText() still returns the text, so every such failure falls back to it rather than dropping the sync.

Parameters

Returns

Promise<LocalClipboardContent>

The content, or null when empty.

Throws

Only genuinely unexpected errors, for the caller to log.

createMultipartClipboardState()

function createMultipartClipboardState(openStream): MultipartClipboardState;

Defined in: lib/clipboard-sync.js:227

Multipart server-to-client clipboard download state.

Chunks go straight to the worker as they arrive and the decoded byte count is tracked from their base64 lengths, so a multi-MB clipboard is never held on the main thread, let alone joined into one string there and copied again into the message carrying it off. A truncated stream must never be delivered as content: callers compare receivedSize against totalSize before finishing, or the decoded byte length after, and discard on a mismatch.

Parameters

Returns

MultipartClipboardState

createTaggedClipboardFetch()

function createTaggedClipboardFetch(): TaggedClipboardFetch;

Defined in: lib/clipboard-sync.js:296

Tracker for the connect-time cache-only clipboard fetch (cr).

The reply must populate the sync cache and preview but never be written to the local clipboard, which would clobber whatever the user copied just before connecting. A tagging server marks the answering payload deterministically; for a server that never tags, a short timed window stands in, so a dropped reply cannot swallow a later genuine push.

Returns

TaggedClipboardFetch

createLocalClipboardSender()

function createLocalClipboardSender(hooks): LocalClipboardSender;

Defined in: lib/clipboard-sync.js:372

Focus and gesture driven local-to-server clipboard sync.

readAndSend is serialized so the paste-ordering hold can hold Ctrl/Cmd+V until the send settles. maybeInitial covers a focused Chromium tab, which gets no focus event after connect and would otherwise leave the server on its stale clipboard until the first alt-tab; it runs only when clipboard read is already granted, since it must never raise a prompt at load.

sendExplicit carries the dashboard's own pushes -- the clipboard box and the image upload -- and outranks a read while it runs and briefly after: choosing a file blurs the page and refocuses it, and the read that refocus fires would put the local clipboard straight back over the upload. It reads a Blob itself, so the push is on record from the call rather than from whenever its bytes arrive; a copy made later reaches the session on the next focus or paste.

Parameters

Returns

LocalClipboardSender

explicitHasPrecedence()

function explicitHasPrecedence(): boolean;

Defined in: lib/clipboard-sync.js:389

Whether a push the user asked for is still the session's latest word.

Returns

boolean

asSendInFlight()

function asSendInFlight(work): Promise<void>;

Defined in: lib/clipboard-sync.js:395

Runs work as the send the paste-ordering hold waits on.

Parameters

Returns

Promise<void>

readAndSend()

function readAndSend(): Promise<void>;

Defined in: lib/clipboard-sync.js:413

A server push still settling through the deferred writer must land before this read: reading around the flush returns the pre-push content, which then reads as a change and bounces the stale value back to the server.

Returns

Promise<void>

sendExplicit()

function sendExplicit(
   data, 
   mime, 
   onSkip
): Promise<void>;

Defined in: lib/clipboard-sync.js:463

Pushes content the user named. A Blob is read here, so the push counts from this call rather than from whenever its bytes arrive.

Parameters

Returns

Promise<void>

createDeferredClipboardWriter()

function createDeferredClipboardWriter(): DeferredClipboardWriter;

Defined in: lib/clipboard-sync.js:520

Deferred local-clipboard writer for server pushes.

Firefox and WebKit reject navigator.clipboard writes outside a transient user activation, and a server push handler never has one, so on an activation or focus rejection the write is stashed and retried on the next real gesture instead of being lost. Only the newest pending write is kept, since the clipboard is last-value-wins: a monotonic sequence lets a failed newer write replace an older stash while a flushed stash that fails again can never clobber a write that arrived during its attempt. The paste-ordering hold awaits the in-flight attempt so a server-to-client write lands before a paste reads the local clipboard; otherwise the stash flushes on the paste's own keydown and lands just after the read, and the first paste is one behind. The flush rides keydown and pointerdown, which carry a user activation, and focus and visibilitychange, which land the write the instant Chromium accepts it again (it rejects writes from an unfocused document), well before the user's next paste.

Returns

DeferredClipboardWriter

attemptOnce()

function attemptOnce(w): Promise<boolean>;

Defined in: lib/clipboard-sync.js:544

Runs one write. An activation rejection (a synthetic event, or a blurred tab) stashes it for the next gesture unless something newer replaced it; any other error reaches onFailure.

The attempt is started inside a promise chain so that a caller passing a plain expression -- navigator.clipboard.write(...), which throws outright where the browser exposes no clipboard -- fails the same way an async one does, instead of throwing past onFailure.

Parameters

Returns

Promise<boolean>

write()

function write(attempt, __namedParameters?): Promise<boolean>;

Defined in: lib/clipboard-sync.js:574

Runs attempt now; on an activation or focus rejection queues it for the next gesture. onSuccess fires whenever the write eventually lands, onFailure only for non-activation errors.

Parameters

Returns

Promise<boolean>

clipboardPreviewMessage()

function clipboardPreviewMessage(text): object;

Defined in: lib/clipboard-sync.js:597

The clipboardContentUpdate message carrying server clipboard text to the dashboards.

A multi-MB payload structured-clones through postMessage and lands in a controlled textarea, freezing the page, while the UI only needs a bounded preview. The truncated flag tells the dashboard to render it read-only so a blur cannot echo the cut-down text back over the real server clipboard.

Parameters

Returns

object

type

type: string;

text

text: string;

truncated

truncated: boolean;

totalLength

totalLength: number;

createClipboardSync()

function createClipboardSync(hooks): ClipboardSync;

Defined in: lib/clipboard-sync.js:652

Server-clipboard cache, change-only signature and the Ctrl/Cmd+C request queue with its one-behind guard.

The server reads its clipboard the instant REQUEST_CLIPBOARD arrives, racing ahead of the application writing the new selection, so a request stays open until an incoming value differs from the value cached when it was made. The wire protocol carries no request id, so any server push can settle the oldest pending request; the timeout plus the cache bound the impact.

Exactly one value is current at a time, the latest synced in either direction: remembering older signatures would suppress legitimately re-copying content copied before an intervening value. Beside it lives the browser's re-encoded form of the latest inbound image, since writing a pushed image recompresses it and the focus read-back would otherwise read as new and echo once; it follows the synced signature's lifetime.

Parameters

Returns

ClipboardSync

sigOf()

function sigOf(data, mime): object;

Defined in: lib/clipboard-sync.js:677

Both signature forms of a value. Text and byte-backed values are content-hashed so two distinct payloads of equal size still differ; a bare Blob, whose bytes are not in hand, gets the size-only legacy form, which also rides along with hashed binary signatures so the two can be cross-matched.

Parameters

Returns

object

full

full: string;

legacy

legacy: string;

shouldSend()

function shouldSend(data, mime): boolean;

Defined in: lib/clipboard-sync.js:712

Change-only gate: true while this content and mime differ from the last synced value. Read-only: the caller marks the content synced through markSynced only after the transfer completes, so a failed transfer never permanently suppresses re-sending the same content. The legacy compare suppresses echoes of content whose receive-side signature was stored without bytes.

Parameters

Returns

boolean

markSynced()

function markSynced(data, mime): void;

Defined in: lib/clipboard-sync.js:719

Records content as synced; called on transfer success.

Parameters

Returns

void

resolveServer()

function resolveServer(
   text, 
   blob, 
   mime, 
   bytes
): void;

Defined in: lib/clipboard-sync.js:729

Caches fresh server data and settles pending requests through the one-behind guard. bytes, when the receive path has them, make the stored signature content-hashed so it matches what shouldSend computes for the same data.

Parameters

Returns

void

captureLocalImageSig()

function captureLocalImageSig(): Promise<void>;

Defined in: lib/clipboard-sync.js:760

After a server image is written to the local clipboard, records the browser's re-encoded representation so the next focus read is recognized as the same content instead of echoed back. Needs clipboard read permission and focus and is silently skipped otherwise; the worst case is one redundant round trip, never a loop. The capture is anchored to the synced signature at entry: a sync in either direction landing mid-read makes it stale, and storing it would suppress a legitimate later copy.

Returns

Promise<void>

request()

function request(wantBinary): Promise<string | Blob>;

Defined in: lib/clipboard-sync.js:796

Requests the server clipboard and resolves with the next fresh value.

After two seconds the request settles so the ClipboardItem promise, and the browser's transient-activation window, can never hang: with a cached value that differs from the baseline recorded at request time it resolves, otherwise it rejects, since resolving with the baseline-equal cache would settle the copy with stale content exactly when the session-start cache is empty or stale.

Parameters

Returns

Promise<string | Blob>

copyViaExecCommand()

function copyViaExecCommand(textPromise): Promise<void>;

Defined in: lib/clipboard-sync.js:831

Last-resort copy for browsers that reject navigator.clipboard.write (older Firefox and Safari): execCommand('copy') from a hidden textarea. Awaiting the promise first can outlive the Ctrl/Cmd+C transient activation, hence last resort. A rejected request or an empty value writes nothing: either would clobber the user's local clipboard with pre-copy content.

Parameters

Returns

Promise<void>

createClipboardGestures()

function createClipboardGestures(hooks): object;

Defined in: lib/clipboard-sync.js:910

Keyboard and paste gesture wiring for clipboard sync.

Owns the three window-level pieces around the per-transport read and send functions:

• Paste-ordering hold: a Ctrl/Cmd+V arriving while the local clipboard is still being read or sent would depart the ordered channel before the clipboard content and paste the previous value on the server. The chord's key events are swallowed, held until the send flushes (bounded), then replayed in order for the input stack.
• Non-Chromium Ctrl/Cmd+C: Safari and Firefox reject navigator.clipboard from focus and message handlers, which have no transient activation, so the server clipboard is written inside the copy gesture through a ClipboardItem whose blob is a Promise, with execCommand('copy') as last resort.
• Non-Chromium paste-to-server: driven by the paste event's synchronous clipboardData. There is deliberately no Ctrl/Cmd+V navigator.clipboard read: WebKit rejects it from keydown, Firefox re-raises its paste prompt, and it would double-send next to the paste event.

Gestures in page form fields (the settings UI) are left alone; the stream's overlay input is exempt. Consumed gestures are never preventDefaulted: the chord must still reach the remote session.

Parameters

Returns

object

Listener registration.

wire

wire: () => void;

Returns

void

unwire

unwire: () => void;

Returns

void

dropHeldPasteKeydowns()

function dropHeldPasteKeydowns(): void;

Defined in: lib/clipboard-sync.js:949

The in-flight transfer failed or never settled: injecting the held V now would paste stale content, so the held keydowns are dropped. The swallowed keyups (V and the chord's modifiers) are still replayed, as losing a modifier keyup would leave it stuck server-side.

Returns

void

holdPasteWhileClipboardInFlight()

function holdPasteWhileClipboardInFlight(ev): void;

Defined in: lib/clipboard-sync.js:972

Capture-phase key listener implementing the paste-ordering hold.

A paste chord is held while a send is in flight or a server-to-client local-clipboard write is still landing, since the paste would otherwise read the old value; any KeyV event is held while a replay is queued, so its keyup cannot overtake the held keydown, and so are the chord's modifier keyups, since a Ctrl keyup overtaking the replayed V would break the chord server-side and type a literal v. The hold waits for the current read/send and deferred write, then re-checks, as a follow-on transfer may have started meanwhile (the deferred write flushed by this very keydown); replay happens only once nothing is pending, and on failure or an expired bound the paste is dropped rather than injected with stale content.

Parameters

Returns

void

onCopyKeydown()

function onCopyKeydown(event): void;

Defined in: lib/clipboard-sync.js:1018

Non-Chromium Ctrl/Cmd+C: writes the server clipboard inside the gesture.

Only text/plain is advertised: a Ctrl/Cmd+C cannot synchronously know whether the server's current clipboard is an image, and a stale cached MIME type would build a malformed ClipboardItem. Server images are delivered by the push handler instead. Autorepeat is ignored so it cannot spam REQUEST_CLIPBOARD.

Parameters

Returns

void

onPaste()

function onPaste(event): void;

Defined in: lib/clipboard-sync.js:1052

Non-Chromium paste-to-server from the event's synchronous clipboard data, preferring an image when binary clipboard is on and the payload carries one.

Parameters

Returns

void

wire()

function wire(): void;

Defined in: lib/clipboard-sync.js:1076

Registers the listeners; called before input attaches so the hold runs first.

Returns

void

unwire()

function unwire(): void;

Defined in: lib/clipboard-sync.js:1086

Removes the listeners wire registered.

Returns

void