Tsubaki で書く(actor も Tsubaki)

小さい drop なら、JS を一行も書かないでいい。ops/*.tsubaki と drop.toml の [actor] だけ置くと、 build がどの drop でも同じ殻(lib の std-actor)を着せる。殻の bytes はその lib に一枚だけあって、 drop の xpi には入らない ── xpi に残るのは、その drop 自身の宣言と logic と、殻を呼ぶ数行。 drops/hello-tsubaki がそれ(ツールバーに数字、押すと増えて pref に残る)。

ここはその道の全部。はじめの一歩は GUIDE。殻で足りないときは actor.ts の道。

drop.toml の [actor]

actors = ["hello"]          # src/hello/ops/*.tsubaki

[actor]
id = "hello-tsubaki@noraneko.app"
namespace = "noraHelloTsubaki"
version = "1.0.2"
matches = ["chrome://browser/content/browser.xhtml"]
run_at = "document_end"     # 既定

logic が答える door は三つ。返すのは全部データで、DOM も preact も出てこない:

setup() = Dict(
    "anchor" => Dict("at" => "parent", "selector" => "#nav-bar", "tag" => "hbox", "id" => "nora-hello"),
    "style"  => "#nora-hello label { ... }",
    "prefs"  => ["noraneko.hello.count"]      # 見ていてほしい pref
)

start(facts)     # facts = Dict("prefs" => Dict(名前 => 値), "url" => …)。最初の一枚
dispatch(action) # 次の一枚。押されたとき、pref が変わったとき(PrefChanged)

一枚 = frame(view) か frame(view, effects)。view は el(tag, props, kids) の木で、 "on:command" => Action の値は closure ではなく action そのもの(closure は postMessage を越えない)。 殻が押されたときにそれを dispatch へ渡す — そのとき、こちら側にしか分からないこと (画面の座標、入力欄の字、押された key)を __event に入れて添える。 props はそのまま要素に渡る。inline style は "style" => Dict("width" => "320px") と Dict で (字を連ねると ; の混入を自分で見張ることになる)。

VNode / el / frame / effect たちは std のことば(std-tsubaki-runtime 0.7.0 以上の ops/std.tsubaki)。[deps] に std を書けば付いてくる。

置き場所

置き場所が二つ以上あるときは "anchor" の代わりに "anchors" に名前をつけて並べ、 view はその名前で答える。窓の中の離れた二か所 — タブの横の列と、#mainPopupSet の下の <menupopup> — は一本の木にできないので:

setup() = Dict("anchors" => [
    Dict("name" => "sidebar", "at" => "before", "selector" => "#tabbrowser-tabbox", "tag" => "hbox"),
    Dict("name" => "menu",    "at" => "parent", "selector" => "#mainPopupSet",      "tag" => "menupopup")
])

view(s) = Dict("sidebar" => …, "menu" => …)

鍵を一つ取る

置き場所に "at" => "keyset" を書く。<key> は窓の keyset の直の子でないと Firefox が見てくれないので、 そこだけ selector ではなく場所の名前で言う(殻が #mainKeyset の隣に、この drop 自身の <keyset> を立てる)。

setup() = Setup(anchors = [
    Anchor(name = "mark", at = "parent", selector = "#browser", tag = "hbox", id = "nora-zen"),
    Anchor(name = "keys", at = "keyset", id = "nora-zen-keys")
])

view(s) = Dict("mark" => …, "keys" => el("key", Dict("combo" => "Accel+Alt+Z", "on:command" => Toggle())))

押しかたは combo の一つの字で書く。keycode / key / modifiers の三つに綴り直すのは殻で、 同じ字が drop.toml にも並ぶ:

[permissions]
keys = ["Accel+Alt+Z"]

Accel は、どこでも同じ指(Windows と Linux は Ctrl、macOS は Cmd)。F2 のように名前のある鍵と、 Z のような一文字が書ける。宣言に無い組み合わせは、その <key> だけ置かれない — 他の鍵と view の残りはそのまま動いて、console に一行出る。入れる人の画面には 「キーボードの Accel+Alt+Z を、この drop が受け取ります」と出る。

ツールバーに置く

"at" => "toolbar"。殻が CustomizableUI の widget を一つ作って、それぞれの窓に自分のぶんを渡す:

setup() = Setup(anchors = [Anchor(at = "toolbar", area = "nav-bar", id = "nora-undo-closed-tab")])

view() = el("toolbarbutton", Dict("label" => t(:label), "on:command" => Undo()))

area は最初に置く場所で、書けるのは abi/v1.json の toolbar_areas にある名前 (nav-bar / TabsToolbar / PersonalToolbar / widget-overflow-fixed-list)。 知らない名前は nav-bar に落ちる。

そのあとどこに居るのかは、drop には分からない。 入れた人が customize mode で動かした場所を ブラウザが覚えていて、drop が言えるのは「最初はここに」だけ。減らした機能ではなく、そういう 約束 ── 位置は入れた人のもの。

片づけも drop の仕事ではない。widget はアプリに一つで、窓を一つ閉じただけで全部の窓から ボタンが消えては困るので、外すのは drop を外す側(Drops.sys.mts)がする。

設定の一枚を持つ

"at" => "settings" を書いて、drop.toml の matches に設定の頁も足す。 about:nora:settings が、入っている drop ごとに空の箱を置いていて、その drop の一枚がそこに入る:

[actor]
matches = ["chrome://browser/content/browser.xhtml", "chrome://noraneko-settings/*"]
setup() = Dict("anchors" => [
    Dict("name" => "sidebar", "at" => "before", "selector" => "#tabbrowser-tabbox", "tag" => "hbox"),
    Dict("name" => "settings", "at" => "settings")
])

view(s) = Dict("sidebar" => …, "settings" => …)

置き場所のほうに行き先が書いてあるので、窓の置き場所は設定の頁に出ないし、 設定の一枚は窓に出ない。view は、どちらでも同じ名前で答えればいい。

二つの document は logic を別々に持つ(memory は分け合わない)。話が合うのは pref のほう -- 片方が SetPref すると、もう片方は見ていた pref が動いたのを聞いて、 その場で描き直る。窓どうしが前から合っているのと、同じ仕組み。

中身はいまの語彙だけで書ける(pref を読む・書く、view を描く)ので、足したのは場所だけ。 設定の頁は HTML の document なので、そこの view は div / label / input / span で書く(窓のほうは XUL)。要らない drop は何も書かなくてよく、空の箱は畳まれて出ない。

できること(effect)

殻が carry out できる effect は、いまのところ 18:

effect すること
SetPref(name, value) 設定を書く ── 宣言 prefs
OpenURL(url) web の URL をタブで開く(http/https だけ) ── 宣言 open_url
Ask(fields, action) 事実を訊く(要る permission は facts の側)
Measure(selector, action) 自分が置いたものの大きさを測る
OpenPopup(selector, x, y) 自分が置いた menupopup を開く
ReloadFrame(selector) 自分が置いた窓を読み込み直す ── 宣言 web_frame
DoCommand(name) ブラウザの命令を一つ実行する ── 宣言 commands
SetTabAttr(tab, name, value) / ClearTabAttr(tab, name) タブに、この drop の目印 ── 宣言 tab_marks
SetTabValue(tab, key, value) / ClearTabValue(tab, key) タブに、この drop の覚書 ── 宣言 tab_values
Prompt(tab, action, value, placeholder) 名札のところに、字を打つ欄 ── 宣言 prompt
HideTab(tab) / ShowTab(tab) タブを仕舞う / また見せる ── 宣言 tabs = "write"
SelectTab(tab) そのタブを選ぶ ── 宣言 tabs = "write"
SetWindowValue(key, value) / ClearWindowValue(key) 窓に、この drop の覚書 ── 宣言 window_values
Log(text) console に一行

これで足りないものは actor.ts を書く(REFERENCE-ACTOR)。狭いのはわざと: この一覧が、入れる人に「この drop は何ができるか」を約束する。

ブラウザ自身の命令は DoCommand 一つで届く。名前は abi/v1.json の commands にある綴りで、 同じ名前を drop.toml にも並べる:

[permissions]
commands = ["back", "forward", "restore-last-tab"]
update(s, a::Run) = Step(s, [DoCommand("back")])

門は二つ。宣言に有ることと、表に有ること。どちらか片方でも欠けたらしない ── 綴りを間違えても、ブラウザの知らない口が開かない。入れる人の画面には、名前ではなく 表の日本語が並ぶ(「戻る、進む、閉じたタブを戻す」)。

ブラウザ自身のページを窓に出すときは、<browser> に URL ではなく 名前を書く:

[permissions]
web_frame = true
browser_pages = ["bookmarks", "history", "downloads", "library"]
el("browser", Dict("page" => "bookmarks"))

門は命令と同じ二つ ── 表に有ることと 宣言に有ること。だから drop は chrome:// の綴りを 一度も書かないし、任意の chrome: を開く口にもならない。表は abi/v1.json の browser_pages。

読み込む窓の作りも変わる。ブラウザ自身のページは remote な窓では開かないので、 殻がその場(親)で読む窓にする ── Firefox 自身のサイドバー(#sidebar)と同じ着せかた。 web の URL(src)のほうは今までどおり content の、別のプロセスの窓。

表は Floorp の mouse-gesture の 94 個から来ていて、gecko- を落とした綴りのまま。 ページを scroll する八つは content の actor が要るのでまだ無く、窓を開け閉めするものは 別の宣言になる。

タブのこと

タブは、この drop が置いたものではない。だから触れるのは 自分が付けたものだけ ── 見える目印(attr)と、残る覚書(value)、それと名札のところに出す欄。タブそのものは id(殻がこの窓のために鋳った不透明な字)としてしか見えない。

[permissions]
tabs = "read"        # 一覧を読む。開いた / 閉じた / 選ばれた を知る
tab_marks = true     # 自分の目印を付ける(CSS で拾える)
tab_values = true    # 自分の覚書を残す(閉じて開き直しても付いてくる)
prompt = true        # 名札のところに、字を打つ欄

tabs は 段のある宣言。"read" は読むだけ、"write" はタブを選ぶ・仕舞う・また 見せるところまで。入れる人の画面には、その段の一文だけが出る。段が足りない drop は 組むところで止まる(check-drop.rb が、どの effect がその段を要っているかを言う)。

setup() = Setup(
    anchors = [...],
    watch = Watch(tabs = ["open", "restore", "close", "select", "dblclick"]),
    tab_values = ["name"]        # 読み戻す覚書の鍵
)

出来事は一つの action にまとまって来る:

Dict("__type" => "TabsChanged", "kind" => "open", "tab" => そのタブ, "tabs" => 一覧)

一枚のタブは Dict("id" =>, "index" =>, "title" =>, "url" =>, "pinned" =>, "selected" =>, "hidden" =>, "muted" =>, "discarded" =>, "group" =>, "container" =>, "values" =>)。 url は current_url も宣言した drop にだけ入る(それ以外は空の字)── Ask("url") と同じ線で、 「タブのことを読む」と「どこを見ているかを読む」は、入れる人にとって別の一文だから。

目印と覚書の名前は 短く書く。data-nora-<uuid>-name / nora.<uuid>.name に伸ばすのは殻で、 生の CSS の中の {attr} も、殻がその接頭辞に書き換える:

SetTabAttr(id, "name", "ねこ")     # → .tabbrowser-tab[{attr}name]
SetTabValue(id, "name", "ねこ")    # → 再起動しても、そのタブに

だから drop は自分の uuid を一度も綴らないし、二枚の drop が互いの目印を消し合うことも、 Firefox 自身の覚書を踏むことも、構造的に起きない。

Prompt は、打ち終わると Dict("__type" => action, "tab" => …, "value" => 打たれた字) で返ってくる。 Escape で閉じたときは 何も来ない(打っていた字はどこにも残らないので、届けてもすることが無い)。

タブを仕舞う、そして戻ってくるとき

タブを束にして切り替える drop(workspaces のような)は、三つを順に使う。順が大事です ── 先に選んで、あとで仕舞う。選ばれているタブは本体が仕舞わないので、逆にすると 一枚だけ残ります。

SelectTab(id)     # 新しい束の、どれかを選ぶ
HideTab(id)       # 前の束のぶんを仕舞う
ShowTab(id)       # 新しい束のぶんを見せる

「いまどの束を開いているか」はタブ一枚に属さないので、窓の覚書に置きます (window_values)。置き場所が窓なだけで、作法はタブの覚書と同じ:

setup() = Setup(
    window_values = ["ws"],          # 読み戻す鍵。start(facts) の `window` に入って届く
    tab_values = ["ws"],
    restore = Restore(hide_unless = "ws")
)

restore が、前回から戻ってくるタブの迎えかた。marks はその覚書を持って戻って きたタブに同じ名前の目印を、hide_unless はその覚書が窓の覚書と違うタブを仕舞ったまま 戻します。戻ってきてから仕舞い直すのでも動きますが、そのときは 一瞬ぜんぶ見える ── 本体は戻すタブをまとめて挿すので、殻はその同じ turn の中で焼きます。だから logic には訊かれません(worker の返事を待つ時間が無い)。決めるのは logic、するのは殻。

facts に window が入っているかどうかは、「ここは窓か」の合図でもあります。設定の頁に 同じ logic が居るとき、そちらには窓のタブが無いので。

この drop が仕舞ったタブは、drop を外すと見せて返します(タブ帯から消えたタブを戻す道が、 外した人の手元に無くなってしまうので)。窓を閉じたときは返しません ── そのときの仕舞われかたは、 その窓の姿として SessionStore が持っていくものだから。

本体の menu に行を混ぜる

"at" => "menu":

[permissions]
menu = ["tabContextMenu"]
Anchor(name = "menu", at = "menu", menu = "tabContextMenu", id = "nora-rename-tab-menu")

行は popup の 末尾に足される(本体の行は動かさない)。その menu が「何についての menu か」を abi/v1.json が知っているので、押されたタブの目印が host に写る ── 名前のあるタブのときだけ 出したい行は、CSS の側で閉じられる:

#nora-rename-tab-menu:not([{attr}name]) .nora-rename-clear { display: none; }

popupshowing は待てないので(worker の返事を待つあいだに popup は塗られてしまう)、 ここが一往復も要らないのは、そのための形。その行から起きた action には、どのタブのことかが __event の tab に入って届く。

要素(tag)

tag も同じように決まっている。 view が名乗れるのは殻(drops/std-actor/src/lib/vnode.ts)の ELEMENTS にある顔ぶれだけ(箱、ラベル、ボタン、メニューの行 — どれも何も読み込まないし、何も走らせない)。 知らない tag は、その場で止まる。約束が「effect の一覧」で済むのは、要素のほうがおとなしいからで、 そこが開いていると「データと既知の殻を読めばいい」が成り立たない。 足したい要素があれば registry に PR を(読むのは、drop を読むのと同じ人たち)。

訊く(Ask と Measure)

Ask と Measure は、命令ではなく質問。logic は事実を作らない、が守りたい線なので (新しい uuid も、いま見ているタブの URL も、drag のあとに箱が実際になった幅も、 logic には分からない)、action に穴を開けて殻に埋めさせるのではなく、訊いて、名前を つけた action で返してもらう。返事は普通の dispatch で来る:

update(s, a::AddClicked) = Step(s, [Ask(["uuid", "url"], "AddPanel")])
# → dispatch(Dict("__type" => "AddPanel", "uuid" => …, "url" => …))

update(s, a::DragEnded) = Step(s, [Measure("#nora-webpanel-box", "SetWidth")])
# → dispatch(Dict("__type" => "SetWidth", "width" => 321, "height" => 640))

いま訊ける事実は "uuid"(新しい uuid)、"url"(いま見ているタブの URL。 http/https でなければ "")、"tabs"(この窓のタブの一覧)、"tab"(いま選ばれているタブ)。 あとの二つは tabs = "read" が要る。Measure の selector は その drop が置いた host と その中だけを探す — 自分が描いたものを測る。

ページを読み込む窓(<browser>)

一つだけ、宣言してから使う要素がある。drop.toml の [actor] に:

[actor]
...
web_frame = true      # view に <browser> を書ける

と書くと、view が browser を名乗れる。入れる人の画面には「ページを読み込む窓を置く」と 出る(actor.json の webFrame)。view が書くのはどこに置くか・何を読むかだけ:

el("browser", Dict("key" => p.id, "src" => p.url, "flex" => "1"))

type="content" / remote="true" などの「どんな窓か」を決める九つの属性は、 殻が着せる(drops/std-actor/src/lib/vnode.ts の WEB_FRAME_ATTRS)。九つあれば一つ忘れるし、 これは view を書いていて忘れてよい種類のまちがいではないので。src は OpenURL と 同じ規則で http/https だけ — ほかは空の窓になる。

key を必ず書く。preact は key で「同じもの」を見分けて、位置が変わったときに moveBefore(取り出さない移動)で動かす。key が無いと作り直しになって、読み込んだページが 消える。この移動は std-preact-xul 1.1.0 から(<video> や、字を打っている <input> も 一緒に助かる)。

reload() や、ページの題が変わったことを logic に伝える口は、まだ無い。要るなら actor.ts を書く道がある。

logic を分けたいとき(import)

ops/ は一枚でなくていい。分けたぶんを module にして、import と書く:

# ops/Style.tsubaki
module Style
    sheet() = "…"
end

# ops/webpanel.tsubaki
import Style
setup() = Dict("style" => Style.sheet(), …)

その import の一行が、読む順を決めている。 Tsubaki の import Shapes は 「訊いた file の隣の Shapes.jl / Shapes.tsubaki を読む」だけれど、drop の logic は file の無い worker で動く。だから 読むのは build(tooling/webext-actors/build.ts の opsFiles): using / import の行をたどって、import されたほうを先に置く。drop が 走るときには module がもう有るので、import は何も探さずに見つける。

書き換えも貼り合わせもしない。読まれる file は、書いた人が書いた file そのまま (xpi の source/ と同じもの)。置き場所は ops/ の中で横並び —— それが import の 探す場所だから、path を書くことも、dir を作ることも無い。