textual-wasm 0.1.0__tar.gz

textual_wasm-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kai Erik Niermann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

textual_wasm-0.1.0/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: textual-wasm
+Version: 0.1.0
+Summary: Ship a Textual TUI as both a terminal app and a client-side web page.
+License-Expression: MIT
+License-File: LICENSE
+Keywords: textual,tui,webassembly,wasm,pyodide,xterm
+Author: KaiErikNiermann
+Author-email: 61298289+KaiErikNiermann@users.noreply.github.com
+Requires-Python: >=3.12,<4.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Environment :: WebAssembly :: Emscripten
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Terminals
+Classifier: Typing :: Typed
+Requires-Dist: packaging (>=26.3,<27.0)
+Requires-Dist: pyodide-lock (>=0.2.1,<0.3.0)
+Requires-Dist: pyte (>=0.8.2,<0.9.0)
+Requires-Dist: rich (>=13.0)
+Requires-Dist: textual (>=8.2,<9.0)
+Requires-Dist: typer (>=0.15,<1.0)
+Project-URL: Documentation, https://kaierikniermann.github.io/textual-wasm/
+Project-URL: Homepage, https://github.com/KaiErikNiermann/textual-wasm
+Project-URL: Issues, https://github.com/KaiErikNiermann/textual-wasm/issues
+Project-URL: Repository, https://github.com/KaiErikNiermann/textual-wasm
+Description-Content-Type: text/markdown
+
+# textual-wasm
+
+[![ci](https://github.com/KaiErikNiermann/textual-wasm/actions/workflows/ci.yml/badge.svg)](https://github.com/KaiErikNiermann/textual-wasm/actions/workflows/ci.yml)
+[![docs](https://github.com/KaiErikNiermann/textual-wasm/actions/workflows/pages.yml/badge.svg)](https://kaierikniermann.github.io/textual-wasm/)
+[![python](https://img.shields.io/badge/python-3.12%2B-blue)](https://kaierikniermann.github.io/textual-wasm/installation.html)
+[![license](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
+
+Ship one [Textual](https://github.com/Textualize/textual) application as **both** a terminal
+TUI and a fully client-side web page — same source, no server-side Python process, no fork of
+Textual.
+
+**[Documentation](https://kaierikniermann.github.io/textual-wasm/)** ·
+**[Live demos](https://kaierikniermann.github.io/textual-wasm/examples.html)** ·
+**[Porting guide](https://kaierikniermann.github.io/textual-wasm/porting.html)**
+
+```bash
+textual-wasm build myapp.main:App myapp -o dist/   # a static directory
+textual-wasm dev dist/                             # http://127.0.0.1:8000
+```
+
+The output is static files. Pyodide and xterm.js come from a pinned CDN; your application is
+copied in as source. There is no build toolchain at the far end and nothing for the person
+deploying it to install.
+
+Textual itself is untouched. The extension point is a public one —
+`TEXTUAL_DRIVER=module:Symbol` (`textual/app.py:1585`) — so there is no patch to rebase.
+
+## The four commands
+
+| | |
+|---|---|
+| `textual-wasm doctor <module:App>` | What will break, with a `file:line`. Reads imports, **call sites**, and dependencies. |
+| `textual-wasm build <module:App> <package> -o dist/` | A static site. Bare page by default; `--title` and `--template` if you want otherwise. |
+| `textual-wasm dev dist/` | Serve it locally. Standard library only. |
+| `textual-wasm check --app <module:App>` | Run it on every runtime available and compare. |
+
+## What `check` actually checks
+
+Four runtimes, and two comparisons that mean something:
+
+| Leg | Runtime | Settles |
+|---|---|---|
+| native | CPython | The baseline. |
+| wasm | Pyodide under Node | Everything on the Python side, in CI, with no browser. |
+| browser | Chromium, Firefox **and** WebKit over a real `build` | Rendering, and whether the engines agree. |
+| terminal | a real pty via tmux, on Textual's own driver | What a user would actually see. |
+
+`native` against `wasm` is compared check-by-check, fact-by-fact and grid-by-grid.
+`terminal` against `browser` is compared cell-by-cell — that one is the render claim, and it
+is made against a real terminal rather than a replay because three different character-width
+tables are involved and they do not share code.
+
+A runtime this machine cannot reach is reported as **skipped, with the command that would
+enable it**, and the rest still produce a verdict. `--strict` makes a skip a failure, which
+is what CI wants.
+
+```
+textual_wasm.app:SpikeApp at 80x24
+┏━━━━━━━━━━┳━━━━━━━━━┳──────────────────────────────────────┓
+┃ runtime  ┃ status  ┃ detail                               ┃
+┡━━━━━━━━━━╇━━━━━━━━━╇──────────────────────────────────────┩
+│ native   │ ran     │ 8 checks, 0 failed                   │
+│ wasm     │ ran     │ 0 check(s) failed                    │
+│ browser  │ ran     │ 19 rows rendered                     │
+│ terminal │ ran     │ tmux 3.7c                            │
+└──────────┴─────────┴──────────────────────────────────────┘
+identical: terminal and browser render the same
+equivalent across 4 runtime(s)
+```
+
+Nothing the probe measures is asked of your app: the timer is scheduled by the probe, the
+resize is read back off the `Screen` it laid out, and input is judged by what appears on the
+grid. An app that has never heard of this project is measured by exactly the code that
+measures the one that ships with it.
+
+## Diagnostics
+
+Pyodide's most dangerous failures are the ones that raise nothing. `os.system()` returns 0
+and does nothing; `loop.run_in_executor()` ignores the executor and runs inline on the only
+thread, so code written to keep a UI responsive freezes the page instead.
+
+`textual_wasm.diagnostics.install()` manufactures a loud, specific failure for each, naming
+the substitute. `diagnostics.attach(app, driver)` moves crash output off stderr — which under
+Pyodide is a browser console nobody is watching — and into the terminal the user is looking
+at. The build output does both for you.
+
+Every one of those claims is **measured, not transcribed**, and the
+[porting matrix](./docs/porting-matrix.md) is generated from the same registry the analyser
+and the guards read. A test fails when it drifts; a characterisation suite re-measures the
+registry inside a real Pyodide. Pyodide's own documentation lists four modules as removed
+that import fine in 314.0.6, which is what a hand-maintained table gets you.
+
+## Documentation
+
+The [documentation site](https://kaierikniermann.github.io/textual-wasm/) is itself the proof:
+every demo on it is a real build of a real Textual app, running in your browser, served as
+static files by GitHub Pages.
+
+- [Quickstart](https://kaierikniermann.github.io/textual-wasm/quickstart.html) — a new app in a
+  browser in five minutes.
+- [Porting guide](https://kaierikniermann.github.io/textual-wasm/porting.html) — moving an app
+  you already have.
+- [Embedding](https://kaierikniermann.github.io/textual-wasm/embedding.html) — custom pages,
+  and Textual inside Svelte, Vue or plain HTML.
+- [Limitations](https://kaierikniermann.github.io/textual-wasm/limitations.html) — what does
+  not work, organised by *whose* constraint each one is.
+- [Browser support](https://kaierikniermann.github.io/textual-wasm/browsers.html) — measured
+  across three engines, and what that measurement does not cover.
+- [Feasibility study](./textual-wasm-feasability-study.md) — the architecture audit, what the
+  spike measured, and the claims it corrected.
+
+### Examples
+
+| | |
+|---|---|
+| [`simple-app`](./examples/simple-app) | A task list. The smallest complete thing. |
+| [`embedded-page`](./examples/embedded-page) | The terminal as one component of an article, driven by HTML buttons. |
+| [`svelte-app`](./examples/svelte-app) | Mounted in a Svelte 5 component, with Svelte state around it. |
+
+Each is a self-contained project with its own `pyproject.toml`, README and linting — copy one
+out and it works.
+
+## How the pieces fit
+
+```
+bootstrap.py   TEXTUAL_* env, applied before the first `import textual` (it caches at import)
+polyfills.py   runtime bugs, quarantined and reported
+driver.py      WasmDriverBase  ->  CaptureDriver (sink: a list)
+browser.py     WasmDriverBase  ->  BrowserDriver (sink: xterm.js)
+target.py      which app, and how a harness knows it drew
+probe.py       the experiment, over any app
+check.py       every runtime this machine has, and the comparisons
+substitutions  the registry: one source for the analyser, the guards and the docs
+```
+
+Nothing in the probe, the driver, the app or the report may branch on `sys.platform` — a
+semgrep rule enforces it. Runtime differences are confined to `polyfills.py` and recorded in
+the report, so a WASM run can never look accidentally native.
+
+## Development
+
+```bash
+poetry install
+pnpm install                                 # only for the wasm and browser legs of `check`
+poetry run pytest                            # includes a selftest of the semgrep rules
+pnpm lint:all                                # eslint (css + js), stylelint, principled-css
+poetry run textual-wasm pins                 # regenerate wasm-requirements.txt
+poetry run textual-wasm matrix -o docs/porting-matrix.md
+git config core.hooksPath .githooks          # lint, types, complexity, policy, tests
+./scripts/run-spike.sh                       # the whole matrix, strictly
+```
+

textual_wasm-0.1.0/README.md

@@ -0,0 +1,151 @@
+# textual-wasm
+
+[![ci](https://github.com/KaiErikNiermann/textual-wasm/actions/workflows/ci.yml/badge.svg)](https://github.com/KaiErikNiermann/textual-wasm/actions/workflows/ci.yml)
+[![docs](https://github.com/KaiErikNiermann/textual-wasm/actions/workflows/pages.yml/badge.svg)](https://kaierikniermann.github.io/textual-wasm/)
+[![python](https://img.shields.io/badge/python-3.12%2B-blue)](https://kaierikniermann.github.io/textual-wasm/installation.html)
+[![license](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
+
+Ship one [Textual](https://github.com/Textualize/textual) application as **both** a terminal
+TUI and a fully client-side web page — same source, no server-side Python process, no fork of
+Textual.
+
+**[Documentation](https://kaierikniermann.github.io/textual-wasm/)** ·
+**[Live demos](https://kaierikniermann.github.io/textual-wasm/examples.html)** ·
+**[Porting guide](https://kaierikniermann.github.io/textual-wasm/porting.html)**
+
+```bash
+textual-wasm build myapp.main:App myapp -o dist/   # a static directory
+textual-wasm dev dist/                             # http://127.0.0.1:8000
+```
+
+The output is static files. Pyodide and xterm.js come from a pinned CDN; your application is
+copied in as source. There is no build toolchain at the far end and nothing for the person
+deploying it to install.
+
+Textual itself is untouched. The extension point is a public one —
+`TEXTUAL_DRIVER=module:Symbol` (`textual/app.py:1585`) — so there is no patch to rebase.
+
+## The four commands
+
+| | |
+|---|---|
+| `textual-wasm doctor <module:App>` | What will break, with a `file:line`. Reads imports, **call sites**, and dependencies. |
+| `textual-wasm build <module:App> <package> -o dist/` | A static site. Bare page by default; `--title` and `--template` if you want otherwise. |
+| `textual-wasm dev dist/` | Serve it locally. Standard library only. |
+| `textual-wasm check --app <module:App>` | Run it on every runtime available and compare. |
+
+## What `check` actually checks
+
+Four runtimes, and two comparisons that mean something:
+
+| Leg | Runtime | Settles |
+|---|---|---|
+| native | CPython | The baseline. |
+| wasm | Pyodide under Node | Everything on the Python side, in CI, with no browser. |
+| browser | Chromium, Firefox **and** WebKit over a real `build` | Rendering, and whether the engines agree. |
+| terminal | a real pty via tmux, on Textual's own driver | What a user would actually see. |
+
+`native` against `wasm` is compared check-by-check, fact-by-fact and grid-by-grid.
+`terminal` against `browser` is compared cell-by-cell — that one is the render claim, and it
+is made against a real terminal rather than a replay because three different character-width
+tables are involved and they do not share code.
+
+A runtime this machine cannot reach is reported as **skipped, with the command that would
+enable it**, and the rest still produce a verdict. `--strict` makes a skip a failure, which
+is what CI wants.
+
+```
+textual_wasm.app:SpikeApp at 80x24
+┏━━━━━━━━━━┳━━━━━━━━━┳──────────────────────────────────────┓
+┃ runtime  ┃ status  ┃ detail                               ┃
+┡━━━━━━━━━━╇━━━━━━━━━╇──────────────────────────────────────┩
+│ native   │ ran     │ 8 checks, 0 failed                   │
+│ wasm     │ ran     │ 0 check(s) failed                    │
+│ browser  │ ran     │ 19 rows rendered                     │
+│ terminal │ ran     │ tmux 3.7c                            │
+└──────────┴─────────┴──────────────────────────────────────┘
+identical: terminal and browser render the same
+equivalent across 4 runtime(s)
+```
+
+Nothing the probe measures is asked of your app: the timer is scheduled by the probe, the
+resize is read back off the `Screen` it laid out, and input is judged by what appears on the
+grid. An app that has never heard of this project is measured by exactly the code that
+measures the one that ships with it.
+
+## Diagnostics
+
+Pyodide's most dangerous failures are the ones that raise nothing. `os.system()` returns 0
+and does nothing; `loop.run_in_executor()` ignores the executor and runs inline on the only
+thread, so code written to keep a UI responsive freezes the page instead.
+
+`textual_wasm.diagnostics.install()` manufactures a loud, specific failure for each, naming
+the substitute. `diagnostics.attach(app, driver)` moves crash output off stderr — which under
+Pyodide is a browser console nobody is watching — and into the terminal the user is looking
+at. The build output does both for you.
+
+Every one of those claims is **measured, not transcribed**, and the
+[porting matrix](./docs/porting-matrix.md) is generated from the same registry the analyser
+and the guards read. A test fails when it drifts; a characterisation suite re-measures the
+registry inside a real Pyodide. Pyodide's own documentation lists four modules as removed
+that import fine in 314.0.6, which is what a hand-maintained table gets you.
+
+## Documentation
+
+The [documentation site](https://kaierikniermann.github.io/textual-wasm/) is itself the proof:
+every demo on it is a real build of a real Textual app, running in your browser, served as
+static files by GitHub Pages.
+
+- [Quickstart](https://kaierikniermann.github.io/textual-wasm/quickstart.html) — a new app in a
+  browser in five minutes.
+- [Porting guide](https://kaierikniermann.github.io/textual-wasm/porting.html) — moving an app
+  you already have.
+- [Embedding](https://kaierikniermann.github.io/textual-wasm/embedding.html) — custom pages,
+  and Textual inside Svelte, Vue or plain HTML.
+- [Limitations](https://kaierikniermann.github.io/textual-wasm/limitations.html) — what does
+  not work, organised by *whose* constraint each one is.
+- [Browser support](https://kaierikniermann.github.io/textual-wasm/browsers.html) — measured
+  across three engines, and what that measurement does not cover.
+- [Feasibility study](./textual-wasm-feasability-study.md) — the architecture audit, what the
+  spike measured, and the claims it corrected.
+
+### Examples
+
+| | |
+|---|---|
+| [`simple-app`](./examples/simple-app) | A task list. The smallest complete thing. |
+| [`embedded-page`](./examples/embedded-page) | The terminal as one component of an article, driven by HTML buttons. |
+| [`svelte-app`](./examples/svelte-app) | Mounted in a Svelte 5 component, with Svelte state around it. |
+
+Each is a self-contained project with its own `pyproject.toml`, README and linting — copy one
+out and it works.
+
+## How the pieces fit
+
+```
+bootstrap.py   TEXTUAL_* env, applied before the first `import textual` (it caches at import)
+polyfills.py   runtime bugs, quarantined and reported
+driver.py      WasmDriverBase  ->  CaptureDriver (sink: a list)
+browser.py     WasmDriverBase  ->  BrowserDriver (sink: xterm.js)
+target.py      which app, and how a harness knows it drew
+probe.py       the experiment, over any app
+check.py       every runtime this machine has, and the comparisons
+substitutions  the registry: one source for the analyser, the guards and the docs
+```
+
+Nothing in the probe, the driver, the app or the report may branch on `sys.platform` — a
+semgrep rule enforces it. Runtime differences are confined to `polyfills.py` and recorded in
+the report, so a WASM run can never look accidentally native.
+
+## Development
+
+```bash
+poetry install
+pnpm install                                 # only for the wasm and browser legs of `check`
+poetry run pytest                            # includes a selftest of the semgrep rules
+pnpm lint:all                                # eslint (css + js), stylelint, principled-css
+poetry run textual-wasm pins                 # regenerate wasm-requirements.txt
+poetry run textual-wasm matrix -o docs/porting-matrix.md
+git config core.hooksPath .githooks          # lint, types, complexity, policy, tests
+./scripts/run-spike.sh                       # the whole matrix, strictly
+```

textual_wasm-0.1.0/pyproject.toml

@@ -0,0 +1,154 @@
+[project]
+name = "textual-wasm"
+version = "0.1.0"
+description = "Ship a Textual TUI as both a terminal app and a client-side web page."
+authors = [{ name = "KaiErikNiermann", email = "61298289+KaiErikNiermann@users.noreply.github.com" }]
+readme = "README.md"
+license = "MIT"
+keywords = ["textual", "tui", "webassembly", "wasm", "pyodide", "xterm"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Environment :: WebAssembly :: Emscripten",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Build Tools",
+    "Topic :: Terminals",
+    "Typing :: Typed",
+]
+requires-python = ">=3.12,<4.0"
+dependencies = [
+    "textual (>=8.2,<9.0)",
+    "typer (>=0.15,<1.0)",
+    "rich (>=13.0)",
+    "pyte (>=0.8.2,<0.9.0)",
+    "pyodide-lock (>=0.2.1,<0.3.0)",
+    "packaging (>=26.3,<27.0)",
+]
+
+[project.scripts]
+textual-wasm = "textual_wasm.cli:app"
+
+[project.urls]
+Homepage = "https://github.com/KaiErikNiermann/textual-wasm"
+Documentation = "https://kaierikniermann.github.io/textual-wasm/"
+Repository = "https://github.com/KaiErikNiermann/textual-wasm"
+Issues = "https://github.com/KaiErikNiermann/textual-wasm/issues"
+
+[tool.poetry]
+packages = [{ include = "textual_wasm", from = "src" }]
+# The page, its stylesheet, the browser entry script and the two JavaScript harnesses are
+# not Python and are all load-bearing: without them `build` writes an empty site and `check`
+# has no wasm or browser leg. Named explicitly rather than relying on the backend's defaults.
+include = [
+    { path = "src/textual_wasm/assets/**/*", format = ["sdist", "wheel"] },
+    { path = "src/textual_wasm/harness/*.mjs", format = ["sdist", "wheel"] },
+]
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.3"
+pytest-asyncio = "^1.4"
+ruff = "^0.16"
+pyright = "^1.1"
+radon = "^6.0"
+semgrep = "^1.100"
+pyyaml = "^6.0.3"
+types-pyyaml = "^6.0.12.20260906"
+
+
+[tool.poetry.group.docs.dependencies]
+sphinx = "^9.1.0"
+furo = "^2025.12.19"
+myst-parser = "^5.1.0"
+sphinx-copybutton = "^0.5.2"
+sphinx-design = "^0.7.0"
+
+[build-system]
+requires = ["poetry-core>=2.0"]
+build-backend = "poetry.core.masonry.api"
+
+# --- Ruff -------------------------------------------------------------------
+[tool.ruff]
+src = ["src", "tests"]
+# Deliberately non-compliant code that exists to prove the semgrep rules still fire.
+extend-exclude = ["tests/semgrep/positive", "tests/doctor"]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = [
+    "E", "W",    # pycodestyle
+    "F",         # pyflakes
+    "I",         # isort
+    "N",         # pep8-naming
+    "UP",        # pyupgrade
+    "B",         # bugbear
+    "A",         # builtins shadowing
+    "C4",        # comprehensions
+    "DTZ",       # naive datetimes
+    "ISC",       # implicit str concat
+    "PIE",       # misc lints
+    "PT",        # pytest style
+    "RET",       # return
+    "SIM",       # simplify
+    "TID",       # tidy imports
+    "PTH",       # use pathlib
+    "PL",        # pylint
+    "TRY",       # tryceratops
+    "RUF",       # ruff-specific
+    "ANN",       # annotations (pyright-strict's partner)
+    "S",         # bandit
+]
+ignore = [
+    "ANN401",  # Any is banned by convention, not by this rule's blunt form
+    "TRY003",  # long messages inside raise are fine and more useful than a constant
+    "ISC001",  # conflicts with the formatter
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["S101", "PLR2004"]  # asserts and literal comparisons are the point of a test
+# A Typer command's options *are* its parameters: there is no object to group them into that
+# the decorator would still read. The rule is about functions that grew too many arguments,
+# and a command with four ways to name an application and two to size a grid is not that.
+# PLR0917 is the same judgement for the positional-only count, stabilised in ruff 0.16.
+"src/textual_wasm/cli/*" = ["PLR0913", "PLR0917"]
+
+[tool.ruff.lint.flake8-tidy-imports]
+ban-relative-imports = "all"
+
+# --- Pyright ----------------------------------------------------------------
+[tool.pyright]
+include = ["src", "tests", "scripts"]
+exclude = ["tests/semgrep/positive", "tests/doctor"]
+# Hand-written stubs for the Pyodide `js` module, which exists only inside the runtime.
+stubPath = "typings"
+# `js` is stub-only by nature: the module exists only inside the Pyodide runtime, so a
+# missing source is the expected state rather than a finding.
+reportMissingModuleSource = "none"
+pythonVersion = "3.12"
+typeCheckingMode = "strict"
+reportMissingTypeStubs = false
+venvPath = "."
+venv = ".venv"
+
+# --- Pytest -----------------------------------------------------------------
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+addopts = "-q --strict-markers"
+markers = [
+    # Boots a real Pyodide runtime. Measured at ~4s for the whole set, so these run by
+    # default: a characterisation test that is deselected by default is a test that rots,
+    # which is the exact failure the registry exists to prevent. Deselect with
+    # `-m "not slow"` when working offline.
+    "slow: re-measures a claim inside a real Pyodide runtime",
+    # Needs a Playwright browser *binary*, not just the package - `pnpm exec playwright
+    # install` territory. Separate from `slow` because the two have different remedies and
+    # because CI runs them in different jobs: only the `check` matrix has engines. Deselect
+    # with `-m "not browser"`; a machine without one otherwise sees a launch failure rather
+    # than a skip, which is the honest outcome for a measurement that cannot be taken.
+    "browser: drives a real browser engine",
+]
+filterwarnings = ["error"]

textual_wasm-0.1.0/src/textual_wasm/__init__.py

@@ -0,0 +1,41 @@
+"""Feasibility spike for running Textual fully client-side under WebAssembly.
+
+The package core contains no runtime-specific branching: the same
+:func:`textual_wasm.probe.run_probe` coroutine is executed by the native CLI and by the
+Pyodide harness, and any divergence between the two reports is the finding.
+
+Importing this package applies :data:`textual_wasm.bootstrap.REQUIRED_ENVIRONMENT` and any
+runtime shim :mod:`textual_wasm.polyfills` finds necessary. That has
+to happen before the first `import textual` anywhere in the process — see
+:mod:`textual_wasm.bootstrap` for why — and a package `__init__` is the only place that can
+be guaranteed to run before its own submodules.
+"""
+
+from textual_wasm.bootstrap import DRIVER_IMPORT_PATH, REQUIRED_ENVIRONMENT, apply_environment
+from textual_wasm.polyfills import IS_EMSCRIPTEN, apply_polyfills
+
+apply_environment()
+APPLIED_POLYFILLS = apply_polyfills()
+"""Runtime shims this process needed; surfaced in the probe report."""
+
+from textual_wasm.report import (  # noqa: E402 - must follow apply_environment()
+    CheckId,
+    CheckResult,
+    CheckStatus,
+    ProbeReport,
+    RuntimeFacts,
+)
+
+__all__ = [
+    "APPLIED_POLYFILLS",
+    "DRIVER_IMPORT_PATH",
+    "IS_EMSCRIPTEN",
+    "REQUIRED_ENVIRONMENT",
+    "CheckId",
+    "CheckResult",
+    "CheckStatus",
+    "ProbeReport",
+    "RuntimeFacts",
+    "apply_environment",
+    "apply_polyfills",
+]

textual_wasm-0.1.0/src/textual_wasm/__main__.py

@@ -0,0 +1,9 @@
+"""Entry point for `python -m textual_wasm`.
+
+The commands live in :mod:`textual_wasm.cli`; this module only starts them.
+"""
+
+from textual_wasm.cli import app
+
+if __name__ == "__main__":
+    app()

textual_wasm-0.1.0/src/textual_wasm/app.py

@@ -0,0 +1,104 @@
+"""The minimal Textual application the probe drives by default.
+
+Deliberately tiny, and deliberately ordinary: it uses nothing a WASM host has to special-case,
+so that any failure the probe reports is a failure of the *runtime*, not of the app.
+
+It carries no probe instrumentation, and that is the point. The probe schedules its own
+timer, reads the resize off the `Screen`, and judges input by what appears on the grid - so
+this app is measured by exactly the code that measures anyone else's, and a check that only
+passes because the app cooperated cannot exist.
+"""
+
+from __future__ import annotations
+
+from typing import ClassVar, Final
+
+from textual.app import App, ComposeResult
+from textual.binding import Binding, BindingType
+from textual.widgets import Label, Static
+
+MARKER: Final[str] = "TEXTUAL-WASM-SPIKE"
+"""Text that means this app has drawn - `AppTarget.ready_marker` for the default target."""
+
+HINT_ID: Final[str] = "hint"
+"""Widget whose text reports the key-press count, so input is visible and not just asserted."""
+
+HINT_TEMPLATE: Final[str] = "press 'a' - pressed {count}"
+"""What that widget says. Module level because `AppTarget.settled_marker` is a substring of
+it, and a test pins the two together - a settled marker that no longer matches what the app
+draws does not fail loudly, it makes every harness wait out its timeout."""
+
+WIDTH_SAMPLES: Final[tuple[tuple[str, str], ...]] = (
+    ("ascii", "abcdef"),
+    ("box", "\u2500\u2502\u250c\u2510\u2514\u2518\u251c\u2524"),
+    ("arrows", "\u2190\u2191\u2192\u2193"),
+    ("braille", "\u2801\u2802\u2803\u2804\u2805"),
+    ("cjk", "\u4e16\u754c\u65e5\u672c\u8a9e"),
+    ("combining", "e\u0301a\u0300"),
+    ("astral", "\U0001f680\U0001f4bb"),
+    ("vs16", "\u2705\u26a0\ufe0f"),
+    ("zwj", "\U0001f469\u200d\U0001f4bb"),
+)
+"""Character classes whose cell width three different tables have to agree on.
+
+Textual lays out with rich's `cell_len`, `pyte` replays with `wcwidth`, and `xterm.js` uses
+its own - none of them shared code. Each sample is followed by a terminator in
+:data:`WIDTH_TERMINATOR`, so a disagreement moves that character into a different column and
+the screen diff names the row and the column rather than merely failing.
+
+Ordered easiest-first: ASCII and box drawing are unanimous, CJK is where a naive table goes
+wrong, and astral-plane characters are where a UTF-16 emulator can miscount.
+
+Two classes are deliberately absent, and their absence is a finding rather than an
+omission. `pyte` 0.8.2 **silently discards the remainder of the line** after a zero-width
+joiner (U+200D) or a variation selector (U+FE0F): fed `"\N{WARNING SIGN}\ufe0f|"` it
+renders `"\N{WARNING SIGN}"` and the terminator is gone. `xterm.js` preserves both. So on
+emoji sequences the oracle is wrong and the browser is right, which means pyte cannot
+adjudicate them at all - including them would only measure the measuring instrument.
+Settling emoji needs a different reference, such as a real terminal captured through
+`tmux capture-pane`.
+"""
+
+WIDTH_TERMINATOR: Final[str] = "|"
+"""Marks where the preceding sample ended. A width disagreement shifts it."""
+
+
+class SpikeApp(App[int]):
+    """A one-widget app with a keybinding, drawn at a range of awkward character widths."""
+
+    CSS = """
+    Screen { align: center middle; }
+    #marker { color: $success; border: round $accent; padding: 1 2; }
+    """
+
+    BINDINGS: ClassVar[list[BindingType]] = [
+        # `priority` so the binding fires from the app regardless of what holds focus; the
+        # probe is testing the input path, not Textual's focus resolution.
+        Binding("a", "bump", "Bump the counter", priority=True),
+    ]
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.bump_count: int = 0
+        """Incremented by the `a` binding, i.e. by bytes that went through `XTermParser`."""
+
+    def compose(self) -> ComposeResult:
+        yield Label(MARKER, id="marker")
+        yield Static(id=HINT_ID)
+        for name, sample in WIDTH_SAMPLES:
+            yield Static(f"{name:<10}{sample}{WIDTH_TERMINATOR}", classes="width-sample")
+
+    def on_mount(self) -> None:
+        self._refresh_hint()
+
+    def action_bump(self) -> None:
+        self.bump_count += 1
+        self._refresh_hint()
+
+    def _refresh_hint(self) -> None:
+        """Put the count on screen.
+
+        On screen rather than only in an attribute: every harness judges input by what it can
+        read back off the grid, so a counter that is not drawn is a counter no leg can see.
+        """
+        self.query_one(f"#{HINT_ID}", Static).update(HINT_TEMPLATE.format(count=self.bump_count))