clay-server 4.0.0-beta.13 → 4.0.0-beta.15

package/lib/capsule-tictactoe-logic.js

@@ -0,0 +1,260 @@
+// Server-side Logic for the Tic-Tac-Toe Capsule.
+//
+// Logic is the single source of truth. Every state change in the game happens
+// through one of these functions and nowhere else: turn order, cell ownership,
+// and win detection are enforced here, and the game record lives in the
+// Capsule's own datastore. A human button click and a Mate clay_tool_act call
+// arrive at the same act pipeline with the same rules, so neither party can
+// break a rule the other is bound by, and neither sees state the other cannot.
+//
+// The two seats are "user" (X, first to move in a fresh game) and "mate" (O).
+// The server resolves its own actor before calling in, and the human actor
+// maps onto the user seat; seat is never read from caller-supplied text.
+//
+// Rules: seats alternate marks on a 3x3 board, cells numbered 0-8 left to
+// right, top to bottom. Three in a row, column, or diagonal wins; a full board
+// with no line is a draw. A finished game is frozen until someone resets it;
+// only the user may reset a game in progress, because the Capsule belongs to
+// the human, not to the Mate.
+
+var GAME_DOC_ID = "game";
+var BOARD_CELLS = 9;
+var USER = "user";
+var MATE = "mate";
+var SEATS = [USER, MATE];
+var SEAT_LABELS = { user: "You", mate: "Your Mate" };
+var SEAT_MARKS = { user: "X", mate: "O" };
+var WIN_LINES = [
+  [0, 1, 2], [3, 4, 5], [6, 7, 8],
+  [0, 3, 6], [1, 4, 7], [2, 5, 8],
+  [0, 4, 8], [2, 4, 6],
+];
+
+// Every read-modify-write for one stored game runs to completion before the
+// next one starts. Two acts that arrive together would otherwise both validate
+// against the same turn, and the second write would silently discard the first.
+var gameLocks = Object.create(null);
+
+function runExclusive(key, operation) {
+  var previous = gameLocks[key] || Promise.resolve();
+  var settled = previous.then(operation, operation);
+  gameLocks[key] = settled.then(function () {}, function () {});
+  return settled;
+}
+
+function otherSeat(seat) {
+  return seat === USER ? MATE : USER;
+}
+
+function emptyBoard() {
+  var board = [];
+  for (var i = 0; i < BOARD_CELLS; i++) board.push(null);
+  return board;
+}
+
+function newGame() {
+  return {
+    status: "playing",
+    turn: USER,
+    board: emptyBoard(),
+    winner: null,
+    eventSeq: 0,
+  };
+}
+
+// Counters are ordering, not points: they only ever grow, so they carry no
+// upper bound. eventSeq must survive a reset, because a Display that saw
+// event N must treat anything at or below N as already rendered.
+function safeCounter(value) {
+  return Number.isInteger(value) && value >= 0 ? value : 0;
+}
+
+// A stored game is data, not a promise about shape. Anything unreadable is
+// replaced by a fresh game rather than trusted.
+function normalizeState(stored) {
+  if (!stored || typeof stored !== "object" || Array.isArray(stored)) return newGame();
+  if (SEATS.indexOf(stored.turn) === -1) return newGame();
+  if (stored.status !== "playing" && stored.status !== "complete") return newGame();
+  var board = emptyBoard();
+  if (Array.isArray(stored.board)) {
+    for (var i = 0; i < BOARD_CELLS; i++) {
+      if (SEATS.indexOf(stored.board[i]) !== -1) board[i] = stored.board[i];
+    }
+  }
+  return {
+    status: stored.status,
+    turn: stored.turn,
+    board: board,
+    winner: SEATS.indexOf(stored.winner) !== -1 ? stored.winner : null,
+    eventSeq: safeCounter(stored.eventSeq),
+  };
+}
+
+function lineWinner(board) {
+  for (var i = 0; i < WIN_LINES.length; i++) {
+    var line = WIN_LINES[i];
+    var seat = board[line[0]];
+    if (seat && board[line[1]] === seat && board[line[2]] === seat) return seat;
+  }
+  return null;
+}
+
+function boardFull(board) {
+  for (var i = 0; i < BOARD_CELLS; i++) {
+    if (board[i] === null) return false;
+  }
+  return true;
+}
+
+function requirePlayableTurn(state, seat) {
+  if (state.status !== "playing") {
+    throw new Error("This game is already over. Reset it to play again.");
+  }
+  if (state.turn !== seat) {
+    throw new Error("This move is out of turn: " + SEAT_LABELS[state.turn] + " to play.");
+  }
+}
+
+function mark(state, seat, args) {
+  requirePlayableTurn(state, seat);
+  var cell = args && typeof args === "object" ? args.cell : undefined;
+  if (!Number.isInteger(cell) || cell < 0 || cell >= BOARD_CELLS) {
+    throw new Error("The cell must be an integer from 0 to 8.");
+  }
+  if (state.board[cell] !== null) {
+    throw new Error("Cell " + cell + " is already marked with " + SEAT_MARKS[state.board[cell]] + ".");
+  }
+  state.board[cell] = seat;
+  var winner = lineWinner(state.board);
+  if (winner) {
+    state.status = "complete";
+    state.winner = winner;
+    return state;
+  }
+  if (boardFull(state.board)) {
+    state.status = "complete";
+    state.winner = null;
+    return state;
+  }
+  state.turn = otherSeat(seat);
+  return state;
+}
+
+function reset(state, seat) {
+  if (state.status === "playing" && seat !== USER) {
+    throw new Error("Only the user may reset a game that is still in progress.");
+  }
+  return newGame();
+}
+
+function statusText(state) {
+  if (state.status !== "complete") {
+    return SEAT_LABELS[state.turn] + " (" + SEAT_MARKS[state.turn] + ") to play.";
+  }
+  if (state.winner === USER) return "You (X) won this game.";
+  if (state.winner === MATE) return "Your Mate (O) won this game.";
+  return "The game ended in a draw.";
+}
+
+// The projection a Display renders and a Mate reads. It adds no meaning that
+// is absent from state: every derived field is a restatement of the fields
+// above. The per-cell fields exist because the floor's grid buttons bind to
+// one scalar each.
+function project(state) {
+  var complete = state.status === "complete";
+  var userTurn = !complete && state.turn === USER;
+  var projection = {
+    status: state.status,
+    turn: state.turn,
+    winner: state.winner,
+    complete: complete,
+    userTurn: userTurn,
+    statusText: statusText(state),
+    eventSeq: state.eventSeq,
+  };
+  for (var i = 0; i < BOARD_CELLS; i++) {
+    var seat = state.board[i];
+    projection["cell" + i] = seat ? SEAT_MARKS[seat] : "";
+    projection["cell" + i + "Disabled"] = seat !== null || complete || !userTurn;
+  }
+  return projection;
+}
+
+// Causality for the live Display: {actor, action, previous, next} plus a
+// monotonic seq. Sending only the new state would make a Mate's move teleport
+// onto the human's screen; the event lets the Display replay and attribute it.
+function buildEvent(seat, actionId, previous, next) {
+  return {
+    seq: next.eventSeq,
+    actor: seat,
+    action: actionId,
+    previous: previous,
+    next: next,
+  };
+}
+
+function seatFor(context) {
+  var actor = context && context.actor;
+  if (actor === "human" || actor === USER) return USER;
+  if (actor === MATE) return MATE;
+  throw new Error("The Capsule caller seat could not be determined.");
+}
+
+// One act pipeline. The human surface and the Mate MCP surface both land here.
+function createRuntime(options) {
+  options = options || {};
+  var storage = options.storage;
+  var lockKey = options.lockKey || "tictactoe";
+  if (!storage) throw new Error("The Tic-Tac-Toe Capsule requires its datastore.");
+
+  async function writeState(state) {
+    await storage.put({ _id: GAME_DOC_ID, state: state });
+    return state;
+  }
+
+  async function readState() {
+    var doc = await storage.get(GAME_DOC_ID);
+    if (!doc) return writeState(newGame());
+    return normalizeState(doc.state);
+  }
+
+  async function snapshot(context) {
+    seatFor(context);
+    return runExclusive(lockKey, async function () {
+      return project(await readState());
+    });
+  }
+
+  // An act returns {state, event}: the new projection for the caller and the
+  // causal event for every watching Display. Both are built inside the lock,
+  // so seq order on the wire is the order the rules actually ran in.
+  async function act(context, actionId, args) {
+    var seat = seatFor(context);
+    return runExclusive(lockKey, async function () {
+      var state = await readState();
+      var previous = project(state);
+      var next;
+      if (actionId === "mark") next = mark(state, seat, args);
+      else if (actionId === "reset") next = reset(state, seat);
+      else throw new Error("Unknown Tic-Tac-Toe action '" + String(actionId) + "'.");
+      next.eventSeq = previous.eventSeq + 1;
+      await writeState(next);
+      var projected = project(next);
+      return { state: projected, event: buildEvent(seat, actionId, previous, projected) };
+    });
+  }
+
+  return { snapshot: snapshot, act: act };
+}
+
+module.exports = {
+  GAME_DOC_ID: GAME_DOC_ID,
+  SEATS: SEATS,
+  newGame: newGame,
+  normalizeState: normalizeState,
+  project: project,
+  buildEvent: buildEvent,
+  mark: mark,
+  reset: reset,
+  createRuntime: createRuntime,
+};

package/lib/capsules/pig/display.js

@@ -0,0 +1,190 @@
+// Pig rich Display element. Runs inside the sandboxed Capsule frame.
+//
+// This element is pure rendering over the same projection the floor renders
+// and a Mate reads: it invents no meaning of its own, and its only outward
+// capability is ClayCapsule.act, which lands in the same Logic pipeline as a
+// floor button. Swapping this file in or out changes nothing a Mate sees.
+
+(function () {
+  "use strict";
+
+  var api = window.ClayCapsule;
+  var state = null;
+  var caption = "";
+  var animating = null;
+
+  document.body.style.margin = "0";
+  document.body.style.background = "#141414";
+  document.body.style.fontFamily = "system-ui, sans-serif";
+
+  var root = document.createElement("div");
+  root.style.padding = "12px";
+  document.body.appendChild(root);
+
+  var captionEl = document.createElement("div");
+  captionEl.style.color = "#b8b8b8";
+  captionEl.style.fontSize = "12px";
+  captionEl.style.minHeight = "16px";
+  captionEl.style.marginBottom = "8px";
+  root.appendChild(captionEl);
+
+  var canvas = document.createElement("canvas");
+  canvas.width = 560;
+  canvas.height = 190;
+  canvas.style.width = "100%";
+  canvas.style.display = "block";
+  root.appendChild(canvas);
+  var ctx = canvas.getContext("2d");
+
+  var controls = document.createElement("div");
+  controls.style.display = "flex";
+  controls.style.gap = "8px";
+  controls.style.marginTop = "10px";
+  root.appendChild(controls);
+
+  function makeButton(label, action, accent) {
+    var button = document.createElement("button");
+    button.type = "button";
+    button.textContent = label;
+    button.style.flex = "1";
+    button.style.padding = "8px 0";
+    button.style.border = "0";
+    button.style.borderRadius = "8px";
+    button.style.fontSize = "13px";
+    button.style.cursor = "pointer";
+    button.style.background = accent ? "#c96f4a" : "#2c2c2c";
+    button.style.color = accent ? "#141414" : "#d8d8d8";
+    button.addEventListener("click", function () { api.act(action, {}); });
+    controls.appendChild(button);
+    return button;
+  }
+
+  var rollButton = makeButton("Roll", "roll", true);
+  var holdButton = makeButton("Hold", "hold", false);
+  var resetButton = makeButton("Reset", "reset", false);
+
+  function drawBar(y, label, value, target, color) {
+    ctx.fillStyle = "#b8b8b8";
+    ctx.font = "12px system-ui, sans-serif";
+    ctx.fillText(label + "  " + value + " / " + target, 12, y - 6);
+    ctx.fillStyle = "#2c2c2c";
+    ctx.fillRect(12, y, 380, 14);
+    ctx.fillStyle = color;
+    var width = Math.max(0, Math.min(1, value / target)) * 380;
+    ctx.fillRect(12, y, width, 14);
+  }
+
+  function drawDie(face, highlight) {
+    var x = 430;
+    var y = 40;
+    var size = 96;
+    ctx.fillStyle = highlight ? "#f0e5d8" : "#d8d8d8";
+    ctx.beginPath();
+    ctx.roundRect(x, y, size, size, 14);
+    ctx.fill();
+    if (!face) return;
+    ctx.fillStyle = face === 1 ? "#c9564a" : "#141414";
+    var spots = {
+      1: [[0.5, 0.5]],
+      2: [[0.28, 0.28], [0.72, 0.72]],
+      3: [[0.25, 0.25], [0.5, 0.5], [0.75, 0.75]],
+      4: [[0.28, 0.28], [0.72, 0.28], [0.28, 0.72], [0.72, 0.72]],
+      5: [[0.25, 0.25], [0.75, 0.25], [0.5, 0.5], [0.25, 0.75], [0.75, 0.75]],
+      6: [[0.28, 0.22], [0.72, 0.22], [0.28, 0.5], [0.72, 0.5], [0.28, 0.78], [0.72, 0.78]],
+    };
+    var pips = spots[face] || [];
+    for (var i = 0; i < pips.length; i++) {
+      ctx.beginPath();
+      ctx.arc(x + pips[i][0] * size, y + pips[i][1] * size, 7, 0, Math.PI * 2);
+      ctx.fill();
+    }
+  }
+
+  function draw(faceOverride, highlight) {
+    ctx.clearRect(0, 0, canvas.width, canvas.height);
+    if (!state) {
+      ctx.fillStyle = "#b8b8b8";
+      ctx.font = "13px system-ui, sans-serif";
+      ctx.fillText("Waiting for the game state...", 12, 30);
+      return;
+    }
+    var target = state.target || 100;
+    var scores = state.scores || {};
+    drawBar(36, "You", scores.user || 0, target, "#5a9e6f");
+    drawBar(78, "Your Mate", scores.mate || 0, target, "#6f7fc9");
+    ctx.fillStyle = "#d8d8d8";
+    ctx.font = "13px system-ui, sans-serif";
+    ctx.fillText(state.turnTotalText || "", 12, 122);
+    if (state.complete && state.winner) {
+      ctx.fillStyle = "#f0c96f";
+      ctx.font = "600 15px system-ui, sans-serif";
+      ctx.fillText((state.winner === "user" ? "You win!" : "Your Mate wins!"), 12, 152);
+    }
+    drawDie(faceOverride !== undefined ? faceOverride : state.lastRoll, !!highlight);
+  }
+
+  function syncButtons() {
+    var userTurn = !!(state && state.userTurn);
+    rollButton.disabled = !userTurn;
+    holdButton.disabled = !userTurn;
+    rollButton.style.opacity = userTurn ? "1" : "0.4";
+    holdButton.style.opacity = userTurn ? "1" : "0.4";
+  }
+
+  // Animates a decided roll: a brief pip shuffle that settles on the face the
+  // server already rolled. Pure presentation of a fact already in state.
+  function animateRoll(finalFace, next) {
+    if (animating) clearInterval(animating.timer);
+    var frames = 8;
+    var animation = { timer: null };
+    animating = animation;
+    animation.timer = setInterval(function () {
+      frames--;
+      if (frames <= 0) {
+        clearInterval(animation.timer);
+        if (animating === animation) animating = null;
+        state = next;
+        draw(finalFace, finalFace === 1);
+        syncButtons();
+        return;
+      }
+      draw((frames % 6) + 1, true);
+    }, 55);
+  }
+
+  api.onState = function (nextState) {
+    state = nextState || {};
+    if (!animating) {
+      draw();
+      syncButtons();
+    }
+    captionEl.textContent = caption;
+  };
+
+  api.onEvent = function (event) {
+    if (!event || !event.next) return;
+    var who = event.actor === "mate" ? "Your Mate" : "You";
+    var next = event.next;
+    if (event.action === "roll") {
+      caption = next.lastRoll === 1
+        ? who + " rolled a 1 and lost the turn total."
+        : who + " rolled a " + next.lastRoll + ".";
+      captionEl.textContent = caption;
+      animateRoll(next.lastRoll, next);
+      return;
+    }
+    if (event.action === "hold") {
+      var banked = (event.previous && event.previous.turnTotal) || 0;
+      caption = who + " held and banked " + banked + " point(s).";
+    } else if (event.action === "reset") {
+      caption = who + " started a new game.";
+    }
+    state = next;
+    captionEl.textContent = caption;
+    draw();
+    syncButtons();
+  };
+
+  draw();
+  syncButtons();
+})();

package/lib/capsules/pig/manifest.json

@@ -0,0 +1,9 @@
+{
+  "id": "pig",
+  "name": "Pig",
+  "runtime": "server",
+  "lucideIcon": "sparkles",
+  "description": "Two-player push-your-luck dice game shared by the user and one Mate.",
+  "useWhen": "Use when the user wants to play Pig, take a turn, or hear how the current game stands.",
+  "skills": "# Pig\n\nA two-seat push-your-luck dice game. The seats are `user` and `mate`; the person holds the user seat and you hold the mate seat. All randomness, turn order, and scoring are enforced server-side by the Capsule's Logic; you cannot roll a die yourself, and neither can the user.\n\n## Rules\n\n- Seats alternate turns. On your turn you may roll as often as you like.\n- Each roll adds its face value to the turn total. Rolling a 1 loses the entire turn total and passes play to the other seat.\n- Holding banks the turn total into your score and passes play.\n- The first seat to bank at least 100 points wins. A finished game is frozen until it is reset.\n- Only the user may reset a game that is still in progress. You may reset once the game is complete.\n\n## How to play\n\n1. `clay_tool_snapshot` with toolId `pig` to read the current state: `turn`, `scores.user`, `scores.mate`, `turnTotal`, `status`, `winner`, and `recentRolls`, which lists recent rolls only and never holds or wins.\n2. Act only when `turn` is `mate`. `clay_tool_act` with actionId `roll`, `hold`, or `reset`. Arguments are not used.\n3. An out-of-turn or post-game call is refused by Logic with an explanatory error. Read the snapshot again rather than retrying blindly.\n4. Every act returns the complete new state, so a snapshot immediately after an act is redundant.\n\n## Playing well\n\nThe interesting part of this Capsule is the judgement call, not the mechanics: decide whether to roll again or hold, and say why in your own words before you act. Typical play holds at a turn total near 20, but the score gap matters more than the rule of thumb, so explain the trade-off you are taking. Never claim a roll result before the act returns it."
+}

package/lib/capsules/pig/ui.json

@@ -0,0 +1,46 @@
+{
+  "type": "stack",
+  "props": { "gap": "md" },
+  "children": [
+    {
+      "type": "chart",
+      "bind": "userScoreSeries",
+      "props": { "label": "Your score", "kind": "progress", "categoryKey": "seat", "valueKey": "value", "max": 100 }
+    },
+    {
+      "type": "chart",
+      "bind": "mateScoreSeries",
+      "props": { "label": "Your Mate's score", "kind": "progress", "categoryKey": "seat", "valueKey": "value", "max": 100 }
+    },
+    { "type": "text", "props": { "text": { "$bind": "$state.turnTotalText", "fallback": "Turn total 0 of 100." }, "role": "output" } },
+    {
+      "type": "row",
+      "props": { "gap": "sm", "wrap": true },
+      "children": [
+        {
+          "type": "button",
+          "action": "roll",
+          "when": { "all": [{ "equals": { "path": "$state.status", "value": "playing" } }, { "equals": { "path": "$state.turn", "value": "user" } }] },
+          "props": { "label": "Roll", "variant": "primary" },
+          "else": { "type": "button", "action": "roll", "props": { "label": "Roll", "variant": "primary", "disabled": true } }
+        },
+        {
+          "type": "button",
+          "action": "hold",
+          "when": { "all": [{ "equals": { "path": "$state.status", "value": "playing" } }, { "equals": { "path": "$state.turn", "value": "user" } }] },
+          "props": { "label": "Hold", "variant": "secondary" },
+          "else": { "type": "button", "action": "hold", "props": { "label": "Hold", "variant": "secondary", "disabled": true } }
+        },
+        { "type": "button", "action": "reset", "props": { "label": "Reset", "variant": "ghost" } }
+      ]
+    },
+    {
+      "type": "list",
+      "bind": "recentRolls",
+      "props": { "variant": "divided", "gap": "xs" },
+      "children": [
+        { "type": "text", "props": { "text": "$item.text", "role": "body" } }
+      ]
+    }
+  ]
+}

package/lib/capsules/tictactoe/manifest.json

@@ -0,0 +1,9 @@
+{
+  "id": "tictactoe",
+  "name": "Tic-Tac-Toe",
+  "runtime": "server",
+  "lucideIcon": "x",
+  "description": "Two-player tic-tac-toe on a 3x3 grid shared by the user and one Mate.",
+  "useWhen": "Use when the user wants to play tic-tac-toe, take a turn on the grid, or hear how the current game stands.",
+  "skills": "# Tic-Tac-Toe\n\nA two-seat game on a 3x3 grid. The seats are `user` (X) and `mate` (O); the person holds the user seat and you hold the mate seat. Turn order, cell ownership, and win detection are enforced server-side by the Capsule's Logic; you cannot mark a cell for the user, and the user cannot mark one for you.\n\n## Rules\n\n- The user (X) moves first in a fresh game, and seats alternate marks.\n- Cells are numbered 0 to 8, left to right, top to bottom: 0 1 2 on the top row, 3 4 5 in the middle, 6 7 8 on the bottom.\n- Three matching marks in a row, column, or diagonal win. A full board with no line is a draw.\n- A finished game is frozen until it is reset. Only the user may reset a game that is still in progress. You may reset once the game is complete.\n\n## How to play\n\n1. `clay_tool_snapshot` with toolId `tictactoe` to read the current state first: `turn`, `status`, `winner`, `statusText`, and the board as `cell0` through `cell8` (each `\"X\"`, `\"O\"`, or empty).\n2. Act only when `turn` is `mate`. `clay_tool_act` with actionId `mark` and args `{\"cell\": N}` where N is 0-8, or actionId `reset` with no args.\n3. An occupied cell, an out-of-turn move, or a post-game move is refused by Logic with an explanatory error. Read the snapshot again rather than retrying blindly.\n4. Every act returns the complete new state, so a snapshot immediately after an act is redundant.\n\n## Playing well\n\nThe interesting part of this Capsule is the judgement call, not the mechanics: block a line the user is about to complete, take a winning line when you have one, and say what you see in your own words before you act. Never claim the outcome of a move before the act returns it."
+}