Calculator editor

Takeaway: import only the constructors used by your config. The complete export list is in the package source.

Bosatsu Packages and Imports

package MyPackage

from Bosatsu/Predef import Int, String, Bool, List
from Yichus/Num/Float64 import Float64, int_to_Float64

Each file starts with package Name. Use from Pkg import ... to bring names into scope. Takeaway: package declarations establish identity, and imports bring exported names into scope. The Bosatsu language guide is the authoritative syntax route.

Core Value Types

Takeaway: use these types in annotations and let the compiler reject mismatches. See the language guide for type and literal syntax.

Struct Construction and Destructuring

struct Point(x: Int, y: Int)

p = Point(3, 4)
# Access fields via pattern matching

Takeaway: structs group typed fields and patterns read them. The language guide covers struct declarations and matches.

Function Definitions and Calls

def add(a: Int, b: Int) -> Int:
  a.add(b)

def greet(name: String) -> String:
  "Hello, ".concat(name)

Functions use indentation for body. Types can be inferred; explicit parameter and return annotations document a function’s interface. Takeaway: a function body is the final expression in its indented block. See the function syntax reference.

Exhaustive Pattern Matching

match point:
  case Point(x, y):
    x.add(y)

Exhaustive matching is required. Use _ for wildcard. Takeaway: each constructor must be covered or the wildcard must handle the remainder. See the pattern reference.

Enum Constructors and Matches

enum Color: Red, Green, Blue

match c:
  case Red: "red"
  case Green: "green"
  case Blue: "blue"

Constructors are bare names imported directly. Takeaway: enum values select one declared variant, and exhaustive matching handles them. See the enum reference.

Local Bindings and Method-Call Sugar

def calc(x: Int) -> Int:
  doubled = x.mul(2)
  offset = doubled.add(10)
  offset

Bindings are name = expr. The last expression is the return value. x.mul(2) is method-call sugar for mul(x, 2) -- any function can be called this way on its first argument, with no automatic currying. Takeaway: local names bind immutable expression results. See the Bosatsu guide for declaration blocks and application syntax.

Common Bosatsu/Predef Functions

Takeaway: these functions cover common integer, comparison, and string operations. Check the upstream builtin package sources when a signature is uncertain.

Fractional arithmetic

Use these imports in a calculation that needs fractional results. The aliases let you write arithmetic with ordinary operators.

from Yichus/Num/Float64 import (
  Float64, int_to_Float64,
  addf as `+`, subf as `-`, mulf as `*`, divf as `/`
)

Read the complete numeric package for powers, comparisons, and other operations.

Immutability, Recursion, and Numeric Imports

All values are immutable. Bosatsu supports checked recursion, including recur blocks over structurally smaller values; recursive definitions must satisfy the totality checker. foldl_List from Bosatsu/Predef remains useful when a fold expresses the operation directly.

Integer literals and arithmetic use Int. Convert inputs with int_to_Float64 when your calculation requires fractions.

Full language guide: johnynek.github.io/bosatsu/language_guide.html

Local WebMCP Relay Connection

This editor publishes WebMCP tools through a compatible browser host or a local relay, so an agent (Claude Code, Claude Desktop, Cursor, or anything that speaks MCP) can read and edit the sources, compile, and power autocompletion. Native site-tool hosts can use the page directly. For an ordinary browser, these three steps connect the local relay:

1. Build the relay. @yichus/mcp is not published to npm, so npx will not find it. Build it from a checkout with Node.js 20 or newer and pnpm:

git clone https://github.com/snoble/yichus && cd yichus
pnpm install
pnpm run yichus-mcp:build

2. Register the relay with your MCP client. Add this to the client's MCP config (Claude Desktop, Cursor, Windsurf, Claude Code all accept stdio servers in this shape), replacing the path with the absolute path to your checkout; the client launches and keeps the relay process running:

{
  "mcpServers": {
    "yichus": {
      "command": "node",
      "args": ["/absolute/path/to/yichus/packages/yichus-mcp/dist/cli.js"]
    }
  }
}

(To try the relay without a client config, run that same command in a terminal. It stays in the foreground while connected.)

3. Attach this page to the relay. Reload with ?webmcp=1 in the URL (or set localStorage.yichus_webmcp = "on"). The page then registers its tools with the local relay; without that flag the page never attaches to the local relay. Native site tools do not require the flag. To check the connection, ask the agent to call yichus_autocomplete_list_editors. It lists the editors currently attached. Takeaway: both the relay process and the page opt-in are required. The relay README documents the connection boundary.

Revision-Safe Agent Autocompletion

Ask your connected agent to loop: call yichus_autocomplete_wait_for_request (it blocks until you pause typing or request a completion), answer with yichus_autocomplete_suggest, repeat. With that loop running:

Suggestions are pinned to the editor revision they were computed against; if the text changes before they arrive, they are discarded instead of applied. Takeaway: keep the wait/suggest loop running, and expect stale completions to be rejected. The protocol and schemas are implemented in bosatsu-autocomplete.js.

Check the result the user can see

Read sources and their revision first. Pass expectedRevision when updating them so a newer user edit is not overwritten. Compile, then call yichus_playground_get_output until outputReady is true. Its feedback includes rendered text, controls, chart count, page width, and runtime errors. Errors and source edits clear the previous output. This feedback is not a screenshot.

Connection instructions and the shared-example workflow. For calculators embedded in guides, the example tools can also change preview controls and open Why.

Playground Editing Tool Names

Takeaway: these tools read, replace, compile, inspect, or reset the two source buffers. Their exact input schemas are in registerPlaygroundWebMcpTools.

Autocomplete Tool Names

Takeaway: use editing tools for whole-source compile cycles and autocomplete tools for revision-pinned suggestions. The exact editing-tool JSON schemas live in registerPlaygroundWebMcpTools; autocomplete schemas live in bosatsu-autocomplete.js. Full relay setup: github.com/snoble/yichus, packages/yichus-mcp/README.md