実行可能セル
実行可能セルは、先頭に metadata comment を持つ通常の MDX code block です。Oxiquill は生成時にその block を抽出し、runtime UI に置き換えます。
Rust セルは build 時に WebAssembly に compile されます。Python セルは browser の Pyodide worker で動きます。Haskell セルは build 時に WASI WebAssembly module に compile されます。3つの言語は同じ input metadata と run mode model を使います。
再実行中も最後に成功した出力を保持し、失敗時にはエラーと再試行操作を併記します。キャンセルや入力不正でも出力を消しません。互換性のあるグラフは同じ canvas を更新し、既定で180msの遷移を使います。OS の動作軽減設定を優先します。style の型・制限と Rust overload は リッチ出力 を参照してください。動的な出力の並びには明示的な artifact ID を推奨します。
Fence と metadata grammar
Section titled “Fence と metadata grammar”interactive fence は rust、python、haskell(Markdown の {.rust} form を含む)を使い、legal backtick/tilde fence と indentation に対応します。metadata は fence 先頭の一つの contiguous な language-specific option-comment block です。Rust は //|////|、Python は #|、Haskell は --| を使います。最初の source line より後にある option 風 comment は source code のままです。
許可される top-level field は次だけで、unknown field は error です。
| Field | Type と rule | Default |
|---|---|---|
ref | 任意の安定した参照名。64文字以内の lowercase kebab-case。同じ locale のセルと見出し全体で一意。 | None |
id | 必須の lowercase kebab-case ^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$。page 内と route scope 後で unique。 | — |
title | cell header に表示する non-empty string。明示した値は前後の空白を除去。 | id |
run | button、reactive、autorun。 | button |
inputs | ^[a-z][a-z0-9_]*$ に一致する lowercase cross-language identifier から input spec への mapping。autorun では禁止。 | {} |
cases | 名前付き入力プリセットの配列。autorun では指定できません。 | [] |
packages | unique non-empty Pyodide package name。Python 専用。 | [] |
crates | cratesDir 直下の helper package name の unique non-empty list。Rust 専用。 | [] |
timeoutMs | 1 以上 2147483647 以下の integer millisecond。 | 30000 |
showSource | initial source visibility を指定する boolean。 | true |
outputLayout | stack、または幅の広いセルでグラフと画像を同じ行に並べる columns(出力の配置)。 | stack |
editable | 読者がローカルの draft を編集・実行できるかを指定する boolean。Python 専用。 | true |
setup | 入力を持たない同じページの Python セル ID を一つ指定。python.experimentalSetup: true が必要。 | なし |
source には metadata 以外の code が必要です。malformed YAML、wrong scalar/collection type、duplicate normalized ID/binding/function、unknown package/crate、language-mismatched dependency field は output を書く前に失敗します。diagnostic は page path、fence start line、可能なら cell ID、正確な field path を含みます。
Haskell cell は standard-library code のみで packages/crates を受け付けません。helper 不要の Rust example では crates: [] を明示します。package/crate list は strict validation 後に deduplicate/sort されます。
Run mode
Section titled “Run mode”button: input と Run button を表示し、mount 時は実行しません。reactive: input を表示して Run button を隠し、mount 時に一度実行します。その後は 150 ms trailing debounce を使い、active execution 一つと最新 replacement 一つだけを保持します。autorun: input/Run button を表示せず、各cell.id + runtimeVersion + sourceについて正確に一度だけ実行します。開発中は runtime-version の更新が先に届いた場合も、source の更新によって前回の実行結果を無効化します。
次の button cell は、input を変更しても明示的に実行するまで待機します。
Rust + Wasm
Explicit button execution
次の autorun cell には実行 control がなく、現在の生成 runtime に対して1回だけ実行されます。
Rust + Wasm
One-time autorun execution
println!("autorun ready");Waiting for the runtime to start.
reactive run が supersede されると、その worker request を active に cancel し、worker recycle の影響を受ける全 request を reject して timer を除去します。debounce 後は最新の complete value だけを実行します。cancellation は execution error として表示されず、stale result は新しい state を上書きしません。timeout/worker fault も同じ deterministic recycle boundary で回復します。unmount は pending/active work を cancel します。
Input schema
Section titled “Input schema”各 input が受け取るのは type に関係する field だけです。共通 field は type、label、description、value。numeric input は min、max、step、integer、select/radio は options も使います。
| Type | Value と constraint |
|---|---|
range, number | finite number。step > 0、min <= max、default が bound 内かつ step grid 上。 |
integer | -2147483648 以上 2147483647 以下の signed 32-bit integer。bound/step も同じ domain。 |
text, textarea | string value。 |
checkbox | boolean value。 |
select, radio | non-empty unique string option または { label, value } object。default は option value と一致。 |
type の default は text、label の default は input name です。description は control と assistive technology 向けに関連付ける optional non-empty string です。default value は checkbox が false、numeric input が 0、text input が空 string です。numeric 専用 field は non-numeric control で拒否され、options は select/radio 以外では使えません。
signed 32-bit integer domain は JavaScript で正確に表現でき、Rust i32、Haskell Int、Python int に同じ値として渡されます。domain 外の integer value、min、max、step は authoring 時に拒否されます。browser control と worker request も、integer: true の numeric input を含めて同じ domain を適用します。
numeric default は browser control と同じ step grid に揃える必要があります。effective step は step があればその値、なければ 1 です。grid の base は min があればその値、なければ明示または default の numeric value です。Oxiquill は不一致の default を丸めたり clamp したりせず、authoring 時に拒否します。
number/integer control は raw edit text と committed runtime value を分離します。空、入力途中、non-finite、range 外、step 不一致の text は表示を保ちますが cell input を更新しません。どれか一つでも invalid なら Run button は disabled になり、reactive execution は validity が戻った後に最新の complete value set を一度だけ実行します。range label の表示精度は step から決まります。
visible label が control の accessible name で、input key は generated language binding にだけ使います。normalization で二つの Rust/Haskell binding が衝突してはなりません。label、description、current value、validation message、grouped control は stable ID で関連付けられ、keyboard focus を表示し、run/error status は focus を奪わず announce されます。
Pythonセルでは「Pythonを編集」でtextareaを開けます。セルにeditable: falseを指定すると、このボタンを表示しません。編集中はreactiveセルでもコードと入力の変更を自動実行せず、「実行」を待ちます。「元のコードに戻す」は実行せずdraftを戻し、「編集を終了」はdraftとその出力を破棄して著者の実行モードに戻します。ページ遷移とソース更新でもdraftを破棄します。公開ページや共有リンクは変更しません。importできるのは配布済みのパッケージ、つまりいずれかのPythonセルがpackagesで宣言したものとその依存だけです。それ以外のPyodideパッケージはダウンロードせずにエラーを表示します。通常のセルのタイムアウトが適用されます。
「入力のリンクをコピー」の対象にするには、各入力のメタデータに share: true を追加します。自由記述を含め、既定では共有しません。リンクには、このページで共有を有効にした入力の既定値との差分だけを保存します。既存の検索パラメータと見出しへのリンクは保持します。不正な値や古い選択肢は復元しません。8,192文字を超えるリンクはコピーできません。コード、出力、乱数の状態、外部データは含まれず、同じ結果の再現を保証する機能ではありません。
入力のあるセルには「入力を初期値に戻す」があります。すべての既定値を復元し、入力途中の文字列と検証エラーを消去します。reactive セルは一度だけ再計算し、button セルは実行操作を待ちます。次の結果を待つ間は前の成功結果を表示します。
入力欄はセル自身の幅に収まる数の列に並びます。左右のナビゲーションを表示している場合は、画面が広くても一列になることがあります。各列の最小幅は --oq-input-column-min-width(既定値 16rem)です。列数を変えるには、starlight.customCss に登録したスタイルシートで :root に設定します。
新しい共有リンクは v: 2 を使い、各セルを { values, case? } として保存します。values は引き続き share: true の差分だけです。現在値がケースと完全に一致する場合だけ case ID を含めます。既知のケースは著者の全入力値を復元するため、share: false の入力も適用します。未知のケース ID は検証済みの共有値にフォールバックします。従来の v: 1 リンクも復元できます。
名前付き入力ケース
Section titled “名前付き入力ケース”cases で複数の入力をまとめたプリセットを宣言できます。「ケース」から選ぶと、全入力を一度に置き換えます。reactive セルは変更後の組み合わせを一度だけ実行し、button セルは「実行」を待ちます。Python の編集中も「実行」を待ちます。
各ケースにはセル内で一意の kebab-case id、必須の label、部分的な値の mapping である inputs を指定します。default は予約 ID です。description は任意の空でないプレーンテキストです。入力とケースの label は前後の空白を除去し、空でない256文字以内の文字列にします。省略した入力は現在の読者の値ではなく、宣言した既定値で補完します。すべての値に型、範囲、step grid、整数の制約、選択肢を検証します。min がなければ、step grid の基準は元の入力の既定値です。
選択表示は現在の全入力と一致するケースを示し、一致しない場合は「カスタム値」を示します。手動編集で完全に一致すればケース表示に戻ります。複数のケースが一致するときは記述順の最初を表示します。「入力を初期値に戻す」は宣言した既定値を復元します。開発中の HMR は有効な現在値を保持し、無効または追加された入力だけを新しい既定値に戻して選択表示を更新します。
乱数を使う計算では seed を通常の入力として公開し、ケースに含めることを推奨します。Oxiquill は別の seed 機構を追加しません。
Rust + Wasm
名前付き入力ケース
println!("samples = {samples}, noise = {noise:.2}, seed = {seed}, model = {model}, enabled = {enabled}");Waiting for the runtime to start.
ソースの表示領域
Section titled “ソースの表示領域”コードは固定された枠の内側でスクロールし、長い行でもページの幅を広げません。枠にはキーボードでフォーカスできます。Tabで移動し、矢印キーでスクロールしてください。どちらのテーマでもフォーカスの輪郭を表示します。
既定ではソース表示の高さに上限はありません。画面上の高さを制限するには、starlight.customCss に登録したスタイルシートに次のCSSを追加します。
:root { --oq-source-max-height: 24rem;}上限は構文強調されたソースの枠自体に適用されます。以前 .doc-source の高さを直接制限していたサイトは、代わりに --oq-source-max-height を使ってください。印刷時には上限を解除して長い行を折り返し、ソース全体を表示します。画面がダークテーマでも、印刷にはライトテーマの構文色を使います。
テキスト、JSON、エラーの出力にも同じ仕組みの --oq-output-max-height があり、既定では上限がありません。上限を設定した出力は枠の内側でスクロールし、キーボードでフォーカスでき、印刷時には全文を表示します。
:root { --oq-output-max-height: 20rem;}Rust とグラフ
Section titled “Rust とグラフ”この Rust セルは helper crate を使い、slider が変わるたびに plot を再描画します。
Rust + Wasm
Calculate the logistic map with Rust
let steps = u32::try_from(steps).map_err(|_| "steps must be non-negative".to_owned())?;
let points = doc_rust::logistic_series(r, x0, steps).map_err(|error| error.to_string())?;
for point in points.iter().take(5) {
println!("n={} x={:.6}", point.n, point.x);
}
let coordinates: Vec<[f64; 2]> = points.iter().map(|point| [f64::from(point.n), point.x]).collect();
emit_line_chart!(&coordinates, "n", "x");Waiting for the runtime to start.
Rust 入力 UI
Section titled “Rust 入力 UI”crates: [] のセルは helper crate に依存しません。この例では checkbox、select、radio input を使います。
Rust + Wasm
Rust input UI
let base_score = match operation.as_str() {
"triple" => 21_i32,
"double" => 14_i32,
_ => 7_i32,
};
let score = if include_bonus {
base_score + 5
} else {
base_score
};
println!("style = {style}");
println!("score = {score}");Waiting for the runtime to start.
複数 Rust helper crate
Section titled “複数 Rust helper crate”各 Rust セルは必要な helper crate を宣言します。名前は crates/* 配下の Cargo package name と一致させます。
Rust + Wasm
Rust cell with multiple crates
let points = doc_rust::logistic_series(3.2, 0.2, 8).map_err(|error| error.to_string())?;
let final_point = points.last().ok_or_else(|| "series is empty".to_owned())?;
println!("{}", doc_rust_text::labeled_value("final step", final_point.n));
println!("{}", doc_rust_text::labeled_value("final x", format!("{:.6}", final_point.x)));
println!("{}", doc_rust_text::style_note(style.as_str()));Waiting for the runtime to start.
Python 入力
Section titled “Python 入力”Python セルも同じ input metadata を使います。input value は Python 変数として使えます。
Python + Pyodide
Python input UI
values = [1, 2, 3, 4]
if method == "sum":
result = sum(values) * scale
elif method == "max":
result = max(values) * scale
else:
result = sum(values) / len(values) * scale
name = label.upper() if enabled else label
print(f"{name}: {method} = {result}")
print(f"style = {style}")Waiting for the runtime to start.
Haskell 入力
Section titled “Haskell 入力”Haskell セルは --| metadata comment を使います。input value は Haskell 変数になり、putStrLn や print の text output が結果 panel に表示されます。
Haskell + WASI
Haskell input UI
{- Imports may use normal multiline Haskell layout. -}
import Data.List
( intercalate
, sort
)
let base = [1 .. 4 :: Int]
let scaled = map (* factor) base
let displayed = sort (if include_squares then map (\value -> value * value) scaled else scaled)
putStrLn (label ++ ": " ++ intercalate ", " (map show displayed))
putStrLn ("total = " ++ show (sum displayed))Waiting for the runtime to start.
Python の初期化と package 読み込み中は「Python を準備中…」、執筆した code の実行中は「実行中…」と表示します。python.preload による page 単位の先読みは Python runtime asset を参照してください。
ページ内の Rust 定義
Section titled “ページ内の Rust 定義”kind: definitions で通常の Rust アイテムを一度だけ定義し、順序付きの uses で同じページ内から参照できます。定義ブロックはタイトルとソースのみを表示し、実行用の操作はありません。他のブロックから使うアイテムやフィールドには、通常 pub(crate) の可視性が必要です。
Shared model
Model helper
Rust + Wasm
First consumer
Rust + Wasm
Second consumer
Rust + Wasm
Transitive consumer
定義ブロックで指定できるのは id、kind、title、crates、uses、showSource のみです。実行セルでは kind を省略します。uses の参照先は同じページの定義 ID に限り、重複や循環参照は許可されません。現在は Rust のみ対応し、Python の setup の動作は変わりません。
インポートには通常の Rust の glob 規則が適用されます。ローカル定義による隠蔽は可能ですが、名前の曖昧さはコンパイルエラーになります。インポートは自動的に再公開されません。3 番目のセルはヘルパーとモデル関数を直接使うため、両方のブロックを列挙しています。
参照先を再帰的にたどり、必要なヘルパークレートを実行セルへ統合します。未使用の定義はメタデータと参照のみ検証し、コンパイルや依存関係には追加しません。使用中の定義を編集すると、その定義を使うページの Rust モジュールを再ビルドします。未使用の定義の編集はソース表示のみを更新します。
変更前の入力による結果
Section titled “変更前の入力による結果”出力は計算に使った入力を記憶します。入力の編集、ケースの選択、入力の復元、再実行を行うと、保持された出力に変更前の入力による結果という表示と data-stale="true" が付きます。この表示、更新中の表示、依存元の変更や再利用の表示は、行を追加せず出力の上部に重ねて表示するため、値を変更してもグラフや表の位置は変わりません。不正な数値入力でも付きます。リアクティブセルは待機・実行中も表示を維持し、ボタンセルは実行が成功するまで維持します。入力を編集すると、そのセルの実行中の計算も取り消します。結果が変更前の入力によるものになるためです。元と同じ入力に戻すだけでは消えません。キャンセル、古い応答、実行失敗でも消えず、実行エラーと古い結果を区別して表示します。現在の入力で実行が成功すると消えます。ソースやランタイムの更新でも古い結果を無効化します。
著者は 計算結果 を出力して、正常に実行された計算が条件を満たしたかを明示できます。表、グラフ、テキストと同様に古い入力の結果として表示され、実行エラーを置き換えることはありません。
ページ内のデータ依存関係
Section titled “ページ内のデータ依存関係”生成元は exports を宣言し、export!(name, value) で値を書き出します。利用側の dependsOn は生成元のエクスポートオブジェクト全体を受け取ります。セル ID だけなら変更できない &serde_json::Value、{ cell, type } なら指定した Rust 型にデシリアライズします。uses の共有型も使えます。現在は Rust のみ対応しています。
data-model
#[derive(serde::Deserialize)]
pub(crate) struct Dataset {
pub(crate) points: Vec<i32>,
pub(crate) truth: i32,
}Rust + Wasm
データ生成
let points: Vec<i32> = (0..samples).map(|n| (n + seed) % 17).collect();
let truth = seed;
println!("Generated {} points with seed {seed}", points.len());
export!(points, &points);
export!(truth, &truth);Run the cell to show its output.
Rust + Wasm
データ集計
let total: i32 = data.points.iter().sum::<i32>() + data.truth;
println!("Total: {total}");
export!(total, &total);Run the cell to show its output.
Rust + Wasm
データ分析
let total = data["total"].as_i64().ok_or("total must be an integer")?;
println!("Analysis: {}", total + i64::from(bias));Waiting for the runtime to start.
依存関係は同じページ内の非循環グラフです。セルを実行すると、必要な依存元を現在の入力で決定的な順序に従って一度ずつ計算します。画面外の生成元も復元済みまたは既定の入力で計算し、ハイドレーション後に結果を表示します。名前付きケースが変更するのは自分のセルだけです。oxiquill test-wasm は依存元を既定の入力で実行します。
生成元の入力変更は、そのセルと、リアクティブおよび自動実行の依存先を再計算します。再利用または再計算される依存元は、その間も現在の結果を表示します。ボタン実行の依存先は「依存元が変更されました」と表示して実行を待ちます。ただしリアクティブな依存先の計算に必要なら自動実行します。入力を変えずに生成元を実行または再計算した場合は、エクスポートが変わったときだけ依存先に印を付けます。入力が不正な依存先は、入力が正しくなるまで対象外になり、他の依存先は更新を続けます。入力のスナップショットが最新の場合だけ結果をまとめて公開します。生成元の失敗、タイムアウト、キャンセル時は依存先を実行せず、診断と生成元へのリンクを表示します。古いエクスポートへのフォールバックはありません。
エクスポートは表示用の出力とは別です。自動表示も共有 URL への保存も行いません。宣言したすべての値を書き出す必要があります。未宣言の値、入れ子を含む非有限数、4 MiB を超えるオブジェクトは実行エラーとなり、部分的なデータは渡しません。名前は ^[a-z][a-z0-9_]*$ に一致する必要があります。依存関係の変数名も同じ形式で、入力、生成された名前、Rust の予約語と重複できません。
明示的なプロデューサーキャッシュ
Section titled “明示的なプロデューサーキャッシュ”cache: inputs はエクスポートを宣言した Rust セルだけで使えます。正規化したソース、使用する定義、ランタイムモジュールのフィンガープリント、型付きの完全な入力、エクスポート名、直接の依存元の結果によって出力が決まるという宣言です。シードなど変化する値はすべて入力として公開してください。純粋性を自動検出する機能ではありません。
例で Bias だけを変えると両方の生成元の結果を再利用します。以前のシードに戻した場合も再利用できます。各生成元は最大 4 件、ページ全体で 32 MiB まで保持します。容量は正規化した結果のシリアライズサイズで計測し、最後の利用が古いものから削除します。表示用の出力とエクスポートの両方を保存します。失敗、キャンセル、タイムアウト、不正なエクスポートや出力、切り詰めた結果は保存しません。
再利用時は「同じ入力の結果を再利用しました」と表示します。「再計算」は対象のキャッシュを使わず、成功後に保存結果を置き換えます。ボタン実行の生成元で「実行」を押した場合も再計算します。同じキーの同時リクエストは cache の有無にかかわらず計算を共有し、一方のキャンセルで他方に必要な計算を止めません。
ソース、ヘルパー、定義、モジュールの変更は該当するキーを無効化します。無効化の範囲は Rust モジュール単位です。再ビルドしたモジュール内の生成元は無効になり、変更のないモジュールの生成元は結果を保持します。そのため site のような粗いグループ化では、一度に多くのページが無効になります。キャッシュはメモリ内に限り、ページ移動やセッション終了時に破棄します。