drop を作る(はじめての人へ)
drop は、noraneko に コード一つで降ってくる機能。中身は小さな xpi(入れ物)と JSWindowActor(ページや窓への道)で、Firefox 自身の about:newtab と同じ形。
いちばん前に置いているのは「入れる本人が中身を読める」こと。だから、読める形で書く (minify 無し、一枚、依存を持ち込まない)。PR の diff がそのまま「実際に xpi になる source」で、 レビューはそれを読む。
書く道は二つ。ふつうは Tsubaki(JS を一行も書かない)。殻で足りないときだけ actor.ts(JS)を書く。
この頁は、Tsubaki で最小の drop を動かすまで。細部はリファレンスへ。
1. 置く場所
drops/<name>/drop.toml uuid / name / note / contact / actors(と [actor] / [deps])
drops/<name>/src/<actor>/ops/*.tsubaki 決めることを書く(窓も pref も知らない。純粋)
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"]
[actor]
id = "hello@noraneko.app"
namespace = "noraHello"
version = "1.0.0"
matches = ["chrome://browser/content/browser.xhtml"]
run_at = "document_end" # 既定
[deps]
std = "0064c162-13ac-458e-80ef-e73b1bc49a24" # 殻と Tsubaki のことば
[compat]
std = "1"
name は札で、uuid が正体。別の registry に同じ名前があっても、uuid が違えば別のもの。
deps / compat の読みかたは LAYERS。
2. ops/main.tsubaki の形
書くのは一枚。殻が訊いてくる door は三つだけ。
# どこに置くか。ここでは #nav-bar の中で、hbox 一つ
setup() = Setup(
anchors = [Anchor(at = "parent", selector = "#nav-bar", tag = "hbox", id = "nora-hello")]
)
# 押されたこと。それだけ
struct Bump end
# 描くもの。"on:*" の値は closure ではなく action そのもの
view() = el("label", Dict("value" => "こんにちは", "on:click" => Bump()))
start(facts) = frame(view()) # 最初の一枚
dispatch(a) = frame(view(), [Log("押された")]) # 次の一枚と、してほしいこと
setup()— どこに置くか、style、見ていてほしい pref。start(facts)— 最初の一枚。factsはもう本当のこと(pref や url)。dispatch(action)— 次の一枚と、してほしいこと(effect)。
返すのは全部データで、DOM も preact も出てこない。押されたときに殻が action を dispatch へ渡し、
こちらにしか分からないこと(座標、入力欄の字、押された key)を __event に添えて返す。
決めるのは Tsubaki、するのは殻。 窓に触るのは殻の仕事なので、drop は「どこに・何を」だけを言う。
置き場所の種類、effect の一覧、設定の一枚、タブ、<browser>、import は
Tsubaki のリファレンス に全部あります。
実物は drops/hello-tsubaki(いちばん小さい、JS 無し)と
drops/undo-closed-tab(押すと命令を一つ)。
3. 手元で動かす
mise install && npm install
mise exec -- ruby scripts/dev.rb drops/<name>
これが書いているあいだの輪。drops/<name>/ と殻を見張っていて、変わったら組み直して、
手元の棚(http://127.0.0.1:8765/drop)に置く。出るのは一行:
14:32:05 hello 1.0.0.22138980 を組んだ(1.7 秒)
版の四つ目は「手元で組んだ印」。同じ版のまま bytes が替わって古い module が動く穴を 塞ぐ。CI はこの旗を通らないので reproducible の約束はそのまま(踏んだ話は TRAPS)。
noraneko 側の設定(棚をブラウザに繋ぐ)は一度だけ ── SHELF。
これで、輪が閉じる:
ops/main.tsubaki を保存 → 2 秒で組み上がる → 数秒で窓の中が新しくなる
ブラウザを建て直す必要はない。外すのも settings から ── 外したあと、窓に何も残っていないかを、ときどき見てください。
一度だけ組むときは ruby scripts/build.rb drops/<name>。実機で一周させる道具は
ruby scripts/lap.rb drops/<name>。詳しくは BUILD と TRAPS。
4. 出す
- PR に
drop.tomlとsrc/だけを入れる(manifest.jsonなどは CI が main で書く)。 - CI(
verify)が Linux で build する。手元の mac と 同じ sha256 が出ることが約束(ずれたら BUILD で追う)。 - 人がレビューする。読むのは: 何をするか(
parent/contentの役割)、どこで動くか、fetch の向き先、eval の有無、chrome API。 - main に入ると、管理者の承認のあとで CI が判を押し、配られる(
dl.f3liz.casa/drop/<uuid>/)。 - 更新は同じ dir に PR。版は
<meta.version>.<commit の分>で自動的に上がる。
似すぎる名前は断られる。
5. もっと知る
- Tsubaki のリファレンス: REFERENCE-TSUBAKI — 置き場所、18 の effect、タブ、設定、
<browser>、import - actor.ts(JS)のリファレンス: REFERENCE-ACTOR — 殻で足りないときの道
- 層と片づけの約束: LAYERS —
io/の台帳、依存関係、compat - xpi ができるまで: BUILD / 罠: TRAPS / 次にやること: NEXT
- 手元の棚を繋ぐ(一度だけ): SHELF — noraneko 側の pref と settings
- 形の元(なぜ JSWindowActor か、addon 式が駄目だった理由): noraneko の
browser-features/webext-actors/README.md - 実物:
drops/hello-tsubaki(JS 無し、いちばん小さい)、drops/newtab(actor.ts一枚)、drops/newtab-hello(view は preact、言葉は Tsubaki)、drops/webpanel(JS 無しで窓に UI を置く。二か所の root、Ask/Measure、<browser>、import)