One coherent change: make the mudlib TUI library (/std/tui) work in the
browser on BOTH web terminals, harden everything the work surfaced, and
pin the toolchain that broke it.
## Web terminals: xterm.js + a shared telnet client
* Vendor @xterm/xterm 6.0.0 + @xterm/addon-fit 0.11.0 (dist files
byte-exact from the official npm tarballs, licenses included) under
src/www/vendor/. xterm.js does the terminal emulation on both pages:
rendering, SGR 16/256/truecolor, alternate screen, cursor state, wide
characters, scrollback, mouse reporting, bracketed paste, and keyboard
encoding (the whole dialect testsuite/std/tui/keys.lpc decodes,
including C-_ undo).
* src/www/telnet.js -- one telnet option engine shared by both pages
(transport-agnostic; hooks for page-specific options): ECHO masks the
password prompt, WILL/WONT SGA -- the driver's char-mode signal
(set_charmode) -- automatically switches between the line-input bar
and raw keystroke streaming, NAWS reports real terminal geometry from
the fit addon and re-reports on resize (driving the window_size
apply), TTYPE answers xterm-256color.
* src/www/wasm/index.html (the wasm shell): output/input rides xterm.js;
the page keeps the synchronous-bridge queueing (sends flush outside
receive() -- the wasm bridge re-enters the parser otherwise), the
error modal, and the jsbridge handlers. Also guards
crypto.getRandomValues() against views backed by resizable
ArrayBuffers (see the emsdk section below).
* src/www/index.html (the websocket client for the native driver):
rewritten on the same stack, replacing a parseANSI() that stripped all
cursor sequences (no TUI possible) and a telnet layer whose option
bytes leaked into the text stream and never answered negotiations.
Passwords now mask, char mode works, GMCP/MSP kept (dead
TelnetOverWebSocket/handler classes removed); ws frames arrive as
arraybuffers (no Blob/FileReader path); UTF-8 and telnet sequences
survive frame splits (streaming decode + stateful parser).
* tools/wasm/pack-mudlib.sh and the release zip ship vendor/ and
telnet.js next to index.html in both layouts.
## Driver: websocket output wedged permanently on multi-window bursts
Re-arming the writeable event from inside LWS_CALLBACK_SERVER_WRITEABLE
is lossy with the libevent event lib: after the user callback returns,
lws core clears POLLOUT and its pollfd bookkeeping desyncs from the
evlib watcher -- the request is dropped and every later
lws_callback_on_writable() no-ops, freezing output on that connection
for good. First bites on any burst larger than one 2048-byte window
(e.g. a full-screen TUI frame; no test had ever pushed one through a ws
client). The ws_telnet.cc/ws_ascii.cc handlers now drain the evbuffer in
a loop gated on lws_send_pipe_choked(); a choked write is flushed by
lws's own core-managed POLLOUT path, which fires the callback again.
Found by the browser end-to-end run below; documented in AGENTS.md 14.
## TUI library (/std/tui): review fixes + features
Fixes: wslice() dropped combining marks from every sliced render;
ESC[1;mR (modified F3) misdecoded as a cursor position report; readline
lost the left scroll marker when a line overflowed both viewport edges;
stray mouse events cancelled incremental search; Tab on a unique
already-complete match missed the trailing space; menu lines wider than
the terminal wrapped and desynced the in-place repaint (width now fed by
the glue and re-fed on NAWS resize); the menu overflow indicator only
showed below the window; backward focus cycling from the initial state
skipped the last widget; a terminal-initiated close (disconnect,
tui_destroy) leaked the app clone and its widgets -- teardown now runs
through a reentry-guarded app_quit() in both directions.
Features (from the README's own deferred list): readline C-_ undo
(per-keystroke snapshots); pterm-style type-to-filter in select/
multiselect (results index the original choices); mouse-wheel scrolling
in list/table/tree/log (wheel no longer click-selects); table clicks
honour the header offset; tree Left on a leaf jumps to its parent.
All pinned by testsuite/single/tests/std/tui/fixes.lpc, including the
app teardown cycle via a runtime-written mock terminal.
## Toolchain: pin emsdk, guard random_get()
emsdk 6.0.2 defaulted GROWABLE_ARRAYBUFFERS=1, making every
ALLOW_MEMORY_GROWTH build's heap a resizable ArrayBuffer
(wasmMemory.toResizableBuffer()) in browsers shipping the wasm
rab-integration -- and two emscripten runtime paths pass raw
HEAPU8.subarray() views into Web APIs that reject resizable-backed
views: random_get() -> crypto.getRandomValues() (threw at boot) and
UTF8ToString() -> TextDecoder (broke jsbridge). 6.0.3 reverted the
default AND fixed the string codegen (getUnsharedTextDecoderView ->
getHeapViewOrCopy), but random_get() is still unguarded upstream.
Reproduced and certified against real 6.0.2/6.0.3 toolchains in
Chromium (--js-flags=--experimental-wasm-rab-integration): 6.0.2
unpatched throws the exact boot error, 6.0.2 + the page's
getRandomValues wrapper passes, 6.0.3 passes. CI now installs a pinned
emsdk-ver input (default 6.0.3) instead of "latest".
## Verification
* Native Debug+ASan: GTest 312/312; full LPC suite (574 files, per-file
ref-count checker) x3 across the work; TUI test dir x3 randomized.
* LPC suite inside the wasm driver under node: 5274 checks, 574 files.
* Browser e2e (Playwright + Chromium): wasm shell 21/21 checks
(charts/SGR, char-mode auto-switch, readline editing + undo +
history, select with filter, multiselect/confirm, full-screen app,
dashboard live repaint + NAWS resize relayout); websocket client
against the native driver 13/13 twice on one instance (plus an
ascii-subprotocol multi-window burst) -- the flow that caught the lws
wedge.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018UvX1HbmGk9zWGBsW4Rkcq
* docs: fully-expandable generated sidebar, replacing index.md link pages
Rework docs navigation so the sidebar expands to every page of every
reference tree, instead of terminating at generated index.md link lists:
- New docs/gen_sidebar.py (replaces gen_index.py + update_index.sh):
walks efun/, apply/, stdlib/, concepts/, driver/, cli/ and zh-CN/ and
emits sidebars.generated.json — a full Docusaurus category tree per
directory. Category landing pages are now `generated-index` card pages
(title/description/slug), so all generated index.md files are deleted.
--check mode verifies freshness; new .github/workflows/docs-sidebar.yml
runs it in CI.
- New docs/sidebar_meta.json holds curated presentation: category labels,
one-line descriptions (shown on the landing cards), explicit ordering
(driver/cli/concepts read top-down from user-facing to internals) and
per-page label overrides.
- sidebars.ts becomes a hand-authored skeleton (Getting Started, lpc/,
Historical) that splices in the generated trees.
Content reorganization (from a docs-wide review):
- Move misplaced efun pages out of efun/general: terminal/protocol efuns
(act_mxp, send_zmp, request_term_*) to interactive/, debugging efuns
(check_memory, dump_*, clear_debug_level, destructed_objects) to
internals/, shallow_inherit_list to system/.
- Delete stub duplicates superseded by complete pages elsewhere:
general/parse_{add_synonym,dump,my_rules,remove}, contrib/{shuffle,
element_of}.
Modernize key pages with MDX:
- index.mdx: landing page with a card grid linking each doc section.
- build.mdx: per-platform <Tabs> (Ubuntu/macOS/Windows/Alpine+Docker),
admonitions, VitePress [[toc]] leftover removed, stale per-platform CI
workflow links updated to the unified ci.yml.
- ffi-plan.md: GitHub-style [!CAUTION] alert converted to an admonition.
`npm run build` passes clean (onBrokenLinks: throw, no warnings).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0174GM2azvAHBmvyESwxm5om
* docs: serve the Chinese corpus through Docusaurus i18n
Move the zh-CN/ directory out of the default docs tree and into a proper
Docusaurus locale (i18n/zh-CN/docusaurus-plugin-content-docs/current/):
- The flat zh-CN/efun/ directory (333 pages) is re-homed to mirror the
categorized English layout (name-matched 1:1; `hash` maps to strings/
per its own frontmatter). apply/ pages map 1:1; the stray English-text
zh-CN/apply/master/view_errors.md documents a MudOS-era apply that no
longer exists in the driver and is dropped; stdlib/db/database_zh.md
becomes the i18n translation of stdlib/db/database.md; the Chinese
build guide becomes the translation of build.mdx.
- Untranslated pages automatically fall back to English content under
/zh-CN/, so the whole site is navigable in either locale from the new
navbar locale dropdown.
- Both locales share one sidebar. Generated sidebar items now carry
stable `key` fields (the directory/doc path) so translation keys are
unique (both efun/ and stdlib/ have an "Arrays" category, crypto and
strings both document `hash`). Category labels, generated-index
titles/descriptions, navbar and footer are translated in
i18n/zh-CN/...; theme UI strings come from Docusaurus' bundled
zh-Hans translations. Translated landing page at /zh-CN/.
- The "中文文档" sidebar section, the zh-CN tree in gen_sidebar.py /
sidebar_meta.json, and its slice of sidebars.generated.json are gone.
- Relative .md-file links on pages that render in both locales break
the localized build (the file->permalink map points at the localized
copy), so concepts/, the two socket_*_option pages and the config.md
generator now emit extension-less route links instead.
- zh interactive.md/objects.md get explicit slugs like their English
counterparts (a doc named after its parent directory is otherwise a
Docusaurus category-index doc, colliding with the generated-index
route).
`npm run build` builds both locales clean (onBrokenLinks: throw).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0174GM2azvAHBmvyESwxm5om
---------
Co-authored-by: Claude <noreply@anthropic.com>
* Char-mode input: deliver real keystrokes (BS/DEL, whole UTF-8, raw ESC); fix NAWS lost at logon
Five input-path fixes that make raw-keystroke (get_char) applications
viable, found by building the LPC TUI library on top of them:
- comm.cc: char mode delivered "" for Backspace/Delete (the byte was
zeroed before delivery, making BS/DEL/NUL indistinguishable). The
literal byte is now delivered; line-mode in-buffer editing unchanged.
- comm.cc: char mode delivered one *byte* per callback, splitting a
multi-byte UTF-8 character into 2-4 invalid one-byte strings.
Extraction is now UTF-8 aware: a complete sequence arrives as one
callback carrying one valid character; malformed bytes still go
byte-at-a-time (no stalls).
- comm.cc: the "no ansi" + "strip before process input" ESC->space
rewrite (both default on) also applied to char mode, so arrow keys
arrived as literal "[A". The rewrite is an anti-ANSI-injection
protection for line-mode commands; char mode now always passes ESC
through.
- net/telnet.cc: each received chunk was u8_sanitize()d independently,
so a UTF-8 character split across TCP segments became U+FFFD in any
input mode. An incomplete trailing sequence (new u8_incomplete_tail(),
GTest-covered) is now carried over in interactive_t and prepended to
the next chunk.
- net/telnet.cc + comm.cc: fast clients answer the initial DO NAWS
while ip->ob is still the master object, so the window_size apply
fired on the wrong object and the size was lost until the next
resize. The last report is cached and replayed on the user object at
logon.
docs/efun/interactive/get_char.md documents the delivery contract.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RpXv4yGCWpkzbkifyZy9EE
* Add /std/tui: an LPC TUI library (readline + ncurses for the prompt line and full-screen apps)
A terminal-UI toolkit in pure LPC, strictly layered (design + rationale
in testsuite/std/tui/DESIGN.md; user docs in docs/concepts/general/tui.md):
- ansi.lpc: escape builders plus the width toolkit the driver lacks
(visible_width/wslice/wpad are ANSI-blind and wide-char aware).
- keys.lpc: keystroke decoder state machine: the get_char byte stream ->
key events (CSI/SS3 with xterm modifiers, Alt prefixes, bracketed
paste as one event, SGR mouse, UTF-8, lone-ESC via caller-driven
flush()).
- readline.lpc: the line editor: emacs keymap (motion/kill/yank/
transpose), Up/Down history, C-r/C-s incremental search, Tab
completion, masked mode, horizontal scrolling with wide-char aware
viewport; repaints only its own line so it works at any scroll
position.
- screen.lpc: virtual cell grid + minimal-diff frame renderer with
copy-on-write rows (frame cost tracks touched rows, not W x H);
wide chars own two cells, boxes/fills/attrs as SGR param strings.
- widget.lpc + w/ (label, list, textfield) + app.lpc: widget protocol,
focus cycling, event routing; textfield embeds a readline engine.
- terminal.lpc: the one impure module, inherited by the user object:
get_char re-arm loop (I_NOECHO across re-arms), NAWS/TTYPE caching
via the window_size/terminal_type applies, lone-ESC walltime timeout,
guaranteed teardown. tui_readline() is a drop-in input_to()
replacement; tui_open() runs full-screen apps on the alt screen.
Everything below terminal.lpc is a pure state machine: 194 checks in
single/tests/std/tui/ cover the decoder, editor sessions, history
search, screen diffing and widgets headlessly. `tuidemo` /
`tuidemo app` (command/tuidemo.lpc) demo both modes over any telnet
client; the whole stack was verified end-to-end over a live connection
including split-packet UTF-8, modifier keys, paste, resize and
alternate-screen teardown.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RpXv4yGCWpkzbkifyZy9EE
* /std/tui v2: pterm/blessed-inspired widgets, inline printers and prompts, showcases
Reviewed the pterm (Go) and blessed widget catalogs and ported what earns
its keep in a MUD; DESIGN.md is renamed to README.md and documents the
full set (including what was deliberately not ported).
New layers:
- print.lpc — pterm-style printers that compose with plain write():
p_table (boxed, width-aware, header rule), p_tree, p_bars, p_spark,
p_panel, p_bullets, p_header, p_progress, p_info/success/warn/error,
and p_bigtext via the existing /std/bitmap_font.
- menu.lpc + terminal glue — inline interactive prompts in the normal
output flow: tui_select(), tui_multiselect() (Space toggles, list
windows by height, collapses to a "? prompt: answer" line) and
tui_confirm() (y/n with a default).
New widgets (/std/tui/w/): table (columns + header + selection), tree
(collapsible, arrows fold), checklist, radiolist, button, progress,
spinner (app-driven tick()), and log (bottom-anchored scrollback pane).
Showcases (command/tuidemo.lpc): `tuidemo select` (prompt chain),
`tuidemo print` (all printers), `tuidemo dashboard` (animated spinner,
progress bars, sparkline, live table and log on a call_out tick), and
`tuidemo form` (textfield, radio group, checkboxes, buttons).
Coverage: three new test files (print exact-output, menu sessions,
widgets2) bring /std/tui to 8 files in the suite; the live-connection
e2e run now drives all six showcases end-to-end (52 checks), including
the select->multiselect->confirm chain, unattended dashboard animation,
and full form entry.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RpXv4yGCWpkzbkifyZy9EE
* /std/tui: charts — braille canvas, line charts, vertical bars, heatmap
Fills the chart gap left by v2 (only the horizontal p_bars existed):
- canvas.lpc: a braille dot canvas (each cell is a 2x4 dot grid from the
U+2800 block — the blessed-contrib/drawille technique), giving sub-cell
resolution: c_set/c_unset/c_get, Bresenham c_line, and c_plot (scale a
value series across the canvas), with per-cell colour. Renders as a
string, per-row strings, or per-cell ({ ch, attr }) pairs for blitting
into a screen.
- print.lpc: p_chart (multi-series braille line chart with y-axis gutter
and coloured legend), p_vbars (vertical bar chart with eighth-block
partial tops and optional value row), p_heatmap (2D matrix as
256-colour cells, cool-to-hot ramp, optional axis labels).
- w/chart.lpc: the live line-chart widget — add_series()/add_point()
rolling history sized to the widget, auto or fixed y-range; replaces
the dashboard's sparkline label with a real animating graph.
- `tuidemo charts` showcase; chart docs in README.md and the docs page
(heatmap removed from the not-ported list).
Tests: single/tests/std/tui/charts.lpc pins the braille bit math with
exact glyphs, line drawing, plot endpoints, exact p_vbars output,
chart/heatmap structure, and the widget's rolling window. The live e2e
run verifies `tuidemo charts` output and braille frames streaming from
the dashboard chart.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RpXv4yGCWpkzbkifyZy9EE
* docs: move the TUI page from Concepts to STDLIB
/std/tui is a mudlib library like base64/break_string/json, so its page
belongs under docs/stdlib/ with the rest of the /std modules, not under
Concepts. Registered in stdlib/index.md; README file-layout pointer
updated. (Concepts' sidebar is autogenerated, so the old entry disappears
with the file.)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RpXv4yGCWpkzbkifyZy9EE
---------
Co-authored-by: Claude <noreply@anthropic.com>
* docs: add local full-text search and a contributor README
Add @easyops-cn/docusaurus-search-local to the Docusaurus site so the
docs get an offline search bar (index built at build time, no external
service). English and zh-CN pages are both indexed, and matched terms
are highlighted on the target page.
Add docs/README.md describing the Docusaurus setup, local dev/build
commands, search behavior, directory layout, and gotchas; exclude it
from the published site alongside CLAUDE.md. Point the root README's
docs/ entry at it.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TSzcESzU9947zkGzQ6SMmE
* docs: remove dead framework leftovers, fix index generation, complete the nav
Delete the VitePress (.vitepress/) and Jekyll (_layouts/, css/) leftovers,
the one-shot migration scripts (fix_md_header.py, fix_seealso.py), and the
stale keywords.json snapshot; prune the matching .gitignore entries and
docusaurus exclude patterns.
Rewrite gen_index.py for Docusaurus: it emitted dead .html links and
legacy 'layout: doc' frontmatter, choked on non-markdown entries, and
dropped nested categories — regenerating an index would have broken it.
It now emits the extension-less links the site actually uses, links
nested category indexes (restoring apply/* on the zh-CN index), and
refuses to run on the docs root. Fix update_index.sh's copy-paste titles
(zh-CN efun/build were titled 'APPLY'), stop it clobbering the
hand-written lpc/index.md, and cover cli/. Regenerated indexes pick up
the missing driver/ffi-plan entry. add_missing_efuns.py now takes the
keywords.json path as an argument instead of requiring a stale copy.
Move CNAME and the Google site-verification file into static/ so they
actually reach the published build output.
Complete the sidebar: link the CLI category to cli/index and add the
missing portbind/symbol/generate_keywords pages, and expose the
previously orphaned stdlib section under Reference.
Promote onBrokenLinks to 'throw' now the build is warning-free, and drop
the empty Demo section from the landing page.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TSzcESzU9947zkGzQ6SMmE
* docs: strip legacy 'layout: doc' frontmatter from all pages
Mechanical sweep removing the Jekyll-era 'layout: doc' line from every
doc page's frontmatter (Docusaurus ignores it), and the matching line
from the templates in docs/CLAUDE.md so new pages don't reintroduce it.
No content changes.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TSzcESzU9947zkGzQ6SMmE
---------
Co-authored-by: Claude <noreply@anthropic.com>
* Reorder sidebar: Driver > CLI > Reference (LPC Language, Apply, EFUN, Concepts)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* Fix Docusaurus build: broken links, duplicate routes, and gh-pages CI
- Strip .html from all markdown link targets (51 files) for Docusaurus URL routing
- Add slug: frontmatter to 4 files whose names match their parent directory
(interactive.md, objects.md, README.md, build.md) to prevent Docusaurus's
category-index convention from creating duplicate routes
- Fix one missed .html link in zh-CN/build/index.md
- Move onBrokenMarkdownLinks to markdown.hooks (Docusaurus v4 deprecation)
- Update gh-pages.yml: rename to Docusaurus, use node 22, correct build path
(docs/build instead of docs/.vitepress/dist)
Build now completes with [SUCCESS] and zero warnings or broken links.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
The package.json had dead Docusaurus deps from a previous setup while the
site itself was VitePress. This completes the migration back to Docusaurus
3.10.1 with its latest theme and features:
- Add docusaurus.config.ts with docs plugin (path: '.', routeBasePath: '/')
and markdown.format: 'detect' so .md files use standard markdown
- Add sidebars.ts converted from the VitePress sidebar.ts format
- Replace devDependency-only vitepress with full Docusaurus preset-classic
- Upgrade clsx 1.x → 2.x, prism-react-renderer 2.1 → 2.4, typescript 5.2 → 5.8
- Update index.md to add slug: / for the home page
- Escape {…} in 7 doc files where curly braces appeared in prose text and
were mis-parsed as JSX expressions
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* Added documentation for defer() efun
* Updated index to reflect defer() documentation
* Added documentation for new efun perf_counter_ns()
* Updated index to reflect perf_counter_ns() documentation
* Added documentation for new efun perf_counter_ns()
* Updated index to reflect perf_counter_ns() documentation
