actor.ts で書く(JS)

Tsubaki の殻(REFERENCE-TSUBAKI)で足りない drop は、 actor.ts を一枚書く。ここはその道の細部。ふだんは GUIDE で足りる。

置く場所

drops/<name>/drop.toml               uuid / name / note / contact / actors(と [deps] / [compat])
drops/<name>/src/<actor>/actor.ts    書くのはこれ(actor はいくつでも)
drops/<name>/src/<actor>/view.tsx    view(preact)。触るものが増えたら io/ に出す(docs/LAYERS.md)

drop.toml

drops/_example/drop.toml を写すのが早い。

uuid = "..."                # uuidgen | tr A-Z a-z で一つ振る。一度振ったら変えない(正体)
name = "hello"              # dir と同じ。この registry の中で一つ(札)
note = "何をする drop か、一行で"
contact = ["gh/you"]        # 困ったとき、誰に訊けばいいか(gh/ mail/ social/)
actors = ["hello"]          # src/<actor>/actor.ts

[deps]
std = "0064c162-13ac-458e-80ef-e73b1bc49a24"   # preact と mount、Tsubaki の runtime(札 = uuid。版は build が固定)
[compat]
std = "1"                   # 1.x でよい(Julia と同じ読みかた)

deps / compat の読みかたと台帳の仕組みは LAYERS。

actor.ts の形

import { defineContent, defineParent, type ActorMeta } from "../_shared/defineActor.ts";

export const meta: ActorMeta = {
  id: "hello@example.org",          // 拡張の id
  version: "1.0.0",
  namespace: "hello",               // 名前(いまは表示だけ)
  matches: ["about:newtab*"],       // content が動くページ(JSWindowActor の matches)
  runAt: "document_end",            // document_start / document_end / document_idle
};

// メインプロセスで動く。Services も ChromeUtils も使える(= 何でもできる。だからレビューはここを一番読む)
export const parent = defineParent({
  async count(): Promise<number> { return 1; },
});

// ページ側。window / document をそのまま使える。parent.xxx() はメインプロセスへの往復(Promise)
export const content = defineContent<typeof parent>((parent, ctx) => {
  window.addEventListener("DOMContentLoaded", async () => {
    const n = await parent.count();
    document.title = `hello ${n}`;
  });
});

三つの export を名前で出す。build が parent と content を別々に束ねる(ページ側の bundle にメインプロセスのコードは入らない、その逆も)。

約束

ctx にあるもの

三つの形

形 matches 例
ページに特権のデータを渡す about:newtab* など drops/newtab(NewTabUtils のデータを event で渡す)
ページに関数を生やして双方向 chrome://noraneko-settings/* など noraneko の settings-bridge(pref の読み書き)
ブラウザの窓そのものに UI を置く chrome://browser/content/browser.xhtml drops/webpanel(タブの横にウェブページ。JS は一行も無い)

三つ目は特別。matches に chrome://browser/ を書くと、build が includeChrome: true を付け、content hook が ブラウザの窓の中で動く(window は ChromeWindow。gBrowser も Services も手の届くところ)。

三つ目の形を JS なしで書くのが Tsubaki の道。