svelte-kit-vice/src/arts/clipboard/README.md

clipboard

arts/clipboard contains ActiveClipboard, a small service for writing text to the clipboard without components reading navigator.clipboard directly.

Ownership

• ActiveApp can declare it with defineActiveClipboard(...).
• Standalone ActiveUix creates it by default and lets you disable it with clipboard:false.
• Attached ActiveUix creates no substitutes: if a layer asks for uix.clipboard and app.clipboard does not exist, it fails with an explicit error.
• ActiveDom does not own this capability. The clipboard is an environment capability, not a visual mutation of DOM nodes.

Direct use

import { createActiveClipboard } from '$clipboard';

const clipboard = createActiveClipboard();

await clipboard.writeText('Copied text');
clipboard.dispose();

Injection

Tests, SSR shells and apps with their own permissions can inject a writer:

const clipboard = createActiveClipboard({
	writer: {
		async writeText(text) {
			await customClipboardApi.write(text);
		}
	}
});

With no writer and no navigator.clipboard.writeText, writeText(...) throws ActiveClipboardUnavailableError.

ActiveApp

import { createActiveApp } from '$active-app';
import { defineActiveClipboard } from '$active-app/service-factories';

const App = createActiveApp({
	services: {
		clipboard: defineActiveClipboard()
	}
});

await App.clipboard.writeText('Copied text');

UIX / Soma

Soma components that need to write to the clipboard consume uix.clipboard through their layer scope. They do not import $clipboard or read navigator directly.