@wcstack/camera 1.15.0 → 1.17.0

package/README.ja.md

@@ -77,6 +77,66 @@ $on: {
 
 > **`objectURL` の寿命は recorder に束縛されます。** dispose が最後の object URL を revoke し、**さらに次の録画は前のクリップの URL を新規発行前に revoke する**ため、古い URL を指したままの `<video src>` / `<wcs-upload>` は `<wcs-recorder>` が外れる・次のクリップが完成した時点で壊れます。常に最新の `objectURL` / `recorded` 値を追従し、古い URL を保持しないでください。URL を寿命の長い消費側へ渡す場合は、URL を使い終わるまで recorder を接続したままにするか、`Blob` から自前で URL を作り（`URL.createObjectURL(blob)`）revoke も自分で管理してください。structured-clone 可能な **`blob`** にはこの結合がありません——`Blob` を state に流し、利用箇所で URL を生成するのが安全です。
 
+## `:state()` による CSS スタイリング
+
+`<wcs-camera>` と `<wcs-recorder>` は boolean 出力ステートを
+[`ElementInternals` の `CustomStateSet`](https://developer.mozilla.org/ja/docs/Web/API/CustomStateSet)
+に反映します。そのため `data-wcs` バインディングやクラスの手動トグルなしに、CSS の
+`:state()` 疑似クラスで直接スタイリングできます。
+
+| 要素 | ステート | on になる条件 |
+|------|----------|----------------|
+| `wcs-camera` | `active` | `wcs-camera:active-changed` が `true` で発火（`false` でクリア） |
+| `wcs-camera` | `error` | `wcs-camera:error` が非 `null` の detail で発火（`null` でクリア） |
+| `wcs-recorder` | `recording` | `wcs-recorder:recording-changed` が `true` で発火（`false` でクリア） |
+| `wcs-recorder` | `paused` | `wcs-recorder:paused-changed` が `true` で発火（`false` でクリア） |
+| `wcs-recorder` | `error` | `wcs-recorder:error` が非 `null` の detail で発火（`null` でクリア） |
+
+> `permission` / `audioPermission` には現時点で boolean 派生 getter が無いため
+> 反映対象外です（v1 スコープ。docs/custom-state-reflection-design.md §7 参照）。
+> `duration` は連続値のため意図的に除外しています。
+
+```css
+wcs-camera:state(active) ~ .live-badge     { display: block; }
+form:has(wcs-camera:state(error)) .banner  { display: block; }
+
+wcs-recorder:state(recording) ~ .rec-dot   { animation: blink 1s infinite; }
+wcs-recorder:state(paused) ~ .rec-dot      { animation: none; opacity: .4; }
+```
+
+属性やクラスと異なり `:state()` は要素の外部から書き込めないため、この出力ステートが
+入力と混同される心配がありません。
+
+**対応ブラウザ**（新構文 `:state(x)`）: Chrome/Edge 125+、Safari 17.4+、Firefox 126+。
+非対応の環境ではステートが一切 set されないだけです — `:state()` セレクタがマッチしなく
+なりますが、各要素自体は通常どおり動作し続けます（graceful degradation・never-throw）。
+
+**SSR:** `:state()` は HTML にシリアライズできないため、サーバーレンダリングされた
+マークアップの初期ペイントにはこれらのステートは乗りません（`@wcstack/server` は無改変）。
+ハイドレーション前の見た目を制御したい場合は、代わりに `wcs-camera:not(:defined)` /
+`wcs-recorder:not(:defined)` と組み合わせてください。
+
+### デバッグ
+
+カスタムステートは DevTools の Elements パネルには表示されず、`attachInternals()`
+は同一要素に 2 回呼べないため、コンソールから直接覗く手段がありません。そのための
+デバッグ専用の補助を 2 つ用意しています:
+
+- `el.debugStates` — 現在 on になっているステート名の**スナップショット**配列
+  （例: `["active"]`）。`wc-bindable` の一部ではなく（バインド対象ではない）、
+  形状も契約として保証されません — デバッグ用途にのみ使ってください。
+- `debug-states` 属性（opt-in・既定 OFF）は、ステート変化を要素の
+  `data-wcs-state-*` 属性にミラーします。Elements パネルを開いておけば、
+  トグルのたびにハイライトされます:
+
+  ```html
+  <wcs-camera autostart debug-states></wcs-camera>
+  ```
+
+**CSS は `data-wcs-state-*` ではなく `:state()` に書いてください。** ミラーされた
+属性は、DevTools を開いた状態でステート変化を可視化するためだけのものであり、
+スタイリング用の正式なフックではありません。
+
 ## ヘッドレス Core
 
 `CameraCore` / `RecorderCore` を非 DOM 用途向けにエクスポートしています（`@wc-bindable/core` の `bind()`）。Shell は薄いラッパです。

package/README.md

@@ -77,6 +77,67 @@ The assembled `Blob` is structured-clone friendly, so it *is* a value and may fl
 
 > **`objectURL` lifetime is bound to the recorder.** Because dispose revokes the last object URL — **and a new recording revokes the previous clip's URL before minting the next** — any `<video src>` / `<wcs-upload>` still pointing at an old URL breaks once the `<wcs-recorder>` is removed or the next clip completes. Always follow the latest `objectURL` / `recorded` value; never pin a stale one. If you hand the URL to a longer-lived consumer, either keep the recorder mounted for as long as the URL is in use, or build your own URL from the `Blob` (`URL.createObjectURL(blob)`) and own its revoke. The structured-clone-friendly **`blob`** has no such coupling — prefer flowing the `Blob` through state and minting URLs at the point of use.
 
+## CSS styling with `:state()`
+
+`<wcs-camera>` and `<wcs-recorder>` reflect their boolean output states onto
+[`ElementInternals` `CustomStateSet`](https://developer.mozilla.org/en-US/docs/Web/API/CustomStateSet),
+so you can style them directly from CSS with the `:state()` pseudo-class — no
+`data-wcs` binding or extra class toggling required.
+
+| Element | State | On when |
+|---------|-------|---------|
+| `wcs-camera` | `active` | `wcs-camera:active-changed` fires with `true` (cleared on `false`) |
+| `wcs-camera` | `error` | `wcs-camera:error` fires with a non-`null` detail (cleared on `null`) |
+| `wcs-recorder` | `recording` | `wcs-recorder:recording-changed` fires with `true` (cleared on `false`) |
+| `wcs-recorder` | `paused` | `wcs-recorder:paused-changed` fires with `true` (cleared on `false`) |
+| `wcs-recorder` | `error` | `wcs-recorder:error` fires with a non-`null` detail (cleared on `null`) |
+
+> `permission` / `audioPermission` have no boolean derived getter today, so they
+> are not reflected (v1 scope; see docs/custom-state-reflection-design.md §7).
+> `duration` is a continuous value and is intentionally excluded.
+
+```css
+wcs-camera:state(active) ~ .live-badge     { display: block; }
+form:has(wcs-camera:state(error)) .banner  { display: block; }
+
+wcs-recorder:state(recording) ~ .rec-dot   { animation: blink 1s infinite; }
+wcs-recorder:state(paused) ~ .rec-dot      { animation: none; opacity: .4; }
+```
+
+Unlike attributes or classes, `:state()` cannot be written from outside the
+element, so there is no risk of confusing this output state with an input.
+
+**Browser support** (`:state(x)` syntax): Chrome/Edge 125+, Safari 17.4+,
+Firefox 126+. In older browsers the states are simply never set — `:state()`
+selectors never match, but the elements themselves keep working normally
+(graceful degradation, never-throw).
+
+**SSR**: `:state()` cannot be serialized into HTML, so server-rendered markup
+never carries these states on first paint (`@wcstack/server` is unaffected).
+If you need to style the pre-hydration gap, pair your rule with
+`wcs-camera:not(:defined)` / `wcs-recorder:not(:defined)` instead.
+
+### Debugging
+
+Custom states are invisible in DevTools' Elements panel and `attachInternals()`
+cannot be called twice, so there is no console way to inspect them directly.
+Two debug-only aids are provided for that:
+
+- `el.debugStates` — a **snapshot** array of the currently-on state names
+  (e.g. `["active"]`). It is not part of `wc-bindable` (not a bind target)
+  and its shape is not a guaranteed contract — use it for debugging only.
+- The `debug-states` attribute (opt-in, default off) mirrors state changes
+  onto `data-wcs-state-*` attributes on the element, so the Elements panel
+  highlights them as they toggle:
+
+  ```html
+  <wcs-camera autostart debug-states></wcs-camera>
+  ```
+
+**Write your CSS against `:state()`, not `data-wcs-state-*`.** The mirrored
+attributes exist purely to make state changes visible while debugging with
+DevTools open; they are not a supported styling hook.
+
 ## Headless cores
 
 `CameraCore` and `RecorderCore` are exported for non-DOM use (`bind()` from `@wc-bindable/core`). The Shells are thin wrappers.

package/dist/index.d.ts

@@ -299,7 +299,11 @@ declare class WcsCamera extends HTMLElement {
     private _connectedCallbackPromise;
     private _connected;
     private _batchingAttrs;
+    private _internals;
     constructor();
+    get debugStates(): string[];
+    private _initInternals;
+    private _wireStates;
     get audio(): boolean;
     set audio(value: boolean);
     get facingMode(): FacingMode;
@@ -451,7 +455,11 @@ declare class WcsRecorder extends HTMLElement {
     static wcBindable: IWcBindable;
     private _core;
     private _connectedCallbackPromise;
+    private _internals;
     constructor();
+    get debugStates(): string[];
+    private _initInternals;
+    private _wireStates;
     get connectedCallbackPromise(): Promise<void>;
     get mimeType(): string;
     set mimeType(value: string);

package/dist/index.esm.js

@@ -583,6 +583,7 @@ class WcsCamera extends HTMLElement {
     // tear active down so the later change's re-acquire is skipped). We suppress the
     // per-attribute re-acquire and drive a single one with the final constraints.
     _batchingAttrs = false;
+    _internals = null;
     constructor() {
         super();
         this._core = new CameraCore(this);
@@ -603,6 +604,60 @@ class WcsCamera extends HTMLElement {
         // `document` (outlives the element) and MUST be detached.
         this.addEventListener("wcs-camera:stream-ready", this._onStreamReady);
         this.addEventListener("wcs-camera:active-changed", this._onActiveChanged);
+        this._internals = this._initInternals();
+        this._wireStates({
+            "wcs-camera:active-changed": (d) => ({ active: d === true }),
+            "wcs-camera:error": (d) => ({ error: d != null }),
+        });
+    }
+    // CSS state reflection (:state()) — debug-only snapshot getter. NOT part of
+    // wc-bindable (not a bind target); see README "CSS styling with :state()".
+    // MUST NOT return the live CustomStateSet (that would let callers write
+    // states from outside, defeating the point of :state() being read-only).
+    get debugStates() {
+        return this._internals ? [...this._internals.states] : [];
+    }
+    _initInternals() {
+        // never-throw (docs/custom-state-reflection-design.md §3.4): attachInternals is
+        // absent in happy-dom / older environments, and pre-125 Chromium rejects
+        // non-dashed state names from states.add() (probed and discarded here). Either
+        // case silently disables reflection — the component still works, it just doesn't
+        // expose :state() selectors.
+        try {
+            if (typeof this.attachInternals !== "function")
+                return null;
+            const internals = this.attachInternals();
+            internals.states.add("wcs-probe");
+            internals.states.delete("wcs-probe");
+            return internals;
+        }
+        catch {
+            return null;
+        }
+    }
+    _wireStates(map) {
+        if (this._internals === null)
+            return;
+        const states = this._internals.states;
+        for (const [event, toStates] of Object.entries(map)) {
+            this.addEventListener(event, (e) => {
+                const debug = this.hasAttribute("debug-states");
+                for (const [name, on] of Object.entries(toStates(e.detail))) {
+                    try {
+                        // 式文の三項演算子は ESLint no-unused-expressions に抵触するため if/else。
+                        if (on) {
+                            states.add(name);
+                        }
+                        else {
+                            states.delete(name);
+                        }
+                    }
+                    catch { /* never-throw */ }
+                    if (debug)
+                        this.toggleAttribute(`data-wcs-state-${name}`, on);
+                }
+            });
+        }
     }
     // --- Attribute accessors ---
     get audio() { return this.hasAttribute("audio"); }
@@ -1080,9 +1135,65 @@ class WcsRecorder extends HTMLElement {
     };
     _core;
     _connectedCallbackPromise = Promise.resolve();
+    _internals = null;
     constructor() {
         super();
         this._core = new RecorderCore(this);
+        this._internals = this._initInternals();
+        this._wireStates({
+            "wcs-recorder:recording-changed": (d) => ({ recording: d === true }),
+            "wcs-recorder:paused-changed": (d) => ({ paused: d === true }),
+            "wcs-recorder:error": (d) => ({ error: d != null }),
+        });
+    }
+    // CSS state reflection (:state()) — debug-only snapshot getter. NOT part of
+    // wc-bindable (not a bind target); see README "CSS styling with :state()".
+    // MUST NOT return the live CustomStateSet (that would let callers write
+    // states from outside, defeating the point of :state() being read-only).
+    get debugStates() {
+        return this._internals ? [...this._internals.states] : [];
+    }
+    _initInternals() {
+        // never-throw (docs/custom-state-reflection-design.md §3.4): attachInternals is
+        // absent in happy-dom / older environments, and pre-125 Chromium rejects
+        // non-dashed state names from states.add() (probed and discarded here). Either
+        // case silently disables reflection — the component still works, it just doesn't
+        // expose :state() selectors.
+        try {
+            if (typeof this.attachInternals !== "function")
+                return null;
+            const internals = this.attachInternals();
+            internals.states.add("wcs-probe");
+            internals.states.delete("wcs-probe");
+            return internals;
+        }
+        catch {
+            return null;
+        }
+    }
+    _wireStates(map) {
+        if (this._internals === null)
+            return;
+        const states = this._internals.states;
+        for (const [event, toStates] of Object.entries(map)) {
+            this.addEventListener(event, (e) => {
+                const debug = this.hasAttribute("debug-states");
+                for (const [name, on] of Object.entries(toStates(e.detail))) {
+                    try {
+                        // 式文の三項演算子は ESLint no-unused-expressions に抵触するため if/else。
+                        if (on) {
+                            states.add(name);
+                        }
+                        else {
+                            states.delete(name);
+                        }
+                    }
+                    catch { /* never-throw */ }
+                    if (debug)
+                        this.toggleAttribute(`data-wcs-state-${name}`, on);
+                }
+            });
+        }
     }
     get connectedCallbackPromise() {
         return this._connectedCallbackPromise;