@wcstack/clipboard 1.15.0 → 1.16.0

package/README.ja.md

@@ -138,6 +138,17 @@ DOM の autoTrigger は書き込み（`writeText`）のみを起動します。
 
 > DOM トリガによる `writeText` は fire-and-forget（`Promise` を await しません）ですが、決して reject しません。コピー失敗は他の書き込みと同様 `error` プロパティに現れます。autoTrigger の失敗を観測するには `error` をバインドしてください（例: `text: error.message@cb`）。
 
+> **autoTrigger は既定で有効。** 最初に接続した `<wcs-clipboard>` が document レベルの `click` リスナーを 1 つ設置します（`data-clipboardtarget` 要素のクリックで `writeText` を起動）。DOM ショートカットを使わないなら bootstrap エントリで無効化してください:
+>
+> ```js
+> import { bootstrapClipboard, getConfig } from "@wcstack/clipboard";
+> bootstrapClipboard({ autoTrigger: false });        // document クリックリスナーを設置しない
+> bootstrapClipboard({ triggerAttribute: "data-copy" }); // トリガ属性名を変更（既定: data-clipboardtarget）
+> getConfig();                                        // 実効設定（deep-frozen）を読む
+> ```
+>
+> `bootstrapClipboard()` は要素が接続される前に呼んでください。（`setConfig` は内部用。設定は `bootstrapClipboard` 経由で行います。）
+
 ## 観測可能なプロパティ（出力）
 
 | プロパティ        | イベント                                  | 説明                                                                  |
@@ -173,7 +184,7 @@ DOM の autoTrigger は書き込み（`writeText`）のみを起動します。
 ## 注意点と制約
 
 - **属性は接続時に読み取られ、監視されない。** `<wcs-clipboard>` は `observedAttributes` / `attributeChangedCallback` を実装していません。`monitor` 属性は要素の接続時に読み取られます。接続*後*に命令的にトグルしても、それだけでは監視は開始/停止しません。`startMonitor()` / `stopMonitor()` を呼ぶか、要素を再接続してください。
-- **接続時の読み取りは無い。** `<wcs-geo>` と異なり、クリップボードは接続時に自動読み取りできません（読み取りにはユーザージェスチャとパーミッションが必要）。そのため `connectedCallbackPromise` / SSR スナップショットはありません。接続時の唯一のアクションは任意の監視です。
+- **接続時の読み取りは無い。** `<wcs-geo>` と異なり、クリップボードは接続時に自動読み取りできません（読み取りにはユーザージェスチャとパーミッションが必要）。接続時のアクションは初回パーミッション照会と任意の監視です。ただし `connectedCallbackPromise`（`hasConnectedCallbackPromise = true`）は公開しており、state バインダ / SSR はこれを await して初回パーミッションスナップショットの確定を待ってからバインドできます。
 - **再接続で再購読する。** 要素を削除して再挿入すると `connectedCallback` が再度実行されるため、パーミッション追跡が復活し、`monitor` 属性を持つ要素は監視を再開します（切断時に解体するのと対称です）。監視の永続性は**属性駆動のみ**です。`monitor` 属性*なし*の要素で `startMonitor()` を使って命令的に監視を開始した場合、再接続では復元されません（属性が真実の源）。リペアレント間で監視を永続させたい場合は `monitor` 属性を付けてください。
 - **`copy` / `cut` のテキストは選択範囲から取得する。** `copy` / `cut` イベント中はクリップボードのペイロードがまだ読めない（セキュリティ上ブラウザは空文字列を返す）ため、`copied` / `cut` は `document.getSelection().toString()` — ユーザーの選択テキストを報告します。ページが `clipboardData.setData(...)` でペイロードを上書きするカスタム `copy` ハンドラを設置している場合、その上書きは `copied` / `cut` に**反映されません**。`pasted` は `event.clipboardData.getData("text/plain")` を読み取ります。
 - **無言のエラー処理（ゼロログ）。** wcstack 全体のゼロ依存・最小主義に従い、`<wcs-clipboard>` は実行時の失敗に対して一切ログ出力も throw もしません。パーミッション照会の失敗（クリップボードのパーミッション名を持たない Firefox など）は無言で `"unsupported"` にフォールバックします。read/write の失敗（パーミッション拒否・フォーカス無し・Clipboard API 欠如）は `error` プロパティ / `wcs-clipboard:error` イベントを通じてのみ表面化します — コマンドは resolve し、決して reject しません。観測・対処するには `error`（および `*Permission` プロパティ）をバインドしてください。

package/README.md

@@ -140,6 +140,17 @@ Add the `monitor` attribute to republish document `copy` / `cut` / `paste` as re
 
 > A DOM-triggered `writeText` is fire-and-forget (its `Promise` is not awaited), but it never rejects: a failed copy surfaces through the `error` property like any other write. Bind `error` (e.g. `text: error.message@cb`) to observe autoTrigger failures.
 
+> **autoTrigger is on by default.** The first `<wcs-clipboard>` to connect installs a single **document-level `click` listener** (a click on a `data-clipboardtarget` element runs `writeText`). If you don't use the DOM shortcut, opt out via the bootstrap entry:
+>
+> ```js
+> import { bootstrapClipboard, getConfig } from "@wcstack/clipboard";
+> bootstrapClipboard({ autoTrigger: false });        // no document click listener
+> bootstrapClipboard({ triggerAttribute: "data-copy" }); // rename the trigger attribute (default: data-clipboardtarget)
+> getConfig();                                        // read the effective (deep-frozen) config
+> ```
+>
+> Call `bootstrapClipboard()` before the elements connect. (`setConfig` is internal; configure through `bootstrapClipboard`.)
+
 ## Observable Properties (outputs)
 
 | Property         | Event                                    | Description                                                            |
@@ -175,7 +186,7 @@ State-driven invocation uses the command-token protocol:
 ## Notes & limitations
 
 - **Attributes are read at connect time, not observed.** `<wcs-clipboard>` does not implement `observedAttributes` / `attributeChangedCallback`. The `monitor` attribute is read when the element connects — toggling it imperatively after connect does not start/stop monitoring by itself; call `startMonitor()` / `stopMonitor()`, or re-connect the element.
-- **No connect-time read.** Unlike `<wcs-geo>`, the clipboard cannot auto-read on connect (reads need a user gesture and permission), so there is no `connectedCallbackPromise` / SSR snapshot. The only connect-time action is optional monitoring.
+- **No connect-time read.** Unlike `<wcs-geo>`, the clipboard cannot auto-read on connect (reads need a user gesture and permission); the connect-time actions are an initial permission probe and optional monitoring. It still exposes `connectedCallbackPromise` (`hasConnectedCallbackPromise = true`) — a state binder / SSR awaits it so the initial permission snapshot has settled before binding.
 - **Reconnect re-subscribes.** Removing and re-inserting the element runs `connectedCallback` again, so permission tracking is revived and a `monitor`-attribute element restarts monitoring (matching how it tears them down on disconnect). Monitoring persistence is **attribute-driven only**: if you started monitoring imperatively with `startMonitor()` on an element *without* the `monitor` attribute, a reconnect does not restore it (the attribute is the source of truth). Add the `monitor` attribute for persistent monitoring across reparents.
 - **`copy` / `cut` text comes from the selection.** During a `copy` / `cut` event the clipboard payload is not yet readable (the browser returns an empty string for security reasons), so `copied` / `cut` report `document.getSelection().toString()` — the user's selected text. If the page installs a custom `copy` handler that overrides the payload via `clipboardData.setData(...)`, that override is **not** reflected in `copied` / `cut`. `pasted` reads `event.clipboardData.getData("text/plain")`.
 - **Silent failure handling (zero-log).** Consistent with the rest of wcstack's zero-dependency, minimal philosophy, `<wcs-clipboard>` never logs or throws for runtime failures. A failed permission query (e.g. Firefox, which has no clipboard permission names) silently falls back to `"unsupported"`. Read/write failures (denied permission, no focus, missing Clipboard API) are surfaced only through the `error` property / `wcs-clipboard:error` event — the commands resolve and never reject. Bind `error` (and the `*Permission` properties) to observe and react.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wcstack/clipboard",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "description": "Declarative clipboard component for Web Components. Framework-agnostic Clipboard API primitive via wc-bindable-protocol.",
   "type": "module",
   "main": "./dist/index.esm.js",