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("押された")])   # 次の一枚と、してほしいこと

返すのは全部データで、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. 出す

  1. PR に drop.toml と src/ だけを入れる(manifest.json などは CI が main で書く)。
  2. CI(verify)が Linux で build する。手元の mac と 同じ sha256 が出ることが約束(ずれたら BUILD で追う)。
  3. 人がレビューする。読むのは: 何をするか(parent / content の役割)、どこで動くか、fetch の向き先、eval の有無、chrome API。
  4. main に入ると、管理者の承認のあとで CI が判を押し、配られる(dl.f3liz.casa/drop/<uuid>/)。
  5. 更新は同じ dir に PR。版は <meta.version>.<commit の分> で自動的に上がる。

似すぎる名前は断られる。

5. もっと知る