macotron.clipboard

Read and write the general pasteboard, keep a short history of what was copied, and make Command-V paste plain text.

// Copy the frontmost window's title.
const win = macotron.window.focused();
if (win) macotron.clipboard.set(win.title);

Reading and writing

text(): string

The pasteboard's plain text, or "" when it holds none.

set(text: string): void

Replaces the pasteboard contents with text.

setImage(base64: string): boolean

Puts a PNG on the pasteboard. Accepts raw base64 or a data:image/png;base64,… URL. Returns false when the data does not decode.

clear(): void

Empties the pasteboard.

types(): string[]

The type identifiers on the pasteboard right now, such as public.utf8-plain-text or public.png.

data(uti: string): string | null

The raw bytes for one type, base64-encoded, or null when that type is absent.

History

Macotron records history only while some plugin wants it: after the first call to history(), or while a plugin listens for clipboard:changed. It keeps the newest 50 entries from the last 24 hours, in memory only, so history is gone after a restart.

Password managers mark secrets with org.nspasteboard.ConcealedType or TransientType. Copies that carry either type are never recorded.

history(): Array<{ id, text, kind, ts }>

Newest first. kind is "text" or "image". For an image, text holds the PNG as base64. ts is milliseconds since 1970.

paste(id: string): boolean

Puts a history entry back on the pasteboard. It does not press Command-V; send that with macotron.event if you need it. Returns false for an unknown id.

remove(id: string): boolean

Deletes one entry. Returns false when the id was not in the history.

clearHistory(): void

Deletes every entry.

Plain-text paste

setPastePlain(on: boolean): boolean

While on, Command-V in any app pastes only the plain text, dropping fonts, colors, and links. Returns false when the keyboard tap cannot be installed, which usually means Macotron lacks Accessibility permission.

isPastePlain(): boolean

Whether plain-text paste is on.

Events

clipboard:changed

Fires when the pasteboard changes, checked twice a second. The payload is { changeCount, types }; read the contents with text() or data().

macotron.on("clipboard:changed", ({ types }) => {
  if (types.includes("public.png")) macotron.notify.toast("Copied an image");
});