@effindomv2/fui-rs 0.1.3

package/COMMERCIAL.md

@@ -0,0 +1,7 @@
+# FUI-RS Commercial License
+
+`@effindomv2/fui-rs` is available under a separate commercial license if you
+want to use it without the obligations of AGPL-3.0-only.
+
+To discuss commercial licensing, contact the repository maintainer through the
+project's public contact channel.

package/Cargo.toml

@@ -0,0 +1,34 @@
+[package]
+name = "fui-rs"
+version = "0.1.3"
+edition = "2021"
+license = "AGPL-3.0-only OR LicenseRef-EffinDom-Commercial"
+
+[workspace]
+members = [
+  ".",
+  "crates/demo-home",
+  "crates/demo-shared",
+  "crates/demo-stage4",
+  "crates/demo-stage5",
+  "crates/demo-worker",
+  "crates/demo-workbench",
+]
+resolver = "2"
+
+[features]
+default = []
+worker-runtime = []
+native-runtime = []
+
+[dependencies]
+
+[profile.release]
+opt-level = 3
+lto = true
+codegen-units = 1
+panic = "abort"
+
+[lib]
+name = "fui"
+crate-type = ["rlib"]

package/LICENSE.md

@@ -0,0 +1,9 @@
+`@effindomv2/fui-rs` is licensed under the GNU Affero General Public License
+v3.0 (AGPL-3.0-only) or, at your option, the commercial license terms in
+`COMMERCIAL.md`.
+
+See:
+
+- `../../LICENSE.md`
+- `../../LICENSES/AGPL-3.0-only.md`
+- `COMMERCIAL.md`

package/README.md

@@ -0,0 +1,88 @@
+# FUI-RS - Rust SDK for EffinDom v2
+
+FUI-RS is the Rust retained-mode SDK for building EffinDom v2 WebAssembly UI
+apps. It provides retained controls, layout nodes, text input, overlays,
+custom drawing, host services, workers, routing support, and app lifecycle
+macros for browser-hosted Rust WASM apps.
+
+## Quickstart
+
+```bash
+# Prerequisites: Rust + wasm32-unknown-unknown target + Binaryen
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+rustup target add wasm32-unknown-unknown
+brew install binaryen
+
+# Clone and build
+git clone https://github.com/zion-sati/fui-rs.git
+cd fui-rs
+npm ci
+npm run build
+npm run serve
+```
+
+Open:
+
+```text
+http://127.0.0.1:8080/v2/fui-rs/demo/index.html
+```
+
+Full quickstart: [docs/v2/fui-rs/QUICKSTART.md](../../docs/v2/fui-rs/QUICKSTART.md)
+
+## Minimal app
+
+```rust
+use fui::prelude::*;
+
+fn build_page() -> FlexBox {
+    ui! {
+        column().fill_size().padding(24.0, 24.0, 24.0, 24.0) {
+            text("Hello from Rust"),
+            button("Click me").on_click(|_| logger::info("App", "clicked")),
+        }
+    }
+}
+
+fui_app!(FlexBox, build_page);
+```
+
+## SDK docs
+
+- [SDK docs index](../../docs/v2/fui-rs/SDK_INDEX.md)
+- [API reference](../../docs/v2/fui-rs/API_REFERENCE.md)
+- [Controls and nodes](../../docs/v2/fui-rs/CONTROLS_AND_NODES.md)
+- [Events and callbacks](../../docs/v2/fui-rs/EVENTS_AND_CALLBACKS.md)
+- [Text input reference](../../docs/v2/fui-rs/TEXT_INPUT_REFERENCE.md)
+- [Forms and autofill](../../docs/v2/fui-rs/FORMS_AND_AUTOFILL.md)
+- [Theming and style matrix](../../docs/v2/fui-rs/THEMING_STYLE_MATRIX.md)
+
+## What is included
+
+| Area | Status |
+|---|---|
+| Retained app lifecycle macros | Available |
+| `ui!` mixed child tree macro | Available |
+| Flex/Grid layout nodes | Available |
+| Text, rich text, image, SVG | Available |
+| Buttons, toggles, slider, dropdown, combobox | Available |
+| TextInput/TextArea | Available |
+| Context menu, popup, dialog, tooltip | Available |
+| Selection, mobile text handles, context toolbar | Available |
+| ScrollView, ScrollBox, VirtualList | Available |
+| Custom drawing and text layouts | Available |
+| Browser file/fetch/worker bridges | Available |
+| Host services/events generator support | Available |
+
+## Architecture
+
+FUI-RS builds Rust retained UI objects into the EffinDom v2 runtime through the
+browser bridge. Rust app WASM and the UI runtime WASM are separate modules;
+strings and command data cross the bridge through explicit UTF-8/runtime ABI
+calls.
+
+Retained controls are cheap clone handles. Cloning a control gives another Rust
+handle to the same retained UI object.
+
+## License
+
+AGPL-3.0-only, or commercial license. See [COMMERCIAL.md](COMMERCIAL.md).

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@effindomv2/fui-rs",
+  "version": "0.1.3",
+  "private": false,
+  "license": "AGPL-3.0-only OR LicenseRef-EffinDom-Commercial",
+  "description": "EffinDom v2 Rust frontend framework SDK and host generators",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "src",
+    "scripts",
+    "Cargo.toml",
+    "README.md",
+    "LICENSE.md",
+    "COMMERCIAL.md"
+  ],
+  "scripts": {
+    "generate:abi": "mkdir -p build && esbuild ../abi/generate.ts --bundle --format=esm --platform=node --target=node20 --packages=external --outfile=build/generate-abi.mjs && node build/generate-abi.mjs fui-rs-ffi",
+    "check:abi": "mkdir -p build && esbuild ../abi/generate.ts --bundle --format=esm --platform=node --target=node20 --packages=external --outfile=build/generate-abi.mjs && node build/generate-abi.mjs fui-rs-ffi --check",
+    "generate:host-services": "mkdir -p build && esbuild scripts/generate-host-services.ts --bundle --format=esm --platform=node --target=node20 --packages=external --outfile=build/generate-host-services.mjs && node build/generate-host-services.mjs demo/src/host-services.ts demoHostServices crates/demo-shared/src/generated/host_services.rs fui::host_services",
+    "generate:host-events:home": "mkdir -p build && esbuild scripts/generate-host-events.ts --bundle --format=esm --platform=node --target=node20 --packages=external --outfile=build/generate-host-events.mjs && node build/generate-host-events.mjs demo/src/host-events.ts demoHostEvents crates/demo-home/src/generated/host_events.rs",
+    "generate:host-events:workbench": "mkdir -p build && esbuild scripts/generate-host-events.ts --bundle --format=esm --platform=node --target=node20 --packages=external --outfile=build/generate-host-events.mjs && node build/generate-host-events.mjs demo/src/host-events.ts demoHostEvents crates/demo-workbench/src/generated/host_events.rs",
+    "generate:host-events:stage4": "mkdir -p build && esbuild scripts/generate-host-events.ts --bundle --format=esm --platform=node --target=node20 --packages=external --outfile=build/generate-host-events.mjs && node build/generate-host-events.mjs demo/src/host-events.ts demoHostEvents crates/demo-stage4/src/generated/host_events.rs",
+    "generate:host-events:stage5": "mkdir -p build && esbuild scripts/generate-host-events.ts --bundle --format=esm --platform=node --target=node20 --packages=external --outfile=build/generate-host-events.mjs && node build/generate-host-events.mjs demo/src/host-events.ts demoHostEvents crates/demo-stage5/src/generated/host_events.rs",
+    "generate:worker-host-services": "mkdir -p build && esbuild scripts/generate-host-services.ts --bundle --format=esm --platform=node --target=node20 --packages=external --outfile=build/generate-host-services.mjs && node build/generate-host-services.mjs demo/src/worker-host-services.ts demoWorkerHostServices crates/demo-shared/src/generated/worker_host_services.rs fui::host_services fui_host_service",
+    "generate:framework-host-services": "mkdir -p build && esbuild scripts/generate-host-services.ts --bundle --format=esm --platform=node --target=node20 --packages=external --outfile=build/generate-host-services.mjs && node build/generate-host-services.mjs scripts/framework-host-services.ts frameworkHostServices src/generated/framework_host_services.rs crate::host_services fui_host",
+    "generate:host": "npm run generate:host-services && npm run generate:host-events:home && npm run generate:host-events:workbench && npm run generate:host-events:stage4 && npm run generate:host-events:stage5 && npm run generate:worker-host-services && npm run generate:framework-host-services",
+    "guard:runtime-dependency": "bash scripts/check-runtime-dependency.sh",
+    "lint": "cd ../.. && npm run lint:v2",
+    "build": "npm run guard:runtime-dependency && npm run check:abi && bash scripts/build.sh",
+    "test:unit": "npm run guard:runtime-dependency && npm run check:abi && npm run generate:host && bash -lc 'source \"$HOME/.cargo/env\" && cargo test --manifest-path Cargo.toml'",
+    "test:integration": "npm --prefix ../.. run build:v2:browser-bridge && npm run build && playwright test -c playwright.config.ts",
+    "typecheck": "npm run guard:runtime-dependency && npm run check:abi && tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run check:abi && npm run lint && npm run typecheck"
+  },
+  "dependencies": {
+    "@effindomv2/runtime": "0.1.24"
+  },
+  "devDependencies": {
+    "@playwright/test": "1.59.1",
+    "@types/node": "^24.10.1",
+    "esbuild": "^0.27.7",
+    "typescript": "^5.9.3"
+  },
+  "allowScripts": {
+    "esbuild@0.27.7": true,
+    "fsevents@2.3.2": true
+  }
+}

package/scripts/build.sh

@@ -0,0 +1,227 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+PACKAGE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+REPO_ROOT="$(cd "${PACKAGE_DIR}/../.." && pwd)"
+OUT_DIR="${REPO_ROOT}/public/v2/fui-rs"
+DEMO_OUT_DIR="${OUT_DIR}/demo"
+PUBLIC_BRIDGE_DIR="${REPO_ROOT}/public/v2/browser-bridge"
+PACKAGE_BRIDGE_DIR="${REPO_ROOT}/v2/browser-bridge/dist"
+SHARED_FONTS_DIR="${REPO_ROOT}/public/v2/fonts"
+SHARED_DEMO_TEXTURE="${REPO_ROOT}/v2/fui-as/demo/demo-texture.png"
+HOST_SERVICE_GENERATOR_BUILD="${PACKAGE_DIR}/build/generate-host-services.mjs"
+HOST_EVENT_GENERATOR_BUILD="${PACKAGE_DIR}/build/generate-host-events.mjs"
+WORKER_BOOTSTRAP_BUILD="${PACKAGE_DIR}/build/worker-bootstrap.js"
+WORKER_BOOTSTRAP_MAP_BUILD="${PACKAGE_DIR}/build/worker-bootstrap.js.map"
+
+mkdir -p "${PACKAGE_DIR}/build" "${OUT_DIR}" "${DEMO_OUT_DIR}" "${DEMO_OUT_DIR}/workbench" "${DEMO_OUT_DIR}/stage4" "${DEMO_OUT_DIR}/stage5"
+
+cd "${PACKAGE_DIR}"
+if ! command -v cargo >/dev/null 2>&1 && [ -f "${HOME}/.cargo/env" ]; then
+  # shellcheck disable=SC1090
+  source "${HOME}/.cargo/env"
+fi
+if ! command -v cargo >/dev/null 2>&1; then
+  echo "cargo not found. Install Rust and ensure cargo is on PATH." >&2
+  exit 1
+fi
+
+resolve_runtime_dist_dir() {
+  local candidate=""
+  local public_manifest="${PUBLIC_BRIDGE_DIR}/effindom.v2.manifest.json"
+  local package_manifest="${PACKAGE_BRIDGE_DIR}/effindom.v2.manifest.json"
+  local candidates=()
+
+  if [ -n "${EFFINDOM_RUNTIME_DIST_DIR:-}" ]; then
+    candidates+=("${EFFINDOM_RUNTIME_DIST_DIR}")
+  fi
+
+  candidates+=(
+    "${PUBLIC_BRIDGE_DIR}"
+    "${PACKAGE_BRIDGE_DIR}"
+    "${PACKAGE_DIR}/node_modules/@effindomv2/runtime/dist"
+    "${REPO_ROOT}/node_modules/@effindomv2/runtime/dist"
+  )
+
+  if [ -f "${public_manifest}" ] && [ -f "${package_manifest}" ] && ! cmp -s "${public_manifest}" "${package_manifest}"; then
+    echo "Note: using ${PUBLIC_BRIDGE_DIR} for local runtime assets." >&2
+    echo "      ${PACKAGE_BRIDGE_DIR} is a staged package copy and may be stale." >&2
+    echo "      For ABI changes, run repo-root ./build.sh (or npm run build:v2:abi)." >&2
+  fi
+
+  for candidate in "${candidates[@]}"; do
+    if [ -f "${candidate}/bridge.js" ] && [ -f "${candidate}/effindom.v2.manifest.json" ] && [ -d "${candidate}/runtime" ]; then
+      printf '%s\n' "${candidate}"
+      return 0
+    fi
+  done
+
+  echo "Could not locate runtime dist assets." >&2
+  echo "Expected one of:" >&2
+  echo "  - \$EFFINDOM_RUNTIME_DIST_DIR" >&2
+  echo "  - ${PACKAGE_DIR}/node_modules/@effindomv2/runtime/dist" >&2
+  echo "  - ${REPO_ROOT}/node_modules/@effindomv2/runtime/dist" >&2
+  echo "  - ${REPO_ROOT}/public/v2/browser-bridge" >&2
+  echo "  - ${REPO_ROOT}/v2/browser-bridge/dist" >&2
+  echo "Install @effindomv2/runtime or build runtime assets first." >&2
+  exit 1
+}
+
+RUNTIME_DIST_DIR="$(resolve_runtime_dist_dir)"
+optimize_wasm() {
+  local wasm_file="$1"
+
+  if command -v wasm-opt >/dev/null 2>&1; then
+    wasm-opt -O3 --strip-debug --strip-producers "${wasm_file}" -o "${wasm_file}"
+  else
+    echo "wasm-opt not found; skipping Binaryen speed optimization for ${wasm_file}." >&2
+  fi
+}
+
+generate_host_services() {
+  local definition_file="$1"
+  local export_name="$2"
+  local output_file="$3"
+  local runtime_path="${4:-}"
+  local host_import_module="${5:-}"
+
+  npx esbuild "${PACKAGE_DIR}/scripts/generate-host-services.ts" \
+    --bundle \
+    --format=esm \
+    --platform=node \
+    --target=node20 \
+    --packages=external \
+    --outfile="${HOST_SERVICE_GENERATOR_BUILD}"
+
+  if [ -n "${runtime_path}" ] && [ -n "${host_import_module}" ]; then
+    node "${HOST_SERVICE_GENERATOR_BUILD}" \
+      "${definition_file}" "${export_name}" "${output_file}" "${runtime_path}" "${host_import_module}"
+  elif [ -n "${runtime_path}" ]; then
+    node "${HOST_SERVICE_GENERATOR_BUILD}" "${definition_file}" "${export_name}" "${output_file}" "${runtime_path}"
+  elif [ -n "${host_import_module}" ]; then
+    node "${HOST_SERVICE_GENERATOR_BUILD}" "${definition_file}" "${export_name}" "${output_file}" "" "${host_import_module}"
+  else
+    node "${HOST_SERVICE_GENERATOR_BUILD}" "${definition_file}" "${export_name}" "${output_file}"
+  fi
+}
+
+generate_host_events() {
+  local definition_file="$1"
+  local export_name="$2"
+  local output_file="$3"
+
+  npx esbuild "${PACKAGE_DIR}/scripts/generate-host-events.ts" \
+    --bundle \
+    --format=esm \
+    --platform=node \
+    --target=node20 \
+    --packages=external \
+    --outfile="${HOST_EVENT_GENERATOR_BUILD}"
+
+  node "${HOST_EVENT_GENERATOR_BUILD}" "${definition_file}" "${export_name}" "${output_file}"
+}
+
+generate_host_services "demo/src/host-services.ts" "demoHostServices" "crates/demo-shared/src/generated/host_services.rs" "fui::host_services"
+generate_host_events "demo/src/host-events.ts" "demoHostEvents" "crates/demo-home/src/generated/host_events.rs"
+generate_host_events "demo/src/host-events.ts" "demoHostEvents" "crates/demo-workbench/src/generated/host_events.rs"
+generate_host_events "demo/src/host-events.ts" "demoHostEvents" "crates/demo-stage4/src/generated/host_events.rs"
+generate_host_events "demo/src/host-events.ts" "demoHostEvents" "crates/demo-stage5/src/generated/host_events.rs"
+generate_host_services "demo/src/worker-host-services.ts" "demoWorkerHostServices" "crates/demo-shared/src/generated/worker_host_services.rs" "fui::host_services" "fui_host_service"
+generate_host_services "demo/src/worker-host-services.ts" "demoWorkerHostServices" "crates/demo-worker/src/generated/worker_host_services.rs" "" "fui_host_service"
+generate_host_services "scripts/framework-host-services.ts" "frameworkHostServices" "src/generated/framework_host_services.rs" "crate::host_services" "fui_host"
+
+rm -f "${OUT_DIR}/app.wasm" "${OUT_DIR}/harness.js" "${OUT_DIR}/harness.js.map" "${DEMO_OUT_DIR}/demo.wasm"
+
+build_demo_route() {
+  local package="$1"
+  local wasm_name="$2"
+  local wasm_out="$3"
+
+  cargo build --package "${package}" --target wasm32-unknown-unknown --target-dir "${PACKAGE_DIR}/target" --release
+  cp "${PACKAGE_DIR}/target/wasm32-unknown-unknown/release/${wasm_name}.wasm" "${wasm_out}"
+  optimize_wasm "${wasm_out}"
+}
+
+build_demo_route "fui-rs-demo-home" "fui_rs_demo_home" "${DEMO_OUT_DIR}/home.wasm"
+build_demo_route "fui-rs-demo-workbench" "fui_rs_demo_workbench" "${DEMO_OUT_DIR}/workbench.wasm"
+build_demo_route "fui-rs-demo-stage4" "fui_rs_demo_stage4" "${DEMO_OUT_DIR}/stage4.wasm"
+build_demo_route "fui-rs-demo-stage5" "fui_rs_demo_stage5" "${DEMO_OUT_DIR}/stage5.wasm"
+build_demo_route "fui-rs-demo-worker" "fui_rs_demo_worker" "${DEMO_OUT_DIR}/workers.wasm"
+cp "${DEMO_OUT_DIR}/workers.wasm" "${DEMO_OUT_DIR}/workbench/workers.wasm"
+cp "${DEMO_OUT_DIR}/workers.wasm" "${DEMO_OUT_DIR}/stage4/workers.wasm"
+cp "${DEMO_OUT_DIR}/workers.wasm" "${DEMO_OUT_DIR}/stage5/workers.wasm"
+
+npx esbuild "${PACKAGE_DIR}/demo/harness.ts" \
+  --bundle \
+  --format=esm \
+  --platform=browser \
+  --target=es2020 \
+  --minify \
+  --outfile="${DEMO_OUT_DIR}/harness.js" \
+  --sourcemap
+
+npx esbuild "${PACKAGE_DIR}/demo/worker-host-services.ts" \
+  --bundle \
+  --format=iife \
+  --platform=browser \
+  --target=es2020 \
+  --minify \
+  --outfile="${DEMO_OUT_DIR}/worker-host-services.js" \
+  --sourcemap
+
+npx esbuild "${REPO_ROOT}/v2/browser-bridge/src/managed-harness/worker-bootstrap.ts" \
+  --bundle \
+  --format=iife \
+  --platform=browser \
+  --target=es2020 \
+  --minify \
+  --outfile="${WORKER_BOOTSTRAP_BUILD}" \
+  --sourcemap
+
+cp "${WORKER_BOOTSTRAP_BUILD}" "${DEMO_OUT_DIR}/worker-bootstrap.js"
+cp "${WORKER_BOOTSTRAP_MAP_BUILD}" "${DEMO_OUT_DIR}/worker-bootstrap.js.map"
+
+cp "${PACKAGE_DIR}/browser/index.html" "${OUT_DIR}/index.html"
+cp "${PACKAGE_DIR}/demo/index.html" "${DEMO_OUT_DIR}/index.html"
+cp "${PACKAGE_DIR}/demo/route-shell.html" "${DEMO_OUT_DIR}/workbench/index.html"
+cp "${PACKAGE_DIR}/demo/route-shell.html" "${DEMO_OUT_DIR}/stage4/index.html"
+cp "${PACKAGE_DIR}/demo/route-shell.html" "${DEMO_OUT_DIR}/stage5/index.html"
+cp "${PACKAGE_DIR}/demo/routes.json" "${DEMO_OUT_DIR}/routes.json"
+rm -f "${DEMO_OUT_DIR}/worker-manifest.json"
+if [ -f "${SHARED_DEMO_TEXTURE}" ]; then
+  cp "${SHARED_DEMO_TEXTURE}" "${OUT_DIR}/demo-texture.png"
+  cp "${SHARED_DEMO_TEXTURE}" "${DEMO_OUT_DIR}/demo-texture.png"
+  cp "${SHARED_DEMO_TEXTURE}" "${DEMO_OUT_DIR}/workbench/demo-texture.png"
+  cp "${SHARED_DEMO_TEXTURE}" "${DEMO_OUT_DIR}/stage4/demo-texture.png"
+  cp "${SHARED_DEMO_TEXTURE}" "${DEMO_OUT_DIR}/stage5/demo-texture.png"
+fi
+cat > "${OUT_DIR}/effindom-runtime-config.js" << 'RUNTIMECFG'
+window.__effindomRuntime = Object.assign({}, window.__effindomRuntime, {
+  manifestUrl: './effindom.v2.manifest.json',
+});
+RUNTIMECFG
+cp "${OUT_DIR}/effindom-runtime-config.js" "${DEMO_OUT_DIR}/effindom-runtime-config.js"
+cp "${RUNTIME_DIST_DIR}/bridge.js" "${OUT_DIR}/bridge.js"
+cp "${RUNTIME_DIST_DIR}/bridge.js.map" "${OUT_DIR}/bridge.js.map"
+cp "${RUNTIME_DIST_DIR}/effindom.v2.manifest.json" "${OUT_DIR}/effindom.v2.manifest.json"
+cp "${OUT_DIR}/bridge.js" "${DEMO_OUT_DIR}/bridge.js"
+cp "${OUT_DIR}/bridge.js.map" "${DEMO_OUT_DIR}/bridge.js.map"
+cp "${OUT_DIR}/effindom.v2.manifest.json" "${DEMO_OUT_DIR}/effindom.v2.manifest.json"
+if [ -f "${RUNTIME_DIST_DIR}/icu-asset.json" ]; then
+  cp "${RUNTIME_DIST_DIR}/icu-asset.json" "${OUT_DIR}/icu-asset.json"
+  cp "${OUT_DIR}/icu-asset.json" "${DEMO_OUT_DIR}/icu-asset.json"
+fi
+rm -rf "${OUT_DIR}/runtime"
+cp -R "${RUNTIME_DIST_DIR}/runtime" "${OUT_DIR}/runtime"
+rm -rf "${OUT_DIR}/fonts"
+rm -rf "${DEMO_OUT_DIR}/fonts"
+if [ -d "${SHARED_FONTS_DIR}" ]; then
+  cp -R "${SHARED_FONTS_DIR}" "${OUT_DIR}/fonts"
+  cp -R "${SHARED_FONTS_DIR}" "${DEMO_OUT_DIR}/fonts"
+elif [ -d "${RUNTIME_DIST_DIR}/fonts" ]; then
+  cp -R "${RUNTIME_DIST_DIR}/fonts" "${OUT_DIR}/fonts"
+  cp -R "${RUNTIME_DIST_DIR}/fonts" "${DEMO_OUT_DIR}/fonts"
+fi
+rm -rf "${DEMO_OUT_DIR}/runtime"
+cp -R "${RUNTIME_DIST_DIR}/runtime" "${DEMO_OUT_DIR}/runtime"

package/scripts/check-runtime-dependency.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+PACKAGE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+REPO_ROOT="$(cd "${PACKAGE_DIR}/../.." && pwd)"
+PACKAGE_JSON="${PACKAGE_DIR}/package.json"
+RUNTIME_PACKAGE_JSON="${REPO_ROOT}/v2/browser-bridge/package.json"
+
+runtime_spec="$(
+  node -e '
+    const fs = require("node:fs");
+    const pkg = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
+    process.stdout.write(String(pkg.dependencies?.["@effindomv2/runtime"] ?? ""));
+  ' "${PACKAGE_JSON}"
+)"
+
+if [ -z "${runtime_spec}" ]; then
+  echo "@effindomv2/runtime must be declared in dependencies." >&2
+  exit 1
+fi
+
+if ! printf '%s' "${runtime_spec}" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+([-.][0-9A-Za-z.]+)?$'; then
+  echo "@effindomv2/runtime must be pinned to an exact version, found: ${runtime_spec}" >&2
+  exit 1
+fi
+
+if [ -f "${RUNTIME_PACKAGE_JSON}" ]; then
+  runtime_version="$(
+    node -e '
+      const fs = require("node:fs");
+      const pkg = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
+      process.stdout.write(String(pkg.version ?? ""));
+    ' "${RUNTIME_PACKAGE_JSON}"
+  )"
+
+  if [ -n "${runtime_version}" ] && [ "${runtime_spec}" != "${runtime_version}" ]; then
+    echo "@effindomv2/fui-rs depends on @effindomv2/runtime@${runtime_spec}, but the local runtime is ${runtime_version}." >&2
+    exit 1
+  fi
+fi

package/scripts/framework-host-services.ts

@@ -0,0 +1,40 @@
+import { defineHostServices, hostService } from "../../browser-bridge/src/managed-harness/host-services.js";
+
+function unsupported(): never {
+  throw new Error("Framework host service definitions are generator metadata only.");
+}
+
+export const frameworkHostServices = defineHostServices({
+  frameworkHost: {
+    nowMs: hostService({
+      importName: "fui_now_ms",
+      args: [] as const,
+      returns: "f64",
+      implementation: () => unsupported(),
+    }),
+    isDarkMode: hostService({
+      importName: "fui_is_dark_mode",
+      args: [] as const,
+      returns: "bool",
+      implementation: () => unsupported(),
+    }),
+    accentColor: hostService({
+      importName: "fui_get_accent_color",
+      args: [] as const,
+      returns: "u32",
+      implementation: () => unsupported(),
+    }),
+    platformFamily: hostService({
+      importName: "fui_get_platform_family",
+      args: [] as const,
+      returns: "u32",
+      implementation: () => unsupported(),
+    }),
+    isCoarsePointer: hostService({
+      importName: "fui_is_coarse_pointer",
+      args: [] as const,
+      returns: "bool",
+      implementation: () => unsupported(),
+    }),
+  },
+});

package/scripts/generate-host-events.ts

@@ -0,0 +1,17 @@
+import path from "node:path";
+import { generateRustHostEventsFile } from "./hostgen/rust-host-events";
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+  if (args.length < 3) {
+    throw new Error("Usage: generate-host-events <module-path> <export-name> <output-path>");
+  }
+  const [moduleArg, exportName, outputArg] = args as [string, string, string];
+  await generateRustHostEventsFile(
+    path.resolve(process.cwd(), moduleArg),
+    exportName,
+    path.resolve(process.cwd(), outputArg),
+  );
+}
+
+await main();

package/scripts/generate-host-services.ts

@@ -0,0 +1,28 @@
+import path from "node:path";
+import { generateRustHostServicesFile } from "./hostgen/rust-host-services";
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+  if (args.length < 3) {
+    throw new Error(
+      "Usage: generate-host-services <module-path> <export-name> <output-path> [runtime-path] [host-import-module]",
+    );
+  }
+  const [moduleArg, exportName, outputArg, runtimePathArg, hostModuleArg] = args as [
+    string,
+    string,
+    string,
+    string | undefined,
+    string | undefined,
+  ];
+  await generateRustHostServicesFile(
+    path.resolve(process.cwd(), moduleArg),
+    exportName,
+    path.resolve(process.cwd(), outputArg),
+    runtimePathArg,
+    hostModuleArg ?? "fui_host_service",
+  );
+}
+
+await main();
+

package/scripts/hostgen/common.ts

@@ -0,0 +1,73 @@
+import { build } from "esbuild";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+export function toPosix(value: string): string {
+  return value.split(path.sep).join("/");
+}
+
+export function relativeImport(fromFile: string, targetFile: string): string {
+  let relative = path.relative(path.dirname(fromFile), targetFile);
+  relative = relative.replace(/\.[^.]+$/, "");
+  if (!relative.startsWith(".")) {
+    relative = `./${relative}`;
+  }
+  return toPosix(relative);
+}
+
+export function sourcePathForHeader(sourceModulePath: string): string {
+  const relative = path.relative(process.cwd(), sourceModulePath);
+  return toPosix(relative.startsWith(".") ? relative : `./${relative}`);
+}
+
+export async function loadModuleExport(
+  modulePath: string,
+  exportName: string,
+  tempPrefix: string,
+): Promise<unknown> {
+  const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), tempPrefix));
+  const bundledFile = path.join(tempDir, "module.mjs");
+  try {
+    await build({
+      entryPoints: [modulePath],
+      outfile: bundledFile,
+      bundle: true,
+      format: "esm",
+      platform: "node",
+      target: "node20",
+      logLevel: "silent",
+    });
+    const loaded = await import(pathToFileURL(bundledFile).href) as Record<string, unknown>;
+    if (!(exportName in loaded)) {
+      throw new Error(`Module does not export "${exportName}".`);
+    }
+    return loaded[exportName];
+  } finally {
+    await fs.rm(tempDir, { recursive: true, force: true });
+  }
+}
+
+export function snakeCaseIdentifier(value: string): string {
+  let result = "";
+  for (let index = 0; index < value.length; index += 1) {
+    const char = value[index] ?? "";
+    const previous = index > 0 ? value[index - 1] ?? "" : "";
+    const next = index + 1 < value.length ? value[index + 1] ?? "" : "";
+    const isUpper = char >= "A" && char <= "Z";
+    const prevIsLowerOrDigit =
+      (previous >= "a" && previous <= "z") || (previous >= "0" && previous <= "9");
+    const nextIsLower = next >= "a" && next <= "z";
+    if (
+      index > 0 &&
+      isUpper &&
+      (prevIsLowerOrDigit || ((previous >= "A" && previous <= "Z") && nextIsLower))
+    ) {
+      result += "_";
+    }
+    result += char.toLowerCase();
+  }
+  return result;
+}
+