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 にメインプロセスのコードは入らない、その逆も)。
約束
- module の top level は純粋に。
Services/ChromeUtils/windowなどは関数の中だけで触る。build がmetaを読むために Deno で import するので、top level で触ると build が落ちる。 - 置くのは
ctx.ioとmountを通す。import { h, mount } from "std"。host を置いて preact で描く。外したとき、置いたものは自分で戻る(LAYERS)。_shared/は tooling のもので、drop から足せない。CSS は文字列で持ってctx.io.style。 - 読める形で。 build は minify しないし、一行 400 字を超える JS があれば断る。preact は
stdから来る(drop に同梱されない)。他の依存を持ち込むなら、library drop にするか、その source を自分の src に写す(vendored で見える形)。 - 短く。 DOM を触るのは JS で間違いないけれど、JS の分量は最小に。大きい logic は将来 WASM(
.tsubaki)に分ける絵。
ctx にあるもの
ctx.expose({ fn })— ページのwindowに関数を生やす(exportFunction)。ctx.io.place / style / listen / pref / defer— 置くと、戻しかたが台帳に積まれる。置くのはここを通す。mount(ctx.io, view, at)(std)— host を置いて preact で描く。外れるとき view の unmount → host の remove。ctx.ops—[deps]にstdがあれば Tsubaki の runtime。await ctx.ops.load("ops/x.tsubaki")→ctx.ops.call("f", ...)。 Tsubaki の中からはjsglobal("console")で sandbox の global に手が届く(std-tsubaki-runtime0.2.0 から)。 あるのはconsole/fetch/URL/TextDecoder/TextEncoderと、glue のための偽のdocumentだけ。 窓の DOM はここには無い(そこはctx.ioとmountの仕事)。ctx.onDestroy(fn)— 上で表せないものを、手で戻すとき。ctx.dev— dev build なら true。
三つの形
| 形 | 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 も手の届くところ)。
await window.delayedStartupPromiseしてから触る(gBrowser が揃うのを待つ)。chromehiddenに toolbar が入る窓(popup)では何もしない。- Firefox は
#browserの子を CSSorder1〜7 で並べている。右に置くなら 8 以降。 - 置いたもの(DOM、style、observer、listener)は
ctx.io/mountを通すと自分で戻る。外したあとに残るのは、いちばん嫌なこと。 <browser>は preact に作らせてよい(std-preact-xul 1.1.0 から、並び替えがmoveBefore= 取り出さない移動になった。insertBeforeは同じ位置へでもページを作り直す)。ただしkeyを必ず。actor.ts を書いて手で持つ道も閉じてはいない。- 入れる人の画面には「ブラウザの窓そのものに効く」と出る。渡す力が大きいぶん、レビューも重い。
三つ目の形を JS なしで書くのが Tsubaki の道。