@hayasaka7/haya-pet 0.1.0

package/apps/companion/test/terminal-helper-client.test.mjs

@@ -0,0 +1,68 @@
+import assert from "node:assert/strict";
+import { EventEmitter } from "node:events";
+import { test } from "../../../test/harness.mjs";
+import { createHelperClient } from "../src/main/terminal-helper-client.js";
+
+// Fake helper process that answers the line-delimited JSON protocol the way the
+// real native helper does, so the client plumbing is testable without a binary.
+function fakeSpawn(responder) {
+  const stdout = new EventEmitter();
+  const stdin = {
+    write(data) {
+      const request = JSON.parse(data);
+      queueMicrotask(() => {
+        stdout.emit("data", Buffer.from(`${JSON.stringify(responder(request))}\n`));
+      });
+      return true;
+    },
+    end() {}
+  };
+  const child = new EventEmitter();
+  child.stdout = stdout;
+  child.stdin = stdin;
+  child.kill = () => {};
+  return () => child;
+}
+
+test("requests capabilities and correlates the response by id", async () => {
+  const client = createHelperClient({
+    spawn: fakeSpawn((req) => ({ id: req.id, ok: true, capabilities: { locate: true } })),
+    command: "helper"
+  });
+
+  const caps = await client.capabilities();
+  assert.equal(caps.ok, true);
+  assert.equal(caps.capabilities.locate, true);
+  await client.close();
+});
+
+test("locate forwards pid and resolves the window", async () => {
+  const seen = [];
+  const client = createHelperClient({
+    spawn: fakeSpawn((req) => {
+      seen.push(req);
+      return { id: req.id, ok: true, window: { x: 10, y: 20, width: 800, height: 600 } };
+    }),
+    command: "helper"
+  });
+
+  const result = await client.locate(1234, 5678);
+  assert.equal(result.ok, true);
+  assert.equal(result.window.width, 800);
+  assert.equal(seen[0].op, "locate");
+  assert.equal(seen[0].pid, 1234);
+  assert.equal(seen[0].terminalPid, 5678);
+  await client.close();
+});
+
+test("concurrent requests resolve to their matching responses", async () => {
+  const client = createHelperClient({
+    spawn: fakeSpawn((req) => ({ id: req.id, ok: true, echo: req.pid })),
+    command: "helper"
+  });
+
+  const [a, b] = await Promise.all([client.locate(1), client.locate(2)]);
+  assert.equal(a.echo, 1);
+  assert.equal(b.echo, 2);
+  await client.close();
+});

package/apps/companion/test/terminal-locator.test.mjs

@@ -0,0 +1,35 @@
+import assert from "node:assert/strict";
+import { test } from "../../../test/harness.mjs";
+import { getTerminalAttachmentStrategy } from "../src/main/terminal-locator.js";
+
+test("uses Windows helper strategy on Windows", () => {
+  assert.deepEqual(getTerminalAttachmentStrategy({ platform: "windows", env: {} }), {
+    supported: "best-effort",
+    strategy: "win32-window-helper",
+    reason: "Windows terminal windows require process tree and HWND lookup."
+  });
+});
+
+test("uses macOS accessibility helper strategy on macOS", () => {
+  assert.deepEqual(getTerminalAttachmentStrategy({ platform: "macos", env: {} }), {
+    supported: "best-effort",
+    strategy: "macos-accessibility-helper",
+    reason: "macOS terminal attachment requires Accessibility or window-list permissions."
+  });
+});
+
+test("uses X11 helper strategy for Linux X11", () => {
+  assert.deepEqual(getTerminalAttachmentStrategy({ platform: "linux", env: { DISPLAY: ":0" } }), {
+    supported: "best-effort",
+    strategy: "x11-window-helper",
+    reason: "X11 allows best-effort terminal window discovery."
+  });
+});
+
+test("uses manual fallback strategy for Linux Wayland", () => {
+  assert.deepEqual(getTerminalAttachmentStrategy({ platform: "linux", env: { WAYLAND_DISPLAY: "wayland-0" } }), {
+    supported: "fallback",
+    strategy: "manual-fallback",
+    reason: "Wayland commonly blocks global window positioning and terminal lookup."
+  });
+});

package/apps/companion/test/tray-menu.test.mjs

@@ -0,0 +1,45 @@
+import assert from "node:assert/strict";
+import { test } from "../../../test/harness.mjs";
+import { buildTrayMenu } from "../src/main/tray-menu.js";
+
+const baseState = {
+  petVisible: true,
+  displayMode: "hybrid",
+  attachBubblesToTerminals: true,
+  sessions: [{ sessionId: "s1", label: "Codex · netdisk-server" }],
+  pets: [{ id: "example-pet", name: "Example Pet" }]
+};
+
+test("includes the documented recovery controls", () => {
+  const menu = buildTrayMenu(baseState);
+  const ids = menu.map((item) => item.id);
+  for (const id of ["toggle_pet", "display_mode", "sessions", "pets", "attach_bubbles", "reset_position", "settings", "quit"]) {
+    assert.ok(ids.includes(id), `missing ${id}`);
+  }
+});
+
+test("toggles the pet label based on visibility", () => {
+  assert.equal(buildTrayMenu({ ...baseState, petVisible: true }).find((i) => i.id === "toggle_pet").label, "Hide Pet");
+  assert.equal(buildTrayMenu({ ...baseState, petVisible: false }).find((i) => i.id === "toggle_pet").label, "Show Pet");
+});
+
+test("checks the current display mode in the submenu", () => {
+  const submenu = buildTrayMenu(baseState).find((i) => i.id === "display_mode").submenu;
+  const hybrid = submenu.find((i) => i.value === "hybrid");
+  const global = submenu.find((i) => i.value === "global");
+  assert.equal(hybrid.checked, true);
+  assert.equal(global.checked, false);
+});
+
+test("lists active sessions or shows an empty placeholder", () => {
+  const withSessions = buildTrayMenu(baseState).find((i) => i.id === "sessions").submenu;
+  assert.equal(withSessions[0].label, "Codex · netdisk-server");
+
+  const empty = buildTrayMenu({ ...baseState, sessions: [] }).find((i) => i.id === "sessions").submenu;
+  assert.equal(empty[0].enabled, false);
+});
+
+test("reflects the attach-bubbles checkbox state", () => {
+  assert.equal(buildTrayMenu(baseState).find((i) => i.id === "attach_bubbles").checked, true);
+  assert.equal(buildTrayMenu({ ...baseState, attachBubblesToTerminals: false }).find((i) => i.id === "attach_bubbles").checked, false);
+});

package/apps/companion/test/window-options.test.mjs

@@ -0,0 +1,62 @@
+import assert from "node:assert/strict";
+import { test } from "../../../test/harness.mjs";
+import { getPlatformCapabilities } from "../../../packages/platform-core/src/capabilities.js";
+import { buildPetWindowOptions } from "../src/main/window-options.js";
+
+test("builds non-focus-stealing transparent overlay options", () => {
+  const options = buildPetWindowOptions({
+    platform: "windows",
+    capabilities: getPlatformCapabilities({ platform: "windows", env: {} }),
+    bounds: { x: 100, y: 200, width: 192, height: 208 }
+  });
+
+  assert.equal(options.overlayMode, "transparent-overlay");
+  assert.deepEqual(options.browserWindow, {
+    x: 100,
+    y: 200,
+    width: 192,
+    height: 208,
+    transparent: true,
+    frame: false,
+    alwaysOnTop: true,
+    skipTaskbar: true,
+    resizable: false,
+    hasShadow: false,
+    focusable: false,
+    backgroundColor: "#00000000"
+  });
+});
+
+test("uses transparent overlay mode for macOS and Linux X11 capabilities", () => {
+  assert.equal(
+    buildPetWindowOptions({
+      platform: "macos",
+      capabilities: getPlatformCapabilities({ platform: "macos", env: {} }),
+      bounds: { width: 192, height: 208 }
+    }).overlayMode,
+    "transparent-overlay"
+  );
+
+  assert.equal(
+    buildPetWindowOptions({
+      platform: "linux",
+      capabilities: getPlatformCapabilities({ platform: "linux", env: { DISPLAY: ":0" } }),
+      bounds: { width: 192, height: 208 }
+    }).overlayMode,
+    "transparent-overlay"
+  );
+});
+
+test("uses fallback window mode when platform capabilities do not guarantee overlay positioning", () => {
+  const options = buildPetWindowOptions({
+    platform: "linux",
+    capabilities: getPlatformCapabilities({ platform: "linux", env: { WAYLAND_DISPLAY: "wayland-0" } }),
+    bounds: { width: 384, height: 416 }
+  });
+
+  assert.equal(options.overlayMode, "fallback-window");
+  assert.equal(options.browserWindow.transparent, false);
+  assert.equal(options.browserWindow.frame, true);
+  assert.equal(options.browserWindow.focusable, true);
+  assert.equal(options.browserWindow.skipTaskbar, false);
+});

package/apps/pet-preview/index.html

@@ -0,0 +1,42 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>Haya Pet Preview</title>
+    <link rel="stylesheet" href="./src/preview.css">
+  </head>
+  <body>
+    <main class="app-shell">
+      <section class="toolbar" aria-label="Preview controls">
+        <h1 class="brand">Haya Pet Preview</h1>
+        <label class="file-input">
+          <span>Spritesheet</span>
+          <input id="spritesheet-file" type="file" accept="image/png,image/webp">
+        </label>
+        <div id="action-list" class="action-list" aria-label="Actions"></div>
+      </section>
+
+      <section class="stage" aria-label="Pet frame">
+        <canvas id="pet-canvas" width="384" height="416"></canvas>
+      </section>
+
+      <aside class="meta-panel" aria-label="Frame details">
+        <button id="play-toggle" class="play-button" type="button">Pause</button>
+        <label class="scale-control">
+          <span class="control-label">Scale</span>
+          <input id="scale" type="range" min="1" max="4" step="1" value="2">
+        </label>
+        <div>
+          <span class="control-label">Action</span>
+          <p id="action-meta" class="meta-value">idle</p>
+        </div>
+        <div>
+          <span class="control-label">Frame</span>
+          <p id="frame-meta" class="meta-value">frame 1 / 1</p>
+        </div>
+      </aside>
+    </main>
+    <script type="module" src="./src/preview-app.js"></script>
+  </body>
+</html>

package/apps/pet-preview/src/preview-app.js

@@ -0,0 +1,123 @@
+import {
+  advancePreviewFrame,
+  buildPreviewRows,
+  createPreviewState,
+  selectPreviewAction,
+  setPreviewPlaying,
+  setPreviewScale
+} from "./preview-state.js";
+
+const canvas = document.querySelector("#pet-canvas");
+const context = canvas.getContext("2d");
+const fileInput = document.querySelector("#spritesheet-file");
+const actionList = document.querySelector("#action-list");
+const playToggle = document.querySelector("#play-toggle");
+const scaleInput = document.querySelector("#scale");
+const frameMeta = document.querySelector("#frame-meta");
+const actionMeta = document.querySelector("#action-meta");
+
+let state = createPreviewState();
+let spritesheet = null;
+let lastFrameAt = 0;
+let objectUrl = null;
+const previewRows = buildPreviewRows();
+
+for (const row of previewRows) {
+  const button = document.createElement("button");
+  button.type = "button";
+  button.className = "action-button";
+  button.textContent = row.action;
+  button.dataset.action = row.action;
+  button.addEventListener("click", () => {
+    state = selectPreviewAction(state, row.action);
+    render();
+  });
+  actionList.append(button);
+}
+
+fileInput.addEventListener("change", () => {
+  const file = fileInput.files?.[0];
+  if (!file) {
+    return;
+  }
+
+  if (objectUrl) {
+    URL.revokeObjectURL(objectUrl);
+  }
+
+  objectUrl = URL.createObjectURL(file);
+  const image = new Image();
+  image.onload = () => {
+    spritesheet = image;
+    render();
+  };
+  image.src = objectUrl;
+});
+
+playToggle.addEventListener("click", () => {
+  state = setPreviewPlaying(state, !state.playing);
+  render();
+});
+
+scaleInput.addEventListener("input", () => {
+  state = setPreviewScale(state, Number(scaleInput.value));
+  render();
+});
+
+function tick(timestamp) {
+  if (state.playing && timestamp - lastFrameAt > 120) {
+    state = advancePreviewFrame(state);
+    lastFrameAt = timestamp;
+    render();
+  }
+
+  requestAnimationFrame(tick);
+}
+
+function render() {
+  canvas.width = state.frameRect.width * state.scale;
+  canvas.height = state.frameRect.height * state.scale;
+  context.imageSmoothingEnabled = false;
+  context.clearRect(0, 0, canvas.width, canvas.height);
+
+  if (spritesheet) {
+    context.drawImage(
+      spritesheet,
+      state.frameRect.x,
+      state.frameRect.y,
+      state.frameRect.width,
+      state.frameRect.height,
+      0,
+      0,
+      canvas.width,
+      canvas.height
+    );
+  } else {
+    drawEmptyState();
+  }
+
+  for (const button of actionList.querySelectorAll("button")) {
+    button.classList.toggle("active", button.dataset.action === state.action);
+  }
+
+  playToggle.textContent = state.playing ? "Pause" : "Play";
+  actionMeta.textContent = state.action;
+  const row = previewRows.find((previewRow) => previewRow.action === state.action);
+  frameMeta.textContent = `frame ${state.frameIndex + 1} / ${row.frameCount}`;
+}
+
+function drawEmptyState() {
+  context.fillStyle = "#f4f1e8";
+  context.fillRect(0, 0, canvas.width, canvas.height);
+  context.strokeStyle = "#2f5d62";
+  context.lineWidth = 2;
+  context.strokeRect(1, 1, canvas.width - 2, canvas.height - 2);
+  context.fillStyle = "#24343b";
+  context.font = "14px system-ui, sans-serif";
+  context.textAlign = "center";
+  context.fillText("spritesheet", canvas.width / 2, canvas.height / 2 - 8);
+  context.fillText("1536 x 1872", canvas.width / 2, canvas.height / 2 + 14);
+}
+
+render();
+requestAnimationFrame(tick);

package/apps/pet-preview/src/preview-state.js

@@ -0,0 +1,70 @@
+import {
+  ACTION_ROWS,
+  FRAME_COUNTS,
+  getFrameCount,
+  getFrameRect
+} from "../../../packages/pet-core/src/atlas.js";
+
+export function buildPreviewRows() {
+  return Object.entries(ACTION_ROWS).map(([action, row]) => ({
+    action,
+    row,
+    frameCount: FRAME_COUNTS[action]
+  }));
+}
+
+export function createPreviewState(options = {}) {
+  const action = options.action ?? "idle";
+  const frameIndex = options.frameIndex ?? 0;
+  const scale = options.scale ?? 2;
+  const playing = options.playing ?? true;
+
+  return withFrameRect({
+    action,
+    frameIndex,
+    scale,
+    playing
+  });
+}
+
+export function selectPreviewAction(state, action) {
+  return withFrameRect({
+    ...state,
+    action,
+    frameIndex: 0,
+    playing: true
+  });
+}
+
+export function setPreviewScale(state, scale) {
+  if (!Number.isFinite(scale) || scale <= 0) {
+    throw new RangeError("scale must be greater than 0");
+  }
+
+  return withFrameRect({
+    ...state,
+    scale
+  });
+}
+
+export function setPreviewPlaying(state, playing) {
+  return withFrameRect({
+    ...state,
+    playing: Boolean(playing)
+  });
+}
+
+export function advancePreviewFrame(state) {
+  const frameCount = getFrameCount(state.action);
+  return withFrameRect({
+    ...state,
+    frameIndex: (state.frameIndex + 1) % frameCount
+  });
+}
+
+function withFrameRect(state) {
+  return {
+    ...state,
+    frameRect: getFrameRect(state.action, state.frameIndex)
+  };
+}

package/apps/pet-preview/src/preview.css

@@ -0,0 +1,125 @@
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  min-height: 100vh;
+  background: #f7f3ea;
+  color: #1e272b;
+  font-family: Arial, Helvetica, sans-serif;
+}
+
+button,
+input {
+  font: inherit;
+}
+
+.app-shell {
+  display: grid;
+  grid-template-columns: minmax(220px, 280px) minmax(360px, 1fr) minmax(180px, 220px);
+  gap: 20px;
+  min-height: 100vh;
+  padding: 20px;
+}
+
+.toolbar,
+.meta-panel {
+  align-self: stretch;
+  border: 1px solid #c9c3b6;
+  background: #fffaf1;
+  padding: 14px;
+}
+
+.brand {
+  margin: 0 0 16px;
+  font-size: 18px;
+  line-height: 1.2;
+}
+
+.file-input {
+  display: block;
+  margin-bottom: 14px;
+}
+
+.file-input span,
+.control-label {
+  display: block;
+  margin-bottom: 6px;
+  color: #4b5457;
+  font-size: 13px;
+}
+
+.file-input input {
+  width: 100%;
+}
+
+.action-list {
+  display: grid;
+  grid-template-columns: 1fr;
+  gap: 6px;
+}
+
+.action-button,
+.play-button {
+  min-height: 34px;
+  border: 1px solid #7f8c84;
+  background: #f7f3ea;
+  color: #1e272b;
+  cursor: pointer;
+}
+
+.action-button.active,
+.play-button {
+  border-color: #245c63;
+  background: #2f6f73;
+  color: #ffffff;
+}
+
+.stage {
+  display: grid;
+  place-items: center;
+  min-width: 0;
+  overflow: auto;
+  border: 1px solid #c9c3b6;
+  background:
+    linear-gradient(45deg, #ded8cc 25%, transparent 25%),
+    linear-gradient(-45deg, #ded8cc 25%, transparent 25%),
+    linear-gradient(45deg, transparent 75%, #ded8cc 75%),
+    linear-gradient(-45deg, transparent 75%, #ded8cc 75%);
+  background-color: #f8f4ec;
+  background-position: 0 0, 0 10px, 10px -10px, -10px 0;
+  background-size: 20px 20px;
+}
+
+canvas {
+  width: auto;
+  height: auto;
+  max-width: 100%;
+  image-rendering: pixelated;
+}
+
+.meta-panel {
+  display: grid;
+  align-content: start;
+  gap: 16px;
+}
+
+.meta-value {
+  margin: 0;
+  font-size: 15px;
+}
+
+.scale-control input {
+  width: 100%;
+}
+
+@media (max-width: 840px) {
+  .app-shell {
+    grid-template-columns: 1fr;
+  }
+
+  .stage {
+    min-height: 440px;
+  }
+}

package/apps/pet-preview/test/preview-state.test.mjs

@@ -0,0 +1,62 @@
+import assert from "node:assert/strict";
+import { test } from "../../../test/harness.mjs";
+import {
+  advancePreviewFrame,
+  buildPreviewRows,
+  createPreviewState,
+  selectPreviewAction
+} from "../src/preview-state.js";
+
+test("builds preview rows for every pet atlas action", () => {
+  assert.deepEqual(buildPreviewRows().map((row) => row.action), [
+    "idle",
+    "running-right",
+    "running-left",
+    "waving",
+    "jumping",
+    "failed",
+    "waiting",
+    "running",
+    "review"
+  ]);
+
+  assert.deepEqual(buildPreviewRows().find((row) => row.action === "jumping"), {
+    action: "jumping",
+    row: 4,
+    frameCount: 5
+  });
+});
+
+test("selecting an action resets preview playback to the first frame", () => {
+  const state = createPreviewState({ action: "running", frameIndex: 4, scale: 3 });
+
+  assert.deepEqual(selectPreviewAction(state, "waving"), {
+    action: "waving",
+    frameIndex: 0,
+    frameRect: {
+      x: 0,
+      y: 624,
+      width: 192,
+      height: 208
+    },
+    scale: 3,
+    playing: true
+  });
+});
+
+test("advancing preview frame wraps at the action frame count", () => {
+  const state = createPreviewState({ action: "waving", frameIndex: 3 });
+
+  assert.equal(advancePreviewFrame(state).frameIndex, 0);
+});
+
+test("preview state exposes the current atlas frame rectangle", () => {
+  const state = createPreviewState({ action: "review", frameIndex: 2 });
+
+  assert.deepEqual(state.frameRect, {
+    x: 384,
+    y: 1664,
+    width: 192,
+    height: 208
+  });
+});

package/assets/fallback-pet/README.md

@@ -0,0 +1,16 @@
+# Fallback Pet
+
+This directory holds the bundled fallback pet manifest. The matching
+`spritesheet.webp` is a binary 1536×1872 Codex-compatible atlas (8 columns ×
+9 rows of 192×208 cells) and is **not** checked in here.
+
+To use a real pet:
+
+- Drop a Codex-compatible pet (a folder with `pet.json` + `spritesheet.webp`)
+  into `~/.codex/pets` or `~/.haya-pet/pets`, or
+- Add `spritesheet.webp` next to this `pet.json`.
+
+If no spritesheet is found, the companion renderer draws labelled placeholder
+frames so interaction and state mapping can still be exercised during
+development. Atlas dimensions are validated against 1536×1872 once the image
+loads (`packages/pet-core/src/validation.js`).

package/assets/fallback-pet/pet.json

@@ -0,0 +1,13 @@
+{
+  "id": "fallback-pet",
+  "name": "Fallback Pet",
+  "spritesheet": "spritesheet.webp",
+  "cellWidth": 192,
+  "cellHeight": 208,
+  "frameDurationMs": 120,
+  "actionFrameDurations": {
+    "idle": 160,
+    "waving": 90,
+    "jumping": 90
+  }
+}