@wcstack/contacts 1.19.1 → 1.21.0

package/README.ja.md

@@ -54,6 +54,12 @@ npm install @wcstack/contacts
 | `loading`   | `wcs-contacts:loading-changed`    | ピッカーダイアログが開いている間`true`。 |
 | `error`     | `wcs-contacts:error`              | 真のプラットフォーム失敗（`select()`が投げた`DOMException`/`Error`）、または unsupported 経路ではプレーンオブジェクト`{ message: "Contact Picker API is not supported in this browser." }`、無ければ`null`。 |
 | `cancelled` | `wcs-contacts:cancelled-changed`  | ユーザーがピッカーを閉じたら`true`（`error`とは分離）。 |
+| `errorInfo` | `wcs-contacts:error-info-changed` | serializable な失敗 taxonomy（安定 `code` / `phase` / `recoverable`）、または `null`。追加的で `error` の shape は不変。`code` は unsupported なら `capability-missing`、真の失敗なら `select-failed`。 |
+
+**並行制御。** 連絡先ピッカーはシステムに1つのモーダル面なので、`<wcs-contacts>` は共有
+io-core lane を `exhaust` policy で用いる: 1つの `select()` が進行中の間、2回目の呼び出しは
+冪等な **no-op**（2つ目のピッカーを開かず `null` を返す）となり、進行中の呼び出しの結果を
+汚さない。
 
 ## コマンド
 

package/README.md

@@ -55,6 +55,13 @@ npm install @wcstack/contacts
 | `loading`   | `wcs-contacts:loading-changed` | `true` while the picker dialog is open. |
 | `error`     | `wcs-contacts:error`           | A true platform failure (a `DOMException`/`Error` from `select()`), or the plain object `{ message: "Contact Picker API is not supported in this browser." }` on the unsupported path, or `null`. |
 | `cancelled` | `wcs-contacts:cancelled-changed` | `true` when the user dismissed the picker (kept separate from `error`). |
+| `errorInfo` | `wcs-contacts: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 `select-failed` on a genuine failure. |
+
+**Concurrency.** The contact picker is a single system-modal surface, so
+`<wcs-contacts>` runs its calls through the shared io-core lane with the `exhaust`
+policy: while one `select()` is in flight, a second call is an idempotent **no-op**
+(it returns `null` without opening a second picker), leaving the in-flight call's
+result untouched.
 
 ## Commands
 

package/dist/index.d.ts

@@ -1,3 +1,56 @@
+/**
+ * platform-capability.ts
+ *
+ * Phase 6(docs/architecture-hardening/09-remediation-design.md §7.2 /
+ * 07-browser-capability-variance.md)の browser capability 判定と error taxonomy の
+ * 汎用プリミティブ。node 固有の capability registry / error code は各パッケージが
+ * 別ファイルで宣言し、この汎用層(型 + assess 機構)を import する。
+ *
+ * 原則:
+ * - feature detection は境界(利用直前)で行う。module 評価時に browser global を
+ *   参照しない(SSR / worker で import が失敗しない)。
+ * - capability ID(`web.fetch` 等)は文字列を global property path として eval せず、
+ *   registry が ID ごとに副作用のない presence probe を対応付ける。
+ * - availability / permission / readiness / activity / operation error を 1 つの
+ *   `ready / unsupported / error` enum に畳まない。required 欠如は開始しない、
+ *   optional 欠如は宣言済み fallback で readiness を `degraded` にする。
+ *
+ * 配置: 本ファイルは /io-core/ の単一正典であり、scripts/sync-io-core.mjs が
+ * 各 IO ノードの src/core/ へ生成コピー (AUTO-GENERATED, 編集禁止) を配布する。
+ * `protocol/wcBindable.ts` と同じ copy-distribution 方式で、ランタイム依存を導入せず
+ * 各パッケージのバンドルへ inline される (zero-runtime-dep / 自己完結 CDN を維持)。
+ * 編集はこの正典に対して行い、`node scripts/sync-io-core.mjs` で再配布する。
+ *
+ * pure(module 評価時に browser global 非参照)。
+ */
+type Availability = "available" | "missing" | "unknown";
+type PermissionState = "granted" | "denied" | "prompt" | "not-applicable" | "unknown";
+type Readiness = "idle" | "ready" | "degraded";
+type Activity = "inactive" | "active";
+type PreconditionState = "satisfied" | "required" | "not-applicable";
+/** operation error の phase(taxonomy)。 */
+type WcsIoErrorPhase = "probe" | "start" | "execute" | "decode" | "commit" | "dispose";
+/** serializable な error info(non-cloneable な cause とは分離。DevTools / remote へは info のみ)。 */
+interface WcsIoErrorInfo {
+    readonly code: string;
+    readonly phase: WcsIoErrorPhase;
+    readonly recoverable: boolean;
+    readonly capabilityId?: string;
+    readonly message: string;
+}
+interface PlatformAssessment {
+    readonly availability: ReadonlyMap<string, Availability>;
+    readonly permission: PermissionState;
+    readonly readiness: Readiness;
+    readonly activity: Activity;
+    readonly preconditions: {
+        readonly secureContext: PreconditionState;
+        readonly userActivation: PreconditionState;
+    };
+    readonly epoch: number;
+    readonly lastError?: WcsIoErrorInfo;
+}
+
 interface IWcBindableProperty {
     readonly name: string;
     readonly event: string;
@@ -13,7 +66,8 @@ interface IWcBindableCommand {
 }
 interface IWcBindable {
     readonly protocol: "wc-bindable";
-    readonly version: 1;
+    /** Integer protocol version. All versions >= 1 are core-compatible. */
+    readonly version: number;
     readonly properties: readonly IWcBindableProperty[];
     readonly inputs?: readonly IWcBindableInput[];
     readonly commands?: readonly IWcBindableCommand[];
@@ -86,6 +140,7 @@ interface WcsContactsCoreValues {
     loading: boolean;
     error: any;
     cancelled: boolean;
+    errorInfo: WcsIoErrorInfo | null;
 }
 /**
  * Value types for the Shell (`<wcs-contacts>`) — identical observable surface
@@ -103,27 +158,31 @@ declare function getConfig(): IConfig;
  * `navigator.contacts.select(properties, options)` exposed through the
  * wc-bindable protocol.
  *
- * This is the same simplified derivative of `FetchCore._doFetch` that
- * `@wcstack/share`'s `ShareCore` establishes (docs/contact-picker-tag-design.md
- * §1): single `_gen` generation guard, same-value-guarded private setters,
- * never-throw try/catch, no `AbortController`/`abort()` — the Contact Picker
- * API accepts no `AbortSignal` and, like the Web Share dialog, the picker is a
- * single system-modal surface (at most one open at a time).
+ * Concurrency is owned by the shared `OperationLane` (io-core) with the `exhaust`
+ * policy: the contact picker is a single system-modal surface, so while one
+ * select() is in flight a new call is rejected as an idempotent no-op instead of
+ * starting a second `navigator.contacts.select()`. This replaces the earlier
+ * dispose-only `_gen` guard, which relied on the platform rejecting the second call
+ * with `InvalidStateError` — but that let the rejected second call reset/overwrite
+ * the still-pending first call's `error`/`loading` state. The lane's owner
+ * generation still invalidates any in-flight select() on dispose().
  *
- * The one structural difference from `ShareCore`: `select()` takes **two**
- * positional arguments (`properties`, `options`) rather than one — the first
- * batch-3 member to do so. The command-token argument pass-through
- * (spec-proposal-command-token-arguments.md) does not special-case argument
- * count, so this requires no protocol change.
+ * The Contact Picker API accepts no `AbortSignal`, so the lane runs with
+ * `withSignal: false`. `select()` takes **two** positional arguments
+ * (`properties`, `options`) rather than one — the command-token argument
+ * pass-through does not special-case argument count, so this requires no protocol
+ * change.
  */
 declare class ContactsCore extends EventTarget {
     static wcBindable: IWcBindable;
+    private static readonly REQUIRED_CAPABILITIES;
     private _target;
     private _value;
     private _loading;
     private _error;
     private _cancelled;
-    private _gen;
+    private _errorInfo;
+    private _lane;
     private _ready;
     constructor(target?: EventTarget);
     get ready(): Promise<void>;
@@ -131,13 +190,32 @@ declare class ContactsCore extends EventTarget {
     get loading(): boolean;
     get error(): any;
     get cancelled(): boolean;
+    /**
+     * The last failure's serializable `WcsIoErrorInfo` (stable `code` / `phase` /
+     * `recoverable` / `capabilityId`), or null. Exposed as an additive wc-bindable
+     * property (event `wcs-contacts:error-info-changed`); the existing `error`
+     * property/event are unchanged.
+     */
+    get errorInfo(): WcsIoErrorInfo | null;
+    /**
+     * Whether the required platform capability (`web.contacts`) is available right
+     * now — decided by call-time feature detection, not User-Agent. Core-only,
+     * additive.
+     */
+    get supported(): boolean;
+    /**
+     * Full platform assessment (availability / readiness / preconditions), probed at
+     * call time. Core-only opt-in dev / sidecar view.
+     */
+    get platformAssessment(): PlatformAssessment;
     observe(): Promise<void>;
     dispose(): void;
     private _setLoading;
     private _setValue;
     private _setError;
     private _setCancelled;
-    private _api;
+    private _setErrorInfo;
+    private _commitErrorInfo;
     select(properties: ContactProperty[], options?: ContactsSelectOptions): Promise<ContactInfo[] | null>;
 }
 
@@ -166,11 +244,27 @@ declare class WcsContacts extends HTMLElement {
     get loading(): boolean;
     get error(): any;
     get cancelled(): boolean;
+    get errorInfo(): WcsIoErrorInfo | null;
     get connectedCallbackPromise(): Promise<void>;
     select(properties: ContactProperty[], options?: ContactsSelectOptions): Promise<ContactInfo[] | null>;
     connectedCallback(): void;
     disconnectedCallback(): void;
 }
 
-export { ContactsCore, WcsContacts, bootstrapContacts, getConfig };
-export type { ContactAddress, ContactInfo, ContactProperty, ContactsSelectOptions, IWritableConfig, IWritableTagNames, WcsContactsCoreValues, WcsContactsValues };
+/**
+ * contactsCapabilities.ts
+ *
+ * Contact Picker node 固有の capability registry と error code。汎用の assess 機構・
+ * 型は `./platformCapability.js`(/io-core/ から copy-distribution される生成ファイル)
+ * から import する。node 固有の宣言はこのハンドライトファイルに置き、生成コピーとは
+ * 分離する。
+ */
+
+/** 安定した contacts error code(taxonomy)。値は公開キーとして固定。 */
+declare const WCS_CONTACTS_ERROR_CODE: {
+    readonly CapabilityMissing: "capability-missing";
+    readonly SelectFailed: "select-failed";
+};
+
+export { ContactsCore, WCS_CONTACTS_ERROR_CODE, WcsContacts, bootstrapContacts, getConfig };
+export type { ContactAddress, ContactInfo, ContactProperty, ContactsSelectOptions, IWritableConfig, IWritableTagNames, WcsContactsCoreValues, WcsContactsValues, WcsIoErrorInfo, WcsIoErrorPhase };