@wcstack/share 1.20.0 → 1.21.1

package/README.ja.md

@@ -88,6 +88,12 @@ npm install @wcstack/share
 | `loading`   | `wcs-share:loading-changed`     | `share()` 呼び出しが進行中なら `true`。 |
 | `error`     | `wcs-share:error`               | 真のプラットフォーム障害（ユーザーが共有シートをキャンセルした場合を**除く**すべて）。まだ失敗が無い場合、または次の `share()` 呼び出しでリセットされた後は `null`。 |
 | `cancelled` | `wcs-share:cancelled-changed`   | ユーザーがネイティブ共有シートを閉じた（`AbortError`）場合に `true`。`error` を条件にしたバインディングが日常的なキャンセルに反応しないよう、`error` とは独立している。 |
+| `errorInfo` | `wcs-share:error-info-changed`  | serializable な失敗 taxonomy（安定 `code` / `phase` / `recoverable`）、または `null`。追加的で `error` の shape は不変。`code` は unsupported なら `capability-missing`、真の失敗なら `share-failed`。 |
+
+**並行制御。** 共有シートはシステムに1つのモーダル面なので、`<wcs-share>` は共有
+io-core lane を `exhaust` policy で用いる: 1つの `share()` が進行中の間、2回目の呼び出しは
+冪等な **no-op**（2つ目のシートを開かず `null` を返す）となり、進行中の呼び出しの結果を
+汚さない。
 
 `cancelled` と `error` はどちらも、実際に `navigator.share()` を呼び出す `share()` 呼び出しの **開始時** にリセットされる（`false` / `null`）ため、前回の呼び出しの古い結果がその呼び出しの結果に残り続けることはありません。唯一の例外が unsupported 早期リターン（`navigator.share` が存在しない場合。後述）です — このリセットが走る前に return するため、前回呼び出しの `cancelled` が `true` のまま残り、新たに設定された unsupported の `error` と同時に立つことがあります。`navigator.share` がセッション途中で消失するのは非現実的なため、これは限定的なエッジケースです。
 

package/README.md

@@ -88,6 +88,12 @@ Because `share()` must run from within a real user gesture (a click handler), th
 | `loading`   | `wcs-share:loading-changed`     | `true` while a `share()` call is in flight. |
 | `error`     | `wcs-share:error`               | A genuine platform failure (anything **other than** the user cancelling the share sheet). `null` when there has been no failure yet, or after the next `share()` call resets it. |
 | `cancelled` | `wcs-share:cancelled-changed`   | `true` when the user dismissed the native share sheet (`AbortError`). Kept independent of `error` so bindings gated on `error` do not react to routine cancellation. |
+| `errorInfo` | `wcs-share: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 `share-failed` on a genuine failure. |
+
+**Concurrency.** A share sheet is a single system-modal surface, so `<wcs-share>`
+runs its calls through the shared io-core lane with the `exhaust` policy: while one
+`share()` is in flight, a second call is an idempotent **no-op** (it returns `null`
+without opening a second sheet), leaving the in-flight call's result untouched.
 
 `cancelled` and `error` are both reset (`false` / `null`) at the **start** of a `share()` call that goes on to actually invoke `navigator.share()`, so a stale outcome from a previous call never lingers into that call's result. The one exception is the unsupported early-return (`navigator.share` missing, see below): it returns before that reset runs, so a `cancelled` left over from an earlier call can still read `true` alongside the freshly-set unsupported `error`. This is a narrow edge case in practice — a page losing `navigator.share` mid-session is not a realistic scenario.
 

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[];
@@ -73,6 +127,8 @@ interface WcsShareCoreValues {
      * routine cancellation (docs/web-share-tag-design.md §3).
      */
     cancelled: boolean;
+    /** Last failure's serializable taxonomy (stable code/phase/recoverable), or null. */
+    errorInfo: WcsIoErrorInfo | null;
 }
 /**
  * Value types for the Shell (`<wcs-share>`) — identical observable surface to
@@ -89,24 +145,28 @@ declare function getConfig(): IConfig;
  * Headless Web Share primitive. A thin, framework-agnostic wrapper around
  * `navigator.share(data)` exposed through the wc-bindable protocol.
  *
- * This is a simplified derivative of `FetchCore._doFetch`
- * (docs/web-share-tag-design.md §2): it keeps the single `_gen` generation
- * guard, the same-value-guarded private setters, and the never-throw
- * try/catch wrapper, but drops `AbortController`/`abort()` entirely —
- * `navigator.share()` accepts no `AbortSignal` and there is no platform
- * mechanism for a caller to cancel an in-flight share dialog. A share dialog
- * is also a single system-modal surface (at most one open at a time), so the
- * "a new call supersedes the previous one" plumbing that `FetchCore` needs
- * has no counterpart here either.
+ * Concurrency is owned by the shared `OperationLane` (io-core) with the `exhaust`
+ * policy: a share dialog is a single system-modal surface, so while one share() is
+ * in flight a new call is rejected as an idempotent no-op instead of starting a
+ * second `navigator.share()`. 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 share() on dispose() (a late resolve fails the commit guard).
+ *
+ * `navigator.share()` accepts no `AbortSignal` and there is no platform mechanism
+ * to cancel an in-flight share dialog, so the lane runs with `withSignal: false`.
  */
 declare class ShareCore 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>;
@@ -114,13 +174,31 @@ declare class ShareCore 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-share:error-info-changed`); the existing `error`
+     * property/event are unchanged.
+     */
+    get errorInfo(): WcsIoErrorInfo | null;
+    /**
+     * Whether the required platform capability (`web.share`) 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;
     share(data?: WcsShareData): Promise<WcsShareData | null>;
 }
 
@@ -145,6 +223,7 @@ declare class WcsShare extends HTMLElement {
     get loading(): boolean;
     get error(): any;
     get cancelled(): boolean;
+    get errorInfo(): WcsIoErrorInfo | null;
     get connectedCallbackPromise(): Promise<void>;
     share(data?: WcsShareData): Promise<WcsShareData | null>;
     /**
@@ -166,5 +245,19 @@ declare class WcsShare extends HTMLElement {
     disconnectedCallback(): void;
 }
 
-export { ShareCore, WcsShare, bootstrapShare, getConfig };
-export type { IWritableConfig, IWritableTagNames, WcsShareCoreValues, WcsShareData, WcsShareValues };
+/**
+ * shareCapabilities.ts
+ *
+ * Web Share node 固有の capability registry と error code。汎用の assess 機構・型は
+ * `./platformCapability.js`(/io-core/ から copy-distribution される生成ファイル)から
+ * import する。node 固有の宣言はこのハンドライトファイルに置き、生成コピーとは分離する。
+ */
+
+/** 安定した share error code(taxonomy)。値は公開キーとして固定。 */
+declare const WCS_SHARE_ERROR_CODE: {
+    readonly CapabilityMissing: "capability-missing";
+    readonly ShareFailed: "share-failed";
+};
+
+export { ShareCore, WCS_SHARE_ERROR_CODE, WcsShare, bootstrapShare, getConfig };
+export type { IWritableConfig, IWritableTagNames, WcsIoErrorInfo, WcsIoErrorPhase, WcsShareCoreValues, WcsShareData, WcsShareValues };