@wcstack/worker 1.12.0

package/README.ja.md

@@ -0,0 +1,184 @@
+# @wcstack/worker
+
+`@wcstack/worker` は wcstack エコシステム向けのヘッドレスな Web Worker コンポーネントです。
+
+これは視覚的な UI ウィジェットではありません。
+`@wcstack/fetch` がネットワークリクエストをリアクティブな状態に変え、`@wcstack/websocket` がソケットをリアクティブな状態に変えるのと同じように、**Dedicated Worker をリアクティブな状態に変える非同期プリミティブノード**です。
+
+`<wcs-worker>` はバックグラウンドスレッドを所有し、そのメッセージパッシング面を wc-bindable トークンプロトコルを通じて公開します。
+
+- **post**（`state → element`）— command-token プロトコル経由（`command.post: $command.run`）
+- **message**（`element → state`）— event-token プロトコル経由（`eventToken.message: onResult`）
+
+`@wcstack/state` と組み合わせると、`<wcs-worker>` はパス契約を通じて直接バインドできます。
+
+- **入力面**: `src`, `type`, `name`, `manual`, `keep-alive`, `restart-on-error`, `max-restarts`, `restart-interval`
+- **コマンド面**: `start`, `post`, `terminate`
+- **出力状態面**: `message`, `error`, `running`
+
+つまり、worker スレッドへの処理のオフロードを HTML 上で宣言的に表現でき、UI 層に `new Worker()` / `postMessage()` / `onmessage` リスナ、後始末のグルーコードを書く必要がありません。
+
+`@wcstack/worker` は [CSBC](https://github.com/csbc-dev/arch/blob/main/README.md)（Core / Shell / Binding Contract）アーキテクチャに従います。
+
+- **Core**（`WorkerCore`）が worker のライフサイクル、post、structured clone による受信、エラー処理、オプトインの restart-on-error を所有
+- **Shell**（`<wcs-worker>`）がその状態を DOM 属性・ライフサイクル・宣言的コマンドに接続
+- **Binding Contract**（`static wcBindable`）が観測可能な `properties`・書き込み可能な `inputs`・呼び出し可能な `commands` を宣言
+
+## なぜ存在するのか
+
+Worker は `fetch` や `WebSocket` と同様、値を非同期に生み出すソースですが、加えて**リソースを所有**します（バックグラウンドスレッド）。命令的に書くと、worker の構築・`message` / `messageerror` / `error` リスナの配線・解体時の terminate が必要になります。
+
+`@wcstack/worker` はそのロジックを再利用可能なコンポーネントに押し込み、結果をバインド可能な状態として公開します。worker から返ってくる計算結果が命令的なコールバック配線ではなく、**状態遷移**になります。
+
+> **バス型であって RPC ではない。** `post` は fire-and-forget で、結果は `message` に届きます。リクエスト/レスポンスの組み込みの相関付けはありません。返信を特定のリクエストに対応付けたい場合は、ペイロードに相関 id を含めて worker にエコーバックさせてください（あるいは、リクエストが 1 つだけ進行中なら次の値を `message` で待ってください）。
+
+> **structured clone、JSON の往復は無い。** ペイロードはブラウザの structured clone に乗ります（`@wcstack/broadcast` と対称であり、テキストワイヤで送る `<wcs-ws>` とは意図的に異なります）。オブジェクトを直接 post すると、worker はコピーを受け取ります。クローン不可能なペイロード（関数、DOM ノード）は throw せず `error` プロパティを通じて `DataCloneError` を表面化します。
+
+> **既定で ESM。** worker は `type="classic"` を設定しない限り `{ type: "module" }` で作成されます。
+
+## インストール
+
+```bash
+npm install @wcstack/worker
+```
+
+## クイックスタート
+
+### 1. ジョブを実行して結果を読む
+
+```html
+<script type="module" src="https://esm.run/@wcstack/state/auto"></script>
+<script type="module" src="https://esm.run/@wcstack/worker/auto"></script>
+
+<wcs-state>
+  <script type="module">
+    export default { result: null };
+  </script>
+</wcs-state>
+
+<wcs-worker id="job" src="./compute.js" data-wcs="message: result"></wcs-worker>
+
+<!-- 任意の DOM トリガ: クリックで解決したテキストを worker に post -->
+<input id="n" value="42" />
+<button data-worker-target="job" data-worker-from="#n">Run</button>
+
+<p data-wcs="textContent: result"></p>
+```
+
+`data-worker-text` はリテラル文字列を post します。`data-worker-from` はセレクタにマッチした要素の `value`（なければ `textContent`）を post します。
+
+### 2. post（command-token） + result（event-token）
+
+1 つの要素に双対性が同居します。`post` は command-token から配線され、受信する `message` は event-token 経由で受け取ります。
+
+```html
+<wcs-state>
+  <script type="module">
+    export default {
+      input: 10,
+      output: null,
+      $commandTokens: ["run"],
+      $eventTokens: ["onResult"],
+      compute() {
+        this.$command.run.emit(this.input);   // state → worker
+      },
+      $on: {
+        onResult: (state, event) => {          // worker → state
+          state.output = event.detail;
+        }
+      }
+    };
+  </script>
+</wcs-state>
+
+<wcs-worker src="./compute.js" data-wcs="
+  command.post:       $command.run;
+  eventToken.message: onResult
+"></wcs-worker>
+
+<button data-wcs="onclick: compute">Compute</button>
+<p data-wcs="textContent: output"></p>
+```
+
+## 属性 / 入力（Attributes / Inputs）
+
+| 属性               | 型      | 既定値     | 説明                                                                        |
+| ------------------ | ------- | ---------- | --------------------------------------------------------------------------- |
+| `src`              | string  | `""`       | worker スクリプトの URL。変更すると古い worker を terminate して新しいスクリプトを spawn する。 |
+| `type`             | string  | `"module"` | `"module"`（ESM）または `"classic"`。                                       |
+| `name`             | string  | `""`       | 任意の worker 名。`Worker` コンストラクタの `name` オプションに渡される（DevTools / エラー識別に役立つ）。spawn 時に適用される — 後述の `type` の注記を参照。 |
+| `manual`           | boolean | `false`    | 接続時や `src` 変更時に自動で spawn しない。代わりに `start()` を呼ぶ。      |
+| `keep-alive`       | boolean | `false`    | 切断時に worker を terminate **しない** — 要素より長く生き残る。所有権はあなたに移る。スレッドを解放するには `terminate()` を呼ぶこと。 |
+| `restart-on-error` | boolean | `false`    | worker スクリプト内の未捕捉エラー後に新しい worker を再 spawn する。        |
+| `max-restarts`     | number  | `Infinity` | worker の生存期間にわたる自動再起動の**累積**回数の上限（連続クラッシュ数ではない — 安定稼働ではカウンタはリセットされない）。新しい `start()` / `src` 変更でのみリセットされる。 |
+| `restart-interval` | number  | `0`        | 自動再起動前の遅延（ミリ秒）。                                              |
+
+### DOM トリガ属性（autoTrigger、クリックで post）
+
+| 属性                 | 付与先         | 説明                                                                  |
+| -------------------- | -------------- | --------------------------------------------------------------------- |
+| `data-worker-target` | トリガボタン   | 駆動する `<wcs-worker>` の id。                                       |
+| `data-worker-text`   | トリガボタン   | post するリテラルテキスト（優先される。空文字列も有効）。             |
+| `data-worker-from`   | トリガボタン   | CSS セレクタ。マッチした要素の `value`（なければ `textContent`）を post。 |
+
+DOM トリガは**常に文字列を post します** — リテラルの `data-worker-text`、または解決された要素の `value` / `textContent`。これは単純なテキストペイロードのための利便機能であり、意図的に値のパース・型変換・構造化を行いません。structured clone データ（オブジェクト、typed array、transferable）を送るには、command-token プロトコル（`command.post: $command.run`）経由で `post` を起動するか、命令的に `element.post(data, transfer?)` を呼んでください。
+
+## 観測可能なプロパティ（出力）
+
+| プロパティ | イベント                      | 説明                                                                                 |
+| --------- | ----------------------------- | ------------------------------------------------------------------------------------ |
+| `message` | `wcs-worker:message`          | worker が post し返した直近の値（structured clone のコピー）。値が変わらなくても、メッセージごとに再発火する。 |
+| `error`   | `wcs-worker:error`            | 正規化された `{ name, message, filename?, lineno?, colno? }` — `DataCloneError`（クローン不可能な post）、`DataError`（worker メッセージをデシリアライズできなかった）、`InvalidStateError`（稼働中の worker が無い状態での post）、スクリプトの `Error`（worker 内の未捕捉エラー、位置情報付き）、または spawn 失敗（不正な URL / CSP / 非対応）。 |
+| `running` | `wcs-worker:running-changed`  | worker が spawn され、まだ terminate されていない間は `true`。                       |
+
+## コマンド
+
+| コマンド     | 説明                                                                                        |
+| ----------- | ------------------------------------------------------------------------------------------- |
+| `start`     | `src` 属性から worker を spawn する（以前に spawn した worker は terminate する。同じ `src` では冪等）。 |
+| `post`      | structured clone 可能な値を worker に post する（reject しない — 失敗は `error` へ）。ヘッドレスな `WorkerCore.post(data, transfer?)` は transfer リストも受け付ける。 |
+| `terminate` | worker を terminate する（冪等）。                                                          |
+
+状態からの起動には command-token プロトコルを使います。
+
+```html
+<wcs-worker src="./compute.js" data-wcs="command.post: $command.run"></wcs-worker>
+```
+
+## 注意点と制約
+
+- **バス型メッセージモデル。** リクエスト/レスポンスの相関付けは組み込まれていません。`post` は fire-and-forget で、返信は `message` に届きます。命令的利用向けの RPC 風 `request(data): Promise` は将来追加され得ます。
+- **「ready」シグナルは無い。** worker は即座に `postMessage` を受け付けます（プラットフォームはスクリプトが読み込まれるまでメッセージをキューします）。また標準の「スクリプト読み込み完了」イベントはありません。`running` は「spawn 済みかつ未 terminate」を意味し、「リクエストを処理できる準備ができた」ことを**意味しません**。本当の ready シグナルが必要なら、worker に起動時に ready メッセージを `post` させ、それを `message` で観測してください。
+- **`keep-alive` は所有権を移す。** `keep-alive` が無ければ、worker は切断時に terminate されます（`<wcs-ws>` / `<wcs-broadcast>` の close と同様）。`keep-alive` があると、worker は切断後も生き残り、`terminate()` を呼ぶ責任があなたに移ります — さもなければスレッドがリークします。この所有権移転の帰結として、`keep-alive` と `restart-on-error` の両方がある場合、切断時に保留中の再起動（`restart-interval` タイマーをスケジュールしたエラー）は**キャンセルされず**、要素が DOM を離れた後に発火し、切り離された要素上で新しい worker を再 spawn します。これは意図的です — `keep-alive` は切断後もライフサイクルがあなたのものであることを意味するからです — が、`keep-alive` な worker を止める最もきれいな方法は明示的な `terminate()` であり、これは保留中の再起動もクリアします。
+- **`restart-on-error` はオプトインかつ上限付き。** worker 内の未捕捉エラーはプラットフォーム上で自動 terminate しません。`restart-on-error` が設定されていると、`restart-interval` ミリ秒後に新しい worker が spawn され、最大 `max-restarts` 回まで行われます（`<wcs-ws>` の再接続上限と対応）。再起動カウンタは **worker の生存期間にわたる累積**です。最後の `start()` 以降の再起動総数をカウントし、安定稼働の期間で**リセットされません**。したがって `max-restarts` は連続クラッシュ数ではなく再起動総数を上限とします — 回復して後に再び失敗する worker も同じ予算を消費します。カウンタは新しい `start()`（または `start()` を呼ぶ `src` 変更）でのみリセットされます。予算を使い切ると、**同じ** `src` で再び `start()` を呼んでも冪等となり再 spawn しません — `terminate()` してから `start()`（または `src` 変更）してカウンタをリセットし、新たに spawn してください。**使うなら `max-restarts` を設定すること** — 既定値（`max-restarts="Infinity"`、`restart-interval="0"`）では、読み込み時に即座に throw する worker が密な `setTimeout(0)` ループで再 spawn し、`wcs-worker:error` / `wcs-worker:running-changed` を氾濫させてメインスレッドを飢餓状態にします。小さな正の `restart-interval` と有限の `max-restarts` が影響範囲を抑えます。
+- **再起動は `post` 状態を再生しない。** 各再起動は `new Worker(src)` を呼び、以前のメッセージの記憶を持たない*新鮮な*プロセスを生みます。Core は以前の `post` を再送しません。worker が機能するために初期化状態（config メッセージ、転送されたポート）を必要とするなら、起動時に要求するか再構築しなければなりません（例: ready シグナルを `post` してページに返信させる）。restart-on-error はそれを再配信しないからです。
+- **`src` は監視される。`type` / `name` は spawn 時に適用される。** 接続中（かつ非 `manual`）に `src` 属性を変更すると、古い worker を terminate して新しいスクリプトを spawn します。空でない新しい値だけが切り替えをトリガします。`type` と `name` は spawn 時に読み取られ、`observedAttributes` に**含まれません** — 稼働中の worker でそれらを変更しても、次回の spawn（`src` 変更、または `terminate()` + `start()`）まで効果はありません。同様に、同じ `src` で `start()` を再呼び出ししても冪等となり、変更されたオプションは無視されます。
+- **transferable はエスケープハッチ。** `transfer`（ArrayBuffer の所有権、MessagePort）は `data-wcs` のデータ配線では表現できません。命令的な `element.post(data, transfer)`（または `WorkerCore.post(data, transfer)`）を使ってください。宣言的レイヤは structured clone データのみを運びます。
+- **無言のエラー処理（ゼロログ）。** wcstack のゼロ依存主義に従い、`<wcs-worker>` は実行時の失敗に対して一切ログ出力も throw もしません。不正なスクリプト URL、CSP `worker-src` ブロック、クローン不可能な post、デシリアライズ失敗、worker 内の未捕捉エラーは `error` プロパティ / `wcs-worker:error` イベントを通じてのみ表面化します — `post()` は return し、決して reject しません。観測・対処するには `error` をバインドしてください。
+- **`src` はコードとして実行される — 信頼すること。** `src` の値は `new Worker(src)` にそのまま渡され、ページの権限でスクリプトを実行します。タグはオリジンの検証もサンドボックス化もしません。信頼するスクリプトにのみ `src` を向け（`<script src>` と同様に扱う）、worker をどこから読み込めるか制約するために明示的な `worker-src` 許可リストを持つ `Content-Security-Policy` を優先してください — 特に `src` がデータバインディングの影響を受け得る場合は。
+- **Dedicated Worker のみ。** SharedWorker と Worklet はこのタグの対象外です。
+
+## ヘッドレス利用（`WorkerCore`）
+
+Core はグローバルな `Worker` 以外に DOM 依存を持たず、`@wc-bindable/core` の `bind()` と直接組み合わせて使えます。
+
+```typescript
+import { WorkerCore } from "@wcstack/worker";
+
+const core = new WorkerCore();
+core.addEventListener("wcs-worker:message", (e) => {
+  console.log((e as CustomEvent).detail); // worker が post し返した値
+});
+
+core.start("./compute.js");
+core.post({ task: "sum", values: [1, 2, 3] });
+// ArrayBuffer を転送する（所有権が worker に移る）
+const buf = new ArrayBuffer(1024);
+core.post(buf, [buf]);
+// ...後で
+core.terminate();
+```
+
+## ライセンス
+
+MIT

package/README.md

@@ -0,0 +1,184 @@
+# @wcstack/worker
+
+`@wcstack/worker` is a headless Web Worker component for the wcstack ecosystem.
+
+It is not a visual UI widget.
+It is an **async primitive node** that turns a Dedicated Worker into reactive state — the same way `@wcstack/fetch` turns a network request into reactive state and `@wcstack/websocket` turns a socket into reactive state.
+
+`<wcs-worker>` owns a background thread and exposes its message-passing surface through the wc-bindable token protocol:
+
+- **post** (`state → element`) via the command-token protocol — `command.post: $command.run`
+- **message** (`element → state`) via the event-token protocol — `eventToken.message: onResult`
+
+With `@wcstack/state`, `<wcs-worker>` can be bound directly through path contracts:
+
+- **input surface**: `src`, `type`, `name`, `manual`, `keep-alive`, `restart-on-error`, `max-restarts`, `restart-interval`
+- **command surface**: `start`, `post`, `terminate`
+- **output state surface**: `message`, `error`, `running`
+
+This means offloading work to a worker thread can be expressed declaratively in HTML, without writing `new Worker()`, `postMessage()`, `onmessage` listeners, or teardown glue in your UI layer.
+
+`@wcstack/worker` follows the [CSBC](https://github.com/csbc-dev/arch/blob/main/README.md) (Core / Shell / Binding Contract) architecture:
+
+- **Core** (`WorkerCore`) owns the worker lifecycle, posting, structured-clone receipt, error handling, and opt-in restart-on-error
+- **Shell** (`<wcs-worker>`) connects that state to DOM attributes, lifecycle, and declarative commands
+- **Binding Contract** (`static wcBindable`) declares observable `properties`, writable `inputs`, and callable `commands`
+
+## Why this exists
+
+A Worker is, like `fetch` or `WebSocket`, an asynchronous source of values — but it also **owns a resource** (a background thread). Imperatively it requires constructing the worker, wiring `message` / `messageerror` / `error` listeners, and terminating on teardown.
+
+`@wcstack/worker` moves that logic into a reusable component and exposes the result as bindable state. A computed result coming back from a worker becomes a **state transition**, not imperative callback wiring.
+
+> **Bus-style, not RPC.** `post` is fire-and-forget and results arrive on `message`; there is no built-in request/response correlation. If you need to match a reply to a specific request, include a correlation id in your payload and have the worker echo it back (or await `message` for the next value when only one request is in flight).
+
+> **Structured clone, no JSON round-trip.** Payloads ride the browser's structured clone (symmetrical with `@wcstack/broadcast`, deliberately unlike `<wcs-ws>` which sends over a text wire). Post objects directly; the worker receives a copy. A non-cloneable payload (a function, a DOM node) surfaces a `DataCloneError` through the `error` property rather than throwing.
+
+> **ESM by default.** The worker is created with `{ type: "module" }` unless you set `type="classic"`.
+
+## Install
+
+```bash
+npm install @wcstack/worker
+```
+
+## Quick Start
+
+### 1. Run a job and read the result
+
+```html
+<script type="module" src="https://esm.run/@wcstack/state/auto"></script>
+<script type="module" src="https://esm.run/@wcstack/worker/auto"></script>
+
+<wcs-state>
+  <script type="module">
+    export default { result: null };
+  </script>
+</wcs-state>
+
+<wcs-worker id="job" src="./compute.js" data-wcs="message: result"></wcs-worker>
+
+<!-- Optional DOM triggering: click posts the resolved text to the worker -->
+<input id="n" value="42" />
+<button data-worker-target="job" data-worker-from="#n">Run</button>
+
+<p data-wcs="textContent: result"></p>
+```
+
+`data-worker-text` posts a literal string; `data-worker-from` posts the `value` (or `textContent`) of the element matched by the selector.
+
+### 2. post (command-token) + result (event-token)
+
+The duality in one element: `post` is wired from a command-token, and an incoming `message` is received via an event-token.
+
+```html
+<wcs-state>
+  <script type="module">
+    export default {
+      input: 10,
+      output: null,
+      $commandTokens: ["run"],
+      $eventTokens: ["onResult"],
+      compute() {
+        this.$command.run.emit(this.input);   // state → worker
+      },
+      $on: {
+        onResult: (state, event) => {          // worker → state
+          state.output = event.detail;
+        }
+      }
+    };
+  </script>
+</wcs-state>
+
+<wcs-worker src="./compute.js" data-wcs="
+  command.post:       $command.run;
+  eventToken.message: onResult
+"></wcs-worker>
+
+<button data-wcs="onclick: compute">Compute</button>
+<p data-wcs="textContent: output"></p>
+```
+
+## Attributes / Inputs
+
+| Attribute          | Type    | Default    | Description                                                                 |
+| ------------------ | ------- | ---------- | --------------------------------------------------------------------------- |
+| `src`              | string  | `""`       | The worker script URL. Changing it terminates the old worker and spawns the new script. |
+| `type`             | string  | `"module"` | `"module"` (ESM) or `"classic"`.                                            |
+| `name`             | string  | `""`       | Optional worker name, passed to the `Worker` constructor `name` option (aids DevTools / error identification). Applied at spawn time — see the note on `type` below. |
+| `manual`           | boolean | `false`    | Do not spawn automatically on connect or on `src` change. Call `start()` instead. |
+| `keep-alive`       | boolean | `false`    | Do **not** terminate the worker on disconnect — it outlives the element. Ownership transfers to you: call `terminate()` to free the thread. |
+| `restart-on-error` | boolean | `false`    | Re-spawn a fresh worker after an uncaught error inside the worker script.    |
+| `max-restarts`     | number  | `Infinity` | Upper bound on the **cumulative** number of automatic restarts over the worker's lifetime (not consecutive crashes — the counter is not reset by a stable run). Reset only by a fresh `start()` / `src` change. |
+| `restart-interval` | number  | `0`        | Delay in ms before an automatic restart.                                     |
+
+### DOM trigger attributes (autoTrigger, post-on-click)
+
+| Attribute            | On             | Description                                                            |
+| -------------------- | -------------- | --------------------------------------------------------------------- |
+| `data-worker-target` | trigger button | Id of the `<wcs-worker>` to drive.                                    |
+| `data-worker-text`   | trigger button | Literal text to post (takes precedence; empty string is valid).       |
+| `data-worker-from`   | trigger button | CSS selector; posts the matched element's `value` (or `textContent`). |
+
+The DOM trigger **always posts a string** — the literal `data-worker-text`, or the resolved element's `value` / `textContent`. It is a convenience for simple text payloads and intentionally does not parse, coerce, or structure the value. To send structured-clone data (objects, typed arrays, transferables), drive `post` via the command-token protocol (`command.post: $command.run`) or call `element.post(data, transfer?)` imperatively.
+
+## Observable Properties (outputs)
+
+| Property  | Event                         | Description                                                                          |
+| --------- | ----------------------------- | ------------------------------------------------------------------------------------ |
+| `message` | `wcs-worker:message`          | The last value posted back by the worker (structured-clone copy). Re-fires on every message, even when the value is unchanged. |
+| `error`   | `wcs-worker:error`            | Normalized `{ name, message, filename?, lineno?, colno? }` — `DataCloneError` (non-cloneable post), `DataError` (a worker message could not be deserialized), `InvalidStateError` (post with no running worker), a script `Error` (uncaught error in the worker, with location), or a spawn failure (bad URL / CSP / unsupported). |
+| `running` | `wcs-worker:running-changed`  | `true` while a worker is spawned and not yet terminated.                              |
+
+## Commands
+
+| Command     | Description                                                                                  |
+| ----------- | ------------------------------------------------------------------------------------------- |
+| `start`     | Spawn the worker from the `src` attribute (terminates any previously-spawned worker; idempotent on the same `src`). |
+| `post`      | Post a structured-cloneable value to the worker (never rejects — failures go to `error`). The headless `WorkerCore.post(data, transfer?)` also accepts a transfer list. |
+| `terminate` | Terminate the worker (idempotent).                                                          |
+
+State-driven invocation uses the command-token protocol:
+
+```html
+<wcs-worker src="./compute.js" data-wcs="command.post: $command.run"></wcs-worker>
+```
+
+## Notes & limitations
+
+- **Bus-style message model.** No request/response correlation is built in; `post` is fire-and-forget and replies arrive on `message`. An RPC-style `request(data): Promise` is a possible future addition for imperative use.
+- **No "ready" signal.** A worker accepts `postMessage` immediately (the platform queues messages until the script loads), and there is no standard "script loaded" event. `running` means "spawned and not terminated", **not** "ready to serve requests". If you need a true ready signal, have the worker `post` a ready message on startup and observe it via `message`.
+- **`keep-alive` transfers ownership.** Without `keep-alive`, the worker is terminated on disconnect (like `<wcs-ws>` / `<wcs-broadcast>` close). With `keep-alive`, the worker survives disconnect and you become responsible for calling `terminate()` — otherwise the thread leaks. A consequence of this ownership transfer: with both `keep-alive` and `restart-on-error`, a restart pending at disconnect (an error that scheduled a `restart-interval` timer) is **not** cancelled and will fire after the element leaves the DOM, re-spawning a fresh worker on the now-detached element. This is intentional — `keep-alive` means the lifecycle is yours past disconnect — but it means the cleanest way to stop a `keep-alive` worker is an explicit `terminate()`, which also clears any pending restart.
+- **`restart-on-error` is opt-in and bounded.** An uncaught error inside the worker does not auto-terminate it on the platform. When `restart-on-error` is set, a fresh worker is spawned after `restart-interval` ms, up to `max-restarts` times (mirrors `<wcs-ws>` reconnect bounding). The restart counter is **cumulative over the worker's lifetime**: it counts the total number of restarts since the last `start()` and is **not** reset by a period of stable operation. So `max-restarts` bounds total restarts, not consecutive crashes — a worker that recovers and later fails again still draws down the same budget. The counter resets only on a fresh `start()` (or a `src` change, which calls `start()`). Once the budget is exhausted, calling `start()` again with the **same** `src` is idempotent and will not re-spawn — call `terminate()` then `start()` (or change `src`) to reset the counter and spawn fresh. **Set `max-restarts` when using it** — the defaults (`max-restarts="Infinity"`, `restart-interval="0"`) mean a worker that throws immediately on load will re-spawn in a tight `setTimeout(0)` loop, flooding `wcs-worker:error` / `wcs-worker:running-changed` and starving the main thread. A small positive `restart-interval` and a finite `max-restarts` bound the blast radius.
+- **A restart does not replay `post` state.** Each restart calls `new Worker(src)` and produces a *fresh* process with no memory of prior messages; the Core does not re-send any earlier `post`s. If a worker needs initialization state to function (a config message, a transferred port), it must request or rebuild it on startup (e.g. `post` a ready signal and have the page reply), because restart-on-error will not re-deliver it.
+- **`src` is observed; `type` / `name` are applied at spawn.** Changing the `src` attribute while connected (and not `manual`) terminates the old worker and spawns the new script; only a non-empty new value triggers the switch. `type` and `name` are read at spawn time and are **not** in `observedAttributes` — changing them on an already-running worker has no effect until the next spawn (a `src` change, or a `terminate()` + `start()`). Likewise, re-calling `start()` with the same `src` is idempotent and ignores changed options.
+- **Transferables are an escape hatch.** `transfer` (ArrayBuffer ownership, MessagePort) cannot be expressed through `data-wcs` data wiring. Use the imperative `element.post(data, transfer)` (or `WorkerCore.post(data, transfer)`); the declarative layer carries structured-clone data only.
+- **Silent failure handling (zero-log).** Consistent with wcstack's zero-dependency philosophy, `<wcs-worker>` never logs or throws for runtime failures. A bad script URL, a CSP `worker-src` block, a non-cloneable post, a deserialization failure, and an uncaught worker error are surfaced only through the `error` property / `wcs-worker:error` event — `post()` returns and never rejects. Bind `error` to observe and react.
+- **`src` runs as code — trust it.** The `src` value is passed straight to `new Worker(src)`, which executes the script with the page's privileges; the tag does not validate or sandbox the origin. Only point `src` at scripts you trust (treat it like a `<script src>`), and prefer a `Content-Security-Policy` with an explicit `worker-src` allowlist to constrain where workers may load from — especially if `src` can be influenced by data binding.
+- **Dedicated Worker only.** SharedWorker and Worklets are out of scope for this tag.
+
+## Headless usage (`WorkerCore`)
+
+The Core has no DOM dependency beyond the global `Worker` and can be used directly with `bind()` from `@wc-bindable/core`:
+
+```typescript
+import { WorkerCore } from "@wcstack/worker";
+
+const core = new WorkerCore();
+core.addEventListener("wcs-worker:message", (e) => {
+  console.log((e as CustomEvent).detail); // the value posted back by the worker
+});
+
+core.start("./compute.js");
+core.post({ task: "sum", values: [1, 2, 3] });
+// transfer an ArrayBuffer (ownership moves to the worker)
+const buf = new ArrayBuffer(1024);
+core.post(buf, [buf]);
+// ...later
+core.terminate();
+```
+
+## License
+
+MIT

package/dist/auto.js

@@ -0,0 +1,3 @@
+import { bootstrapWorker } from "./index.esm.js";
+
+bootstrapWorker();

package/dist/auto.min.js

@@ -0,0 +1,3 @@
+import { bootstrapWorker } from "./index.esm.min.js";
+
+bootstrapWorker();

package/dist/index.d.ts

@@ -0,0 +1,252 @@
+interface ITagNames {
+    readonly worker: string;
+}
+interface IWritableTagNames {
+    worker?: string;
+}
+interface IConfig {
+    readonly autoTrigger: boolean;
+    readonly triggerAttribute: string;
+    readonly tagNames: ITagNames;
+}
+interface IWritableConfig {
+    autoTrigger?: boolean;
+    triggerAttribute?: string;
+    tagNames?: IWritableTagNames;
+}
+interface IWcBindableProperty {
+    readonly name: string;
+    readonly event: string;
+    readonly getter?: (event: Event) => any;
+}
+interface IWcBindableInput {
+    readonly name: string;
+    readonly attribute?: string;
+}
+interface IWcBindableCommand {
+    readonly name: string;
+    readonly async?: boolean;
+}
+interface IWcBindable {
+    readonly protocol: "wc-bindable";
+    readonly version: number;
+    readonly properties: IWcBindableProperty[];
+    readonly inputs?: IWcBindableInput[];
+    readonly commands?: IWcBindableCommand[];
+}
+/**
+ * Normalized Worker failure. `name` mirrors the underlying `DOMException.name`
+ * or `Error.name`: `DataCloneError` when a posted value (or a value the worker
+ * posted back) is not structured-cloneable, `InvalidStateError` when `post()` is
+ * called with no running worker, and a script `Error` for an uncaught error
+ * inside the worker. For a script error the optional `filename` / `lineno` /
+ * `colno` carry the `ErrorEvent` location; they are absent for the other kinds.
+ */
+interface WcsWorkerErrorDetail {
+    name: string;
+    message: string;
+    filename?: string;
+    lineno?: number;
+    colno?: number;
+}
+/**
+ * Options for `WorkerCore.start()`.
+ */
+interface WcsWorkerStartOptions {
+    /** Module ("module", default) or classic ("classic") worker. */
+    type?: WorkerType;
+    /** Optional worker name, passed to the `Worker` constructor `name` option. */
+    name?: string;
+    /** Re-spawn the worker after an uncaught error fires (default `false`). */
+    restartOnError?: boolean;
+    /** Maximum number of automatic restarts (default `Infinity`). */
+    maxRestarts?: number;
+    /** Delay in ms before an automatic restart (default `0`). */
+    restartInterval?: number;
+}
+/**
+ * Value types for WorkerCore (headless) — the observable state properties.
+ * Use with `bind()` from `@wc-bindable/core` for compile-time type checking.
+ */
+interface WcsWorkerCoreValues {
+    /**
+     * The most recent message posted back by the worker, reconstructed via
+     * structured clone (no JSON round-trip). Re-fires on every incoming message,
+     * even when the value is identical to the previous one.
+     */
+    message: any;
+    /** The last failure (post / spawn / script error / messageerror), or `null`. */
+    error: WcsWorkerErrorDetail | null;
+    /** `true` while a worker is spawned and not yet terminated. */
+    running: boolean;
+}
+/**
+ * Value types for the Shell (`<wcs-worker>`) — identical observable surface to
+ * the Core.
+ */
+type WcsWorkerValues = WcsWorkerCoreValues;
+interface WcsWorkerInputs {
+    /** The worker script URL. Changing it re-spawns on the new script. */
+    src: string;
+    /** Module ("module", default) or classic ("classic") worker. */
+    type: WorkerType;
+    /** Optional worker name (passed to the `Worker` constructor `name` option). */
+    name: string;
+    /**
+     * When present, do NOT spawn the worker automatically on connect (or when the
+     * `src` attribute changes). Spawn imperatively via `start()` instead.
+     */
+    manual: boolean;
+    /**
+     * When present, the worker is NOT terminated on disconnect — it outlives the
+     * element. Ownership transfers to the caller, who must call `terminate()`.
+     */
+    keepAlive: boolean;
+    /** When present, re-spawn the worker after an uncaught error. */
+    restartOnError: boolean;
+    /** Maximum number of automatic restarts (default `Infinity`). */
+    maxRestarts: number;
+    /** Delay in ms before an automatic restart (default `0`). */
+    restartInterval: number;
+}
+interface WcsWorkerCoreCommands {
+    start(src: string, options?: WcsWorkerStartOptions): void;
+    post(data: any, transfer?: Transferable[]): void;
+    terminate(): void;
+}
+/** Commands exposed on the Shell — `start()` reads the `src` / `type` attributes. */
+interface WcsWorkerCommands {
+    start(): void;
+    post(data: any, transfer?: Transferable[]): void;
+    terminate(): void;
+}
+
+declare function bootstrapWorker(userConfig?: IWritableConfig): void;
+
+declare function getConfig(): IConfig;
+
+/**
+ * Headless Dedicated Worker primitive. A thin, framework-agnostic wrapper around
+ * the `Worker` API exposed through the wc-bindable protocol.
+ *
+ * A Worker is a "headless async message-passing resource that owns a child
+ * thread" — structurally identical to BroadcastCore (structured-clone payloads,
+ * no wire encoding, `post` is a `state → element` command-token and an incoming
+ * `message` is an `element → state` event-token) with one extra axis: this Core
+ * *owns* the underlying resource, so `start()` / `terminate()` spawn and tear
+ * down the thread, mirroring how WebSocketCore owns its socket.
+ *
+ * Message model is bus-style (fire-and-forget `post`, observe `message`), not
+ * RPC: there is no request/response correlation. Payloads ride structured clone
+ * with NO JSON round-trip (symmetrical with BroadcastCore, deliberately unlike
+ * WebSocketCore). The Core never throws — a spawn failure (bad URL, CSP block,
+ * absent `Worker`), a non-cloneable `post` (`DataCloneError`), a `post` with no
+ * running worker (`InvalidStateError`), an uncaught worker error, and a
+ * `messageerror` all flow through the `error` property.
+ */
+declare class WorkerCore extends EventTarget {
+    static wcBindable: IWcBindable;
+    private _target;
+    private _worker;
+    private _message;
+    private _error;
+    private _running;
+    private _src;
+    private _type;
+    private _name;
+    private _restartOnError;
+    private _maxRestarts;
+    private _restartInterval;
+    private _restartCount;
+    private _restartTimer;
+    constructor(target?: EventTarget);
+    get message(): any;
+    get error(): WcsWorkerErrorDetail | null;
+    get running(): boolean;
+    private _setMessage;
+    private _setError;
+    private _setRunning;
+    /**
+     * Spawn the worker from `src`. Any previously-spawned worker is terminated
+     * first, so calling `start()` again with a different `src` switches scripts.
+     * Idempotent on the same `src` (re-spawning the script we are already running
+     * is pure churn) — this also absorbs the custom-element upgrade path where a
+     * connected element with a `src` attribute triggers both
+     * attributeChangedCallback and connectedCallback, calling start() twice. A
+     * consequence of this guard: changing only the options (`type`, `name`,
+     * restart-*) while running the same `src` is ignored — call `terminate()`
+     * then `start()` to re-spawn with new options. Never throws: a spawn failure
+     * surfaces through `error`.
+     */
+    start(src: string, options?: WcsWorkerStartOptions): void;
+    /**
+     * Post a structured-cloneable value to the worker. The optional `transfer`
+     * list moves ownership of `Transferable`s (ArrayBuffer, MessagePort, ...) — the
+     * escape hatch the declarative layer cannot express. Never throws: a
+     * non-cloneable value surfaces as `DataCloneError` and posting with no running
+     * worker surfaces an `InvalidStateError`, both through `error`.
+     */
+    post(data: any, transfer?: Transferable[]): void;
+    /** Terminate the worker. Idempotent — a no-op when none is running. */
+    terminate(): void;
+    /**
+     * Tear the Core down for a disconnected Shell: terminate the worker and reset
+     * the error shadow. Only the `error` clear is silent — it mutates the shadow
+     * without dispatching. Terminating a *running* worker still dispatches
+     * `wcs-worker:running-changed` (true→false) via `_terminateWorker`, so a
+     * dispose on a worker that was live does emit one event on the (now
+     * disconnected) element; only a no-op dispose (no worker running) is fully
+     * silent.
+     *
+     * Asymmetry by design: `_message` is deliberately NOT reset. `error` is
+     * transient state — a stale error from a previous worker would mislead after a
+     * reconnect, so it is cleared. `message` is the last value received (an event
+     * payload); it is retained as the Core's last-known datum and is naturally
+     * overwritten by the next incoming message.
+     */
+    dispose(): void;
+    private _spawn;
+    private _onMessage;
+    private _onMessageError;
+    private _onError;
+    private _scheduleRestart;
+    private _clearRestartTimer;
+    private _terminateWorker;
+    private _normalizeError;
+}
+
+declare class WcsWorker extends HTMLElement {
+    static hasConnectedCallbackPromise: boolean;
+    static wcBindable: IWcBindable;
+    static get observedAttributes(): string[];
+    private _core;
+    constructor();
+    get src(): string;
+    set src(value: string);
+    get type(): WorkerType;
+    set type(value: WorkerType);
+    get name(): string;
+    set name(value: string);
+    get manual(): boolean;
+    set manual(value: boolean);
+    get keepAlive(): boolean;
+    set keepAlive(value: boolean);
+    get restartOnError(): boolean;
+    set restartOnError(value: boolean);
+    get maxRestarts(): number;
+    set maxRestarts(value: number);
+    get restartInterval(): number;
+    set restartInterval(value: number);
+    get message(): any;
+    get error(): WcsWorkerErrorDetail | null;
+    get running(): boolean;
+    start(): void;
+    post(data: any, transfer?: Transferable[]): void;
+    terminate(): void;
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+}
+
+export { WcsWorker, WorkerCore, bootstrapWorker, getConfig };
+export type { IWritableConfig, IWritableTagNames, WcsWorkerCommands, WcsWorkerCoreCommands, WcsWorkerCoreValues, WcsWorkerErrorDetail, WcsWorkerInputs, WcsWorkerStartOptions, WcsWorkerValues };