feat(repl): Lynx REPL — interactive playground with GitHub Pages deployment

.github/workflows/nodejs-dependencies.yml

@@ -36,4 +36,4 @@ jobs:
           package-manager-cache: false
       - run: |
           pnpm dedupe --check
-          pnpm dlx sherif@latest
+          pnpm dlx sherif@latest -i tailwindcss

.github/workflows/workflow-website.yml

@@ -26,6 +26,7 @@
           key: turbo-v4-${{ runner.os }}-${{ hashFiles('**/packages/**/src/**/*.rs') }}-${{ github.sha }}
           fail-on-cache-miss: true
       - name: Setup Pages
+        id: pages
         uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5
       - name: Install
         run: |
@@ -35,6 +36,16 @@
       - name: Build
         run: |
           pnpm turbo --filter website build:docs
+      - name: Build REPL
+        run: |
+          BASE_PATH='${{ steps.pages.outputs.base_path }}'
+          export ASSET_PREFIX="${BASE_PATH%/}/repl/"
+          pnpm --filter @lynx-js/repl build
+      - name: Copy REPL into website output
+        run: |
+          rm -rf website/doc_build/repl
+          mkdir -p website/doc_build
+          cp -r packages/repl/dist website/doc_build/repl
       - name: Upload artifact
         uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4
         with:

CODEOWNERS

@@ -1,3 +1,4 @@
+packages/repl/** @huxpro
 packages/web-platform/** @pupiltong @Sherry-hue
 packages/webpack/** @colinaaa @upupming @luhc228
 packages/rspeedy/** @colinaaa @upupming @luhc228

biome.jsonc

@@ -57,6 +57,9 @@
       "packages/motion/__tests__/**",
 
       "packages/rspeedy/lynx-bundle-rslib-config/test/fixtures/**",
+
+      // REPL examples use Lynx platform globals and are not subject to lint rules
+      "packages/repl/src/examples/**",
     ],
     "rules": {
       // We are migrating from ESLint to Biome

eslint.config.js

@@ -71,6 +71,14 @@ export default tseslint.config(
       'packages/react/transform/index.cjs',
       'packages/react/transform/**/index.d.ts',
 
+      // REPL examples use Lynx platform globals and are not subject to lint rules
+      'packages/repl/src/examples/**',
+      // REPL components use Vite path aliases and ?raw imports not handled by root tsconfig
+      'packages/repl/src/components/**',
+      'packages/repl/src/editor.ts',
+      // REPL build config is not part of the TS project
+      'packages/repl/rsbuild.config.ts',
+
       // TODO: enable eslint for react
       // react
       'packages/react/types/**',

package.json

@@ -63,5 +63,12 @@
   "packageManager": "pnpm@10.29.3+sha512.498e1fb4cca5aa06c1dcf2611e6fafc50972ffe7189998c409e90de74566444298ffe43e6cd2acdc775ba1aa7cc5e092a8b7054c811ba8c5770f84693d33d2dc",
   "engines": {
     "node": "^22 || ^24"
+  },
+  "pnpm": {
+    "peerDependencyRules": {
+      "allowedVersions": {
+        "rsbuild-plugin-tailwindcss>tailwindcss": "^3 || ^4"
+      }
+    }
   }
 }

packages/repl/.gitignore

@@ -0,0 +1 @@
+src/generated/

packages/repl/README.md

@@ -0,0 +1,77 @@
+# @lynx-js/repl
+
+A **pure-browser** playground for Vanilla Lynx. Users write raw Element PAPI code and see it rendered in real time — no local toolchain, no server, no install.
+
+## Architecture Principle: Pure Browser, Zero Server
+
+This REPL runs **entirely in the browser**. The built artifact is a static site that can be deployed to any CDN or GitHub Pages. There is no compilation server, no Node.js dependency at runtime, and no network round-trip in the edit-preview loop.
+
+An alternative approach would be to run a local (or remote) Node.js server that invokes rspack for each edit — effectively a browser-based editor bolted onto the real build pipeline. We deliberately chose **not** to do this because:
+
+1. **If you need a local server, you already have Node.js** — at that point `rspeedy dev` gives you a strictly better experience (your own editor, incremental builds, HMR, full plugin pipeline).
+2. A server-backed REPL sits in an awkward middle ground: it loses the zero-setup advantage of a pure-browser tool while offering a worse DX than the real toolchain.
+3. The value of this REPL is precisely that it **does not overlap** with `rspeedy dev`. It serves a different audience (learners, docs, quick experiments) with a different tradeoff (instant access, limited features).
+
+## Where We Cut Into the Build Pipeline
+
+A standard Lynx project goes through 8 steps from source to bundle:
+
+```text
+Step  What happens                        Tool / Plugin
+────  ──────────────────────────────────   ─────────────────────────────
+ 1.   Source Transform (JSX/TS → JS)       rspack loader (SWC)
+ 2.   Module Resolution (import/require)   rspack resolver
+ 3.   CSS Processing (CSS → LynxStyleNode) @lynx-js/css-serializer
+ 4.   Bundling (multi-file → chunks)       rspack
+ 5.   Asset Tagging (lynx:main-thread)     MarkMainThreadPlugin
+ 6.   Template Assembly (assets → data)    LynxTemplatePlugin
+ 7.   Encoding (data → binary/JSON)        @lynx-js/tasm / WebEncodePlugin
+ 8.   Emit (write to disk)                 rspack compilation
+```
+
+This REPL **enters at step 6** and takes a shortcut:
+
+```text
+ rspeedy dev (full pipeline):
+   [1] → [2] → [3] → [4] → [5] → [6] → [7] → [8] → lynx-view (via URL fetch)
+
+ This REPL (pure browser):
+                              [3'] → [6'] ─────────→ lynx-view (via callback)
+```
+
+- **Step 3':** Parse user CSS in-browser via `css-tree` (pure JS) and a simplified `genStyleInfo` (adapted from `@lynx-js/css-serializer`) to produce `styleInfo`.
+- **Step 6':** Directly construct a `LynxTemplate` JS object from the user's code strings and the processed `styleInfo`. No webpack compilation, no asset pipeline.
+- **Delivery:** The template object is handed to `<lynx-view>` via the `customTemplateLoader` callback — no encoding, no file I/O, no URL fetch.
+
+Steps 1, 2, 4, 5 are skipped entirely because the user writes final-form JS (no JSX, no imports, no multi-file). Steps 7–8 are skipped because `<lynx-view>` can consume a `LynxTemplate` object directly.
+
+## Functional Boundaries
+
+What this REPL **can** do:
+
+- All Element PAPIs (`__CreateElement`, `__AppendElement`, `__AddInlineStyle`, etc.)
+- CSS class selectors, `@keyframes`, `@font-face`, CSS variables
+- Inline styles via `__AddInlineStyle`
+- Real-time preview with Lynx Web runtime (`<lynx-view>`)
+- Dual-thread model: main-thread.js (Lepus) + background.js (Web Worker)
+
+What this REPL **cannot** do (by design):
+
+- `import` / `require` — no module resolution, no bundler
+- JSX / TypeScript — no source transform
+- Export `.lynx.bundle` — requires `@lynx-js/tasm` (Node native addon)
+- Export `.web.json` binary — possible in future but not a priority
+- Multi-file projects — single main-thread.js + background.js + index.css
+
+Users who need any of the above should use `rspeedy dev`.
+
+## Target Capability: L0 + L1
+
+We target two capability levels, both achievable in pure browser:
+
+| Level         | Capability                          | Browser dependency          |
+| ------------- | ----------------------------------- | --------------------------- |
+| **L0** (done) | Raw Element PAPI with inline styles | None (zero extra KB)        |
+| **L1** (done) | + CSS class selectors               | `css-tree` (~200KB gzipped) |
+
+Higher levels (JSX, module imports, bundle export) are **not planned** — they would move toward `rspeedy dev` territory without matching its DX.

packages/repl/index.html

@@ -0,0 +1,23 @@
+<!DOCTYPE html>
+<html lang="en" data-theme="dark">
+  <head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Lynx REPL</title>
+    <!-- Critical CSS: prevent flash of white background before main CSS loads.
+         Uses the CSS variable so the background adapts when the theme changes;
+         the fallback #1e1e1e is only used during the brief initial load. -->
+    <style>
+    html, body, #app {
+      background: var(--repl-bg, #1e1e1e);
+      height: 100%;
+      width: 100%;
+      margin: 0;
+      overflow: hidden;
+    }
+    </style>
+  </head>
+  <body>
+    <div id="app"></div>
+  </body>
+</html>

packages/repl/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@lynx-js/repl",
+  "version": "0.0.1",
+  "private": true,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lynx-family/lynx-stack.git",
+    "directory": "packages/repl"
+  },
+  "license": "Apache-2.0",
+  "type": "module",
+  "scripts": {
+    "build": "node scripts/collect-lynx-types.mjs && rsbuild build",
+    "dev": "node scripts/collect-lynx-types.mjs && rsbuild dev"
+  },
+  "dependencies": {
+    "@radix-ui/react-select": "^2.2.6",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "lucide-react": "^0.575.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "react-resizable-panels": "^4.6.5",
+    "tailwind-merge": "^3.4.0"
+  },
+  "devDependencies": {
+    "@lynx-js/lynx-core": "0.1.3",
+    "@lynx-js/type-element-api": "0.0.3",
+    "@lynx-js/types": "3.7.0",
+    "@lynx-js/web-constants": "workspace:*",
+    "@lynx-js/web-core": "workspace:*",
+    "@lynx-js/web-elements": "workspace:*",
+    "@lynx-js/web-mainthread-apis": "workspace:*",
+    "@lynx-js/web-platform-rsbuild-plugin": "workspace:*",
+    "@lynx-js/web-worker-rpc": "workspace:*",
+    "@lynx-js/web-worker-runtime": "workspace:*",
+    "@rsbuild/core": "catalog:rsbuild",
+    "@rsbuild/plugin-react": "^1.4.5",
+    "@tailwindcss/postcss": "^4.2.1",
+    "@types/css-tree": "^2.3.11",
+    "@types/react": "npm:@types/react@^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "css-tree": "^3.1.0",
+    "hyphenate-style-name": "^1.1.0",
+    "monaco-editor": "^0.52.2",
+    "postcss": "^8.5.6",
+    "tailwindcss": "^4.2.1",
+    "tslib": "^2.8.1",
+    "wasm-feature-detect": "^1.8.0"
+  }
+}

packages/repl/postcss.config.mjs

@@ -0,0 +1,9 @@
+// Copyright 2026 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+
+export default {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+};

packages/repl/rsbuild.config.ts

@@ -0,0 +1,74 @@
+import { defineConfig } from '@rsbuild/core';
+import { pluginReact } from '@rsbuild/plugin-react';
+import { pluginWebPlatform } from '@lynx-js/web-platform-rsbuild-plugin';
+import path from 'node:path';
+
+export default defineConfig({
+  source: {
+    entry: {
+      index: './src/index.tsx',
+    },
+    include: [/node_modules[\\/]@lynx-js[\\/]/, /@lynx-js[\\/]/],
+  },
+  output: {
+    target: 'web',
+    assetPrefix: process.env.ASSET_PREFIX,
+    distPath: {
+      root: 'dist',
+    },
+    overrideBrowserslist: ['Chrome > 118'],
+  },
+  html: {
+    title: 'Lynx REPL',
+    template: './index.html',
+  },
+  tools: {
+    rspack: {
+      ignoreWarnings: [
+        (warning) =>
+          warning.module?.resource?.includes('monaco-editor')
+          && warning.message.includes('Critical dependency')
+          && warning.message.includes('require function is used in a way'),
+        (warning) =>
+          warning.module?.resource?.includes('monaco-editor')
+          && warning.message.includes(
+            '"__filename" is used and has been mocked',
+          ),
+        (warning) =>
+          warning.module?.resource?.includes('monaco-editor')
+          && warning.message.includes(
+            '"__dirname" is used and has been mocked',
+          ),
+      ],
+      resolve: {
+        alias: {
+          '@': path.resolve(__dirname, 'src'),
+          '@lynx-js/type-element-api/types/element-api.d.ts': path.resolve(
+            __dirname,
+            'node_modules/@lynx-js/type-element-api/types/element-api.d.ts',
+          ),
+        },
+        fallback: {
+          module: false,
+        },
+        modules: [
+          'node_modules',
+          path.resolve(__dirname, 'node_modules'),
+          path.resolve(__dirname, '../../node_modules'),
+        ],
+        symlinks: true,
+      },
+    },
+  },
+  performance: {
+    chunkSplit: {
+      strategy: 'all-in-one',
+    },
+  },
+  plugins: [
+    pluginReact(),
+    pluginWebPlatform({
+      polyfill: false,
+    }),
+  ],
+});