honeytree 1.1.6 → 1.2.1

package/src/renderer.js

@@ -1,6 +1,6 @@
 import chalk from "chalk";
 
-import { getSprite, getGroundDetail, TREE_TYPES, GROUND_DETAIL_TYPES } from "./sprites.js";
+import { getSprite, getAncientSprite, getGroundDetail, TREE_TYPES, GROUND_DETAIL_TYPES } from "./sprites.js";
 import { getVirtualWidth } from "./plant.js";
 
 const SKY_ROWS = 4;
@@ -160,6 +160,14 @@ function getTreeYOffset(treeId) {
   return h % 2; // Returns 0 or 1 (only up, never below ground)
 }
 
+function getWindOffset(treeId, windTick) {
+  if (windTick == null) return 0;
+  const windDirection = Math.floor(windTick / 4) % 2 === 0 ? 1 : -1;
+  const treePhase = hash(treeId * 7) % 3;
+  const effectiveTick = Math.max(0, windTick - treePhase);
+  return (effectiveTick % 2 === 0) ? 0 : windDirection;
+}
+
 function generateStars(width, biome, twinkle = 0) {
   const stars = [];
   for (let x = 0; x < width; x += 1) {
@@ -175,14 +183,16 @@ function generateStars(width, biome, twinkle = 0) {
   return stars;
 }
 
-function compositeSprite(buffer, sprite, centerX, baseY) {
+function compositeSprite(buffer, sprite, centerX, baseY, canopyShiftX = 0) {
   const offsetX = centerX - Math.floor(sprite.width / 2);
+  const trunkRows = 2;
   for (let rowIndex = 0; rowIndex < sprite.rows.length; rowIndex += 1) {
     const targetY = baseY - rowIndex;
     if (targetY < 0 || targetY >= buffer.length) continue;
     const row = sprite.rows[rowIndex];
+    const shiftX = rowIndex < trunkRows ? 0 : canopyShiftX;
     for (let columnIndex = 0; columnIndex < row.length; columnIndex += 1) {
-      const targetX = offsetX + columnIndex;
+      const targetX = offsetX + columnIndex + shiftX;
       if (targetX < 0 || targetX >= buffer[0].length) continue;
       const [char, color] = row[columnIndex];
       if (!color) continue;
@@ -292,6 +302,34 @@ function buildStatsLine(forest, biome, viewportX = 0, virtualWidth = 0, termWidt
   );
 }
 
+export function getStatsData(forest, viewportX = 0, virtualWidth = 0, termWidth = 80) {
+  const treeCount = forest.trees.length;
+  const biome = getBiome(treeCount);
+  const milestone = getNextMilestone(treeCount);
+  const progress = milestone === 0 ? 0 : treeCount / milestone;
+  const streak = forest.streak || 0;
+  const wilt = getWiltFactor(forest.lastActiveDate);
+  let idleDays = 0;
+  if (wilt > 0 && forest.lastActiveDate) {
+    const a = new Date(forest.lastActiveDate + "T00:00:00");
+    const b = new Date(new Date().toISOString().slice(0, 10) + "T00:00:00");
+    idleDays = Math.round((b - a) / (24 * 60 * 60 * 1000));
+  }
+  return {
+    treeCount,
+    streak,
+    wilt,
+    idleDays,
+    milestone,
+    progress,
+    biomeName: biome.label,
+    nextTreeType: getNextTreeType(treeCount),
+    viewportX,
+    virtualWidth,
+    termWidth,
+  };
+}
+
 export function renderFrame(forest, termWidth = 80, options = {}) {
   const width = Math.max(40, termWidth);
   const treeCount = forest.trees.length;
@@ -320,18 +358,86 @@ export function renderFrame(forest, termWidth = 80, options = {}) {
     }
   }
 
+  const windTick = options.windTick ?? null;
   const treeBaseY = groundStart - 1;
+  const spriteOverride = options.spriteOverride ?? null;
+  const rewards = options.rewards ?? null;
+  const hasAncient = rewards && rewards.ancient;
+  const hasBloomer = rewards && rewards.cherry;
+
   for (const tree of forest.trees) {
     const yOffset = getTreeYOffset(tree.id);
-    compositeSprite(buffer, getSprite(tree.type, tree.growth), tree.x, treeBaseY - yOffset);
+    let sprite;
+    if (spriteOverride && spriteOverride.treeId === tree.id) {
+      sprite = spriteOverride.sprite;
+    } else if (hasAncient && hash(tree.id * 37) % 8 === 0) {
+      // Ancient: 1 in 8 trees become tall golden trees (still honor heightBonus)
+      sprite = getSprite(tree.type, tree.growth, {
+        heightBonus: tree.heightBonus || 0,
+        variant: "ancient",
+      });
+    } else {
+      sprite = getSprite(tree.type, tree.growth, {
+        heightBonus: tree.heightBonus || 0,
+        variant: tree.variant || null,
+      });
+    }
+    const canopyShiftX = getWindOffset(tree.id, windTick);
+    compositeSprite(buffer, sprite, tree.x, treeBaseY - yOffset, canopyShiftX);
+  }
+
+  // Apply ground overlay (soil reaction during tree birth animation)
+  const groundOverlayOpt = options.groundOverlay ?? null;
+  if (groundOverlayOpt && groundOverlayOpt.overlays) {
+    const groundRow = groundStart; // first ground row
+    for (const overlay of groundOverlayOpt.overlays) {
+      const ox = groundOverlayOpt.treeX + overlay.dx;
+      if (ox >= 0 && ox < virtualWidth && groundRow < buffer.length) {
+        buffer[groundRow][ox] = { char: overlay.char, color: overlay.color };
+      }
+    }
+  }
+
+  // Ground pulse — brighten all ground pixels by 30% during planting flash
+  const groundPulse = options.groundPulse ?? false;
+  if (groundPulse) {
+    for (let rowIndex = 0; rowIndex < GROUND_ROWS; rowIndex += 1) {
+      for (let x = 0; x < virtualWidth; x += 1) {
+        const cell = buffer[groundStart + rowIndex][x];
+        if (cell.color) {
+          const c = parseHex(cell.color);
+          cell.color = toHex({
+            r: Math.min(255, c.r + (255 - c.r) * 0.3),
+            g: Math.min(255, c.g + (255 - c.g) * 0.3),
+            b: Math.min(255, c.b + (255 - c.b) * 0.3),
+          });
+        }
+      }
+    }
   }
 
   renderGroundDetails(buffer, biome, virtualWidth, groundStart);
 
+  // Reward: Bloomer — 30% of canopy █ chars become ✿ in pink
+  if (hasBloomer) {
+    for (let y = 0; y < groundStart; y++) {
+      for (let x = 0; x < virtualWidth; x++) {
+        const cell = buffer[y][x];
+        if (cell.char === "█" && cell.color && y < groundStart) {
+          if (hash(x * 71 + y * 113) % 10 < 3) {
+            cell.char = "✿";
+            cell.color = "#FFB7C5";
+          }
+        }
+      }
+    }
+  }
+
   applyFog(buffer, wilt, virtualWidth);
 
   // Slice the viewport from the virtual buffer
   const lines = [];
+
   for (let y = 0; y < SCENE_HEIGHT - SPACER_ROWS - STATS_ROWS - CTA_ROWS; y += 1) {
     let line = "";
     for (let x = viewportX; x < viewportX + width; x += 1) {
@@ -346,12 +452,15 @@ export function renderFrame(forest, termWidth = 80, options = {}) {
     lines.push(line);
   }
 
-  lines.push("");
-  lines.push(buildStatsLine(forest, biome, viewportX, virtualWidth, width));
-  lines.push(
-    chalk.hex("#555555")(" ← → pan  ·  add your forest to your README → ") +
-    chalk.hex(STATS_ACCENT)("honeytree badge"),
-  );
+  const includeStats = options.includeStats !== false;
+  if (includeStats) {
+    lines.push("");
+    lines.push(buildStatsLine(forest, biome, viewportX, virtualWidth, width));
+    lines.push(
+      chalk.hex("#555555")(" ← → pan  ·  add your forest to your README → ") +
+      chalk.hex(STATS_ACCENT)("honeytree badge"),
+    );
+  }
 
   return lines.join("\n");
 }
@@ -381,7 +490,12 @@ export function buildScene(forest, width) {
   const treeBaseY = groundStart - 1;
   for (const tree of forest.trees) {
     const yOffset = getTreeYOffset(tree.id);
-    compositeSprite(buffer, getSprite(tree.type, tree.growth), tree.x, treeBaseY - yOffset);
+    compositeSprite(
+      buffer,
+      getSprite(tree.type, tree.growth, { heightBonus: tree.heightBonus || 0, variant: tree.variant || null }),
+      tree.x,
+      treeBaseY - yOffset,
+    );
   }
 
   renderGroundDetails(buffer, biome, w, groundStart);
@@ -420,7 +534,12 @@ export function renderPlainText(forest, width = 60) {
   const treeBaseY = groundStart - 1;
   for (const tree of forest.trees) {
     const yOffset = getTreeYOffset(tree.id);
-    compositeSprite(buffer, getSprite(tree.type, tree.growth), tree.x, treeBaseY - yOffset);
+    compositeSprite(
+      buffer,
+      getSprite(tree.type, tree.growth, { heightBonus: tree.heightBonus || 0, variant: tree.variant || null }),
+      tree.x,
+      treeBaseY - yOffset,
+    );
   }
 
   const lines = [];

package/src/rewards.js

@@ -0,0 +1,119 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { VARIETIES } from "./varieties.js";
+
+const REWARDS_FILE = path.join(os.homedir(), ".honeydew", "rewards.json");
+
+const TIERS = [
+  { slug: "cherry",  label: "Cherry Blossom", threshold: 1,  description: "Cherry blossom trees in your forest" },
+  { slug: "pine",    label: "Pine",           threshold: 5,  description: "Evergreen pines in your forest" },
+  { slug: "oak",     label: "Oak",            threshold: 10, description: "Broad oaks in your forest" },
+  { slug: "ancient", label: "Ancient",        threshold: 25, description: "Rare tall golden ancients" },
+  { slug: "mythic",  label: "Mythic",         threshold: 50, description: "Glowing mythic trees" },
+];
+
+export { TIERS };
+
+export function getRewards() {
+  try {
+    const data = JSON.parse(fs.readFileSync(REWARDS_FILE, "utf8"));
+    if (!Array.isArray(data.celebrated)) data.celebrated = [];
+    return data;
+  } catch {
+    return { badges: [], cherry: false, pine: false, oak: false, ancient: false, mythic: false, celebrated: [], username: "" };
+  }
+}
+
+export function saveRewards(data) {
+  const dir = path.dirname(REWARDS_FILE);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(REWARDS_FILE, JSON.stringify(data, null, 2));
+}
+
+export function hasReward(slug) {
+  return getRewards()[slug] === true;
+}
+
+// Back-compat alias used by the renderer's blossom branch.
+export function hasCherryBlossom() { return hasReward("cherry"); }
+
+// Fetch rewards from server and cache locally
+export async function syncRewards(apiUrl) {
+  apiUrl = apiUrl || process.env.HONEYTREE_API_URL || "https://tryhoney.xyz";
+  const { getAuth } = await import("./auth.js");
+  const auth = getAuth();
+  if (!auth || !auth.access_token) return null;
+
+  try {
+    const res = await fetch(`${apiUrl}/api/rewards`, {
+      headers: { Authorization: `Bearer ${auth.access_token}` },
+    });
+
+    if (!res.ok) return null;
+
+    const { rewards } = await res.json();
+    const unlocked = rewards.filter((r) => r.unlocked);
+    const slugs = unlocked.map((r) => r.slug);
+
+    const data = {
+      badges: unlocked.map((r) => ({ slug: r.slug, label: r.label, description: r.description })),
+      cherry: slugs.includes("cherry"),
+      pine: slugs.includes("pine"),
+      oak: slugs.includes("oak"),
+      ancient: slugs.includes("ancient"),
+      mythic: slugs.includes("mythic"),
+      celebrated: getRewards().celebrated,
+      username: auth.username || "",
+    };
+
+    saveRewards(data);
+    return data;
+  } catch {
+    return null;
+  }
+}
+
+// Print rewards status to console
+export function printRewardsStatus(realTreesPlanted = 0) {
+  const rewards = getRewards();
+  console.log();
+  console.log("  Honeytree Rewards");
+  console.log("  ─────────────────");
+  for (const tier of TIERS) {
+    const unlocked = rewards[tier.slug] === true;
+    if (unlocked) {
+      console.log(`  ✅ ${tier.label} (${tier.threshold} tree${tier.threshold > 1 ? "s" : ""}) — ${tier.description}`);
+    } else {
+      const remaining = tier.threshold - realTreesPlanted;
+      const progress = remaining > 0 ? `${remaining} more real tree${remaining > 1 ? "s" : ""} to go` : "ready to unlock";
+      console.log(`  🔒 ${tier.label} (${tier.threshold} tree${tier.threshold > 1 ? "s" : ""}) — ${progress}`);
+    }
+  }
+  console.log();
+}
+
+// Unlocked variety keys (always includes "standard"), read from the local cache.
+export function getUnlockedVarietyKeys() {
+  const r = getRewards();
+  return VARIETIES.filter((v) => v.key === "standard" || r[v.key] === true).map((v) => v.key);
+}
+
+// Mark a variety's celebration as shown (idempotent).
+export function markCelebrated(key) {
+  const r = getRewards();
+  if (!Array.isArray(r.celebrated)) r.celebrated = [];
+  if (!r.celebrated.includes(key)) {
+    r.celebrated.push(key);
+    saveRewards(r);
+  }
+}
+
+// Unlocked varieties (excluding standard) whose celebration has not been shown.
+export function uncelebratedUnlocked() {
+  const r = getRewards();
+  const celebrated = new Set(r.celebrated || []);
+  return VARIETIES
+    .filter((v) => v.key !== "standard" && r[v.key] === true && !celebrated.has(v.key))
+    .map((v) => v.key);
+}

package/src/session.js

@@ -0,0 +1,34 @@
+import fs from "node:fs";
+import path from "node:path";
+import { getHoneydewDir } from "./state.js";
+
+const STALE_MS = 5 * 60 * 1000; // a turn older than this is abandoned
+
+function sessionFile() {
+  return path.join(getHoneydewDir(), "active-session.json");
+}
+
+export function writeActiveSession(data) {
+  const dir = getHoneydewDir();
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(sessionFile(), JSON.stringify(data, null, 2));
+}
+
+export function readActiveSession() {
+  try {
+    return JSON.parse(fs.readFileSync(sessionFile(), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export function clearActiveSession() {
+  try {
+    fs.unlinkSync(sessionFile());
+  } catch {}
+}
+
+export function isStale(session, now = Date.now()) {
+  if (!session || typeof session.turnStartedAt !== "number") return true;
+  return now - session.turnStartedAt > STALE_MS;
+}

package/src/sprites.js

@@ -14,6 +14,30 @@ const COLORS = {
   cherryBloom: "#f0b7cf",
 };
 
+const BLOSSOM_COLORS = {
+  petalSoft: "#f7d1e0",
+  petalBright: "#ffa6c9",
+  petalDeep: "#e87aab",
+  branch: "#a67c5b",
+};
+
+// Teal palette for "Grove" status unlock
+// Gold palette for "Ancient Forest" tall trees
+export const GOLD_COLORS = {
+  canopyTop: "#FFD700",
+  canopyMid: "#DAA520",
+  canopyDark: "#B8860B",
+  trunk: "#8B7355",
+};
+
+// Mythic palette — glowing unicode treatment.
+const MYTHIC_COLORS = {
+  glow: "#b388ff",
+  glowBright: "#e0c3fc",
+  core: "#7c4dff",
+  trunk: "#5e35b1",
+};
+
 const DETAIL_COLORS = {
   mushroom: "#c4a882",
   mushroomCap: "#9e4a3a",
@@ -27,7 +51,7 @@ const DETAIL_COLORS = {
   bushLight: "#5a8a4a",
 };
 
-function parse(template, palette) {
+export function parse(template, palette) {
   const lines = template.trim().split("\n");
   const width = Math.max(...lines.map((line) => line.length));
   const rows = lines
@@ -240,8 +264,32 @@ pPPpPPPp
       { p: COLORS.cherryBloom, P: COLORS.cherryPink, t: COLORS.trunkLight },
     ),
   },
+  cherry_blossom: {
+    seed: parse(` p\n b`, { p: BLOSSOM_COLORS.petalSoft, b: BLOSSOM_COLORS.branch }),
+    sapling: parse(` pP\npBp\n b`, { p: BLOSSOM_COLORS.petalSoft, P: BLOSSOM_COLORS.petalBright, B: BLOSSOM_COLORS.petalDeep, b: BLOSSOM_COLORS.branch }),
+    young: parse(`  PB\n PpBp\npBPpBP\n  bb\n  bb`, { p: BLOSSOM_COLORS.petalSoft, P: BLOSSOM_COLORS.petalBright, B: BLOSSOM_COLORS.petalDeep, b: BLOSSOM_COLORS.branch }),
+    full: parse(`   PBp\n pBPPBp\nPBpPBPBP\n pBPPBp\n   bb\n   bb`, { p: BLOSSOM_COLORS.petalSoft, P: BLOSSOM_COLORS.petalBright, B: BLOSSOM_COLORS.petalDeep, b: BLOSSOM_COLORS.branch }),
+  },
+  mythic: {
+    seed: parse(`\n m\n t\n`, { m: MYTHIC_COLORS.glow, t: MYTHIC_COLORS.trunk }),
+    sapling: parse(`\n mm\nmGm\n t\n`, { m: MYTHIC_COLORS.glow, G: MYTHIC_COLORS.glowBright, t: MYTHIC_COLORS.trunk }),
+    young: parse(`\n  mG\n mGGm\nmGGcGm\n  tt\n  tt\n`, { m: MYTHIC_COLORS.glow, G: MYTHIC_COLORS.glowBright, c: MYTHIC_COLORS.core, t: MYTHIC_COLORS.trunk }),
+    full: parse(`\n   mGm\n mGGGGm\nmGGccGGm\n mGGGGm\n   tt\n   tt\n`, { m: MYTHIC_COLORS.glow, G: MYTHIC_COLORS.glowBright, c: MYTHIC_COLORS.core, t: MYTHIC_COLORS.trunk }),
+  },
 };
 
+// Tall golden tree for "Ancient Forest" reward (1 in 8 trees)
+const ANCIENT_TREE = {
+  seed: parse(` g\n t`, { g: GOLD_COLORS.canopyTop, t: GOLD_COLORS.trunk }),
+  sapling: parse(` gg\ngGg\n t`, { g: GOLD_COLORS.canopyTop, G: GOLD_COLORS.canopyMid, t: GOLD_COLORS.trunk }),
+  young: parse(`  Tg\n TGGg\nTgGGgT\n  tt\n  tt\n  tt`, { g: GOLD_COLORS.canopyMid, G: GOLD_COLORS.canopyDark, T: GOLD_COLORS.canopyTop, t: GOLD_COLORS.trunk }),
+  full: parse(`   TT\n  TGGT\n TgGGGgT\nTgGGGGgT\n TgGGGg\n   tt\n   tt\n   tt`, { g: GOLD_COLORS.canopyMid, G: GOLD_COLORS.canopyDark, T: GOLD_COLORS.canopyTop, t: GOLD_COLORS.trunk }),
+};
+
+export function getAncientSprite(growth) {
+  return ANCIENT_TREE[getGrowthStage(growth)];
+}
+
 const GROUND_DETAILS = {
   mushroom: parse(
     `
@@ -293,10 +341,28 @@ function getGrowthStage(growth) {
   return "full";
 }
 
-export function getSprite(type, growth) {
-  const spriteSet = SPRITES[type];
-  if (!spriteSet) {
-    throw new Error(`Unknown tree type: ${type}`);
+// rows are stored bottom-first (row[0] is the ground row). Adding trunk rows at
+// the bottom makes the trunk taller and pushes the canopy up.
+function addTrunkRows(sprite, n) {
+  const bottom = sprite.rows[0] || [];
+  const trunkRow = bottom.map((cell) => (cell && cell[1] ? ["█", cell[1]] : [" ", null]));
+  const extra = Array.from({ length: n }, () => trunkRow.map((c) => [c[0], c[1]]));
+  return { rows: [...extra, ...sprite.rows], width: sprite.width };
+}
+
+export function getSprite(type, growth, opts = {}) {
+  const { heightBonus = 0, variant = null } = opts;
+  let sprite;
+  if (variant === "ancient") {
+    sprite = getAncientSprite(growth);
+  } else {
+    const spriteSet = SPRITES[type];
+    if (!spriteSet) {
+      throw new Error(`Unknown tree type: ${type}`);
+    }
+    sprite = spriteSet[getGrowthStage(growth)];
   }
-  return spriteSet[getGrowthStage(growth)];
+  if (heightBonus > 0) sprite = addTrunkRows(sprite, heightBonus);
+  return sprite;
 }
+

package/src/stdin.js

@@ -0,0 +1,28 @@
+// Read a hook's JSON payload from stdin. Resolves "" if stdin is a TTY/empty
+// (e.g. when the command is run manually), so callers can fall back gracefully.
+export function readStdin(timeoutMs = 1500) {
+  return new Promise((resolve) => {
+    if (process.stdin.isTTY) {
+      resolve("");
+      return;
+    }
+    let data = "";
+    let done = false;
+    const finish = () => {
+      if (done) return;
+      done = true;
+      resolve(data);
+    };
+    const timer = setTimeout(finish, timeoutMs);
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (c) => (data += c));
+    process.stdin.on("end", () => {
+      clearTimeout(timer);
+      finish();
+    });
+    process.stdin.on("error", () => {
+      clearTimeout(timer);
+      finish();
+    });
+  });
+}

package/src/sync.js

@@ -0,0 +1,44 @@
+import { getAuth, saveAuth } from "./auth.js";
+import { readForest } from "./state.js";
+
+const API_URL = process.env.HONEYTREE_API_URL || "https://tryhoney.xyz";
+
+export async function syncToCloud(forest) {
+  const auth = getAuth();
+  if (!auth || !auth.access_token) return;
+
+  // Send tree data: type, growth, x position for rendering on the web
+  const trees = (forest.trees || []).map((t) => ({
+    type: t.type,
+    growth: t.growth,
+    x: t.x,
+  }));
+
+  try {
+    const res = await fetch(`${API_URL}/api/sync`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${auth.access_token}`,
+      },
+      body: JSON.stringify({
+        count: forest.totalPrompts,
+        streak: forest.streak || 0,
+        trees,
+      }),
+    });
+
+    if (res.ok) {
+      auth.lastSyncedPrompts = forest.totalPrompts;
+      saveAuth(auth);
+    }
+  } catch {
+    // Silently fail — sync is best-effort
+  }
+}
+
+// Immediate sync (called after login)
+export async function syncNow() {
+  const forest = readForest();
+  if (forest) await syncToCloud(forest);
+}

package/src/transcript.js

@@ -0,0 +1,62 @@
+import fs from "node:fs";
+
+function sumOutputTokens(text) {
+  let total = 0;
+  for (const raw of text.split("\n")) {
+    const t = raw.trim();
+    if (!t) continue;
+    try {
+      const obj = JSON.parse(t);
+      const ot = obj?.message?.usage?.output_tokens;
+      if (typeof ot === "number" && Number.isFinite(ot)) total += ot;
+    } catch {
+      // ignore malformed line
+    }
+  }
+  return total;
+}
+
+function readFrom(filePath, fromOffset, maxBytes = Infinity) {
+  let stat;
+  try {
+    stat = fs.statSync(filePath);
+  } catch {
+    return null;
+  }
+  if (stat.size <= fromOffset) return { text: "", size: stat.size };
+  const fd = fs.openSync(filePath, "r");
+  try {
+    const len = Math.min(stat.size - fromOffset, maxBytes);
+    const buf = Buffer.alloc(len);
+    fs.readSync(fd, buf, 0, len, fromOffset);
+    return { text: buf.toString("utf8"), size: stat.size };
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+// Cap each live tail read so a runaway/unterminated transcript line can't
+// allocate unbounded memory on the 1s viewer interval. The Stop-time full
+// read (readTurnTokens) stays uncapped so a turn is always totalled correctly.
+const MAX_LIVE_READ = 1024 * 1024;
+
+// Sum all output tokens from `fromOffset` to EOF (turn is complete at Stop).
+export function readTurnTokens(filePath, fromOffset) {
+  const r = readFrom(filePath, fromOffset);
+  if (!r) return 0;
+  return sumOutputTokens(r.text);
+}
+
+// Read only complete (newline-terminated) lines; leave a partial trailing line
+// for the next read by not advancing the offset past it.
+export function readNewTokens(filePath, fromOffset) {
+  const r = readFrom(filePath, fromOffset, MAX_LIVE_READ);
+  if (!r) return { tokens: 0, newOffset: fromOffset };
+  if (!r.text) return { tokens: 0, newOffset: fromOffset };
+  const lastNl = r.text.lastIndexOf("\n");
+  if (lastNl === -1) return { tokens: 0, newOffset: fromOffset };
+  const complete = r.text.slice(0, lastNl + 1);
+  const tokens = sumOutputTokens(complete);
+  const consumed = Buffer.byteLength(complete, "utf8");
+  return { tokens, newOffset: fromOffset + consumed };
+}

package/src/turn.js

@@ -0,0 +1,54 @@
+import fs from "node:fs";
+import { readForest, createEmptyForest } from "./state.js";
+import { getUnlockedVarietyKeys } from "./rewards.js";
+import { unlockedPool, pickSpecies } from "./varieties.js";
+import { getPlantWidth, findOpenX } from "./plant.js";
+import { writeActiveSession, readActiveSession, clearActiveSession } from "./session.js";
+import { readTurnTokens } from "./transcript.js";
+import { tokensToTree } from "./growth.js";
+
+function fileSize(p) {
+  try {
+    return fs.statSync(p).size;
+  } catch {
+    return 0;
+  }
+}
+
+// UserPromptSubmit: mark the start of a turn and pre-choose the tree (type + x)
+// so the live overlay and the committed tree are the same tree.
+export function startTurn(payload) {
+  const transcript_path = payload?.transcript_path;
+  if (!transcript_path) return;
+
+  const forest = readForest() ?? createEmptyForest();
+  const species = pickSpecies(unlockedPool(getUnlockedVarietyKeys()));
+  const type = species.type;
+  const variant = species.variant ?? null;
+  const width = getPlantWidth(forest);
+  const x = findOpenX(forest.trees, type, 1, width);
+
+  writeActiveSession({
+    transcript_path,
+    session_id: payload.session_id ?? null,
+    turnStartedAt: Date.now(),
+    baselineOffset: fileSize(transcript_path),
+    type,
+    variant,
+    x,
+  });
+}
+
+// Stop: total this turn's output tokens and produce the tree shape, then clear
+// the session. Returns null if there's no matching active session.
+export function computeTickShape(payload) {
+  const session = readActiveSession();
+  const transcript_path = payload?.transcript_path ?? session?.transcript_path;
+  if (!session || !transcript_path || session.transcript_path !== transcript_path) {
+    return null;
+  }
+  const tokens = readTurnTokens(transcript_path, session.baselineOffset || 0);
+  const shape = tokensToTree(tokens);
+  clearActiveSession();
+  return { ...shape, type: session.type, variant: session.variant ?? null, x: session.x, tokens };
+}