@wcstack/eyedropper 1.20.0 → 1.21.1

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/README.ja.md CHANGED
@@ -118,9 +118,14 @@ npm install @wcstack/eyedropper
118
118
  | `loading` | `wcs-eyedropper:loading-changed` | スポイトカーソルが有効な間(`open()` 呼び出しが進行中)は `true`。 |
119
119
  | `error` | `wcs-eyedropper:error` | 真のプラットフォーム障害(ピッカーがキャンセルされた場合を除く全て)。まだ失敗が無い場合、または次の `open()` 呼び出しでリセットされた後は `null`。 |
120
120
  | `cancelled` | `wcs-eyedropper:cancelled-changed` | 選択が完了しなかった場合に `true` — ユーザーが Escape を押した場合と、呼び出し元が `abort()` を呼んだ場合の両方。どちらも同じ `AbortError` として現れ、区別されない。 |
121
+ | `errorInfo` | `wcs-eyedropper:error-info-changed` | serializable な失敗 taxonomy(安定 `code` / `phase` / `recoverable`)、または `null`。追加的で `error` の shape は不変。`code` は unsupported なら `capability-missing`、真の失敗なら `pick-failed`。キャンセルは `cancelled` であり `errorInfo` ではない。 |
121
122
 
122
123
  `cancelled` と `error` はどちらも、次の `open()` 呼び出しの **開始時** にリセットされる(`false` / `null`)ため、前回の呼び出しの古い結果が次回の結果に残り続けることはありません。
123
124
 
125
+ **並行制御。** `EyeDropper.open()` は `AbortSignal` を受けるため、`<wcs-eyedropper>` は共有
126
+ io-core lane を `latest` policy で用いる(`<wcs-fetch>` と同様): 新しい `open()` が進行中の
127
+ 呼び出しを **supersede**(abort)し、`abort()` コマンドは実行中の選択をキャンセルする。
128
+
124
129
  ## コマンド
125
130
 
126
131
  | コマンド | 非同期 | 説明 |
package/README.md CHANGED
@@ -118,9 +118,15 @@ npm install @wcstack/eyedropper
118
118
  | `loading` | `wcs-eyedropper:loading-changed` | `true` while the eyedropper cursor is active (an `open()` call is in flight). |
119
119
  | `error` | `wcs-eyedropper:error` | A true platform failure (anything other than the picker being dismissed). `null` when there has been no failure yet, or after the next `open()` call resets it. |
120
120
  | `cancelled` | `wcs-eyedropper:cancelled-changed` | `true` when the pick did not complete — either the user pressed Escape, or the caller invoked `abort()`. Both surface as the same `AbortError` and are not distinguished. |
121
+ | `errorInfo` | `wcs-eyedropper:error-info-changed` | Serializable failure taxonomy (stable `code` / `phase` / `recoverable`), or `null`. Additive — the `error` shape is unchanged; `code` is `capability-missing` when unsupported or `pick-failed` on a genuine failure. Cancellation is `cancelled`, not `errorInfo`. |
121
122
 
122
123
  `cancelled` and `error` are both reset (`false` / `null`) at the **start** of the next `open()` call, so a stale outcome from a previous call never lingers into the next one's result.
123
124
 
125
+ **Concurrency.** `EyeDropper.open()` accepts an `AbortSignal`, so `<wcs-eyedropper>`
126
+ runs its calls through the shared io-core lane with the `latest` policy (like
127
+ `<wcs-fetch>`): a new `open()` **supersedes** the in-flight one (aborting it), and
128
+ the `abort()` command cancels the active pick.
129
+
124
130
  ## Commands
125
131
 
126
132
  | Command | Async | Description |
package/dist/index.d.ts CHANGED
@@ -1,3 +1,56 @@
1
+ /**
2
+ * platform-capability.ts
3
+ *
4
+ * Phase 6(docs/architecture-hardening/09-remediation-design.md §7.2 /
5
+ * 07-browser-capability-variance.md)の browser capability 判定と error taxonomy の
6
+ * 汎用プリミティブ。node 固有の capability registry / error code は各パッケージが
7
+ * 別ファイルで宣言し、この汎用層(型 + assess 機構)を import する。
8
+ *
9
+ * 原則:
10
+ * - feature detection は境界(利用直前)で行う。module 評価時に browser global を
11
+ * 参照しない(SSR / worker で import が失敗しない)。
12
+ * - capability ID(`web.fetch` 等)は文字列を global property path として eval せず、
13
+ * registry が ID ごとに副作用のない presence probe を対応付ける。
14
+ * - availability / permission / readiness / activity / operation error を 1 つの
15
+ * `ready / unsupported / error` enum に畳まない。required 欠如は開始しない、
16
+ * optional 欠如は宣言済み fallback で readiness を `degraded` にする。
17
+ *
18
+ * 配置: 本ファイルは /io-core/ の単一正典であり、scripts/sync-io-core.mjs が
19
+ * 各 IO ノードの src/core/ へ生成コピー (AUTO-GENERATED, 編集禁止) を配布する。
20
+ * `protocol/wcBindable.ts` と同じ copy-distribution 方式で、ランタイム依存を導入せず
21
+ * 各パッケージのバンドルへ inline される (zero-runtime-dep / 自己完結 CDN を維持)。
22
+ * 編集はこの正典に対して行い、`node scripts/sync-io-core.mjs` で再配布する。
23
+ *
24
+ * pure(module 評価時に browser global 非参照)。
25
+ */
26
+ type Availability = "available" | "missing" | "unknown";
27
+ type PermissionState = "granted" | "denied" | "prompt" | "not-applicable" | "unknown";
28
+ type Readiness = "idle" | "ready" | "degraded";
29
+ type Activity = "inactive" | "active";
30
+ type PreconditionState = "satisfied" | "required" | "not-applicable";
31
+ /** operation error の phase(taxonomy)。 */
32
+ type WcsIoErrorPhase = "probe" | "start" | "execute" | "decode" | "commit" | "dispose";
33
+ /** serializable な error info(non-cloneable な cause とは分離。DevTools / remote へは info のみ)。 */
34
+ interface WcsIoErrorInfo {
35
+ readonly code: string;
36
+ readonly phase: WcsIoErrorPhase;
37
+ readonly recoverable: boolean;
38
+ readonly capabilityId?: string;
39
+ readonly message: string;
40
+ }
41
+ interface PlatformAssessment {
42
+ readonly availability: ReadonlyMap<string, Availability>;
43
+ readonly permission: PermissionState;
44
+ readonly readiness: Readiness;
45
+ readonly activity: Activity;
46
+ readonly preconditions: {
47
+ readonly secureContext: PreconditionState;
48
+ readonly userActivation: PreconditionState;
49
+ };
50
+ readonly epoch: number;
51
+ readonly lastError?: WcsIoErrorInfo;
52
+ }
53
+
1
54
  interface IWcBindableProperty {
2
55
  readonly name: string;
3
56
  readonly event: string;
@@ -13,7 +66,8 @@ interface IWcBindableCommand {
13
66
  }
14
67
  interface IWcBindable {
15
68
  readonly protocol: "wc-bindable";
16
- readonly version: 1;
69
+ /** Integer protocol version. All versions >= 1 are core-compatible. */
70
+ readonly version: number;
17
71
  readonly properties: readonly IWcBindableProperty[];
18
72
  readonly inputs?: readonly IWcBindableInput[];
19
73
  readonly commands?: readonly IWcBindableCommand[];
@@ -55,6 +109,7 @@ interface WcsEyedropperCoreValues {
55
109
  loading: boolean;
56
110
  error: any;
57
111
  cancelled: boolean;
112
+ errorInfo: WcsIoErrorInfo | null;
58
113
  }
59
114
  /**
60
115
  * Value types for the Shell (`<wcs-eyedropper>`) — identical observable
@@ -71,34 +126,29 @@ declare function getConfig(): IConfig;
71
126
  * Headless EyeDropper primitive. A thin, framework-agnostic wrapper around
72
127
  * `new EyeDropper().open(options)` exposed through the wc-bindable protocol.
73
128
  *
74
- * This is a simplified derivative of `FetchCore._doFetch`
75
- * (docs/eyedropper-tag-design.md §1, docs/web-share-tag-design.md §2): it
76
- * keeps the single `_gen` generation guard, the same-value-guarded private
77
- * setters, and the never-throw try/catch wrapper — the same skeleton
78
- * `@wcstack/share`'s `ShareCore` uses.
79
- *
80
- * Unlike `ShareCore`, this Core **does** restore `AbortController`/`abort()`
81
- * (docs/eyedropper-tag-design.md §2): `EyeDropper.open()` accepts a `{signal}`
82
- * option, so — unlike Web Share — a caller has a real platform mechanism to
83
- * cancel an in-flight color pick. The shape mirrors `FetchCore.abort()`
84
- * (packages/fetch/src/core/FetchCore.ts:159-164) including the identity check
85
- * on the locally-held `AbortController` in the `finally` block
86
- * (packages/fetch/src/core/FetchCore.ts:312-314), so a fast abort()→open()
87
- * sequence never lets a stale controller null out the new call's controller.
129
+ * Concurrency is owned by the shared `OperationLane` (io-core) with the `latest`
130
+ * policy: `EyeDropper.open()` accepts a `{signal}`, so — unlike Web Share / Contact
131
+ * Picker (exhaust) — a caller has a real platform mechanism to cancel an in-flight
132
+ * pick. A new `open()` supersedes the previous one (the lane aborts its
133
+ * AbortController and the superseded completion fails the terminal CAS), and the
134
+ * `abort()` command aborts the active pick. This replaces the ad-hoc `_gen` +
135
+ * `_abortController` + finally-block identity check with the same lane FetchCore
136
+ * uses; the lane owns the per-attempt AbortController and the commit guard.
88
137
  *
89
138
  * Both the user dismissing the picker with Escape and the caller invoking
90
- * `abort()` reject `open()` with the same `AbortError` — both land on
91
- * `cancelled` without distinction (docs/eyedropper-tag-design.md §2).
139
+ * `abort()` reject `open()` with the same `AbortError` — both land on `cancelled`
140
+ * without distinction (docs/eyedropper-tag-design.md §2).
92
141
  */
93
142
  declare class EyedropperCore extends EventTarget {
94
143
  static wcBindable: IWcBindable;
144
+ private static readonly REQUIRED_CAPABILITIES;
95
145
  private _target;
96
146
  private _value;
97
147
  private _loading;
98
148
  private _error;
99
149
  private _cancelled;
100
- private _abortController;
101
- private _gen;
150
+ private _errorInfo;
151
+ private _lane;
102
152
  private _ready;
103
153
  constructor(target?: EventTarget);
104
154
  get ready(): Promise<void>;
@@ -106,18 +156,39 @@ declare class EyedropperCore extends EventTarget {
106
156
  get loading(): boolean;
107
157
  get error(): any;
108
158
  get cancelled(): boolean;
159
+ /**
160
+ * The last failure's serializable `WcsIoErrorInfo` (stable `code` / `phase` /
161
+ * `recoverable` / `capabilityId`), or null. Exposed as an additive wc-bindable
162
+ * property (event `wcs-eyedropper:error-info-changed`); the existing `error`
163
+ * property/event are unchanged. Note user/abort cancellation is `cancelled`, not
164
+ * `errorInfo`.
165
+ */
166
+ get errorInfo(): WcsIoErrorInfo | null;
167
+ /**
168
+ * Whether the required platform capability (`web.eyedropper`) is available right
169
+ * now — decided by call-time feature detection, not User-Agent. Core-only,
170
+ * additive.
171
+ */
172
+ get supported(): boolean;
173
+ /**
174
+ * Full platform assessment (availability / readiness / preconditions), probed at
175
+ * call time. Core-only opt-in dev / sidecar view.
176
+ */
177
+ get platformAssessment(): PlatformAssessment;
109
178
  observe(): Promise<void>;
110
179
  dispose(): void;
180
+ private _commitStep;
111
181
  private _setLoading;
112
182
  private _setValue;
113
183
  private _setError;
114
184
  private _setCancelled;
115
- private _api;
185
+ private _setErrorInfo;
186
+ private _commitErrorInfo;
116
187
  /**
117
- * Cancels an in-flight `open()` call, if any. A no-op when no open() is in
118
- * flight (no AbortController has been created yet, or the previous one has
119
- * already settled) — mirrors `FetchCore.abort()`
120
- * (packages/fetch/src/core/FetchCore.ts:159-164).
188
+ * Cancels an in-flight `open()` call, if any (a no-op otherwise). Aborts the
189
+ * lane's active AbortController — the in-flight open() then rejects with
190
+ * `AbortError` and lands on `cancelled`. The epoch is not advanced, so the
191
+ * aborted operation keeps eligibility to claim the `aborted` terminal.
121
192
  */
122
193
  abort(): void;
123
194
  open(): Promise<WcsEyedropperData | null>;
@@ -145,6 +216,7 @@ declare class WcsEyedropper extends HTMLElement {
145
216
  get loading(): boolean;
146
217
  get error(): any;
147
218
  get cancelled(): boolean;
219
+ get errorInfo(): WcsIoErrorInfo | null;
148
220
  get connectedCallbackPromise(): Promise<void>;
149
221
  open(): Promise<WcsEyedropperData | null>;
150
222
  abort(): void;
@@ -152,5 +224,19 @@ declare class WcsEyedropper extends HTMLElement {
152
224
  disconnectedCallback(): void;
153
225
  }
154
226
 
155
- export { EyedropperCore, WcsEyedropper, bootstrapEyedropper, getConfig };
156
- export type { IWritableConfig, IWritableTagNames, WcsEyedropperCoreValues, WcsEyedropperData, WcsEyedropperValues };
227
+ /**
228
+ * eyedropperCapabilities.ts
229
+ *
230
+ * EyeDropper node 固有の capability registry と error code。汎用の assess 機構・型は
231
+ * `./platformCapability.js`(/io-core/ から copy-distribution される生成ファイル)から
232
+ * import する。node 固有の宣言はこのハンドライトファイルに置き、生成コピーとは分離する。
233
+ */
234
+
235
+ /** 安定した eyedropper error code(taxonomy)。値は公開キーとして固定。 */
236
+ declare const WCS_EYEDROPPER_ERROR_CODE: {
237
+ readonly CapabilityMissing: "capability-missing";
238
+ readonly PickFailed: "pick-failed";
239
+ };
240
+
241
+ export { EyedropperCore, WCS_EYEDROPPER_ERROR_CODE, WcsEyedropper, bootstrapEyedropper, getConfig };
242
+ export type { IWritableConfig, IWritableTagNames, WcsEyedropperCoreValues, WcsEyedropperData, WcsEyedropperValues, WcsIoErrorInfo, WcsIoErrorPhase };