@gotcos/glasses-server 6.99.20 → 6.99.29

package/server/lib/web-pet-choice.ts

@@ -0,0 +1,225 @@
+/**
+ * Which pet COS Control Web shows (Miles 11/06 23:06: "build the change pet picker ... Just use the
+ * existing 300 pack that we have on the COS control").
+ *
+ * A choice is one of:
+ *   mac               the pet COS Control shows (its own session-pet-states.json, or its single sprite)
+ *   shipped:<id>      a character COS Control ships in its app bundle (BundledCharacters/<id>, animated),
+ *                     or shipped:cloud-puff, the StarterPet still
+ *   gallery:<id>      one of the OpenPets gallery pets COS Control lists (openpets-catalog.json, about 300).
+ *                     As on the Mac (installOpenPetsThumb), a gallery pick is the gallery picture as a still.
+ *
+ * The choice is kept per browser. Changing the Mac's own pet stays in COS Control on the Mac: the app does
+ * not watch its pet folder, so writing it from here would leave the Mac showing the old pet.
+ * Everything here reads COS Control's files and never writes them.
+ */
+import crypto from 'crypto'
+import fs from 'fs'
+import path from 'path'
+import { controlSupportDir, readPetSources } from './web-pet.js'
+
+export type PetChoice =
+  | { kind: 'mac' }
+  | { kind: 'shipped'; id: string }
+  | { kind: 'gallery'; id: string }
+
+const ID = /^[a-z0-9][a-z0-9-]{0,80}$/
+
+export function parsePetChoice(raw: unknown): PetChoice | null {
+  if (raw === undefined) return { kind: 'mac' }
+  // A repeated ?pet= arrives as an array: refuse it rather than guess.
+  if (typeof raw !== 'string') return null
+  const s = raw
+  if (s === '' || s === 'mac') return { kind: 'mac' }
+  const m = s.match(/^(shipped|gallery):(.+)$/)
+  if (!m || !ID.test(m[2])) return null
+  return { kind: m[1] as 'shipped' | 'gallery', id: m[2] }
+}
+
+export function petChoiceKey(c: PetChoice): string {
+  return c.kind === 'mac' ? 'mac' : `${c.kind}:${c.id}`
+}
+
+/** COS Control's app resources. Most installs live in /Applications; ~/Applications is checked too. */
+export function controlResourcesDir(env: NodeJS.ProcessEnv = process.env): string | null {
+  if (env.COS_CONTROL_RESOURCES_DIR) return env.COS_CONTROL_RESOURCES_DIR
+  for (const base of ['/Applications', path.join(env.HOME || '', 'Applications')]) {
+    const dir = path.join(base, 'COS Control.app', 'Contents', 'Resources')
+    try { if (fs.statSync(dir).isDirectory()) return dir } catch { /* next */ }
+  }
+  return null
+}
+
+/** Names and summaries word for word from COS Control (Models.swift bundledCharacters). Cloud Puff has no
+ *  summary there (defaultCharacterName only), so its line is ours. Keep in step when Control adds a character. */
+const SHIPPED_NAMES: Record<string, { name: string; summary: string }> = {
+  'jedi-miles-windu': { name: 'Jedi Miles Windu', summary: 'Ten animated states. Purple saber and escalating droid fights.' },
+  'jedi-nia-solari': { name: 'Jedi Nia Solari', summary: 'Eight-frame idle and four combat loops. Purple saber, braided silhouette, and Force counters.' },
+  'jedi-elara-vale': { name: 'Jedi Elara Vale', summary: 'Eight-frame idle and four combat loops. Green saber, auburn braid, and agile redirects.' },
+  'jedi-rowan-vale': { name: 'Jedi Rowan Vale', summary: 'Eight-frame idle and four combat loops. Blue saber, two-handed guard, and grounded strikes.' },
+  'cloud-puff': { name: 'Cloud Puff', summary: 'A simple, calm figure. The default for new installs.' },
+}
+
+function isFile(p: string): boolean {
+  try { return fs.statSync(p).isFile() } catch { return false }
+}
+
+export interface ShippedPet { id: string; name: string; summary: string; animated: boolean }
+
+/** Characters the installed COS Control carries. Only folders with a valid state map count. */
+export function shippedPets(resources: string | null = controlResourcesDir()): ShippedPet[] {
+  if (!resources) return []
+  const out: ShippedPet[] = []
+  let names: string[] = []
+  try { names = fs.readdirSync(path.join(resources, 'BundledCharacters')).filter((n) => ID.test(n)).sort() } catch { /* none */ }
+  for (const id of names) {
+    if (Object.keys(readPetSources(path.join(resources, 'BundledCharacters', id))).length === 0) continue
+    const label = SHIPPED_NAMES[id] ?? { name: id.replace(/-/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase()), summary: '' }
+    out.push({ id, name: label.name, summary: label.summary, animated: true })
+  }
+  if (isFile(path.join(resources, 'StarterPet', 'cloud-puff.webp'))) out.push({ id: 'cloud-puff', ...SHIPPED_NAMES['cloud-puff'], animated: false })
+  return out
+}
+
+export interface GalleryPet { id: string; name: string; description: string; category: string; preview: string }
+
+/** The OpenPets gallery COS Control fetched (openpets-catalog.json). Only https previews on openpets.dev. */
+export function galleryPets(dir: string = controlSupportDir()): GalleryPet[] {
+  const file = path.join(dir, 'openpets-catalog.json')
+  let raw: { catalog?: { pets?: unknown[] } }
+  try {
+    if (!isFile(file)) return []
+    raw = JSON.parse(fs.readFileSync(file, 'utf8'))
+  } catch { return [] }
+  const pets = Array.isArray(raw?.catalog?.pets) ? raw.catalog!.pets! : []
+  const out: GalleryPet[] = []
+  const seen = new Set<string>()
+  for (const p of pets as Array<Record<string, unknown>>) {
+    const id = typeof p?.id === 'string' ? p.id : ''
+    const preview = typeof p?.preview === 'string' ? p.preview : ''
+    if (!ID.test(id) || seen.has(id) || !isOpenPetsUrl(preview)) continue
+    seen.add(id)
+    out.push({
+      id,
+      name: typeof p.displayName === 'string' && p.displayName ? p.displayName : id,
+      description: typeof p.description === 'string' ? p.description : '',
+      category: [p.category, p.subcategory].filter((x) => typeof x === 'string' && x).join(' '),
+      preview,
+    })
+  }
+  return out
+}
+
+/** The Mac helper's rule, exactly (HelperSources/main.swift isAllowedThumbURL): https, host openpets.dev, a path
+ *  ending in /thumb.webp, no user or password. The catalog is untrusted; nothing else is ever fetched. */
+export function isOpenPetsUrl(url: string): boolean {
+  try {
+    const u = new URL(url)
+    return u.protocol === 'https:' && u.hostname === 'openpets.dev' && u.port === '' && !u.username && !u.password && u.pathname.endsWith('/thumb.webp')
+  } catch { return false }
+}
+
+export type ResolvedPet =
+  | { kind: 'strips'; dir: string; cacheName: string }
+  | { kind: 'still'; file: string; type: string }
+  | { kind: 'gallery'; id: string; preview: string }
+
+const STILL_TYPES: Record<string, string> = { '.png': 'image/png', '.webp': 'image/webp', '.gif': 'image/gif', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg' }
+
+/** Where the chosen pet's art lives, or null when that pet is not available on this Mac. */
+export function resolvePet(choice: PetChoice, opts: { supportDir?: string; resources?: string | null } = {}): ResolvedPet | null {
+  const support = opts.supportDir ?? controlSupportDir()
+  const resources = opts.resources === undefined ? controlResourcesDir() : opts.resources
+  if (choice.kind === 'mac') {
+    if (Object.keys(readPetSources(support)).length > 0) return { kind: 'strips', dir: support, cacheName: '' }
+    // A gallery pick or a single custom image on the Mac: COS Control's plain sprite (PetSpriteStore.fileStem).
+    for (const ext of Object.keys(STILL_TYPES)) {
+      const file = path.join(support, `session-pet-sprite${ext}`)
+      if (isFile(file)) return { kind: 'still', file, type: STILL_TYPES[ext] }
+    }
+    return null
+  }
+  if (choice.kind === 'shipped') {
+    if (!resources) return null
+    if (choice.id === 'cloud-puff') {
+      const file = path.join(resources, 'StarterPet', 'cloud-puff.webp')
+      return isFile(file) ? { kind: 'still', file, type: 'image/webp' } : null
+    }
+    const dir = path.join(resources, 'BundledCharacters', choice.id)
+    return Object.keys(readPetSources(dir)).length > 0 ? { kind: 'strips', dir, cacheName: `shipped-${choice.id}` } : null
+  }
+  const pet = galleryPets(support).find((p) => p.id === choice.id)
+  return pet ? { kind: 'gallery', id: pet.id, preview: pet.preview } : null
+}
+
+/** The Mac helper's limits (openPetsThumbMaxBytes, timeout 6): 512 KB, enforced while reading, and 6 seconds. */
+export const GALLERY_MAX_BYTES = 512 * 1024
+export const GALLERY_TIMEOUT_MS = 6_000
+/** COS Control keeps the thumbnails it already fetched here (main.swift openPetsThumbsDir, <id>.webp). */
+export const MAC_THUMBS_DIR = 'openpets-thumbs'
+
+function isWebP(b: Buffer): boolean {
+  return b.length >= 12 && b.toString('ascii', 0, 4) === 'RIFF' && b.toString('ascii', 8, 12) === 'WEBP'
+}
+
+/** Read at most max bytes from a response body, cancelling the stream past the limit. */
+async function readCapped(res: Response, max: number): Promise<Buffer> {
+  const reader = res.body?.getReader()
+  if (!reader) return Buffer.from(await res.arrayBuffer())
+  const parts: Buffer[] = []
+  let total = 0
+  for (;;) {
+    const { done, value } = await reader.read()
+    if (done) break
+    total += value.byteLength
+    if (total > max) { await reader.cancel().catch(() => {}); throw new Error('gallery_too_large') }
+    parts.push(Buffer.from(value))
+  }
+  return Buffer.concat(parts)
+}
+
+export type PetFetcher = (url: string, init: { signal: AbortSignal; redirect: 'error' }) => Promise<Response>
+const galleryInflight = new Map<string, Promise<{ file: string; type: string }>>()
+/** A picture that just failed is not asked for again for this long, so a broken gallery is not hammered. */
+export const GALLERY_RETRY_MS = 10 * 60_000
+const galleryFailedAt = new Map<string, number>()
+
+/**
+ * The gallery picture for one pet, downloaded once from openpets.dev (as COS Control does) and kept under
+ * the data folder. Refuses anything the Mac helper would (not WebP, over 512 KB, redirected, slower than 6 s).
+ */
+export function galleryThumb(pet: { id: string; preview: string }, cacheDir: string, fetcher: PetFetcher = fetch as unknown as PetFetcher, macSupportDir: string | null = null): Promise<{ file: string; type: string }> {
+  if (!ID.test(pet.id) || !isOpenPetsUrl(pet.preview)) return Promise.reject(new Error('gallery_pet_invalid'))
+  // The thumbnail COS Control already fetched, when it is a real WebP: no second download (read only).
+  if (macSupportDir) {
+    const mac = path.join(macSupportDir, MAC_THUMBS_DIR, `${pet.id}.webp`)
+    try {
+      if (fs.statSync(mac).isFile() && fs.statSync(mac).size <= GALLERY_MAX_BYTES && isWebP(fs.readFileSync(mac))) return Promise.resolve({ file: mac, type: 'image/webp' })
+    } catch { /* not there: fetch below */ }
+  }
+  const tag = crypto.createHash('sha256').update(pet.preview).digest('hex').slice(0, 12)
+  const base = path.join(cacheDir, `${pet.id}-${tag}`)
+  if (isFile(base + '.webp')) return Promise.resolve({ file: base + '.webp', type: 'image/webp' })
+  const failed = galleryFailedAt.get(base)
+  if (failed && Date.now() - failed < GALLERY_RETRY_MS) return Promise.reject(new Error('gallery_recently_failed'))
+  let job = galleryInflight.get(base)
+  if (!job) {
+    job = (async () => {
+      const res = await fetcher(pet.preview, { signal: AbortSignal.timeout(GALLERY_TIMEOUT_MS), redirect: 'error' })
+      if (res.status !== 200) throw new Error(`gallery_http_${res.status}`)
+      const declared = Number(res.headers.get('content-length') || 0)
+      if (declared > GALLERY_MAX_BYTES) throw new Error('gallery_too_large')
+      const body = await readCapped(res, GALLERY_MAX_BYTES)
+      // WebP only, as the Mac (isOpenPetsWebP).
+      if (!isWebP(body)) throw new Error('gallery_not_image')
+      fs.mkdirSync(cacheDir, { recursive: true })
+      const tmp = `${base}.${process.pid}.${Date.now()}.tmp`
+      fs.writeFileSync(tmp, body)
+      fs.renameSync(tmp, base + '.webp')
+      return { file: base + '.webp', type: 'image/webp' }
+    })().then((ok) => { galleryFailedAt.delete(base); return ok }, (err) => { galleryFailedAt.set(base, Date.now()); throw err })
+      .finally(() => galleryInflight.delete(base))
+    galleryInflight.set(base, job)
+  }
+  return job
+}

package/server/lib/web-pet.ts

@@ -0,0 +1,226 @@
+/**
+ * The session pet on COS Control Web (Miles 11/06: "pets brought to the COS ... on home").
+ *
+ * COS Control keeps the active pet as horizontal PNG strips plus `session-pet-states.json`
+ * in `~/Library/Application Support/COS Control`. The web reads that same map, so the phone
+ * shows the pet the Mac shows, with no copy to keep in step.
+ *
+ * The Mac's 1x strips are 256 px tall and up to ~56,000 px wide (Windu's working cast is
+ * 184 frames, 3.2 MB). That is too much for a phone to decode at once, so each pose is
+ * resized to WEB_PET_HEIGHT with macOS `sips` and cut into chunks no wider than
+ * WEB_PET_MAX_CHUNK_WIDTH, each holding whole frames. The result is cached on disk, keyed by
+ * the source file's size and mtime, so a pet change on the Mac shows on the next load.
+ *
+ * `sips` quirk (measured 11/06): `--cropOffset 0 0` crops from the CENTER, while any other
+ * offset is measured from the top-left. The first chunk is therefore cut by flipping the
+ * strip, cropping from the far end, and flipping back. Pixel-identical to a direct crop.
+ */
+import crypto from 'crypto'
+import { execFile } from 'child_process'
+import fs from 'fs'
+import os from 'os'
+import path from 'path'
+
+/** The poses COS Control's live pet uses (PetSpritePose.liveCases). */
+export const WEB_PET_POSES = ['idle', 'patrol', 'waiting', 'working', 'duel', 'trio', 'swarm', 'done', 'error', 'attention'] as const
+export type WebPetPose = typeof WEB_PET_POSES[number]
+/** Frame height sent to the phone, in pixels. */
+export const WEB_PET_HEIGHT = 160
+/** Widest chunk sent, in pixels. Keeps each decoded image near 5 MB. */
+export const WEB_PET_MAX_CHUNK_WIDTH = 8192
+
+export interface PetPoseSource { pose: WebPetPose; file: string; frames: number; interval: number; width: number; height: number; size: number; mtimeMs: number }
+export interface PetPosePlan extends PetPoseSource { outHeight: number; frameWidth: number; perChunk: number; chunks: number; key: string }
+
+export function controlSupportDir(env: NodeJS.ProcessEnv = process.env): string {
+  return env.COS_CONTROL_SUPPORT_DIR || path.join(os.homedir(), 'Library', 'Application Support', 'COS Control')
+}
+
+/** Width and height from a PNG's IHDR, or null for anything that is not a PNG. */
+export function pngSize(file: string): { width: number; height: number } | null {
+  let fd: number | null = null
+  try {
+    // Non-blocking: a FIFO planted at this path would otherwise hang the whole server (hazard-invariants.test.ts).
+    fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NONBLOCK)
+    if (!fs.fstatSync(fd).isFile()) return null
+    const head = Buffer.alloc(24)
+    if (fs.readSync(fd, head, 0, 24, 0) < 24) return null
+    if (head.readUInt32BE(0) !== 0x89504e47 || head.toString('ascii', 12, 16) !== 'IHDR') return null
+    return { width: head.readUInt32BE(16), height: head.readUInt32BE(20) }
+  } catch {
+    return null
+  } finally {
+    if (fd !== null) fs.closeSync(fd)
+  }
+}
+
+/** A file name from the state map, kept inside the support folder. */
+function insideDir(dir: string, name: unknown): string | null {
+  if (typeof name !== 'string' || !name || name.includes('\0') || path.isAbsolute(name)) return null
+  const full = path.resolve(dir, name)
+  return full.startsWith(path.resolve(dir) + path.sep) ? full : null
+}
+
+/** Read the Mac's pet. Poses with a missing, unreadable or mismatched strip are left out. */
+export function readPetSources(dir: string): Partial<Record<WebPetPose, PetPoseSource>> {
+  let map: { poses?: Record<string, { file?: unknown; frames?: unknown; interval?: unknown }> }
+  const mapFile = path.join(dir, 'session-pet-states.json')
+  try {
+    // Only a regular file is read: readFileSync on a FIFO blocks the event loop.
+    if (!fs.statSync(mapFile).isFile()) return {}
+    map = JSON.parse(fs.readFileSync(mapFile, 'utf8'))
+  } catch { return {} }
+  const out: Partial<Record<WebPetPose, PetPoseSource>> = {}
+  for (const pose of WEB_PET_POSES) {
+    const row = map?.poses?.[pose]
+    if (!row) continue
+    const file = insideDir(dir, row.file)
+    const frames = Number(row.frames)
+    if (!file || !Number.isInteger(frames) || frames < 1 || frames > 1000) continue
+    let stat: fs.Stats
+    try { stat = fs.statSync(file) } catch { continue }
+    if (!stat.isFile()) continue
+    const size = pngSize(file)
+    if (!size || size.height < 8 || size.width % frames !== 0) continue
+    const interval = Number(row.interval)
+    out[pose] = {
+      pose, file, frames, interval: Number.isFinite(interval) && interval >= 0.01 && interval <= 2 ? interval : 0.12,
+      width: size.width, height: size.height, size: stat.size, mtimeMs: stat.mtimeMs,
+    }
+  }
+  return out
+}
+
+/** How a pose is resized and chunked. Frame width is rounded once, so every chunk holds whole frames. */
+export function planPose(src: PetPoseSource, height = WEB_PET_HEIGHT, maxChunk = WEB_PET_MAX_CHUNK_WIDTH): PetPosePlan {
+  const frameWidth = Math.max(1, Math.round((src.width / src.frames) * (height / src.height)))
+  const perChunk = Math.max(1, Math.floor(maxChunk / frameWidth))
+  const chunks = Math.ceil(src.frames / perChunk)
+  const key = crypto.createHash('sha256')
+    .update(`${src.file}\0${src.size}\0${src.mtimeMs}\0${src.frames}\0${height}\0${maxChunk}\0v1`)
+    .digest('hex').slice(0, 16)
+  return { ...src, outHeight: height, frameWidth, perChunk, chunks, key }
+}
+
+export function webPetManifest(dir: string = controlSupportDir(), pet = 'mac') {
+  const sources = readPetSources(dir)
+  const poses: Record<string, { frames: number; interval: number; frameWidth: number; height: number; perChunk: number; chunks: string[] }> = {}
+  for (const pose of WEB_PET_POSES) {
+    const src = sources[pose]
+    if (!src) continue
+    const p = planPose(src)
+    poses[pose] = {
+      frames: p.frames, interval: p.interval, frameWidth: p.frameWidth, height: WEB_PET_HEIGHT, perChunk: p.perChunk,
+      chunks: Array.from({ length: p.chunks }, (_, i) => `/api/web-pet/sheet/${pose}/${i}?pet=${encodeURIComponent(pet)}&v=${p.key}`),
+    }
+  }
+  return { available: Object.keys(poses).length > 0, poses }
+}
+
+type Run = (cmd: string, args: string[]) => Promise<void>
+const sips: Run = (cmd, args) => new Promise((resolve, reject) => {
+  execFile(cmd, args, { timeout: 30_000 }, (err) => (err ? reject(err) : resolve()))
+})
+
+export interface PetChunkOptions { cacheDir: string; run?: Run; sipsPath?: string }
+const inflight = new Map<string, Promise<string>>()
+
+/**
+ * The PNG path for one chunk of one pose, building it on first request. Every chunk of the pose
+ * is built together, so a pose costs one resize. Concurrent requests share one build.
+ */
+export function petChunk(plan: PetPosePlan, index: number, opts: PetChunkOptions): Promise<string> {
+  if (!Number.isInteger(index) || index < 0 || index >= plan.chunks) return Promise.reject(new Error('no_such_chunk'))
+  const base = path.join(opts.cacheDir, `${plan.pose}-${plan.key}`)
+  const target = `${base}-${index}.png`
+  if (fs.existsSync(target)) return Promise.resolve(target)
+  let job = inflight.get(base)
+  if (!job) {
+    job = buildPose(plan, base, opts).finally(() => inflight.delete(base))
+    inflight.set(base, job)
+  }
+  return job.then(() => target)
+}
+
+async function buildPose(plan: PetPosePlan, base: string, opts: PetChunkOptions): Promise<string> {
+  const run = opts.run ?? sips
+  const bin = opts.sipsPath ?? '/usr/bin/sips'
+  fs.mkdirSync(opts.cacheDir, { recursive: true })
+  const tmp = fs.mkdtempSync(path.join(opts.cacheDir, '.build-'))
+  try {
+    const H = plan.outHeight
+    const total = plan.frameWidth * plan.frames
+    const resized = path.join(tmp, 'resized.png')
+    await run(bin, ['-z', String(H), String(total), plan.file, '--out', resized])
+    let flipped: string | null = null
+    for (let i = 0; i < plan.chunks; i++) {
+      const x = i * plan.perChunk * plan.frameWidth
+      const w = Math.min(plan.perChunk, plan.frames - i * plan.perChunk) * plan.frameWidth
+      const out = path.join(tmp, `${i}.png`)
+      if (plan.chunks === 1) {
+        fs.copyFileSync(resized, out)
+      } else if (x === 0) {
+        // `--cropOffset 0 0` means centre to sips: cut the first chunk from the mirrored strip's far end.
+        if (!flipped) { flipped = path.join(tmp, 'flipped.png'); await run(bin, ['-f', 'horizontal', resized, '--out', flipped]) }
+        const far = path.join(tmp, `${i}-far.png`)
+        await run(bin, ['-c', String(H), String(w), '--cropOffset', '0', String(total - w), flipped, '--out', far])
+        await run(bin, ['-f', 'horizontal', far, '--out', out])
+      } else {
+        await run(bin, ['-c', String(H), String(w), '--cropOffset', '0', String(x), resized, '--out', out])
+      }
+    }
+    for (let i = 0; i < plan.chunks; i++) fs.renameSync(path.join(tmp, `${i}.png`), `${base}-${i}.png`)
+    // Drop this pose's older builds (a pet change on the Mac makes a new key).
+    const keep = path.basename(base) + '-'
+    for (const name of fs.readdirSync(opts.cacheDir)) {
+      if (name.startsWith(`${plan.pose}-`) && !name.startsWith(keep) && name.endsWith('.png')) fs.rmSync(path.join(opts.cacheDir, name), { force: true })
+    }
+    return base
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true })
+  }
+}
+
+/** Height of the first-frame previews in the pet picker. */
+export const WEB_PET_PREVIEW_HEIGHT = 96
+
+/**
+ * One still frame (the first frame of idle, else of the first pose this pet has) for the picker, built once
+ * with sips and cached. Uses the same flip-and-crop as the first chunk, since sips reads offset 0 as centre.
+ */
+export function petPreview(dir: string, cacheDir: string, opts: { run?: Run; sipsPath?: string } = {}): Promise<string> {
+  const sources = readPetSources(dir)
+  const src = sources.idle ?? WEB_PET_POSES.map((p) => sources[p]).find(Boolean)
+  if (!src) return Promise.reject(new Error('no_pet_art'))
+  const plan = planPose(src, WEB_PET_PREVIEW_HEIGHT)
+  const target = path.join(cacheDir, `preview-${plan.key}.png`)
+  if (fs.existsSync(target)) return Promise.resolve(target)
+  let job = inflight.get(target)
+  if (!job) {
+    job = (async () => {
+      const run = opts.run ?? sips
+      const bin = opts.sipsPath ?? '/usr/bin/sips'
+      fs.mkdirSync(cacheDir, { recursive: true })
+      const tmp = fs.mkdtempSync(path.join(cacheDir, '.preview-'))
+      try {
+        const H = plan.outHeight, total = plan.frameWidth * plan.frames, w = plan.frameWidth
+        const resized = path.join(tmp, 'resized.png'), out = path.join(tmp, 'out.png')
+        await run(bin, ['-z', String(H), String(total), plan.file, '--out', resized])
+        if (plan.frames === 1) {
+          fs.copyFileSync(resized, out)
+        } else {
+          const flipped = path.join(tmp, 'flipped.png'), far = path.join(tmp, 'far.png')
+          await run(bin, ['-f', 'horizontal', resized, '--out', flipped])
+          await run(bin, ['-c', String(H), String(w), '--cropOffset', '0', String(total - w), flipped, '--out', far])
+          await run(bin, ['-f', 'horizontal', far, '--out', out])
+        }
+        fs.renameSync(out, target)
+        return target
+      } finally {
+        fs.rmSync(tmp, { recursive: true, force: true })
+      }
+    })().finally(() => inflight.delete(target))
+    inflight.set(target, job)
+  }
+  return job
+}

package/server/lib/work-lens-rounds.ts

@@ -36,7 +36,14 @@ const MAX_SENDS_KEPT = 8
 const MAX_STOPS_KEPT = 8
 
 const WORK_ID = /^task:[a-z_]+:[a-f0-9]{12}$/
-const CLIENT_ROUND_ID = /^lens-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
+const CLIENT_ROUND_ID = /^(lens|web)-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
+/**
+ * Who made the plan: the lens, or COS Control Web (Work chat on the phone or in a browser; GET /api/work/chat/web-plans
+ * says this server takes it). The client round id starts with its source (`lens-`, `web-`). A web round is the same contract as a
+ * lens round: recorded, sent only by COS Control through its own Send, never by this server.
+ */
+export const ROUND_SOURCES = ['lens', 'web'] as const
+export type RoundSource = typeof ROUND_SOURCES[number]
 const SID = /^(claude|codex|cursor):[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/
 const ITEM_ID = /^[a-z]{1,8}(:[a-f0-9]{12})?$/
 const RECEIPT_ID = /^[A-Za-z0-9_.:-]{1,80}$/
@@ -72,6 +79,8 @@ export interface LensRound {
   /** The card's sessions (Control snapshot links and receipts) when the plan was recorded; null when no snapshot. */
   cardSessions: string[] | null
   sends: LensSendRequest[]; stops: LensStopRequest[]; updatedAt: number
+  /** Set only on a round COS Control Web made. A lens round has no `source`, so its stored shape is unchanged. */
+  source?: 'web'
   /** COS Control's own Send of this round's assignments on the Mac (the lens was told to send from the Mac): when, and which. */
   mac?: { at: number; ids: string[] } | null
 }
@@ -89,7 +98,7 @@ const newId = (prefix: string) => `${prefix}_${randomBytes(8).toString('hex')}`
 
 export interface LensRoundInput {
   workID: string; clientRoundId: string; question: string; answer: string; planner: string | null; effort: string | null
-  orchestrator: boolean; assignments: Omit<LensAssignment, 'state'>[]; createdAt: string
+  orchestrator: boolean; assignments: Omit<LensAssignment, 'state'>[]; createdAt: string; source: RoundSource
 }
 
 /** The record body. Unknown keys are ignored and never stored. */
@@ -103,7 +112,8 @@ export function parseLensRound(v: unknown): LensRoundInput {
   if (v.planner !== undefined && !(WORK_CHAT_PLANNERS as readonly unknown[]).includes(v.planner)) throw invalid('planner')
   if (v.effort !== undefined && !(WORK_CHAT_EFFORTS as readonly unknown[]).includes(v.effort)) throw invalid('effort')
   if (v.orchestrator !== undefined && typeof v.orchestrator !== 'boolean') throw invalid('orchestrator')
-  if (v.source !== 'lens') throw invalid('source')
+  if (!(ROUND_SOURCES as readonly unknown[]).includes(v.source)) throw invalid('source')
+  if (!v.clientRoundId.startsWith(`${v.source}-`)) throw invalid('clientRoundId', 'The round id must start with its source.')
   if (!iso(v.createdAt)) throw invalid('createdAt')
   if (!Array.isArray(v.assignments) || v.assignments.length > WORK_CHAT_MAX_ASSIGNMENTS) throw invalid('assignments')
   const assignments: LensRoundInput['assignments'] = []
@@ -122,7 +132,19 @@ export function parseLensRound(v: unknown): LensRoundInput {
       ...(a.contextItemIDs ? { contextItemIDs: [...new Set<string>(a.contextItemIDs)] } : {}) })
   })
   return { workID: v.workID, clientRoundId: v.clientRoundId, question: v.question, answer: v.answer, planner: v.planner ?? null,
-    effort: v.effort ?? null, orchestrator: v.orchestrator === true, assignments, createdAt: v.createdAt }
+    effort: v.effort ?? null, orchestrator: v.orchestrator === true, assignments, createdAt: v.createdAt, source: v.source }
+}
+
+/**
+ * A web round sent again under the same id must be the same plan. The lens keeps its replay rule (the stored round is
+ * answered, whatever the repeat carries); a web repeat with any other question, answer, planner, effort or assignment is
+ * refused, so one id can never stand for two plans. createdAt is when the plan was made and may be re-sent as it was.
+ */
+export function sameRoundContent(round: LensRound, input: LensRoundInput): boolean {
+  const plan = (r: { workID: string; question: string; answer: string; planner: string | null; effort: string | null; orchestrator: boolean;
+    assignments: Omit<LensAssignment, 'state'>[] }) => JSON.stringify([r.workID, r.question, r.answer, r.planner, r.effort, r.orchestrator,
+    r.assignments.map(a => [a.id, a.mode, a.sessionID ?? null, a.provider ?? null, a.prompt, a.contextItemIDs ?? null])])
+  return plan(round) === plan(input)
 }
 
 /** The card's sessions as COS Control's snapshot records them: confirmed links, receipt targets and fork children. */
@@ -240,6 +262,7 @@ export class LensRoundStore {
       answer: input.answer, planner: input.planner, effort: input.effort, orchestrator: input.orchestrator,
       assignments: input.assignments.map(a => ({ ...a, state: 'pending' as const })), createdAt: input.createdAt, recordedAt: now,
       inHistory: false, historyAt: null, autoSendCard: false, cardSessions, sends: [], stops: [], updatedAt: now,
+      ...(input.source === 'web' ? { source: 'web' as const } : {}),
     }
     this.file.rounds.push(round)
     while (this.file.rounds.length > LENS_ROUNDS_MAX) {
@@ -320,6 +343,7 @@ export class LensRoundStore {
     if (changed) this.persist()
     const content = (r: LensRound) => ({ roundId: r.roundId, workID: r.workID, clientRoundId: r.clientRoundId, question: r.question, answer: r.answer,
       planner: r.planner, effort: r.effort, orchestrator: r.orchestrator, createdAt: r.createdAt, recordedAt: new Date(r.recordedAt).toISOString(),
+      ...(r.source === 'web' ? { source: 'web' as const } : {}),
       assignments: r.assignments.map(a => ({ id: a.id, mode: a.mode, ...(a.sessionID ? { sessionID: a.sessionID } : {}), ...(a.provider ? { provider: a.provider } : {}),
         prompt: a.prompt, ...(a.contextItemIDs ? { contextItemIDs: a.contextItemIDs } : {}) })) })
     return {
@@ -432,6 +456,7 @@ export function roundView(r: LensRound) {
   }
   return {
     roundId: r.roundId, workID: r.workID, state, inHistory: r.inHistory, autoSendCard: r.autoSendCard,
+    ...(r.source === 'web' ? { source: 'web' as const } : {}),
     assignments: r.assignments.map(a => ({ id: a.id, state: a.state, ...(a.reportedSessionID ?? a.sessionID ? { sessionID: a.reportedSessionID ?? a.sessionID } : {}),
       ...(a.receiptId ? { receiptId: a.receiptId } : {}), ...(a.detail ? { detail: a.detail } : {}) })),
     updatedAt: new Date(r.updatedAt).toISOString(),