@wcstack/upload 1.20.0 → 1.21.0

package/README.ja.md

@@ -202,6 +202,7 @@ npm install @wcstack/upload
 | `progress` | `number` | `0` | `0` から `100` の進捗率 |
 | `error` | `any` | `null` | バリデーション、ネットワーク、レスポンスのエラー |
 | `status` | `number` | `0` | HTTP レスポンスステータス |
+| `errorInfo` | `WcsIoErrorInfo \| null` | `null` | serializable な失敗 taxonomy（安定 `code` / `phase` / `recoverable`）。追加的で `error` は不変。`code` は `capability-missing` / `invalid-argument` / `network` / `http-error`。`abort()` は失敗ではない（`errorInfo` を立てない） |
 | `promise` | `Promise<any>` | resolved `null` | 現在のアップロード Promise |
 
 ### メソッド

package/README.md

@@ -202,6 +202,7 @@ In this setup, upload becomes a bindable async node:
 | `progress` | `number` | `0` | Upload progress from `0` to `100` |
 | `error` | `any` | `null` | Validation, network, or response error |
 | `status` | `number` | `0` | HTTP response status |
+| `errorInfo` | `WcsIoErrorInfo \| null` | `null` | Serializable failure taxonomy (stable `code` / `phase` / `recoverable`). Additive — `error` is unchanged; `code` is `capability-missing`, `invalid-argument`, `network`, or `http-error`. An `abort()` is not a failure (no `errorInfo`) |
 | `promise` | `Promise<any>` | resolved `null` | Current upload promise |
 
 ### Methods

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[];
@@ -54,6 +108,8 @@ interface WcsUploadCoreValues<T = unknown> {
     progress: number;
     error: WcsUploadError | Error | null;
     status: number;
+    /** Last failure's serializable taxonomy (stable code/phase/recoverable), or null. */
+    errorInfo: WcsIoErrorInfo | null;
 }
 /**
  * Value types for the Shell (`<wcs-upload>`) — extends Core with `trigger` and `files`.
@@ -80,15 +136,17 @@ interface UploadRequestOptions {
 }
 declare class UploadCore extends EventTarget {
     static wcBindable: IWcBindable;
+    private static readonly REQUIRED_CAPABILITIES;
     private _target;
     private _value;
     private _loading;
     private _progress;
     private _error;
     private _status;
+    private _errorInfo;
     private _xhr;
     private _promise;
-    private _gen;
+    private _lane;
     private _ready;
     constructor(target?: EventTarget);
     get ready(): Promise<void>;
@@ -100,11 +158,31 @@ declare class UploadCore extends EventTarget {
     get error(): any;
     get status(): number;
     get promise(): Promise<any>;
+    /**
+     * The last failure's serializable `WcsIoErrorInfo` (stable `code` / `phase` /
+     * `recoverable` / `capabilityId`), or null. Exposed as an additive wc-bindable
+     * property (event `wcs-upload:error-info-changed`); the existing `error`
+     * property/event are unchanged. An abort() is not a failure (no errorInfo).
+     */
+    get errorInfo(): WcsIoErrorInfo | null;
+    /**
+     * Whether the required platform capability (`web.xhr`) 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;
+    private _commitStep;
     private _setLoading;
     private _setProgress;
     private _setError;
     setError(error: any): void;
     private _setResponse;
+    private _setErrorInfo;
+    private _commitErrorInfo;
     abort(): void;
     upload(url: string, files: FileList | File[], options?: UploadRequestOptions): Promise<any>;
     private _doUpload;
@@ -143,6 +221,7 @@ declare class WcsUpload extends HTMLElement {
     get progress(): number;
     get error(): any;
     get status(): number;
+    get errorInfo(): WcsIoErrorInfo | null;
     get promise(): Promise<any>;
     get trigger(): boolean;
     set trigger(value: boolean);
@@ -156,5 +235,21 @@ declare class WcsUpload extends HTMLElement {
     disconnectedCallback(): void;
 }
 
-export { UploadCore, WcsUpload, bootstrapUpload, getConfig };
-export type { IWritableConfig, IWritableTagNames, UploadRequestOptions, WcsUploadCoreValues, WcsUploadError, WcsUploadValues };
+/**
+ * uploadCapabilities.ts
+ *
+ * Upload node 固有の capability registry と error code。汎用の assess 機構・型は
+ * `./platformCapability.js`(/io-core/ から copy-distribution される生成ファイル)から
+ * import する。node 固有の宣言はこのハンドライトファイルに置き、生成コピーとは分離する。
+ */
+
+/** 安定した upload error code(taxonomy)。値は公開キーとして固定。 */
+declare const WCS_UPLOAD_ERROR_CODE: {
+    readonly CapabilityMissing: "capability-missing";
+    readonly InvalidArgument: "invalid-argument";
+    readonly Network: "network";
+    readonly HttpError: "http-error";
+};
+
+export { UploadCore, WCS_UPLOAD_ERROR_CODE, WcsUpload, bootstrapUpload, getConfig };
+export type { IWritableConfig, IWritableTagNames, UploadRequestOptions, WcsIoErrorInfo, WcsIoErrorPhase, WcsUploadCoreValues, WcsUploadError, WcsUploadValues };