@polycode-projects/the-mechanical-code-talker 3.2.0 → 4.0.0

package/src/adapters/p2p/webrtc-transport.mjs

@@ -0,0 +1,146 @@
+// One WebRTC DataChannel between two browsers, and nothing else. The caller
+// carries the offer and answer SDP strings between the two machines however it
+// likes — a link, a paste, an already-open channel to a third peer — and this
+// module never learns what travels over the channel once it is open: it takes
+// plain JS values in and hands plain JS values out.
+//
+// `connectionState` is a live GETTER PROPERTY, not a method: read
+// `transport.connectionState`, never `transport.connectionState()`. It reports
+// RTCPeerConnection's own state ("new" | "connecting" | "connected" | "failed"
+// | "closed"), so a caller can poll it without registering a handler.
+//
+// `iceServers` defaults to [] and this design keeps it empty: no STUN, no
+// TURN, no third party in the loop at all. Peers that cannot already reach
+// each other directly (same machine, same LAN, or a NAT that allows it) never
+// finish the handshake, which is the stated boundary of staying serverless.
+//
+// Both `createOffer` and `createAnswerFor` resolve only once ICE gathering has
+// completed, so the SDP string they return already carries every candidate.
+// Nothing here trickles, because a pasted blob is a one-shot message rather
+// than a live connection back to the other side.
+//
+// Late handler registration still fires: `onOpen` on an already-open channel
+// and `onClose` on an already-closed one call back immediately, so a caller
+// that registers after the transition never silently misses it. Each fires at
+// most once.
+
+const CHANNEL_LABEL = "tmct";
+
+export function createTransport({ iceServers = [] } = {}) {
+  const PeerConnection = globalThis.RTCPeerConnection;
+  if (typeof PeerConnection !== "function") {
+    throw new Error("no RTCPeerConnection here: this transport runs in a browser, not in bare node");
+  }
+
+  const connection = new PeerConnection({ iceServers });
+  const messageHandlers = [];
+  const openHandlers = [];
+  const closeHandlers = [];
+
+  let channel = null;
+  let openAnnounced = false;
+  let closeAnnounced = false;
+  let tornDown = false;
+
+  function announceOpen() {
+    if (openAnnounced) return;
+    openAnnounced = true;
+    for (const handler of openHandlers) handler();
+  }
+
+  function announceClose() {
+    if (closeAnnounced) return;
+    closeAnnounced = true;
+    for (const handler of closeHandlers) handler();
+  }
+
+  function receive(event) {
+    let value;
+    try {
+      value = JSON.parse(event.data);
+    } catch {
+      // A peer sending something that isn't JSON must not be able to throw
+      // inside our receive path, so the frame is dropped rather than raised.
+      return;
+    }
+    for (const handler of messageHandlers) handler(value);
+  }
+
+  function attachChannel(dataChannel) {
+    channel = dataChannel;
+    dataChannel.addEventListener("open", announceOpen);
+    dataChannel.addEventListener("close", announceClose);
+    dataChannel.addEventListener("message", receive);
+    if (dataChannel.readyState === "open") announceOpen();
+  }
+
+  connection.addEventListener("datachannel", (event) => attachChannel(event.channel));
+  connection.addEventListener("connectionstatechange", () => {
+    const state = connection.connectionState;
+    if (state === "failed" || state === "closed") announceClose();
+  });
+
+  async function whenIceGatheringCompletes() {
+    if (connection.iceGatheringState === "complete") return;
+    await new Promise((resolve) => {
+      const settle = () => {
+        if (connection.iceGatheringState !== "complete") return;
+        connection.removeEventListener("icegatheringstatechange", settle);
+        resolve();
+      };
+      connection.addEventListener("icegatheringstatechange", settle);
+    });
+  }
+
+  return {
+    async createOffer() {
+      attachChannel(connection.createDataChannel(CHANNEL_LABEL));
+      await connection.setLocalDescription(await connection.createOffer());
+      await whenIceGatheringCompletes();
+      return connection.localDescription.sdp;
+    },
+
+    async createAnswerFor(offerSdp) {
+      await connection.setRemoteDescription({ type: "offer", sdp: offerSdp });
+      await connection.setLocalDescription(await connection.createAnswer());
+      await whenIceGatheringCompletes();
+      return connection.localDescription.sdp;
+    },
+
+    async completeWithAnswer(answerSdp) {
+      await connection.setRemoteDescription({ type: "answer", sdp: answerSdp });
+    },
+
+    send(data) {
+      const state = channel ? channel.readyState : "missing";
+      if (state !== "open") throw new Error(`cannot send over a data channel that is ${state}`);
+      channel.send(JSON.stringify(data));
+    },
+
+    onMessage(handler) {
+      messageHandlers.push(handler);
+    },
+
+    onOpen(handler) {
+      openHandlers.push(handler);
+      if (openAnnounced) handler();
+    },
+
+    onClose(handler) {
+      closeHandlers.push(handler);
+      if (closeAnnounced) handler();
+    },
+
+    close() {
+      if (tornDown) return;
+      tornDown = true;
+      channel?.close();
+      connection.close();
+      announceClose();
+    },
+
+    get connectionState() {
+      return connection.connectionState;
+    },
+  };
+}

package/src/domain/game-config.mjs

@@ -27,6 +27,35 @@ export const DEFAULT_GAME_CONFIG = Object.freeze({
     minHatchlingMass: 3,
     webDurationTurns: 10,
   }),
+  // The drains are what make a mud character mortal: every scripted turn
+  // charges one, and a character whose mass reaches zero starves and takes no
+  // more turns. They are sized against the demo page's own default run (400
+  // shared turns, so roughly 200 each for two animals) — an animal that never
+  // eats dies about two thirds of the way through, and one that forages does
+  // not. A drain that emptied a starting mass in twenty turns would end every
+  // run before it had shown anything.
+  mud: Object.freeze({
+    moleInitialMass: 8,
+    moleMassDecrementPerTurn: 0.06,
+    moleSpeed: 1,
+    moleDigReach: 1,
+    voleInitialMass: 6,
+    voleMassDecrementPerTurn: 0.05,
+    voleSpeed: 1,
+    voleDigReach: 1,
+    badgerInitialMass: 20,
+    badgerMassDecrementPerTurn: 0.08,
+    badgerSpeed: 2,
+    badgerDigReach: 2,
+    groundhogInitialMass: 12,
+    groundhogMassDecrementPerTurn: 0.06,
+    groundhogSpeed: 2,
+    groundhogDigReach: 2,
+    meerkatInitialMass: 9,
+    meerkatMassDecrementPerTurn: 0.05,
+    meerkatSpeed: 1,
+    meerkatDigReach: 1,
+  }),
   guessNumber: Object.freeze({
     defaultLo: 1,
     defaultHi: 100,
@@ -55,6 +84,29 @@ const SPIDER_FLY_KEY_MAP = Object.freeze({
   web_duration_turns: "webDurationTurns",
 });
 
+const MUD_KEY_MAP = Object.freeze({
+  mole_initial_mass: "moleInitialMass",
+  mole_mass_decrement_per_turn: "moleMassDecrementPerTurn",
+  mole_speed: "moleSpeed",
+  mole_dig_reach: "moleDigReach",
+  vole_initial_mass: "voleInitialMass",
+  vole_mass_decrement_per_turn: "voleMassDecrementPerTurn",
+  vole_speed: "voleSpeed",
+  vole_dig_reach: "voleDigReach",
+  badger_initial_mass: "badgerInitialMass",
+  badger_mass_decrement_per_turn: "badgerMassDecrementPerTurn",
+  badger_speed: "badgerSpeed",
+  badger_dig_reach: "badgerDigReach",
+  groundhog_initial_mass: "groundhogInitialMass",
+  groundhog_mass_decrement_per_turn: "groundhogMassDecrementPerTurn",
+  groundhog_speed: "groundhogSpeed",
+  groundhog_dig_reach: "groundhogDigReach",
+  meerkat_initial_mass: "meerkatInitialMass",
+  meerkat_mass_decrement_per_turn: "meerkatMassDecrementPerTurn",
+  meerkat_speed: "meerkatSpeed",
+  meerkat_dig_reach: "meerkatDigReach",
+});
+
 const GUESS_NUMBER_KEY_MAP = Object.freeze({
   default_lo: "defaultLo",
   default_hi: "defaultHi",
@@ -77,6 +129,20 @@ function mergeSection(defaults, raw, keyMap) {
   return out;
 }
 
+/** The species a mud character id names — "mole-1" -> "mole" — which is how
+ *  every per-species knob above is keyed. Pure. */
+export function mudSpeciesOf(characterId) {
+  return String(characterId).replace(/-\d+$/, "");
+}
+
+/** What one turn costs `characterId` in mass, from the resolved `mud` section.
+ *  Zero for a species the config carries no drain for: a knob nobody set is not
+ *  a reason to invent a number and starve something with it. Pure. */
+export function mudMassDrainPerTurn(mudConfig, characterId) {
+  const drain = mudConfig?.[`${mudSpeciesOf(characterId)}MassDecrementPerTurn`];
+  return Number.isFinite(drain) ? drain : 0;
+}
+
 /**
  * Fold a normalized tmct.toml's `games`/`planning` tables (the raw sparse
  * pass-through src/adapters/toml-config.mjs's normalizeConfig produces —
@@ -90,6 +156,7 @@ export function resolveGameConfig(toml) {
   const games = toml?.games ?? {};
   return {
     spiderFly: mergeSection(DEFAULT_GAME_CONFIG.spiderFly, games["spider-fly"], SPIDER_FLY_KEY_MAP),
+    mud: mergeSection(DEFAULT_GAME_CONFIG.mud, games.mud, MUD_KEY_MAP),
     guessNumber: mergeSection(DEFAULT_GAME_CONFIG.guessNumber, games["guess-number"], GUESS_NUMBER_KEY_MAP),
     planning: mergeSection(DEFAULT_GAME_CONFIG.planning, toml?.planning, PLANNING_KEY_MAP),
   };

package/src/domain/grammar/ace.mjs

@@ -525,7 +525,7 @@ export function parseAce(sentence, lexicon = loadLexicon()) {
 // it is reported back on the command (`corrected`) for the caller to name in
 // its response — a synonym executes silently, a typo fix does not.
 
-const IMPERATIVE_VERBS = new Set(["go", "take", "drop", "open", "unlock", "close", "give", "look", "talk", "examine"]);
+const IMPERATIVE_VERBS = new Set(["go", "take", "drop", "open", "unlock", "close", "give", "look", "talk", "examine", "dig", "eat", "put"]);
 const IMPERATIVE_DIRECTIONS = new Set(["north", "south", "east", "west", "up", "down"]);
 
 // The object pronouns an imperative object slot may carry ("examine it", "take
@@ -665,13 +665,13 @@ export function parseImperative(sentence, lexicon = loadLexicon()) {
     if (object.term == null) return miss(object.unknown);
     return command({ object: object.term });
   }
-  if (verb === "examine" || verb === "talk") {
+  if (verb === "examine" || verb === "talk" || verb === "eat") {
     if (!rest.length) return null;
     const object = imperativeNP(lexicon, rest);
     if (object.term == null) return miss(object.unknown);
     return command({ object: object.term });
   }
-  if (verb === "go") {
+  if (verb === "go" || verb === "dig") {
     if (rest.length === 1) {
       if (IMPERATIVE_DIRECTIONS.has(lower[0])) return command({ direction: lower[0] });
       const fuzzyDir = fuzzyMatchInSet(lower[0], [...IMPERATIVE_DIRECTIONS], IMPERATIVE_FUZZY_BOUND);
@@ -690,6 +690,14 @@ export function parseImperative(sentence, lexicon = loadLexicon()) {
     if (object.term == null || indirect.term == null) return miss([...object.unknown, ...indirect.unknown]);
     return command({ object: object.term, indirectObject: indirect.term });
   }
+  if (verb === "put") {
+    const inIdx = lower.indexOf("in");
+    if (inIdx < 1 || inIdx === rest.length - 1) return null;
+    const object = imperativeNP(lexicon, rest.slice(0, inIdx));
+    const container = imperativeNP(lexicon, rest.slice(inIdx + 1));
+    if (object.term == null || container.term == null) return miss([...object.unknown, ...container.unknown]);
+    return command({ object: object.term, indirectObject: container.term });
+  }
   if (verb === "unlock") {
     const withIdx = lower.indexOf("with");
     if (withIdx !== -1) {

package/src/domain/grammar/lexicon-core.json

@@ -394,6 +394,9 @@
     "tiger": {},
     "elephant": {},
     "snake": {},
+    "mole": {},
+    "groundhog": {},
+    "meerkat": {},
     "tree": {},
     "flower": {},
     "grass": {},

package/src/domain/grammar/lexicon.mjs

@@ -149,6 +149,19 @@ export function loadLexicon(extra, ns = DEFAULT_NS) {
   return lex;
 }
 
+/** `lexicon` with `names` additionally declared as proper names. The noun,
+ *  verb and adjective maps are SHARED with the base lexicon rather than
+ *  re-ingested — a caller that re-declares on every turn (a live game world
+ *  minting ids as it is played) would otherwise rebuild nine thousand core
+ *  entries to add half a dozen. Proper names outrank every other category, so
+ *  a name with no dictionary reading of its own ("groundhog-1", "carrot-2")
+ *  resolves as itself instead of dying as an undeclared word. */
+export function withProperNames(lexicon, names) {
+  const properNames = new Map(lexicon.properNames);
+  for (const name of names) properNames.set(String(name).toLowerCase(), String(name));
+  return { ...lexicon, properNames };
+}
+
 /** Noun lookup with plural folding; returns the entry ({lemma, property?}) or
  *  null. `opts.singularOnly` (an "a"/"an" determiner) prunes the irregular-
  *  plural fold in favor of a standalone-singular entry when both exist for

package/src/domain/memory/trust.mjs

@@ -40,6 +40,13 @@ function parseChatTagRest(rest) {
  *      same tier the hand-written tier2 corpus already scores at; the :turnN
  *      segment a snapshot write carries records when, not who, and is not
  *      part of the Source identity)
+ *   mud:<character>[:turnN][:gone] -> { kind:"corpus", name:"mud:<character>" }
+ *     (one character's own testimony in a multi-character world — what it told
+ *      someone, what it examined for itself, and with `:gone` what it saw leave
+ *      the world. Same tier as the world, but one Source per character; the
+ *      `mud:` prefix in the name keeps that Source apart from a world of the
+ *      same literal name. Both trailing segments say when and what, not who, so
+ *      neither is part of the Source identity)
  *   ace:chat:<session>@<ts>    -> { kind:"operator",  createdAt:<ts>, sessionId:<session> }
  *   teach:chat:<session>@<ts>  -> { kind:"teach",     createdAt:<ts>, sessionId:<session> }
  *   web:<url> | url:<url>      -> { kind:"web",       url:<url> }
@@ -98,6 +105,14 @@ export function provenanceTagToSource(tag) {
   // authored shipped content scored at the corpus tier; the per-turn tail is
   // dropped from the id so every write of one world corroborates one Source.
   if (head.startsWith("world:")) return { kind: "corpus", name: head.slice("world:".length).split(":")[0] || "unknown" };
+  // mud:<character>[:turnN] — one character's own testimony inside a multi-
+  // character world: what it told another character, and what it saw for
+  // itself. Same corpus tier as the world it stands in, but a Source per
+  // CHARACTER, so every claim an animal makes over a whole game accumulates on
+  // that animal's own track record rather than the world's. The name keeps the
+  // `mud:` prefix so `src:corpus:mud:<character>` can never collide with a
+  // `world:<name>` Source that happens to share the literal name.
+  if (head.startsWith("mud:")) return { kind: "corpus", name: `mud:${head.slice("mud:".length).split(":")[0] || "unknown"}` };
   if (head.startsWith("ace:")) return { kind: "operator", ...parseChatTagRest(head.slice("ace:".length)) };
   if (head.startsWith("teach:")) {
     // the chat teach lane's natural frames — chat.mjs's teachProvenanceTag

package/src/domain/p2p/facts.mjs

@@ -0,0 +1,81 @@
+// domain/p2p/facts.mjs — the small set of new predicates the P2P layer
+// introduces on top of the existing memory store's triple shape, plus pure
+// constructors for each. Every one is a plain add-only fact, replicated the
+// same way any other fact is (appendFacts' own union-by-id behavior) — no
+// new CRDT primitive. Provenance uses the existing `ace:` tag shape
+// (`ace:p2p:<id>@<ts>`) so trust.mjs's own parser reads it with no changes
+// there: stripped of its `ace:` prefix it reads as `p2p:<id>@<ts>`, which
+// parses to { kind: "operator", sessionId: "p2p:<id>", createdAt: <ts> }.
+import { provenanceTagToSource } from "../memory/trust.mjs";
+
+export const WORLD_NAME_PREDICATE = "mgx:worldName";
+export const NODE_NAME_PREDICATE = "mgx:nodeName";
+export const PLAYED_BY_PREDICATE = "mgx:playedBy";
+export const WAVED_PREDICATE = "mgx:waved";
+
+export const P2P_PREDICATES = Object.freeze([
+  WORLD_NAME_PREDICATE,
+  NODE_NAME_PREDICATE,
+  PLAYED_BY_PREDICATE,
+  WAVED_PREDICATE,
+]);
+
+const provenanceFor = (id, timestamp) => `ace:p2p:${id}@${timestamp}`;
+
+export function worldNameFact(worldId, name, timestamp) {
+  return { subject: worldId, predicate: WORLD_NAME_PREDICATE, object: name, provenance: provenanceFor(worldId, timestamp) };
+}
+
+export function nodeNameFact(peerId, name, timestamp) {
+  return { subject: `peer:${peerId}`, predicate: NODE_NAME_PREDICATE, object: name, provenance: provenanceFor(peerId, timestamp) };
+}
+
+export function playedByFact(characterId, peerId, timestamp) {
+  return { subject: characterId, predicate: PLAYED_BY_PREDICATE, object: `peer:${peerId}`, provenance: provenanceFor(characterId, timestamp) };
+}
+
+export function waveFact(characterId, roomId, timestamp) {
+  return { subject: characterId, predicate: WAVED_PREDICATE, object: roomId, provenance: provenanceFor(`${characterId}-${roomId}`, timestamp) };
+}
+
+/** The newest asserted-at timestamp across every " | "-joined segment of a
+ *  fact's provenance — the correct read for "when was this most recently
+ *  true," since a repeat wave unions a fresh tag onto the SAME fact id
+ *  (same subject/predicate/object) rather than minting a new row. Returns
+ *  null if no segment parses to a timestamp at all. */
+export function latestProvenanceTimestamp(provenance) {
+  const tag = String(provenance || "");
+  if (!tag) return null;
+  let latest = null;
+  for (const segment of tag.split(" | ")) {
+    const source = provenanceTagToSource(segment);
+    const at = source?.createdAt ? Date.parse(source.createdAt) : NaN;
+    if (!Number.isNaN(at) && (latest === null || at > latest)) latest = at;
+  }
+  return latest;
+}
+
+/** "Currently waving" is a read-time recency question, never a retraction —
+ *  a wave fact older than the window just stops being read as current, with
+ *  nothing ever deleted from the graph. */
+export function isRecentWave(waveFactRow, nowMs, windowMs = 8000) {
+  const at = latestProvenanceTimestamp(waveFactRow?.provenance);
+  if (at === null) return false;
+  const age = nowMs - at;
+  return age >= 0 && age <= windowMs;
+}
+
+/** The latest-by-timestamp fact for a subject+predicate pair — the "current
+ *  value" read for an add-only, no-retraction fact like a node's own name
+ *  or which peer plays a character (first-claim-wins uses the OLDEST of
+ *  these instead; see playedByFact's own caller for that distinction). */
+export function latestFact(rows, subject, predicate) {
+  let best = null;
+  let bestAt = -Infinity;
+  for (const row of rows) {
+    if (row.subject !== subject || row.predicate !== predicate) continue;
+    const at = latestProvenanceTimestamp(row.provenance) ?? -Infinity;
+    if (at > bestAt) { best = row; bestAt = at; }
+  }
+  return best;
+}

package/src/domain/p2p/peer-id.mjs

@@ -0,0 +1,32 @@
+// domain/p2p/peer-id.mjs — pure id/name generation for the P2P layer. No
+// network, no DOM; safe to import from both a Node test and a browser
+// bundle. World/peer ids are UUIDs, generated client-side and never seen by
+// any server. Display names are two words drawn from the same closed-world
+// lexicon that grounds every taught fact, so a name a player sees on screen
+// is always a real word this build's vocabulary already recognizes.
+import { loadLexicon } from "../grammar/lexicon.mjs";
+
+const fallbackId = (prefix) => `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+
+export function generatePeerId() {
+  return globalThis.crypto?.randomUUID?.() ?? fallbackId("peer");
+}
+
+export function generateWorldId() {
+  return globalThis.crypto?.randomUUID?.() ?? fallbackId("world");
+}
+
+/** Two distinct words drawn from the lexicon's own noun list — a mnemonic
+ *  label, not a credential. `random` is injectable for deterministic tests;
+ *  defaults to Math.random. Callers add a numeric suffix themselves if a
+ *  live collision turns up among currently-connected peers — this function
+ *  never guesses at uniqueness on its own. */
+export function generateDisplayName(random = Math.random) {
+  const words = [...loadLexicon().nouns.keys()];
+  if (words.length < 2) return "guest-guest";
+  const pick = () => words[Math.floor(random() * words.length)];
+  const first = pick();
+  let second = pick();
+  while (second === first) second = pick();
+  return `${first}-${second}`;
+}

package/src/domain/p2p/provenance-relabel.mjs

@@ -0,0 +1,26 @@
+// domain/p2p/provenance-relabel.mjs — rewrites a fact's outgoing provenance
+// tag before it's broadcast to peers, so "who taught this" reads as a node
+// name rather than a local session id. Only teach/operator-kind tags are
+// touched; a mud world/testimony tag is already attributed to the world or
+// the character that made it, not the person at the keyboard, and rewriting
+// it would lose information rather than add it.
+import { provenanceTagToSource } from "../memory/trust.mjs";
+
+const RELABELED_KINDS = new Set(["teach", "operator"]);
+
+/** `provenance` may already be a " | "-joined union of several tags (the
+ *  same fact taught more than once, from different sources) — relabel each
+ *  segment independently and rejoin, so a segment this peer didn't author
+ *  passes through untouched. */
+export function relabelForBroadcast(provenance, myDisplayName, timestamp) {
+  const tag = String(provenance || "");
+  if (!tag) return tag;
+  return tag
+    .split(" | ")
+    .map((segment) => {
+      const source = provenanceTagToSource(segment);
+      if (!source || !RELABELED_KINDS.has(source.kind)) return segment;
+      return `teach:peer:${myDisplayName}@${timestamp}`;
+    })
+    .join(" | ");
+}

package/src/domain/p2p/sync-filter.mjs

@@ -0,0 +1,31 @@
+// domain/p2p/sync-filter.mjs — which rows of an already-loaded fact store
+// are worth syncing to a new joiner. Every peer's page ships the identical
+// build-time seed, so those rows already share the same content-addressed
+// ids before any network traffic happens; sending them again is pure waste.
+// What actually needs syncing is the delta: whatever a person or a peer
+// actually added since boot.
+import { provenanceTagToSource } from "../memory/trust.mjs";
+
+const CHAT_SYNCABLE_KINDS = new Set(["teach", "operator"]);
+
+/** chat.html: every fact a human (locally or via a peer) actually taught or
+ *  asserted — never a row from the shipped corpus. */
+export function chatSyncableFacts(rows) {
+  return rows.filter((row) => {
+    const source = provenanceTagToSource(row.provenance);
+    return source ? CHAT_SYNCABLE_KINDS.has(source.kind) : false;
+  });
+}
+
+/** mud.html: every fact that isn't part of the bare, unsuffixed world seed —
+ *  a move, a dig, a piece of testimony, or one of the P2P layer's own new
+ *  predicates (world/node names, character claims, waves). `isMudStatePredicate`
+ *  is injected rather than imported from adventure.mjs directly, so this
+ *  module never needs to know that file's internal predicate names — the
+ *  caller (whoever wires the mud room) supplies it, typically
+ *  `adventure.mjs`'s own exported predicate check, extended to also accept
+ *  this module's own P2P predicates via `extraPredicates`. */
+export function mudSyncableFacts(rows, isMudStatePredicate, extraPredicates = []) {
+  const extra = new Set(extraPredicates);
+  return rows.filter((row) => extra.has(row.predicate) || isMudStatePredicate(row.predicate));
+}

package/src/domain/p2p/wire.mjs

@@ -0,0 +1,123 @@
+// domain/p2p/wire.mjs — pure message shapes and blob encoding for the P2P
+// layer. Two kinds of payload: an "invite blob" carried in a URL or pasted
+// by hand (a base64url-encoded JSON envelope holding one SDP string), and
+// plain JSON messages sent over an already-open DataChannel. Nothing here
+// touches the network or WebRTC itself — src/adapters/p2p/webrtc-transport.mjs
+// owns the connection, src/services/p2p-room.mjs owns what these messages mean.
+
+const INVITE_KINDS = new Set(["offer", "reply"]);
+
+function toBase64Url(str) {
+  const b64 = typeof btoa === "function" ? btoa(str) : Buffer.from(str, "utf8").toString("base64");
+  return b64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function fromBase64Url(b64url) {
+  let b64 = b64url.replace(/-/g, "+").replace(/_/g, "/");
+  while (b64.length % 4) b64 += "=";
+  return typeof atob === "function" ? atob(b64) : Buffer.from(b64, "base64").toString("utf8");
+}
+
+/** Encode one invite envelope — an offer (from the sharer) or a reply (from
+ *  the joiner) — into a URL-safe string. An offer carries the world id and
+ *  name so a fresh joiner can be shown them before connecting; a reply only
+ *  needs to carry the answer SDP back to the inviter. */
+export function encodeInviteBlob({ kind, sdp, world, worldName }) {
+  if (!INVITE_KINDS.has(kind)) throw new Error(`encodeInviteBlob: unknown kind "${kind}"`);
+  if (typeof sdp !== "string" || !sdp) throw new Error("encodeInviteBlob: sdp is required");
+  const envelope = kind === "offer" ? { v: 1, kind, sdp, world, worldName } : { v: 1, kind, sdp };
+  return toBase64Url(JSON.stringify(envelope));
+}
+
+/** Decode a blob produced by encodeInviteBlob. Never throws — a malformed,
+ *  truncated, or foreign-shaped blob returns { error } instead, so the UI can
+ *  show a specific message ("this invite looks cut short") rather than an
+ *  uncaught exception or a silent no-op. */
+export function decodeInviteBlob(blobString) {
+  if (typeof blobString !== "string" || !blobString.trim()) return { error: "empty" };
+  let json;
+  try {
+    json = fromBase64Url(blobString.trim());
+  } catch {
+    return { error: "truncated" };
+  }
+  let envelope;
+  try {
+    envelope = JSON.parse(json);
+  } catch {
+    return { error: "truncated" };
+  }
+  if (!envelope || typeof envelope !== "object") return { error: "malformed" };
+  if (envelope.v !== 1) return { error: "unsupported-version" };
+  if (!INVITE_KINDS.has(envelope.kind)) return { error: "malformed" };
+  if (typeof envelope.sdp !== "string" || !envelope.sdp) return { error: "malformed" };
+  if (envelope.kind === "offer" && (typeof envelope.world !== "string" || !envelope.world)) {
+    return { error: "malformed" };
+  }
+  return { value: envelope };
+}
+
+const ROOM_MESSAGE_TYPES = new Set([
+  "hello",
+  "peer-list",
+  "intro-offer",
+  "intro-answer",
+  "sync-request",
+  "sync-response",
+  "op",
+]);
+
+export function helloMessage({ peerId, displayName }) {
+  return { type: "hello", peerId, displayName };
+}
+
+export function peerListMessage({ peers }) {
+  return { type: "peer-list", peers };
+}
+
+export function introOfferMessage({ from, to, sdp }) {
+  return { type: "intro-offer", from, to, sdp };
+}
+
+export function introAnswerMessage({ from, to, sdp }) {
+  return { type: "intro-answer", from, to, sdp };
+}
+
+export function syncRequestMessage() {
+  return { type: "sync-request" };
+}
+
+export function syncResponseMessage({ facts }) {
+  return { type: "sync-response", facts };
+}
+
+export function opMessage({ from, facts }) {
+  return { type: "op", from, facts };
+}
+
+/** Structural validation only — the front door for anything a peer sends
+ *  over an open channel. Returns true/false rather than throwing, so a room
+ *  can drop a malformed message from a misbehaving or out-of-date peer
+ *  instead of crashing on it. */
+export function isValidRoomMessage(msg) {
+  if (!msg || typeof msg !== "object" || !ROOM_MESSAGE_TYPES.has(msg.type)) return false;
+  switch (msg.type) {
+    case "hello":
+      return typeof msg.peerId === "string" && msg.peerId.length > 0 && typeof msg.displayName === "string";
+    case "peer-list":
+      return Array.isArray(msg.peers)
+        && msg.peers.every((p) => p && typeof p.peerId === "string" && typeof p.displayName === "string");
+    case "intro-offer":
+    case "intro-answer":
+      return typeof msg.from === "string" && typeof msg.to === "string"
+        && typeof msg.sdp === "string" && msg.sdp.length > 0;
+    case "sync-request":
+      return true;
+    case "sync-response":
+      return Array.isArray(msg.facts);
+    case "op":
+      return typeof msg.from === "string" && Array.isArray(msg.facts);
+    default:
+      return false;
+  }
+}

package/src/domain/sprite-map.mjs

@@ -96,9 +96,17 @@ const FURNITURE_SVG =
   + '<rect x="4" y="8" width="3" height="12" fill="currentColor"/>'
   + '<rect x="17" y="8" width="3" height="12" fill="currentColor"/></svg>';
 
+// A drawstring parcel: the plainest "some small thing you could pick up"
+// shape in the set. The body-plus-shackle outline this replaced drew a
+// padlock, which reads as "restricted" rather than "unidentified" — the
+// wrong thing to say about an object whose class simply has no sprite yet.
+// Matches the silhouette data/sprites/portable-icon.toml already draws, so
+// the same class looks the same whichever tier answers.
 const PORTABLE_SVG =
-  '<svg viewBox="0 0 24 24" aria-hidden="true"><rect x="5" y="9" width="14" height="11" rx="1.5" fill="currentColor"/>'
-  + '<path d="M9 9 V6.5 A3 3 0 0 1 15 6.5 V9" fill="none" stroke="currentColor" stroke-width="1.6"/></svg>';
+  '<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M12 6 C7.5 6 5 9.4 5 13.4 C5 17.7 8.1 20 12 20 '
+  + 'C15.9 20 19 17.7 19 13.4 C19 9.4 16.5 6 12 6 Z" fill="currentColor"/>'
+  + '<path d="M9.4 6.4 C9.9 4.6 10.8 3.4 12 3.4 C13.2 3.4 14.1 4.6 14.6 6.4" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round"/>'
+  + '<ellipse cx="9.8" cy="11.6" rx="1.6" ry="2.1" fill="currentColor" opacity="0.28"/></svg>';
 
 const PERSON_SVG =
   '<svg viewBox="0 0 24 24" aria-hidden="true"><circle cx="12" cy="6.5" r="3.2" fill="currentColor"/>'