@pylonsync/create-pylon 0.19.1 → 0.21.0

package/templates/chat/lib/chat.ts

@@ -0,0 +1,188 @@
+// Pure chat helpers: names, colors, grouping, and labels. No Pylon imports,
+// so tests/chat.test.ts runs them without a server and the server functions
+// and the client share one copy.
+
+export interface ChatMessage {
+  id: string;
+  channelId: string;
+  authorId: string;
+  text: string;
+  /** Absent on an optimistic row until the server stamps it. */
+  createdAt?: string | null;
+}
+
+export interface ChatMember {
+  id: string;
+  userId: string;
+  name: string;
+  hue: number;
+}
+
+export const MAX_MESSAGE_LENGTH = 4000;
+export const MAX_NAME_LENGTH = 32;
+
+/** Messages from one author closer together than this share one header. */
+export const GROUP_GAP_MS = 5 * 60 * 1000;
+
+const ADJECTIVES = [
+  "Amber", "Brisk", "Cobalt", "Dusky", "Ember", "Fern", "Gilded", "Hazel",
+  "Indigo", "Juniper", "Kestrel", "Lunar", "Maple", "Nimble", "Ochre", "Pewter",
+  "Quiet", "Russet", "Saffron", "Tidal", "Umber", "Velvet", "Willow", "Zephyr",
+];
+
+const ANIMALS = [
+  "Otter", "Heron", "Lynx", "Finch", "Marten", "Ibis", "Badger", "Wren",
+  "Puffin", "Stoat", "Crane", "Hare", "Magpie", "Newt", "Osprey", "Plover",
+  "Raven", "Seal", "Tern", "Vole", "Wolf", "Yak", "Gecko", "Moth",
+];
+
+/** FNV-1a: a small, stable string hash. The same id always maps to the same name. */
+export function hashString(input: string): number {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < input.length; i++) {
+    h ^= input.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return h >>> 0;
+}
+
+/** "Amber Otter" style display name for a guest, derived from the user id. */
+export function guestName(userId: string): string {
+  const h = hashString(userId);
+  const adjective = ADJECTIVES[h % ADJECTIVES.length];
+  const animal = ANIMALS[Math.floor(h / ADJECTIVES.length) % ANIMALS.length];
+  return `${adjective} ${animal}`;
+}
+
+/** Avatar hue (0–359) derived from the user id. */
+export function guestHue(userId: string): number {
+  return hashString(`hue:${userId}`) % 360;
+}
+
+/** Trims, collapses whitespace, and validates a display name. Returns null when invalid. */
+export function cleanName(raw: string): string | null {
+  // \p{Cf} covers zero-width and bidi control characters, which could make a
+  // name invisible or reorder the text around it.
+  const name = raw.replace(/\p{Cf}/gu, "").replace(/\s+/g, " ").trim();
+  if (name.length === 0 || name.length > MAX_NAME_LENGTH) return null;
+  return name;
+}
+
+/** Up to two initials: "Maya Chen" → "MC", "theo" → "T". */
+export function initials(name: string): string {
+  const parts = name.trim().split(/\s+/).filter(Boolean);
+  if (parts.length === 0) return "?";
+  // Array.from splits by code point, so an emoji stays whole.
+  const first = Array.from(parts[0])[0] ?? "";
+  const last = parts.length > 1 ? (Array.from(parts[parts.length - 1])[0] ?? "") : "";
+  return (first + last).toUpperCase();
+}
+
+/**
+ * Chronological order. Rows the server has not stamped yet sort last. Equal
+ * timestamps (Postgres stores whole seconds) fall back to the id, which is
+ * time-ordered, so every client shows the same order.
+ */
+export function sortMessages<T extends ChatMessage>(messages: readonly T[]): T[] {
+  return [...messages].sort((a, b) => {
+    if (!a.createdAt && !b.createdAt) return 0;
+    if (!a.createdAt) return 1;
+    if (!b.createdAt) return -1;
+    return a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id);
+  });
+}
+
+export interface MessageGroup<T extends ChatMessage = ChatMessage> {
+  key: string;
+  authorId: string;
+  /** Local-day key ("2026-09-26") of the first message; null while pending. */
+  day: string | null;
+  messages: T[];
+}
+
+/** Local calendar day of an ISO timestamp, as "YYYY-MM-DD". */
+export function dayKey(iso: string): string {
+  const d = new Date(iso);
+  const m = String(d.getMonth() + 1).padStart(2, "0");
+  const day = String(d.getDate()).padStart(2, "0");
+  return `${d.getFullYear()}-${m}-${day}`;
+}
+
+/**
+ * Groups sorted messages into runs by one author. A new group starts when the
+ * author changes, the local day changes, or the gap exceeds GROUP_GAP_MS. A
+ * pending row (no createdAt) joins the previous group when the author matches.
+ */
+export function groupMessages<T extends ChatMessage>(
+  sorted: readonly T[],
+  gapMs: number = GROUP_GAP_MS,
+): MessageGroup<T>[] {
+  const groups: MessageGroup<T>[] = [];
+  let lastTime: number | null = null;
+  for (const m of sorted) {
+    const prev = groups[groups.length - 1];
+    const time = m.createdAt ? Date.parse(m.createdAt) : null;
+    const day = m.createdAt ? dayKey(m.createdAt) : null;
+    const sameAuthor = prev?.authorId === m.authorId;
+    const sameDay = day === null || prev?.day === null || prev?.day === day;
+    const closeInTime = time === null || lastTime === null || time - lastTime <= gapMs;
+    if (prev && sameAuthor && sameDay && closeInTime) {
+      prev.messages.push(m);
+    } else {
+      groups.push({ key: m.id, authorId: m.authorId, day, messages: [m] });
+    }
+    if (time !== null) lastTime = time;
+  }
+  return groups;
+}
+
+/** "Today", "Yesterday", "Wednesday", or "Monday, September 21". */
+export function dayLabel(iso: string, now: Date = new Date()): string {
+  const d = new Date(iso);
+  const startOf = (x: Date) => new Date(x.getFullYear(), x.getMonth(), x.getDate()).getTime();
+  const diffDays = Math.round((startOf(now) - startOf(d)) / 86_400_000);
+  if (diffDays === 0) return "Today";
+  if (diffDays === 1) return "Yesterday";
+  if (diffDays > 1 && diffDays < 7) {
+    return d.toLocaleDateString("en-US", { weekday: "long" });
+  }
+  return d.toLocaleDateString("en-US", {
+    weekday: "long",
+    month: "long",
+    day: "numeric",
+    ...(d.getFullYear() === now.getFullYear() ? {} : { year: "numeric" }),
+  });
+}
+
+/** "9:41 AM" in the viewer's locale. */
+export function timeLabel(iso: string): string {
+  return new Date(iso).toLocaleTimeString([], { hour: "numeric", minute: "2-digit" });
+}
+
+/** "Maya is typing", "Maya and Theo are typing", "Maya, Theo, and 2 others are typing". */
+export function typingLabel(names: readonly string[]): string {
+  if (names.length === 0) return "";
+  if (names.length === 1) return `${names[0]} is typing`;
+  if (names.length === 2) return `${names[0]} and ${names[1]} are typing`;
+  if (names.length === 3) return `${names[0]}, ${names[1]}, and ${names[2]} are typing`;
+  return `${names[0]}, ${names[1]}, and ${names.length - 2} others are typing`;
+}
+
+/**
+ * Messages from other people in a channel, newer than `lastSeen`. A channel the
+ * viewer has no mark for counts as read, so a first visit shows no badges.
+ */
+export function unreadCount(
+  messages: readonly ChatMessage[],
+  channelId: string,
+  lastSeen: string | undefined,
+  selfId: string,
+): number {
+  if (!lastSeen) return 0;
+  let n = 0;
+  for (const m of messages) {
+    if (m.channelId !== channelId || m.authorId === selfId || !m.createdAt) continue;
+    if (m.createdAt > lastSeen) n++;
+  }
+  return n;
+}

package/templates/chat/lib/seed.ts

@@ -0,0 +1,78 @@
+// Workspace loaded on first boot by functions/joinChat.ts. The channels are
+// always created. With `includeDemoConversation` on, four demo people (a team
+// shipping an offline-maps update for a trail-running app) and their messages
+// are added too. Set it to false to start with empty channels.
+//
+// `minutesAgo` is relative to the moment the seed runs, so the conversation
+// always reads as yesterday plus this morning.
+
+export const includeDemoConversation = true;
+
+export interface SeedChannel {
+  slug: string;
+  name: string;
+  topic: string;
+}
+
+export interface SeedPerson {
+  /** Stable author id for seeded rows. Real users have session ids instead. */
+  userId: string;
+  name: string;
+  hue: number;
+}
+
+export interface SeedMessage {
+  channel: string;
+  author: string;
+  minutesAgo: number;
+  text: string;
+}
+
+export const seedChannels: SeedChannel[] = [
+  { slug: "general", name: "general", topic: "Anything that doesn't fit elsewhere" },
+  { slug: "launch", name: "launch", topic: "Ridgeline 2.4 ships Thursday at 10:00" },
+  { slug: "design", name: "design", topic: "Screens, icons, and App Store art" },
+];
+
+export const seedPeople: SeedPerson[] = [
+  { userId: "seed_maya", name: "Maya Chen", hue: 28 },
+  { userId: "seed_theo", name: "Theo Okafor", hue: 250 },
+  { userId: "seed_priya", name: "Priya Raman", hue: 150 },
+  { userId: "seed_jonas", name: "Jonas Weber", hue: 330 },
+];
+
+const DAY = 24 * 60;
+
+export const seedMessages: SeedMessage[] = [
+  // #launch, yesterday afternoon
+  { channel: "launch", author: "seed_priya", minutesAgo: DAY + 190, text: "Status check for 2.4. We still have three open items: the iPad crash, the App Store screenshots, and the release notes." },
+  { channel: "launch", author: "seed_maya", minutesAgo: DAY + 186, text: "The iPad crash is in the tile cache. When you download a region bigger than about 2 GB, the eviction pass runs on the main thread and the watchdog kills the app." },
+  { channel: "launch", author: "seed_maya", minutesAgo: DAY + 185, text: "Moving eviction to a background queue now. Should have a build tonight." },
+  { channel: "launch", author: "seed_jonas", minutesAgo: DAY + 171, text: "I can reproduce it every time on the 10th gen iPad with the Cascades region. Happy to run it again once the build is up." },
+  { channel: "launch", author: "seed_priya", minutesAgo: DAY + 168, text: "Great. If it slips past Wednesday noon we move the release to next week. I'd rather not ship offline maps that crash offline." },
+  { channel: "launch", author: "seed_theo", minutesAgo: DAY + 122, text: "Screenshots are 80% done. Waiting on a clean capture of the elevation profile with the new colors." },
+  { channel: "launch", author: "seed_maya", minutesAgo: DAY + 34, text: "TestFlight build 412 is up. Eviction runs in the background, and I added a progress bar so a big cleanup doesn't look frozen." },
+  { channel: "launch", author: "seed_jonas", minutesAgo: DAY + 21, text: "Installing now." },
+
+  // #launch, this morning
+  { channel: "launch", author: "seed_jonas", minutesAgo: 58, text: "Build 412 survived six full downloads of the Cascades region on the iPad. No crash, memory stays under 600 MB." },
+  { channel: "launch", author: "seed_jonas", minutesAgo: 57, text: "One small thing: the progress bar says 100% for about four seconds before it disappears." },
+  { channel: "launch", author: "seed_maya", minutesAgo: 49, text: "That's the index rebuild after the last tile lands. I'll change the label to \"Finishing up\" for that step instead of hiding it." },
+  { channel: "launch", author: "seed_priya", minutesAgo: 44, text: "Perfect. That takes the crash off the list 🎉" },
+  { channel: "launch", author: "seed_priya", minutesAgo: 43, text: "Remaining: screenshots (Theo) and release notes (me). Submitting for review Wednesday at 3." },
+  { channel: "launch", author: "seed_theo", minutesAgo: 12, text: "Screenshots are uploaded to the shared folder: 6.9\" and 13\" iPad, light and dark. Can someone check the Spanish captions?" },
+  { channel: "launch", author: "seed_priya", minutesAgo: 6, text: "On it after standup." },
+
+  // #design
+  { channel: "design", author: "seed_theo", minutesAgo: DAY + 240, text: "New elevation colors: climbs go from sand to rust, descents from sky to deep blue. The old green-to-red read like a heart rate chart." },
+  { channel: "design", author: "seed_maya", minutesAgo: DAY + 231, text: "Much easier to read in sunlight. Is the rust still readable on the dark map style?" },
+  { channel: "design", author: "seed_theo", minutesAgo: DAY + 226, text: "I bumped its lightness 8% in dark mode. Checked it on a phone outside at noon." },
+  { channel: "design", author: "seed_theo", minutesAgo: 95, text: "Offline badge is final: a small filled cloud with a slash, bottom-left of the region card. No more \"Saved\" text label." },
+  { channel: "design", author: "seed_jonas", minutesAgo: 88, text: "Support will like that. Half the tickets last month were people not knowing a region was already downloaded." },
+
+  // #general
+  { channel: "general", author: "seed_priya", minutesAgo: DAY + 300, text: "Welcome to the team chat. #launch is for the 2.4 release, #design for screens and art." },
+  { channel: "general", author: "seed_jonas", minutesAgo: DAY + 75, text: "Trail run Saturday at 8 at the Mill Creek trailhead. 12 km, easy pace, coffee after." },
+  { channel: "general", author: "seed_theo", minutesAgo: DAY + 70, text: "In, as long as easy pace means easy pace." },
+  { channel: "general", author: "seed_maya", minutesAgo: 30, text: "Standup moved to 10:30 today, Priya is on a call with the App Review team." },
+];

package/templates/chat/tests/chat.test.ts

@@ -0,0 +1,159 @@
+import { describe, expect, test } from "bun:test";
+import {
+  cleanName,
+  dayLabel,
+  groupMessages,
+  guestHue,
+  guestName,
+  initials,
+  sortMessages,
+  typingLabel,
+  unreadCount,
+  type ChatMessage,
+} from "../lib/chat";
+import { seedChannels, seedMessages, seedPeople } from "../lib/seed";
+
+const at = (iso: string, authorId = "a", id = iso, channelId = "c1"): ChatMessage => ({
+  id,
+  channelId,
+  authorId,
+  text: "x",
+  createdAt: iso,
+});
+
+describe("guest identity", () => {
+  test("the same id always gets the same name and hue", () => {
+    expect(guestName("guest_abc")).toBe(guestName("guest_abc"));
+    expect(guestHue("guest_abc")).toBe(guestHue("guest_abc"));
+  });
+
+  test("names are two words and hues are angles", () => {
+    for (const id of ["guest_1", "guest_2", "guest_ffff", "u_42"]) {
+      expect(guestName(id)).toMatch(/^[A-Z][a-z]+ [A-Z][a-z]+$/);
+      const hue = guestHue(id);
+      expect(hue).toBeGreaterThanOrEqual(0);
+      expect(hue).toBeLessThan(360);
+    }
+  });
+});
+
+describe("cleanName", () => {
+  test("trims and collapses whitespace", () => {
+    expect(cleanName("  Maya   Chen ")).toBe("Maya Chen");
+  });
+  test("removes zero-width and bidi control characters", () => {
+    expect(cleanName("Ma\u200bya\u202e")).toBe("Maya");
+    expect(cleanName("\u200b\u200b")).toBeNull();
+  });
+  test("rejects empty and over-long names", () => {
+    expect(cleanName("   ")).toBeNull();
+    expect(cleanName("x".repeat(33))).toBeNull();
+    expect(cleanName("x".repeat(32))).toBe("x".repeat(32));
+  });
+});
+
+test("initials", () => {
+  expect(initials("Maya Chen")).toBe("MC");
+  expect(initials("theo")).toBe("T");
+  expect(initials("Priya de la Raman")).toBe("PR");
+  expect(initials("  ")).toBe("?");
+  expect(initials("🎉 Party")).toBe("🎉P");
+});
+
+describe("sortMessages", () => {
+  test("orders by time and puts unsent rows last", () => {
+    const pending: ChatMessage = { id: "p", channelId: "c1", authorId: "a", text: "x" };
+    const sorted = sortMessages([at("2026-09-26T10:05:00Z"), pending, at("2026-09-26T10:00:00Z")]);
+    expect(sorted.map((m) => m.id)).toEqual(["2026-09-26T10:00:00Z", "2026-09-26T10:05:00Z", "p"]);
+  });
+});
+
+test("equal timestamps fall back to id order", () => {
+  const sorted = sortMessages([
+    at("2026-09-26T10:00:00Z", "a", "b-id"),
+    at("2026-09-26T10:00:00Z", "a", "a-id"),
+  ]);
+  expect(sorted.map((m) => m.id)).toEqual(["a-id", "b-id"]);
+});
+
+describe("groupMessages", () => {
+  test("joins consecutive messages from one author within five minutes", () => {
+    const groups = groupMessages([
+      at("2026-09-26T10:00:00Z", "a"),
+      at("2026-09-26T10:03:00Z", "a"),
+      at("2026-09-26T10:04:00Z", "b"),
+      at("2026-09-26T10:20:00Z", "b"),
+    ]);
+    expect(groups.map((g) => [g.authorId, g.messages.length])).toEqual([
+      ["a", 2],
+      ["b", 1],
+      ["b", 1],
+    ]);
+  });
+
+  test("starts a new group on a new day", () => {
+    const groups = groupMessages([
+      at(new Date(2026, 8, 25, 23, 58).toISOString(), "a"),
+      at(new Date(2026, 8, 26, 0, 1).toISOString(), "a"),
+    ]);
+    expect(groups).toHaveLength(2);
+    expect(groups[0].day).not.toBe(groups[1].day);
+  });
+
+  test("a pending row joins the sender's last group", () => {
+    const pending: ChatMessage = { id: "p", channelId: "c1", authorId: "a", text: "x", createdAt: null };
+    const groups = groupMessages([at("2026-09-26T10:00:00Z", "a"), pending]);
+    expect(groups).toHaveLength(1);
+    expect(groups[0].messages.map((m) => m.id)).toEqual(["2026-09-26T10:00:00Z", "p"]);
+  });
+});
+
+describe("dayLabel", () => {
+  const now = new Date(2026, 8, 26, 12, 0);
+  test("today and yesterday", () => {
+    expect(dayLabel(new Date(2026, 8, 26, 8, 0).toISOString(), now)).toBe("Today");
+    expect(dayLabel(new Date(2026, 8, 25, 23, 0).toISOString(), now)).toBe("Yesterday");
+  });
+  test("weekday within a week, full date after", () => {
+    expect(dayLabel(new Date(2026, 8, 22, 9, 0).toISOString(), now)).toBe("Tuesday");
+    expect(dayLabel(new Date(2026, 8, 14, 9, 0).toISOString(), now)).toBe("Monday, September 14");
+    expect(dayLabel(new Date(2025, 8, 14, 9, 0).toISOString(), now)).toBe("Sunday, September 14, 2025");
+  });
+});
+
+test("typingLabel", () => {
+  expect(typingLabel([])).toBe("");
+  expect(typingLabel(["Maya"])).toBe("Maya is typing");
+  expect(typingLabel(["Maya", "Theo"])).toBe("Maya and Theo are typing");
+  expect(typingLabel(["Maya", "Theo", "Priya"])).toBe("Maya, Theo, and Priya are typing");
+  expect(typingLabel(["Maya", "Theo", "Priya", "Jonas"])).toBe("Maya, Theo, and 2 others are typing");
+});
+
+describe("unreadCount", () => {
+  const msgs = [
+    at("2026-09-26T10:00:00Z", "other", "1"),
+    at("2026-09-26T10:05:00Z", "other", "2"),
+    at("2026-09-26T10:06:00Z", "me", "3"),
+    at("2026-09-26T10:07:00Z", "other", "4", "c2"),
+  ];
+  test("counts other people's messages after the mark in that channel", () => {
+    expect(unreadCount(msgs, "c1", "2026-09-26T10:01:00Z", "me")).toBe(1);
+  });
+  test("a channel without a mark counts as read", () => {
+    expect(unreadCount(msgs, "c1", undefined, "me")).toBe(0);
+  });
+});
+
+describe("seed", () => {
+  test("every seeded message points at a seeded channel and person", () => {
+    const channels = new Set(seedChannels.map((c) => c.slug));
+    const people = new Set(seedPeople.map((p) => p.userId));
+    for (const m of seedMessages) {
+      expect(channels.has(m.channel)).toBe(true);
+      expect(people.has(m.author)).toBe(true);
+    }
+  });
+  test("seed ids cannot collide with session user ids", () => {
+    for (const p of seedPeople) expect(p.userId.startsWith("seed_")).toBe(true);
+  });
+});

package/templates/chat/tests/composer.test.tsx

@@ -0,0 +1,54 @@
+import { afterEach, expect, mock, test } from "bun:test";
+// This project uses the classic JSX transform, so .tsx tests import React.
+import React from "react";
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { Composer } from "../components/chat/composer";
+
+afterEach(cleanup);
+
+function setup() {
+  const onSend = mock((_text: string) => {});
+  const onTyping = mock(() => {});
+  const onStopTyping = mock(() => {});
+  render(
+    <Composer
+      channelName="launch"
+      channelKey="c1"
+      onSend={onSend}
+      onTyping={onTyping}
+      onStopTyping={onStopTyping}
+    />,
+  );
+  const field = screen.getByPlaceholderText("Message #launch") as HTMLTextAreaElement;
+  return { field, onSend, onTyping, onStopTyping };
+}
+
+test("Enter sends the trimmed text and clears the field", () => {
+  const { field, onSend, onStopTyping } = setup();
+  fireEvent.change(field, { target: { value: "  ship it  " } });
+  fireEvent.keyDown(field, { key: "Enter" });
+  expect(onSend).toHaveBeenCalledWith("ship it");
+  expect(field.value).toBe("");
+  expect(onStopTyping).toHaveBeenCalled();
+});
+
+test("Shift+Enter does not send", () => {
+  const { field, onSend } = setup();
+  fireEvent.change(field, { target: { value: "line one" } });
+  fireEvent.keyDown(field, { key: "Enter", shiftKey: true });
+  expect(onSend).not.toHaveBeenCalled();
+});
+
+test("whitespace-only text does not send and the button stays disabled", () => {
+  const { field, onSend } = setup();
+  fireEvent.change(field, { target: { value: "   " } });
+  fireEvent.keyDown(field, { key: "Enter" });
+  expect(onSend).not.toHaveBeenCalled();
+  expect((screen.getByRole("button", { name: "Send message" }) as HTMLButtonElement).disabled).toBe(true);
+});
+
+test("typing reports activity", () => {
+  const { field, onTyping } = setup();
+  fireEvent.change(field, { target: { value: "h" } });
+  expect(onTyping).toHaveBeenCalled();
+});

package/templates/consumer/AGENTS.md

@@ -62,7 +62,7 @@ this pass before the user has to ask.
 - **`serverData` (SSR) is READ-ONLY.** No write methods; the runtime rejects write frames (`SSR_WRITE_FORBIDDEN`). Mutations belong in actions/functions, never in a page render.
 - **`response.*` / `response.redirect()` / `response.notFound()` must fire in the synchronous shell render**, before any `await` / `<Suspense>`. The HTTP head commits when the shell is ready; status/headers/cookies set from a suspended subtree are lost, and `redirect`/`notFound` thrown below a Suspense boundary are swallowed.
 - **`ctx.llm`, `ctx.rooms`, and `ctx.connections` are on mutation + action only, NOT query** (reactive purity). `action` has no direct `ctx.db`; use `ctx.runQuery` / `ctx.runMutation`.
-- **`ctx.llm.stream(request, onEvent)` streams tokens as they generate** and still resolves with the full response, so `stop_reason === "tool_use"` drives an agent tool loop. Events are `text_delta` / `tool_use_start` / `tool_input_delta` / `done`. Same auth + model-allowlist gating as `ctx.llm.complete`. Streaming does NOT extend the call deadline (`PYLON_FN_CALL_TIMEOUT`, 30s default) — set `timeout: <secs>` on the def for a long run.
+- **`ctx.llm.stream(request, onEvent)` streams tokens as they generate** and still resolves with the full response, so `stop_reason === "tool_use"` drives an agent tool loop. Events are `text_delta` / `tool_use_start` / `tool_input_delta` / `done`. Same auth + model-allowlist gating as `ctx.llm.complete`. The call timeout is an idle timeout (`PYLON_FN_CALL_TIMEOUT`, 30s default; Stack0 Cloud 300s): each stream event resets it, and the total run is capped at 10× the timeout. Set `timeout: <secs>` on the def when a step (a slow tool call) can be silent longer than that.
 - **`ctx.stream.write(text)` streams to the caller — and every fn stream is RESUMABLE**: the server buffers frames under a stream id (`streamFn`'s `onStreamId`), so a dropped connection or closed tab catches up via `resumeStream(id)`, including the final result after the handler finished. `ctx.rooms.broadcast(room, topic, data)` fans out to every CURRENTLY-CONNECTED subscriber (second device, second tab) but does not replay missed messages — use the stream id for anything that must survive a gap. Broadcast resolves `{ delivered: false }` when the room has no members — a no-op, not an error. Clients receive with `useRoomMessages(room, cb)` from `@pylonsync/react`; `useRoom` is the send side.
 - **It's `db.useQueryOne`, not `useOne`.** Validators and field types have aliases: `v.bool`/`v.boolean`, `v.float`/`v.number`.
 - **Use the supported file and scheduling APIs.** Files go through `<FileUpload>` and `/api/files/*`; an upload is readable by its uploader only, so pass `visibility: "public"` to `uploadFile` or `<FileUpload>` for files every visitor sees; there is no `ctx.files`. One-shot work uses `ctx.scheduler.runAfter`, `runAt`, or `cancel`; there is no `defineWorkflow` or `defineJob`. Recurring work uses `cron("0 * * * *", "fnName")` in `buildManifest({ crons: [...] })`, imported from `@pylonsync/sdk`. Make the target function `internal: true`. It runs with anonymous auth, but its own `ctx.db.*` calls are server-side and bypass policies. Use `ctx.auth.elevate({ admin: true, reason: "..." })`, with a mandatory reason, only when chaining another internal function through `ctx.scheduler`.

package/templates/consumer/README.md

@@ -10,7 +10,7 @@ saved posts. Likes, comments, and follows update live in every open tab.
 __RUN_DEV__
 ```
 
-Open http://localhost:4321. The first visit loads twelve demo people with
+Open http://localhost:4321. The first visit loads eight demo people with
 their posts, likes, comments, and follows, and gives you a guest profile.
 Post a photo with Create, like with a double tap, and open a second tab to
 watch counts change.
@@ -30,7 +30,7 @@ lib/seed.ts                     the demo people and posts
 lib/site.ts                     the app's name
 functions/                      ensureProfile, updateProfile, createPost,
                                 addComment, seedFeed
-public/images/                  demo avatars and photos
+public/images/posts/            demo photos
 ```
 
 ## How it works
@@ -55,7 +55,7 @@ public/images/                  demo avatars and photos
   move a guest's profile to the account on sign-in.
 - **Scale:** `components/social/use-social.ts` reads every row, which is fine
   for a demo. For a large network, query per screen with `where` and `limit`.
-- **Launch:** delete `functions/seedFeed.ts`, `lib/seed.ts`, and
+- **Launch:** delete `functions/seedFeed.ts`, `lib/seed.ts`, `tests/seed.test.ts`, and
   `public/images/`, and remove the `seedFeed` call in `session.tsx`.
 
 ## Deploy

package/templates/consumer/app/globals.css

@@ -16,9 +16,12 @@
    on <html>. */
 :root {
   --radius: 0.625rem;
-  /* The app's own colors: links and the follow button, and a liked heart. */
-  --brand: #2563eb;
-  --like: #e11d48;
+  /* The app's own colors: links and the follow button, and a liked heart.
+     They match the iOS app in apps/ios. */
+  --brand: #0095f6;
+  --like: #ff3040;
+  /* The ring around someone who posted in the last 24 hours. */
+  --story-ring: conic-gradient(from 180deg, #fcba45, #fa6133, #de2678, #8c38d9, #fcba45);
   --background: oklch(1 0 0);
   --foreground: oklch(0.141 0.005 285.823);
   --card: oklch(1 0 0);
@@ -147,6 +150,10 @@
 }
 
 /* The wordmark. Instrument Serif is declared in app.ts. */
+.bg-story-ring {
+  background: var(--story-ring);
+}
+
 .font-display {
   font-family: var(--font-display, "Iowan Old Style", Georgia, serif);
 }

package/templates/consumer/app/icon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64"><defs><linearGradient id="g" x1="0" y1="1" x2="1" y2="0"><stop offset="0" stop-color="#fcba45"/><stop offset=".35" stop-color="#fa6133"/><stop offset=".7" stop-color="#de2678"/><stop offset="1" stop-color="#8c38d9"/></linearGradient></defs><rect width="64" height="64" rx="14" fill="url(#g)"/><text x="32" y="45" text-anchor="middle" font-family="Georgia, 'Times New Roman', serif" font-style="italic" font-weight="700" font-size="40" fill="#ffffff">G</text></svg>

package/templates/consumer/components/social/avatar.tsx

@@ -4,7 +4,17 @@ import React from "react";
 import { cn } from "@/lib/utils";
 import type { Profile } from "@/lib/social";
 
-/** A round profile photo, or the first letter of the name when there is none. */
+/** The same tints, in the same order, as the iOS app's AvatarView. */
+const TINTS = ["#ff9500", "#ff2d55", "#af52de", "#5856d6", "#30b0c7", "#34c759", "#007aff", "#ff3b30"];
+
+/** A stable tint per username. Same hash as the iOS app, so a person has one color everywhere. */
+export function avatarTint(username: string): string {
+  let h = 0;
+  for (const ch of username) h = (Math.imul(h, 31) + (ch.codePointAt(0) ?? 0)) & 0xffff;
+  return TINTS[h % TINTS.length];
+}
+
+/** A round profile photo, or the first letter of the name on a tinted circle. */
 export function Avatar({
   profile,
   size = 32,
@@ -13,11 +23,12 @@ export function Avatar({
 }: {
   profile: Pick<Profile, "username" | "displayName" | "avatarUrl"> | null | undefined;
   size?: number;
-  /** A colored ring, for people who posted recently. */
+  /** The gradient ring, for people who posted in the last 24 hours. */
   ring?: boolean;
   className?: string;
 }) {
   const letter = (profile?.displayName || profile?.username || "?").trim().charAt(0).toUpperCase();
+  const tint = avatarTint(profile?.username ?? "");
   const inner = profile?.avatarUrl ? (
     <img
       src={profile.avatarUrl}
@@ -29,22 +40,25 @@ export function Avatar({
     />
   ) : (
     <span
-      className="grid size-full place-items-center rounded-full bg-zinc-200 font-semibold text-zinc-600"
-      style={{ fontSize: Math.max(10, Math.round(size * 0.4)) }}
+      aria-hidden
+      className="grid size-full place-items-center rounded-full font-semibold text-white"
+      style={{
+        fontSize: Math.max(10, Math.round(size * 0.42)),
+        background: `linear-gradient(to bottom, color-mix(in srgb, ${tint} 78%, white), ${tint})`,
+      }}
     >
       {letter}
     </span>
   );
+  const pad = ring ? Math.max(2, Math.round(size * 0.05)) : 0;
   return (
     <span
-      className={cn(
-        "inline-block shrink-0 rounded-full",
-        ring ? "bg-brand p-[2px]" : "",
-        className,
-      )}
-      style={{ width: size + (ring ? 4 : 0), height: size + (ring ? 4 : 0) }}
+      className={cn("inline-block shrink-0 rounded-full", ring ? "bg-story-ring" : "", className)}
+      style={{ width: size + pad * 4, height: size + pad * 4, padding: pad }}
     >
-      <span className={cn("block size-full rounded-full", ring ? "bg-background p-[2px]" : "")}>{inner}</span>
+      <span className="block size-full rounded-full bg-background" style={{ padding: pad }}>
+        {inner}
+      </span>
     </span>
   );
 }

package/templates/consumer/functions/seedFeed.ts

@@ -1,5 +1,5 @@
 import { mutation } from "@pylonsync/functions";
-import { shapeSeed } from "../lib/seed";
+import { SEED_PROFILES, demoUserId, shapeSeed } from "../lib/seed";
 
 /**
  * Load the demo people, posts, likes, comments, and follows once. The feed
@@ -8,7 +8,7 @@ import { shapeSeed } from "../lib/seed";
  *
  * Public so an anonymous first visitor seeds it. `unsafe.insert` writes past
  * the policies, which only accept the caller's own id, so the posts read as
- * twelve different people. It only writes lib/seed.ts. Delete this function
+ * eight different people. It only writes lib/seed.ts. Delete this function
  * and lib/seed.ts when you launch.
  */
 export default mutation<Record<string, never>, { seeded: boolean }>({
@@ -16,7 +16,7 @@ export default mutation<Record<string, never>, { seeded: boolean }>({
   args: {},
   async handler(ctx) {
     await ctx.db.advisoryLock("consumer_seed_feed");
-    const existing = await ctx.db.unsafe.query("Profile", { userId: "demo_mara_bakes", $limit: 1 });
+    const existing = await ctx.db.unsafe.query("Profile", { userId: demoUserId(SEED_PROFILES[0].username), $limit: 1 });
     if (existing.length > 0) return { seeded: false };
 
     const seed = shapeSeed();