DEV Community: yuelinghuashu

MCP stdio Protocol's 3 Hidden Traps: When All Unit Tests Pass but the MCP Server Won't Respond

yuelinghuashu — Sun, 23 Aug 2026 10:22:22 +0000

This article records a real MCP Server debugging session: every automated test of story-cli passed, yet in a real environment the MCP Server couldn't respond to any request at all. The root cause turned out to be 3 bugs, each touching low-level details of the Node.js process model and the stdio protocol.

TL;DR

If you're building an MCP Server (or any long-running process that speaks a stdio protocol), remember three iron rules:

Never call process.exit() inside a run() function — MCP Servers, --watch modes, and any other long-running command are not one-shot CLI tools. process.exit() kills the process before it even starts listening. If you must make an exception, extract the "long-running" abstraction (e.g. isLongRunning) instead of enumerating specific commands.
Never print debug logs to stdout — stdout is the MCP protocol channel. Any output that isn't JSON-RPC pollutes the message stream and makes the client unable to parse any response. Diagnostics belong on stderr.
Always wait for all async work in the close event — close only means the input stream closed, not that your callbacks have finished. You need to wait for all in-flight Promises before exiting.

Background: story-cli's MCP Server

First, a quick introduction to the project. story-cli is a zero-deployment, Git-native Markdown content management CLI. It manages stories/papers/notes/tutorials with a simple directory convention (NN-名称/ — "NN-name/" — containing config.json + text.md), auto-generates READMEs, exports EPUB, and is bilingual (Chinese/English).

On our roadmap, the MCP Server was a P0-level strategic task — the gateway to the AI era. The design principle: "AI does the thinking, the CLI does the governance."

We exposed 6 tools over JSON-RPC 2.0 over stdio:

MCP tool	Purpose
`scan_stories`	List all stories and their metadata
`read_chapter`	Read a chapter's content from a story
`write_chapter`	Write body text to a story (atomic write)
`validate`	Validate the config.json of every story
`build`	Trigger a README rebuild
`import_json`	Bulk-import stories from structured JSON

The code structure was clean:

src/mcp/
├── protocol.ts   # JSON-RPC 2.0 protocol parsing/serialization (pure functions, fully tested)
├── tools.ts      # MCP tool registration (reuses shared logic from core/loader.ts)
└── server.ts     # stdio server startup and request dispatch

Everything looked perfect — until we actually called it.

The Symptom: All Automated Tests Green, But Real Requests Get No Response

At the time we had 404 automated tests, 401 passing. tests/mcp.test.ts covered protocol parsing, serialization, tool registration, and every tool handler — all passing.

So I started the MCP Server against a real story repository and sent a JSON-RPC request through a pipe:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node bin/index.ts mcp-server

💀 Empty output. No response at all.

I thought my pipe syntax was wrong. I tried several variations:

# approach 1: printf
printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' | node bin/index.ts mcp-server

# approach 2: file redirection
printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n' > /tmp/req.json && node bin/index.ts mcp-server < /tmp/req.json

# approach 3: keep stdin open
{ printf '{"jsonrpc":"2.0","id":1,"method":"tools/list"}\n'; sleep 2; } | node bin/index.ts mcp-server

Still nothing.

Even weirder: when sending the request through Node.js's spawnSync, the process exit code was 0 (it looked "successful"), but both stdout and stderr were empty.

At that moment I realized: this isn't a calling convention problem — our MCP Server has a bug.

But 404 tests were green! How could there be a bug?

Bug #1: The Ghost of process.exit()

Root Cause Investigation

I first looked at the CLI entry file bin/index.ts:

#!/usr/bin/env node
import { run } from "../src/cli.ts"

const exitCode = await run(process.argv)
process.exit(exitCode)

The problem was obvious at a glance.

When a user runs story mcp-server:

run(process.argv) is invoked
Inside run(), runMcpServer(rootDir) is called → startMcpServer() starts listening on stdin
run() returns 0 immediately (because startMcpServer() is an async pattern that "registers listeners and returns" — it doesn't block)
process.exit(0) executes immediately → the process terminates
The JSON-RPC request sitting in stdin never gets read by readline

The MCP Server died the moment it was born.

The Fix

#!/usr/bin/env node
import { run } from "../src/cli.ts"

const exitCode = await run(process.argv)

// An MCP server needs to stay alive and keep listening on stdin.
// Process exit is handled by the close/SIGINT events inside server.ts.
if (process.argv[2] !== "mcp-server" && process.argv[2] !== "mcp") {
  process.exit(exitCode)
}

⚠️ Note: this fix looked fine at the time, but later that same day testing exposed its limitation — see "Bug #1.5: The Same Bug Returns" below.

The Deeper Lesson

This is the first trap when turning a CLI tool into a service:

Mode	Lifecycle	When to exit
CLI tool	Exits after the command finishes	`process.exit(exitCode)` is the right thing
Long-running process (MCP Server / daemon)	Keeps listening for input until EOF/signal	Exit must be driven by a callback triggered by the input source

process.exit() is unconditional, immediate, and uninterruptible. It doesn't wait for pending I/O, timers, or Promises. In the MCP Server scenario, that "feature" killed our server outright.

Bug #1.5: The Same Bug Returns — process.exit()'s Second Ghost

The Symptom

After fixing Bug #1, I kept testing the MCP Server. That same day, I wanted to check the performance of story build --watch:

story build --watch

The output said 「👀 监听模式已启动，文件变更自动重建...」 ("👀 watch mode started, auto-rebuilding on file changes..."), but the process exited immediately — --watch mode never actually started watching files.

I tried modifying a story file:

echo "新内容" > "01-测试故事/text.md"

Nothing happened. The README was never updated.

Root Cause: The Whitelist-of-Commands Flaw

I looked back at the fix in bin/index.ts:

if (process.argv[2] !== "mcp-server" && process.argv[2] !== "mcp") {
  process.exit(exitCode)
}

What this logic says is: "for every command except mcp-server and mcp, call process.exit()."

But build --watch is also a long-running process! It needs to keep watching files until it receives SIGINT. Only the two MCP Server commands were exempted — build --watch wasn't on the whitelist, so it got killed by process.exit() immediately too.

The first MCP Server bug was fixed, and the same ghost reappeared on build --watch.

The Fix: Extract the "Long-Running" Abstraction

The right fix isn't to enumerate even more commands — it's to extract the essential property of "which commands are long-running":

#!/usr/bin/env node
import { run } from "../src/cli.ts"

const exitCode = await run(process.argv)

// Long-running processes need to stay alive; exit is handled by internal close/SIGINT events:
// - MCP server: keeps listening on stdin; exit is controlled by server.ts's close/SIGINT
// - build --watch: keeps watching file changes; exit is controlled by build.ts's SIGINT
const isLongRunning =
  process.argv[2] === "mcp-server" ||
  process.argv[2] === "mcp" ||
  (process.argv[2] === "build" && process.argv[3] === "--watch") ||
  (process.argv[2] === "b" && process.argv[3] === "--watch")

if (!isLongRunning) {
  process.exit(exitCode)
}

The Deeper Lesson: Fix Bugs by Extracting an "Abstraction", Not Enumerating "Instances"

This was the biggest lesson of the whole session:

Fix approach	Code shape	Problem
Enumerate instances (at the time)	`if (cmd !== "mcp-server" && cmd !== "mcp")`	Adding one more long-running command means coming back to edit this line
Extract an abstraction (final)	`const isLongRunning = ...`	Any new command just expresses its property inside this set

When you see an "exclusion list" in code (if (cmd !== "A" && cmd !== "B")), it means you're enumerating specific commands instead of expressing the essential property of "which commands are long-running". The moment a new long-running command appears (like --watch), the same bug returns.

Checklist: if your CLI is ever going to add a "keep-listening" feature (watch / serve / daemon), check the isLongRunning list in bin/index.ts first — it must include the new command.

Bug #2: The Fatal Pollution of console.log

The Surprise: After Fixing Bug #1, Some Responses Appeared

After fixing Bug #1, I was pleasantly surprised to see tools/list respond! But only these responded:

tools/list ✅
initialize ✅
Error responses for unknown tools ✅

Meanwhile, the async tools/call still got no response (scan_stories / read_chapter / validate).

I tested scan_stories on its own:

echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"scan_stories","arguments":{}}}' | node bin/index.ts mcp-server

Still empty.

I tried a different angle — calling loadStories() directly in Node:

node --experimental-strip-types -e "
import { loadStories } from './src/core/loader.ts';
const { stories } = await loadStories('/tmp/test-story-cli');
console.log('STORIES:', stories.length);
"

Output:

📊 01-测试故事: 自动计算字数为 约 13 字（未写回，使用 --save-counts 持久化）
📊 02-二创故事: 自动计算字数为 约 13 字（未写回，使用 --save-counts 持久化）
📊 03-English-Story: 自动计算字数为 ~7 words（未写回，使用 --save-counts 持久化）
STORIES: 3

Found it! Inside loadStories(), a console.log was printing "auto-computed word count" diagnostic lines.

Why Can a Single `console.log` Kill MCP?

MCP's stdio transport spec says stdout is the protocol-dedicated channel:

├── stdin  ← client sends JSON-RPC requests
├── stdout → server returns JSON-RPC responses (protocol-dedicated, the only legal output)
└── stderr → logs/warnings/errors (for humans, not for the protocol)

When an MCP client sends a scan_stories request, the server calls loadStories() while handling it, and console.log dumps a 📊 01-测试故事: ... line to stdout. Now stdout looks like:

📊 01-测试故事: 自动计算字数为 约 13 字...      ← pollution!
{"jsonrpc":"2.0","id":3,"result":{...}}        ← the real response

MCP clients (VSCode / Claude Desktop / Cursor) expect every line of stdout to be a valid JSON-RPC message when parsing. The first line isn't JSON at all —

the client gives up on parsing, which looks like "no response".

As a side note, MCP's stdio transport also has a hard requirement about newlines: every JSON-RPC message must end with \n. If your server outputs JSON without a trailing newline, the client also fails to parse it. That's why the official MCP docs' Debugging page states it plainly:

"Local MCP servers should not log messages to stdout (standard out), as this will interfere with protocol operation."

— The docs warned us all along; we only truly understood it after stepping on it in a real environment.

And this kind of bug is especially sneaky:

In unit tests, scan_stories's handler is called directly and nobody parses stdout → tests pass
In a real environment, the MCP client strictly parses stdout → immediate breakage

The Fix

// Before
if (!config.wordCount) {
  console.log(locale.autoWordCount(folder, story.wordCount, saveCounts))
}

// After
if (!config.wordCount) {
  // Use stderr for diagnostics so we don't pollute the stdout channel of the MCP stdio protocol.
  console.error(locale.autoWordCount(folder, story.wordCount, saveCounts))
}

The console.log(locale.generatedText(...)) inside loadStoryContentAsync was changed the same way.

The Deeper Lesson

In a stdio protocol, stdout is not for logging. It's the protocol channel between two processes. Any extra output — even a single seemingly harmless log line — breaks protocol parsing.

This is a silent runtime failure: the code doesn't throw, tests don't fail, and only real clients mysteriously stop working.

In an MCP Server, stdout = protocol, stderr = logs. Never mix them.

Bug #3: The Async Race on readline close

Another Surprise

After fixing Bug #2, I thought everything was done. But testing showed tools/call still responded intermittently: sometimes a response came back, sometimes not.

I stared at the old code in src/mcp/server.ts:

export function startMcpServer(rootDir: string, tools: RegisteredTool[]): void {
  const rl = createInterface({ input: process.stdin, terminal: false })

  rl.on("line", async (line) => {
    // ... parse and handle the request
    const response = await handleRequest(request, rootDir, tools)
    if (response) process.stdout.write(serializeMessage(response))
  })

  rl.on("close", () => {
    // Wait for stdout to flush before exiting (avoid truncated output)
    process.stdout.write("", () => process.exit(0))
  })
  // ...
}

In pipe mode (echo '...' | node bin/index.ts mcp-server), stdin closes immediately after all lines are read, which fires the close event. When close fires, the async await handleRequest() inside rl.on("line") hasn't finished yet!

Here's the timing:

t0:  stdin receives the JSON-RPC request line
t1:  rl fires the "line" event and enters the async callback
t2:  the async callback hits await handleRequest() and suspends (shaded area = waiting for the async result)
t3:  stdin finishes reading all lines → rl fires the "close" event
t4:  the "close" callback runs process.stdout.write("", () => process.exit(0))
t5:  the process exits while await handleRequest() is still suspended → the response is lost forever

This is an async race: close says "the input stream is closed", but it doesn't wait for your Promises to finish.

The Fix

Track all in-flight requests with a pending Set, and wait for all of them on close before exiting:

export function startMcpServer(rootDir: string, tools: RegisteredTool[]): void {
  const rl = createInterface({ input: process.stdin, terminal: false })
  const pending = new Set<Promise<void>>()

  rl.on("line", (line) => {
    const trimmed = line.trim()
    if (!trimmed) return
    let request: JsonRpcRequest
    try {
      request = parseRequest(trimmed)
    } catch (e) {
      const code =
        (e as Error & { code?: number }).code ?? JsonRpcErrorCode.InternalError
      process.stdout.write(
        serializeMessage(makeErrorResponse(null, code, (e as Error).message)),
      )
      return
    }
    // Track in-flight requests so we know the async handler has finished when stdin closes.
    const task = (async () => {
      const response = await handleRequest(request, rootDir, tools)
      if (response) process.stdout.write(serializeMessage(response))
    })()
    pending.add(task)
    task.finally(() => pending.delete(task))
  })

  rl.on("close", () => {
    // Wait for all in-flight requests to finish, then flush stdout before exiting (avoid truncated output).
    void Promise.allSettled([...pending]).then(() => {
      process.stdout.write("", () => process.exit(0))
    })
  })
  process.on("SIGINT", () => {
    rl.close()
  })
}

The Deeper Lesson

In Node.js's event loop, readline's close event only means "the input stream closed", not "your async callbacks have run".

This is a universal problem for every stdio protocol server: when stdin hits EOF, you may still have queued Promises. You need to track and wait for them explicitly:

Maintain a set of all in-flight operations
On close or SIGINT, wait with Promise.allSettled
Only then call process.exit

The Takeaway: Test Layering

The biggest insight from this session was the value of layered testing:

Test layer	Our previous coverage	What it would catch
Unit tests (calling handler functions directly)	✅ 401 all green	Can't catch Bug #1 / #2 / #3
Integration tests (calling `startMcpServer` without a real process)	❌ none	—
End-to-end tests (spawnSync a real child process + real stdin/stdout)	❌ none	All 3 bugs at once

Green unit tests don't mean the system works. You need to start the server in a real process, send requests through real pipes, and parse real stdout — because only end-to-end tests can catch problems at the "process lifecycle" and "protocol integrity" levels.

// tests/mcp-server.test.ts (the end-to-end test we added)
function sendRequests(dir: string, requests: string[]) {
  const input = `${requests.join("\n")}\n`
  const result = spawnSync(process.execPath, [binPath, "mcp-server"], {
    cwd: dir,
    input,
    encoding: "utf-8",
    timeout: 5000,
  })
  return {
    stdout: result.stdout || "",
    stderr: result.stderr || "",
    status: result.status ?? -1,
  }
}

test("MCP server responds to async tools/call (scan_stories)", () => {
  const { stdout, stderr } = sendRequests(dir, [
    '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"scan_stories","arguments":{}}}',
  ])
  // stderr must not contain JsonRpcResponse content → guards against console.log/stdout pollution
  assert.ok(!stderr.includes("jsonrpc"))

  // Split by lines and filter empty lines instead of JSON.parse(stdout.trim()).
  // If stdout contains multiple lines, trim() only strips leading/trailing whitespace
  // and the inner newlines make JSON.parse fail.
  const lines = stdout
    .split("\n")
    .map((l) => l.trim())
    .filter(Boolean)
  assert.ok(lines.length >= 1, "there should be at least one JSON-RPC response")
  // Take the last line (or look up the line by id when multiple responses are requested)
  const response = JSON.parse(lines[lines.length - 1] ?? "{}")
  // ...
})

This test starts the MCP Server in a real child process, sends JSON-RPC requests through real pipes, and validates the stdout contents. If anyone ever adds a console.log to loadStories, this test fails immediately.

Follow-up (same day): after fixing Bug #1.5, we added an end-to-end regression test for build --watch (tests/watch.test.ts) — it uses spawnSync to start a real child process and asserts "the process stays alive" + "the README is rebuilt within 5 seconds of editing a story". If we'd had that test back then, Bug #1.5 would have been caught the day it was fixed, instead of surfacing by accident during a later performance check. That's test layering proven once again: unit tests can't cover process lifecycle — only end-to-end tests can.

Appendix 1: The Complete Debugging Flow (for Reference)

# 1. Create a test repository
mkdir -p /tmp/test-story-cli && cd /tmp/test-story-cli
node /path/to/story-cli/bin/index.ts init
node /path/to/story-cli/bin/index.ts new "测试故事"

# 2. Start the MCP Server (find the problem)
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node /path/to/story-cli/bin/index.ts mcp-server
# → empty output (Bug #1)

# 3. After fixing #1 → tools/list responds, but scan_stories doesn't (Bug #2's stdio pollution)

# 4. Verify loadStories behavior in isolation
node --experimental-strip-types -e "
import { loadStories } from './src/core/loader.ts';
await loadStories('/tmp/test-story-cli');
"
# → see the 📊 logs appearing on stdout

# 5. After fixing #2 → sometimes responds, sometimes not (Bug #3's async race)

# 6. Verify repeatedly via the end-to-end test
node --test tests/mcp-server.test.ts
# → 7 tests pass

Appendix 2: The MCP Inspector Debugging Tool

Everything above is "post-mortem" debugging. If you integrate MCP Inspector (MCP's official debugging tool) during development, many of these problems can be caught before release:

npx @modelcontextprotocol/inspector node /path/to/story-cli/bin/index.ts mcp-server

MCP Inspector launches a visual web UI that lets you:

View the full tool list / parameter schemas (catch registration problems)
Call each tool one by one and inspect the raw responses (catch stdout pollution)
Check the protocol-layer communication logs (catch handshake failures / newline issues)

It's the "X-ray machine" of MCP Server development — I recommend every MCP Server developer run everything through the Inspector before CI/CD.

There are also third-party helpers in the community (like mcp-stdio-guard for catching stdout pollution), but the Inspector as the official tool covers most scenarios.

Appendix 3: Format Drift in the AI Interaction Layer

An MCP Server has to handle not only protocol traps (#1 / #2 / #3) but also traps in the AI interaction layer:

When create_story creates a directory, it converts spaces in the title to hyphens (e.g. "AI 创作的故事" → 02-AI-创作的故事), but the LLM may pass back the original space form ("02-AI 创作的故事") — safeFolder has to match both variants to hit the right directory.

Protocol-layer traps and interaction-layer traps — we stepped on all of them the same day.

Summary: Three Iron Rules + One Meta-Lesson

If you only take away three sentences, plus one lesson about fixing bugs themselves:

process.exit() belongs only to one-shot CLI commands. Long-running processes (MCP Servers / watch mode / daemons) must have their exit controlled by input/signal callbacks. When making exceptions, extract the "long-running" abstraction — don't enumerate specific commands.
stdout is a protocol channel, not a log channel. In any stdio protocol server, non-protocol output is pollution. Diagnostics belong on stderr.
close ≠ all work finished. Use a pending Set + Promise.allSettled to explicitly wait for async work.
Fix bugs by extracting an "abstraction", not by enumerating "instances". When you see an exclusion list like if (cmd !== "A" && cmd !== "B"), you're enumerating specific commands — when a new long-running command appears, the same bug recurs somewhere new.

What these four problems have in common: none of them can be caught by unit tests; they only surface in real process environments. So — after writing your handlers, don't forget to write a spawnSync end-to-end test.

Note that these four iron rules are language-agnostic — whether you build a stdio server in Node.js, Python, or Go, the same four traps exist: process.exit() / stdout pollution / un-awaited async work / enumerating instead of abstracting. This article uses Node.js only because our project happens to be on the Node stack.

This article is based on a real debugging session from the story-cli project. Repository: story-cli

Flutter Streaming UI: How the Typewriter Experience of AI Replies Is Built

yuelinghuashu — Tue, 18 Aug 2026 12:44:59 +0000

The typewriter effect looks simple: characters appear one by one. But behind "skip animation", "no truncation", and "no performance regression" lies a whole set of engineering decisions.

The implementation in this article is Flutter/Dart based, but the core semantic decisions — "skip ≠ abort" and "buffer and batch" — are framework-agnostic: Web's EventSource, and native/RN SSE clients, face the same choices.

Prologue: a "skip typewriter" button that kept breaking

In an AI narrative app (where the user influences an AI-driven interactive story by entering fate instructions), I built a "⏩ skip typewriter" button — users click it to see the full AI reply immediately instead of waiting for the text to appear character by character.

The button went through three stages in the dev log:

V1: clicking does nothing — the callback fires, but the user experiences no change
V2: clicking truncates the content — the animation is gone, but the reply is incomplete too
Final: clicking reveals the partial text immediately, while the LLM keeps generating the full reply in the background, which appears all at once when done

Behind these three versions lie the three most common pitfalls in "streaming UI". This article breaks them down.

1. From SSE to screen: the streaming rendering pipeline

Why the LLM "pops" text out

The LLM's reply comes back in chunks via HTTP SSE (Server-Sent Events). A typical chunk looks like this:

data: {"choices":[{"delta":{"content":"Mephistopheles appears"}}]}

data: {"choices":[{"delta":{"content":"at the study door."}}]}

data: [DONE]

The interval between chunks is determined by the model's generation speed — tens of milliseconds when fast, possibly a full second when slow. That "character-by-character appearance" is what the user perceives as the typewriter animation.

Why you can't update the UI on every chunk

If you trigger a state update on every chunk, a reply of a few hundred characters can cause dozens or hundreds of UI rebuilds, which visibly lags on longer texts. So you need batching — reading the chunks into a buffer and committing them together:

final _buffer = StringBuffer();
Timer? _timer;

void onChunk(String chunk) {
  _buffer.write(chunk);
  // Batch chunks within a 50ms window; flush once when the window closes
  _timer ??= Timer(const Duration(milliseconds: 50), flush);
}

void flush() {
  _timer?.cancel();
  _timer = null;
  state = state.copyWith(content: _buffer.toString());
}

A 50ms batching window reduces "dozens of notifications" to "one notification per few hundred milliseconds". This number is not arbitrary: the human eye perceives smooth animation at 60fps and above (~16.6ms/frame), but the typewriter's "popping" interval is usually 100-300ms — a 50ms merging window is far smaller than the typewriter's perceptual granularity, has zero visible impact, yet effectively batches high-frequency chunk frames and significantly reduces UI overhead.

StringBuffer: avoiding O(n²) concatenation

If you store the complete content every time and then do state.streamingContent = current + pending, longer replies cause repeated full concatenation — O(n²) complexity.

The right approach is to maintain a StringBuffer accumulator and build the result once via toString():

final _streamingBuffer = StringBuffer();

String applyAndGet(String pending) {
  _streamingBuffer.write(pending);
  return _streamingBuffer.toString(); // O(total length), not O(n²)
}

2. The correct semantics of "skip animation": silent accumulation ≠ aborting generation

This is the most subtle point in the whole streaming experience, and the easiest to get backwards.

V1 mistake: only skipping the UI batching window

My initial implementation was:

void revealStreaming() {
  _revealInstant = true;    // subsequent chunks skip the 50ms batching window
  _flushStreamBuffer();     // immediately commit buffered content
}

After _revealInstant = true, subsequent chunks no longer go through the batching window and are committed straight to the UI. But this doesn't solve the user's problem at all — because the real source of the typewriter effect is the LLM returning chunks one by one, not the UI's 50ms batching window.

The LLM still spends seconds emitting the whole reply. What the user sees: after clicking, text still appears one character at a time. "Skip typewriter" became "skip batching", which is equivalent to doing nothing from the user's perspective.

V2 mistake: triggering the cancel signal

To make "skip" actually effective, I added a cancel signal:

void revealStreaming() {
  _revealInstant = true;
  _flushStreamBuffer();
  cancelGeneration(); // make the LLM stop generating
}

This time it was indeed "immediate" — because the LLM was aborted, the accumulated content was returned as the final reply together with [DONE], and all "content not yet generated" was lost forever.

The user's report: "after clicking skip, the content is truncated, and the rest never shows up."

The problem: I interpreted "skip the animation" as "skip the generation". But the user only wanted "not to watch the animation", not "to stop the AI from finishing its response".

The right answer: silent accumulation, let the LLM finish

The correct semantics of "skip animation" is: stop the UI from updating character by character — the cursor disappears and text no longer pops in one at a time — but the LLM continues generating fully in the background, and when done, the complete reply is written into the message list all at once.

void _appendStreamChunk(String chunk) {
  if (_revealInstant) {
    // Skip typewriter: silently ignore subsequent chunks, no UI rebuilds
    // The complete content is written by ReplySucceeded once finished
  } else {
    _streaming.append(chunk, _applyStreamChunk);
  }
}

After clicking ⏩:

Immediately flush the content received so far into the message bubble (the user instantly sees the existing partial text)
_revealInstant = true, subsequent chunks are silently ignored — the UI no longer updates character by character
The LLM finishes generating in the background; ReplySucceeded carries the complete reply and writes it into the message list all at once

The key distinction, in one sentence:

Stopping character-by-character UI updates ≠ aborting LLM generation

A UX gap worth acknowledging

Silent accumulation brings an extreme scenario: if the model is very slow and the reply is very long, by the time the user clicks ⏩ the LLM may have only generated the first ten characters, with the remaining 2000 queued up — there can be a 10-20 second window with no UI feedback at all between clicking skip and ReplySucceeded. At that point, "cursor gone" is not enough; the user may think the app has frozen.

A product-level solution: in skip mode, show a very subtle "generating in background…" indicator (low visual distraction, but lets the user know the system is still working). This is the balance between "stabilizing immediate experience" and "protecting user patience" — behind every technical decision, there is often an experience decision as well.

A real fallback flaw

Silent accumulation has a risk that must be acknowledged: if the LLM generation fails (network timeout, server 5xx), ReplySucceeded never arrives. At that point you can't be stuck on "loading" forever.

My approach relies on the global fallback of the generation flow:

} catch (e, st) {
  debugPrint('generation failed: $e\n$st');
  _dispatch(const GenerationFailed(narrativeErrorGenFailed)); // reset generation state
} finally {
  endGeneration(); // release re-entry guard, allow next message
}

But this exposes a real UX flaw: GenerationFailed clears streamingContent — the partial content the user saw after clicking ⏩ disappears, leaving only an error message.

This can actually be fixed immediately, not deferred to the next version. Since _revealInstant = true means "silently ignore" subsequent chunks, the fallback on failure should be: if already in skip mode, flush the accumulated buffer first and archive the generated part as an "incomplete reply" before marking the failure:

Note: _flushStreamBuffer() commits the buffered content to the UI (i.e., streamingContent); _streamingContent is the streaming text currently displayed. In the failure fallback, archive this part as an "incomplete reply" first, then set the error.

} catch (e, st) {
  debugPrint('generation failed: $e\n$st');
  if (_revealInstant) {
    // Skip mode: archive the accumulated content as an "incomplete reply"
    // to preserve what the user has seen.
    // _flushStreamBuffer() commits the buffer → _streamingContent is the displayed text
    _flushStreamBuffer();
    final partial = _streamingContent;
    _dispatch(ReplySucceeded(
      reply: partial,
      // keep current state/memories...
    ));
  }
  _dispatch(const GenerationFailed(narrativeErrorGenFailed));
} finally {
  endGeneration();
}

This only touches the failure branch, not the main framework, and achieves "even if generation fails after skip, the content the user already saw is not lost".

3. Data consistency: interrupted streaming never loses content

Mephisto has two "interrupt generation" entry points:

⏹ Stop: the user explicitly wants to interrupt, keeping the generated content
⏩ Skip: the user doesn't want to watch the animation, but wants the LLM to finish

They share the same "cooperative cancellation" signal underneath — when LlmClient receives the cancel signal, it stops reading at the next SSE data line and returns the complete accumulated content:

// Inside LlmClient's SSE loop
await for (final line in response.stream...) {
  if (isCancelled()) break; // cooperative: stop at the next data line
  // ...parse delta, write fullContent, call onChunk
}
return fullContent.toString(); // return accumulated content, not throw

⏹ stopGenerating(): trigger cancel + flush displayed content → generation flow wraps up normally with "accumulated content"
⏩ revealStreaming(): only set _revealInstant, don't trigger cancel → LLM keeps generating, final full commit

Both guarantee no loss of existing data through "return accumulated content after cancel"; the difference is "whether the LLM continues".

Terminology clarification: the "cancel signal" here is the client actively stopping reading the SSE stream (breaking at the next data line), i.e., the client disconnects its reception — the server/model may still be generating in the background and still consuming compute. It is not an "instruct the server to abort" operation; LLM APIs usually don't support client-side cancellation. This matters: when you hit "stop", you simply stop receiving; the server-side cost doesn't end immediately.

4. How to test streaming scenarios

Streaming UI is among the trickiest things to test: timing-sensitive, involves real network IO, and is mixed with buffered batching. Fortunately, in Flutter tests you can use MockClient.streaming + StreamController to control the timing precisely.

Controllable chunked stream

The core idea: use a StreamController to push SSE chunks manually, injecting the "user clicks ⏩" call at any point in time and verifying subsequent behavior.

final controller = StreamController<List<int>>();
final streamingClient = MockClient.streaming((request, bodyStream) async {
  return http.StreamedResponse(
    controller.stream,
    200,
    headers: {'content-type': 'text/event-stream; charset=utf-8'},
  );
});

The three key steps for testing "skip animation without truncation"

// 1. First chunk arrives
controller.add(utf8.encode(sseChunk('Mephistopheles appears at the study door.')));
await Future<void>.delayed(const Duration(milliseconds: 50));

// 2. User clicks ⏩ skip typewriter
notifier.revealStreaming();
expect(state.streamingContent, contains('Mephistopheles appears at the study door'));

// 3. More content keeps arriving (reveal must not abort generation)
controller.add(utf8.encode(sseChunk('He quietly proposes a bargain.')));
controller.add(utf8.encode('data: [DONE]\n\n'));
await controller.close();
// waitForGeneration: polls state.isGenerating until it resets,
// ensuring the async generation flow (including auto-save) fully wraps up before asserting
await waitForGeneration(container);

// Final reply = complete content (not truncated)
expect(state.messages.last.content,
    'Mephistopheles appears at the study door. He quietly proposes a bargain.');

This test verifies three key invariants at once:

After clicking ⏩, the existing content is displayed immediately
After reveal, subsequent chunks are still received (not aborted)
When generation ends, the message list contains the fully concatenated content (not truncated)

If this test had been written first, the "cancel signal causes truncation" bug in V2 would have surfaced in the test immediately — instead of waiting for a user report.

Conclusion

The "smoothness" of streaming UI is not luck; it comes from a clear set of semantic decisions. Three takeaways:

Batching is not animation: the animation comes from the LLM's chunk-by-chunk output; batching is only an optimization to reduce UI rebuilds
Skip is not abort: the semantics of skipping the animation is "stop character-by-character updates", not "stop generation" — let the LLM finish, then fill in everything at once
Interruptions must be testable: use StreamController to simulate a chunked stream controllably, turning the most fragile timing scenario — "interrupting mid-stream" — into a repeatable test

Glossary

Term	Description
SSE (Server-Sent Events)	HTTP long-connection server push protocol, the carrier for LLM token/chunk streaming
Batching (Debounce)	Merging multiple arrivals within a time window into one commit, reducing UI rebuild count
`StringBuffer`	Dart's mutable string accumulator; `toString()` builds once, avoiding O(n²) concatenation
`StreamController`	Dart's controllable stream controller; in tests, push chunks manually to simulate server timing
Cooperative cancellation	The mechanism where the client stops reading the SSE stream: break at the next data line rather than aborting the underlying connection
`MockClient.streaming`	The streaming response mock from `package:http/testing`, used with `StreamedResponse`

Project: Mephisto (MIT License)

Flutter Desktop Input Design — Where Does the Enter Key Actually Go?

yuelinghuashu — Sat, 15 Aug 2026 09:37:15 +0000

From "pressing Enter does nothing" to "the Enter on the arrow-key area still inserts a newline", these desktop input field pitfalls ultimately trace back to a Focus model problem.

Prologue: a bug reported by a user

"After typing in the input field, the first Enter inserts a newline, and only the second one actually submits."

This is an extremely representative problem in Flutter desktop development: mobile input logic cannot be directly transplanted to desktop. On mobile, the "send" button on the soft keyboard naturally triggers onSubmitted; on desktop, there's a physical keyboard where Enter, Shift, and arrow keys are independent visible physical events whose semantics must be defined by the developer.

(Background: this input field comes from an AI-driven interactive narrative app, where the user enters instructions as a "Fate" and the AI unfolds the story. The input field and the streaming reply are the two core interaction entry points of this app, so their details deserve careful polishing.)

My initial approach was very "intuitive": wrap the TextField with an outer Focus and intercept the Enter key inside it. That produced the exact bug at the start of this article — the first Enter became a newline.

1. The real propagation path of keyboard events

Why the intuition is wrong

Most people (including me) write it like this:

Expanded(
  child: Focus(
    onKeyEvent: _handleKeyEvent, // outer Focus intercepts
    child: TextField(
      focusNode: _focusNode,
      maxLines: null, // desktop: multiline
      textInputAction: TextInputAction.newline,
    ),
  ),
)

It looks like onKeyEvent should receive every key press. But in reality, a keyboard event first reaches the node that actually has focus — the EditableText inside the TextField — not the Focus wrapper you put around it.

With maxLines: null + textInputAction: newline, when EditableText receives Enter it:

Inserts a newline internally
Returns KeyEventResult.handled (marking the event as consumed)

Once an event is handled, it no longer bubbles up to the outer Focus. Your _handleKeyEvent never receives the event and obviously can't intercept it. The first Enter becomes a newline; the second one "happens" to submit.

The word "bubbling" naturally makes frontend readers think of JS DOM event bubbling. The two do share a commonality: the event starts at a point, propagates up a chain, and can be stopped midway if consumed. But the details of "propagation path" and "midway stop" are completely different:

	JS DOM events	Flutter keyboard events
What determines the propagation path	DOM tree	Focus Chain
Is visual containment = propagation path?	Yes	No (focus relation ≠ containment relation)
Propagation direction	capture down → target → bubble up	focus node → up the focus chain
Midway stop	`stopPropagation()`	return `KeyEventResult.handled`
Key difference	any DOM ancestor receives the event	inner node can consume early; the event is cut off before bubbling reaches ancestors

In JS, an outer div wrapping an inner input always receives the event — visual containment is the propagation path, so intercepting at the outer layer is natural. But in Flutter, the event travels along the focus chain, not the widget containment tree: the EditableText inside the TextField is the current focus node, and the event starts there and propagates up the focus chain. The outer Focus, as an ancestor of EditableText, is indeed on the focus chain — but the problem is that EditableText returns KeyEventResult.handled when handling Enter, so the event bubble is cut off before it reaches the outer Focus. That's the real reason "wrapping the TextField with an outer Focus fails to intercept Enter": it's not that the node is off the chain, but that the event is already consumed before it arrives.

The correct mounting point

Bind the keyboard event handler directly to the TextField's own FocusNode:

late FocusNode _focusNode;

@override
void initState() {
  super.initState();
  _focusNode = FocusNode(onKeyEvent: _handleKeyEvent);
}

// No outer Focus wrapper needed in build
Expanded(
  child: TextField(
    focusNode: _focusNode,
    // ...
  ),
)

This way _handleKeyEvent runs before EditableText processes the event. Enter (without Shift) returns handled to prevent the newline and send; Shift+Enter returns ignored to let the TextField insert a newline.

Lesson: in Flutter, "wrapping a widget" is not the same as "being able to intercept keyboard events from descendant widgets". If you want to intercept something, mount the listener on the node the event actually passes through.

2. The same "Enter", two key codes

After fixing the "first Enter creates a newline" bug, another user reported: "the Enter on the arrow-key area still inserts a newline."

Same Enter key — why does the letter area work but the arrow-key area doesn't?

Because in Flutter, these two "Enters" are different key codes:

Key	`LogicalKeyboardKey`
Main keyboard Enter	`enter`
Enter above the arrow-key area / on the numpad	`numpadEnter`

And my check was:

if (event.logicalKey == LogicalKeyboardKey.enter) {

numpadEnter doesn't match, so _handleKeyEvent returns ignored for it, the event passes through to the TextField, and a newline is inserted as usual.

The fix is simply to match both key codes:

if (event.logicalKey == LogicalKeyboardKey.enter ||
    event.logicalKey == LogicalKeyboardKey.numpadEnter) {

Lesson: a desktop keyboard is not "one key = one semantic". The same physical action (pressing Enter) can map to different key codes in different areas — especially when matching keys, think about the existence of areas beyond the main keyboard.

3. The Shift+Enter semantics must not be lost

Desktop has a common convention: Enter to send, Shift+Enter for a newline. This is nearly universal in chat apps, terminals, and editors.

The implementation detail is that Shift+Enter should pass through to EditableText rather than constructing a newline yourself:

if (HardwareKeyboard.instance.isShiftPressed) {
  // Shift+Enter → let the TextField insert a newline
  return KeyEventResult.ignored;
}

Why is "passing through" more reliable than "constructing a newline yourself"?

Letting EditableText handle the newline correctly maintains the cursor position, selection, and IME composition state
Pushing \n into the controller yourself can corrupt the cursor context during input method (e.g., Chinese pinyin) composition

The Shift state check uses HardwareKeyboard.instance.isShiftPressed — the global hardware keyboard state query Flutter currently provides. Worth noting: KeyDownEvent itself does not carry modifier state (KeyEvent only has fields like physicalKey / logicalKey / character / timeStamp, no modifiers), so checking Shift must rely on the HardwareKeyboard global singleton.

The global state has a boundary worth noticing: it reflects the hardware state "right now", not "at the instant of that event". In scenarios like rapid successive key presses, or releasing a modifier key right after a dialog steals focus, it could theoretically read a lagged state. Flutter's future KeyEvent API direction is to have events carry a modifiers snapshot (like Web's KeyboardEvent), at which point event-level checks will be more reliable than global state — but in the current Flutter version, HardwareKeyboard.instance.isShiftPressed is the standard, usable approach.

Also worth mentioning: here you neither need nor should build your own "modifier state cache" (manually setting true on KeyDown and false on KeyUp) — because HardwareKeyboard itself is a global state maintained by the Flutter framework: it keeps its state strictly consistent with the event stream through KeyDown/KeyUp events plus a synthesized-event synchronization mechanism. For example, when focus switching causes a Shift release event to be lost, Flutter injects a synthesized event to correct the state. A hand-rolled cache is actually more likely to fail in edge cases like focus switching and synthesized events — that's exactly the complexity the framework handles for you.

4. Input history: Widget lifecycle ≠ data lifecycle

Problem: ↑ / ↓ stops working after leaving and re-entering

After adding the "↑ / ↓ to recall the last 5 inputs" shortcuts on desktop, the first round of testing was fine — send a few messages, press ↑ to recall them one by one. But a user said: "after leaving and re-entering, the ↑ key doesn't work."

The reason is simple:

class _InputBarState extends State<InputBar> {
  final List<String> _history = []; // ← pure memory, cleared when the widget is destroyed
}

The input history lives in State. While playing, InputBar stays alive and history accumulates normally; once you leave the narrative page and InputBar is destroyed and rebuilt, _history is reset to empty.

Widget lifecycle ≠ data lifecycle. State exists for "UI state" (scroll position, current input-box content), not for "user data" (input history that must survive across sessions). Putting persistent data in State is an anti-pattern.

The right approach: state lifting + persistence

Following Riverpod's Notifier pattern, lift the input history to a global Provider and persist it with SharedPreferences:

class InputHistoryNotifier extends Notifier<List<String>> {
  static const int maxHistory = 5;
  static const String key = 'mephisto_input_history';

  @override
  List<String> build() => const [];

  Future<void> push(String text) async {
    if (state.isNotEmpty && state.last == text) return; // adjacent dedup
    final next = [...state, text];
    if (next.length > maxHistory) next.removeAt(0);
    state = next;
    final prefs = await SharedPreferences.getInstance();
    await prefs.setString(key, jsonEncode(next));
  }
}

// An optional initializer: restore from persistence

After changing InputBar from State to ConsumerState:

List<String> get _history => ref.watch(inputHistoryProvider);

Write to the Provider on send, read from the Provider after rebuild — history survives across sessions.

A design decision: global sharing, or per-contract isolation?

A user raised a very reasonable concern: "if I have multiple sub-versions in progress, are all their histories saved? Does it affect performance?"

I ultimately chose a global single list:

Constant storage: one SharedPreferences key, at most 5 short text entries (a few KB), does not grow with the number of sub-version files
Reasonable semantics: different scripts/branches often use similar directional words ("investigate", "ask", "go to"), so global sharing is actually more convenient
Simple to implement: no Map<fileName, List<String>> serialization

Per-sub-version isolation (Map structure) would pose no performance pressure either (each sub-version is just a few KB), but it's more complex to implement for limited benefit. For a personal project, a global single list is the right "good enough and simple" trade-off.

A forward-looking risk: the global single list's write is an async setString; if you ever support multi-window / multi-tab simultaneous editing, there's a theoretical chance of concurrent write clobbering (two windows each push and overwrite each other). The current design fits single-window serial scenarios; if multi-window arrives, writes need debounce merging, or switch to file locks / a database (e.g., sqlite) for atomicity.

And one more extreme-scenario trade-off: SharedPreferences.setString is an async write. If the user closes the app or the system hard-kills the process before the await completes, the last write can be lost. Since input history is "auxiliary convenience" rather than "core asset" (losing it only means the ↑ key recalls one less entry; it doesn't corrupt narrative data), this extremely-low-probability loss is acceptable — hence no double-write or transaction log over-engineering.

5. How to test these interaction boundaries

Keyboard events: simulating the desktop platform

testWidgets runs under FakeAsync by default, and you can use sendKeyEvent to simulate key presses directly. The key is specifying the platform — InputBar._isDesktop is determined by Theme.of(context).platform, and by default it's Android, not desktop:

await tester.pumpWidget(buildInputBar(onSend: sent.add)); // internally sets ThemeData(platform: linux)
await tester.enterText(find.byType(TextField), 'fate instruction');
await tester.sendKeyEvent(LogicalKeyboardKey.enter, platform: 'linux');
await tester.pump();

expect(sent, ['fate instruction']); // submits on the first Enter

The same applies to testing Numpad Enter and ↑ / ↓ recall.

The FakeAsync limitation: real async IO doesn't complete automatically

When a test involves "persist → rebuild → restore", I hit a snag: inside testWidgets' FakeAsync, the SharedPreferences read Future doesn't complete automatically — pumpAndSettle only drives scheduled frames, not pure async IO.

My initial "input history persistence" widget test never passed: write history in the first session → destroy and rebuild → press ↑ and get nothing. I tried runAsync, multi-stage pump, and there was always a timing contradiction between the two.

Conclusion: don't force "persistence round-trip" and "UI recall" into a single widget test. Splitting the tests is more stable:

Provider-level unit test: verify push writes, restore after recreating the container (round-trip), dedup, cap, and JSON-corruption tolerance
Widget-level test: verify ↑ / ↓ recall interaction behavior (on top of an already-mocked persistent Provider)

Each focuses on its own concern, and neither is affected by the FakeAsync-vs-real-IO timing contradiction of the combined test.

The Provider-level test skeleton looks like this — SharedPreferences.setMockInitialValues handles the in-memory mock in one line:

test('round-trip: push then restore after recreating container', () async {
  SharedPreferences.setMockInitialValues({});

  final container1 = ProviderContainer();
  await container1.read(inputHistoryProvider.notifier).push('test history');
  container1.dispose();

  // Recreate the container (simulating an app restart) → AutoLoadNotifier restores from the in-memory mock
  final container2 = ProviderContainer();
  await container2.read(inputHistoryProvider.notifier).load();
  expect(container2.read(inputHistoryProvider), ['test history']);
});

Note: the Provider-level load() is a pure async method that you can await directly in a normal test() without touching testWidgets' FakeAsync — this is the testability dividend of extracting persistence logic out of widgets.

A further architectural direction: abstract persistence behind an interface (e.g., InputHistoryStore), letting the Provider depend on the interface instead of directly on SharedPreferences — tests inject an in-memory implementation, completely escaping the FakeAsync-vs-real-IO timing contradiction. setMockInitialValues is Flutter's built-in lightweight mock, sufficient for the current scenario; interface injection is the upgrade path when you need stricter isolation.

Conclusion

The "boundary sense" of a desktop input field comes from understanding three things:

The propagation path of keyboard events: the interceptor must be mounted on the real focus node (FocusNode), not an outer wrapping widget — events don't bubble after handled
The physical identity of key codes: when matching physical keys (Enter), consider numpadEnter; when modifier state (Shift) isn't carried by the event, query it via HardwareKeyboard global state (and be aware of its "right now, not event-instant" boundary)
The data lifecycle: whether data goes in State or is lifted to a Provider + persistence depends on whether it must survive across Widget lifecycles — and verify with layered tests (round-trip at the Provider layer, UI interaction at the widget layer)

These details almost never appear on mobile — mobile has only one soft keyboard Enter, and no concept of "files whose state must survive leaving and re-entering". But once you build for desktop, "functionally correct" and "experientially correct" diverge into a boundary that demands careful thought.

Glossary

Term	Description
`LogicalKeyboardKey`	Flutter's "logical key" abstraction (after key-position + layout mapping), e.g., `enter` / `numpadEnter`
`PhysicalKeyboardKey`	Physical key position (USB HID code), independent of keyboard layout
`KeyEventResult`	Keyboard event handler result: `handled` (consumed, no longer propagates) / `ignored` (passed through, continues propagating)
Focus Chain	The path along which keyboard events propagate from "focus node → ancestors", unrelated to widget containment
`HardwareKeyboard`	Flutter's maintained global keyboard state (keys / modifiers / lock keys) query entry

Project: Mephisto (MIT License)

Three Attempts to Refactor a Large Flutter State Class — and the Final Solution

yuelinghuashu — Mon, 10 Aug 2026 17:42:22 +0000

A step-by-step record of refactoring an 800-line State class.

What do you do when your State grows beyond maintainability?

1. When Do You Know It's Time to Split?

When a State class grows to several hundred lines, it's usually a sign that it's taken on too many responsibilities.

In a real-world home screen, the 800+ line _HomeScreenState mixed together:

Responsibility	Example Methods
Contract tree actions	Master/subcontract menus, rename, delete confirm
Stage actions	Stage card menu, multi-select, character row actions
Navigation	Navigate to narrative / stage pages
File operations	Import / create new / restore built-in
Pure rendering	Contract tree list, stage dashboard, recent edits

Rule of thumb: If the same class contains more than 3 unrelated concerns, it's time to split.

Line count is a symptom, not the root cause — responsibility mixing is.

2. Attempt 1: Extract Mixins → Blocked by Library-Private Visibility

The most intuitive move: extract methods into Mixins, then with them in.

// home_screen.dart
class _HomeScreenState extends ConsumerState<HomeScreen>
    with HomeContractActions, HomeStageActions { ... }

// home_contract_actions.dart (separate file)
mixin HomeContractActions on ConsumerState<HomeScreen> {
  Future<void> _handleMasterMenu(...) { ... }  // ❌ Not accessible from host!
}

Error:

The method '_handleMasterMenu' isn't defined for the type '_HomeScreenState'

Why?

Dart's _ prefix is library-level private, not class-level private.

In many languages (Java, C++, TS), private means "visible within the class" → mixin members are naturally visible.
In Dart, _ means "visible only within the same library file" — across files, even if mixed into the same class, the host can't see the mixin's private members.

There's a "workaround" that looks plausible at first: declare abstract getters in the mixin and implement them in the host.

mixin HomeStageActions on ConsumerState<HomeScreen> {
  HomeSelectionController get selection; // abstract getter
  void refreshLists();
  Future<void> _handleStageMenu(...) { ... } // ❌ Still private, host can't see it
}

The data bridge works (selection / refreshLists), but method visibility remains broken — _handleStageMenu is still private to a different library.

Clarification: The Problem Isn't Mixins — It's Cross-File

If you define the mixin in the same file, it works perfectly:

// home_screen.dart (same file)
mixin HomeStageActions on ConsumerState<HomeScreen> {
  Future<void> _handleStageMenu(...) { ... } // ✅ Visible, same file
}

class _HomeScreenState extends ConsumerState<HomeScreen>
    with HomeStageActions { ... }

So the intuition "use Mixins to split State" is not wrong. The real hard constraint is: Dart's library-private visibility + files as library boundaries. Once you move methods to another file, _ becomes a hard wall.

📌 Key takeaway: Dart's private isn't "class-private" — it's "library-private".

Across files, _ members are isolated by default; mixins are only safe if they stay in the same file.

3. Attempt 2: Use `part` → Blocked by Missing `this`

If _ is library-private, then using part to split one library across multiple files should let private members be shared — right?

// home_screen.dart
part 'home_screen_contract.dart';
part 'home_screen_stage.dart';

// home_screen_contract.dart
part of 'home_screen.dart';

Future<void> _handleMasterMenu(...) { ... } // ✅ Private now visible

part of does make private members visible (I can see _selection / _refreshLists), but a new problem appears:

Top-level functions have no this context.

Code inside part of is library-level top-level functions, not methods of the host class. So:

part of 'home_screen.dart';

Future<void> editContract(ContractInfo info) {
  return editContractFile(
    context,          // ❌ Undefined name 'context'
    onRefreshLists: _refreshLists, // ❌ Undefined name '_refreshLists'
  );
}

context, ref, mounted, _selection are all instance members of _HomeScreenState. Top-level functions can't access them.

So When Is `part` Actually the Right Tool?

The project already had a successful precedent — freezed-generated code:

// narrative_state.dart
import 'package:freezed_annotation/freezed_annotation.dart';
part 'narrative_state.freezed.dart'; // ✅ Pure generated code, no this dependency

narrative_state.freezed.dart is generated by the freezed tool, depending only on the @freezed annotated _NarrativeState class. It doesn't need to access any host instance members. That kind of "pure declaration + generated implementation" split is what part is actually for.

📌 Key takeaway: part shares library-private visibility, not host instance context.

If your goal is to split methods that need to access this, part is not the answer.

4. Final Solution: Widget Composition — Back to the Framework Philosophy (and a Reasonable Boundary)

After two detours, the answer was the classic Flutter Composition model all along:

Extract rendering into independent Widgets, and inject interactions via callbacks.

Core Principle

What	Where It Belongs	Why
Interaction orchestration depending on `ref` / `context` / `mounted`	Stay in State	These are State's lifecycle capabilities
Read-only view building	Extract to standalone `ConsumerWidget`	Pure functional rendering — independently maintainable and testable

Implementation

Extract the "contract tree + stage dashboard + recent edits" rendering block into ContractTreeSection:

class ContractTreeSection extends ConsumerWidget {
  final List<ContractGroup> groups;
  final HomeSelectionController selection;

  // ---- All interactions injected via callbacks ----
  final void Function(BuildContext, ContractGroup) onMasterTap;
  final void Function(ContractInfo child, String action) onChildMenu;
  final void Function(String stagePath) onStageTap;
  // ...

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    // Pure rendering only: ListView + ContractCard + StageSection ...
  }
}

The host _HomeScreenState is left with just assembly + delegation:

return ContractTreeSection(
  groups: groups,
  selection: _selection,
  onMasterTap: _onMasterTap,
  onChildMenu: (child, action) => _handleChildMenu(context, child, action),
  onStageTap: _openStageNarrative,
  // ...
);

Results (split ≠ deleting code; it's about rehoming responsibilities):

File	Before	After	Responsibility
`home_screen.dart`	816	640	Interaction orchestration (assembly + navigation + delegation)
`contract_tree_section.dart`	—	263	Contract tree + stage dashboard + recent edits (pure rendering)
`stage_card.dart`	806	529	Pure presentation `StageCard`
`stage_section.dart`	—	192	Stage list area
`stage_card_with_meta.dart`	—	92	Stage data loading glue layer

Total code volume stayed the same, but each file's responsibility went from "mixed" to "single." Pure presentation components (StageCard / ContractTreeSection) can now be tested independently without a State.

stage_card_with_meta.dart is the thin glue between "data loading" and "pure rendering": it reads stage data (character list, save detection, recent activity) from Riverpod and passes it unchanged to the pure StageCard — keeping StageCard itself Riverpod-free and easier to test.

Why This Is "The Flutter Way"

Flutter's composition model is inherently about "a Widget renders, callbacks go upward":

Button.onPressed, TextField.onChanged, ListView.builder — all examples of callback-based decoupling.
The project already did this with ContractCard / StageSection — this time we just applied the same pattern to a whole page-level rendering block.
It also reduces rebuild scope: extracting into a standalone ConsumerWidget means unrelated field changes in the State won't reach this subtree — Flutter's Element reuse + subtree isolation prevents unnecessary repaints of ContractTreeSection.

Mixins are for behavior reuse (e.g., GenerationCoordinator). Using them to reorganize State is simply a misapplication.

💡 TIPS: Should the String action be replaced with enum?
A String for action might trigger type-safety instincts. But for PopupMenu scenarios, this is a pragmatic trade-off: PopupMenuItem<String> works natively with String payloads, menu_actions.dart shared constants already provide compile-time guardrails, and menu actions are an evolving set (each new action with an enum would require modifying the enum definition + updating every switch).
Bottom line: If the action set is closed and stable (like MessageRole), enum exhaustiveness is worth it. Otherwise, String + shared constants fits the PopupMenu ecosystem better.

Why We Stopped Here (and Didn't Extract a Coordinator)

Extracting interaction orchestration to a Riverpod Notifier coordinator is a common advanced suggestion — but we evaluated it and decided not to:

The remaining navigation / dialog / menu dispatch in the State is inherently UI work — Navigator.push, ScaffoldMessenger, and confirmation dialogs all need BuildContext. Moving them to a Notifier just shifts the shell without reducing parameters.
These logic blocks were already extracted to top-level functions (home_operations.dart / home_menu_actions.dart). What's left in the State is clean one-line delegations.
Adding a coordinator would introduce ref.read(coordinator.notifier).xxx() + context.mounted boilerplate — extra indirection that increases cognitive load without real gain.

So 640 lines isn't "unfinished" — it's a reasonable stopping point after achieving single responsibility. Maintainability is about "every method clearly shows what it does," not line count.

📌 Key takeaway: When you hit language-mechanism limits, don't hack around them with dynamic or workarounds.

Revisit the architecture from a framework-idiomatic angle — that's usually the real answer. Knowing when to stop is also part of architectural judgment.

5. Decision Tree: Which Approach to Choose

State class too large?
│
├─ Refactoring for behavior reuse? (e.g., streaming throttling, generation coordination)
│    └─ ✅ Use Mixin (define in the same file to avoid library-private issues)
│
├─ Splitting pure data / generated code? (e.g., freezed .g.dart)
│    └─ ✅ Use part / part of
│
└─ Splitting State methods that need `this`?
     ├─ Pure rendering parts → ✅ Extract as standalone Widget + callback injection
     └─ Interaction orchestration parts → ✅ Keep in State

Approach	Best For	Key Limitation
Mixin	Behavior reuse (no cross-file)	`_` is library-private; invisible across files
part	Generated code / pure	Shares private visibility but no `this` context
Standalone Widget + Callbacks	Rendering ↔ Interaction decoupling	Requires explicit parameter passing (callbacks)

6. Engineering Safeguards for Landing the Refactor

Refactoring is where things break most easily, so pure moves + pure parameter extraction = zero behavioral change is the baseline:

Keep behavior identical: Only move method bodies and rewrite call sites — no logic changes.
Static analysis as gatekeeper: flutter analyze must return No issues found!
Full test suite: 406 tests all green before calling it done.
Small commits: Split one concern at a time, validate independently — avoid "big bang" refactoring.

Summary

Dart's _ is library-private, not class-private → Mixins fail across files.
part shares private visibility but has no this → not suitable for splitting State methods.
Extract standalone Widget + inject callbacks is the Flutter-idiomatic way to refactor oversized State classes.
Decoupling rendering from interaction aligns with the framework philosophy and enables independent maintenance and testing.

Project: Mephisto

LLM Narrative Engines, Part 6: Runtime Loop and Branching

yuelinghuashu — Wed, 05 Aug 2026 10:45:53 +0000

Before reading this: This is the final post in the series. I'd recommend reading the previous five — Part 1 covers the .meph format, Part 2 walks through a hands-on tutorial, Parts 3 and 4 explain how the parser outputs a domain.Contract, and Part 5 covers testing. This post assumes you already know the engine has a contract struct. The core problem we're solving: how do we drive it?

I. A Narrative Engine's Fifth Problem: How Do You Bring Rules to Life?

The parser turns contracts into structs, but structs don't tell stories. A narrative engine also needs a runtime — a complete loop of input → matching → execution → output.

Three engineering problems need solving:

How do rules match in real time? When user input arrives, the engine needs to iterate over all rules, evaluate conditions, and decide which actions to trigger — all in milliseconds, without affecting user experience.
How does the LLM follow rules? Rules can't directly constrain the LLM — they must take effect indirectly through prompts. Translating rules into a format the LLM understands is the core challenge here.
How do state and memory persist? Every turn changes the character's state and memory pool. But when the next turn starts, the engine must restore the complete state from the previous turn. Without persistence, there's no long-form narrative.

This post solves all three. Parts 4 and 5 already covered rule-matching details (two-phase matching, dice evaluation) — I won't rehash them here. Instead, I'll focus on how the runtime wires the entire pipeline together.

Once the engine has a contract, it enters a loop: receive user input → match rules → execute actions → call LLM → return response. That loop is the runtime.

But before implementing the loop, several engineering problems must be solved first — they determine whether the engine is "functional" or "usable."

II. Novel-Grade Terminal Output: Full-Width Indentation and Streaming Interception

LLM streaming output comes back in chunks. The engine intercepts each chunk via an onChunk callback and writes it directly to the terminal.

One design detail: full-width indentation (　　).

onChunk := func(chunk string) {
    for _, ch := range chunk {
        if ch == '\n' {
            fmt.Println()
            needIndent = true
            inParagraph = false
        } else {
            if !inParagraph && needIndent {
                fmt.Print("　　")  // two full-width spaces at the start of each paragraph
                needIndent = false
            }
            fmt.Print(string(ch))
            inParagraph = true
        }
    }
}

The effect: each paragraph in the terminal output starts with two full-width spaces, making it look like a printed book. This small detail dramatically improves the creator's experience — it turns "terminal output" into "novel pages."

But behind streaming output is a more critical engineering decision: the action executor handles all streaming callbacks uniformly.

State-modification actions: return results immediately, then simulate character-by-character output via callback
LLM actions: true streaming output, chunk by chunk
Static text: return immediately, then simulate streaming output

Every action ultimately outputs through onChunk, regardless of its source. This ensures a consistent terminal experience.

III. Five-Layer Sandwich Prompt: Welding Constraints at Both Ends

The biggest problem with LLM narrative is format drift — it often outputs stage-direction script format:

( smirks ) [Belial]: You're all too weak.

This breaks immersion. The solution: place format constraints at both the top and bottom of the prompt, forming a sandwich structure. In v1.1.0, the actual prompt rendering (RenderPrompt in internal/core/llm/prompt.go) has five layers:

【格式硬性要求】
(NarrativeConstraints — no parentheses, no script markers, no soliloquies)

【世界观】
(context)

【角色】
You are {角色名}, a being with {锚点风格}. Your background: {角色背景}

【当前状态】
(rendered from the runtime `map[string]any`)

【命运的推动】
(conversation history — alternating fate and assistant records)

【你记得的过往】
(dynamically accumulated memories from the runtime)

【此刻】
(user_input)

【要求】
(NarrativeConstraints, emphasized again)

Constraints appear twice, at both ends, with the context sandwiched in between. Two reasons for this:

Primacy effect: the LLM sees the constraints first — they get the highest priority
Recency effect: the constraints the LLM sees last influence the final output

Double emphasis ensures the format constraints aren't diluted by the context in the middle.

3.1 Deterministic Rendering: Sorting Guarantees Cache Hits

There's a subtle engineering problem here: Go's map iteration order is random.

At runtime, 【状态】 from the contract is converted to a map[string]any for fast read/write. When rendering 【当前状态】 in the prompt, if the iteration order changes each time, the generated prompt text changes — even if the state content is identical. This causes the LLM's KV Cache to completely miss, forcing recomputation every time.

The solution: sort the keys of state (sort.Strings) to ensure stable rendering order. When the state doesn't change, the generated prompt text is byte-for-byte identical, allowing the LLM service's KV Cache to hit, reducing latency and token consumption.

3.2 Anti-Soliloquy Constraint

NarrativeConstraints has one deliberately emphasized rule:

Each response must include dialogue and action from at least one other character (non-player). If no other characters are present in the scene, introduce or create at least one interactive object. Prohibit purely player-only soliloquies.

This solves the "empty world" problem in narrative. If the LLM only responds to player input without introducing other characters, the story becomes a monologue and loses dramatic tension. This constraint forces the LLM to introduce at least one interactive object in every response, making the world feel alive.

IV. Mother-Child Save Mechanism

After every turn, the engine automatically saves the current state to a child file.

Naming convention (v1.1.0 onward, aligned with the Flutter version, dot-separated):

Master story.meph → default child story.child.meph
Branch --branch dark → story.dark.meph

func BuildChildPath(filename string, branch string) string {
    dir := filepath.Dir(filename)
    base := filepath.Base(filename)
    ext := filepath.Ext(base)
    name := strings.TrimSuffix(base, ext)

    // Already a child file: overwrite directly (prevent nested generation)
    if isChildFileName(name) {
        return filename
    }

    if branch != "" {
        return filepath.Join(dir, name+"."+branch+ext)
    }
    return filepath.Join(dir, name+childSuffix+ext) // childSuffix = ".child"
}

isChildFileName precisely identifies existing child files: xxx.child (default child) or xxx.branchName (branch names starting with letters). This means my_story_1.meph (with a numeric suffix) won't be misidentified as a child.

A child file is a complete .meph contract, containing:

All static blocks from the master (character name, worldview, character background, opening scene, anchors, rules)
Updated 【状态】
Accumulated 【记忆】
Recent 【历史】

This means one static contract can evolve into any number of dynamic children:

story.meph (master, read-only)
    ├── story.child.meph (main timeline)
    ├── story.dark.meph (dark branch)
    ├── story.light.meph (light branch)
    └── story.experimental.meph (experimental branch)

Each branch evolves independently, without interfering with the others. The project includes data/dantes.meph alongside an already-run data/dantes.child.meph save.

Save timing: instead of writing to disk every turn (which would be inefficient), it's split into two layers:

After each turn: the Session layer (cmd/mephisto/session.go) calls engine.Save() to persist progress in real time
On exit: a defer saves one more time, ensuring the final state is written before exit

Rule freshness during save: Save() has a clever design — before saving, it reads the child file from disk (if it exists) and uses the 【规则】 block from disk as the latest rules. This means the user's real-time edits to the rules section in their editor won't be overwritten by the auto-save. This also supports rule hot-reload introduced in v1.0.3: session.go watches the child file for changes via fsnotify, with a 500ms debounce, then calls ReloadContract to re-parse — replacing only the rules while preserving state and history. This makes "edit rules → save → instantly effective" a reality.

Loading:

Default: load the child if it exists
--reset: ignore the child, start fresh from the master
--branch dark: load the corresponding branch file

Note: Running a child file directly will overwrite it — the engine treats any .meph file as a master and generates a corresponding child. To avoid losing progress, don't run run directly on child files.

The value of this design: creators can fork storylines at critical moments, exploring different directions without losing any progress.

V. Memory Extraction: Synchronous Weaving After Streaming

Memory extraction is critical for long-form narrative — it extracts key events from conversation history, compresses them for long-term storage, and injects them into the LLM context every turn.

But extraction calls the LLM, which takes seconds. If executed before streaming output, users would wait several seconds every 5 turns before seeing the first character.

The solution is simple: output first, extract later.

Here's the flow for each turn:

User input
    │
    ▼
Rule matching + action execution + LLM streaming output (user sees text appear character by character)
    │
    ▼
Streaming completes, user finishes reading the response
    │
    ▼
Engine.Run synchronously executes memory extraction (still inside Run, user has finished reading)
    │
    ▼
Return to Session — Session calls Save to auto-save the child
    │
    ▼
Show input prompt, wait for next turn

Note the difference from the old version: memory extraction runs synchronously inside engine.Run(), while child saving is handled by the Session layer after each Run returns. The two are decoupled — the engine handles narrative and memory, while Session handles persistence.

// internal/core/engine/engine.go

func (e *Engine) Run(input string, onChunk func(string)) (string, error) {
    // ... rule matching, LLM call, streaming output ...

    // 4. Record the assistant's response
    runtime.AddHistory("assistant", response)

    // 5. Memory extraction (every N turns, synchronous)
    e.processMemories()   // ← user has finished reading the response by now

    return response, nil
}

processMemories() internal flow:

Extraction interval check: ShouldExtract — triggers when turn_count % 5 == 0 (ExtractInterval = 5)
Call LLM for extraction: takes the most recent 10 turns (ExtractWindow = 10), generates key-event summaries (each no more than 20 words)
Semantic deduplication: shared.DeduplicateMemories uses keyword Jaccard similarity for deduplication — semantically similar memories with different wording are automatically merged. For example: "Faust meets Mephistopheles in his study" and "Mephistopheles visits Faust's study late at night" — both memories share keywords like Faust, Mephistopheles, and study, so they're judged to describe the same event and merged into one
Append + compress: when the count exceeds the limit (MaxLimit = 30), auto-compress — keep the most recent 5 entries plus 3-5 summary entries

Why this design?

User-unaware: streaming is already complete, the user is reading or thinking about the response. Memory extraction happens silently in the background — the user doesn't "wait"
Simple logic: synchronous calls are easier to control than async goroutines — no race conditions, no "memory isn't written yet when saving"

If extraction fails, it only logs silently (the extraction function returns an error and skips it). The conversation continues — just without saving memories for that turn.

VI. The Complete Loop

Putting it all together, here's how each turn of the engine runs:

User input
    │
    ▼
Rule matching
    │   ├── Passive rules (state modification + memory injection): batch execution, multiple can trigger
    │   └── Active rules (LLM instruction / static text): mutually exclusive, only the first match triggers
    │
    ▼
Execute action → LLM call (60-second timeout protection, falls back to ⚠️ static response on failure)
    │                        ↑—— timeout only protects the LLM call phase
    ▼
Streaming output (full-width indentation + chunk-by-chunk callbacks)
    │
    ▼
Record assistant history → (sync) memory extraction (every 5 turns, no streaming wait)
    │
    ▼
Session layer calls Save → auto-save to child file (story.child.meph)
    │
    ▼
Rule hot-reload listener (background async fsnotify, doesn't block main loop)
    │
    ▼
Wait for next input

A few runtime robustness details worth calling out:

LLM timeout fallback: the entire LLM call is wrapped in a 60-second timeout context (context.WithTimeout). On timeout or failure, the engine outputs (⚠️ LLM call failed: request timeout, fallback to static response) via onChunk, then returns a default static text. Telling the user "LLM is down" is better than making them guess "the character went silent" — the former is a diagnosable engineering issue, the latter might be misinterpreted as narrative design.
Debugging and quiet mode: debug output (--debug) goes to os.Stderr, while normal output (--quiet) doesn't interfere. Both can be enabled simultaneously.

This is Mephisto's runtime.

VII. Costs and Limitations

This system doesn't come without cost:

1. Memory extraction depends on LLM quality

If the main model is in poor state, extracted summaries may drift — even altering key facts (e.g., writing "banished" instead of "defeated"). This is a "hallucination" risk.

Two layers of mitigation:

Prompt protection: extraction and compression prompts explicitly forbid modifying core character settings (name, anchor content, state values, etc.). This works reliably on DeepSeek and GPT-4.
Model selection advice: for 7B local models, summary quality drops significantly. If you must use a lightweight model, consider disabling automatic memory extraction (ExtractInterval = 0) and managing memories manually.

Future enhancement: post-extraction validation — after extraction results return, the engine checks for conflicts with core settings. If a conflict is found, discard that memory entry.

2. Branch switching requires manual management

Child files are stored independently. Switching branches requires the user to explicitly specify --branch. Unlike real version control with diff and merge, branches don't auto-sync.

3. Streaming output occupies the terminal

Full-width indentation and streaming look great in the terminal, but if the user wants to copy-paste text, the indentation and newlines come along — sometimes interfering.

VIII. Summary

Six posts complete a full path:

Post	Problem Solved	Core Output
1	What format to write rules in?	`.meph` format design
2	What to run first?	Write a Faust contract from scratch and run it
3	How to parse precisely with good errors?	Block scanner + Parser
4	How to parse rules and variables?	Rule expressions + interpolation syntax
5	How to ensure changes don't break things?	Golden file testing
6	How to bring a contract to life?	Five-layer prompt + branching + memory extraction

Together, they form a complete long-form narrative engine:

Contract (.meph)
    │
    ▼
Parser (Posts 3 & 4) ──→ Contract
    │
    ▼
Engine (Post 6) ──→ Rule matching + LLM streaming narrative + memory extraction
    │
    ▼
Child save (story.child.meph) ──→ Long-term continuity + multiple branches

Quick Reference: Complete Flow

.meph contract file
    │
    ▼ Scanner (line number binding)
    │
    ▼ Block list []Block
    │
    ▼ Parser (routing by block title)
    │
    ▼ domain.Contract
    │   ├─ RoleName
    │   ├─ Anchor
    │   ├─ State
    │   ├─ Worldview
    │   └─ Rules (conditions stored as-is, evaluated at runtime)
    │
    ▼ Engine
    │   ├─ Five-layer sandwich prompt (top constraints → worldview → character → state/history/memory → bottom constraints)
    │   ├─ Rule matching (passive batch + active mutex)
    │   ├─ Action execution (inject / state modify / LLM call / static text)
    │   ├─ Streaming output (full-width indentation)
    │   ├─ Memory extraction (every 5 turns, synchronous, semantic deduplication)
    │   ├─ LLM timeout fallback (60s, ⚠️ message + static response)
    │   └─ Child save (story.child.meph, dot-separated naming)
    │
    ▼ Engine loop
        User input → rule matching → execute action → LLM streaming narrative
        → memory extraction → Session auto-save → hot-reload listener → wait for next input

For quick reference on where to find specific content:

Flow Node	Corresponding Post	Key Concepts
`.meph` format	Post 1	Block titles, rule syntax
Hands-on	Post 2	Write a contract from scratch, no-LLM mode
Scanner	Post 3	Line number binding, whitelist-first
Parser	Post 4	Rule decomposition, interpolation syntax
Testing	Post 5	Golden file, error-scenario tests
Engine runtime	Post 6	Five-layer prompt, branching, memory extraction

GitHub: https://github.com/yuelinghuashu/mephisto

LLM Narrative Engines, Part 5: Integration Testing and Behavior Freezing

yuelinghuashu — Sun, 02 Aug 2026 06:16:48 +0000

Before reading this: I'd recommend skimming Part 3's "Parser" section and Part 4's summary to understand how the parser outputs a domain.Contract. This post assumes you already know the parser can turn .meph into a struct.

I. A Narrative Engine's Fourth Problem: How Do You Keep Behavior Stable?

The parser is written. But it's code that gets maintained long-term — requirements change, formats expand, bugs get fixed. Every change risks breaking existing behavior.

The tension here is: creators depend on stable behavior, while developers depend on freedom to change. If every code change requires manually testing every known scenario, the developer will fear refactoring. If you don't test, broken behavior reaches the creator — but the creator doesn't care that you refactored the parser.

The solution is to "freeze" parsing behavior: use a fixed set of contracts as watchdogs. After every change, automatically compare parse results against expectations.

This is what integration tests do: take a fixed set of .meph contracts as "watchdogs," run them after every change, and verify that behavior hasn't been accidentally altered.

II. Golden File Testing: Freezing Parse Results

The most straightforward approach: prepare a standard contract, parse it, serialize the result to JSON, and save it. On every subsequent test run, compare the current parse result against that JSON file.

The project's testdata/sample.meph is that standard contract. Here's the test flow:

func TestParseSample(t *testing.T) {
    got, err := ParseFile("testdata/sample.meph")
    if err != nil {
        t.Fatalf("parse failed: %v", err)
    }

    goldenPath := "testdata/sample.golden"
    var want domain.Contract

    if err := loadGolden(goldenPath, &want); err != nil {
        // Golden file doesn't exist — generate it automatically
        saveGolden(goldenPath, got)
        t.Log("Golden file generated. Please review and re-run the test.")
        t.FailNow()
    }

    // Compare got and want
    if diff := cmp.Diff(want, got); diff != "" {
        t.Errorf("Parse result doesn't match expected:\n%s", diff)
        t.Log("💡 If this change is intentional, run: go test -update")
    }
}

On first run, sample.golden is auto-generated. Every subsequent run compares against it, reporting differences. If the change is intended (e.g., a new field was added), running go test -update refreshes the Golden file.

The core value of this mechanism: the parser's behavior is "frozen." Any change must pass test validation — it can't silently alter parse results.

III. Parse-Time Validation

Parsing isn't just "reading text in" — it validates required fields during the parse itself.

If the character name is empty, parseRoleName errors out immediately:

Line X: character name cannot be empty

If a rule name, condition, or action is empty, parseRuleLine errors out with the line number.

If parsing fails, the struct doesn't exist. There's no state where "parsing succeeded but content is invalid" — this is another advantage of the hand-written parser over JSON/YAML. JSON parsers don't validate semantic completeness — they only validate structural correctness.

IV. Sliding-Window Aging Tests: Correct History Truncation

The engine has a critical behavior: history can't grow indefinitely. It must auto-truncate, keeping only the most recent N turns.

This test verifies that behavior:

func TestIntegrationHistoryLimit(t *testing.T) {
    contract, err := parser.ParseFile("../parser/testdata/sample.meph")
    if err != nil {
        t.Fatalf("parse failed: %v", err)
    }
    // Set max history to 2 turns
    eng := engine.New(contract, engine.WithMaxHistory(2))

    // Run 5 turns
    for range 5 {
        eng.Run("Hello", nil)
    }

    history := eng.History()
    // 5 turns produce 10 records, but capacity is only 4 (2 turns * 2 records/turn)
    if len(history) != 4 {
        t.Errorf("history length = %d, want 4", len(history))
    }
}

This test ensures history truncation is "whole-turn" rather than "per-record." If truncation were per-record, you could end up with only the "fate" input and no "assistant" response — half a turn of data, leading to incomplete context in the 【命运的推动】 prompt block.

Whole-turn truncation preserves history integrity — either a full turn (fate + assistant) is retained, or it's discarded entirely.

V. Error Scenario Testing: Ensuring Precise Error Messages

Beyond the "happy path," integration tests cover the error path — ensuring all kinds of malformed input produce correct errors, with line numbers and block names included:

func TestParseErrors(t *testing.T) {
    tests := []struct {
        name    string
        input   string
        wantErr string // substring the error should contain
    }{
        {
            name:    "content outside any block",
            input:   "content outside any block\n【角色名】\nBelial",
            wantErr: "content appears outside any block",
        },
        {
            name:    "list item missing - prefix",
            input:   "【锚点】\n核心信念: power",
            wantErr: "list item must start with '-'",
        },
        {
            name:    "list item missing colon",
            input:   "【锚点】\n- 核心信念 \"power\"",
            wantErr: "missing ':' or '：'",
        },
        // ...
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            _, err := ParseString(tt.input)
            if err == nil || !strings.Contains(err.Error(), tt.wantErr) {
                t.Errorf("expected error containing '%s', got: %v", tt.wantErr, err)
            }
        })
    }
}

These tests ensure error messages never degrade to unexpected token at position 42 — the kind of error we set out to eliminate in Part 1.

VI. The Cost

Golden files need manual review on first generation or update (checking that the content is correct)
Error-scenario tests need to cover as many edge cases as possible
Each new block type requires updating test cases

But the payoff is: you can refactor fearlessly. As long as all tests pass, behavior hasn't changed.

VII. Summary

Integration tests are the project's "watchdogs." They freeze the parser's behavior, and every change must pass their validation.

Four things make up this test suite:

Golden file tests: freeze the parse results of a standard contract
Parse-time validation: check required fields and completeness during parsing
Sliding-window aging tests: ensure history is truncated by whole turns
Error-scenario tests: guarantee error messages are precise down to the line number

With this system in place, the engine can evolve confidently — no fear of breaking things, because the tests will catch it.

Next, we enter the engine's runtime. The core problem: once you have a domain.Contract, how do you drive the LLM to generate narrative that follows the rules?

The answer is the sandwich prompt structure — putting format constraints at both the top and bottom, with context in the middle — to completely eliminate parenthetical stage-direction drivel.

GitHub: https://github.com/yuelinghuashu/mephisto

LLM Narrative Engines, Part 4: Parsing Rules and Interpolation

yuelinghuashu — Wed, 29 Jul 2026 03:48:48 +0000

Before reading this: I'd recommend skimming Part 3's "Two-Phase Design" and "Block Scanner" sections to understand how the scanner outputs []Block. This post assumes you already know how the parser routes blocks to different parse functions based on their Title.

I. A Narrative Engine's Third Problem: How Do You Parse Condition-Action Rules?

Once the blocks are split, the most complex part is rule expressions. A narrative engine needs to answer: how are conditions written, how are actions written, and how are variables referenced?

There's an important design boundary here: the parser only parses, it doesn't evaluate. Condition strings like 包含 "攻击" && 状态.堕落指数 > 80 are stored as-is in the struct. The engine evaluates them at runtime. Why? Because the runtime state needed for evaluation doesn't exist at parse time — state values change dynamically during conversation and can't be determined at load time.

This post is about the parsing logic itself.

II. Rule Parsing: Splitting Conditions and Actions

The rule format is fixed: [name] if condition -> action

[攻击] if 包含 "攻击" -> 注入 "贝利亚发动了猛烈的攻击"
[光之国] if 包含 "光之国" && 状态.情绪 == "暴怒" -> 注入 "光之国的记忆让贝利亚更加愤怒"
[高堕落] if 状态.堕落指数 > 80 -> 状态.情绪 = "癫狂"

Interpolation syntax appears in rule actions and text blocks:

注入 "{角色名}的故乡是光之国"

This post tackles two problems:

How do we parse rule conditions and actions into storable structures?
How is interpolation syntax recognized and handled at the parsing layer?

2.1 Rule Name Extraction

Find the first [ and the first ], extract what's between them:

func parseRuleLine(line string, lineNumber int) (*domain.Rule, error) {
    trimmed := strings.TrimSpace(line)
    if !strings.HasPrefix(trimmed, "[") {
        return nil, fmt.Errorf("规则必须以 '[' 开头")
    }
    idx := strings.Index(trimmed, "]")
    if idx == -1 {
        return nil, fmt.Errorf("缺少闭合的 ']'")
    }
    name := strings.TrimSpace(trimmed[1:idx])
    if name == "" {
        return nil, fmt.Errorf("规则名不能为空")
    }

    rest := strings.TrimSpace(trimmed[idx+1:])
    // Extract condition and action next...
}

Note: The error messages in the Go code above are shown in Chinese — they're the actual output from the engine's parser.

2.2 Splitting Condition and Action

Use if and -> as delimiters:

// Remove the "if " prefix
if !strings.HasPrefix(rest, "if ") {
    return nil, fmt.Errorf("规则条件必须以 'if ' 开头")
}
rest = strings.TrimPrefix(rest, "if")
rest = strings.TrimSpace(rest)

// Use the first "->" to split condition and action
cond, action, ok := strings.Cut(rest, "->")
if !ok {
    return nil, fmt.Errorf("规则缺少 '->'")
}
cond = strings.TrimSpace(cond)
action = strings.TrimSpace(action)

2.3 Mutex Groups

Actions may contain a [group:xxx] marker:

[攻击] if 包含 "攻击" -> [group:combat] 注入 "贝利亚发动了猛烈的攻击"

When parsing, we extract the group name and store it in domain.Rule.Group:

group := ""
if strings.HasPrefix(action, "[group:") {
    endIdx := strings.Index(action, "]")
    if endIdx != -1 {
        group = action[7:endIdx]
        action = strings.TrimSpace(action[endIdx+1:])
    }
}

Mutex groups ensure that within the same group, only the first matching rule is triggered. This logic takes effect at runtime; the parser just stores the group name.

Mutex groups can be used with any action type, not just 注入:

[高堕落] if 状态.堕落指数 > 80 -> [group:escalate] 状态.情绪 = "癫狂"
[失控] if 状态.情绪 == "癫狂" && 状态.堕落指数 > 90 -> [group:escalate] 注入 "{角色名}已完全失控"

2.4 Quote Handling

Strings in conditions and actions are wrapped in ". During parsing, I call unquote to strip the outer quotes:

func unquote(s string) (string, error) {
    s = strings.TrimSpace(s)
    if len(s) >= 2 {
        if (strings.HasPrefix(s, "\"") && strings.HasSuffix(s, "\"")) ||
           (strings.HasPrefix(s, "“") && strings.HasSuffix(s, "”")) {
            return s[1:len(s)-1], nil
        }
    }
    return s, nil
}

Chinese quotes are supported because creators may use Chinese input methods — “ and ” are more natural to type than ".

III. Interpolation Syntax: Recognizing and Replacing `{variable}`

The core requirement for interpolation: recognize {角色名} in any text and replace it with the corresponding character name. Currently, only one interpolation variable is supported — {角色名}, which comes from the 【角色名】 block and is statically defined.

3.1 Why Only `{角色名}`?

You might wonder: why can't state variables like corruption index or emotion be interpolated directly with {堕落指数}?

Because state variables are read and written dynamically at runtime — creators modify them via 状态.键 = 值 and compare them via 状态.键 > 值. Allowing {堕落指数} interpolation would introduce a parallel mechanism: the same variable could be referenced both via 状态.堕落指数 and {堕落指数}. Two syntaxes for the same thing, increasing the learning curve.

So state variables are uniformly referenced using the 状态.键 syntax, with no interpolation. The engine's template substitution does one thing only: replace {角色名} with the actual character name.

3.2 Substitution Timing: Three Scenarios

Interpolation substitution happens in three different scenarios:

CLI welcome screen display: Worldview and opening scenes are substituted once when displayed to the user. The creator sees "贝利亚奥特曼" instead of {角色名}.
Rule action execution: 注入 "{角色名}的故乡是光之国" is substituted every time the rule triggers. This is the most common usage of interpolation.
Prompt construction: Worldview and background text are passed to the LLM as-is, without engine-side substitution. The LLM naturally understands {角色名} from context (e.g., "You are 贝利亚奥特曼").

Why not substitute in scenario 3?

Because substitution changes the raw form of the text. If we replace {角色名}的故乡是光之国 with 贝利亚奥特曼的故乡是光之国, the LLM receives a "hardened" narrative. Keeping {角色名} as-is lets the LLM dynamically decide how to use the name during generation — in some narrative branches, the character name might change (e.g., the character is renamed or forgotten), and keeping the placeholder is actually more flexible.

IV. The Intersection: When Rules Meet Interpolation

Take this rule as an example:

[光之国] if 包含 "光之国" -> 注入 "{角色名}的故乡是光之国"

Full execution flow:

User input: "I'm going to the Land of Light!"
    │
    ▼
Rule matching: contains "光之国" → true
    │
    ▼
Action recognition: action type is "注入"
    │
    ▼
Runtime substitution: {角色名} → "贝利亚奥特曼"
    │
    ▼
Append to memory: "贝利亚奥特曼的故乡是光之国" written to memory
    │
    ▼
LLM narrative: generates response with the new memory

Why is substitution done at runtime?

Because the engine supports multiple branching storylines. If substitution happened at load time, all branches would share the same static value and couldn't evolve independently. Runtime substitution means each branch reads its own state — when the state changes, the interpolation result changes with it.

Dice Expression Error Tolerance

Dice expressions like roll(1d100) >= 80 are stored as-is during parsing and evaluated at runtime. If the expression has a format error — e.g., roll(1d10 missing a closing parenthesis — the engine doesn't report an error. Instead, it treats the condition as not satisfied (returns false). This is because dice expressions are part of conditions, and the parsing layer isn't responsible for validating runtime correctness — malformed expressions are simply treated as "no match."

V. Summary: The Parsing Layer Is Complete

At this point, the parsing layer covers all syntax units:

Block Type	Parse Function	Complexity	Notes
Text blocks	`parseTextBlock`	Low	Concatenates content, preserves newlines
Key-value lists	`parseKeyValuePairs`	Medium	Supports Chinese/English colons, precise error reporting
Rule lists	`parseRules`	High	Condition expressions, mutex groups, dice expressions
Plain text lists	`parsePlainList`	Low	Extracts lines one by one
Interpolation	`ReplacePlaceholders` (runtime)	Medium	Preserved at parse time, substituted at runtime

The most critical boundary:

The parser only "reads" — it turns text into structured data.
The engine "computes" — condition evaluation, variable substitution, action execution.

Next, we cross that boundary and enter the engine's runtime. The first engineering challenge the engine faces: how do we ensure code changes don't break existing parsing behavior?

The answer is integration testing — using a fixed set of .meph contracts as "watchdogs," comparing parse results against expectations after every change.

GitHub: https://github.com/yuelinghuashu/mephisto

LLM Narrative Engines, Part 3: Block Scanner and Line Numbers

yuelinghuashu — Sat, 25 Jul 2026 07:56:12 +0000

Before reading this: If you jumped here from a search engine, I'd recommend skimming Part 1's "See the Target" and ".meph Design Principles" sections to get familiar with what .meph looks like and why it exists. This post assumes you already know what 【角色名】 and 【规则】 are.

A JSON parser reports position 246. What a creator needs is "line 12: missing colon." This post is about making that precise error reporting a reality.

I. A Narrative Engine's Second Problem: How Do Rules Become Structure?

Once the format is defined, the next problem is parsing — how do we turn text into data the program can work with?

Two metrics matter here: parsing correctness and error readability. General-purpose formats (JSON/YAML) excel at the first but are a disaster on the second — position 246 means nothing to a creator. And for a custom format, the parser must be written from scratch.

A well-designed parser should do three things:

Precise recognition — every block and every line must be correctly classified
Line number binding — every error must trace back to a specific line, not a byte offset
Whitelist validation — typos like 【脚色名】 (a misspelling of "Character Name") should not be silently treated as valid content

This post implements all three.

II. See the Problem First: What Happens Without Line Numbers

Before diving into the parser, let's look at a real scenario.

A creator writes a contract with this line:

【锚点】
- 核心信念 "力量就是一切"

Notice: - 核心信念 "力量就是一切" is missing a colon. The correct form is - 核心信念: "力量就是一切".

With a general-purpose parser, the error would be something like:

unexpected token at position 42

The creator has to copy-paste and count characters to figure out where position 42 is. This process is excruciating.

My goal was to make the parser report:

第 2 行（区块「锚点」）：缺少 ':' 或 '：'

No counting positions, no understanding what a "token" is — just "line 2, block '锚点': missing ':'."

This difference is the entire reason for writing a custom parser.

III. Two-Phase Design

I split the parsing into two phases:

Phase	Responsibility	Input	Output
Block Scanner (Lexer)	Split into blocks, record line numbers	Raw text	`[]Block`
Structured Parser	Parse into structured data	`[]Block`	`*domain.Contract`

Key design decision: line numbers are bound during the scan phase. The parser receives them pre-attached and never needs to calculate offsets. This means error reporting always has precise, absolute line numbers.

Two data structures:

type Line struct {
    Text   string
    Number int  // absolute line number, starting from 1
}

type Block struct {
    Title   string  // e.g., "角色名"
    Content []Line  // content lines with their line numbers attached
    Line    int     // the line number of the title line
}

With this structure, error reporting becomes straightforward:

fmt.Errorf("第 %d 行（区块「%s」）：列表项必须以 '-' 开头",
    line.Number, blockName)

IV. Block Scanner: A Simple State Machine

The core is a line-by-line state machine. It has only two states:

inBlock == false: currently outside any block
inBlock == true: inside a block, collecting content

func Lex(text string) ([]Block, error) {
    lines := strings.Split(text, "\n")
    var blocks []Block
    var currentTitle string
    var currentContent []Line
    var currentLine int
    inBlock := false

    for i, rawLine := range lines {
        lineNumber := i + 1

        // Outside a block: skip empty lines
        if !inBlock && strings.TrimSpace(rawLine) == "" {
            continue
        }

        // Check if this line is a block title
        if title, ok := isBlockTitle(rawLine); ok {
            if inBlock {
                // Save the current block
                blocks = append(blocks, Block{
                    Title:   currentTitle,
                    Content: currentContent,
                    Line:    currentLine,
                })
            }
            // Start a new block
            currentTitle = title
            currentContent = []Line{}
            currentLine = lineNumber
            inBlock = true
            continue
        }

        // Non-title line: must be inside a block
        if !inBlock {
            return nil, fmt.Errorf("第 %d 行：内容出现在任何区块之外", lineNumber)
        }

        currentContent = append(currentContent, Line{
            Text:   rawLine,
            Number: lineNumber,
        })
    }

    if inBlock {
        blocks = append(blocks, Block{...})
    }

    if len(blocks) == 0 {
        return nil, fmt.Errorf("没有有效区块")
    }
    return blocks, nil
}

Two key design decisions:

1. Whitelist first

isBlockTitle only recognizes a predefined set of titles:

var knownBlocks = map[string]bool{
    "角色名": true,
    "锚点":  true,
    "规则":  true,
    "状态":  true,
    // ...
}

If a creator writes 【脚色名】 (a typo), the scanner won't treat it as a block start — it will return an error pointing to that line. The exact error message depends on context: if the line appears outside any block, it's "content appears outside any block"; if it appears inside a block, the block's parser will catch it. Either way, the line number is precise.

2. Line number binding

Every line carries its lineNumber at storage time, never offset. This is the foundation of precise error reporting.

V. Parser: Routing to Different Parse Functions

After the scanner outputs []Block, the parser routes each block to its corresponding parse function based on Title:

func parseBlocks(blocks []Block) (*domain.Contract, error) {
    contract := &domain.Contract{}
    for _, block := range blocks {
        switch block.Title {
        case "角色名":
            contract.RoleName, err = parseRoleName(block.Content, block.Line)
        case "锚点":
            contract.Anchor, err = parseKeyValuePairs(block.Content, block.Title)
        case "规则":
            contract.Rules, err = parseRules(block.Content, block.Title)
        // ... other block types
        }
        if err != nil {
            return nil, err
        }
    }
    return contract, nil
}

Each block type has its own parsing logic. Here's the key-value parser — note that every error includes the line number and block name:

func parseKeyValuePairs(lines []Line, blockName string) ([]KeyValue, error) {
    for _, line := range lines {
        trimmed := strings.TrimSpace(line.Text)
        if trimmed == "" || strings.HasPrefix(trimmed, "#") {
            continue
        }
        if !strings.HasPrefix(trimmed, "-") {
            return nil, fmt.Errorf("第 %d 行（区块「%s」）：列表项必须以 '-' 开头",
                line.Number, blockName)
        }
        // ... extract key-value pair
    }
    return result, nil
}

VI. Error Message Comparison

Same error, two experiences:

What the user wrote wrong	Generic parser error	`.meph` parser error
`- 核心信念 "力量"` (missing colon)	`Unexpected token at position 42`	`第 2 行（区块「锚点」）：缺少 ':' 或 '：'`
`情绪: 暴怒` (missing `-`)	`invalid character looking for value`	`第 2 行（区块「状态」）：列表项必须以 '-' 开头`
`【脚色名】` (typo)	N/A	Points to the exact line with an error

VII. The Cost

Approximately 400 lines of Go code
Need to write independent parsing logic for each block type
Adding a new block type means updating the whitelist

But there are no external dependencies. go build completes in one step. The parsing logic is fully controllable and can be adjusted at any time.

VIII. Summary

The block scanner and parser complete the "text to structure" transformation. 【角色名】 is now contract.RoleName. 【规则】 is now contract.Rules.

But the conditions in contract.Rules — like 包含 "攻击" — and the actions — like 注入 "{角色名}的故乡是光之国" — are still strings. The next post tackles: how do we parse rule condition-action expressions? How does the {变量} interpolation syntax work?

Those are the last two pieces of the parsing layer.

GitHub: https://github.com/yuelinghuashu/mephisto

LLM Narrative Engines, Part 2: Quick Start — Write Your First Contract

yuelinghuashu — Thu, 23 Jul 2026 13:13:17 +0000

Before reading this: If you haven't read the first post, From Freeform to Constrained Generation, I'd recommend starting there to understand why .meph exists. This post requires zero prior knowledge — just a terminal and Go 1.26+.

In the previous post, we talked about why .meph is a better fit for narrative contracts than JSON or YAML. But talk is cheap.

Then let's stop talking and start building. We'll write a real contract from scratch, compile it, and run it. You'll have your first narrative running in no time — and you'll see, firsthand, how the rules you write drive LLM-generated storytelling.

I. What You'll Need

Three things:

Go 1.26+ — open a terminal and run go version to check
A terminal — any OS works
(Optional) An LLM API key — DeepSeek, OpenAI, or Ollama all work. Not required — the engine runs fine without an LLM.

If you have an API key, create a .env file in the project root:

MEPHISTO_CLIENT=openai
MEPHISTO_MODEL=deepseek-v4-flash
OPENAI_API_KEY=sk-your-key-here

II. Clone and Build

git clone https://github.com/yuelinghuashu/mephisto.git
cd mephisto
go build -o ./mephisto ./cmd/mephisto

If everything goes well, you'll see a binary named mephisto.

III. Write Your First Contract

Now for the real work. Create a new file data/faust.meph and fill it from scratch.

3.1 Character Name

The first line of any contract is the character name. Mark the block with 【角色名】 (Character Name) and write the name directly below:

【角色名】
Faust

That's it — no quotes, no colons, no markup.

3.2 Anchor

The 【锚点】 (Anchor) block defines the character's core personality. Use the - key: value format:

【锚点】
- 核心信念：Knowledge above all else. I would pay any price for truth.
- 欲望：To experience everything a human can experience.
- 绝对禁忌：I will never admit regret.

These are injected directly into the LLM's context — they're the bedrock of the character's behavior.

3.3 State

【状态】 (State) holds dynamic variables, also in key-value format:

【状态】
- 灵魂完整度：100
- 情绪：Never satisfied
- 位置：Study

State values support three types: numbers, booleans, and strings. The engine infers types automatically at parse time — "100" becomes the number 100, while "Never satisfied" stays a string. This means you can write conditions like 状态.灵魂完整度 > 50 directly, without manual type conversion.

At runtime, state is stored as a map[string]any for fast read/write. Initial order is inherited from the contract, but runtime access is key-based and order-agnostic.

3.4 Worldview

【世界观】 (Worldview) is multi-line text. Write freely — line breaks are preserved:

【世界观】
The story takes place in 16th-century Germany, an era where theology and science are locked in tension. Universities are consumed by sterile scholastic debates; real knowledge is suppressed. The world is composed of God, angels, demons, and mortals — Heaven and Hell are real dimensions. Mephistopheles is a hellish emissary, skilled at trapping souls through words and contracts. Soul transactions are legally binding in this world — once a soul contract is signed, there's no revocation.

3.5 Character Background

【角色背景】 (Character Background) works alongside Worldview to define the character's history:

【角色背景】
Faust is a scholar of vast learning — philosophy, medicine, law, and theology. Yet he despairs at the limits of human knowledge: after a lifetime of study, he still cannot touch the essence of the world. In his despair, he signs a contract with Mephistopheles: his soul in exchange for unlimited earthly experience.

3.6 Opening Scene

【开局场景】 (Opening Scene) sets the stage when the conversation begins:

【开局场景】
Late night. Candlelight flickers in the study, books piled high on the desk. Faust stands by the window, gazing at the moonlight. On the corner of the table lies a contract, its ink still wet.

3.7 Rules — The Heart That Brings the Character to Life

【规则】 (Rules) is the engine's core. Each rule has three parts: [name] if condition -> action.

【规则】
[New Desire] if 包含 "追求" || 包含 "想要" || 包含 "体验" -> 注入 "{角色名} feels a new longing kindle in his chest — nothing can stop him from experiencing it all firsthand"
[Mephistopheles] if 包含 "梅菲斯特" || 包含 "契约" -> 注入 "Mephistopheles's voice whispers at {角色名}'s ear: 'Is this what you truly want? Have you considered the price?'"
[Soul's Price] if 包含 "代价" || 包含 "灵魂" -> 注入 "{角色名} looks down at his hands, as if he can see something slowly slipping away"
[Never Satisfied] if 不包含 "放弃" && 不包含 "满足" -> 注入 "{角色名}'s eyes burn with an unquenchable flame — he still wants more"

Rule conditions support logical operators (&&, ||), state comparisons (状态.key > value), and dice expressions (roll(1d100)). The most common action is 注入 (inject) — it appends a message to memory, which the LLM then weaves naturally into the ongoing narrative.

3.8 Validate

Save the file and validate the parse:

./mephisto parse data/faust.meph

You'll see JSON output like this:

{
  "role_name": "Faust",
  "anchor": [...],
  "state": [...],
  "rules": [...]
}

If parsing fails, the error tells you exactly what's wrong and where — something like "line 12 (block '锚点'): missing ':' or '：'."

IV. First Conversation (No LLM Mode)

The engine runs fine even without an LLM:

./mephisto run data/faust.meph

You'll see a welcome message, then enter the conversation loop. Type "I want to experience love":

命运 > I want to experience love
Faust gazes silently at fate.

No LLM means the engine returns the default response. But rules still fired — the input contained “想要” (want), which matched the condition 包含 "想要", triggering the [New Desire] rule and writing the injection into memory.

Type /state to see the current state:

Current state:
  灵魂完整度: 100
  情绪: Never satisfied
  位置: Study

Type /history to see the conversation log — your input “I want to experience love” is already recorded as a fate directive.

This is how the engine works without an LLM: rule matching, injection, state management — everything runs normally. The LLM is just the final “narrative rendering layer.”

V. Bring in the LLM

Now add your API key and run again:

./mephisto run data/faust.meph -debug

You'll see the same welcome message, this time with -debug enabled. The LLM configuration will be displayed first.

Then type this at the prompt:

命运 > You want to acquire knowledge beyond human comprehension

The terminal shows debug output — and then Mephistopheles steps out of the shadows:

🔍 Rule debug mode
----------------------------------------
📌 Checking rule [New Desire] (line 26)
   Condition: 包含 "追求" || 包含 "想要" || 包含 "体验"
   Result: true
   ✅ Triggered → inject "{角色名} feels a new longing kindle in his chest, no...

  The candlelight in the study flickered, casting the parchment rolls and codices that lined the walls into shifting pools of light and shadow. Faust sat slumped at his desk, piled high with manuscripts, his fingertips tracing the worn cover of an old astronomy text. But his gaze drifted past the window, into the pitch-black night. He muttered, his voice hoarse, almost carried away by the draft: “A lifetime of searching, and I've never even pushed open a single door.”

  Then, from the bookshelves behind him, came a sound — soft, like a mouse gnawing at wood, or a stifled chuckle. Faust did not turn. He said coldly: “Is that you again, Wagner? It's late. You needn't bring me any more warm broth.”

  But the footsteps were light — too light for his clumsy apprentice. A low, metallic voice emerged from the darkness: “Wagner is only fit to stoke your fire. I bring a different kind of warmth.” A figure stepped out of the shadows — tall, draped in a sumptuous crimson robe, with a lean face and a smile that seemed to curve just slightly too far. He toyed with a bronze ring between his fingers. He stopped before the desk, leaned forward slightly, and fixed his gaze on Faust's eyes: “You said a moment ago that you've spent your life unable to push open that door. But have you ever considered that doors weren't meant to be pushed?”

  Faust slowly lifted his head and fixed his stare on this uninvited guest. His hand pressed flat on the astronomy text. “Who are you? You enter my study without permission.”

  The man gave a soft laugh and turned the ring in the candlelight. It cast a twisted shadow — as though it were some kind of unutterable sigil. “I am the answer to all your questions — and the price of all your desires.” He extended his hand, palm up, fingers spread. Dim red light pulsed through the lines of his palm. “I can show you the patterns behind the stars. I can let you hear the melody that played at the beginning of creation. I can let you touch the law itself. All I ask in return is one small, insignificant thing.”

  Faust rose to his feet, his sleeve sweeping across the scattered drafts on the desk. Sheets of formulae and notes drifted to the floor. He stared at that outstretched hand for a long time, then finally spoke: “What do you want?”

  The man's smile widened, his voice soft as a feather brushing a blade: “Your soul. But don't worry — you don't use it anyway. It can't solve your equations. It can't carry you to the heavens. Keeping it is just letting it rot with a body that's already decaying.” He withdrew his hand and instead produced a roll of jet-black parchment, which he unfurled across the desk. The surface held no script, only an abyss of darkness that seemed to swallow the light around it. “Sign it, and I will deliver everything at once.”

  Faust's breath quickened. He looked down at that dark expanse, then up at the man's eyes — which reflected the birth and death of countless stars. At last, he reached out. His fingertip touched the parchment, and a chill shot up along his shoulder. He hesitated no longer. He took the quill the man offered, pricked his own thumb, and let the blood fall onto the page.

  Just then, the study door creaked open a crack. Wagner peered in, clutching a dim oil lamp. He saw the stranger in the room, then saw the blood on his master's fingertip. His face went white. Trembling, he cried out: “Master! What are you doing? When did this man enter?”

  Faust didn't stop. The blood-script was already taking form on the parchment. Without turning, he said: “Wagner, close the door. Tonight you will witness a scholar's final wish.” As the words faded, the darkness on the parchment began to churn, spreading through the room like a starless night unfurling — while the crimson-robed man's laughter echoed among the scrolls.

That's what those 30 lines of contract you just wrote can generate.

Now try changing just one number.

Open data/faust.meph, change 灵魂完整度 in 【状态】 from 100 to 50, save, and run again. Type the same line:

命运 > You want to acquire knowledge beyond human comprehension

Same rules, same input, one number different — and the narrative shifts entirely:

  The candlelight in the study swayed, casting enormous shadows that crawled across the shelves like living things. Faust slumped in his chair behind a mountain of books. A quill hung between his fingers, the ink long dry on its tip. His empty gaze swept across the Latin, Greek, and Hebrew scrolls — these symbols that had once enraptured him now lay like dried insect husks, drained of meaning.

  “Forty years,” he rasped, barely audible. “Forty years of study, and I have not even touched the edge of the first heaven.”

  From outside came the low cry of a night bird, as though something was answering his despair. At that moment, the study door opened silently, and in came his old servant Wagner, carrying a steaming bowl of herbal broth. He picked his way carefully through the scattered parchment, set the bowl on the corner of the desk, and spoke with evident worry: “Master, you haven't eaten for three days. You've been reading Paracelsus all night — your eyes are bloodshot. If you keep this up…”

  “If I keep this up, what? What's the worst that could happen — this body rotting before my desires do?” Faust's head snapped up, a near-crazed light kindling in his eyes. “Wagner, you've studied for years too. Tell me — have you ever seen the face of truth?”

  Wagner stepped back, daunted by the look in Faust's eyes. He murmured: “Master, this servant believes that truth is God's affair.”

  “God's affair.” Faust repeated the words, then burst into laughter — laughter thick with bitterness. “Exactly. Exactly. We hand everything over to God, fencing ourselves in with theological rails, safe in our pigsties, chewing the dry crusts the priests toss us — and we're grateful for it!” He rose to his feet, knocking over his chair behind him. The candle flame almost died under the wind of his robe. “I'm done with these words, these symbols, this stuff written by men to deceive one another. I need real knowledge — the knowledge that belongs to the ancient ones, the primordial ones.”

  Wagner stared at him in terror, his hands trembling. “Master… what are you saying? Such thoughts are blasphemy…”

  “Blasphemy?” Faust strode to the window and threw it open. The cold night wind rushed in, whipping his gray hair and robe into frenzy. “If seeking truth is blasphemy, then let this blasphemy be complete.” He turned, his eyes burning like live coals. “Wagner, leave. Tonight I need to be alone.”

  Wagner opened his mouth, but finally lowered his head and retreated quickly. The wooden door closed heavily behind him. Faust stood alone at the open window, staring up at the star-filled, silent sky. He whispered: “You've been standing there for billions of years. Do you have nothing to say to this mere mortal?”

  No sooner had the words left his mouth than the candle flame on the desk leaped high, turning into a sheet of blue fire. From its center, a voice spoke — low, elegant, not coming through the air, but echoing directly inside Faust's skull.

  “You're finally ready to listen, Mr. Faust.” The voice carried a smile. “Then allow me to introduce myself.”

Notice the difference: at soul integrity 100, Faust is a “contemplative scholar,” calmly skeptical when Mephistopheles appears — “Who are you? Entering my study without permission.” At soul integrity 50, he becomes a “brilliant scholar teetering on the edge of self-destruction,” shouting at Wagner, redefining the pursuit of knowledge as blasphemy. Even Mephistopheles' entrance changes — not emerging from shadow, but erupting from candle flames, his voice resonating directly inside Faust's skull.

A single state value changes, and the entire texture of the narrative transforms. That's the power of state-driven storytelling.

Look closely at the first output:

Faust's identity as a scholar — drawn directly from 核心信念：Knowledge above all else in 【锚点】 and the 【世界观】 line about spending a lifetime without touching the essence of reality. The LLM faithfully inherited these traits.
Mephistopheles's appearance — triggered by the [New Desire] rule from the input “want.” The injected memory gave the LLM the context: “Faust feels a new longing kindle in his chest.”
“Price” and “soul” — the LLM naturally introduced the theme of “price,” which triggered the [Soul's Price] rule — even though you didn't explicitly type those words.
“Never satisfied” as an underlying tone — the [Never Satisfied] rule has the condition 不包含 "放弃" && 不包含 "满足" (doesn't contain “give up” and doesn't contain “satisfied”), which fires on almost every turn. It constantly injects “Faust still wants more,” making this not just a one-turn interaction but a persistent character trait that runs through the entire narrative.

Every rule is doing work. Not a single one is wasted.

VI. Try Changing Something

Now that you've seen the engine in action, make some changes and see what happens:

Change a State Value

- 灵魂完整度：50

You already saw the result. Try 10 or 0 and see how Faust changes.

Add a Dice Rule

[Favor of Fate] if 包含 "追求" && roll(1d100) >= 80 -> 注入 "Fate seems to favor {角色名} — things go more smoothly than expected"

roll(1d100) >= 80 means: roll a 100-sided die, and the rule only triggers if the result is >= 80. A 20% success rate — not every pursuit is lucky. This introduces real randomness into the story.

Run Two Turns, Then Look at the Child Save

After a couple of turns, open data/faust_child.meph in a text editor:

【状态】
- 灵魂完整度：100
- 情绪：Never satisfied

【记忆】
- Faust feels a new longing kindle in his chest…
- Mephistopheles's voice whispers at Faust's ear…

【历史】
- fate: I want to experience love
- assistant: …

This is the engine's Mother-Child save mechanism: faust.meph is the read-only master contract; faust_child.meph is the dynamic snapshot containing runtime state, memories, and history. Automatically saved after every conversation.

VII. Summary

At this point, you've done three things:

Written a complete contract — 30 lines covering character name, anchor, state, worldview, background, opening scene, and rules
Validated its structure with the parser — the parse command tells you precisely whether your contract is correct
Run the engine and watched the character come alive — even without an LLM, rules still fire; with an LLM, every rule you wrote shapes the narrative direction

Those 30 lines are the contract between you and the engine. The engine ensures the LLM honors it.

Next post goes under the hood. It answers one critical question: how does the block scanner precisely recognize 【角色名】 and 【规则】? And why can errors report “line 12, block ‘锚点’: missing ':' or '：'” — instead of unexpected token at position 246?

The answer is a handwritten block scanner — a lightweight lexer that scans line by line, binds precise line numbers, and enforces a block whitelist. See you in the next one.

GitHub: https://github.com/yuelinghuashu/mephisto

LLM Narrative Engines, Part 1: From Freeform to Constrained

yuelinghuashu — Mon, 20 Jul 2026 13:47:44 +0000

On the first day I started building narratives with LLMs, I hit a wall.

I defined a character: Belial, a fallen Ultraman — arrogant, contemptuous of the Land of Light, obsessed with power. The first three turns were perfect. Every response carried that satisfying villainous edge. By the fifth turn, he started giving me life advice, like a mild-mannered philosopher. By the tenth, he called himself "a guardian of the Land of Light." He had completely forgotten who he was.

This isn't a model quality issue. It's the fundamental flaw of free generation — LLMs have no built-in mechanism to "enforce rules." You can write "you are an arrogant villain" in the system prompt, but the model's understanding of "arrogant" is probabilistic. Over long contexts, it attenuates, overwritten by user inputs, model outputs, and even token-order drift.

I needed a way to write down rules that the model must follow. So I started building Mephisto.

But before writing the engine code, I had to solve a more fundamental problem: what format should these rules be written in?

The format needs to carry: the character name (single-line), the worldview (multi-line), state variables (key-value pairs), and behavioral rules (condition-action pairs). Each type has a different structure and parsing strategy. The choice of format determines whether the creator spends their time writing stories or debugging syntax.

This post documents my trade-offs and final decision.

I. A Narrative Engine's First Problem: How Do You Express Rules?

A narrative engine's first problem is the rule expression layer — how does the creator tell the engine what this character will and won't do? There are three common approaches:

General-purpose structured formats (JSON/YAML): program-friendly, but cruel to creators — escaping hell, unreadable error messages
Custom domain-specific formats (like .meph, Ink): a middle ground, but the parser must be written from scratch
Plain text: most friendly to creators, but almost impossible for programs to parse precisely

Each approach has a cost. I'll compare them one by one, then explain why I chose the custom path.

II. See the Destination: A Real .meph Contract

Before discussing any design decisions, let's look at the finished product. Here's a complete .meph contract, taken from the project's data/sample.meph:

【角色名】
贝利亚奥特曼

【锚点】
- 核心信念：力量就是一切
- 说话风格：狂傲、嘲讽、不容置疑

【世界观】
光之国是宇宙中最强大的文明，也是贝利亚的故乡。
但他早已被驱逐，如今他带着对光之国的憎恨归来。

【状态】
- 堕落指数：50
- 情绪：暴怒
- 位置：宇宙空间站

【规则】
[攻击] if 包含 "攻击" -> 注入 "贝利亚发动了猛烈的攻击"
[防御] if 包含 "防御" || 包含 "防守" -> 注入 "贝利亚摆出了防御姿态"
[光之国] if 包含 "光之国" -> 注入 "{角色名}的故乡是光之国，也是他最大的仇恨来源"
[高堕落] if 状态.堕落指数 > 80 -> 状态.情绪 = "癫狂"

This is the entire contract. The creator sees not { and }, not escaped quotes, not indentation levels, but:

A name directly under 【角色名】
Key-value pairs under 【锚点】 using - key: value
Rules under 【规则】 using [name] if condition -> action

Notice {角色名} in the rules — that's interpolation syntax. The parser stores it as-is, and the engine replaces it at runtime with the current character name. This ensures branches evolve independently without interfering with each other.

It reads like a document. But the program can parse it precisely, and when something goes wrong, it can tell the creator "line 12, block '状态': list item must start with '-'" — not unexpected token at position 246.

The question is: how did I get here?

III. JSON: Friendly to Programs, Hostile to People

JSON was the obvious first choice. Clean structure, simple parsing, mature libraries in every language. I actually built a prototype with JSON — I still have that yellowed printout somewhere, covered in handwritten notes. Then I hit the fatal problem.

That rule from above, in JSON:

{
  "rules": [
    {
      "name": "攻击",
      "condition": "包含 \"攻击\"",
      "action": "注入 \"贝利亚发动了猛烈的攻击\""
    }
  ]
}

The creator's intent:

包含 "攻击"

In JSON, it becomes:

"condition": "包含 \"攻击\""

The problem isn't that the syntax is "hard." It's context switching cost.

The creator can't directly express their intent — they have to constantly think "am I writing JSON or am I writing rules?" Over a large contract, this cost accumulates. You're not reading content; you're constantly verifying how many backslashes are on this line.

Even worse: error messages. A common mistake — a trailing comma after the last element in a JSON array. The JSON parser reports:

Unexpected token } in JSON at position 246

The creator has to paste it into an online tool and count characters to figure out where position 246 is. For non-technical users, this experience is devastating.

JSON is friendly to programs, but hostile to people. And the author of this file is a creator, not a programmer.

IV. YAML: The Mirage of Simplicity

YAML seemed to fix JSON's readability problem:

role_name: 贝利亚奥特曼
rules:
  - name: 攻击
    condition: 包含 "攻击"
    action: 注入 "贝利亚发动了猛烈的攻击"

Indentation replaced brackets and commas. It looked more like "writing a document."

But YAML's problems are more insidious than JSON's. They're not syntax errors — they're logic errors. The file parses, but the behavior is wrong.

Imagine defining a multi-line text block in YAML (a worldview, for example), using the | marker:

worldview: |
  光之国是宇宙中最强大的文明。
  贝利亚被驱逐后，一直在寻找复仇的机会。

Then you define a list below it. One space off in indentation, and the parser may treat subsequent lines of the multi-line block as children of the list. Result: the worldview is truncated, the list structure is broken, no error is reported, and the engine behaves unexpectedly.

Even more subtle: Chinese full-width spaces (　) and English half-width spaces () are visually indistinguishable. A creator accidentally types a full-width space instead of a half-width one — YAML parsers don't treat it as indentation. They either throw a syntax error or, worse, misidentify the entire block as a key. Without syntax highlighting, this is almost impossible to debug by eye.

The creator isn't reading content; they're constantly verifying "how many spaces are on this line." For a hundred-line contract, this cognitive burden never stops.

YAML's simplicity is a mirage. It's friendly to people, but to programs, its rules are more complex and unpredictable than JSON's.

V. Plain Text: Free but Ambiguous

Since structured formats have problems, why not skip structure entirely and just write plain text?

Like this:

角色名是贝利亚奥特曼。
世界观是光之国。
规则是如果用户提到攻击，就执行攻击。

For creators, this is the most natural way — zero learning curve.

But there's a problem: the program can't understand it. It doesn't know whether the "是" in "角色名是贝利亚奥特曼" is a declaration or a description. It doesn't know the relationship between "世界观是光之国" and the next sentence "规则是...". Natural language is clear to humans, but to programs, it's ambiguous, imprecise, and unparseable.

If I used plain text, I'd have to design an implicit convention — recognizing blocks by keyword matching, distinguishing entries by line breaks. That's harder to guarantee correctness than an explicit syntax.

Plain text is most friendly to creators, but almost unfriendly to programs.

VI. Three Options Compared

Format	Creator-Friendly	Program-Friendly	Core Problem
JSON	❌ No	✅ Yes	Escaping hell, unreadable error messages
YAML	⚠️ Partial	✅ Yes	Indentation sensitivity, multi-line vs. list confusion
Plain Text	✅ Yes	❌ No	Ambiguous structure, unparseable

I needed a format that: reads like a document, but has structure. It had to satisfy two conditions simultaneously:

Creators can write naturally, without learning JSON escaping or YAML indentation rules
Programs can parse precisely, and on error, tell the creator the exact location and reason

This meant I couldn't use any existing general-purpose format — I needed to design one specifically for the "narrative contract" scenario.

Even if only one out of ten users is a minimalist who craves a simpler config — that's still 10%, if you round it. So I decided to go all in on the custom format.

VII. .meph Design Principles

Back to that .meph contract from the beginning. Its design is based on three principles:

1. Use human language for boundaries, eliminate bracket-phobia

Creators see 【角色名】, not { and }. Chinese guillemets are more natural than curly braces for Chinese-speaking creators. 【角色名】 itself says what this section contains — no comments needed.

More importantly, block titles are restricted to a whitelist (角色名, 锚点, 规则, 状态, etc.). If a creator writes 【脚色名】 (a typo), the parser won't treat it as a block start — the creator will get an error pointing to that exact line.

(The specific message depends on whether the typo appears inside a block or outside one, but the line number is always precise.)

2. Distinguish "semantic blocks" rather than "data structures"

In JSON, the creator decides whether to use an object or an array — that's an implementation detail. In .meph, the creator only needs to know "this is a list" or "this is a paragraph." The parser identifies the structure based on the block title — the creator doesn't declare it.

3. Syntax mirrors natural logic

Rules use the intuitive [name] if condition -> action form. Condition logic uses readable expressions like 包含 "keyword" and 状态.key > value, not symbolic operators.

VIII. The Cost

This design doesn't come without cost:

The parser must be handwritten: I can't use json.Unmarshal or yaml.Unmarshal — I have to write my own lexer and parser
The whitelist must be maintained: adding a new block type means updating the knownBlocks list
Documentation is required: creators need to learn the format — though the learning curve is lower than JSON's, it's still a curve
Tooling is absent: no off-the-shelf syntax highlighting, formatting, or validation tools

But the deciding factor is simple: who writes this file?

If it's a programmer writing for a program, JSON is fine. If it's a creator writing for a program, you need a "human-centric" format. And the target users of a narrative engine are creators — people who write stories.

I believe this trade-off is worth it.

IX. Summary

This post answered the question "what format to use?" The answer is .meph — a custom text format designed specifically for narrative contracts, optimized for creator experience.

But "design" only solves half the problem. The next post puts theory aside and walks through writing a real contract from scratch — so you can see what it actually feels like to use this format.

GitHub: https://github.com/yuelinghuashu/mephisto

From Code to npm: Publishing a Vue 3 Component Library and Avoiding Pitfalls

yuelinghuashu — Wed, 24 Jun 2026 08:21:46 +0000

The component library is done, but publishing to npm is the real test: 2FA, network proxies, registry switching, build artifact verification… This guide covers all the pitfalls encountered and the final standardized release workflow in one go.

1. Introduction

After completing the component library development, the final step is also the crucial one—publishing to npm. This process seems straightforward, but it hides plenty of modern engineering baggage: package name conflicts, strict 2FA validation, security keys (WebAuthn) getting stuck under certain network conditions, frequent registry mirror switching… and—the correctness of build artifacts.

This article documents my publishing journey from v0.0.1 all the way to v1.5.0.

2. Pre-Publishing Preparation

2.1 Build and Verification Pipeline (v1.5.0 Actual)

The build script in v1.5.0 is an automated verification pipeline:

# package.json scripts
"build": "pnpm run clean && vite build && pnpm run build:types && pnpm run clean:dts && pnpm run copy:reset && pnpm run verify:build && pnpm run check:size",
"prepublishOnly": "pnpm build && pnpm test"

Responsibilities of each step:

Script	Purpose
`vite build`	Bundles JS + CSS artifacts (27 component multi-entry)
`build:types`	Generates `.d.ts` type declarations via vue-tsc
`clean:dts`	Cleans up redundant type files from artifacts
`copy:reset`	Copies `reset.css` to dist
`verify:build`	Verifies .js / .d.ts / style.css / reset.css exist for each component entry + export names are correct
`check:size`	Bundle budget check (Min+Gzip ≤ 25KB)
`prepublishOnly`	Forces build + test before publishing

Core logic of verify-build.js — preventing missed component entry publications:

// Each component: dist/<kebab>.js exists + dist/exports/<Name>.d.ts exists + export name is correct
for (const [componentName, kebabName] of Object.entries(componentEntries)) {
  const jsPath = join(distDir, `${kebabName}.js`)
  const dtsPath = join(distDir, "exports", `${componentName}.d.ts`)
  if (!existsSync(jsPath)) {
    errors.push(`Missing component artifact: ${kebabName}.js`)
  }
  // Any error → process.exit(1) prevents publishing
}

2.2 Distribution Contract (package.json)

{
  "name": "moongate-vue",
  "version": "1.5.0",
  "type": "module",
  "main": "./dist/index.js",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "default": "./dist/index.js"
    },
    "./style.css": "./dist/style.css",
    "./reset.css": "./dist/reset.css",
    "./button": {
      "types": "./dist/exports/Button.d.ts",
      "import": "./dist/button.js",
      "default": "./dist/button.js"
    }
    // ... 27 component entries
  },
  "files": ["dist"],
  "sideEffects": ["*.css"],
  "peerDependencies": {
    "vue": "^3.5.0"
  }
}

Key Differences (vs initial version):

Pure ES Module: Only .js, no .cjs — this is a deliberate choice (all modern bundlers support ESM, and having an import condition in exports suffices)
27 on-demand export entries: Users can import Button from 'moongate-vue/button' to load only the needed component
peerDependencies raised to ^3.5.0: Because useId() (Vue 3.5+ API) is used
sideEffects: ["*.css"]: Prevents bundlers from tree-shaking away CSS

💡 Bundle Size Defense Tip: The files field is a "whitelist". With ["dist"] configured, npm only uploads the dist directory. package.json, README.md, and LICENSE are automatically included by npm.

2.3 Managing npm Registry with nrm

🛠️ nrm Registry Switching Details

Publishing to npm requires the official registry. If you previously switched to a domestic mirror for faster downloads, it's recommended to use nrm.

npm install -g nrm
nrm ls
nrm use npm        # Switch to official registry for publishing
nrm current

Tip: The domestic Taobao npm mirror has migrated to https://registry.npmmirror.com.

2.4 Local Link Testing

Before publishing to npm, it's best to test in a real project first:

# 1. In the component library directory: build + global link
pnpm build
pnpm link --global

# 2. In the test project directory: link local component library
pnpm link /home/dark/projects/moongate-vue

Testing checklist:

[ ] Components render correctly
[ ] Style file import works (import 'moongate-vue/style.css')
[ ] On-demand entry works (import Button from 'moongate-vue/button')
[ ] TypeScript type hints work correctly
[ ] HMR hot reload works

Note: After testing, to remove the link you need: pnpm remove moongate-vue + manually clean up link: entries.

3. Overcoming the Two-Factor Authentication (2FA) Quagmire

npm requires two-factor authentication to be enabled for publishing. npm has fully embraced the security key (WebAuthn) model.

🛠️ WebAuthn Network Troubleshooting Details

⚠️ Industrial-Grade Pitfall Warning: npm's WebAuthn verification attempts to interact with Google's verification service. Under domestic network conditions, using Chrome/Edge to trigger the security key window is extremely prone to timeouts, unresponsiveness, or errors due to network issues.

Browser	Requires Global Proxy	Success Rate	Recommendation
Chrome	✅ Must enable	Very high	First choice
Edge	❌ Not required	High	Second choice
Firefox	❌ Not required	Very low	Not recommended

3.2 CI/CD Alternative: Granular Access Token

//registry.npmjs.org/:_authToken=your_granular_token_value

Select Read and Write permissions, and check "Bypass two-factor authentication for automation".

4. Standardized Release Workflow

4.1 Manual Publishing Steps

nrm use npm
npm login (complete 2FA in browser)
npm version patch|minor|major (note --no-git-tag-version is optional)
npm publish --access public

Scoped packages must include --access public.

4.2 Step-by-Step Automation Scripts

{
  "scripts": {
    "release:pre": "nrm use npm && npm run build && npm test",
    "release:version": "npm version patch --no-git-tag-version",
    "release:tag": "git add package.json && git commit -m \"chore: release v$(node -p 'require(\"./package.json\").version')\" && git tag v$(node -p 'require(\"./package.json\").version')",
    "release:publish": "npm publish --access public",
    "release": "npm run release:pre && npm run release:version && npm run release:tag && npm run release:publish"
  }
}

5. Final Pre-Publishing Checklist

[ ] Build succeeds: pnpm run build completed without errors (including verify-build + check:size)
[ ] Artifacts complete: dist/ contains index.js, 27 component .js files, style.css, reset.css, index.d.ts
[ ] Bundle size meets target: Min+Gzip ≤ 25KB (confirmed by tree-shake-check.js output)
[ ] Tests pass: pnpm test (450 tests all green)
[ ] Version is clean: Current version number has never existed on npm
[ ] Local sandbox verified: Styles + on-demand entry + types all working
[ ] peerDependencies correct: vue ^3.5.0

6. FAQ

Q1: Publishing returns 403/404?

403 = package name is taken or not logged in. 404 = forgot nrm use npm and published to a read-only mirror.

Q2: 2FA won't show the security key window?

Confirm that the proxy is set to global/TUN mode. If it still fails, use a Granular Access Token.

Q3: Users get a white screen after installing styles?

Confirm that sideEffects: ["*.css"] is configured, and users explicitly import 'moongate-vue/style.css'.

Q4: Users can `import 'moongate-vue'` but `import 'moongate-vue/button'` fails?

Check whether the /button sub-path is declared in exports. v1.5.0 has all 27 components fully configured.

7. Conclusion

The publishing phase is often treated as "the last chore," but it's actually just as important as component design—the correctness of build artifacts, restraint in bundle size, and API stability all depend on this stage holding the line.

Publishing in v1.5.0 is no longer a simple npm publish, but an automated pipeline guarded by verify-build.js + tree-shake-check.js + 450 tests working together.

May your component library also cross the quagmire and reach further horizons. 🚀

🌙 About Moongate Vue

This article is based on the real publishing practice of Moongate Vue. Related resources:

Project Repository: github.com/yuelinghuashu/moongate-vue — Minimalist Vue 3 component library, zero dependencies, CSS-first, 25KB gzip
Live Example: moongate.top — Personal blog, migrated from Nuxt UI v4 to Moongate Vue
Online Documentation: vue.moongate.top — Component API and theme customization guide

Vue 3 Complex Component Development: API Design for Select and Pagination

yuelinghuashu — Fri, 19 Jun 2026 11:58:12 +0000

Simple components are one-way data consumers; complex components are data adapters and state coordinators. Using Select and Pagination as examples, let's see where the "industrial-grade details" lie.

1. Introduction

If writing a Button component is about enjoying the "paint-like beauty" of CSS variables, then writing Select and Pagination is about wrestling in the "mud pit" of native HTML's historical baggage. Simple components are one-way data consumers, while complex components are data adapters (compatible with multiple formats) and state coordinators (searchable, multiple selection, keyboard navigation, SSR-safe).

This article uses Select and Pagination as examples to demonstrate the complex component development approach behind the v1.5.0 implementation.

2. Select Dropdown: The Data Adapter

The Select component needs to accept a list of options and allow the user to choose one. Real-world APIs may return object arrays, string arrays, or even number arrays, so the component must have robust data adaptation capabilities.

2.1 Requirements Analysis

Support object arrays { label, value } (default)
Support custom field names (labelKey / valueKey)
Support string arrays ['Option A', 'Option B']
Support number arrays [1, 2, 3]
Provide a placeholder (non-selectable default option)
Support disabled options (disabled: true)
Searchable mode (filterable): input filtering + dropdown panel
Multiple selection mode (multiple + filterable): tag display
Must solve the type trap of native <select> returning strings
Full ARIA keyboard navigation (listbox + option + aria-activedescendant)

2.2 Dual-Mode Architecture: Native Mode + Searchable Mode

The v1.5.0 Select supports dual modes:

Native mode (default): renders a native <select>, zero JS overhead
Searchable mode (filterable=true): renders a custom input + dropdown panel, supporting search/multiple selection/keyboard navigation

<!-- Native mode: best performance -->
<Select v-model="category" :options="categories" />

<!-- Searchable mode: filtering + dropdown -->
<Select v-model="fruit" :options="fruits" filterable />

<!-- Searchable + multiple selection -->
<Select v-model="tags" :options="tags" filterable multiple />

2.3 API Design and Type Anti-Corruption

To avoid type pollution caused by any, we use union type narrowing:

export type SelectValue = string | number
export type SelectOption = string | number | Record<string, any>

interface Props {
  options?: SelectOption[]
  placeholder?: string
  size?: Size
  disabled?: boolean
  error?: boolean
  labelKey?: string // default 'label'
  valueKey?: string // default 'value'
  filterable?: boolean // searchable mode
  emptyText?: string
  maxHeight?: number // dropdown panel max height
  multiple?: boolean // multiple selection (requires filterable)
}

Type backtracking solves the problem of native select always returning strings:

const handleNativeChange = (event: Event) => {
  const target = event.target as HTMLSelectElement
  const rawValue = target.value

  // Find the original type (number or object value) in the original options
  const originalItem = props.options?.find(
    (item) => String(getValue(item)) === rawValue,
  )
  const finalValue =
    originalItem !== undefined ? getValue(originalItem) : rawValue

  modelValue.value = finalValue
  emit("change", finalValue)
}

This logic ensures that a number value bound via v-model won't accidentally become a string.

2.4 Attribute Passthrough Split

This is a key detail of the searchable mode — which attributes pass through to the native input and which stay on the outer wrapper:

const attrs = useAttrs()

/** Form/aria attributes that pass through to the native form element */
const formAttrs = computed(() => {
  const result: Record<string, unknown> = {}
  for (const [key, value] of Object.entries(attrs)) {
    if (
      key.startsWith("aria-") ||
      ["name", "id", "role", "tabindex"].includes(key)
    ) {
      result[key] = value
    }
  }
  return result
})

/** Remaining attributes retained on the outer wrapper (class/style/events, etc.) */
const wrapperAttrs = computed(() => {
  const result: Record<string, unknown> = {}
  for (const [key, value] of Object.entries(attrs)) {
    if (!(key in formAttrs.value)) {
      result[key] = value
    }
  }
  return result
})

Why is this split necessary? If aria-label stays on the outer wrapper without being passed through to the actual <input>, screen readers won't be able to identify the input's accessible name — this triggers an aria-input-field-name violation in axe-core checks in a11y.test.ts.

2.5 ARIA Keyboard Navigation (WAI-ARIA Combobox Pattern)

The keyboard navigation in searchable mode follows the WAI-ARIA Combobox pattern:

<!-- Dropdown panel -->
<div
  v-if="isOpen"
  ref="dropdownRef"
  class="mg-select-dropdown"
  role="listbox"
  :aria-label="listboxAriaLabel"
  :aria-activedescendant="focusedIndex >= 0 ? getOptionId(focusedIndex) : undefined"
>
  <!-- Options -->
  <div
    v-for="(item, index) in filteredOptions"
    :id="getOptionId(index)"
    role="option"
    :aria-selected="isSelected(item)"
    :class="{ 'mg-select-option-focused': focusedIndex === index }"
    @click="selectOption(item)"
    @mouseenter="focusedIndex = index"
  >

Supported operations:

ArrowDown / ArrowUp: move highlight (focusedIndex) and scrollIntoView to keep it visible
Enter: select the currently highlighted option
Esc: close the dropdown
Each option has a unique id (based on useId()) for aria-activedescendant reference

2.6 Multiple Selection Mode

Multiple selection (multiple + filterable) turns modelValue into an array. The core branching logic for selection:

// Multiple selection: toggle selection (remove if selected, append if not)
if (props.multiple) {
  const current = multipleValues.value
  const isAlreadySelected = current.some((v) => String(v) === String(value))
  const next = isAlreadySelected
    ? current.filter((v) => String(v) !== String(value))
    : [...current, value]

  modelValue.value = next
  // Multiple selection keeps the dropdown open for continuous selection
  nextTick(() => inputRef.value?.focus())
  return
}

// Single selection: close after selection
modelValue.value = value
closeDropdown()

During multiple selection:

Selected items render as tags; each tag has a delete button with aria-label="Remove {label}"
The dropdown stays open after selection (convenient for continuous multiple selection)
The input only displays search text; selected tags appear outside

3. Pagination: The State Coordinator

3.1 API Design (v1.5.0 Actual)

interface Props {
  totalPages: number // total pages (required)
  modelValue: number // current page (v-model)
  size?: "sm" | "md" | "lg"
  showQuickJump?: boolean // first/last page quick jump buttons (default true)
  prevText?: string // previous page text (uses global i18n)
  nextText?: string
  firstText?: string
  lastText?: string
}

Pagination uses defineModel<number> to bind the current page:

const currentPage = defineModel<number>({ required: true })

3.2 Quick Jump + Page Number Editing

<!-- Display mode: clickable number → enter editing -->
<span v-else class="mg-pagination-current" @click="startEdit">
  {{ currentPage }}
</span>

<!-- Edit mode: input field -->
<input
  v-if="isEditing"
  v-model="inputPage"
  type="number"
  :min="1"
  :max="totalPages"
  @blur="commitJump"
  @keyup.enter="commitJump"
/>

Extreme edge-case defense in commitJump:

const commitJump = () => {
  isEditing.value = false
  const newPage = parseInt(String(inputPage.value), 10)

  // Invalid input: abandon and restore
  if (isNaN(newPage)) {
    inputPage.value = currentPage.value
    return
  }

  goToPage(newPage) // clamp to [1, totalPages]
}

const goToPage = (page: number) => {
  let newPage = page
  if (newPage < 1) newPage = 1
  if (newPage > props.totalPages) newPage = props.totalPages
  if (newPage === currentPage.value) return
  currentPage.value = newPage
  emit("change", newPage)
}

3.3 Global Text (i18n)

v1.5.0 introduced a global text system. All aria-labels and button text in Pagination go through the configuration chain:

const texts = useTexts() // reactive global text

const prevTextValue = computed(
  () => props.prevText ?? texts.value.paginationPrev,
)
const pageInfoLabel = computed(() =>
  formatTemplate(texts.value.paginationPageInfo, {
    current: currentPage.value,
    total: props.totalPages,
  }),
)

Priority: Component prop > setConfig texts > Built-in language text. Text supports {current}/{total} template placeholders.

4. Composable Extraction

Complex components often need to extract shared logic. The core composables in v1.5.0:

4.1 useFormField (Shared by Input/Textarea)

Handles v-model updates + native event passthrough:

export function useFormField(modelValue, emit) {
  const handleInput = (event: Event) => {
    modelValue.value = (event.target as HTMLInputElement).value
    emit("input", event)
  }
  // change/focus/blur native event passthrough
  return { handleInput, handleChange, handleBlur, handleFocus }
}

4.2 useFloating (Shared by Popover/Tooltip)

Custom floating layer positioning engine: viewport flipping + boundary correction + ResizeObserver:

export function useFloating(options: UseFloatingOptions) {
  // Delayed show/hide
  // Position calculation (directional positioning + viewport flipping)
  // Reposition on scroll/window resize
  // ResizeObserver monitors only the floating layer's own size
  // SSR-safe (isBrowser guard)
  return { triggerRef, floatingRef, visible, currentPlacement, floatStyle, show, hide, ... }
}

4.3 useOverlayBehavior (Shared by Modal/Drawer, located in useScrollLock.ts)

Scroll locking + ESC close + focus trap:

// composables/useScrollLock.ts
export function useOverlayBehavior(isOpen, overlayRef, onClose, options) {
  // body scroll lock (module-level lockCount counter, multi-instance safe)
  // ESC key close
  // Tab focus trap
}

This function is defined together with scroll locking logic (lockBodyScroll/unlockBodyScroll) in useScrollLock.ts — scroll lock, ESC close, and focus trap all semantically belong to the "overlay behavior" concern, hence they are placed in the same file.

Module-level lock counting solves scroll lock conflicts when multiple Modal/Drawer instances are open simultaneously — body scrolling is only restored when the last one closes.

5. SSR Adaptation: useId and isBrowser

The SSR adaptation in v1.5.0 is more refined than the initial version, with two core mechanisms:

5.1 useId() Ensures Hydration Safety

All components that require id (Modal/Drawer/Select/Tabs) use Vue 3's useId():

const selectBaseId = useId()
const getOptionId = (index: number): string => `${selectBaseId}-option-${index}`

useId() generates consistent IDs on both server and client, avoiding hydration mismatches.

5.2 isBrowser Guard

All DOM operations include a browser environment guard:

const isBrowser =
  typeof window !== "undefined" && typeof document !== "undefined"

// In watch/onMounted/top-level code:
if (!isBrowser) return

Combined with the module-level counter in useScrollLock.ts, lockBodyScroll() directly skips DOM operations in non-browser environments.

5.3 createOverlay: SSR-Safe Imperative Component

// composables/createOverlay.ts
export function createOverlay(component, props, containerClass) {
  if (!isBrowser) return null // SSR returns null
  // ...
}

6. Data and State Flow

External Data ──► Data Adapter ──► Internal State
(options)        (getLabel/        (selected/
                  getValue)         searchText)
   ▲                                  │
   │                                  ▼
Global Env  ◄── State Coordinator ◄── User Interaction
(i18n/SSR)     (watch/event)        (click/keyboard)

Left column: External input (data + user actions)
Middle: Adaptation and coordination (translating the external world into internal state)
Right column: Internal state (component self-managed)
Bottom: Global environment (i18n / SSR) reverse-constraining component behavior

7. Testing Strategy

The v1.5.0 Select has 40+ tests and Pagination has 14 tests, covering:

Concern	Test Content
Type Backtracking	Native mode number array `[10,20,30]` still produces a number modelValue after selection
ARIA Navigation	`aria-activedescendant` points to highlighted option, each option has a unique id
Keyboard Operations	ArrowDown/Up highlight, Enter select, Esc close, boundary doesn't overflow
Multiple Selection	Tag rendering, toggle selection, tag deletion, Enter continuous multiple selection
Edge Cases	Empty search results, external modelValue change, dropdown stays open on blur
Accessibility	axe-core reports no violations for Select (native + searchable)

Plus SSR checks: renderToString confirms components don't crash on the server and floating layers are hidden by default.

8. Summary

Concern	Simple Component (Button)	Complex Component (Select / Pagination)
Props Count	Fewer (11)	More (10-15)
Data Format	Fixed (string)	Flexible (supports multiple array types, configurable fields, type anti-corruption)
State Management	No internal state	Searchable text, multiple selection array, edit state, dropdown visibility
Accessibility	Native semantics	WAI-ARIA Combobox pattern (listbox/option/activedescendant)
Logic Reuse	Not needed	Composables (useFormField/useFloating/useOverlayBehavior)
SSR Adaptation	Automatic	useId hydration safety + isBrowser guard
i18n	Minimal text	Global configuration chain (prop > setConfig > built-in)
Testing Strategy	Snapshots, event triggers	State combinations, edge cases, keyboard simulation, type backtracking, axe-core

An excellent complex component, internally, should be like a vacuum cleaner — accommodating all kinds of bizarre backend data formats (through key mapping and type backtracking) — and externally, should be like a gentleman — coupling with the global environment (i18n, SSR, keyboard) in a restrained manner. High cohesion, low coupling is fully embodied in these two types of components.

🌙 About Moongate Vue

This article is from the Moongate Vue Component Library Design Series (4 articles), all content is based on real project practice:

Project Repository: github.com/yuelinghuashu/moongate-vue — Minimalist Vue 3 component library, zero dependencies, CSS-first, 25KB gzip
Real-world Example: moongate.top — Personal blog, migrated from Nuxt UI v4 to Moongate Vue
Online Documentation: vue.moongate.top — Component API and theme customization guide

DEV Community: yuelinghuashu

MCP stdio Protocol's 3 Hidden Traps: When All Unit Tests Pass but the MCP Server Won't Respond

TL;DR

Background: story-cli's MCP Server

The Symptom: All Automated Tests Green, But Real Requests Get No Response

Bug #1: The Ghost of process.exit()

Root Cause Investigation

The Fix

The Deeper Lesson

Bug #1.5: The Same Bug Returns — process.exit()'s Second Ghost

The Symptom

Root Cause: The Whitelist-of-Commands Flaw

The Fix: Extract the "Long-Running" Abstraction

The Deeper Lesson: Fix Bugs by Extracting an "Abstraction", Not Enumerating "Instances"

Bug #2: The Fatal Pollution of console.log

The Surprise: After Fixing Bug #1, Some Responses Appeared

Why Can a Single console.log Kill MCP?

The Fix

The Deeper Lesson

Bug #3: The Async Race on readline close

Another Surprise

The Fix

The Deeper Lesson

The Takeaway: Test Layering

Appendix 1: The Complete Debugging Flow (for Reference)

Appendix 2: The MCP Inspector Debugging Tool

Appendix 3: Format Drift in the AI Interaction Layer

Summary: Three Iron Rules + One Meta-Lesson

Flutter Streaming UI: How the Typewriter Experience of AI Replies Is Built

Prologue: a "skip typewriter" button that kept breaking

1. From SSE to screen: the streaming rendering pipeline

Why the LLM "pops" text out

Why you can't update the UI on every chunk

StringBuffer: avoiding O(n²) concatenation

2. The correct semantics of "skip animation": silent accumulation ≠ aborting generation

V1 mistake: only skipping the UI batching window

V2 mistake: triggering the cancel signal

The right answer: silent accumulation, let the LLM finish

A UX gap worth acknowledging

A real fallback flaw

3. Data consistency: interrupted streaming never loses content

4. How to test streaming scenarios

Controllable chunked stream

The three key steps for testing "skip animation without truncation"

Conclusion

Glossary

Flutter Desktop Input Design — Where Does the Enter Key Actually Go?

Prologue: a bug reported by a user

1. The real propagation path of keyboard events

Why the intuition is wrong

The correct mounting point

2. The same "Enter", two key codes

3. The Shift+Enter semantics must not be lost

4. Input history: Widget lifecycle ≠ data lifecycle

Problem: ↑ / ↓ stops working after leaving and re-entering

The right approach: state lifting + persistence

A design decision: global sharing, or per-contract isolation?

5. How to test these interaction boundaries

Keyboard events: simulating the desktop platform

The FakeAsync limitation: real async IO doesn't complete automatically

Conclusion

Glossary

Three Attempts to Refactor a Large Flutter State Class — and the Final Solution

1. When Do You Know It's Time to Split?

2. Attempt 1: Extract Mixins → Blocked by Library-Private Visibility

Why?

Clarification: The Problem Isn't Mixins — It's Cross-File

3. Attempt 2: Use part → Blocked by Missing this

So When Is part Actually the Right Tool?

4. Final Solution: Widget Composition — Back to the Framework Philosophy (and a Reasonable Boundary)

Core Principle

Implementation

Why This Is "The Flutter Way"

Why We Stopped Here (and Didn't Extract a Coordinator)

5. Decision Tree: Which Approach to Choose

6. Engineering Safeguards for Landing the Refactor

Summary

LLM Narrative Engines, Part 6: Runtime Loop and Branching

I. A Narrative Engine's Fifth Problem: How Do You Bring Rules to Life?

II. Novel-Grade Terminal Output: Full-Width Indentation and Streaming Interception

Why Can a Single `console.log` Kill MCP?

3. Attempt 2: Use `part` → Blocked by Missing `this`

So When Is `part` Actually the Right Tool?

III. Interpolation Syntax: Recognizing and Replacing `{variable}`

3.1 Why Only `{角色名}`?