examples: add Node.js 26 runtime support

Allow examples to run under Node 26 with --experimental-ffi in addition to
Bun. Replace some Bun-specific APIs with standard Node equivalents, lazy-load
demos that still require Bun (WebGPU, sprites, shaders), and import Rapier via
its ESM subpath.

Author: simonklee

.gitignore

@@ -30,6 +30,7 @@ report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
 # caches
 .eslintcache
 .cache
+.node
 *.tsbuildinfo
 
 # IntelliJ based IDEs

package.json

@@ -9,6 +9,7 @@
     "build": "cd packages/core && bun run build && cd ../three && bun run build && cd ../solid && bun run build && cd ../react && bun run build && cd ../keymap && bun run build",
     "build:examples": "cd packages/examples && bun run build",
     "clean": "bun scripts/clean.ts",
+    "examples:node": "node packages/examples/scripts/run-node26.mjs",
     "fmt": "oxfmt --write .",
     "fmt:check": "oxfmt --check .",
     "lint": "oxlint .",

packages/examples/package.json

@@ -15,7 +15,9 @@
   "scripts": {
     "dev": "bun src/index.ts",
     "build": "bun scripts/build.ts",
-    "build:host": "bun scripts/build.ts --host"
+    "build:host": "bun scripts/build.ts --host",
+    "download:node26": "node scripts/download-node26.mjs",
+    "dev:node": "node scripts/run-node26.mjs"
   },
   "dependencies": {
     "@dimforge/rapier2d-simd-compat": "^0.17.3",

packages/examples/scripts/download-node26.mjs

@@ -0,0 +1,3 @@
+import { ensureNode26 } from "./node26.mjs"
+
+console.log(ensureNode26())

packages/examples/scripts/node26.mjs

@@ -0,0 +1,102 @@
+import { spawnSync } from "node:child_process"
+import { existsSync, mkdirSync } from "node:fs"
+import { dirname, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+
+export const NODE26_VERSION = "v26.1.0"
+
+const scriptDir = dirname(fileURLToPath(import.meta.url))
+const packageRoot = resolve(scriptDir, "..")
+const cacheDir = resolve(packageRoot, ".cache/node26")
+
+function getTarget() {
+  if (process.arch !== "x64") {
+    throw new Error(`This examples runner downloads the x64 Node 26 builds, not ${process.platform}-${process.arch}.`)
+  }
+
+  switch (process.platform) {
+    case "linux":
+      return {
+        archiveName: `node-${NODE26_VERSION}-linux-x64.tar.xz`,
+        directoryName: `node-${NODE26_VERSION}-linux-x64`,
+        nodeRelativePath: "bin/node",
+        url: `https://nodejs.org/dist/${NODE26_VERSION}/node-${NODE26_VERSION}-linux-x64.tar.xz`,
+      }
+    case "darwin":
+      return {
+        archiveName: `node-${NODE26_VERSION}-darwin-x64.tar.gz`,
+        directoryName: `node-${NODE26_VERSION}-darwin-x64`,
+        nodeRelativePath: "bin/node",
+        url: `https://nodejs.org/dist/${NODE26_VERSION}/node-${NODE26_VERSION}-darwin-x64.tar.gz`,
+      }
+    case "win32":
+      return {
+        archiveName: `node-${NODE26_VERSION}-win-x64.zip`,
+        directoryName: `node-${NODE26_VERSION}-win-x64`,
+        nodeRelativePath: "node.exe",
+        url: `https://nodejs.org/dist/${NODE26_VERSION}/node-${NODE26_VERSION}-win-x64.zip`,
+      }
+    default:
+      throw new Error(`This examples runner does not have a Node 26 download for ${process.platform}-${process.arch}.`)
+  }
+}
+
+export function getNode26Path() {
+  const target = getTarget()
+  return resolve(cacheDir, target.directoryName, target.nodeRelativePath)
+}
+
+export function ensureNode26() {
+  const target = getTarget()
+  const archivePath = resolve(cacheDir, target.archiveName)
+  const nodeDir = resolve(cacheDir, target.directoryName)
+  const nodePath = resolve(nodeDir, target.nodeRelativePath)
+
+  if (existsSync(nodePath)) {
+    return nodePath
+  }
+
+  mkdirSync(cacheDir, { recursive: true })
+
+  if (!existsSync(archivePath)) {
+    run("curl", ["-L", target.url, "-o", archivePath])
+  }
+
+  extractArchive(archivePath, cacheDir)
+
+  if (!existsSync(nodePath)) {
+    throw new Error(`Downloaded Node 26 archive did not produce ${nodePath}`)
+  }
+
+  return nodePath
+}
+
+function extractArchive(archivePath, outputDir) {
+  if (archivePath.endsWith(".zip")) {
+    if (process.platform === "win32") {
+      run("powershell", [
+        "-NoProfile",
+        "-Command",
+        `Expand-Archive -Path '${archivePath}' -DestinationPath '${outputDir}' -Force`,
+      ])
+      return
+    }
+
+    run("unzip", ["-q", archivePath, "-d", outputDir])
+    return
+  }
+
+  run("tar", ["-xf", archivePath, "-C", outputDir])
+}
+
+function run(command, args) {
+  const result = spawnSync(command, args, { stdio: "inherit" })
+
+  if (result.error) {
+    throw result.error
+  }
+
+  if (result.status !== 0) {
+    process.exit(result.status ?? 1)
+  }
+}

packages/examples/scripts/run-node26.mjs

@@ -0,0 +1,76 @@
+import { spawnSync } from "node:child_process"
+import { cpSync, mkdirSync, rmSync } from "node:fs"
+import { dirname, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+
+import { ensureNode26 } from "./node26.mjs"
+
+const scriptDir = dirname(fileURLToPath(import.meta.url))
+const packageRoot = resolve(scriptDir, "..")
+const repoRoot = resolve(packageRoot, "../..")
+const coreRoot = resolve(repoRoot, "packages/core")
+const nodePath = ensureNode26()
+const bundleDir = resolve(packageRoot, ".node")
+const bundleEntry = resolve(bundleDir, "index.js")
+
+ensureNativePackage()
+buildNodeExamples()
+
+const result = spawnSync(nodePath, ["--experimental-ffi", "--no-warnings", bundleEntry], {
+  cwd: packageRoot,
+  stdio: "inherit",
+  env: process.env,
+})
+
+if (result.error) {
+  throw result.error
+}
+
+process.exit(result.status ?? 0)
+
+function buildNodeExamples() {
+  rmSync(bundleDir, { recursive: true, force: true })
+
+  run(
+    "bun",
+    [
+      "build",
+      "src/index.ts",
+      "--target=node",
+      "--format=esm",
+      "--splitting",
+      "--outdir",
+      ".node",
+      "--define",
+      "OPENTUI_BUN_ONLY_EXAMPLES=false",
+    ],
+    packageRoot,
+  )
+}
+
+function ensureNativePackage() {
+  const nativePackageName = `core-${process.platform === "win32" ? "win32" : process.platform}-${process.arch}`
+  const sourceNativeDir = resolve(coreRoot, "node_modules", "@opentui", nativePackageName)
+  const targetNativeDir = resolve(packageRoot, "node_modules", "@opentui", nativePackageName)
+
+  run("bun", ["run", "build:native"], coreRoot)
+
+  mkdirSync(resolve(packageRoot, "node_modules", "@opentui"), { recursive: true })
+  rmSync(targetNativeDir, { recursive: true, force: true })
+  cpSync(sourceNativeDir, targetNativeDir, { recursive: true, dereference: true })
+}
+
+function run(command, args, cwd) {
+  const result = spawnSync(command, args, {
+    cwd,
+    stdio: "inherit",
+  })
+
+  if (result.error) {
+    throw result.error
+  }
+
+  if (result.status !== 0) {
+    process.exit(result.status ?? 1)
+  }
+}

packages/examples/src/hast-syntax-highlighting-demo.ts

@@ -3,8 +3,9 @@ import { setupCommonDemoKeys } from "./lib/standalone-keys.js"
 import { parseColor } from "@opentui/core"
 import { hastToStyledText, type HASTElement } from "@opentui/core"
 import { SyntaxStyle } from "@opentui/core"
+import exampleHAST from "./assets/hast-example.json" with { type: "json" }
 
-const exampleHAST: HASTElement = (await import("./assets/hast-example.json", { with: { type: "json" } })) as HASTElement
+const typedExampleHAST = exampleHAST as HASTElement
 
 let renderer: CliRenderer | null = null
 let keyboardHandler: ((key: KeyEvent) => void) | null = null
@@ -67,7 +68,7 @@ export function run(rendererInstance: CliRenderer): void {
     default: { fg: parseColor("#FFFFFF") },
   })
   const transformStart = performance.now()
-  const styledText = hastToStyledText(exampleHAST, syntaxStyle)
+  const styledText = hastToStyledText(typedExampleHAST, syntaxStyle)
   const transformEnd = performance.now()
   const transformTime = (transformEnd - transformStart).toFixed(2)
 
@@ -93,7 +94,7 @@ export function run(rendererInstance: CliRenderer): void {
       syntaxStyle.clearCache()
 
       const retransformStart = performance.now()
-      const newStyledText = hastToStyledText(exampleHAST, syntaxStyle)
+      const newStyledText = hastToStyledText(typedExampleHAST, syntaxStyle)
       const retransformEnd = performance.now()
       const newTransformTime = (retransformEnd - retransformStart).toFixed(2)