dsh-pet-live2d-viola 1.0.0

package/lib/machine.js

@@ -0,0 +1,279 @@
+/**
+ * The pet's session-driven state machine.
+ *
+ * It consumes host session events and reduces them to one coarse phase plus a
+ * monotonically increasing `revision`. The browser polls the phase and fires a
+ * motion/expression whenever `revision` advances; keeping the mapping in one
+ * place means the client never guesses intent from a bare phase name.
+ * @module dsh-pet-live2d-viola/machine
+ */
+
+/**
+ * Phase definitions: the motion the pet plays on entering each phase, what it
+ * says, and which motions it drifts through while the phase lasts. Motion names
+ * are the model's own motion groups (`<group>_C` is the centre/body part, `_L`/`_R`
+ * the additive layers).
+ *
+ * There is deliberately NO expression here. Her face changes only when one is
+ * picked from the menu, so a phase change moves her body and leaves the chosen
+ * expression alone.
+ *
+ * `idleMotions` is the set the pet picks from at random for the phase's STEADY
+ * state, distinct from `motion`, the one-shot flourish on entering it. A phase
+ * such as `working` can last minutes, so without this the pet would fall back to
+ * the neutral idle drift the moment the entry clip ended and stop looking busy.
+ *
+ * The entry clip plays at NORMAL priority and the drift at IDLE, so the flourish
+ * always wins when both come due.
+ */
+export const PHASES = {
+	idle: {
+		/**
+		 * Every phase carries text, including idle. It is not a transient message: while she is
+		 * idle this is what the bubble reads, so the window is never blank during the state she
+		 * spends most of her time in.
+		 */
+		bubble: "待机中…",
+		motion: "mtn_idle01_C",
+		/**
+		 * EMPTY on purpose: the drift is parked until Viola's own motions are chosen. An empty pool
+		 * makes the drift a no-op, so she stands still rather than playing another character's set.
+		 *
+		 * The client mirrors this list exactly — `verify-phases` compares the two, because a drift set
+		 * that only exists on one side silently does nothing. The client additionally weights them by
+		 * clip length; see IDLE_WEIGHTS there.
+		 */
+		idleMotions: [],
+		label: "idle"
+	},
+	/** The user just spoke: an acknowledging nod. */
+	listening: {
+		/**
+		 * Matches the voice line played on entry, so what is written is what is heard.
+		 *
+		 * Taken from the character's own `VoiceLive_14/Live_Miyako_Start_01` (繁体中文 line
+		 * 「准备已经做好了」), which is what the client plays alongside it.
+		 */
+		bubble: "准备已经做好了",
+		motion: "mtn_nod02_C",
+		/*
+		 * Nodding while the message is being taken in. Randomised like the other short phases: a
+		 * message is acknowledged in LISTEN_HOLD_MS (1.4 s), far less than the drift interval, so a
+		 * fixed entry motion would leave the second clip unreachable.
+		 *
+		 * These are the two nods — `nod02` (3.47 s) and `nod01` (2.70 s). `nod03` is deliberately not
+		 * used here.
+		 */
+		randomMotions: ["mtn_nod02_C", "mtn_nod01_C"],
+		idleMotions: ["mtn_nod02_C", "mtn_nod01_C"],
+		label: "listening"
+	},
+	/**
+	 * The model is reasoning: one of three poses, chosen at random.
+	 *
+	 * No bubble. This phase used to read 「让我想想…」 on a loop for as long as the model took, which
+	 * says nothing the user cannot already see — the pet is visibly thinking. The field is kept as an
+	 * empty string rather than deleted so the table shape stays uniform, and the client already hides
+	 * the bubble when a phase carries no text.
+	 *
+	 * The occasional spoken line still shows its own caption: those go through the overlay window, not
+	 * through this field, so removing the bubble does not silence them.
+	 */
+	thinking: {
+		bubble: "",
+		motion: "mtn_thinking01_C",
+		/*
+		 * Randomised for the same reason as `done`: the drift does not fire for at least 9 s, and a
+		 * thinking spell is usually shorter than that, so the drift set was effectively unreachable
+		 * and every spell opened with the identical pose.
+		 */
+		randomMotions: ["mtn_thinking01_C", "mtn_serious01_C", "mtn_question01_C"],
+		idleMotions: ["mtn_thinking01_C", "mtn_serious01_C", "mtn_question01_C"],
+		label: "thinking"
+	},
+	/** A tool call is in flight: one of three poses, chosen at random. Silent, like `thinking`. */
+	working: {
+		bubble: "",
+		motion: "mtn_serious01_C",
+		// EMPTY on purpose, like `idle`: parked until Viola's own working motions are chosen.
+		randomMotions: [],
+		idleMotions: [],
+		label: "working"
+	},
+	/**
+	 * A turn finished: one of three celebrations, chosen at random.
+	 *
+	 * No phase bubble. It said 「完成啦！」 on every completion, which the celebration itself already
+	 * communicates — and a caption that is always the same stops being information.
+	 *
+	 * The spoken line still shows its own caption: those go through the overlay window, not through this
+	 * field, so removing the phase text does not silence her.
+	 */
+	done: {
+		bubble: "",
+		motion: "mtn_kime01_C",
+		/**
+		 * The celebration actually played, picked at random each time.
+		 *
+		 * A single fixed `motion` was the whole problem: `done` only lasts TRANSIENT_HOLD_MS, and the
+		 * drift does not fire for at least 9 s, so the three-motion set below could never be reached
+		 * — every completion played `kime01` and nothing else. The client picks one of these on
+		 * entry instead.
+		 *
+		 * `motion` is kept as the fallback for a client that does not know about this field, and so
+		 * the "every phase has an entry motion" invariant still holds.
+		 */
+		randomMotions: ["mtn_check01_C", "mtn_nod02_C", "mtn_kime01_C"],
+		idleMotions: ["mtn_check01_C", "mtn_nod02_C", "mtn_kime01_C"],
+		label: "done"
+	},
+	/** Something errored: one of four reactions, chosen at random. */
+	error: {
+		bubble: "出错了…我再试试",
+		motion: "mtn_sad01_C",
+		/**
+		 * Same reasoning as `done`: this phase also settles after TRANSIENT_HOLD_MS, which is far
+		 * shorter than the drift interval, so a fixed entry motion left the drift set unreachable and
+		 * every failure looked identical.
+		 */
+		randomMotions: ["mtn_denial01_C", "mtn_angry01_C", "mtn_cry01_C", "mtn_sad01_C"],
+		idleMotions: ["mtn_denial01_C", "mtn_angry01_C", "mtn_cry01_C", "mtn_sad01_C"],
+		label: "error"
+	}
+};
+
+/** How long a transient phase (done/error) holds before settling back to idle. */
+export const TRANSIENT_HOLD_MS = 2600;
+
+/**
+ * How long the `listening` pose is guaranteed to stay up. A real turn often
+ * starts within a few hundred milliseconds of the user's message, and without
+ * this hold the nod would be replaced before it is visible.
+ */
+export const LISTEN_HOLD_MS = 1400;
+
+/** The state machine: pure bookkeeping, no timers of its own. */
+export class PetMachine {
+	/** @param options - hold durations, overridable from plugin config. */
+	constructor(options = {}) {
+		this.phase = "idle";
+		this.revision = 0;
+		this.lastEventAt = 0;
+		this.sessions = new Set();
+		this.liveSessions = 0;
+		this.holdUntil = 0;
+		this.settleTimer = null;
+		this.transientHoldMs = options.transientHoldMs ?? TRANSIENT_HOLD_MS;
+		this.listenHoldMs = options.listenHoldMs ?? LISTEN_HOLD_MS;
+		this.timer = options.timer ?? { set: (fn, ms) => setTimeout(fn, ms), clear: (handle) => clearTimeout(handle) };
+	}
+
+	/** Move to a phase, bumping the revision only on a real change. */
+	enter(phase, nowMs, options = {}) {
+		if (PHASES[phase] === undefined) return false;
+		const changed = this.phase !== phase;
+		const forced = options.force === true;
+		if (!changed && !forced) return false;
+		this.phase = phase;
+		this.revision += 1;
+		this.lastEventAt = nowMs;
+		this.holdUntil = options.holdMs === undefined ? 0 : nowMs + options.holdMs;
+		this.clearSettle();
+		if (phase === "done" || phase === "error") {
+			this.settleTimer = this.timer.set(() => {
+				this.settleTimer = null;
+				/*
+				 * Always settle, regardless of live sessions.
+				 *
+				 * This used to return early while `liveSessions > 0`, which meant the phase never
+				 * left `done` in normal use — the GUI holds a session open for as long as it is
+				 * running, so the condition was effectively always true. The pet then stayed on the
+				 * `done` animation set forever, and because that set is what the idle drift picks
+				 * from, she kept replaying the completion flourish instead of going back to resting.
+				 *
+				 * Waiting for work to finish belongs to the activity events, which move the phase to
+				 * `thinking`/`working` on their own; this timer only ends the flourish.
+				 */
+				this.enter("idle", Date.now());
+			}, this.transientHoldMs);
+		}
+		return true;
+	}
+
+	/** Cancel a pending settle-to-idle. */
+	clearSettle() {
+		if (this.settleTimer !== null) {
+			this.timer.clear(this.settleTimer);
+			this.settleTimer = null;
+		}
+	}
+
+	/** Track a session becoming live. */
+	onSessionActive(sessionId) {
+		if (sessionId !== undefined) this.sessions.add(sessionId);
+		this.liveSessions = this.sessions.size;
+	}
+
+	/** Track a session ending. */
+	onSessionDisposed(sessionId) {
+		if (sessionId !== undefined) this.sessions.delete(sessionId);
+		else this.sessions.clear();
+		this.liveSessions = this.sessions.size;
+		if (this.liveSessions === 0 && (this.phase === "thinking" || this.phase === "working" || this.phase === "listening")) {
+			this.enter("idle", Date.now());
+		}
+	}
+
+	/**
+	 * Reduce one host session event to a phase transition. Unknown events are
+	 * ignored, so a new core event type can never break the pet.
+	 * @returns whether the phase changed.
+	 */
+	onSessionEvent(event, nowMs = Date.now()) {
+		const type = event?.type;
+		const data = event?.data ?? {};
+		switch (type) {
+			case "user/message":
+				if (data.source?.kind !== undefined && data.source.kind !== "user") return false;
+				return this.enter("listening", nowMs, { holdMs: this.listenHoldMs, force: true });
+			case "turn/start":
+				if (nowMs < this.holdUntil) return false;
+				return this.enter("thinking", nowMs);
+			case "step/start":
+				if (nowMs < this.holdUntil) return false;
+				return this.enter("thinking", nowMs);
+			case "tool/call":
+				return this.enter("working", nowMs);
+			case "tool/result":
+				if (this.phase !== "working") return false;
+				return this.enter("thinking", nowMs);
+			case "turn/end":
+				return this.enter("done", nowMs, { holdMs: this.transientHoldMs, force: true });
+			case "error":
+				return this.enter("error", nowMs, { holdMs: this.transientHoldMs, force: true });
+			default:
+				return false;
+		}
+	}
+
+	/** Snapshot for the API/`view()` layer. */
+	view(nowMs = Date.now()) {
+		const definition = PHASES[this.phase] ?? PHASES.idle;
+		const settled = this.holdUntil !== 0 && nowMs >= this.holdUntil;
+		return {
+			phase: this.phase,
+			revision: this.revision,
+			bubble: definition.bubble,
+			holding: !settled && this.holdUntil !== 0,
+			sessions: this.liveSessions,
+			lastEventAt: this.lastEventAt
+		};
+	}
+
+	/** Release the settle timer. */
+	dispose() {
+		this.clearSettle();
+		this.sessions.clear();
+		this.liveSessions = 0;
+	}
+}

package/lib/persist.js

@@ -0,0 +1,183 @@
+/**
+ * Persistence for the Live2D pet: one small JSON file under $DSH_HOME holding
+ * the layout the user dragged/resized the pet into, plus its name. Deliberately
+ * minimal — atomic rename writes, tolerant reads (a missing or corrupt file
+ * falls back to defaults) — so a bad file can never keep the pet from loading.
+ * @module dsh-pet-live2d-viola/persist
+ */
+
+import { join } from "node:path";
+
+/** How much of the character the pet surface frames. */
+export const CROP_PRESETS = ["full", "threeQuarter", "bust"];
+/** Default framing: the whole character, so nothing is ever cut off. */
+export const DEFAULT_CROP = "full";
+
+/**
+ * Layout defaults.
+ *
+ * The horizontal offset is NOT the usual corner position: this pet is meant to stand beside the other
+ * Live2D pet, and both would otherwise default to `right: 32` and land on exactly the same spot.
+ *
+ * The other pet's surface is `height * SURFACE_ASPECT` wide — 360 * 0.8357 ≈ 301 px — so 370 clears her by
+ * a small margin. Matching `bottom` keeps the two on a shared ground line rather than at different heights,
+ * which is what makes them read as standing next to each other.
+ */
+export const DEFAULT_LAYOUT = {
+	visible: true,
+	height: 360,
+	right: 370,
+	bottom: 16,
+	locked: false,
+	scale: 1,
+	opacity: 1,
+	crop: DEFAULT_CROP,
+	/**
+	 * Draw the framing boundary around the surface.
+	 *
+	 * Off by default: it is a diagnostic overlay for seeing where the surface ends
+	 * and how the character sits inside it, not something a user wants on all the
+	 * time. Purely visual — it never receives pointer events, so toggling it cannot
+	 * change dragging, zooming or tapping.
+	 */
+	showFrame: false,
+	/**
+	 * Automatic eye blinking.
+	 *
+	 * ON by default. This model declares no `EyeBlink` group in its `model3.json`, so the runtime
+	 * never builds a blink controller and she does not blink out of the box — the client supplies
+	 * its own against the standard `ParamEyeLOpen` / `ParamEyeROpen`.
+	 */
+	blink: true,
+	/** Eyes and head follow the pointer anywhere on screen. */
+	gaze: true,
+	/**
+	 * Playback volume for every spoken clip, 0..1.
+	 *
+	 * A layout field rather than a separate setting so it persists through the same path as the rest of
+	 * the pet's state and shows up in `GET /api/pet-live2d-viola/state` with no extra plumbing. 0 means muted,
+	 * which is why the clamp range starts at 0 rather than at a positive floor like `opacity` does.
+	 */
+	voiceVolume: 1
+};
+
+/** Default pet name, used until the user renames her. */
+export const DEFAULT_PET_NAME = "viola";
+
+/**
+ * Directory (relative to the package root) holding one subdirectory per character.
+ *
+ * The plugin ships more than one model and switches between them from the menu, so the models live in a
+ * tree keyed by character id rather than in a single fixed directory.
+ */
+export const CHARACTERS_DIR = join("assets", "characters");
+
+/** Character shown on a fresh install. */
+export const DEFAULT_MODEL = "viola";
+
+/** Layout bounds, mirrored by the plugin Config schema and the set-layout route. */
+export const LAYOUT_LIMITS = {
+	height: { min: 120, max: 1200 },
+	inset: { min: 0, max: 100000 },
+	scale: { min: 0.35, max: 2.5 },
+	opacity: { min: 0.15, max: 1 },
+	/** 0 is a legitimate value here — it means "mute the voice" — so the range starts there. */
+	voiceVolume: { min: 0, max: 1 }
+};
+
+/** Clamp a number into a range, tolerating non-finite input. */
+function clampNumber(value, fallback, min, max) {
+	const n = typeof value === "number" && Number.isFinite(value) ? value : fallback;
+	return Math.min(max, Math.max(min, n));
+}
+
+/** Fresh default record. */
+export function emptyPersist() {
+	return { name: DEFAULT_PET_NAME, character: DEFAULT_MODEL, layout: { ...DEFAULT_LAYOUT } };
+}
+
+/** Resolve the persistence directory ($DSH_HOME, else ~/.dsh). */
+export function petHomeDir(env = process.env, home = undefined) {
+	if (typeof env?.DSH_HOME === "string" && env.DSH_HOME !== "") return env.DSH_HOME;
+	return home ?? ".";
+}
+
+/**
+ * Normalize an untrusted layout patch into a valid layout, clamped exactly like
+ * the API route does so persisted and served values never diverge.
+ * @param patch - a partial or malformed layout object.
+ * @param base - the layout to fall back to per field.
+ */
+export function normalizeLayout(patch, base = DEFAULT_LAYOUT) {
+	const raw = patch !== null && typeof patch === "object" ? patch : {};
+	return {
+		visible: typeof raw.visible === "boolean" ? raw.visible : base.visible,
+		height: Math.round(clampNumber(raw.height, base.height, LAYOUT_LIMITS.height.min, LAYOUT_LIMITS.height.max)),
+		right: Math.round(clampNumber(raw.right, base.right, LAYOUT_LIMITS.inset.min, LAYOUT_LIMITS.inset.max)),
+		bottom: Math.round(clampNumber(raw.bottom, base.bottom, LAYOUT_LIMITS.inset.min, LAYOUT_LIMITS.inset.max)),
+		locked: typeof raw.locked === "boolean" ? raw.locked : base.locked,
+		scale: clampNumber(raw.scale, base.scale, LAYOUT_LIMITS.scale.min, LAYOUT_LIMITS.scale.max),
+		opacity: clampNumber(raw.opacity, base.opacity, LAYOUT_LIMITS.opacity.min, LAYOUT_LIMITS.opacity.max),
+		// An unknown framing name degrades to the previous one rather than
+		// reaching the browser, where it would render an unframed model.
+		crop: CROP_PRESETS.includes(raw.crop) ? raw.crop : base.crop,
+		showFrame: typeof raw.showFrame === "boolean" ? raw.showFrame : base.showFrame,
+		blink: typeof raw.blink === "boolean" ? raw.blink : base.blink,
+		gaze: typeof raw.gaze === "boolean" ? raw.gaze : base.gaze,
+		voiceVolume: clampNumber(raw.voiceVolume, base.voiceVolume, LAYOUT_LIMITS.voiceVolume.min, LAYOUT_LIMITS.voiceVolume.max)
+	};
+}
+
+/**
+ * Read the persisted record. Never throws: any unreadable, unparsable or
+ * implausible field degrades to its default.
+ * @param readFile - sync reader (injected so the module stays testable).
+ * @param file - absolute path of the state file.
+ */
+export function loadPersist(readFile, file) {
+	let parsed;
+	try {
+		parsed = JSON.parse(readFile(file, "utf8"));
+	} catch {
+		return emptyPersist();
+	}
+	const base = emptyPersist();
+	if (parsed === null || typeof parsed !== "object") return base;
+	const name = typeof parsed.name === "string" && parsed.name.trim() !== "" ? parsed.name.trim().slice(0, 24) : base.name;
+	/*
+	 * The stored character is carried through as a plain string and validated LATER, against the characters
+	 * actually on disk — this function is deliberately filesystem-free so a corrupt file cannot throw. An id
+	 * that no longer exists is therefore caught by the service, which falls back to the default.
+	 */
+	const character = typeof parsed.character === "string" && parsed.character.trim() !== "" ? parsed.character.trim() : base.character;
+	return { name, character, layout: normalizeLayout(parsed.layout, base.layout) };
+}
+
+/**
+ * Write the record atomically (temp file + rename) so a crash mid-write cannot
+ * leave a truncated state file behind.
+ *
+ * `io` is a PORT, not a set of `fs` functions: its keys must be `mkdir`, `writeFile` and `rename`. Reading the keys
+ * off `fs` by their own names does not work, and that is exactly how the pet's settings were lost — the call site
+ * passed `{ mkdirSync, writeFileSync, renameSync }` while this function reads `io.mkdir`, `io.writeFile` and
+ * `io.rename`, so every write threw `TypeError: io.mkdir is not a function`, the `catch` swallowed it, and this
+ * returned false. Nothing checks the return value, so the failure was completely silent: measured, the state
+ * directory was still absent after a full session of dragging, resizing and switching character.
+ *
+ * @param io - `{ mkdir(dir), writeFile(path, data, encoding), rename(from, to) }`.
+ * @param file - destination path.
+ * @param dir - directory to create first, including parents.
+ * @param record - the value to serialise.
+ * @returns whether the write succeeded. Callers should surface a false.
+ */
+export function savePersist(io, file, dir, record) {
+	try {
+		io.mkdir(dir);
+		const tmp = `${file}.tmp`;
+		io.writeFile(tmp, `${JSON.stringify(record, null, 2)}\n`, "utf8");
+		io.rename(tmp, file);
+		return true;
+	} catch {
+		return false;
+	}
+}

package/lib/routes.js

@@ -0,0 +1,206 @@
+/**
+ * Host HTTP surfaces of the Live2D pet: the model asset tree and a tiny JSON
+ * API the browser polls.
+ *
+ * Assets are served from a prefix route (`/pet-live2d-viola/assets/<model>/*`) so the
+ * whole Cubism tree — model3.json, moc3, physics, motions, expressions, WebP
+ * textures — resolves with plain relative fetches, exactly as the Live2D
+ * runtime expects. Paths are resolved and re-checked against the asset root, so
+ * encoded traversal cannot escape it.
+ * @module dsh-pet-live2d-viola/routes
+ */
+
+import { createReadStream, statSync } from "node:fs";
+import { extname, join, normalize, resolve, sep } from "node:path";
+
+/** Browser-facing base path of the pet API. */
+export const PET_API_PREFIX = "/api/pet-live2d-viola";
+/** Browser-facing base path of the model asset tree. */
+export const PET_ASSET_PREFIX = "/pet-live2d-viola/assets";
+
+/** Browser-facing base path of the voice clip tree. */
+export const PET_VOICE_PREFIX = "/pet-live2d-viola/voice";
+
+/** Browser-facing base path of the click sound. */
+export const PET_CLICK_PREFIX = "/pet-live2d-viola/click";
+
+/** Content types for every file kind a Cubism model tree contains. */
+const MIME = {
+	".json": "application/json; charset=utf-8",
+	".moc3": "application/octet-stream",
+	".png": "image/png",
+	".webp": "image/webp",
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".mp3": "audio/mpeg",
+	".opus": "audio/ogg",
+	".wav": "audio/wav",
+	".ogg": "audio/ogg",
+	".txt": "text/plain; charset=utf-8"
+};
+
+/** One JSON response, never cached (the pet's state is polled). */
+function sendJson(res, status, body) {
+	const text = JSON.stringify(body);
+	res.writeHead(status, {
+		"content-type": "application/json; charset=utf-8",
+		"content-length": String(Buffer.byteLength(text)),
+		"cache-control": "no-store"
+	});
+	res.end(text);
+}
+
+/** Read a bounded JSON request body. */
+function readJsonBody(req, limit = 32 * 1024) {
+	return new Promise((resolveBody, rejectBody) => {
+		const chunks = [];
+		let size = 0;
+		req.on("data", (chunk) => {
+			size += chunk.length;
+			if (size > limit) {
+				rejectBody(new Error("body-too-large"));
+				req.destroy();
+				return;
+			}
+			chunks.push(chunk);
+		});
+		req.on("end", () => {
+			if (chunks.length === 0) {
+				resolveBody({});
+				return;
+			}
+			try {
+				resolveBody(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+			} catch {
+				rejectBody(new Error("invalid-json"));
+			}
+		});
+		req.on("error", rejectBody);
+	});
+}
+
+/** Wrap an async JSON handler as a route handler. */
+function jsonRoute(method, path, run) {
+	return {
+		kind: "exact",
+		path,
+		handler: (req, res) => {
+			if (req.method !== method) {
+				sendJson(res, 405, { ok: false, error: "method-not-allowed" });
+				return;
+			}
+			const body = method === "POST" ? readJsonBody(req) : Promise.resolve({});
+			body
+				.then((parsed) => run(parsed))
+				.then(
+					(value) => sendJson(res, 200, value),
+					(error) => sendJson(res, 400, { ok: false, error: error instanceof Error ? error.message : String(error) })
+				);
+		}
+	};
+}
+
+/**
+ * Resolve one request path under the asset root, or `undefined` when it escapes.
+ * @param assetRoot - absolute asset directory.
+ * @param relative - the URL path after the prefix, already percent-decoded.
+ */
+export function resolveAsset(assetRoot, relative) {
+	const cleaned = normalize(relative).replace(/^([/\\])+/, "");
+	const target = resolve(join(assetRoot, cleaned));
+	const root = resolve(assetRoot);
+	if (target !== root && !target.startsWith(root + sep)) return undefined;
+	return target;
+}
+
+/**
+ * Build a read-only prefix route that serves one directory tree.
+ *
+ * Extracted so the model assets and the voice clips share one tested implementation: the path
+ * normalisation in {@link resolveAsset} is the security-relevant part, and duplicating it would
+ * mean two places to get the same traversal guard wrong.
+ *
+ * @param prefix - browser-facing base path, e.g. `/pet-live2d-viola/assets`.
+ * @param root - absolute directory to serve.
+ * @param immutableHint - the cache-control comment shown in the header block.
+ */
+function staticTreeRoute(prefix, root, immutableHint) {
+	return {
+		kind: "prefix",
+		path: prefix,
+		handler: (req, res) => {
+			if (req.method !== "GET" && req.method !== "HEAD") {
+				res.writeHead(405).end();
+				return;
+			}
+			let relative;
+			try {
+				relative = decodeURIComponent(new URL(req.url, "http://localhost").pathname.slice(prefix.length));
+			} catch {
+				res.writeHead(400).end();
+				return;
+			}
+			const file = resolveAsset(root, relative);
+			const stat = file === undefined ? undefined : statSync(file, { throwIfNoEntry: false });
+			if (file === undefined || stat?.isFile() !== true) {
+				res.writeHead(404, { "content-type": "text/plain; charset=utf-8" }).end("not found");
+				return;
+			}
+			res.writeHead(200, {
+				"content-type": MIME[extname(file).toLowerCase()] ?? "application/octet-stream",
+				"content-length": String(stat.size),
+				"cache-control": "public, max-age=86400",
+				// The tree is immutable for a given package version.
+				"x-immutable": immutableHint
+			});
+			if (req.method === "HEAD") {
+				res.end();
+				return;
+			}
+			createReadStream(file).pipe(res);
+		}
+	};
+}
+
+/**
+ * Build every route for one pet host.
+ * @param deps - the pet service plus the absolute asset, voice and click roots.
+ * @returns route objects ready for `ctx.webServer.register`.
+ */
+export function makePetRoutes(deps) {
+	const { pet, assetRoot, voiceRoot, clickRoot } = deps;
+
+	const api = [
+		jsonRoute("GET", `${PET_API_PREFIX}/state`, () => pet.view()),
+		// The full phase table, so the animation set for every work state can be inspected
+		// without driving the session through each one.
+		jsonRoute("GET", `${PET_API_PREFIX}/phases`, () => ({ ok: true, phases: pet.phaseTable() })),
+		jsonRoute("POST", `${PET_API_PREFIX}/layout`, (body) => pet.setLayout(body)),
+		jsonRoute("POST", `${PET_API_PREFIX}/name`, (body) => pet.setName(body?.name)),
+		jsonRoute("POST", `${PET_API_PREFIX}/event`, (body) => pet.reportClientEvent(body))
+	];
+
+	/*
+	 * The voice clips get their own prefix rather than a folder inside the model tree.
+	 *
+	 * The model is addressed as `/pet-live2d-viola/assets/<settingsFile>`, so `assetRoot` has to BE the
+	 * model directory; adding a sibling folder under it would both pollute that tree and make the
+	 * model's own paths depend on where the voice files happen to sit.
+	 */
+	const routes = [
+		...api,
+		staticTreeRoute(PET_ASSET_PREFIX, assetRoot, "model")
+	];
+	if (typeof voiceRoot === "string" && voiceRoot !== "") {
+		routes.push(staticTreeRoute(PET_VOICE_PREFIX, voiceRoot, "voice"));
+	}
+	/*
+	 * The click sound gets its own prefix for the same reason the voice clips do, plus one more: it is a
+	 * different MEDIA TYPE (`.mp3`, not `.opus`), and keeping it out of the voice tree means the voice
+	 * directory stays "the spoken lines" rather than "audio of any kind".
+	 */
+	if (typeof clickRoot === "string" && clickRoot !== "") {
+		routes.push(staticTreeRoute(PET_CLICK_PREFIX, clickRoot, "click"));
+	}
+	return routes;
+}