The lws output wedge addressed in the previous commit was incompletely
understood: under genuine backpressure (peer slow or paused, kernel
send buffer full) a connection still froze permanently. Root cause,
established by tracing the writeable-request plumbing end to end:
lws_send_pipe_choked() is true not only when lws holds a truncated
send (lws re-arms the writeable callback itself then) but also when a
zero-timeout poll(POLLOUT) reports the socket simply full -- and in
that case every lws_write() has fully succeeded, lws has nothing
pending, and nobody re-arms anything. Fix, per lws README.coding.md:
whenever the drain loop exits with data still queued in pss->buffer,
request the next writeable callback. Queued data always has a callback
requested, so no exit path can strand output.
Also:
- LWS_CALLBACK_CLOSED frees the session evbuffer unconditionally: on
driver-initiated closes (e.g. the mudlib destructing the interactive)
close_user_websocket() nulls pss->user first, and the old early
return leaked the buffer every time.
- src/www/README.md + src/www/AGENTS.md: architecture doc and agent
checklist for the web terminal pages (xterm.js/telnet.js layering,
vendor policy, packaging, testing, the wedge mechanism).
- tools/ws-smoke.js, wired into CI on the Clang Debug matrix entries
(with and without sanitizers): a dependency-free node websocket
client that boots the real driver and exercises the http mount,
telnet + ascii subprotocols through the shared src/www/telnet.js,
SGA char-mode switching, live TUI streaming, TLS, and -- the actual
regression gate -- forced-backpressure bursts (paused socket, ~4.8MB)
on the plain and TLS ports plus a destruct-while-choked teardown
check. All three backpressure checks fail on the unfixed driver;
neither GTest nor the LPC suite exercises any websocket client
traffic.
- Fix stale src/www/wasm/vendor/ path references left from the vendor
directory move (src/wasm/README.md, docs/build-wasm.md, release.yml).
Validated on the ASan Debug build: forced-backpressure repros recover
the full burst on both subprotocols, destruct-while-choked clean under
ASan, ws-smoke 17/17, GTest 312/312, LPC testsuite clean.
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
Follow-up to reviewing PRs #1068 and #932, both of whose bugs are already
fixed on master:
- #1068 (call_out handles below the allocation counter rejected as
invalid) was fixed by #1220 with a regression test in
testsuite/single/tests/efuns/remove_call_out.lpc. Document the
guaranteed semantics in call_out.md / remove_call_out.md: a handle
stays valid until it fires or is removed, regardless of newer
call_outs; 0 is never a valid handle.
- #932 (an error thrown from valid_read during #include handling left
compile_file's reentrancy guard set, wedging all future loads) is
fixed by the compiler front-end rewrite: compile_file's scope guard
restores all compiler state and clears the guard on exception
unwinding. Document in valid_read.md that the apply runs mid-compile
for #include checks, must not trigger another compile, and that a
thrown error aborts only that compilation.
Claude-Session: https://claude.ai/code/session_01JRvUnh3x5MYPWPk2MiiUS2
Co-authored-by: Claude <noreply@anthropic.com>
* docs/tests: fix constructs index regression from #1196; add ref page to sidebar; extend & ref tests
- Restore extension-less links and the text_blocks entry in
docs/lpc/constructs/index.md (the PR was recreated from a pre-Docusaurus
branch and reintroduced .html links, which fail the docs build under
onBrokenLinks: 'throw', and dropped text_blocks)
- Add lpc/constructs/ref to the hand-authored sidebar in docs/sidebars.ts
- Drop the stale VitePress 'layout: doc' frontmatter from ref.md
- Extend testsuite/single/tests/operators/ref.lpc: & in parameter
declarations, ref keyword in foreach, and bitwise &/&= non-regression
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Skf9CfHwAngWorDNDzPKWp
* vm: fix string foreach crash and off-by-one ref reads; support += / -= on string chars
Three related defects around the shared string-codepoint lvalue
(global_lvalue_codepoint), all reproduced on the unfixed binary:
- Nested foreach over strings SEGFAULTED: the iteration cursor lived in
the shared global, so the inner loop's F_EXIT_FOREACH reset the
iterator out from under the outer loop (null deref in
post_index_to_offset). The EGC cursor now lives in each loop's own
stack slot (the T_NUMBER slot under the loop variable); the ref case
re-arms the shared codepoint lvalue every iteration, and exit only
clears the global when it still points at this loop's string slot.
- foreach (int ref c in str) read the WRONG characters: the shared
index was advanced before the body ran, so every read through the ref
was off by one ('abc' summed to 197 instead of 294, and the final
iteration read one past the end). The global index now stays on the
current character for the whole body. Writes through the ref still go
to the loop's by-value stack copy and never reach the iterated
variable -- semantics pinned by tests/operators/foreach.lpc.
- s[i] += n / s[i] -= n threw "Bad Argument 1 to +=()": F_ADD_EQ and
f_sub_eq handled buffer byte lvalues (T_LVALUE_BYTE) but not string
codepoint lvalues (T_LVALUE_CODEPOINT), even though ++/--/= worked.
Both now route through a new codepoint_lvalue_add() helper and produce
the resulting character as the rvalue.
Regression tests: nested (plain / ref / multi-byte UTF-8) string foreach
and ref-read correctness in tests/operators/foreach.lpc; compound
assignment on string chars (incl. reverse index, rvalue result, and
non-number rhs error) in tests/operators/string_index.lpc. Verified on
the unfixed binary: the nested-foreach test segfaults, the others fail.
Full LPC suite passes 2x on clang ASan/UBSan Debug and 2x on
RelWithDebInfo.
Docs: correct the ref.md note on foreach-over-strings; document the
string-char lvalue rules in AGENTS.md (section 8 + audit checklist 9)
and the ref/& feature in README.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Skf9CfHwAngWorDNDzPKWp
* vm: foreach ref over strings shares the s[i] char-lvalue logic; thorough ref tests
Arming a string-char lvalue now goes through one shared helper,
aim_lvalue_codepoint(): it validates the target EGC (out-of-bounds and
multi-codepoint error cleanly, same messages as s[i]) and points the
shared codepoint state at it. Both s[i] lvalues (push_indexed_lvalue)
and foreach ref loop variables use it, and every write consumer already
funnels into assign_lvalue_codepoint() -- so ref loop chars follow
exactly the s[i] rules:
- single-codepoint characters (and EGCs up to 4 bytes, which index as
their first codepoint) keep working: reads deliver the character,
assignments through the loop variable succeed
- wider EGCs (flag emoji, ZWJ sequences) now raise the catchable
"Indexed character is multi-codepoint" error when the ref loop
reaches them, instead of silently reading as -1; the non-ref form
still iterates and delivers -1 for such clusters
tests/operators/ref.lpc is now a thorough pass-by-reference suite:
ref/& parameter declarations and call arguments, by-value contrast,
ref forwarding through call chains, call-site refs to array elements /
mapping values / string chars (forward and reverse index, write-back),
foreach ref over arrays / mapping values / strings (read correctness,
multi-byte codepoints, by-value write semantics, assignment error
parity, the multi-codepoint error, non-ref contrast), compile-time
rejections via generated sources (ref outside an argument list, ref to
a range), and bitwise &/&= non-regression -- 39 checks.
Full LPC suite passes 2x on RelWithDebInfo and 2x on a clean clang
ASan/UBSan Debug build.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Skf9CfHwAngWorDNDzPKWp
* tests: cover ref across all LPC types
Extend tests/operators/ref.lpc to 58 checks: ref parameters of every
value type (int, float, string, array, mapping, object, function,
buffer, class, mixed) verifying reassignment propagates; the by-value
contrast for reference-typed containers (member writes propagate,
reassignment doesn't); call-site refs to buffer bytes (forward and
reverse index) and class members (both . and -> spellings); foreach
ref over mapping values of mixed types; the compile-time rejection of
a ref mapping KEY in foreach; and the clean runtime error for foreach
over a non-iterable type (buffer).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Skf9CfHwAngWorDNDzPKWp
* buffers behave like byte arrays: foreach, strict 0..255 bytes, string/array promotion, to_buffer()
Buffers are now first-class byte containers:
- foreach iterates a buffer like an array, delivering each byte as an
unsigned int 0..255. A ref loop variable mutates the buffer in place;
each ref carries its OWN T_LVALUE_BYTE (in ref->sv), so nested buffer
ref loops and b[i] lvalues in the body can't alias each other.
T_LVALUE_BYTE consumers now read the lvalue's own pointer/subtype
instead of reaching for the shared global_lvalue_byte (which remains
only as the scratch instance b[i] arms).
- every LPC byte write path (=, ++, --, +=, -=) range-checks the result:
a value outside 0..255 raises "Buffer byte value out of range" and
leaves the byte unchanged, instead of silently truncating/wrapping.
+= / -= on bytes also yield the resulting value as their rvalue.
- strings and arrays of ints 0..255 PROMOTE to buffers: a new
to_buffer() efun (registered like to_int/to_float) is wrapped around
the rhs by do_promotions() / rule_expr_assign for 'buffer b = str',
'b += str', initializers, and 'b + str'; range assignment and the
runtime + / += paths convert unpromoted (mixed) values through the
same svalue_to_buffer_bytes() helper. A string contributes its raw
UTF-8 bytes; an array must hold only ints 0..255 (validated before
allocation) or the conversion errors with the target unchanged.
- fixed a pre-existing ref_t leak: a foreach ref loop variable reused by
a re-entered inner loop leaked one ref per outer iteration (flagged by
the debug memory checker as 'Found temporary block: make_ref').
tests/operators/buffer_bytes.lpc pins the byte-range semantics, + / +=
concatenation, all promotion forms, and the error paths (106 checks);
foreach.lpc and ref.lpc pin buffer iteration and ref-loop independence;
buffer_range_assign.lpc gains range-read pins. New docs for to_buffer
(sidebar regenerated) and a rewritten lpc/types/buffer page.
Full LPC suite passes 2x on RelWithDebInfo and 2x on a clean clang
ASan/UBSan Debug build (no ref-checker warnings); GTest suite 312/312.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Skf9CfHwAngWorDNDzPKWp
---------
Co-authored-by: Claude <noreply@anthropic.com>
* empty
* docs: validate "See Also" references, drop dead ones, document valid_ffi
Reviewed the "See Also" section of every doc and dropped man-page
cross-references whose target page does not exist (verified against the
driver source, not just the docs tree):
- errorp, each, opcprof, dump_socket_status, extract, shadowp,
destruct_env_of, move, inventory_visible, inventory_accessible
These name efuns/applies that no longer exist in FluffOS. keys/values now
point at the `for` construct in place of the defunct `each` efun.
valid_ffi was the one "referenced but undocumented" case: it is a real
master apply (APPLY_VALID_FFI) gating every ffi_load/symbol/prepare/
callback, so it gets a proper apply page rather than having its references
removed. Sidebar regenerated to include it.
The 13 modern markdown-link "See Also" sections were already clean.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Adds '&' as an alternative to the 'ref' keyword for pass-by-reference in
parameter declarations, call arguments, and foreach loops. One-line grammar
change (the 'ref' rule now accepts both L_REF and '&'); no ambiguity with
binary bitwise AND since ref is always in prefix position. Includes
regenerated parser, testsuite coverage, and new docs for the ref construct.
* empty
* docs: flesh out 31 TBW efun reference pages
Replace the placeholder "TBW" DESCRIPTION and type-only SYNOPSIS in 31
efun docs with real descriptions and named parameters, verified against
the driver source:
- math (general/): log10, log2, norm, dotprod, distance, angle
- matrix (general/): id_matrix, translate, scale, rotate_x/y/z,
lookat_rotate, lookat_rotate2 -- note the in-place mutation of the
passed matrix and that rotations are in degrees
- compress (general/): compress, uncompress, compress_file,
uncompress_file -- note the file variants delete the source on success
- interactive/: send_zmp, act_mxp, request_term_type,
start_request_term_type, request_term_size
- internals/: dump_trace, destructed_objects, check_memory (flag
bitmask + DEBUGMALLOC build requirement), dump_stralloc, dump_jemalloc
- core: next_bit, explode_reversible, shallow_inherit_list
Each page keeps the existing manpage-style layout (4-space-indented
NAME/SYNOPSIS/DESCRIPTION, name(3) SEE ALSO). Example blocks are indented
to match, so all files are markdownlint-clean.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* 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>
resolve(), async_read(), async_write(), async_getdir() and
async_db_exec() ran their callbacks with no user context, so
this_player() returned 0 and input_to()/printf() were unusable there.
Follow the call_out() precedent: capture command_giver (ref-held) when
the request is registered and restore it around the callback, skipping
destructed objects, gated on the same 'this_player in call_out'
setting. The pending-request holders account for the new ref in the
DEBUGMALLOC walkers.
The new test registers callbacks from two different living objects and
asserts each callback sees its own registrant, which fails without the
per-request capture.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lv2Gw2AWqtyN3nNEgob1He
Mirrors set_reset(): set_clean_up(ob, seconds) records an explicit
one-shot deadline that overrides the idle-time rule in the periodic
sweep; once it fires the object reverts to the idle rule. With the
seconds argument omitted, any pending deadline is cancelled. Both forms
re-flag the object for clean_up consideration (same gate as
request_clean_up(): the object must define a clean_up() apply).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Lv2Gw2AWqtyN3nNEgob1He
The wasm binary was dominated by the stock 30MB ICU data archive; the
driver only reads break-iterator data from it. Also drops zlib and the
last TLS reference from the target, and turns off MCCP/compress there.
- build-deps.sh trims the ICU archive with icupkg to brkitr rules + the
converter alias table (~780KB). ICU_DATA_FILTER_FILE cannot do this:
it only applies when building ICU data from source, and the -src
tarball ships a prebuilt .dat. Table charsets (GBK, Big5, ...) are
gone on this target -- string_encode() etc. raise an LPC error; a new
__WASM__ LPC predefine lets mudlibs and tests adapt, and ICU_KEEP
re-adds charsets for mudlibs that need them.
- zlib is not linked on wasm at all: a global HAVE_ZLIB (defined on
every other platform) now gates the core's gzip'd file support --
compressed save_object degrades to a plain save, write_file flag 2
raises an error, and read_file/restore_object use stdio instead of
transparent gzopen. That also surfaced a latent bug: core used gz*
but only got zlib transitively via the compress package/libtelnet,
so native now links ZLIB::ZLIB explicitly.
- TLS is fully gone from the target: the one shared caller of the TLS
interface (the sys_reload_tls efun) is excluded from the wasm efun
table in core.spec (the fullspec is preprocessed with the TARGET
compiler, so #ifndef __EMSCRIPTEN__ works there), which lets the
net/tls_stub.cc shim be deleted outright. Websocket code was already
native-only via the Transport split.
- compress package + MCCP are off on wasm (compressing a byte stream to
a client on the same page wastes CPU and size).
- INITIAL_MEMORY 128MB -> 64MB now that the data segment is small.
- Deps prefix is ICU-only; CI/release cache keys bumped to -v3 with the
zlib pin removed. Docs (build-wasm.md guide, driver/wasm.md cookbook,
src/wasm/README.md, README, AGENTS, sys_reload_tls efun page)
updated.
Result: fluffos.wasm 33.5MB -> 3.5MB raw, ~0.8MB brotli / ~1.0MB gzip;
the full LPC testsuite passes inside the wasm driver.
Claude-Session: https://claude.ai/code/session_01VVpphH3cgXyziRDCbjUVkb
Co-authored-by: Claude <noreply@anthropic.com>
A '//' comment after a #define body was captured INTO the stored macro
body. Expansion buffers carry no newline to end it, so when the macro
expanded inside a spliced line (a function-like macro's substituted
body, as in the report's MIN(credits, m[e][CREDITS])), the '//' ate the
rest of the splice and the parse failed with a baffling 'unexpected ;'
attributed to the outer macro. The same missed strip made
'#undef X // why' erase nothing and '#ifdef X // why' look up the
wrong name and silently take the false branch.
Comments are whitespace (C translation phase 3). dispatch_directive now
strips them from the payload before parsing for #define (name, params,
body -- body also right-trimmed so a stripped comment can't turn '1'
vs '1 ' into a spurious redefinition warning), #undef, #ifdef, #ifndef,
and #pragma (word-list payload); #if/#elif already stripped.
strip_directive_comments() now folds a block comment to ONE space
instead of nothing, so '1 -/*c*/-1' keeps its token boundaries instead
of pasting '--'. #error/#warn/#echo payloads stay raw.
Covered by five new Preprocessor unit tests (the report's repro shape,
paste-prevention via #if branch selection, param-list comment,
testsuite/single/tests/compiler/preprocessor.lpc; documented in
docs/lpc/preprocessor/define.md.
Fixes#1240
Claude-Session: https://claude.ai/code/session_016FMBJLkpkpVpZdz6PWzeWe
Co-authored-by: Claude <noreply@anthropic.com>
* Add recompile_object() efun: in-place program update, state preserved
Recompiles a master copy's program from its source file and swaps the
fresh program into the LIVE master copy and every clone sharing it -
the "hot update" alternative to destruct+load_object: nothing is
destructed, so object identity (pointers held elsewhere, name,
inventory, shadows, interactive state, call_outs, heart_beat) is
untouched, and each object's global variables carry over BY NAME
inside the driver (private ones included): the new program's __INIT
runs first, then every surviving name gets its old value back. The
recompile behaves like a normal load - unloaded parents resolve
through the retry dance and the compile-time master applies are
consulted. Returns the number of objects updated.
Made possible by moving an object's variable block OUT of the object_t
allocation into its own (TAG_OBJ_VARS, always >= 1 svalue, wired into
the debug-malloc walkers): every access already went through
ob->variables[i], so a program with a different variable count can now
be swapped onto a live object.
Safety: refused while any object sharing the program is executing
anywhere on the call stack (live frames hold bytecode positions and
variable indices of the old layout), for clones (pass the master
copy), the simul_efun object, pending replace_program(), and nested
calls. Function pointers whose behavior depends on the owner's program
layout (FP_LOCAL, FP_FUNCTIONAL) go stale instead of corrupting:
objects carry a prog_generation stamp, funptrs snapshot it at
creation/bind, and call_function_pointer() errors cleanly on mismatch.
Fixing a latent asymmetry this exposed: make_lfun_funp incremented
func_ref on the creation-time program but dealloc_funp decremented the
owner's CURRENT program. FP_LOCAL pointers now store their program and
account against it symmetrically (checkmemory and %O formatting
updated to match) - caught by the debug-build memory checker in the
testsuite.
The hot-reload daemon's default (state-keeping) path now reloads
through recompile_object() - changed ancestors first, then the watched
program - so clones ride along automatically; a cooperative
hot_reload_state()/hot_reload_restore() pair takes the destruct+load
path with exactly the state it chooses, and watch(prog, 0) opts out
entirely. The daemon test demonstrates finding all live instances with
children()/clonep() and both clone behaviors (updated in place vs.
stragglers on the old program); single/tests/efuns/recompile_object.lpc
pins the efun semantics (master+clones count, per-object state incl.
private, initializers for new variables, removed variables, stale
funptrs, executing/clone/missing-source guards, call_out survival).
Docs: efun reference page, hot-reload guide step 5 rewritten around
the efun with the value-transfer technique kept as the manual
alternative, caveats updated (clone behavior per path, stale funptrs).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018DGhzJfPhDGJA94EPh1gEK
* recompile_object: support master/simul_efun targets; review fixes
The master object and the simul_efun object can now be recompiled
live. Both subsystems dispatch through cached name->runtime-index
tables (master_applies / simuls) whose entries point into the old
program's function table, so recompile_object() rebuilds them against
the new program immediately after the swap and BEFORE the new
program's __INIT runs (an error inside it would already route through
those tables). Simul_efun indices are preserved by NAME across the
rebuild - that table is deliberately unsorted for exactly this reason
- so simul calls compiled into every other program keep working, and
a simul removed by the new source fails with the usual "no longer a
simul_efun" runtime error. set_master()/set_simul_efun() only
ref/assign when the object actually changes, keeping the classic
destruct-driven replacement path intact. %O of a function pointer to
a since-removed simul now prints a placeholder instead of derefing
the null table entry.
Testsuite: the efun test recompiles the live simul_efun object
mid-run (the very next ASSERT dispatches through the rebuilt table),
pins the currently-executing guard on the master (master::flag() sits
on the call stack for the whole run), and re-runs the master recompile
from a post-run call_out where the master is idle - state carry-over
and apply dispatch are enforced by exiting nonzero.
Also from this self-review round (multi-agent):
* f_recompile_object crashed when the target destructed itself from
its new program's __INIT: destruct sweeps the VM stack, so the efun
glue's stack slot held a plain 0 by the time it tried to
free_object() it. Reproduced by a review agent's probe; the glue
now uses free_svalue(), and the scenario is pinned in the efun test
(destructed targets drop out of the updated count).
* hot_reload daemon: ancestors() now returns the inherit closure
DEEPEST-first - recompiling a middle parent bakes in whatever
grandparent program is live at that moment, so a >=3-level chain
with two changed ancestors permanently embedded the stale
grandparent (reproduced by a review agent; pinned by a new
kid/mid/grand scenario).
* hot_reload daemon: dep records were map_delete'd before the
recompile and rebuilt by the applies during it - but a throw BEFORE
compiling (currently-executing guard, unreadable file) left the
object loaded with no records, blinding closure_changed() to
include-file edits forever. Records are now restored when the
recompile throws (pinned by a new watched-object-drives-the-pass
scenario).
* docs: inheritance wording ("copies code" -> the child links against
the exact parent program it was compiled with), the
currently-executing guard also covers inheritors running inherited
code, and the cooperative-pair opt-out triggers on
hot_reload_state() alone.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018DGhzJfPhDGJA94EPh1gEK
* recompile_object: void mid-update replace_program; cover virtuals
Two additions from the C++ review round:
* A replace_program() registered DURING the update slipped past the
pre-flight check: an earlier target's __INIT can call into a
not-yet-swapped clone, whose OLD code registers a pending entry -
computed against the very program the update is replacing. The
backend sweep then ran that entry's variable-offset shuffle against
the fresh program's differently-sized variable block (negative
num_fewer, heap corruption; reproduced under ASan by a review
agent's probe). recompile_object() now voids any pending entry for
each target at its swap point - an entry registered AFTER the swap
is computed against the new program and survives. Pinned in the
efun test; the rest of the suite run doubles as the sweep detector.
* Virtual objects (materialized through master::compile_object) are
covered and pinned: the virtual object carries the BACKING file's
program, so the recompile targets that source and swaps it in with
the virtual name, identity, flag and state untouched. The testsuite
master gains a /data/hu/virt* fixture mapping; docs note the
behavior and that the hot-reload daemon keys its records by
compiled program name (watch virtuals via their backing file).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018DGhzJfPhDGJA94EPh1gEK
* docs: capture hot-reload/recompile_object knowledge in README and AGENTS
README: the hot-reload language bullet now describes what actually
ships (recompile_object with state carried by name, clones included),
and Features gains a Hot Reload section linking the guide.
AGENTS.md, for future agents working on this machinery: the object
variable block is a separate allocation (TAG_OBJ_VARS) and what that
enables; the new-DMALLOC-tag checklist (checkmemory walkers); the
destruct-sweeps-the-VM-stack rule for efun glue; testsuite harness
facts (fixtures outside tests/, unconditional teardown, master::flag
on the stack all run + the post-run call_out pattern, full -ftest
paths, suite side-effect files); the compile-time master applies; and
the recompile_object invariants (executing-frame guard, dispatch-table
rebuild before __INIT, voiding mid-update replace_program entries,
funptr generation staleness, FP_LOCAL func_ref symmetry).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018DGhzJfPhDGJA94EPh1gEK
* recompile_object: pin shadow/catch_tell/add_action/heart_beat survival
New test recompile_object2.lpc verifies the object-attached runtime
state that dispatches by name keeps working across the swap:
catch_tell routes into the new program while accumulated state stays;
a shadow chain survives updating the SHADOWED object (still
intercepted, new code underneath) and updating the SHADOW itself while
attached; add_action sentences registered by the old code still fire
their verb into the new program; the heart_beat registration persists.
Also two doc wording fixes from the docs review: the executing-guard
bullet now covers both halves of the guard (frames executing the
program's code AND frames belonging to an object of the program
running inherited code), and the guide's mode summary matches the
daemon (hot_reload_state alone selects the cooperative path).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018DGhzJfPhDGJA94EPh1gEK
* recompile_object: fix simul_efun/__INIT edge cases; cover callback surface
Four defects from the C++ review round, each probe-verified under ASan:
* Recompiling the simul_efun object to a program that defines no simuls
FREEd the live dispatch table (simul_names/simuls) while other
compiled programs still carry F_SIMUL_EFUN opcodes and FP_SIMUL
funptrs with baked indices -> use-after-free on the next simul call.
Keep the tombstoned arrays instead (remove_simuls() already nulls
every func, which yields the clean "no longer a simul_efun" error and
preserves the name->index mapping for re-adds).
* The debug memory checker did not mark IHE_ORPHAN idents as permanent,
so any run that removed a simul via an update tripped a spurious
"orphan permanent identifier" leak and failed the testsuite gate.
Add IHE_ORPHAN to the mark mask (it is part of IHE_PERMANENT).
* The disassembler dereferenced simuls[].func unguarded in two places;
after a simul removal, dump_prog() on a program referencing it would
null-deref. Guard both, matching the sprintf %O fix.
* An error() thrown from a target's __INIT during the swap leaked this
loop's held references (the per-target snapshot ref, new_prog's
compile ref, the old variable block) and left the update half-applied.
Wrap call___INIT per target in save_context/try/restore: on error the
object is left committed to the new program with fresh initializers
(carried-over state dropped, like a create() that throws during load),
sibling targets still update, and nothing leaks.
Test coverage:
* recompile_object.lpc: an __INIT that errors -- blueprint and clone
both recompile, neither is immortalized, the object stays usable on
the new program, no ref/variable leak (the per-file memory checker is
the detector). (The simul zero-function / removal paths can't be
exercised against the shared /single/simul_efun mid-suite; verified
out-of-band with a throwaway ASan probe that reduces then restores the
file.)
* recompile_object2.lpc: call_outs armed before the swap fire after it --
a name-based call_out dispatches into the new program, a funptr
call_out is stale and is refused cleanly (its target never runs, no
crash), verified from a post-run call_out. Rounds out the by-name
callback survivors already covered (catch_tell, add_action, heart_beat,
shadows).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018DGhzJfPhDGJA94EPh1gEK
---------
Co-authored-by: Claude <noreply@anthropic.com>
* tests: clear the active scanner before yylex_destroy in the harnesses
Both tokenizer harnesses destroyed their scanner without
lpc_lex_scanner_destroyed(), leaving the global active_scanner dangling;
the next compile's first current_line read then dereferenced the
destroyed scanner's guts (lpc_lex_current_line_ref ->
innermost_real_buffer_index). Order-dependent and layout-dependent: any
Preprocessor test followed by CompileEntry.FatalInsideIfExpressionRecovers
segfaulted deterministically in a minimal pair and intermittently in full
runs. Pre-existing (reproduces on master); surfaced while adding the
#1236 tests.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016FMBJLkpkpVpZdz6PWzeWe
* lexer: a directive-line block comment may span physical lines (#1236)
The single anchored directive rule captures one physical line (plus
backslash continuations), so a /* comment opened after a #define body
and closed on a later line ended the capture at the newline:
strip_directive_comments() silently swallowed the open comment, the
define itself parsed, and the comment's remaining lines were tokenized
as code -- a regression against the old lexer for a pattern real
mudlibs use.
New lpc_lex_complete_directive() runs before the terminating-newline
consumption: it scans the captured text (quote-aware, same rules as
strip_directive_comments) and, when the line ends inside an open block
comment, pulls raw bytes through lpc_lex_getc() until the comment
closes and the logical line really ends. Comments fold to a single
space, so text after the close still belongs to the directive (C
semantics), and the tail may open further comments, strings, '//', or
backslash continuations. Newlines pulled this way get the same
bookkeeping as the rule's own terminator, and the count is backed out
of lpc_lex_on_directive()'s first-line attribution so diagnostics still
point at the directive. EOF inside the comment reports the same error
as SC_BLOCK_COMMENT's <<EOF>> rule instead of spinning.
Covered by new Preprocessor unit tests (repro shape, comment tail,
__LINE__ bookkeeping, live/dead #if, string-literal '/*', EOF) and
testsuite/single/tests/compiler/preprocessor.lpc pins; documented in
docs/lpc/preprocessor/define.md.
Fixes#1236
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016FMBJLkpkpVpZdz6PWzeWe
---------
Co-authored-by: Claude <noreply@anthropic.com>
LPC can now read and set OS environment variables -- the ask from the
dockerization discussion -- gated by two new colon-separated runtime
config allow-lists: 'allowed os environment variables' (readable) and
'writable os environment variables' (writable, implicitly readable).
Both default to empty, so nothing is accessible until the host
administrator opts specific names in. set_os_env(name) with no value
unsets. Windows uses _putenv_s.
Includes efun docs, index registration, regenerated config docs, and a
testsuite case exercising allow/deny/read/write/unset paths (the test
config allow-lists PATH read-only and FLUFFOS_TEST_RW read-write).
Fixes#1045
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016FMBJLkpkpVpZdz6PWzeWe
The driver cross-compiles to WebAssembly and runs a complete mudlib
inside a webpage: compiler, VM, all portable efun packages, and the
real telnet protocol layer -- the page is the telnet client, JavaScript
is the wire. The LPC testsuite passes inside the wasm driver (browser
and node).
Architecture (src/wasm/README.md):
- Transport interface (src/net/transport.h): each interactive_t owns an
abstract byte pipe (write/flush/schedule_command/close). comm.cc and
telnet.cc are transport-agnostic and compile unchanged on every
target. Implementations select at link time: SocketTransport +
WebsocketTransport (net/transport_libevent.cc, native) vs
WasmConsoleTransport (src/wasm/comm_wasm.cc).
- Inverted event loop: the shared gametick/event core stays in
backend.cc; backend_libevent.cc (blocking loop) vs
src/wasm/backend_wasm.cc (page-driven fluffos_tick(now_ms), walltime
priority queue, capped catch-up). Other per-target singletons (TLS,
DNS resolver, crash handler) follow the same link-time pattern -- no
#ifdef __EMSCRIPTEN__ in shared logic files.
- Mudlib rides in Emscripten's MEMFS via file_packager; driver file I/O
needed zero changes.
jsbridge package (WASM only): js_eval() (sync), js_call() (async page
handlers with LPC callbacks), js_export() (page calls LPC via
Module.fluffos.callLPC, Promise-resolved on a later tick) -- fetch,
canvas/WebGL, storage, page UIs driving the game. Demo in
testsuite/command/jsdemo.lpc + the bundled web terminal.
Build/tooling: native-tools + wasm CMake presets (host codegen tools,
then cross build); tools/wasm/build-deps.sh (ICU + zlib cross-builds,
including the ICU genccode data quirk); tools/wasm/pack-mudlib.sh
(any mudlib + driver -> static web bundle, also works standalone from
the release zip); src/www/wasm/index.html (self-contained web terminal
with a minimal telnet client). On emsdk >= 3.1.57 the build uses native
wasm exceptions (-fwasm-exceptions); older toolchains fall back to
-sDISABLE_EXCEPTION_CATCHING=0.
CI/release: a wasm CI job (latest emsdk, deps cache keyed on resolved
emcc version) gates PRs on the LPC testsuite running inside the wasm
driver under node; release.yml ships fluffos-<version>-wasm.zip
(driver + web terminal + pack-mudlib.sh). Fixed a stale-predefine bug:
options.autogen.h now depends on packages.autogen.h + config.h.
Docs: docs/build-wasm.md (end-to-end workflow), docs/driver/wasm.md
(packer + jsbridge cookbook), docs/efun/jsbridge/*, README + AGENTS
updated. Testsuite files for optional packages guard themselves with
#ifdef __PACKAGE_*__.
Claude-Session: https://claude.ai/code/session_01VVpphH3cgXyziRDCbjUVkb
Co-authored-by: Claude <noreply@anthropic.com>
package_ffi requires pkg-config and libffi (find_package(PkgConfig
REQUIRED) + pkg_check_modules(FFI REQUIRED libffi) in
src/packages/ffi/CMakeLists.txt), but the docs, Dockerfile, and CI
package lists never listed them — CI only passed because the runners
preinstall pkg-config.
Add the platform-appropriate packages across every dependency list:
- apt: pkg-config libffi-dev
- brew: libffi (pkg-config already present)
- apk: pkgconf libffi-dev
- pacman: mingw-w64-x86_64-pkgconf mingw-w64-x86_64-libffi
Also note in the build docs that flex is only needed when editing the
LPC lexer; otherwise the pre-committed generated lexer is used.
* Add inherit_program / include_file master applies; auto hot-reload demo
New compile-time master applies, consulted for every inherit statement
and #include directive:
* mixed inherit_program(string from, string path, int priv)
Called while compiling `from` for `inherit "path";` (priv nonzero for
private inherits). A string return is an alternate path for the
inherited file; an array-of-strings return is the inherited program's
source itself (compiled via load_object_from_source under the inherit
statement's name, through the existing load_object retry loop); any
other return prevents the inheritance.
* mixed include_file(string compiled, string from, string path)
Called when `from` is about to include `path` while compiling
`compiled`. A string return is the translated path (resolved absolute
from the mudlib root or relative to the includer; returning `path`
unchanged keeps the "..."-vs-<...> search semantics); an
array-of-strings return is the included text itself (pushed as an
in-memory include buffer with the usual file-identity bookkeeping);
any other return prevents the inclusion.
Both follow the valid_override/get_include_path precedent for calling
master LPC mid-compile (skipped without a VM context or master object),
and a missing apply keeps stock behavior.
The applies expose the full compile-time dependency graph, which the
testsuite uses to demonstrate mudlib auto hot-reload on file changes:
/single/hot_reload.lpc registers as the master's compile hooks, records
which source files each program's bytecode was built from (own source,
includes, inherited programs, transitively), and its call_out poller
destructs+reloads watched blueprints whose dependency closure changed
on disk - including reloading a stale parent when only the parent's
include changed.
Testsuite: single/tests/compiler/{inherit_program,include_file}.lpc pin
the apply semantics (redirect, inline source, deny, priv flag, argument
shapes on nested includes) via the scriptable /clone/compile_hook;
single/tests/applies/hot_reload.lpc demonstrates end-to-end hot reload
over a runtime-written inherit+include fixture chain. Docs added for
both applies.
Validated: full LPC suite (532 files) x2 on RelWithDebInfo, x2 on
Debug+ASan/UBSan, plus the 297 GTest unit tests.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018DGhzJfPhDGJA94EPh1gEK
* docs: add hot reload guide for the new compile-time master applies
New concepts page (concepts/general/hot_reload.md) explaining why
"file changed -> reload" needs the compile-time dependency graph, how
the inherit_program / include_file master applies expose it, and a
step-by-step mudlib implementation with examples: master delegation,
dependency recording, closure computation, change detection with
size+mtime snapshots, parent-first reload ordering, and the call_out
poller. Documents blueprint-reload semantics and caveats (clones keep
the old program, no compiles inside the applies, records only complete
for compiles observed by the daemon), pointing at the testsuite
reference implementation. Cross-linked from both apply reference pages
and the concepts indices.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018DGhzJfPhDGJA94EPh1gEK
* docs/testsuite: say "master copy", not "blueprint"
Align the hot-reload guide, apply reference, daemon, and test comments
with the project's terminology for the object loaded from a file (see
clonep(3): "the master copy").
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018DGhzJfPhDGJA94EPh1gEK
* testsuite: edge cases for the compile-time applies; docs review fixes
compile_hooks_edge.lpc pins that unusual inherit_program/include_file
return values produce clean LPC errors or the documented behavior,
never a driver crash: empty array, non-string elements, redirect to
self, empty-string redirect, inline source vs already-loaded object,
multiline inline content, the apply itself throwing mid-compile
(safe_apply falls back to default resolution), extension-spelled
redirects, and denying the auto-included global include file.
Fixtures in /clone/adv_*; /clone/adv_hook wraps the scriptable hook
with a throwing include_file.
Docs fixes from review: the apply-page examples now look the daemon up
with find_object() instead of a path call_other (which would load the
target and trigger a compile mid-compile -- the exact pattern the same
pages forbid), and the hot-reload guide's ancestors() snippet carries
the seen-mapping argument to match the reference daemon.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018DGhzJfPhDGJA94EPh1gEK
* hot_reload: fix multi-watch and failed-reload handling; harden tests
Three defects from the LPC review round, each now pinned by the
demonstration test:
* check_now() collected and reloaded in one pass, so the first reload's
snapshot refresh erased the change evidence for every other watched
program sharing the dependency (a common header, or a watched parent
iterating before its watched child - which then stayed bound to the
destructed old parent forever). The stale set is now collected before
any reload runs.
* A reload whose recompile throws (a syntax error mid-edit - the most
common event in a hot-reload workflow) unwound poll() before the
re-arm, killing the poller forever and leaving the watched master
copy destructed. poll() re-arms first, check_now() catches per
program, reload_count only counts successes, and closure_changed()
treats a watched-but-not-loaded program as stale so the retry
self-heals once the file compiles again.
* The three apply tests registered master compile hooks (and the
hot-reload test armed the poller and wrote /data/hot) with cleanup on
the success path only; a thrown check would leave the hook routing
every remaining compile of the randomized run. Each test now runs its
checks under catch and unhooks/tears down unconditionally, re-raising
the error afterward.
The demo test now also covers the shared-dependency pass (watch parent
and child, change the common include, both reload in one pass) and the
broken-edit recovery cycle. The hot-reload guide's snippets are updated
to match the daemon.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018DGhzJfPhDGJA94EPh1gEK
* simulate: let inline inherit source resolve its own unloaded inherits
From the C++ review round: master::inherit_program returning inline
source whose text itself inherits a not-yet-loaded program failed the
whole load with "#inherit is not supported when compiling from
in-memory source" -- reachable in the feature's primary use case, since
synthesized programs routinely inherit ordinary on-disk library files.
load_object_from_source() now runs the same iterative dance as
load_object(): when the compile aborts on an unloaded parent, load that
parent (from disk, or from further master-supplied inline source, so
synthesized-inheriting-synthesized chains work), then recompile the
same source string -- which is in hand, unlike the historical
no-filename rationale for rejecting #inherit here. Mirrors
load_object()'s guards: illegal-to-inherit-self, the duplicate-name
check after the parent's arbitrary LPC ran, and an inherit-chain bound
on the retry loop as a backstop against a master that redirects to a
fresh unloaded name on every recompile.
The inherit_program test now covers both new shapes (inline inheriting
unloaded on-disk, and two levels of inline source); the apply doc drops
the already-loaded-only caveat.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018DGhzJfPhDGJA94EPh1gEK
---------
Co-authored-by: Claude <noreply@anthropic.com>
From an agent-based self-review of the branch:
- remove proto_sib1/proto_sib2.lpc, dead leftovers from an earlier
repro iteration of the inherit_prototype test
- lpcshell: scope the nonzero-failure exit code and the evaluate-
pending-at-EOF behavior to non-interactive runs, matching the
documented intent (an interactive typo no longer turns Ctrl-D into
exit 1)
- CI: build the optional dwlib package on the Ubuntu GCC legs so it
cannot silently bit-rot again
- docs: alphabetize request_clean_up in the efun indexes and mark its
argument optional in the synopsis; note in the explode gtest that
the empty result is the static null array
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016FMBJLkpkpVpZdz6PWzeWe
src/packages/dwlib had no CMakeLists.txt, so it silently never built
(for roughly a decade). Add the standard package wiring behind a new
PACKAGE_DWLIB option (default OFF, matching its status as a
Discworld-specific optional package) and fix the one API bit-rot spot
(find_in_mapping now takes the key by value).
Enabling it exposed a build-system gap: packages.fullspec (the make_func
input) did not depend on the generated enabled-package list, so toggling
any package option left a stale efun table -- predefines said the
package existed while its efuns didn't. packages.fullspec now depends on
packages.autogen.h. Also corrects the replace_dollars() test to the
efun's real marker/replacement-pairs API.
Verified: full LPC testsuite passes both with -DPACKAGE_DWLIB=ON (dwlib
efun tests active) and with the default OFF configuration.
Also corrects the clean_up() apply documentation (EN + zh-CN): the
argument is the program's reference count (0 for clones), which the
apply cache can inflate -- not a strict inherited flag (issue #179).
Fixes#467Fixes#179
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016FMBJLkpkpVpZdz6PWzeWe
member_array(fp, arr, start, 4) now calls fp on each element and
returns the first index where it yields truthy, composing with the
existing prefix (1) and reverse (2) flag bits; without flag 4 a
function argument still matches by pointer identity as before.
Also fixes an adjacent bug: a reverse search (flag 2) that found
nothing returned sizeof(arr) instead of -1, because the found-index
mirroring was applied to the failure sentinel too.
Fixes#900
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016FMBJLkpkpVpZdz6PWzeWe
Once clean_up() returns 0 the driver clears O_WILL_CLEAN_UP and never
asks that object again, with no way for LPC to opt back in. The new
efun re-arms the flag (for this_object() or a given object), returning
1 on success and 0 when the object defines no clean_up() apply --
mirroring the condition applied at load/clone time.
Fixes#917
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016FMBJLkpkpVpZdz6PWzeWe
The boot-time preload loop unconditionally printed every file name,
letting errors scroll away between hundreds of progress lines. The new
option (default on, preserving current behavior) silences the per-file
listing when set to 0, leaving errors clearly visible.
Fixes#967
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016FMBJLkpkpVpZdz6PWzeWe
Add a 'UTF-8 Native Strings' section to lpc/types/strings.md covering
what the driver actually implements: lengths and positions are measured
in extended grapheme clusters (UAX #29), indexing yields code points and
errors on multi-code-point clusters, ranges/explode/strsrch operate on
character boundaries, display width (strwidth, UAX #11) vs length,
\uXXXX and surrogate-pair escapes, UTF-8 validity requirements, and the
encoding boundary (set_encoding for connections, string_encode /
string_decode / buffer_transcode elsewhere). Note in the old
sub-ranging section that positions are characters, not bytes.
Clarify sizeof() (string = grapheme clusters, buffer = bytes) and
strsrch() (character offsets, character-boundary matches).
Every documented example is pinned by a new testsuite file,
testsuite/single/tests/compiler/utf8_doc_examples.lpc, verified against
a freshly built driver (19 checks). Notably replace_string() is
byte-oriented, so it is deliberately NOT listed among the
grapheme-aware operations.
Claude-Session: https://claude.ai/code/session_01TSzcESzU9947zkGzQ6SMmE
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>
Applies the English efun review (commit 1e7f9bf5) to the zh-CN tree:
- Translated the 28 newly-documented efuns into Chinese: the 18
package_ffi efuns and the 10 package_dwlib efuns (add_a, vowel,
replace, replace_dollars/html/mxp/objects, roulette_wheel,
query_multiple_short, reference_allowed).
- Return-type fixes where the zh-CN doc still carried the old signature:
dump_file_descriptors/malloc_status -> string; disable_commands/
receive/set_heart_beat -> void; get_char/input_to/link -> int. Also
corrected the stale Chinese return-value prose in disable_commands and
receive. (cache_stats/mud_status/set_eval_limit were already correct in
the zh-CN translation.)
- Expanded implode (function-fold form) and save_object (save-to-string
form).
- Removed the stale opcprof doc and its index / see-also references.
- Regenerated docs/zh-CN/efun/index.md and the efun section of
docs/zh-CN/index.md.
Docusaurus build passes (onBrokenLinks:throw). New translations omit the
per-file translator-credit line rather than falsely attribute them.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Reviewed every efun doc against the .spec source of truth (the make_func
declarations) and the implementations.
New docs for 28 previously-undocumented efuns:
- package_ffi (18): new docs/efun/ffi/ category — ffi_load/unload/symbol/
prepare/call, alloc/free/sizeof/peek/address/read/write, struct_layout,
callback/callback_addr/callback_free, error/status.
- package_dwlib (10, under contrib/): add_a, vowel, replace,
replace_dollars/html/mxp/objects, roulette_wheel, query_multiple_short,
reference_allowed.
Return-type fixes where the doc contradicted the spec/impl (mostly stale
MudOS behavior): cache_stats/debugmalloc/dump_file_descriptors/
malloc_status/mud_status return string; disable_commands/flush_messages/
receive/set_heart_beat are void; get_char/input_to/link/set_eval_limit
return int; call_stack -> mixed *, function_profile -> mapping *. Also
corrected receive's and disable_commands' stale "returns ..." prose.
Expanded implode (function-fold form) and save_object (save-to-string
form), both of which the docs had omitted.
Removed 4 stale docs for efuns that no longer exist (no spec entry, no
f_ implementation, zero references anywhere): errorp, opcprof, swap,
dump_socket_status.
Regenerated the affected efun index pages. The Docusaurus build passes
with onBrokenLinks:throw, confirming no dangling links.
Note: the docs/zh-CN translated tree still mirrors the old English docs
(same stale entries, and it lacks the new efuns); left for a separate
translation pass.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Doc-only review pass checking every branch-authored doc against the
shipped code. Fixes where docs described intent rather than the result:
- docs/driver/ffi-plan.md (began life as a plan, drifted from the
shipped package): ffi_status() returns a mapping, not mixed*;
callbacks are implemented and in-scope (ffi_callback/_addr/_free added
to the efun surface and moved out of "v2 deferred"); the DEBUGMALLOC
section now describes the actual std::unordered_map + TAG_BUFFER scheme
(no TAG_FFI / mark hook exists); valid_ffi gates load/symbol/prepare/
callback; testing is the 20-file LPC suite + tools/ffi/test.py (there
is no GTest fixture).
- docs/lpc/preprocessor/index.md: document the #warn directive.
- docs/lpc/diagnostics.md + preprocessor/pragma.md: show_error_context is
a legacy flag that no longer changes clang-style compiler diagnostics
(render_diagnostic ignores PRAGMA_ERROR_CONTEXT; only the runtime
smart_log path still reads it).
- tools/lpc-syntax/README.md: test.mjs is 49 assertions, not 47.
Verified accurate, no change needed: AGENTS.md, testsuite/README.md,
compiler/internal/README.md, and the source-files / float / strings /
text_blocks / define / conditionals / inherit / include docs, sprintf %g,
and the tools/ffi + vscode READMEs.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Fully implements the docs/driver/ffi-plan.md design. LPC can now load
native shared libraries, call C functions whose signatures are described
at runtime, manage native memory, pass in/out parameters, and expose LPC
function pointers to C as callbacks.
Package (src/packages/ffi, option PACKAGE_FFI ON, libffi via pkg-config):
- ffi_load/unload/symbol; ffi_prepare/ffi_call (ffi_prep_cif + ffi_call);
ffi_alloc/free/sizeof/peek/address; ffi_read/write; ffi_struct_layout;
ffi_callback/ffi_callback_addr/ffi_callback_free (libffi closures that
re-enter the VM via safe_call_function_pointer); ffi_error/ffi_status.
- Buffers are the currency for all pointer/byte data; raw pointer VALUES
(returned pointers, buffer/callback addresses) are ints. LPC strings
are UTF-8-native and never implicitly marshalled -- a char* is a
buffer the caller encoded (pinned by ffi_string.lpc).
- Native allocations are LPC buffers (GC-tracked); handle tables freed at
shutdown (ffi_cleanup) and marked for DEBUGMALLOC (mark_ffi).
Security: master apply valid_ffi(op, arg, caller) gates every
load/symbol/prepare/callback (VALID_FFI added to the applies table); a
missing apply denies by default. Optional "ffi allowed libraries" config
allow-list (rc.cc + runtime_config.h + regenerated config.md, new
Security category). __PACKAGE_FFI__ predefine added.
tools/ffi/generate.py: turns a C header into LPC bindings (buffer params
for char*, optional --string-convenience UTF-8 overloads) plus a struct
layout include; reports+skips unsupported forms; --emit-json contract.
Dependency-free test.py.
Tests: 20 testsuite/single/tests/efuns/ffi_*.lpc (every efun, the qsort
callback round trip, the generated-bindings end-to-end path), guarded by
__PACKAGE_FFI__ with a libc-reachability probe. The efuns are VM-stack-
based, so the LPC testsuite is the surface -- libffi's call/closure paths
run there under ASan/UBSan and the per-file check_memory leak gate.
The clang RelWithDebInfo sanitizer caught an error()-unwind leak: both
ffi_prepare and ffi_callback allocated before a code_to_type() that can
error() -- now unique_ptr/custom-deleter owned (AGENTS.md section 4).
Verified: testsuite x3 (ASan Debug) + ctest 297, RelWithDebInfo suite x3
+ ctest 298, clang RelWithDebInfo sanitizer (leak-clean), tools/ffi
test.py.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
LPC strings are UTF-8-native, so the FFI boundary must never auto-convert
a string to a C char* (it would impose UTF-8 on APIs expecting other
encodings and cannot carry arbitrary bytes / embedded NULs). Every
pointer and byte payload crosses as a buffer; the LPC caller does the
encoding explicitly with string_encode/string_decode, exactly like the
rest of the driver. Dropped the FFI_STRING type code (a char* is just an
FFI_POINTER buffer); ffi_call args are int|float|buffer only; added
ffi_peek to copy a returned foreign char* into an owned buffer; the
tools/ffi generator emits buffer params for char* (with an opt-in,
clearly-named string-convenience overload). Driver-mediated identifiers
(library path, symbol name) stay string, consistent with the file efuns.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Proposal for an OFF-by-default ffi package: dlopen/dlsym + libffi to
load native libs and call functions with runtime-described signatures,
native memory managed as ref-counted LPC buffers (no new svalue tag),
a mandatory valid_ffi master-apply security gate, and a tools/ffi
header->LPC bindings generator. Phased v1a/v1b/v2 with GTest + LPC +
generator tests.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Neither master's hand-written scanner nor the flex lexer ever accepted
exponents ("2.5e2" lexed as REAL(2.5) IDENT(e2)) -- but the hand-written
EBNF already documented the form and it should exist. Two lexer rules
add it: an optional exponent on the fraction form, and a bare-exponent
form ("1e3"); "1e" without exponent digits stays NUMBER(1) IDENT(e),
"1..5" stays a range, hex "0x1E3" is untouched, and '_' separators work
in all parts. strtod() already converted exponents, so only the
patterns changed.
Pinned at every layer: syntax_literals.lpc (2.5e2, 2.5e-2, 1.5E+2,
1e3, 1_2e4), the JS tokenizer + generated tmLanguage (with node tests
for the exponent forms and the "1e" non-exponent), the lexical EBNF
(realLiteral | exponent rules, replacing a half-aspirational entry),
and docs/lpc/types/float.md (which also wrongly claimed single
precision -- LPC_FLOAT is a double).
Verified: testsuite x3 + ctest 297 (ASan Debug), RelWithDebInfo full
ctest, lpc-syntax node tests (50).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
New pages: lpc/source-files (extension rules, extension-blind object
identity, registry-before-filesystem, portable-code guidance),
lpc/diagnostics (clang-style output, macro expansion notes, include
chains, fix-its, show_error_context), preprocessor/conditionals
(token-based #if with C precedence, defined()/efun_defined()) and
preprocessor/pragma (real pragma table from the driver).
Rewrote preprocessor/index (full directive table, immutable
predefines), define (function-like macros, stringize/paste, rescan,
redefinition-warning semantics) and include (search order, master
get_include_path, trailing text, macro file names); constructs/include
is now a summary pointing at the reference, and constructs/inherit
documents pathname resolution. Dropped the vestigial
preprocessor/README; sidebar gains the new pages plus the previously
unlisted text_blocks.
AGENTS.md now points agents at docs/lpc/ as the authoritative LPC
reference. Validated with a clean docusaurus production build.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Restructure grammar.y top-down with descriptive nonterminal names, 100%
named references ($name over $N), type-safe Bison value declarations,
EBNF { } repetition folding for recursive list rules, and the grammar
rule actions extracted into grammar_rules*.cc by topic (decls, exprs,
loops, switch, types). No grammar-language changes.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* empty
* docs: modernize concepts/general and fix correctness
Overhaul the docs/concepts/general set: remove MudOS/LPmud/TMI-era
references, correct APIs and config options against the current source,
trim speculative/AI-generated content, and fix the driver overview.
- Rename MudOSdriver.md -> fluffos_driver.md and modernize its content
- lpc: FluffOS branding, note class/struct types, code formatting
- message_doc: correct message()/receive_message signatures and the
`type` semantics; distinguish the message() path from the catch_tell
output efuns; replace the speculative "smart client protocol" essay
with pointers to GMCP/MSDP/MXP/MSP/ZMP
- preprocessor: correct the #pragma list and defaults, document
#error/#warn; move @/@@ text blocks to lpc/constructs/text_blocks.md
- simul_efun: correct the call mechanism, config option name, and
function-visibility rules
- socket_efuns: rewrite the 1992 tutorial into a concise, accurate guide
and document MUD-mode save/restore serialization
- tls: fix fabricated client APIs (socket_connect arity/address, resolve),
the TLS-version claims and cert-path resolution; de-emoji
- tracing: fix the default/cap, output format, build-gate and overhead
claims
- websocket: fix config option names (websocket http dir), set_debug_level,
and the receive_message input/output confusion; trim filler
- global_include_file, oop: minor correctness/typo fixes
Rebased onto the Docusaurus docs: internal links use .md, index files use
extensionless links, and code with braces is fenced. Not built locally;
please verify rendering. See PR notes.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The docs migrated to Docusaurus, but docs/.gitignore still only covered the
previous generators (Jekyll, VitePress). As a result `docs/build/` and
`docs/.docusaurus/` are left untracked after a local `npm run build`. These
are regenerated by CI/CD on deploy and should never be committed, so ignore
them.
Co-authored-by: Claude Opus 4.8 (1M context) <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>
- Expand sidebars.ts: LPC section now has Types, Constructs, Preprocessor
subsections; add top-level Driver section with all driver/*.md pages;
replace Driver Internal with Concepts (autogenerated)
- Add Section 9 to AGENTS.md documenting the Docusaurus 3 setup, config
files, markdown compatibility rules, and sidebar format
- Update docs/CLAUDE.md to reference AGENTS.md Section 9 and replace
stale VitePress references (config path, port 5173) with Docusaurus
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>
The package.json had leftover Docusaurus + React dependencies from a
previous framework, while all scripts and the custom theme already used
VitePress exclusively. Remove the unused packages and upgrade VitePress
from ^1.0.0-rc.30 to ^1.6.4, dropping 1186 packages from the lockfile.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
The synopsis incorrectly listed `void max_eval_cost()` but the function
returns an int (the max eval cost). The spec, implementation, description,
and zh-CN translation all agree on `int`.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The efun spec (mixed *sort_array(mixed *, int|string|function, ...))
and process_efun_callback both support trailing extra arguments that
are passed to the comparison function on each call, but the docs only
showed the three base forms. Update the synopsis to match map_array
and filter_array, and add a paragraph describing the behaviour.
* Generate driver config docs and a starter config from rc.cc tables
Make the runtime-config option tables in rc.cc the single source of truth
for documentation, so the docs can no longer drift from the driver.
- rc.cc: add `category`/`description` fields to the int-option table
(INT_FLAGS) and introduce a STR_FLAGS table for the simple string
options, parsing them directly from the table in read_config().
- docs/gen_config_docs.py: generate docs/driver/config.md from those
tables (resolving expression/macro defaults). `--check` mode fails if
the committed doc is stale.
- .github/workflows/config-docs.yml: run the generator with --check on
changes to rc.cc/options_internal.h/the generator/the doc.
- docs/driver/config.md: regenerated; now covers all recognized options
accurately (previously ~half, with some stale/nonexistent entries).
- driver --generate-config: emit a complete, bootable starter config to
stdout (ints at defaults, required paths as placeholders, websocket/
TLS/external bits commented out). Comment lines are wrapped to stay
under the parser's per-line limit.
- Config.example: add the 9 previously-missing options and fix the
"call_out(0) next level" -> "nest level" typo.
- CLAUDE.md / docs/CLAUDE.md / docs/cli/driver.md: document the source of
truth, the regeneration workflow, and the new flag.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* Config.example: keep only valid options
Remove options the driver doesn't actually use:
- obsolete (driver warns to delete): `binary directory`, `swap file`
- unrecognized / silently ignored: `apply cache bits`, `maximum users`,
`compiler stack size`
Relocate `evaluator stack size` (a valid limit) up with the other limits
and drop the now-empty "not currently used or implemented" section, and
remove the `binary directory` mention from the header note.
Verified: the cleaned sample boots a mudlib to "Initializations complete"
with no obsolete-line warnings.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
