ascii-chat-wasm-development
Skill203 starsChanged 8 days agoMITView on GitHub
Develop, debug, review, and build ascii-chat's Emscripten/WASM browser modules, Embind APIs, shared web renderer, and browser transports. Use when work crosses src/web, lib/platform/wasm, web/packages/shared, web/web, or the CMake WASM targets.
In this repository11 other files it gives its agents.
- web/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- ascii-chat-c-developmentSkill
- ascii-chat-cli-releaseSkill
- ascii-chat-cross-platform-development-and-or-testingSkill
- ascii-chat-documentationSkill
- ascii-chat-mcp-devSkill
- ascii-chat-python-developmentSkill
- ascii-chat-testingSkill
- ascii-chat-web-deploySkill
- sentry-commit-messagesSkill
The file
We split this skill into the rules it gives an agent
9 rules. About 0 are common, 2 are distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 19
Before changing code, inspect the current tree and run git status --short --branch.
- Very specific: line 35
Prefer changing a shared library or its platform abstraction over copying a native feature into src/web.
- Very specific: line 99
Use the current preset and cmake --build output as the authority if these examples drift.
- Distinctive: line 198
Prefer passing strings, numbers, structured values, typed arrays, or Embind objects through the binding.
- Very specific: line 209
Use return_value_policy::reference() for borrowed internal objects and take_ownership()/smart pointers for owned returns when appropriate.
- Very specific: line 223
Use that only when the C++ design really calls back into a JS override.
- Very specific: line 271
When changing codec selection, inspect packet capability bits, packet types, WebRTC/WebTransport receive filters, encoder configuration, …
- Very specific: line 298
Check whether the behavior belongs in shared lib//include/, a WASM platform implementation, a binding, or browser TypeScript.
- Very specific: line 317
Use the package scripts and current CI workflow when names differ.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
ascii-chat WASM development
ascii-chat started life as a native CLI. The browser version works because we carefully reuse the CLI's real media, crypto, protocol, and rendering code and put a thin browser-shaped surface around it. Keep that story intact: make the smallest platform adaptation necessary, preserve the shared pipeline, and do not invent a browser-only implementation when the native implementation can be made portable.
Start by orienting yourself
Before changing code, inspect the current tree and run git status --short
--branch. Existing edits are the user's. The important places are:
src/web/: the nested Emscripten project.CMakeLists.txtselects the browser source set, WASM platform files/stubs, shared native libraries, generated fonts, bindings, and theclient,mirror,renderer, and host entry points.src/web/main_wasm.c,mirror.c,client.c,renderer/, andbindings/are the first places to read for a module change.src/web/bindings/: Embind translation units. These are the deliberate JavaScript ABI, not a place to expose every C function. Generated TypeScript declarations live separately underweb/packages/shared/src/wasm/generated/.lib/platform/wasm/: browser implementations of platform services and stubs.stubs/supplies APIs that make sense for native CLI code but not in a browser.ffmpeg_decoder.candlib/video/webcam/wasm/webcam_wasm.care examples of browser-specific media/platform paths.include/andlib/: the shared public headers and reusable implementation. Prefer changing a shared library or its platform abstraction over copying a native feature intosrc/web.src/common/andsrc/common/session/: shared session, frame, option, and lifecycle orchestration used by native and browser builds. Browser entry points intentionally avoid terminalmain()loops and let TypeScript drive the render/event loop.cmake/: authoritative build machinery. Readcmake/targets/Wasm.cmake,cmake/scripts/build_wasm.cmake,cmake/toolchains/Emscripten.cmake,cmake/init/Options.cmake,cmake/deps/*.cmake, andcmake/targets/Fonts.cmake.web/packages/shared/: reusable TypeScript/React-facing browser package.src/wasm/options.tsis the shared, typed options contract;src/wasm/contains module loaders and generated binding types;src/components/AsciiRenderer/contains the renderer component, hooks, workers, and raster helpers.web/web/: theweb.ascii-chat.comapplication.src/wasm/loads the module artifacts;src/network/owns WebRTC, WebTransport/QUIC, WSS/fallback, ACIP packet handling, browser video encoding/decoding, discovery, handoff, and session security;src/hooks/andsrc/components/connect those APIs to the site.web/web/src/wasm/dist/: canonical checked-in WASM artifacts for the web package (*.js,*.wasm, and the manifest). Runtime copies underweb/web/public/wasm/are generated/ignored; do not hand-edit them.deps/ascii-chat-deps/: vendored dependencies, notably yyjson. WASM dependency build/cache configuration is incmake/deps/and uses the shared.deps-cache/rather than an ad-hoc cache.build/web/: the nested Emscripten build directory created by the parent CMake project. Do not delete it to "fix" a build; reconfigure it.
What the four targets mean
The parent project exposes four custom targets from cmake/targets/Wasm.cmake:
client-web: browser client/session/crypto/network API used by the web site to interoperate with CLI and iOS clients.web: the convenience target that buildsmirror-webandclient-web.mirror-web: browser camera/file/test-pattern/audio/mirror processing used byweb.ascii-chat.com.renderer-web: the renderer WASM package published withoptions.ts, theAsciiRenderercomponent, and its hooks/utilities. It is the reusable way to render ASCII art in another web application.
client-web, web, and mirror-web serve the web.ascii-chat.com product and
its browser-facing service APIs. renderer-web is the separately reusable
renderer surface. The site is deliberately built on these APIs so a browser
can use much of ascii-chat's real feature set while remaining compatible with
native CLI and iOS peers.
BUILD_WEB=OFF is the default. The normal native build therefore does not
require Emscripten or browser dependencies. Enable it through CMake and let
CMake configure the nested Emscripten project. Do not invoke emcmake or
emmake manually; this repository's CMake files select the toolchain and run
the nested configure/build internally.
Typical commands are:
cmake --preset default -B build
cmake --build build
cmake --preset default -B build -DBUILD_WEB=ON
cmake --build build --target client-web
cmake --build build --target web
cmake --build build --target mirror-web
cmake --build build --target renderer-webUse the current preset and cmake --build output as the authority if these
examples drift. Release web artifacts are normally built from the repository's
web deployment workflow and published by web/web/scripts/wasm-build.mjs.
Making CLI C work in a browser
WASM is not a second application. It is the CLI's reusable C machinery with the terminal, process, filesystem, native sockets, OS threads, signals, and blocking entry loops replaced or removed. Use existing guards and platform abstractions:
#ifndef __EMSCRIPTEN__
/* native process, terminal, or OS-only behavior */
#endif
#ifdef __EMSCRIPTEN__
/* browser scheduling or platform behavior */
#endifExamples in this tree include lib/media/yt_dlp.c excluding subprocess
extraction, lib/options/colorscheme.c and lib/options/parsing/parsers.c
excluding native-only behavior, lib/network/tcp/transport.c excluding
native socket paths, src/common/session/host.c excluding blocking/native
host work, and lib/debug/backtrace.c/lib/debug/mutex.c relying on WASM
stubs. Prefer an existing lib/platform/wasm/ implementation or stub to a
new preprocessor island. If a public API must still exist, provide a safe WASM
stub with the same signature and explicit browser semantics.
The WASM CMake source list intentionally omits terminal main.c and blocking
session screen loops. JavaScript owns the browser render/event loop and calls
functions such as mirror conversion, client ticks, packet processing, and
renderer feed operations. Never make a browser callback allocate, log heavily,
block, or wait for a native terminal condition.
Why web.ascii-chat.com is possible
The browser does not have a separate ASCII renderer. The CLI's --render-file
backend is the key: the browser reuses the same media decoding, frame sizing,
options, and terminal-cell rendering path and sends its result to browser
surfaces instead of a native file/terminal. libvterm is central to terminal
cell semantics. The generated font data and the project's font/render support
(including FreeType-backed paths where enabled) are central to converting
pixels into stable glyph output. Read lib/media/render/terminal.c, the
renderer sources, src/web/renderer/, and cmake/targets/Fonts.cmake before
changing rendering. Preserve the allocation-free hot path, dimensions/stride,
palette, glyph, stabilization, and ownership rules.
WASM dependencies are ordinary linked libraries built for the Emscripten
target, not magic browser packages. The current WASM project explicitly wires
libsodium, PCRE2, ICU, Opus, Zstd, libvterm, FFTW, utf8proc, TOML, yyjson,
and generated fonts through src/web/CMakeLists.txt and cmake/deps/. In
addition, Emscripten supplies the runtime/glue library and the Embind runtime
when bindings are linked (the project may therefore produce more than one
compiler/runtime artifact, but do not assume a fixed count). Inspect the
actual link line and artifact manifest rather than guessing.
Embind: the current ABI
Bindings are registered by static EMSCRIPTEN_BINDINGS(...) blocks. The
current binding families are:
audio.cpp:AudioProcessorBinding(valid,process) andOpusCodecBinding(valid,encode,decode) for browser audio work.av_state.cpp:AVStateBinding(valid,generation,begin,complete,current,active,beginStop,finishStop) for lifecycle synchronization.client_frames.cpp:validateFramefor incoming frame validation.discovery.cpp:DiscoveryBinding(valid,callbackToken,enter,receive,leave,snapshot) plushandoffEncode/handoffDecode.face.cpp:faceReset,faceDetect, andfaceTick.frame.cpp: stabilizer/capture helpers plusMirrorFrameBinding(convert,transform,submitAudio,renderAudio).key_parser.cpp: browser key/error APIs (parseKey,keyParserError,errorSnapshot,errorFrame, and dismissal).mirror_session.cpp:initMirror,sessionRenderCleanup, andmirror_cleanup.networking.cpp: client initialization/cleanup, keypair/public-key and connection-state APIs, crypto policy/handshake, server addressing, and QUIC init/tick/epoch/output/packet APIs, plusClientSessionBinding.peer_crypto.cpp:configureCryptoandPeerCryptoBindingfor session crypto, reliable send/receive/tick, QUIC lifecycle/output, and received data.protocol.cpp: handshake, packet crypto, JSON packet parsing, and packet serialization helpers.session_host.cpp: browser host lifecycle/render/audio plusHostPacketBinding.receive.session_ui.cpp: UI FPS/volume andSessionUiBindingfor resize, loading, logs, media, key, tick, clear, and redraw.terminal_renderer.cpp:TerminalRendererBinding(valid,error,cols,rows,width,height,setZalgo,feed,copyPixels).test_pattern.cpp:TestPatternBinding(valid,render).
Generated declarations in web/packages/shared/src/wasm/generated/ are useful
for TypeScript but are not the source of truth. Change the C++ binding and
regenerate/verify the declarations and loaders used by the relevant module.
Memory and object lifetime
Prefer passing strings, numbers, structured values, typed arrays, or Embind
objects through the binding. JavaScript should not manually allocate, copy,
index, and free C heap memory for ordinary application work. In particular,
do not build a parallel Module._malloc/HEAPU8 protocol unless a measured,
obvious binary fast path truly requires it. Put ownership in the C++ binding
method or return an Embind value with a clear policy.
For an Embind class created in JS or returned by a C++ function, call .delete()
when the handle is no longer needed, preferably in try/finally. Use
clone() only when two independent lifetimes genuinely need the same object;
delete every clone. Do not rely on FinalizationRegistry for correctness.
Use return_value_policy::reference() for borrowed internal objects and
take_ownership()/smart pointers for owned returns when appropriate. A typed
memory view is a borrowed view: it becomes invalid if the C buffer changes or
is freed, so copy it before retaining it beyond the documented lifetime.
Current binding classes generally own their native resources and expose a
small method surface. Follow their constructors/destructors and valid()/
error() APIs instead of reaching behind them. If a binding returns a binary
result, make the ownership and validity window explicit in C++ and TypeScript.
Embind can expose true C++ inheritance, but JavaScript subclassing is not a
general replacement for a wrapper. Emscripten's supported route is
allow_subclass() with a wrapper<T>, virtual methods, and EMSCRIPTEN_WRAPPER
for a polymorphic C++ interface; base<T> handles bound C++ inheritance.
Use that only when the C++ design really calls back into a JS override. For
ascii-chat's concrete resource-owning bindings, use the generated classes
directly. If browser code needs presentation state, a small TypeScript helper
or React hook is fine, but do not create a handwritten class that merely wraps
every Embind method. Do not manually wrap a binding just to avoid using the
generated type.
For small C-to-JavaScript conveniences, emscripten::val, EM_JS, or
EM_ASM can be clearer than hand-marshalling memory. yyjson is vendored and
available when a real JSON document must cross a C boundary, but most paths
are nicer as C values plus Emscripten/Embind types; use JSON deliberately, not
as the default interchange format.
Options and renderer package
web/packages/shared/src/wasm/options.ts is the browser/native options
contract. Its enums mirror native values (ColorMode, RenderMode,
ColorFilter, TextRenderer), it owns browser defaults/palettes, validates
option patches and UTF-8 palette limits, and the Options class applies
revision-aware atomic patches through readOptions()/patchOptions(). Keep
those numeric values synchronized with native option enums and treat revision
conflicts as a refresh/retry, not as permission to overwrite state.
The shared package's AsciiRenderer, hooks, raster worker, and utilities are
the intended consumer of renderer-web. Extend those APIs when adding a
renderer feature; do not make web/web privately reimplement the renderer.
The longer-term goal is to publish renderer-web as the open-source
ascii-chat npm package: a polished browser renderer anyone can use to render
ASCII art. Expect that package to grow around the same core with H.264/HEVC
support, face and frame stabilization, an FPS-controlled render loop, and a
callback hook that lets an application supply pixels to the renderer. Keep
those features reusable and browser-agnostic rather than coupling them to
web.ascii-chat.com.
Browser video codecs
Browser capture uses WebCodecs VideoEncoder in
web/web/src/network/VideoUploadEncoder.ts. It probes the exact H.264 and
HEVC configurations with VideoEncoder.isConfigSupported(), and the selection
logic in videoEncoding.ts/useVideoEncodings.ts prefers HEVC in auto only
when the browser actually supports the tested configuration, then H.264, then
raw. Explicit requests must not silently become a different codec. Encoded
Annex-B access units are carried in ACIP H.264/H.265 frame packets, while
BrowserVideoDecoder uses the browser decoder path for received frames.
HEVC/H.265 support is browser/OS/device dependent; H.264 is the compatibility
fallback. Keep probing capability rather than keying off the browser name.
When changing codec selection, inspect packet capability bits, packet types,
WebRTC/WebTransport receive filters, encoder configuration, decoder behavior,
and the E2E tests in web/web/tests/e2e/video-encoding.spec.ts together.
Crypto and browser transports
web/web/{discovery,client} use the same application crypto/session machinery
as the CLI through the client and peer-crypto bindings. The transport wrapper
differs: browsers use WSS/WebSocket fallback, WebRTC/DTLS, and WebTransport
HTTP/3/QUIC where available, with browser APIs handling the underlying socket,
TLS, and ICE mechanics. Native QUIC and browser WebTransport share ACIP
concepts but are not identical browser APIs. Do not claim that browser TLS
replaces ACIP authentication: transport security and application/session
authentication remain separate readiness gates. Read
WebRTCSession.ts, WebTransportClientSession.ts, AcipQuicProtocol.ts,
connectionSecurity.ts, DiscoveryProtocol.ts, and the C bindings before
changing handoff, rekey, or packet security.
Preserve the shared packet formats, authenticated records, epochs, readiness checks, cancellation, and fallback semantics. Browser-only code should adapt events and byte streams to the shared protocol; it should not invent a second crypto handshake or packet format.
A safe change loop
- Identify the module and follow its path from CMake source list to binding, generated TypeScript declaration, loader, and browser caller.
- Check whether the behavior belongs in shared
lib//include/, a WASM platform implementation, a binding, or browser TypeScript. Keep each layer honest. - Guard or stub only the native-only boundary. Preserve error propagation, tracked allocation, ownership, and lifecycle cleanup.
- Build the narrow target with CMake. For a binding or ABI change, rebuild the affected artifact and run the relevant TypeScript/E2E tests; for renderer or media changes, include the renderer and codec tests.
- Inspect generated artifacts and the manifest/source hashes. Never hand-edit
generated
.js,.wasm, or runtime copies to make a test pass.
Useful checks include:
cmake --build build --target mirror-web client-web renderer-web
pnpm --dir web/web test
pnpm --dir web/web exec playwright test tests/e2e/video-encoding.spec.tsUse the package scripts and current CI workflow when names differ. For native
tests, also follow ascii-chat-testing; for web deployment, follow
ascii-chat-web-deploy.
For Embind semantics and current compiler behavior, consult the official Emscripten Embind documentation: https://emscripten.org/docs/porting/connecting_cpp_and_javascript/embind.html
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

