Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

feat(devices): custom pets on the round dial

0xdiego2554f16eff68ab
diff --git a/cli/package-lock.json b/cli/package-lock.json
index fdb5eb7ef..2cbaa87cb 100644
--- a/cli/package-lock.json
+++ b/cli/package-lock.json
@@ -16,6 +16,7 @@
"bonjour-service": "^1.4.4",
"chokidar": "^4.0.0",
"dotenv": "^17.2.3",
+ "pngjs": "^7.0.0",
"qrcode-generator": "^2.0.4",
"werift": "0.24.4",
"ws": "^8.18.0",
@@ -27,6 +28,7 @@
},
"devDependencies": {
"@types/node": "^20.14.10",
+ "@types/pngjs": "^6.0.5",
"@types/ws": "^8.18.1",
"@vitest/coverage-v8": "4.1.10",
"esbuild": "^0.27.2",
@@ -1261,6 +1263,16 @@
"undici-types": "~6.21.0"
}
},
+ "node_modules/@types/pngjs": {
+ "version": "6.0.5",
+ "resolved": "https://registry.npmjs.org/@types/pngjs/-/pngjs-6.0.5.tgz",
+ "integrity": "sha512-0k5eKfrA83JOZPppLtS2C7OUtyNAl2wKNxfyYl9Q5g9lPkgBl/9hNyAu6HuEH2J4XmIv2znEpkDd0SaZVxW6iQ==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "@types/node": "*"
+ }
+ },
"node_modules/@types/ws": {
"version": "8.18.1",
"resolved": "https://registry.npmjs.org/@types/ws/-/ws-8.18.1.tgz",
@@ -2223,6 +2235,15 @@
"url": "https://github.com/sponsors/jonschlinkert"
}
},
+ "node_modules/pngjs": {
+ "version": "7.0.0",
+ "resolved": "https://registry.npmjs.org/pngjs/-/pngjs-7.0.0.tgz",
+ "integrity": "sha512-LKWqWJRhstyYo9pGvgor/ivk2w94eSjE3RGVuzLGlr3NmD8bf7RcYGze1mNdEHRP6TRP6rMuDHk5t44hnTRyow==",
+ "license": "MIT",
+ "engines": {
+ "node": ">=14.19.0"
+ }
+ },
"node_modules/postcss": {
"version": "8.5.16",
"resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.16.tgz",
diff --git a/cli/package.json b/cli/package.json
index e8171caeb..bcb21a9d9 100644
--- a/cli/package.json
+++ b/cli/package.json
@@ -36,6 +36,7 @@
"bonjour-service": "^1.4.4",
"chokidar": "^4.0.0",
"dotenv": "^17.2.3",
+ "pngjs": "^7.0.0",
"qrcode-generator": "^2.0.4",
"werift": "0.24.4",
"ws": "^8.18.0",
@@ -43,6 +44,7 @@
},
"devDependencies": {
"@types/node": "^20.14.10",
+ "@types/pngjs": "^6.0.5",
"@types/ws": "^8.18.1",
"@vitest/coverage-v8": "4.1.10",
"esbuild": "^0.27.2",
diff --git a/cli/src/backendSocket.devices.spec.ts b/cli/src/backendSocket.devices.spec.ts
index 2a239f6a5..2f1ef2752 100644
--- a/cli/src/backendSocket.devices.spec.ts
+++ b/cli/src/backendSocket.devices.spec.ts
@@ -6,7 +6,9 @@ import { dispatchDown, gatewayOf, relaySocket } from './testing/relaySocket.js'
// The Devices tab's requests are the devices' own (services/devices.ts): the socket only routes them, with
// who asked as it established it, and the devices answer the owner alone.
describe('Devices host ownership', () => {
- it.each(DEVICES_REQUESTS)('routes %s to the devices only sealed from afar, saying who asked, and replies to that connection', async type => {
+ // The pet_* requests are local-only by design (services/devices.ts answers them to a local asker): they are not
+ // in the E2EE lists, so there is no sealed remote path to exercise here.
+ it.each(DEVICES_REQUESTS.filter(type => !type.startsWith('pet_')))('routes %s to the devices only sealed from afar, saying who asked, and replies to that connection', async type => {
const socket: BackendSocket = relaySocket('fixture')
const routed: Asker[] = []
socket.serviceRouter = (asked, _payload, asker, reply) => {
diff --git a/cli/src/cable/cableFleet.ts b/cli/src/cable/cableFleet.ts
index b2ff34506..098263bd8 100644
--- a/cli/src/cable/cableFleet.ts
+++ b/cli/src/cable/cableFleet.ts
@@ -328,4 +328,16 @@ export class CableFleet {
turnDone(...args: Parameters<Surface['turnDone']>) { return this.send('turnDone', ...args) }
summary(...args: Parameters<Surface['summary']>) { return this.send('summary', ...args) }
turnError(...args: Parameters<Surface['turnError']>) { return this.send('turnError', ...args) }
+ /** The pet mapping changed: every live dial is brought in line, each on its own link. */
+ petsChanged() { return this.send('petsChanged') }
+ /**
+ * The Devices tab shows ONE pet state. With several dials attached it is the first attached one (discovery
+ * order), the same choice `publish` makes for the flat status; a pull-down per dial is a later concern.
+ */
+ petDial(): ReturnType<Surface['petDial']> {
+ for (const entry of this.entries.values()) {
+ if (entry.attached && entry.session.petDial) return entry.session.petDial()
+ }
+ return { supported: false, held: [], sending: null, errors: {} }
+ }
}
diff --git a/cli/src/cable/cableFrame.ts b/cli/src/cable/cableFrame.ts
index c52642dba..a9e1ac92e 100644
--- a/cli/src/cable/cableFrame.ts
+++ b/cli/src/cable/cableFrame.ts
@@ -53,6 +53,7 @@ export const CableType = {
Pcm: 0x02, // one chunk of 16-bit mono PCM, dial → daemon, during a voice turn
Fw: 0x03, // one slice of a firmware image, daemon → dial only
Log: 0x04, // one ESP_LOG line, dial → daemon, raw bytes (no JSON escaping)
+ Pet: 0x05, // one slice of a custom pet pack, daemon → dial only (same credit window as Fw)
} as const
/**
diff --git a/cli/src/cable/cableHost.ts b/cli/src/cable/cableHost.ts
index f753bdcf0..06c7b727b 100644
--- a/cli/src/cable/cableHost.ts
+++ b/cli/src/cable/cableHost.ts
@@ -32,6 +32,7 @@ import type { WindowRoute } from './windowRoute.js'
import type { SelectionCommand, SelectionResult } from './windowSelection.js'
import type { VisitCommand, VisitResult } from './windowVisit.js'
import type { FormCommand, FormResult } from './windowForm.js'
+import type { PetStore } from './pets/store.js'
import type { MachineFleet } from './machineFleet.js'
import type { ReviewedAnswer, AnswerReceipt } from './questionInbox.js'
@@ -117,6 +118,8 @@ export interface CableHostWiring {
* fleet is off. Absent, this host routes by itself.
*/
fleet?: () => FleetRouting | null
+ /** The custom pets kept on this computer; the dial's session reads the mapping and packs from it. */
+ pets?: () => PetStore | null
}
/** Whether an id is the router's placeholder for a machine with no id yet (`cable:` and the computer id;
@@ -294,6 +297,10 @@ export class DaemonCableHost implements CableHost {
this.wiring.dialStatus?.(status)
}
+ pets(): PetStore | null {
+ return this.wiring.pets?.() ?? null
+ }
+
currentDialStatus(): DialStatus {
return this.dialStatusNow
}
diff --git a/cli/src/cable/cableSession.spec.ts b/cli/src/cable/cableSession.spec.ts
index 8c5cb484d..2d8cf656a 100644
--- a/cli/src/cable/cableSession.spec.ts
+++ b/cli/src/cable/cableSession.spec.ts
@@ -14,6 +14,7 @@ import { describe, expect, it, vi } from 'vitest'
import { CableDecoder, CableType, encodeCableFrame } from './cableFrame.js'
import { CableSession, type CableAgent, type CableHost, type CableMachine, type CablePort } from './cableSession.js'
import { DialLog } from './dialLog.js'
+import type { PetStore } from './pets/store.js'
/** A port whose two ends are both in this process. */
class LoopbackPort implements CablePort {
@@ -23,6 +24,8 @@ class LoopbackPort implements CablePort {
readonly sent: Array<Record<string, unknown>> = []
/** The raw bytes of every frame written, so a test can assert the 8 KB cap holds. */
readonly frames: Uint8Array[] = []
+ /** Payloads of every pet slice (CableType.Pet) the daemon wrote. */
+ readonly petSlices: Buffer[] = []
closedWith: string | null = null
private decoder = new CableDecoder()
@@ -38,6 +41,7 @@ class LoopbackPort implements CablePort {
if (frame.type === CableType.Json) {
this.sent.push(JSON.parse(Buffer.from(frame.payload).toString('utf8')) as Record<string, unknown>)
}
+ if (frame.type === CableType.Pet) this.petSlices.push(Buffer.from(frame.payload))
})
}
@@ -2362,4 +2366,292 @@ describe('spoken output search purpose', () => {
expect(port.types()).not.toContain('voice.search'); expect(host.sendTurn).not.toHaveBeenCalled()
} finally {await session.stop()}
})
+
+ describe('custom pets', () => {
+ const A = 'a'.repeat(16)
+ const B = 'b'.repeat(16)
+ const NEW = 'c'.repeat(16)
+ /** A pack the size of two slices; the crc field is the u32 at offset 18, as in the real header. */
+ const pack = (fill: number, size = 20_000) => { const b = Buffer.alloc(size, fill); b[4] = 1; b.writeUInt32LE(0xdeadbeef, 18); return b }
+ const packs: Record<string, Buffer> = { [A]: pack(1), [B]: pack(2, 100), [NEW]: pack(3, 100) }
+ const fakeStore = (mapping: { all: string | null; engines: Record<string, string> }) => {
+ const store = {
+ current: mapping,
+ mapping: () => ({ all: store.current.all, engines: { ...store.current.engines } }),
+ pack: async (id: string) => packs[id],
+ }
+ return store
+ }
+ const hello = { t: 'hello', product: 'harness', fw: '0.0.1', proto: 3, mac: 'aa:bb' }
+ const petTypes = (port: LoopbackPort) => port.types().filter((t) => t.startsWith('pet.'))
+
+ it('hello without pets: no pet traffic', async () => {
+ const store = fakeStore({ all: A, engines: {} })
+ const { session, port } = await connect(makeHost({ pets: () => store as unknown as PetStore }))
+ port.say(hello)
+ await settle()
+ expect(petTypes(port)).toEqual([])
+ expect(session.petDial()).toEqual({ supported: false, held: [], sending: null, errors: {} })
+ await session.stop()
+ })
+
+ it('hello with pets:1 and petIds [] → pet.map then pet.offer for the first mapped pack', async () => {
+ const store = fakeStore({ all: A, engines: { claude: B } })
+ const { session, port } = await connect(makeHost({ pets: () => store as unknown as PetStore }))
+ port.say({ ...hello, pets: 1, petIds: [] })
+ await settle()
+ expect(port.sent.find((m) => m.t === 'pet.map')).toEqual({ t: 'pet.map', all: A, engines: { claude: B } })
+ const offers = port.sent.filter((m) => m.t === 'pet.offer')
+ // One transfer at a time: the second offer waits for pet.done of the first.
+ expect(offers).toEqual([{ t: 'pet.offer', id: A, size: 20_000, crc: 0xdeadbeef }])
+ expect(petTypes(port).slice(0, 2)).toEqual(['pet.map', 'pet.offer'])
+ expect(port.types().indexOf('welcome')).toBeLessThan(port.types().indexOf('pet.map'))
+ expect(port.petSlices).toHaveLength(0) // nothing before pet.accept
+ port.say({ t: 'pet.accept', id: A })
+ await settle()
+ expect(port.petSlices.map((b) => b.length)).toEqual([8192, 8192]) // the 16 KB credit window
+ expect(session.petDial().sending).toEqual({ id: A, percent: 0 })
+ port.say({ t: 'pet.progress', id: A, written: 16384 })
+ await settle()
+ expect(Buffer.concat(port.petSlices).equals(packs[A])).toBe(true)
+ expect(session.petDial().sending).toEqual({ id: A, percent: 81 })
+ port.say({ t: 'pet.done', id: A })
+ await settle()
+ expect(session.petDial()).toEqual({ supported: true, held: [A], sending: { id: B, percent: 0 }, errors: {} })
+ expect(port.sent.filter((m) => m.t === 'pet.offer').map((m) => m.id)).toEqual([A, B])
+ await session.stop()
+ })
+
+ it('a hello built before pet.done does not resend the pack it just stored', async () => {
+ // Seen on a dial 2026-10-08: its greeting, assembled while the pack was still arriving, landed after the
+ // pet.done and read as "holds nothing" — both packs went over twice.
+ const store = fakeStore({ all: B, engines: {} })
+ const { session, port } = await connect(makeHost({ pets: () => store as unknown as PetStore }))
+ port.say({ ...hello, pets: 1, petIds: [] })
+ await settle()
+ port.say({ t: 'pet.accept', id: B })
+ await settle()
+ port.say({ t: 'pet.done', id: B })
+ await settle()
+ port.say({ ...hello, pets: 1, petIds: [] })
+ await settle()
+ expect(port.sent.filter((m) => m.t === 'pet.offer').map((m) => m.id)).toEqual([B])
+ expect(session.petDial().held).toEqual([B])
+ await session.stop()
+ })
+
+ it('a cut transfer is resent after reattach', async () => {
+ const store = fakeStore({ all: B, engines: {} })
+ const ports: LoopbackPort[] = []
+ const session = new CableSession(makeHost({ pets: () => store as unknown as PetStore }), tmpLog(), async (onData, onClosed) => {
+ const next = new LoopbackPort(onData, onClosed)
+ ports.push(next)
+ return next
+ })
+ session.start()
+ await vi.waitFor(() => expect(ports).toHaveLength(1))
+ ports[0].say({ ...hello, pets: 1, petIds: [] })
+ await settle()
+ ports[0].say({ t: 'pet.accept', id: B })
+ await settle()
+ expect(session.petDial().sending?.id).toBe(B)
+ await ports[0].close('cable pulled')
+ await settle()
+ expect(session.petDial()).toEqual({ supported: false, held: [], sending: null, errors: {} })
+ // The session's tick reopens the port; the dial greets again, having kept nothing of the cut pack.
+ await vi.waitFor(() => expect(ports).toHaveLength(2), NEXT_TICKS)
+ ports[1].say({ ...hello, pets: 1, petIds: [] })
+ await settle()
+ expect(ports[1].sent.filter((m) => m.t === 'pet.offer')).toEqual([{ t: 'pet.offer', id: B, size: 100, crc: 0xdeadbeef }])
+ await session.stop()
+ })
+
+ it('pet.error memory → reported in petDial; the next hello forgives it, a crc refusal stays until the mapping changes', async () => {
+ const store = fakeStore({ all: A, engines: { claude: B } })
+ const { session, port } = await connect(makeHost({ pets: () => store as unknown as PetStore }))
+ port.say({ ...hello, pets: 1, petIds: [] })
+ await settle()
+ port.say({ t: 'pet.error', id: A, reason: 'memory' })
+ await settle()
+ expect(session.petDial().held).toEqual([])
+ expect(session.petDial().errors).toEqual({ [A]: 'memory' })
+ expect(session.petDial().sending?.id).toBe(B)
+ // The next pack is still tried; the refused one is not retried by the sync itself.
+ expect(port.sent.filter((m) => m.t === 'pet.offer').map((m) => m.id)).toEqual([A, B])
+ port.say({ t: 'pet.error', id: B, reason: 'crc' })
+ await settle()
+ expect(session.petDial().errors).toEqual({ [A]: 'memory', [B]: 'crc' })
+ // A greeting forgives the moment's trouble (memory), not the pack the dial found wrong (crc).
+ port.say({ ...hello, pets: 1, petIds: [] })
+ await settle()
+ expect(port.sent.filter((m) => m.t === 'pet.offer').map((m) => m.id)).toEqual([A, B, A])
+ expect(session.petDial().errors).toEqual({ [B]: 'crc' })
+ // A changed mapping clears everything.
+ await session.petsChanged()
+ expect(session.petDial().errors).toEqual({})
+ await session.stop()
+ })
+
+ it('a hello that lost a held pack abandons the transfer in flight and offers again', async () => {
+ const store = fakeStore({ all: A, engines: { claude: B } })
+ const { session, port } = await connect(makeHost({ pets: () => store as unknown as PetStore }))
+ port.say({ ...hello, pets: 1, petIds: [B] })
+ await settle()
+ port.say({ t: 'pet.accept', id: A })
+ await settle()
+ expect(session.petDial().sending?.id).toBe(A)
+ port.say({ ...hello, pets: 1, petIds: [] }) // rebooted under the open link: it holds nothing
+ await settle()
+ expect(port.sent.filter((m) => m.t === 'pet.offer').map((m) => m.id)).toEqual([A, A])
+ expect(session.petDial().sending).toEqual({ id: A, percent: 0 })
+ // A keepalive that merely does not list the pack in flight leaves it alone.
+ port.say({ ...hello, pets: 1, petIds: [] })
+ await settle()
+ expect(port.sent.filter((m) => m.t === 'pet.offer')).toHaveLength(2)
+ await session.stop()
+ })
+
+ it('a memory refusal after a pet.drop is offered once more after 1.5 s', async () => {
+ vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] })
+ try {
+ const store = fakeStore({ all: A, engines: {} })
+ const { session, port } = await connect(makeHost({ pets: () => store as unknown as PetStore }))
+ port.say({ ...hello, pets: 1, petIds: [NEW] }) // the old pet goes, the new one comes
+ await vi.advanceTimersByTimeAsync(5)
+ expect(port.sent.filter((m) => m.t === 'pet.drop')).toEqual([{ t: 'pet.drop', id: NEW }])
+ port.say({ t: 'pet.error', id: A, reason: 'memory' })
+ await vi.advanceTimersByTimeAsync(1_000)
+ expect(port.sent.filter((m) => m.t === 'pet.offer')).toHaveLength(1)
+ await vi.advanceTimersByTimeAsync(600)
+ expect(port.sent.filter((m) => m.t === 'pet.offer').map((m) => m.id)).toEqual([A, A])
+ // Only once.
+ port.say({ t: 'pet.error', id: A, reason: 'memory' })
+ await vi.advanceTimersByTimeAsync(5_000)
+ expect(port.sent.filter((m) => m.t === 'pet.offer')).toHaveLength(2)
+ await session.stop()
+ } finally {
+ vi.useRealTimers()
+ }
+ })
+
+ it('hello.pets is the newest pack version the dial reads', async () => {
+ const store = fakeStore({ all: A, engines: {} })
+ const { session, port } = await connect(makeHost({ pets: () => store as unknown as PetStore }))
+ port.say({ ...hello, pets: 3, petIds: [] })
+ await settle()
+ expect(session.petDial().supported).toBe(true)
+ expect(port.sent.filter((m) => m.t === 'pet.offer')).toHaveLength(1)
+ await session.stop()
+ })
+
+ it('firmware offer pending → pet transfer waits', async () => {
+ const store = fakeStore({ all: B, engines: {} })
+ const host = makeHost({
+ pets: () => store as unknown as PetStore,
+ firmwareFor: async () => ({ version: '9.9.9', image: Buffer.alloc(2048, 9), sha256: 'x'.repeat(64) }),
+ })
+ const { session, port } = await connect(host)
+ port.say({ ...hello, pets: 1, petIds: [] })
+ await settle()
+ expect(port.types()).toContain('fw.offer')
+ expect(port.types()).toContain('pet.map') // the map is a message, not a transfer
+ expect(port.types()).not.toContain('pet.offer')
+ port.say({ t: 'fw.error', message: 'no' })
+ await settle()
+ expect(port.sent.filter((m) => m.t === 'pet.offer').map((m) => m.id)).toEqual([B])
+ await session.stop()
+ })
+
+ it('a stalled pet transfer times out after 10 s without progress, records timeout, and moves on', async () => {
+ vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] })
+ try {
+ const store = fakeStore({ all: A, engines: { claude: B } })
+ const { session, port } = await connect(makeHost({ pets: () => store as unknown as PetStore }))
+ port.say({ ...hello, pets: 1, petIds: [] })
+ await vi.advanceTimersByTimeAsync(5)
+ expect(port.sent.filter((m) => m.t === 'pet.offer').map((m) => m.id)).toEqual([A])
+ await vi.advanceTimersByTimeAsync(9_000)
+ // progress resets the timer
+ port.say({ t: 'pet.accept', id: A })
+ await vi.advanceTimersByTimeAsync(9_000)
+ expect(session.petDial().errors).toEqual({})
+ await vi.advanceTimersByTimeAsync(1_500)
+ expect(session.petDial().errors).toEqual({ [A]: 'timeout' })
+ expect(port.sent.filter((m) => m.t === 'pet.drop')).toEqual([{ t: 'pet.drop', id: A }])
+ expect(session.petDial().sending?.id).toBe(B)
+ expect(port.sent.filter((m) => m.t === 'pet.offer').map((m) => m.id)).toEqual([A, B])
+ await session.stop()
+ } finally {
+ vi.useRealTimers()
+ }
+ })
+
+ it('petsChanged during the firmwareFor await → no fw.offer once a pet transfer started', async () => {
+ const store = fakeStore({ all: A, engines: {} })
+ let release: () => void = () => {}
+ const gate = new Promise<void>((r) => { release = r })
+ let calls = 0
+ const host = makeHost({
+ pets: () => store as unknown as PetStore,
+ firmwareFor: async () => {
+ calls++
+ if (calls === 1) return null
+ await gate
+ return { version: '9.9.9', image: Buffer.alloc(2048, 9), sha256: 'x'.repeat(64) }
+ },
+ })
+ const { session, port } = await connect(host)
+ port.say({ ...hello, pets: 1, petIds: [A] }) // holds everything: nothing to send yet
+ await settle()
+ port.say({ ...hello, pets: 1, petIds: [A] }) // keepalive: parks inside firmwareFor
+ await settle()
+ expect(calls).toBe(2)
+ store.current = { all: A, engines: { claude: B } }
+ await session.petsChanged()
+ await settle()
+ expect(port.sent.filter((m) => m.t === 'pet.offer').map((m) => m.id)).toEqual([B])
+ release()
+ await settle()
+ expect(port.types()).not.toContain('fw.offer')
+ await session.stop()
+ })
+
+ it('a held pack that is no longer mapped is dropped on hello; the next missing pack is offered after pet.done', async () => {
+ const store = fakeStore({ all: A, engines: { claude: B } })
+ const { session, port } = await connect(makeHost({ pets: () => store as unknown as PetStore }))
+ port.say({ ...hello, pets: 1, petIds: [NEW] })
+ await settle()
+ expect(port.sent.filter((m) => m.t === 'pet.drop')).toEqual([{ t: 'pet.drop', id: NEW }])
+ port.say({ t: 'pet.done', id: A })
+ await settle()
+ expect(port.sent.filter((m) => m.t === 'pet.offer').map((m) => m.id)).toEqual([A, B])
+ await session.stop()
+ })
+
+ it('petsChanged with a new mapping → pet.map resent and only the missing pack offered', async () => {
+ const store = fakeStore({ all: B, engines: {} })
+ const { session, port } = await connect(makeHost({ pets: () => store as unknown as PetStore }))
+ port.say({ ...hello, pets: 1, petIds: [B] })
+ await settle()
+ expect(petTypes(port)).toEqual(['pet.map'])
+ port.sent.length = 0
+ store.current = { all: B, engines: { claude: NEW } }
+ await session.petsChanged()
+ await settle()
+ expect(port.sent.filter((m) => m.t === 'pet.map')).toEqual([{ t: 'pet.map', all: B, engines: { claude: NEW } }])
+ expect(port.sent.filter((m) => m.t === 'pet.offer').map((m) => m.id)).toEqual([NEW])
+ // An unchanged mapping says nothing more.
+ port.say({ t: 'pet.done', id: NEW })
+ await settle()
+ port.sent.length = 0
+ await session.petsChanged()
+ expect(petTypes(port)).toEqual([])
+ // A pack nothing maps any more is dropped.
+ store.current = { all: B, engines: {} }
+ await session.petsChanged()
+ await settle()
+ expect(port.sent.filter((m) => m.t === 'pet.drop')).toEqual([{ t: 'pet.drop', id: NEW }])
+ await session.stop()
+ })
+ })
})
diff --git a/cli/src/cable/cableSession.ts b/cli/src/cable/cableSession.ts
index b79cc0d5e..60c003a20 100644
--- a/cli/src/cable/cableSession.ts
+++ b/cli/src/cable/cableSession.ts
@@ -25,6 +25,10 @@ import { readCompanionIdentity, type CompanionIdentity } from './companionProtoc
import { CableDecoder, CableType, encodeCableFrame } from './cableFrame.js'
import { DialLog } from './dialLog.js'
import { FirmwareTransfer } from './fwPush.js'
+import { PACK_VERSION } from './pets/pack.js'
+import { planPetSync } from './pets/sync.js'
+import type { PetStore } from './pets/store.js'
+import type { PetDialState } from './pets/sync.js'
import { SerialLink, findDialPort } from './serial.js'
import { PassageCarry, withCarriedPassage, type CarryRead } from './passageCarry.js'
import { VoiceDraft, type DraftPin } from './voiceDraft.js'
@@ -325,6 +329,11 @@ export interface CableHost {
recentSummaries(agentId: string): Promise<Array<{ recap: string; text: string }>>
/** What the window still has unread, newest first — replayed to a dial that has just attached. */
listUnread(): UnreadNotification[]
+ /**
+ * The custom pets kept on this computer, or null when there is no store (a host that never heard of pets).
+ * Read by the session itself on every sync, so a mapping changed while a dial is attached is the one it sees.
+ */
+ pets?(): PetStore | null
/**
* The image to offer a dial running `runningVersion`, or null for "nothing to do" — which covers a
* dial that is current, a dev build that must not be touched, and an unreachable manifest.
@@ -490,6 +499,15 @@ function readSettings(value: unknown): DeviceSettings | undefined {
}
}
+/** A pet transfer with no pet.accept / pet.progress for this long is abandoned for the rest of the link. */
+const PET_STALL_MS = 10_000
+/** How long a pet.done outranks a greeting that does not list the pack (see petDoneAt). */
+const PET_DONE_TRUST_MS = 3_000
+/** A dial that refused a pack for memory right after we dropped another is given the room a moment to free. */
+const PET_RETRY_MS = 1500
+/** Refusals that say nothing about the pack itself, so a later hello or a changed mapping may try again. */
+const PET_TRANSIENT = new Set(['timeout', 'unreadable', 'memory', 'busy'])
+
export class CableSession {
private link: CablePort | null = null
private decoder = new CableDecoder()
@@ -574,6 +592,35 @@ export class CableSession {
/** A firmware transfer in flight, and the versions already tried this session. */
private transfer: FirmwareTransfer | null = null
+ /**
+ * Custom pets. A transfer of its own, never `transfer`: the firmware one and this one must never be mistaken for each
+ * other by fw.progress / pet.progress, and pets wait while a firmware image is in flight (see syncPets).
+ * All of it is per LINK: a cut cable forgets it, and the next hello (its petIds without the pack) offers again.
+ */
+ private petTransfer: { id: string; xfer: FirmwareTransfer; size: number; written: number } | null = null
+ /** `hello.pets`: the newest pack version the dial understands (a number >= 1). Absent means old firmware: no pet traffic of any kind. */
+ private petDialMax = 0
+ private petsSupported = false
+ /** A pet.drop went out on this link: the dial's memory may still be settling, so a memory refusal is retried once. */
+ private petDropSent = false
+ private petRetried = new Set<string>()
+ private petRetryTimers = new Set<ReturnType<typeof setTimeout>>()
+ /** Pack ids the dial holds: its hello's petIds, plus each pet.done, minus each pet.drop we sent. */
+ private petHeld = new Set<string>()
+ /**
+ * When each pack's pet.done arrived. A greeting the dial assembled while a pack was still arriving can land after its
+ * pet.done and list it as missing — seen 2026-10-08, when both packs went over twice. A pack confirmed this recently
+ * is believed over such a greeting.
+ */
+ private petDoneAt = new Map<string, number>()
+ /** Packs the dial refused on this link, by reason. Not offered again until the link comes back. */
+ private petErrors = new Map<string, string>()
+ /** The last `pet.map` sent on this link, so a keepalive hello does not repeat it. */
+ private petMapSent = ''
+ /** Runs one sync at a time: hello, pet.done and a changed mapping can all ask for one at once. */
+ private petChain: Promise<void> = Promise.resolve()
+ /** Fires when a pet transfer has made no progress (offer, accept, progress) for PET_STALL_MS. */
+ private petStall: ReturnType<typeof setTimeout> | null = null
/** `<mac>:<version>` already offered on this port. The durable, cross-port guard is `mayOffer`. */
private offered = new Set<string>()
@@ -858,6 +905,21 @@ export class CableSession {
// The dial keeps its running image; the half-written slot is erased again by the next accepted offer.
this.transfer?.finish('interrupted by the port closing')
this.transfer = null
+ // The dial discards a half-received pack when the link drops (it keeps showing the old pet), so there
+ // is nothing to resume: the next hello says what it holds and the missing pack is offered from byte 0.
+ this.petTransfer?.xfer.finish('interrupted by the port closing')
+ this.petTransfer = null
+ this.clearPetStall()
+ this.petsSupported = false
+ this.petHeld.clear()
+ this.petDoneAt.clear()
+ this.petErrors.clear()
+ this.petMapSent = ''
+ this.petDialMax = 0
+ this.petDropSent = false
+ this.petRetried.clear()
+ for (const timer of this.petRetryTimers) clearTimeout(timer)
+ this.petRetryTimers.clear()
}
// ── inbound ───────────────────────────────────────────────────────────────────────────────────────
@@ -1018,6 +1080,9 @@ export class CableSession {
// a flash slot before it answers, so a cadence of retries would spend erase cycles on the user's
// hardware every fifteen seconds, and nothing about the next greeting changes what went wrong.
await this.maybeOfferFirmware(str('fw') ?? '')
+ // AFTER the firmware offer, so a pending image is already `this.transfer` and the pets wait for it.
+ this.readPetHello(msg)
+ await this.syncPets()
return
}
case 'pong':
@@ -1402,7 +1467,65 @@ export class CableSession {
this.transfer = null
this.offeringTo = ''
this.report()
+ // Pets that waited behind the image go now.
+ await this.syncPets()
+ return
+ case 'pet.accept':
+ // Only for the pack in flight; a stale accept for another id must not start slices of this one.
+ if (this.petTransfer && str('id') === this.petTransfer.id) {
+ this.armPetStall()
+ await this.petTransfer.xfer.pump()
+ }
+ return
+ case 'pet.progress':
+ // The credit that lets the next slices go, exactly as fw.progress is.
+ if (this.petTransfer && str('id') === this.petTransfer.id && typeof msg.written === 'number') {
+ this.petTransfer.written = msg.written
+ this.armPetStall()
+ await this.petTransfer.xfer.onProgress(msg.written)
+ }
+ return
+ case 'pet.done': {
+ const id = str('id')
+ if (!id) return
+ if (this.petTransfer?.id === id) {
+ this.petTransfer.xfer.finish('stored')
+ this.petTransfer = null
+ this.clearPetStall()
+ }
+ this.petHeld.add(id)
+ this.petDoneAt.set(id, Date.now())
+ // The next pack, one at a time.
+ await this.syncPets()
+ return
+ }
+ case 'pet.error': {
+ const id = str('id')
+ const reason = str('reason') ?? 'unknown'
+ if (!id) return
+ // memory and busy will not change within this link; crc, version and shape would fail identically on a
+ // resend of the same bytes. All are recorded and none retried until the link comes back.
+ this.petErrors.set(id, reason)
+ this.log(`cable: dial refused pet ${id}: ${reason}`)
+ if (this.petTransfer?.id === id) {
+ this.petTransfer.xfer.finish(`refused: ${reason}`)
+ this.petTransfer = null
+ this.clearPetStall()
+ }
+ // A swap near full memory: the pack we dropped may not be freed yet. Once per pack and link, offer again.
+ if ((reason === 'memory' || reason === 'busy') && this.petDropSent && !this.petRetried.has(id)) {
+ this.petRetried.add(id)
+ const timer = setTimeout(() => {
+ this.petRetryTimers.delete(timer)
+ if (this.petErrors.get(id) === reason) this.petErrors.delete(id)
+ void this.syncPets()
+ }, PET_RETRY_MS)
+ timer.unref?.()
+ this.petRetryTimers.add(timer)
+ }
+ await this.syncPets()
return
+ }
default:
this.log(`cable: unhandled message '${msg.t}'`)
}
@@ -1440,10 +1563,14 @@ export class CableSession {
}
private async maybeOfferFirmware(runningVersion: string): Promise<void> {
- if (!this.host.firmwareFor || this.transfer || !runningVersion) return
+ // A pack in flight also holds it back: the reader task that writes flash is busy with the pack, and the
+ // next hello (every fifteen seconds) asks again.
+ if (!this.host.firmwareFor || this.transfer || this.petTransfer || !runningVersion) return
// The BOARD goes with the version. Which manifest entry this device's image comes from is decided
// from its own hello, never defaulted — see otaKeyForBoard.
const candidate = await this.host.firmwareFor(runningVersion, this.greetedHw).catch(() => null)
+ // A pet transfer may have started while that await was parked (petsChanged); never start an image beside it.
+ if (this.petTransfer || this.transfer) return
// Keyed by DIAL as well as version. Holding bare version strings made this a statement about the
// image rather than about the board: offer 0.0.42 to one dial, swap in a second still on 0.0.41, and
// the second was refused because that version had been offered — to someone else. It then sat on the
@@ -1469,6 +1596,141 @@ export class CableSession {
await this.send({ t: 'fw.offer', version: candidate.version, size: candidate.image.length, sha256: candidate.sha256 })
}
+ // ── custom pets ───────────────────────────────────────────────────────────────────────────────────
+
+ private readPetHello(msg: Message): void {
+ const was = this.petHeld
+ this.petDialMax = typeof msg.pets === 'number' && Number.isFinite(msg.pets) ? Math.floor(msg.pets) : 0
+ this.petsSupported = this.petDialMax >= 1
+ // Each greeting forgives what was only the moment's trouble; a pack the dial found wrong stays refused.
+ this.clearTransientPetErrors()
+ const ids = Array.isArray(msg.petIds) ? msg.petIds.filter((v): v is string => typeof v === 'string' && /^[0-9a-f]{16}$/.test(v)) : []
+ this.petHeld = new Set(this.petsSupported ? ids : [])
+ const now = Date.now()
+ for (const [id, at] of this.petDoneAt) {
+ if (now - at >= PET_DONE_TRUST_MS) this.petDoneAt.delete(id)
+ else if (this.petsSupported && was.has(id)) this.petHeld.add(id)
+ }
+ // A dial that holds less than it did has rebooted under a link that stayed open: it has forgotten the
+ // map too, so it is sent again.
+ const shrank = [...was].some((id) => !this.petHeld.has(id))
+ if (shrank) this.petMapSent = ''
+ // ...and it has forgotten a transfer in flight too (it reboots without the link closing): that one is over. A
+ // hello that lists the pack in flight means it was stored and its pet.done went missing.
+ const t = this.petTransfer
+ if (t && (shrank || this.petHeld.has(t.id))) {
+ t.xfer.finish(this.petHeld.has(t.id) ? 'stored' : 'dial restarted')
+ this.petTransfer = null
+ this.clearPetStall()
+ }
+ }
+
+ private clearTransientPetErrors(): void {
+ for (const [id, reason] of this.petErrors) if (PET_TRANSIENT.has(reason)) this.petErrors.delete(id)
+ }
+
+ /** What the Devices tab shows for this dial's pets. */
+ petDial(): PetDialState & { errors: Record<string, string> } {
+ const t = this.petTransfer
+ return {
+ supported: this.petsSupported,
+ held: [...this.petHeld],
+ sending: t ? { id: t.id, percent: t.size > 0 ? Math.min(100, Math.floor((t.written / t.size) * 100)) : 0 } : null,
+ errors: Object.fromEntries(this.petErrors),
+ }
+ }
+
+ /** The mapping changed on this computer: tell the dial and send what it is missing. */
+ async petsChanged(): Promise<void> {
+ // A different mapping is a different question: whatever was refused before may be answered otherwise now.
+ this.petErrors.clear()
+ await this.syncPets()
+ }
+
+ private syncPets(): Promise<void> {
+ const next = this.petChain.then(() => this.runPetSync())
+ this.petChain = next.catch(() => {})
+ // A failed sync is this dial's log line, never a failed hello.
+ return next.catch((error: unknown) => this.log(`cable: pet sync failed: ${error instanceof Error ? error.message : String(error)}`))
+ }
+
+ private async runPetSync(): Promise<void> {
+ const store = this.host.pets?.()
+ if (!store || !this.petsSupported || !this.link?.isOpen || this.greetedMac === null) return
+ const plan = planPetSync(store.mapping(), [...this.petHeld])
+ const mapKey = JSON.stringify(plan.map)
+ if (mapKey !== this.petMapSent) {
+ this.petMapSent = mapKey
+ await this.send({ t: 'pet.map', all: plan.map.all, engines: plan.map.engines })
+ }
+ for (const id of plan.drop) {
+ this.petHeld.delete(id)
+ this.petDropSent = true
+ await this.send({ t: 'pet.drop', id })
+ }
+ // ONE transfer at a time, and never beside a firmware image: both stream into the same reader task on the dial.
+ // A firmware transfer ending (fw.error here, or the reboot after fw.done and its hello) runs this again.
+ if (this.petTransfer || this.transfer) return
+ for (const id of plan.send) {
+ if (this.petErrors.has(id)) continue
+ const pack = await store.pack(id).catch((error: unknown) => {
+ this.log(`cable: pet ${id} unreadable: ${error instanceof Error ? error.message : String(error)}`)
+ this.petErrors.set(id, 'unreadable')
+ return null
+ })
+ if (!pack || pack.length < 22) continue
+ // Never a pack newer than the dial reads (or than we write): it would only be refused as 'version'.
+ if (pack[4] > Math.min(this.petDialMax, PACK_VERSION)) {
+ this.log(`cable: pet ${id} is pack version ${pack[4]}, the dial reads up to ${this.petDialMax}`)
+ continue
+ }
+ if (this.petTransfer || this.transfer || !this.link?.isOpen) return
+ this.log(`cable: offering pet ${id} (${pack.length} B)`)
+ this.petTransfer = {
+ id,
+ size: pack.length,
+ written: 0,
+ xfer: new FirmwareTransfer(
+ pack,
+ id,
+ async (slice) => {
+ if (!this.link?.isOpen) throw new Error('port closed mid-transfer')
+ await this.link.write(encodeCableFrame(CableType.Pet, slice))
+ },
+ (line) => this.log(line.replace('firmware', 'pet')),
+ ),
+ }
+ // The CRC-32 is the pack's own header field (offset 18), so the dial checks what it received against it.
+ this.armPetStall()
+ await this.send({ t: 'pet.offer', id, size: pack.length, crc: pack.readUInt32LE(18) })
+ return
+ }
+ }
+
+ private clearPetStall(): void {
+ if (this.petStall) clearTimeout(this.petStall)
+ this.petStall = null
+ }
+
+ /** (Re)start the no-progress timer for the pack in flight; a stalled one would block firmware offers forever. */
+ private armPetStall(): void {
+ this.clearPetStall()
+ const t = this.petTransfer
+ if (!t) return
+ this.petStall = setTimeout(() => {
+ this.petStall = null
+ if (this.petTransfer !== t) return
+ this.log(`cable: pet ${t.id} stalled for ${PET_STALL_MS / 1000} s, giving up on this link`)
+ t.xfer.finish('timed out')
+ this.petErrors.set(t.id, 'timeout')
+ this.petTransfer = null
+ // The dial keeps the partial pack until told otherwise; this frees it.
+ void this.send({ t: 'pet.drop', id: t.id }).catch(() => undefined)
+ void this.syncPets()
+ }, PET_STALL_MS)
+ this.petStall.unref?.()
+ }
+
private onPcm(chunk: Buffer): void {
if (!this.voice) return // audio outside a turn is a dial that restarted mid-capture
this.voice.bytes += chunk.length
diff --git a/cli/src/cable/pets/convert.spec.ts b/cli/src/cable/pets/convert.spec.ts
new file mode 100644
index 000000000..e0f47912d
--- /dev/null
+++ b/cli/src/cable/pets/convert.spec.ts
@@ -0,0 +1,235 @@
+import { describe, expect, it } from 'vitest'
+import { convertPet, pixelArtFactor } from './convert.js'
+import { PET_ROWS, type PetRow, type PetSheet, type RgbaFrame } from './sheet.js'
+
+const CW = 192
+const CH = 208
+
+type Painter = (x: number, y: number) => [number, number, number, number]
+
+function frame(paint: Painter, w = CW, h = CH): RgbaFrame {
+ const data = new Uint8Array(w * h * 4)
+ for (let y = 0; y < h; y++) {
+ for (let x = 0; x < w; x++) data.set(paint(x, y), (y * w + x) * 4)
+ }
+ return { width: w, height: h, data }
+}
+
+// A blob of `size` px in colour (r, g, b) in the middle of the cell.
+function blob(r: number, g: number, b: number, size = 60, a = 255): Painter {
+ const x0 = (CW - size) >> 1
+ const y0 = (CH - size) >> 1
+ return (x, y) => (x >= x0 && x < x0 + size && y >= y0 && y < y0 + size ? [r, g, b, a] : [0, 0, 0, 0])
+}
+
+function sheet(rows: Partial<Record<PetRow, RgbaFrame[]>>, cellW = CW, cellH = CH): PetSheet {
+ const full = {} as Record<PetRow, RgbaFrame[]>
+ for (const name of PET_ROWS) full[name] = rows[name] ?? []
+ return { cellW, cellH, rows: full }
+}
+
+const simple = () =>
+ sheet({
+ idle: [frame(blob(200, 30, 30)), frame(blob(30, 200, 30))],
+ running: [frame(blob(30, 30, 200)), frame(blob(200, 200, 30)), frame(blob(30, 200, 200))],
+ })
+
+describe('pixelArtFactor', () => {
+ // 48 x 52 art, each art pixel one of 5 colours, drawn k x k px.
+ const art = (k: number, w = CW, h = CH): RgbaFrame =>
+ frame((x, y) => {
+ const ax = Math.floor(x / k)
+ const ay = Math.floor(y / k)
+ return (ax + ay) % 5 === 0 ? [0, 0, 0, 0] : [40 * ((ax * 3 + ay) % 5), 90, 200 - 10 * (ax % 7), 255]
+ }, w, h)
+
+ it('4x-upscaled art → 4', () => {
+ expect(pixelArtFactor([art(4), art(4)])).toBe(4)
+ })
+
+ it('photo-like → 1', () => {
+ const photo = frame((x, y) => [(x * 7 + y * 3) & 255, (x * 5) & 255, (y * 11) & 255, 255])
+ expect(pixelArtFactor([photo])).toBe(1)
+ })
+
+ it('factor 3 is refused when the cell is not divisible', () => {
+ // 192 divides by 3 but 208 does not, so 3x art cannot be a whole number of art pixels tall.
+ expect(pixelArtFactor([art(3)])).toBe(1)
+ })
+
+ it('no frames → 1', () => {
+ expect(pixelArtFactor([])).toBe(1)
+ })
+})
+
+describe('convertPet', () => {
+ it('alpha 127 is transparent, 128 opaque', () => {
+ const s = sheet({
+ idle: [frame((x, y) => (x < 100 ? [255, (x * 7 + y * 13) & 255, 0, y < 100 ? 127 : 128] : [0, 0, 0, 0]))],
+ running: [frame(blob(0, 0, 255))],
+ })
+ const pet = convertPet(s)
+ const f = pet.frames[pet.listening.frames[0]]
+ expect([f.cols, f.cell]).toEqual([CW, 1])
+ expect(f.cells[50 * f.cols + 50]).toBe(0) // alpha 127
+ expect(f.cells[150 * f.cols + 50]).not.toBe(0) // alpha 128
+ })
+
+ it('palette has <= 256 entries and index 0 is unused', () => {
+ const pet = convertPet(simple())
+ expect(pet.palette.length).toBeLessThanOrEqual(256)
+ expect(pet.palette[0]).toBe(0)
+ for (const f of pet.frames) for (const c of f.cells) expect(c).toBeLessThan(pet.palette.length)
+ })
+
+ it('RGB565 panel order', () => {
+ const pet = convertPet(
+ sheet({ idle: [frame(blob(255, 0, 0))], running: [frame(blob(255, 0, 0))] }),
+ )
+ expect(pet.palette[1]).toBe(0x00f8)
+ })
+
+ it('quantize: 40k-colour sheet → 255 colours in under 2 s', () => {
+ // 200 x 200 distinct colours across 8 frames' worth of area: a gradient in two axes.
+ const grad = (shift: number) =>
+ frame((x, y) => (x < 180 && y < 200 ? [(x * 255) / 180, (y * 255) / 200, (shift * 40 + x + y) & 255, 255] : [0, 0, 0, 0]))
+ const s = sheet({
+ idle: [grad(0), grad(1), grad(2), grad(3)],
+ running: [grad(4), grad(5), grad(6), grad(7)],
+ })
+ const t0 = performance.now()
+ const pet = convertPet(s)
+ const ms = performance.now() - t0
+ expect(ms).toBeLessThan(2000)
+ expect(pet.palette.length).toBeLessThanOrEqual(256)
+ expect(pet.palette.length).toBeGreaterThan(200)
+ })
+
+ it('soft-edge warning above 2 %', () => {
+ // Opaque square whose rim is alpha 200: every opaque edge pixel is partial.
+ const soft: Painter = (x, y) => {
+ const inside = x >= 50 && x < 150 && y >= 50 && y < 150
+ const rim = inside && (x === 50 || x === 149 || y === 50 || y === 149)
+ return inside ? [10, 200, 10, rim ? 200 : 255] : [0, 0, 0, 0]
+ }
+ const noisy = convertPet(sheet({ idle: [frame(soft)], running: [frame(blob(0, 0, 255))] }))
+ expect(noisy.warnings).toContain('Soft edges will look jagged on the dial')
+ expect(convertPet(simple()).warnings).not.toContain('Soft edges will look jagged on the dial')
+ })
+
+ it('review row empty → listening uses idle’s frame indices', () => {
+ const pet = convertPet(simple())
+ expect(pet.listening.frames).toEqual(pet.sending.frames)
+ expect(pet.listening.frames).toEqual(pet.failed.frames)
+ expect(pet.listening.frames.length).toBe(2)
+ // Substitution adds no frames: idle (2) + running (3) at full size, small idle (2).
+ expect(pet.frames.length).toBe(2 + 3 + 2)
+ expect(pet.working.frames.length).toBe(3)
+ expect(new Set([...pet.listening.frames, ...pet.working.frames]).size).toBe(5)
+ })
+
+ it('a filled review row gives listening its own frames', () => {
+ const s = simple()
+ s.rows.review = [frame(blob(1, 2, 3)), frame(blob(4, 5, 6))]
+ const pet = convertPet(s)
+ expect(pet.listening.frames).not.toEqual(pet.sending.frames)
+ })
+
+ it('small pet is the 2x art at cell 1: 2w x 2h cells, w x h being the 1x size (firmware ht_pet_t.cells)', () => {
+ for (const [cw, ch] of [[192, 208], [96, 104]]) {
+ const pet = convertPet(
+ sheet({ idle: [frame(blob(9, 9, 9), cw, ch)], running: [frame(blob(9, 9, 9), cw, ch)] }, cw, ch),
+ )
+ expect(pet.small.w * 2).toBeLessThanOrEqual(150)
+ expect(pet.small.h * 2).toBeLessThanOrEqual(112)
+ expect(pet.small.w).toBeGreaterThan(40)
+ for (const n of pet.small.loops.idle) {
+ const f = pet.frames[n]
+ expect([f.cols, f.rows, f.cell]).toEqual([pet.small.w * 2, pet.small.h * 2, 1])
+ }
+ }
+ })
+
+ it('the same art at half size gives scenes of the same 192 x 208 px', () => {
+ const paint: Painter = (x, y) => ((x >> 3) + (y >> 3)) % 3 === 0 ? [0, 0, 0, 0] : [200, (x * 3) & 255, 40, 255]
+ const half = (p: Painter): Painter => (x, y) => p(x * 2, y * 2)
+ const big = convertPet(sheet({ idle: [frame(paint)], running: [frame(paint)] }))
+ const small = convertPet(sheet({ idle: [frame(half(paint), 96, 104)], running: [frame(half(paint), 96, 104)] }, 96, 104))
+ for (const pet of [big, small]) {
+ const f = pet.frames[pet.working.frames[0]]
+ expect([f.cols * f.cell, f.rows * f.cell]).toEqual([192, 208])
+ }
+ const f = small.frames[small.working.frames[0]]
+ expect([f.cols, f.rows, f.cell]).toEqual([96, 104, 2])
+ // The small resting pet is the same size either way.
+ expect(small.small.w).toBe(big.small.w)
+ })
+
+ it('small loops: idle waves every fourth cycle, asking falls back to idle', () => {
+ const s = simple()
+ s.rows.waving = [frame(blob(9, 99, 9)), frame(blob(99, 9, 99))]
+ const pet = convertPet(s)
+ const idle = pet.small.loops.idle
+ expect(idle.length).toBe(2 * 3 + 2)
+ expect(idle.slice(0, 2)).toEqual(idle.slice(2, 4))
+ expect(idle.slice(6)).not.toEqual(idle.slice(0, 2))
+ expect(pet.small.loops.done).toEqual(pet.small.loops.idle.slice(0, 2))
+ expect(pet.small.loops.asking).toEqual(pet.small.loops.done)
+ })
+
+ it('uses the pixel-art factor as the cell size', () => {
+ const art = (k: number) =>
+ frame((x, y) => {
+ const ax = Math.floor(x / k)
+ const ay = Math.floor(y / k)
+ return ax >= 5 && ax < 40 && ay >= 5 && ay < 40 ? [30 * (ax % 8), 100, 30 * (ay % 8), 255] : [0, 0, 0, 0]
+ })
+ const pet = convertPet(sheet({ idle: [art(4)], running: [art(4)] }))
+ const big = pet.frames.find((f) => f.cell === 4)!
+ expect([big.cols, big.rows]).toEqual([48, 52])
+ })
+
+ it('explicit default rows give the same pet as no choice', () => {
+ const s = simple()
+ s.rows.waving = [frame(blob(9, 99, 9))]
+ s.rows.review = [frame(blob(1, 2, 3))]
+ expect(convertPet(s, { rest: 'idle', working: 'running', listening: 'review', sending: 'waving', asking: 'waiting' })).toEqual(convertPet(s))
+ })
+
+ it('chosen rows play their states; empty listening, sending and asking fall back to the rest row', () => {
+ const s = sheet({
+ jumping: [frame(blob(10, 20, 30)), frame(blob(40, 50, 60))],
+ runningLeft: [frame(blob(70, 80, 90))],
+ waving: [frame(blob(9, 99, 9))],
+ failed: [frame(blob(200, 0, 0))],
+ review: [frame(blob(0, 200, 0)), frame(blob(0, 0, 200)), frame(blob(200, 200, 200))],
+ })
+ const pet = convertPet(s, { rest: 'jumping', working: 'runningLeft', listening: 'review', sending: 'waiting', asking: 'idle' })
+ expect(pet.working.frames.length).toBe(1)
+ expect(pet.listening.frames.length).toBe(3)
+ expect(pet.sending.frames.length).toBe(2) // waiting is empty: the rest row
+ expect(pet.failed.frames.length).toBe(1) // the failed row, not the rest row
+ // No waving pass: the rest row is not idle.
+ expect(pet.small.loops.idle).toEqual([...pet.small.loops.done, ...pet.small.loops.done, ...pet.small.loops.done])
+ expect(pet.small.loops.done.length).toBe(2)
+ expect(pet.small.loops.asking).toEqual(pet.small.loops.done)
+ // Only the frames the pack plays are in it: the waving row is not.
+ expect(pet.frames.length).toBe(2 + 1 + 3 + 1 + 2)
+ })
+
+ it('an empty failed row falls back to the rest row', () => {
+ const s = sheet({ jumping: [frame(blob(10, 20, 30))], running: [frame(blob(70, 80, 90))] })
+ const pet = convertPet(s, { rest: 'jumping' })
+ expect(pet.failed.frames).toEqual(pet.listening.frames)
+ })
+
+ it('refuses an empty chosen rest or working row', () => {
+ expect(() => convertPet(simple(), { working: 'jumping' })).toThrow('The row chosen for Working is empty')
+ expect(() => convertPet(simple(), { rest: 'review' })).toThrow('The row chosen for Rest is empty')
+ })
+
+ it('steps default to 120 ms', () => {
+ const pet = convertPet(simple())
+ expect(pet.working).toMatchObject({ stepMs: 120, dx: 0, dy: 0 })
+ })
+})
diff --git a/cli/src/cable/pets/convert.ts b/cli/src/cable/pets/convert.ts
new file mode 100644
index 000000000..31bbe3ff1
--- /dev/null
+++ b/cli/src/cable/pets/convert.ts
@@ -0,0 +1,393 @@
+import { ALPHA_OPAQUE, resolvePetRows, type PetRow, type PetRows, type PetSheet, type RgbaFrame } from './sheet.js'
+
+// One frame of the pack: `cols` x `rows` palette indices, each drawn as a `cell` px square (0 = transparent).
+export interface IndexedFrame {
+ cols: number
+ rows: number
+ cell: number
+ cells: Uint8Array
+}
+
+// A large scene: frame indices into ConvertedPet.frames, one per step.
+export interface PetScene {
+ frames: number[]
+ stepMs: number
+ dx: number
+ dy: number
+}
+
+export interface ConvertedPet {
+ palette: number[] // RGB565 in panel order (byte-swapped); palette[0] is unused (transparent)
+ frames: IndexedFrame[]
+ // The resting pet (rest, recap, small question): one frame pool with a loop per state. w x h is the 1x size, the
+ // frames are drawn at 2x.
+ small: { w: number; h: number; loops: Record<'idle' | 'done' | 'asking', number[]> }
+ working: PetScene
+ listening: PetScene
+ sending: PetScene
+ failed: PetScene
+ warnings: string[]
+}
+
+export const STEP_MS = 120
+export const SOFT_EDGE_WARNING = 'Soft edges will look jagged on the dial'
+
+// The 2x art of a petdex pet is 192 x 208; the small resting pet is that art fitted into this box (the dial's
+// 1x slot is half of it, ht_pet_t.w/h).
+const ART_W = 192
+const ART_H = 208
+const SMALL_BOX_W = 150
+const SMALL_BOX_H = 112
+// The firmware's loop room (HT_PET_STEPS).
+const LOOP_STEPS = 24
+const IDLE_CYCLES = 3 // rest cycles before one waving pass
+// 254, not 255: the pack stores the entry count (index 0 included) in one byte.
+const MAX_COLOURS = 254
+const SOFT_EDGE_SHARE = 0.02
+
+function opaque(data: Uint8Array, i: number): boolean {
+ return data[i + 3] >= ALPHA_OPAQUE
+}
+
+function gcd(a: number, b: number): number {
+ return b === 0 ? a : gcd(b, a % b)
+}
+
+// The largest k (a divisor of both cell sides) for which every k x k block of every frame is one colour, with
+// opacity judged by the dial's alpha test; 1 otherwise. A pixel-art pet drawn at 4x then becomes cells of 4 px.
+export function pixelArtFactor(frames: RgbaFrame[]): number {
+ if (frames.length === 0) return 1
+ const { width: w, height: h } = frames[0]
+ const g = gcd(w, h)
+ for (let k = g; k > 1; k--) {
+ if (g % k !== 0) continue
+ if (frames.every((f) => f.width === w && f.height === h && uniformBlocks(f, k))) return k
+ }
+ return 1
+}
+
+function uniformBlocks(f: RgbaFrame, k: number): boolean {
+ const { width: w, height: h, data } = f
+ for (let by = 0; by < h; by += k) {
+ for (let bx = 0; bx < w; bx += k) {
+ const o = (by * w + bx) * 4
+ const solid = opaque(data, o)
+ for (let y = 0; y < k; y++) {
+ for (let x = 0; x < k; x++) {
+ const i = ((by + y) * w + bx + x) * 4
+ if (opaque(data, i) !== solid) return false
+ if (solid && (data[i] !== data[o] || data[i + 1] !== data[o + 1] || data[i + 2] !== data[o + 2])) return false
+ }
+ }
+ }
+ }
+ return true
+}
+
+// Opaque edge pixels (an opaque pixel with a transparent 4-neighbour) that carry partial alpha, over all of them.
+function softEdgeShare(f: RgbaFrame): number {
+ const { width: w, height: h, data } = f
+ let edge = 0
+ let partial = 0
+ for (let y = 0; y < h; y++) {
+ for (let x = 0; x < w; x++) {
+ const i = (y * w + x) * 4
+ if (!opaque(data, i)) continue
+ const touches =
+ (x > 0 && !opaque(data, i - 4)) ||
+ (x < w - 1 && !opaque(data, i + 4)) ||
+ (y > 0 && !opaque(data, i - w * 4)) ||
+ (y < h - 1 && !opaque(data, i + w * 4))
+ if (!touches) continue
+ edge++
+ if (data[i + 3] < 255) partial++
+ }
+ }
+ return edge === 0 ? 0 : partial / edge
+}
+
+function rgb565(r: number, g: number, b: number): number {
+ return ((r & 0xf8) << 8) | ((g & 0xfc) << 3) | (b >> 3)
+}
+
+// What ht_cell_frame_t palettes hold: the panel takes the two bytes swapped.
+export function panelOrder(v: number): number {
+ return ((v << 8) | (v >> 8)) & 0xffff
+}
+
+export function expand565(v: number): [number, number, number] {
+ const r = (v >> 11) & 31
+ const g = (v >> 5) & 63
+ const b = v & 31
+ return [(r << 3) | (r >> 2), (g << 2) | (g >> 4), (b << 3) | (b >> 2)]
+}
+
+interface Palette {
+ entries565: number[] // index 0 unused
+ indexOf: Int16Array // by RGB565 key; -1 = not mapped yet
+}
+
+// Median cut over the distinct RGB565 colours of every opaque pixel, weighted by how often each occurs. Working on
+// 565 keys (the dial's own precision) bounds the work by 65 536 colours however large the sheet is, and a pet
+// with <= 255 colours is kept exactly.
+function buildPalette(sources: RgbaFrame[], k: number): Palette {
+ const count = new Float64Array(65536)
+ const sum = [new Float64Array(65536), new Float64Array(65536), new Float64Array(65536)]
+ for (const f of sources) {
+ for (let y = 0; y < f.height; y += k) {
+ for (let x = 0; x < f.width; x += k) {
+ const i = (y * f.width + x) * 4
+ if (!opaque(f.data, i)) continue
+ const r = f.data[i]
+ const g = f.data[i + 1]
+ const b = f.data[i + 2]
+ const key = rgb565(r, g, b)
+ count[key]++
+ sum[0][key] += r
+ sum[1][key] += g
+ sum[2][key] += b
+ }
+ }
+ }
+ const keys: number[] = []
+ for (let key = 0; key < 65536; key++) if (count[key] > 0) keys.push(key)
+ const chan = (key: number, c: number) => expand565(key)[c]
+ const order = Uint32Array.from(keys)
+ const boxes: { lo: number; hi: number }[] = [{ lo: 0, hi: order.length }]
+ const rangeOf = (b: { lo: number; hi: number }) => {
+ const min = [255, 255, 255]
+ const max = [0, 0, 0]
+ for (let i = b.lo; i < b.hi; i++) {
+ const e = expand565(order[i])
+ for (let c = 0; c < 3; c++) {
+ if (e[c] < min[c]) min[c] = e[c]
+ if (e[c] > max[c]) max[c] = e[c]
+ }
+ }
+ let best = 0
+ for (let c = 1; c < 3; c++) if (max[c] - min[c] > max[best] - min[best]) best = c
+ return { channel: best, span: max[best] - min[best] }
+ }
+ while (boxes.length < MAX_COLOURS) {
+ let pick = -1
+ let pickSpan = 0
+ let pickChannel = 0
+ for (let i = 0; i < boxes.length; i++) {
+ const b = boxes[i]
+ if (b.hi - b.lo < 2) continue
+ const { channel, span } = rangeOf(b)
+ if (span > pickSpan) {
+ pick = i
+ pickSpan = span
+ pickChannel = channel
+ }
+ }
+ if (pick < 0) break
+ const b = boxes[pick]
+ order.subarray(b.lo, b.hi).sort((p, q) => chan(p, pickChannel) - chan(q, pickChannel))
+ let total = 0
+ for (let i = b.lo; i < b.hi; i++) total += count[order[i]]
+ let acc = 0
+ let cut = b.lo + 1
+ for (let i = b.lo; i < b.hi - 1; i++) {
+ acc += count[order[i]]
+ cut = i + 1
+ if (acc * 2 >= total) break
+ }
+ boxes.splice(pick, 1, { lo: b.lo, hi: cut }, { lo: cut, hi: b.hi })
+ }
+ const entries565 = [0]
+ const indexOf = new Int16Array(65536).fill(-1)
+ for (const b of boxes) {
+ let n = 0
+ const s = [0, 0, 0]
+ for (let i = b.lo; i < b.hi; i++) {
+ const key = order[i]
+ n += count[key]
+ for (let c = 0; c < 3; c++) s[c] += sum[c][key]
+ }
+ if (n === 0) continue
+ entries565.push(rgb565(Math.round(s[0] / n), Math.round(s[1] / n), Math.round(s[2] / n)))
+ for (let i = b.lo; i < b.hi; i++) indexOf[order[i]] = entries565.length - 1
+ }
+ return { entries565, indexOf }
+}
+
+// The palette index of a colour; a colour no frame had (a scaled-down mix) takes the nearest entry.
+function nearest(p: Palette, r: number, g: number, b: number): number {
+ const key = rgb565(r, g, b)
+ if (p.indexOf[key] >= 0) return p.indexOf[key]
+ let best = 1
+ let bestD = Infinity
+ for (let i = 1; i < p.entries565.length; i++) {
+ const [pr, pg, pb] = expand565(p.entries565[i])
+ const d = (pr - r) ** 2 + (pg - g) ** 2 + (pb - b) ** 2
+ if (d < bestD) {
+ bestD = d
+ best = i
+ }
+ }
+ p.indexOf[key] = best
+ return best
+}
+
+// A frame at its pixel-art resolution: every k-th pixel, since each k x k block is one colour. `cell` is what one
+// of those cells is drawn as on the dial: k, times the factor that brings a half-size sheet back to the 192 x 208 px
+// the scenes are laid out for.
+function indexFrame(f: RgbaFrame, k: number, cell: number, p: Palette): IndexedFrame {
+ const cols = f.width / k
+ const rows = f.height / k
+ const cells = new Uint8Array(cols * rows)
+ for (let y = 0; y < rows; y++) {
+ for (let x = 0; x < cols; x++) {
+ const i = (y * k * f.width + x * k) * 4
+ if (opaque(f.data, i)) cells[y * cols + x] = nearest(p, f.data[i], f.data[i + 1], f.data[i + 2])
+ }
+ }
+ return { cols, rows, cell, cells }
+}
+
+// A frame resampled to cols x rows cells drawn at 1 px: the small pet's frames are the 2x picture (2w x 2h) and the
+// dial shows them at 1x..2x with ht_cell_sprite_zoom, exactly as the built-in pets' (gen_pets.py CELL_PETS).
+// Pixel art whose factor is even is sampled at the nearest pixel (its hard edges stay hard); anything else is
+// box-filtered. Either way a cell is opaque when at least half of what it covers is.
+function scaleFrame(f: RgbaFrame, cols: number, rows: number, nearestSample: boolean, p: Palette): IndexedFrame {
+ const cells = new Uint8Array(cols * rows)
+ for (let y = 0; y < rows; y++) {
+ for (let x = 0; x < cols; x++) {
+ if (nearestSample) {
+ const sx = Math.min(f.width - 1, Math.floor(((x + 0.5) * f.width) / cols))
+ const sy = Math.min(f.height - 1, Math.floor(((y + 0.5) * f.height) / rows))
+ const i = (sy * f.width + sx) * 4
+ if (opaque(f.data, i)) cells[y * cols + x] = nearest(p, f.data[i], f.data[i + 1], f.data[i + 2])
+ continue
+ }
+ const x0 = Math.floor((x * f.width) / cols)
+ const x1 = Math.max(x0 + 1, Math.ceil(((x + 1) * f.width) / cols))
+ const y0 = Math.floor((y * f.height) / rows)
+ const y1 = Math.max(y0 + 1, Math.ceil(((y + 1) * f.height) / rows))
+ let n = 0
+ let solid = 0
+ let r = 0
+ let g = 0
+ let b = 0
+ for (let sy = y0; sy < Math.min(y1, f.height); sy++) {
+ for (let sx = x0; sx < Math.min(x1, f.width); sx++) {
+ const i = (sy * f.width + sx) * 4
+ n++
+ if (!opaque(f.data, i)) continue
+ solid++
+ r += f.data[i]
+ g += f.data[i + 1]
+ b += f.data[i + 2]
+ }
+ }
+ if (solid * 2 >= n && solid > 0) {
+ cells[y * cols + x] = nearest(p, Math.round(r / solid), Math.round(g / solid), Math.round(b / solid))
+ }
+ }
+ }
+ return { cols, rows, cell: 1, cells }
+}
+
+// `choice` is which row plays which state (resolvePetRows: the defaults fill what it leaves out). Without one, a
+// petdex sheet gives exactly the pack it always has.
+export function convertPet(sheet: PetSheet, choice?: Partial<PetRows>): ConvertedPet {
+ const rows = sheet.rows
+ const chosen = resolvePetRows(sheet, choice)
+ const sceneRows: Record<'working' | 'listening' | 'sending' | 'failed', PetRow> = {
+ working: chosen.working,
+ listening: chosen.listening,
+ sending: chosen.sending,
+ failed: rows.failed.length > 0 ? 'failed' : chosen.rest,
+ }
+ // The rest loop waves once every few cycles only when it is petdex's idle row, the one the waving row answers.
+ const waves = chosen.rest === 'idle'
+ const smallRows: PetRow[] = [chosen.rest, ...(waves ? ['waving' as const] : []), chosen.asking]
+
+ // Every frame the pack will draw, once each: the factor, the palette and the warnings are about these.
+ const used = new Set<RgbaFrame>()
+ for (const name of Object.values(sceneRows)) for (const f of rows[name]) used.add(f)
+ for (const name of smallRows) for (const f of rows[name]) used.add(f)
+ const sources = [...used]
+
+ const k = pixelArtFactor(sources)
+ const sceneCell = Math.max(1, Math.round((k * ART_W) / sheet.cellW))
+ const palette = buildPalette(sources, k)
+ const warnings: string[] = []
+ if (sources.some((f) => softEdgeShare(f) > SOFT_EDGE_SHARE)) warnings.push(SOFT_EDGE_WARNING)
+
+ // De-duplicated by content, so a scene that falls back to the rest row points at its frames.
+ const frames: IndexedFrame[] = []
+ const seen = new Map<string, number>()
+ const add = (fr: IndexedFrame): number => {
+ const key = `${fr.cols}x${fr.rows}x${fr.cell}:${Buffer.from(fr.cells).toString('latin1')}`
+ let at = seen.get(key)
+ if (at === undefined) {
+ at = frames.length
+ frames.push(fr)
+ seen.set(key, at)
+ }
+ return at
+ }
+ const full = new Map<RgbaFrame, number>()
+ const fullIndex = (f: RgbaFrame): number => {
+ let at = full.get(f)
+ if (at === undefined) {
+ at = add(indexFrame(f, k, sceneCell, palette))
+ full.set(f, at)
+ }
+ return at
+ }
+ const scene = (name: PetRow): PetScene => ({
+ frames: rows[name].map(fullIndex),
+ stepMs: STEP_MS,
+ dx: 0,
+ dy: 0,
+ })
+
+ // The small pet: the 2x art fitted into 150 x 112, half of which is the 1x size (small.w x small.h). Its frames
+ // are the 2x picture itself, 2w x 2h cells of 1 px.
+ const fit = Math.min(SMALL_BOX_W / ART_W, SMALL_BOX_H / ART_H)
+ const smallW = Math.floor((ART_W * fit) / 2)
+ const smallH = Math.floor((ART_H * fit) / 2)
+ const small = new Map<RgbaFrame, number>()
+ const smallIndex = (f: RgbaFrame): number => {
+ let at = small.get(f)
+ if (at === undefined) {
+ at = add(scaleFrame(f, smallW * 2, smallH * 2, k % 2 === 0, palette))
+ small.set(f, at)
+ }
+ return at
+ }
+ const idle = rows[chosen.rest].map(smallIndex)
+ const wave = waves ? rows.waving.map(smallIndex) : []
+ let cycles = IDLE_CYCLES
+ while (cycles > 1 && idle.length * cycles + wave.length > LOOP_STEPS) cycles--
+ const idleLoop: number[] = []
+ for (let c = 0; c < cycles; c++) idleLoop.push(...idle)
+ idleLoop.push(...wave)
+
+ const working = scene(sceneRows.working)
+ const listening = scene(sceneRows.listening)
+ const sending = scene(sceneRows.sending)
+ const failed = scene(sceneRows.failed)
+ return {
+ palette: palette.entries565.map((v, i) => (i === 0 ? 0 : panelOrder(v))),
+ frames,
+ small: {
+ w: smallW,
+ h: smallH,
+ loops: {
+ idle: idleLoop.slice(0, LOOP_STEPS),
+ done: idle.slice(0, LOOP_STEPS),
+ asking: rows[chosen.asking].map(smallIndex).slice(0, LOOP_STEPS),
+ },
+ },
+ working,
+ listening,
+ sending,
+ failed,
+ warnings,
+ }
+}
diff --git a/cli/src/cable/pets/pack.spec.ts b/cli/src/cable/pets/pack.spec.ts
new file mode 100644
index 000000000..cc7ad6a5b
--- /dev/null
+++ b/cli/src/cable/pets/pack.spec.ts
@@ -0,0 +1,109 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { crc32 } from 'node:zlib'
+import { describe, expect, it } from 'vitest'
+import type { ConvertedPet, IndexedFrame } from './convert.js'
+import { PACK_MAX_BYTES, PACK_VERSION, decodePack, encodePack } from './pack.js'
+import { PetSheetError } from './sheet.js'
+
+const VECTOR = fileURLToPath(
+ new URL('../../../../devices/harness-device/firmware/test/vectors/pet_min.hpet', import.meta.url),
+)
+const ID = Uint8Array.from([1, 2, 3, 4, 5, 6, 7, 8])
+
+function frame(cell: number, rows: string[]): IndexedFrame {
+ // '.' transparent, '1'..'9' palette index.
+ const cols = rows[0].length
+ const cells = new Uint8Array(cols * rows.length)
+ rows.forEach((row, y) => [...row].forEach((ch, x) => (cells[y * cols + x] = ch === '.' ? 0 : Number(ch))))
+ return { cols, rows: rows.length, cell, cells }
+}
+
+// Two 8 x 8 frames: runs at the start, middle and end of rows, a blank row and a full row.
+function fixture(): ConvertedPet {
+ const a = frame(2, ['..1221..', '.123321.', '12333321', '........', '1......1', '..1..1..', '.......1', '11111111'])
+ const b = frame(1, ['3.......', '.3.....3', '..3...3.', '...3.3..', '....3...', '...3.3..', '..3...3.', '.3.....3'])
+ const scene = (frames: number[], dx = 0, dy = 0) => ({ frames, stepMs: 120, dx, dy })
+ return {
+ palette: [0, 0x00f8, 0xe007, 0x1f00],
+ frames: [a, b],
+ small: { w: 8, h: 8, loops: { idle: [0, 1, 0], done: [0], asking: [1] } },
+ working: scene([1, 0]),
+ listening: scene([0]),
+ sending: scene([1, 1, 0], -3, 5),
+ failed: scene([0]),
+ warnings: [],
+ }
+}
+
+function rewriteCrc(buf: Buffer): Buffer {
+ buf.writeUInt32LE(crc32(buf.subarray(22)), 18)
+ return buf
+}
+
+describe('pack', () => {
+ it('round-trip: decodePack(encodePack(p)) deep-equals p', () => {
+ const p = fixture()
+ const back = decodePack(encodePack(p, ID))
+ expect(back).toEqual({ ...p, id: '0102030405060708' })
+ })
+
+ it('header layout', () => {
+ const buf = encodePack(fixture(), ID)
+ expect(buf.subarray(0, 4).toString('latin1')).toBe('HPET')
+ expect(buf[4]).toBe(PACK_VERSION)
+ expect([...buf.subarray(6, 14)]).toEqual([...ID])
+ expect(buf.readUInt32LE(14)).toBe(buf.length)
+ expect(buf.readUInt32LE(18)).toBe(crc32(buf.subarray(22)))
+ })
+
+ it('bad CRC / bad magic / version 2 → throws', () => {
+ const good = encodePack(fixture(), ID)
+ const crc = Buffer.from(good)
+ crc[crc.length - 1] ^= 0xff
+ expect(() => decodePack(crc)).toThrow(/CRC/)
+ const magic = Buffer.from(good)
+ magic[0] = 0x58
+ expect(() => decodePack(magic)).toThrow(/magic/)
+ const v2 = Buffer.from(good)
+ v2[4] = 2
+ expect(() => decodePack(rewriteCrc(v2))).toThrow(/version/)
+ expect(() => decodePack(good.subarray(0, good.length - 3))).toThrow(/length/)
+ expect(() => decodePack(good.subarray(0, 10))).toThrow()
+ })
+
+ it('over 1 MB → TOO_BIG with the MB message', () => {
+ const p = fixture()
+ // Random cells defeat the run encoding: 192 x 208 x 30 frames is far more than 1 MB.
+ const noisy = (): IndexedFrame => {
+ const cells = new Uint8Array(192 * 208)
+ for (let i = 0; i < cells.length; i++) cells[i] = i % 2 ? 1 : 0
+ cells[0] = 1
+ return { cols: 192, rows: 208, cell: 1, cells: cells.map((v, i) => (v ? 1 + ((i * 7) % 3) : 0)) }
+ }
+ p.frames = Array.from({ length: 24 }, (_, n) => {
+ const f = noisy()
+ f.cells[1] = 1 + (n % 200)
+ return f
+ })
+ expect(PACK_MAX_BYTES).toBe(1_048_576)
+ try {
+ encodePack(p, ID)
+ throw new Error('did not throw')
+ } catch (e) {
+ expect(e).toBeInstanceOf(PetSheetError)
+ expect((e as PetSheetError).code).toBe('TOO_BIG')
+ expect((e as PetSheetError).message).toMatch(/^This pet is \d+\.\d MB; the limit is 1 MB$/)
+ }
+ })
+
+ it('vector: encodePack(fixture) equals test/vectors/pet_min.hpet', () => {
+ const buf = encodePack(fixture(), ID)
+ if (process.env.UPDATE_VECTORS === '1') {
+ mkdirSync(dirname(VECTOR), { recursive: true })
+ writeFileSync(VECTOR, buf)
+ }
+ expect(readFileSync(VECTOR).equals(buf)).toBe(true)
+ })
+})
diff --git a/cli/src/cable/pets/pack.ts b/cli/src/cable/pets/pack.ts
new file mode 100644
index 000000000..bd166f368
--- /dev/null
+++ b/cli/src/cable/pets/pack.ts
@@ -0,0 +1,201 @@
+import { crc32 } from 'node:zlib'
+import type { ConvertedPet, IndexedFrame, PetScene } from './convert.js'
+import { PetSheetError } from './sheet.js'
+
+// The HPET pack: a converted pet in the firmware's own cell-sprite format, little-endian throughout.
+//
+// "HPET" · version u8 · flags u8 · id u8[8] · length u32 (whole pack) · crc32 u32 (of every byte after this field)
+// palette: count u8 (entries incl. index 0) · count x u16
+// small: w u16 · h u16 · loops idle/done/asking: each n u8 · n x u16 frame index
+// scenes: working, listening, sending, failed: each n u8 · step_ms u16 · dx i16 · dy i16 · n x u16 frame index
+// frames: count u16 · per frame: cols u8 · rows u8 · cell u8 · row_at u16[rows] · packed rows
+export const PACK_VERSION = 1
+export const PACK_MAX_BYTES = 1_048_576
+
+const MAGIC = 'HPET'
+const HEADER_BYTES = 22 // magic, version, flags, id, length, crc
+const CRC_AT = 18
+const SCENES = ['working', 'listening', 'sending', 'failed'] as const
+const LOOPS = ['idle', 'done', 'asking'] as const
+
+class Writer {
+ private parts: Buffer[] = []
+ u8(v: number) {
+ this.parts.push(Buffer.from([v]))
+ }
+ u16(v: number) {
+ const b = Buffer.alloc(2)
+ b.writeUInt16LE(v)
+ this.parts.push(b)
+ }
+ i16(v: number) {
+ const b = Buffer.alloc(2)
+ b.writeInt16LE(v)
+ this.parts.push(b)
+ }
+ bytes(b: Uint8Array | number[]) {
+ this.parts.push(Buffer.from(b))
+ }
+ done(): Buffer {
+ return Buffer.concat(this.parts)
+ }
+}
+
+// Per row, pairs of (transparent cells to skip, opaque cells that follow) each followed by those cells' indices,
+// until `cols` are covered — scripts/gen_pets.py pack_rows, byte for byte (a row that ends transparent ends with a
+// pair whose run is 0). `at[r]` is where row r starts in the packed bytes.
+function packRows(f: IndexedFrame): { packed: number[]; at: number[] } {
+ const packed: number[] = []
+ const at: number[] = []
+ for (let r = 0; r < f.rows; r++) {
+ at.push(packed.length)
+ let x = 0
+ while (x < f.cols) {
+ let skip = 0
+ while (x < f.cols && !f.cells[r * f.cols + x]) {
+ skip++
+ x++
+ }
+ const run: number[] = []
+ while (x < f.cols && f.cells[r * f.cols + x]) {
+ run.push(f.cells[r * f.cols + x])
+ x++
+ }
+ packed.push(skip, run.length, ...run)
+ }
+ }
+ return { packed, at }
+}
+
+export function encodePack(pet: ConvertedPet, id: Uint8Array): Buffer {
+ if (id.length !== 8) throw new Error('A pet id is 8 bytes')
+ const body = new Writer()
+ if (pet.palette.length > 255) throw new Error('A palette has at most 255 entries')
+ body.u8(pet.palette.length)
+ for (const c of pet.palette) body.u16(c)
+ body.u16(pet.small.w)
+ body.u16(pet.small.h)
+ for (const name of LOOPS) {
+ const loop = pet.small.loops[name]
+ body.u8(loop.length)
+ for (const n of loop) body.u16(n)
+ }
+ for (const name of SCENES) {
+ const s = pet[name]
+ body.u8(s.frames.length)
+ body.u16(s.stepMs)
+ body.i16(s.dx)
+ body.i16(s.dy)
+ for (const n of s.frames) body.u16(n)
+ }
+ body.u16(pet.frames.length)
+ for (const f of pet.frames) {
+ const { packed, at } = packRows(f)
+ if (packed.length > 0xffff) throw new Error('A frame is too large to pack')
+ body.u8(f.cols)
+ body.u8(f.rows)
+ body.u8(f.cell)
+ for (const o of at) body.u16(o)
+ body.bytes(packed)
+ }
+ const payload = body.done()
+ const total = HEADER_BYTES + payload.length
+ if (total > PACK_MAX_BYTES) {
+ throw new PetSheetError('TOO_BIG', `This pet is ${(total / 1_048_576).toFixed(1)} MB; the limit is 1 MB`)
+ }
+ const head = Buffer.alloc(HEADER_BYTES)
+ head.write(MAGIC, 0, 'latin1')
+ head[4] = PACK_VERSION
+ head[5] = 0 // flags
+ head.set(id, 6)
+ head.writeUInt32LE(total, 14)
+ head.writeUInt32LE(crc32(payload), CRC_AT)
+ return Buffer.concat([head, payload])
+}
+
+class Reader {
+ at: number
+ constructor(
+ private buf: Buffer,
+ start: number,
+ ) {
+ this.at = start
+ }
+ private need(n: number) {
+ if (this.at + n > this.buf.length) throw new Error('The pet pack is truncated')
+ }
+ u8(): number {
+ this.need(1)
+ return this.buf[this.at++]
+ }
+ u16(): number {
+ this.need(2)
+ const v = this.buf.readUInt16LE(this.at)
+ this.at += 2
+ return v
+ }
+ i16(): number {
+ this.need(2)
+ const v = this.buf.readInt16LE(this.at)
+ this.at += 2
+ return v
+ }
+}
+
+export function decodePack(buf: Buffer): ConvertedPet & { id: string } {
+ if (buf.length < HEADER_BYTES) throw new Error('The pet pack is truncated')
+ if (buf.toString('latin1', 0, 4) !== MAGIC) throw new Error('Not a pet pack: bad magic')
+ if (buf[4] !== PACK_VERSION) throw new Error(`Unsupported pet pack version ${buf[4]}`)
+ if (buf.readUInt32LE(14) !== buf.length) throw new Error('The pet pack has the wrong length')
+ if (buf.readUInt32LE(CRC_AT) !== crc32(buf.subarray(HEADER_BYTES))) throw new Error('The pet pack failed its CRC check')
+ const id = buf.subarray(6, 14).toString('hex')
+ const r = new Reader(buf, HEADER_BYTES)
+
+ const palette: number[] = []
+ for (let n = r.u8(); n > 0; n--) palette.push(r.u16())
+ const w = r.u16()
+ const h = r.u16()
+ const loops = {} as Record<(typeof LOOPS)[number], number[]>
+ for (const name of LOOPS) {
+ const loop: number[] = []
+ for (let n = r.u8(); n > 0; n--) loop.push(r.u16())
+ loops[name] = loop
+ }
+ const scenes = {} as Record<(typeof SCENES)[number], PetScene>
+ for (const name of SCENES) {
+ const n = r.u8()
+ const stepMs = r.u16()
+ const dx = r.i16()
+ const dy = r.i16()
+ const frames: number[] = []
+ for (let i = 0; i < n; i++) frames.push(r.u16())
+ scenes[name] = { frames, stepMs, dx, dy }
+ }
+ const frames: IndexedFrame[] = []
+ for (let count = r.u16(); count > 0; count--) {
+ const cols = r.u8()
+ const rows = r.u8()
+ const cell = r.u8()
+ const at: number[] = []
+ for (let i = 0; i < rows; i++) at.push(r.u16())
+ const base = r.at
+ const cells = new Uint8Array(cols * rows)
+ for (let y = 0; y < rows; y++) {
+ if (r.at - base !== at[y]) throw new Error('The pet pack has a bad row offset')
+ let x = 0
+ while (x < cols) {
+ const skip = r.u8()
+ const run = r.u8()
+ if (x + skip + run > cols) throw new Error('The pet pack has a row longer than its frame')
+ x += skip
+ for (let i = 0; i < run; i++) cells[y * cols + x++] = r.u8()
+ }
+ }
+ frames.push({ cols, rows, cell, cells })
+ }
+ if (r.at !== buf.length) throw new Error('The pet pack has trailing bytes')
+ for (const s of [...Object.values(scenes), { frames: Object.values(loops).flat() }]) {
+ if (s.frames.some((n) => n >= frames.length)) throw new Error('The pet pack points at a missing frame')
+ }
+ return { id, palette, frames, small: { w, h, loops }, ...scenes, warnings: [] }
+}
diff --git a/cli/src/cable/pets/preview.spec.ts b/cli/src/cable/pets/preview.spec.ts
new file mode 100644
index 000000000..f31d11726
--- /dev/null
+++ b/cli/src/cable/pets/preview.spec.ts
@@ -0,0 +1,68 @@
+import { PNG } from 'pngjs'
+import { describe, expect, it } from 'vitest'
+import { PET_ROWS, parsePetSheet, type PetRow, type PetSheet, type RgbaFrame } from './sheet.js'
+import { convertPet } from './convert.js'
+import { STRIP_FRAME_MAX_H, previewFrames, sheetStrips } from './preview.js'
+
+// A cell that is solid (r, g, b) in its left half and clear in its right half.
+function cell(w: number, h: number, rgb: [number, number, number]): RgbaFrame {
+ const data = new Uint8Array(w * h * 4)
+ for (let y = 0; y < h; y++) for (let x = 0; x < w / 2; x++) data.set([...rgb, 255], (y * w + x) * 4)
+ return { width: w, height: h, data }
+}
+
+function sheet(cellW: number, cellH: number, counts: Partial<Record<PetRow, number>>): PetSheet {
+ const rows = {} as Record<PetRow, RgbaFrame[]>
+ for (const name of PET_ROWS) rows[name] = Array.from({ length: counts[name] ?? 0 }, (_, i) => cell(cellW, cellH, [200, 10 * i, 50]))
+ return { cellW, cellH, rows }
+}
+
+const decode = (url: string) => PNG.sync.read(Buffer.from(url.slice(url.indexOf(',') + 1), 'base64'))
+
+describe('sheetStrips', () => {
+ it('one strip per non-empty row, in sheet order, frames side by side at most 64 px tall', () => {
+ for (const [w, h] of [[192, 208], [96, 104]]) {
+ const strips = sheetStrips(sheet(w, h, { review: 2, idle: 3, jumping: 1 }))
+ expect(strips.map((s) => [s.row, s.frames])).toEqual([['idle', 3], ['jumping', 1], ['review', 2]])
+ const png = decode(strips[0].strip)
+ expect(STRIP_FRAME_MAX_H).toBe(64)
+ expect([png.width, png.height]).toEqual([59 * 3, 64])
+ }
+ })
+
+ it('keeps the colours and the clear background', () => {
+ const png = decode(sheetStrips(sheet(192, 208, { idle: 1 }))[0].strip)
+ expect([...png.data.subarray(0, 4)]).toEqual([200, 0, 50, 255])
+ const right = (10 * png.width + png.width - 1) * 4
+ expect(png.data[right + 3]).toBe(0)
+ })
+
+ it('a cell shorter than 64 px is not scaled up', () => {
+ const strips = sheetStrips(sheet(16, 20, { running: 2 }))
+ expect([decode(strips[0].strip).width, decode(strips[0].strip).height]).toEqual([32, 20])
+ })
+})
+
+// pet_preview's reply goes from the devices process to the core and on to the app over the local socket, whose
+// messages are capped at 6 MiB + 4 KiB (localWsServer.ts MAX_WS_MESSAGE_BYTES). Its pictures are bounded by a sheet
+// of full-size cells drawn edge to edge in noise, every row full: more than any sheet that converts (a pack over 1 MB
+// is refused) and than any file under 8 MB holds. The scenes' and the small pet's frames are as many as they can be
+// with the default rows (three scenes of 8, the small pet's 8 idle and 8 waving, 8 asking).
+describe('pet_preview size', () => {
+ it('a full 9 x 8 sheet of noise fits the local socket limit', () => {
+ const png = new PNG({ width: 1536, height: 1872 })
+ let seed = 1
+ for (let i = 0; i < png.data.length; i += 4) {
+ seed = (seed * 1103515245 + 12345) & 0x7fffffff
+ png.data.set([seed & 0xff, (seed >> 8) & 0xff, (seed >> 16) & 0xff, 255], i)
+ }
+ const sheet = parsePetSheet(PNG.sync.write(png))
+ expect(PET_ROWS.every((row) => sheet.rows[row].length === 8)).toBe(true)
+ const strips = JSON.stringify(sheetStrips(sheet)).length
+ const frames = JSON.stringify(previewFrames(convertPet(sheet))).length
+ process.stderr.write(`pet_preview worst case: sheetRows ${strips} B, frames ${frames} B\n`)
+ expect(strips).toBeLessThan(1.25 * 1024 * 1024)
+ // The rest of the reply (id, name, rows, warnings, …) is a few hundred bytes.
+ expect(strips + frames).toBeLessThan(6 * 1024 * 1024)
+ }, 60_000)
+})
diff --git a/cli/src/cable/pets/preview.ts b/cli/src/cable/pets/preview.ts
new file mode 100644
index 000000000..f0b23e67a
--- /dev/null
+++ b/cli/src/cable/pets/preview.ts
@@ -0,0 +1,83 @@
+import { PNG } from 'pngjs'
+import { expand565, panelOrder, type ConvertedPet, type IndexedFrame } from './convert.js'
+import { PET_ROWS, type PetRow, type PetSheet, type RgbaFrame } from './sheet.js'
+
+const SMALL_STEP_MS = 120
+
+// An indexed frame as a PNG data URL: each cell is cell x cell pixels, the panel-order RGB565 palette swapped back
+// (the swap is its own inverse), index 0 clear.
+export function frameUrl(frame: IndexedFrame, palette: number[]): string {
+ const { cols, rows, cell } = frame
+ const png = new PNG({ width: cols * cell, height: rows * cell })
+ for (let y = 0; y < png.height; y++) {
+ for (let x = 0; x < png.width; x++) {
+ const index = frame.cells[Math.floor(y / cell) * cols + Math.floor(x / cell)]
+ if (!index) continue
+ const [r, g, b] = expand565(panelOrder(palette[index] ?? 0))
+ png.data.set([r, g, b, 255], (y * png.width + x) * 4)
+ }
+ }
+ return `data:image/png;base64,${PNG.sync.write(png).toString('base64')}`
+}
+
+// What the Devices tab animates: every scene's frames as data URLs, with the step each is shown for.
+export function previewFrames(pet: ConvertedPet) {
+ const url = (indices: number[]) => indices.map((i) => frameUrl(pet.frames[i], pet.palette))
+ return {
+ frames: {
+ small: url([...new Set(pet.small.loops.idle)]),
+ asking: url([...new Set(pet.small.loops.asking)]),
+ working: url(pet.working.frames),
+ listening: url(pet.listening.frames),
+ sending: url(pet.sending.frames),
+ },
+ stepMs: { small: SMALL_STEP_MS, asking: SMALL_STEP_MS, working: pet.working.stepMs, listening: pet.listening.stepMs, sending: pet.sending.stepMs },
+ }
+}
+
+// The row picker's pictures are small: a frame is at most this tall, so a whole 9 x 8 sheet stays a few hundred KB.
+export const STRIP_FRAME_MAX_H = 64
+
+// Every row with frames, in sheet order, as one PNG data URL of its frames side by side: the source art (not the
+// pack's palette, which depends on the rows chosen), box-filtered down to at most 64 px tall, clear where it is clear.
+export function sheetStrips(sheet: PetSheet): Array<{ row: PetRow; frames: number; strip: string }> {
+ const h = Math.min(STRIP_FRAME_MAX_H, sheet.cellH)
+ const w = Math.max(1, Math.round((sheet.cellW * h) / sheet.cellH))
+ return PET_ROWS.filter((row) => sheet.rows[row].length > 0).map((row) => {
+ const frames = sheet.rows[row]
+ const png = new PNG({ width: w * frames.length, height: h })
+ frames.forEach((f, n) => drawScaled(f, png, n * w, w, h))
+ return { row, frames: frames.length, strip: `data:image/png;base64,${PNG.sync.write(png).toString('base64')}` }
+ })
+}
+
+// Each output pixel averages the source pixels it covers, colours weighted by their alpha so clear pixels add no
+// black fringe.
+function drawScaled(f: RgbaFrame, out: PNG, x0: number, w: number, h: number): void {
+ for (let y = 0; y < h; y++) {
+ const sy0 = Math.floor((y * f.height) / h)
+ const sy1 = Math.max(sy0 + 1, Math.floor(((y + 1) * f.height) / h))
+ for (let x = 0; x < w; x++) {
+ const sx0 = Math.floor((x * f.width) / w)
+ const sx1 = Math.max(sx0 + 1, Math.floor(((x + 1) * f.width) / w))
+ let n = 0
+ let a = 0
+ let r = 0
+ let g = 0
+ let b = 0
+ for (let sy = sy0; sy < sy1; sy++) {
+ for (let sx = sx0; sx < sx1; sx++) {
+ const i = (sy * f.width + sx) * 4
+ const alpha = f.data[i + 3]
+ n++
+ a += alpha
+ r += f.data[i] * alpha
+ g += f.data[i + 1] * alpha
+ b += f.data[i + 2] * alpha
+ }
+ }
+ if (a === 0) continue
+ out.data.set([Math.round(r / a), Math.round(g / a), Math.round(b / a), Math.round(a / n)], (y * out.width + x0 + x) * 4)
+ }
+ }
+}
diff --git a/cli/src/cable/pets/sheet.spec.ts b/cli/src/cable/pets/sheet.spec.ts
new file mode 100644
index 000000000..de7e5d0e7
--- /dev/null
+++ b/cli/src/cable/pets/sheet.spec.ts
@@ -0,0 +1,207 @@
+import { execFileSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { mkdtemp, rm, writeFile, truncate } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { PNG } from 'pngjs'
+import { afterAll, describe, expect, it, vi } from 'vitest'
+import { DEFAULT_PET_ROWS, PetSheetError, parsePetSheet, readPetSheet, resolvePetRows, type PetRow } from './sheet.js'
+
+const ROW_INDEX: Record<PetRow, number> = {
+ idle: 0,
+ runningRight: 1,
+ runningLeft: 2,
+ waving: 3,
+ jumping: 4,
+ failed: 5,
+ waiting: 6,
+ running: 7,
+ review: 8,
+}
+
+// A transparent sheet with `cells[row]` cells drawn (a solid 10 x 10 block) at the start of each row.
+function makeSheet(width: number, height: number, cells: Partial<Record<PetRow, number>>): PNG {
+ const png = new PNG({ width, height })
+ const cw = width / 8
+ const ch = height / 9
+ for (const [row, n] of Object.entries(cells) as [PetRow, number][]) {
+ for (let c = 0; c < n; c++) {
+ for (let y = 0; y < 10; y++) {
+ for (let x = 0; x < 10; x++) {
+ const i = ((ROW_INDEX[row] * ch + 20 + y) * width + c * cw + 20 + x) * 4
+ png.data.set([200, 40 + c * 10, 90, 255], i)
+ }
+ }
+ }
+ }
+ return png
+}
+
+const dirs: string[] = []
+afterAll(async () => {
+ await Promise.all(dirs.map((d) => rm(d, { recursive: true, force: true })))
+})
+
+function expectError(fn: () => unknown, code: string, message?: string) {
+ try {
+ fn()
+ } catch (e) {
+ expect(e).toBeInstanceOf(PetSheetError)
+ expect((e as PetSheetError).code).toBe(code)
+ if (message) expect((e as PetSheetError).message).toBe(message)
+ return
+ }
+ throw new Error('did not throw')
+}
+
+describe('parsePetSheet', () => {
+ it('accepts 1536x1872 and 768x936', () => {
+ const full = parsePetSheet(PNG.sync.write(makeSheet(1536, 1872, { idle: 2, running: 2 })))
+ expect([full.cellW, full.cellH]).toEqual([192, 208])
+ const half = parsePetSheet(PNG.sync.write(makeSheet(768, 936, { idle: 2, running: 2 })))
+ expect([half.cellW, half.cellH]).toEqual([96, 104])
+ expect(half.rows.idle[0].width).toBe(96)
+ expect(half.rows.idle[0].data.length).toBe(96 * 104 * 4)
+ })
+
+ it('rejects 1000x1000', () => {
+ expectError(
+ () => parsePetSheet(PNG.sync.write(makeSheet(1000, 1000, {}))),
+ 'BAD_SIZE',
+ 'The sheet must be 1536 × 1872 (8 × 9 cells of 192 × 208)',
+ )
+ })
+
+ it('row ends at the first transparent cell', () => {
+ const png = makeSheet(768, 936, { idle: 3, running: 1 })
+ // A drawn cell after the gap is not part of the row.
+ const i = ((3 * 104 + 20) * 768 + 5 * 96 + 20) * 4
+ png.data.set([1, 2, 3, 255], i)
+ const sheet = parsePetSheet(PNG.sync.write(png))
+ expect(sheet.rows.idle.length).toBe(3)
+ expect(sheet.rows.waving.length).toBe(0)
+ })
+
+ it('a sheet with nothing drawn on it', () => {
+ expectError(() => parsePetSheet(PNG.sync.write(makeSheet(768, 936, {}))), 'NO_FRAMES', 'The sheet is empty')
+ })
+
+ it('empty idle or running rows are left for the row choice to judge', () => {
+ expect(parsePetSheet(PNG.sync.write(makeSheet(768, 936, { idle: 2 }))).rows.running).toEqual([])
+ expect(parsePetSheet(PNG.sync.write(makeSheet(768, 936, { jumping: 1 }))).rows.idle).toEqual([])
+ })
+
+ it('not a PNG', () => {
+ expectError(() => parsePetSheet(Buffer.from('definitely not a png file')), 'NOT_PNG')
+ const broken = PNG.sync.write(makeSheet(768, 936, { idle: 1, running: 1 })).subarray(0, 60)
+ expectError(() => parsePetSheet(broken), 'NOT_PNG')
+ })
+})
+
+describe('resolvePetRows', () => {
+ const parse = (cells: Partial<Record<PetRow, number>>) => parsePetSheet(PNG.sync.write(makeSheet(768, 936, cells)))
+
+ it('without a choice: today’s table, with listening, sending and asking falling back to idle', () => {
+ expect(resolvePetRows(parse({ idle: 2, running: 2 }))).toEqual({
+ rest: 'idle', working: 'running', listening: 'idle', sending: 'idle', asking: 'idle',
+ })
+ expect(resolvePetRows(parse({ idle: 2, running: 2, review: 1, waving: 1, waiting: 1 }))).toEqual(DEFAULT_PET_ROWS)
+ })
+
+ it('a choice overrides the default per key; an empty chosen listening, sending or asking row falls back to rest', () => {
+ const sheet = parse({ jumping: 2, runningLeft: 3, failed: 1 })
+ expect(resolvePetRows(sheet, { rest: 'jumping', working: 'runningLeft', sending: 'failed', asking: 'waiting' })).toEqual({
+ rest: 'jumping', working: 'runningLeft', listening: 'jumping', sending: 'failed', asking: 'jumping',
+ })
+ })
+
+ it('the chosen rest and working rows must have frames', () => {
+ expectError(() => resolvePetRows(parse({ running: 2 })), 'NO_REST', 'The row chosen for Rest is empty')
+ expectError(() => resolvePetRows(parse({ idle: 2 })), 'NO_WORKING', 'The row chosen for Working is empty')
+ expectError(() => resolvePetRows(parse({ idle: 2, running: 2 }), { working: 'jumping' }), 'NO_WORKING', 'The row chosen for Working is empty')
+ expectError(() => resolvePetRows(parse({ idle: 2, running: 2 }), { rest: 'review' }), 'NO_REST', 'The row chosen for Rest is empty')
+ })
+})
+
+describe('readPetSheet', () => {
+ it('reads a sheet from a path', async () => {
+ const dir = await mkdtemp(join(tmpdir(), 'pet-sheet-'))
+ dirs.push(dir)
+ const file = join(dir, 'sheet.png')
+ await writeFile(file, PNG.sync.write(makeSheet(768, 936, { idle: 1, running: 1 })))
+ const sheet = await readPetSheet(file)
+ expect(sheet.rows.running.length).toBe(1)
+ })
+
+ it('file over 8 MB', async () => {
+ const dir = await mkdtemp(join(tmpdir(), 'pet-sheet-'))
+ dirs.push(dir)
+ const file = join(dir, 'big.png')
+ await writeFile(file, '')
+ await truncate(file, 8 * 1024 * 1024 + 1) // sparse: never read, only stat
+ await expect(readPetSheet(file)).rejects.toMatchObject({ code: 'TOO_BIG' })
+ })
+
+ it('missing file', async () => {
+ await expect(readPetSheet('/nonexistent/pet.png')).rejects.toMatchObject({ code: 'NOT_PNG' })
+ })
+})
+
+// A PNG whose IHDR declares what it likes and whose body is nothing: pngjs would allocate for the declaration.
+function fakeHeader(width: number, height: number, depth = 8, colour = 6, interlace = 0): Buffer {
+ const head = Buffer.alloc(33)
+ Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]).copy(head)
+ head.writeUInt32BE(13, 8)
+ head.write('IHDR', 12, 'latin1')
+ head.writeUInt32BE(width, 16)
+ head.writeUInt32BE(height, 20)
+ head[24] = depth
+ head[25] = colour
+ head[28] = interlace
+ return head
+}
+
+describe('PNG header check', () => {
+ it('rejects a 12000 x 12000 declaration without decoding', () => {
+ const spy = vi.spyOn(PNG.sync, 'read')
+ const start = performance.now()
+ expectError(() => parsePetSheet(fakeHeader(12000, 12000)), 'BAD_SIZE', 'The sheet must be 1536 × 1872 (8 × 9 cells of 192 × 208)')
+ expect(performance.now() - start).toBeLessThan(100)
+ expect(spy).not.toHaveBeenCalled()
+ spy.mockRestore()
+ })
+
+ it('rejects 16-bit and interlaced sheets without decoding', () => {
+ const spy = vi.spyOn(PNG.sync, 'read')
+ expectError(() => parsePetSheet(fakeHeader(768, 936, 16)), 'NOT_PNG')
+ expectError(() => parsePetSheet(fakeHeader(768, 936, 8, 6, 1)), 'BAD_SIZE', 'Save the sheet without interlacing')
+ expect(spy).not.toHaveBeenCalled()
+ spy.mockRestore()
+ })
+})
+
+describe('readPetSource special files', () => {
+ const tmp = async () => {
+ const dir = await mkdtemp(join(tmpdir(), 'pet-special-'))
+ dirs.push(dir)
+ return dir
+ }
+
+ it('refuses a directory', async () => {
+ await expect(readPetSheet(await tmp())).rejects.toMatchObject({ code: 'NOT_PNG', message: 'Choose a PNG file' })
+ })
+
+ it('refuses a FIFO promptly', async () => {
+ const fifo = join(await tmp(), 'pipe.png')
+ execFileSync('mkfifo', [fifo])
+ const start = performance.now()
+ await expect(readPetSheet(fifo)).rejects.toMatchObject({ code: 'NOT_PNG', message: 'Choose a PNG file' })
+ expect(performance.now() - start).toBeLessThan(500)
+ })
+
+ it.skipIf(!existsSync('/dev/zero'))('refuses /dev/zero promptly', async () => {
+ const start = performance.now()
+ await expect(readPetSheet('/dev/zero')).rejects.toMatchObject({ code: 'NOT_PNG', message: 'Choose a PNG file' })
+ expect(performance.now() - start).toBeLessThan(500)
+ })
+})
diff --git a/cli/src/cable/pets/sheet.ts b/cli/src/cable/pets/sheet.ts
new file mode 100644
index 000000000..295bd7b7e
--- /dev/null
+++ b/cli/src/cable/pets/sheet.ts
@@ -0,0 +1,199 @@
+import { open, stat } from 'node:fs/promises'
+import { PNG } from 'pngjs'
+
+// A petdex-layout sprite sheet: 8 columns x 9 rows of cells. The full sheet is 1536 x 1872 (cells of 192 x 208), the
+// half size 768 x 936 (cells of 96 x 104). Rows, top to bottom, are the names below.
+export type PetRow =
+ | 'idle'
+ | 'runningRight'
+ | 'runningLeft'
+ | 'waving'
+ | 'jumping'
+ | 'failed'
+ | 'waiting'
+ | 'running'
+ | 'review'
+
+export const PET_ROWS: readonly PetRow[] = [
+ 'idle',
+ 'runningRight',
+ 'runningLeft',
+ 'waving',
+ 'jumping',
+ 'failed',
+ 'waiting',
+ 'running',
+ 'review',
+]
+
+export interface RgbaFrame {
+ width: number
+ height: number
+ data: Uint8Array // RGBA, 4 bytes per pixel
+}
+
+export interface PetSheet {
+ cellW: number
+ cellH: number
+ rows: Record<PetRow, RgbaFrame[]>
+}
+
+// Which sheet row plays each of the dial's states. The user picks them; without a choice it is the petdex reading.
+export type PetState = 'rest' | 'working' | 'listening' | 'sending' | 'asking'
+export type PetRows = Record<PetState, PetRow>
+export const PET_STATES: readonly PetState[] = ['rest', 'working', 'listening', 'sending', 'asking']
+export const DEFAULT_PET_ROWS: Readonly<PetRows> = {
+ rest: 'idle',
+ working: 'running',
+ listening: 'review',
+ sending: 'waving',
+ asking: 'waiting',
+}
+
+export type PetSheetErrorCode = 'NOT_PNG' | 'BAD_SIZE' | 'NO_FRAMES' | 'NO_REST' | 'NO_WORKING' | 'TOO_BIG' | 'TOO_MANY'
+
+// The message is shown to the user as is, so every throw site words it for them.
+export class PetSheetError extends Error {
+ readonly code: PetSheetErrorCode
+ constructor(code: PetSheetErrorCode, message: string) {
+ super(message)
+ this.name = 'PetSheetError'
+ this.code = code
+ }
+}
+
+export const SHEET_COLS = 8
+export const SHEET_MAX_BYTES = 8 * 1024 * 1024
+// A cell with alpha >= this is opaque; the dial's cell sprites have no partial alpha.
+export const ALPHA_OPAQUE = 128
+
+const PNG_MAGIC = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]
+
+// A sheet is read from a path, not bytes: the app and the daemon share the machine and 8 MB would not fit the local
+// socket's message limit. Only a regular file is opened (a FIFO would block the open, /dev/zero would never end), and
+// at most the limit plus one byte is read, whatever the file grows to.
+export async function readPetSource(path: string): Promise<Buffer> {
+ const notFile = () => new PetSheetError('NOT_PNG', 'Choose a PNG file')
+ try {
+ if (!(await stat(path)).isFile()) throw notFile()
+ } catch (error) {
+ if (error instanceof PetSheetError) throw error
+ throw new PetSheetError('NOT_PNG', 'The file could not be read')
+ }
+ let fh
+ try {
+ fh = await open(path, 'r')
+ } catch {
+ throw new PetSheetError('NOT_PNG', 'The file could not be read')
+ }
+ try {
+ const info = await fh.stat()
+ if (!info.isFile()) throw notFile()
+ if (info.size > SHEET_MAX_BYTES) throw new PetSheetError('TOO_BIG', 'The file is over 8 MB')
+ const buf = Buffer.alloc(info.size + 1) // size <= the limit, so never more than limit + 1
+ let n = 0
+ while (n < buf.length) {
+ const { bytesRead } = await fh.read(buf, n, buf.length - n, n)
+ if (bytesRead === 0) break
+ n += bytesRead
+ }
+ if (n > SHEET_MAX_BYTES) throw new PetSheetError('TOO_BIG', 'The file is over 8 MB')
+ return buf.subarray(0, n)
+ } catch (error) {
+ if (error instanceof PetSheetError) throw error
+ throw new PetSheetError('NOT_PNG', 'The file could not be read')
+ } finally {
+ await fh.close().catch(() => undefined)
+ }
+}
+
+export async function readPetSheet(path: string): Promise<PetSheet> {
+ return parsePetSheet(await readPetSource(path))
+}
+
+export function parsePetSheet(png: Buffer): PetSheet {
+ if (png.length < PNG_MAGIC.length || PNG_MAGIC.some((b, i) => png[i] !== b)) {
+ throw new PetSheetError('NOT_PNG', 'The file is not a PNG')
+ }
+ checkHeader(png)
+ let image: PNG
+ try {
+ image = PNG.sync.read(png)
+ } catch {
+ throw new PetSheetError('NOT_PNG', 'The file is not a PNG')
+ }
+ const { width, height } = image
+ if (!sizeOk(width, height)) throw badSize()
+ const cellW = width / SHEET_COLS
+ const cellH = height / PET_ROWS.length
+ const rows = {} as Record<PetRow, RgbaFrame[]>
+ PET_ROWS.forEach((name, r) => {
+ const frames: RgbaFrame[] = []
+ for (let c = 0; c < SHEET_COLS; c++) {
+ const frame = cut(image.data, width, c * cellW, r * cellH, cellW, cellH)
+ // A row ends at its first cell with nothing opaque in it. "Opaque" is the dial's own alpha test, so a cell of
+ // only faint pixels cannot become an empty frame later.
+ if (isBlank(frame)) break
+ frames.push({ width: cellW, height: cellH, data: frame })
+ }
+ rows[name] = frames
+ })
+ // Which rows must have frames depends on the row choice (resolvePetRows); a sheet with none is no pet at all.
+ if (PET_ROWS.every((name) => rows[name].length === 0)) throw new PetSheetError('NO_FRAMES', 'The sheet is empty')
+ return { cellW, cellH, rows }
+}
+
+// The rows the pack is made from: the choice over the defaults, without judging them. A listening, sending or asking
+// row with no frames falls back to the rest row (with the default rest, idle: the petdex reading).
+export function pickPetRows(sheet: PetSheet, choice: Partial<PetRows> = {}): PetRows {
+ const picked = { ...DEFAULT_PET_ROWS }
+ for (const state of PET_STATES) {
+ const row = choice[state]
+ if (row && PET_ROWS.includes(row)) picked[state] = row
+ }
+ for (const state of ['listening', 'sending', 'asking'] as const) {
+ if (sheet.rows[picked[state]].length === 0) picked[state] = picked.rest
+ }
+ return picked
+}
+
+// pickPetRows, refusing a choice the dial cannot play: rest and working are drawn all the time, so neither may be empty.
+export function resolvePetRows(sheet: PetSheet, choice?: Partial<PetRows>): PetRows {
+ const picked = pickPetRows(sheet, choice)
+ if (sheet.rows[picked.rest].length === 0) throw new PetSheetError('NO_REST', 'The row chosen for Rest is empty')
+ if (sheet.rows[picked.working].length === 0) throw new PetSheetError('NO_WORKING', 'The row chosen for Working is empty')
+ return picked
+}
+
+const badSize = () => new PetSheetError('BAD_SIZE', 'The sheet must be 1536 × 1872 (8 × 9 cells of 192 × 208)')
+const sizeOk = (w: number, h: number) => (w === 1536 && h === 1872) || (w === 768 && h === 936)
+
+// The IHDR is read here, before pngjs, which allocates what the header declares: a few bytes claiming 12000 x 12000
+// must not become half a gigabyte. Only what the sheet format can be (8-bit RGB, RGBA or palette) is decoded.
+function checkHeader(png: Buffer): void {
+ if (png.length < 33 || png.readUInt32BE(8) !== 13 || png.toString('latin1', 12, 16) !== 'IHDR') {
+ throw new PetSheetError('NOT_PNG', 'The file is not a PNG')
+ }
+ if (!sizeOk(png.readUInt32BE(16), png.readUInt32BE(20))) throw badSize()
+ const depth = png[24]
+ const colour = png[25]
+ const depthOk = colour === 3 ? [1, 2, 4, 8].includes(depth) : depth === 8
+ if (![2, 3, 6].includes(colour) || !depthOk) {
+ throw new PetSheetError('NOT_PNG', 'Save the sheet as an 8-bit RGB or RGBA PNG')
+ }
+ if (png[28] !== 0) throw new PetSheetError('BAD_SIZE', 'Save the sheet without interlacing')
+}
+
+function cut(src: Uint8Array, stride: number, x0: number, y0: number, w: number, h: number): Uint8Array {
+ const out = new Uint8Array(w * h * 4)
+ for (let y = 0; y < h; y++) {
+ const from = ((y0 + y) * stride + x0) * 4
+ out.set(src.subarray(from, from + w * 4), y * w * 4)
+ }
+ return out
+}
+
+function isBlank(rgba: Uint8Array): boolean {
+ for (let i = 3; i < rgba.length; i += 4) if (rgba[i] >= ALPHA_OPAQUE) return false
+ return true
+}
diff --git a/cli/src/cable/pets/store.spec.ts b/cli/src/cable/pets/store.spec.ts
new file mode 100644
index 000000000..f6cec42e3
--- /dev/null
+++ b/cli/src/cable/pets/store.spec.ts
@@ -0,0 +1,298 @@
+import { createHash } from 'node:crypto'
+import { mkdtemp, readdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { PNG } from 'pngjs'
+import { afterAll, beforeEach, describe, expect, it } from 'vitest'
+import { PACK_VERSION, decodePack } from './pack.js'
+import { PetSheetError, type PetRows } from './sheet.js'
+import { PetStore, PetStoreError } from './store.js'
+
+const roots: string[] = []
+afterAll(async () => {
+ await Promise.all(roots.map((d) => rm(d, { recursive: true, force: true })))
+})
+
+// A 768 x 936 sheet; `seed` changes its colours, so each seed is a different source file.
+function sheetPng(seed: number): Buffer {
+ const png = new PNG({ width: 768, height: 936 })
+ for (const row of [0, 7]) {
+ for (let c = 0; c < 2; c++) {
+ for (let y = 0; y < 30; y++) {
+ for (let x = 0; x < 30; x++) {
+ const i = ((row * 104 + 30 + y) * 768 + c * 96 + 30 + x) * 4
+ png.data.set([(seed * 37) & 255, 90 + c * 40, (x * 5 + y) & 255, 255], i)
+ }
+ }
+ }
+ }
+ return PNG.sync.write(png)
+}
+
+// What the defaults come to on a sheet with only idle and running drawn.
+const DEFAULT_ROWS_IDLE: PetRows = { rest: 'idle', working: 'running', listening: 'idle', sending: 'idle', asking: 'idle' }
+
+let work: string
+let dir: string
+let store: PetStore
+beforeEach(async () => {
+ work = await mkdtemp(join(tmpdir(), 'pet-store-'))
+ roots.push(work)
+ dir = join(work, 'pets')
+ store = new PetStore(dir)
+})
+
+async function source(seed: number): Promise<string> {
+ const path = join(work, `sheet-${seed}.png`)
+ await writeFile(path, sheetPng(seed))
+ return path
+}
+
+// A 768 x 936 sheet with `rows[row]` cells drawn in the given rows, each cell its own shape and colours.
+function richPng(rows: Record<number, number>): Buffer {
+ const png = new PNG({ width: 768, height: 936 })
+ for (const [row, n] of Object.entries(rows).map(([r, n]) => [Number(r), n])) {
+ for (let c = 0; c < n; c++) {
+ for (let y = 0; y < 40; y++) {
+ for (let x = 0; x < 30 + c * 3; x++) {
+ const i = ((row * 104 + 20 + y + c) * 768 + c * 96 + 20 + x) * 4
+ png.data.set([(row * 29 + c * 17) & 255, (x * 5 + row * 11) & 255, (y * 6 + c * 3) & 255, 255], i)
+ }
+ }
+ }
+ }
+ return PNG.sync.write(png)
+}
+
+const hpets = async () => (await readdir(dir)).filter((n) => n.endsWith('.hpet'))
+
+describe('PetStore', () => {
+ it('prepare converts, stores the pack and the source, and returns the id', async () => {
+ const { id, bytes, pet } = await store.prepare(await source(1))
+ expect(id).toMatch(/^[0-9a-f]{16}$/)
+ expect(pet.frames.length).toBeGreaterThan(0)
+ const pack = await store.pack(id)
+ expect(pack.length).toBe(bytes)
+ expect(decodePack(pack).id).toBe(id)
+ expect((await readdir(dir)).sort()).toEqual([`${id}.hpet`, `${id}.json`, `${id}.png`])
+ })
+
+ it('prepare passes sheet errors through', async () => {
+ const bad = join(work, 'bad.png')
+ await writeFile(bad, 'nope')
+ await expect(store.prepare(bad)).rejects.toMatchObject({ code: 'NOT_PNG' })
+ })
+
+ it('store: same source twice → one pack', async () => {
+ const path = await source(2)
+ const a = await store.prepare(path)
+ const b = await store.prepare(path)
+ expect(b.id).toBe(a.id)
+ await store.apply('claude', a.id)
+ const mapping = await store.apply('codex', b.id)
+ expect(mapping).toEqual({ all: null, engines: { claude: a.id, codex: a.id } })
+ expect(store.mappedIds()).toEqual([a.id])
+ expect(await hpets()).toEqual([`${a.id}.hpet`])
+ })
+
+ it('store: fifth distinct pack is refused', async () => {
+ const ids: string[] = []
+ for (const [n, target] of ['all', 'claude', 'codex', 'muse'].entries()) {
+ ids.push((await store.prepare(await source(11 + n))).id)
+ await store.apply(target, ids[n])
+ }
+ ids.push((await store.prepare(await source(15))).id)
+ const err = await store.apply('gemini', ids[4]).catch((e) => e)
+ expect(err).toBeInstanceOf(PetSheetError)
+ expect(err).toMatchObject({ code: 'TOO_MANY', message: 'Up to 4 pets at once: reset one first' })
+ expect(store.mappedIds().length).toBe(4)
+ // Replacing one of the four is fine.
+ await store.apply('muse', ids[4])
+ expect(store.mappedIds()).toContain(ids[4])
+ })
+
+ it('store: reset removes the mapping and deletes the unreferenced pack', async () => {
+ const a = await store.prepare(await source(20))
+ await store.apply('all', a.id)
+ const mapping = await store.reset('all')
+ expect(mapping).toEqual({ all: null, engines: {} })
+ expect(await readdir(dir)).toEqual(['pets.json'])
+ })
+
+ it('a replaced pack is deleted, a still-mapped one kept', async () => {
+ const a = await store.prepare(await source(30))
+ const b = await store.prepare(await source(31))
+ await store.apply('all', a.id)
+ await store.apply('claude', a.id)
+ await store.apply('all', b.id)
+ expect(store.mappedIds().sort()).toEqual([a.id, b.id].sort())
+ await store.reset('claude')
+ expect(await hpets()).toEqual([`${b.id}.hpet`])
+ })
+
+ it('a prepared pack survives another apply until it is applied', async () => {
+ const a = await store.prepare(await source(40))
+ const b = await store.prepare(await source(41))
+ await store.apply('all', a.id)
+ await store.reset('all')
+ expect(await hpets()).toContain(`${b.id}.hpet`)
+ await store.apply('claude', b.id)
+ expect(store.mappedIds()).toEqual([b.id])
+ })
+
+ it('store: mapping survives a new PetStore on the same dir', async () => {
+ const a = await store.prepare(await source(50))
+ await store.apply('all', a.id)
+ await store.apply('codex', a.id)
+ const again = new PetStore(dir)
+ expect(again.mapping()).toEqual({ all: a.id, engines: { codex: a.id } })
+ expect((await again.pack(a.id)).length).toBeGreaterThan(0)
+ })
+
+ it('apply refuses an unknown id and bad targets', async () => {
+ await expect(store.apply('all', 'aaaaaaaaaaaaaaaa')).rejects.toMatchObject({ code: 'UNKNOWN_PET' })
+ await expect(store.apply('all', '../etc/passwd')).rejects.toMatchObject({ code: 'UNKNOWN_PET' })
+ const a = await store.prepare(await source(60))
+ await expect(store.apply('__proto__', a.id)).rejects.toMatchObject({ code: 'BAD_TARGET' })
+ await expect(store.apply('', a.id)).rejects.toMatchObject({ code: 'BAD_TARGET' })
+ })
+
+ it('keeps the source file\'s base name (max 40 chars) in a sidecar, atomically, and sweeps it with the pack', async () => {
+ const long = join(work, `${'x'.repeat(60)}.png`)
+ await writeFile(long, sheetPng(70))
+ const a = await store.prepare(long)
+ expect(await store.name(a.id)).toBe('x'.repeat(40))
+ expect(JSON.parse(await readFile(join(dir, `${a.id}.json`), 'utf8'))).toEqual({ name: 'x'.repeat(40), rows: DEFAULT_ROWS_IDLE })
+ const b = await store.prepare(await source(71))
+ expect(await store.name(b.id)).toBe('sheet-71')
+ expect((await readdir(dir)).filter((n) => n.endsWith('.tmp'))).toEqual([])
+ expect(await store.name('ffffffffffffffff')).toBe('')
+ await store.apply('all', b.id)
+ await store.reset('all')
+ expect((await readdir(dir)).filter((f) => f.startsWith(b.id))).toEqual([]) // pack, source and name go together
+ })
+
+ it('engine names are capped at 15 chars (the dial keeps 15) and at most 8 engines get their own pet', async () => {
+ const a = await store.prepare(await source(80))
+ await expect(store.apply('x'.repeat(16), a.id)).rejects.toMatchObject({ code: 'BAD_TARGET' })
+ await store.apply('x'.repeat(15), a.id)
+ for (let n = 1; n < 8; n++) await store.apply(`engine${n}`, a.id)
+ const err = await store.apply('ninth', a.id).catch((e) => e)
+ expect(err).toBeInstanceOf(PetStoreError)
+ expect(err.message).toBe('Up to 8 engines can have their own pet')
+ await store.apply('engine3', a.id) // replacing one of the eight is fine
+ await store.reset('engine3')
+ await store.apply('ninth', a.id)
+ })
+
+ it('mapping() returns a copy', async () => {
+ const m = store.mapping()
+ m.all = 'x'
+ expect(store.mapping().all).toBeNull()
+ })
+
+ it('re-prepares a pack whose version byte is not the current one when its source is kept', async () => {
+ const a = await store.prepare(await source(90))
+ const file = join(dir, `${a.id}.hpet`)
+ const old = await readFile(file)
+ old[4] = 0
+ await writeFile(file, old)
+ const pack = await store.pack(a.id)
+ expect(pack[4]).toBe(PACK_VERSION)
+ expect(decodePack(pack).id).toBe(a.id)
+ expect((await readFile(file))[4]).toBe(PACK_VERSION)
+ })
+
+ it('shares the directory with another store: a mapping written there is not overwritten or swept here', async () => {
+ const other = new PetStore(dir)
+ const x = await store.prepare(await source(91))
+ await store.apply('claude', x.id)
+ const y = await other.prepare(await source(92))
+ await other.apply('codex', y.id)
+ expect(other.mapping().engines).toEqual({ claude: x.id, codex: y.id })
+ await store.reset('claude')
+ expect(store.mapping().engines).toEqual({ codex: y.id })
+ expect(await hpets()).toEqual([`${y.id}.hpet`])
+ expect(JSON.parse(await readFile(join(dir, 'pets.json'), 'utf8')).engines).toEqual({ codex: y.id })
+ })
+
+ it('previews that were never applied do not pile up: mapped plus the newest four stay', async () => {
+ const mapped = await store.prepare(await source(100))
+ await store.apply('all', mapped.id)
+ const previews: string[] = []
+ for (let n = 0; n < 7; n++) previews.push((await store.prepare(await source(101 + n))).id)
+ expect((await hpets()).sort()).toEqual([mapped.id, ...previews.slice(-4)].map((id) => `${id}.hpet`).sort())
+ })
+
+ // Recorded before the row choice existed: without one, a sheet is the very pack (and id) it always was.
+ it('without a row choice, the pack and its id are what they were before rows could be chosen', async () => {
+ const golden = [
+ ['rich', { 0: 3, 3: 2, 5: 1, 6: 2, 7: 4, 8: 2 }, '4ccbe14a80622e7b', 'cda81b4c9f49e6838f8f5989d1e02ec9a0122871f2d1b15acba8c4627a6f9c00'],
+ ['plain', { 0: 2, 7: 2 }, '2a6b49cb7b84e278', '9379ef4e9797277e26c15accb15510a70c72b5ff177419aecc891ec8104ffbed'],
+ ['wavy', { 0: 4, 3: 3, 7: 1 }, '04b4f64fa278e7c7', '87af31113da33abfb05a0820920120950c1be4e761bec804fcda216e3a0a0076'],
+ ] as const
+ for (const [label, rows, id, sha] of golden) {
+ const path = join(work, `${label}.png`)
+ await writeFile(path, richPng(rows))
+ expect((await store.prepare(path)).id).toBe(id)
+ expect(createHash('sha256').update(await store.pack(id)).digest('hex')).toBe(sha)
+ // Naming the defaults is no choice at all, and neither is naming what they fall back to.
+ const named = await store.prepare(path, undefined, { rest: 'idle', working: 'running', listening: 'review', sending: 'waving', asking: 'waiting' })
+ expect(named.id).toBe(id)
+ }
+ const plain = join(work, 'plain.png')
+ expect((await store.prepare(plain, undefined, { listening: 'idle' })).id).toBe('2a6b49cb7b84e278')
+ })
+
+ it('a different row choice is a different pack, and its choice is kept beside its name', async () => {
+ const path = join(work, 'rich.png')
+ await writeFile(path, richPng({ 0: 3, 3: 2, 5: 1, 6: 2, 7: 4, 8: 2 }))
+ const plain = await store.prepare(path)
+ expect(plain.rows).toEqual({ rest: 'idle', working: 'running', listening: 'review', sending: 'waving', asking: 'waiting' })
+ const swapped = await store.prepare(path, 'Swapped', { working: 'review', listening: 'running', asking: 'jumping' })
+ expect(swapped.id).not.toBe(plain.id)
+ const rows: PetRows = { rest: 'idle', working: 'review', listening: 'running', sending: 'waving', asking: 'idle' }
+ expect(swapped.rows).toEqual(rows)
+ expect(swapped.sheet.rows.idle.length).toBe(3)
+ expect(JSON.parse(await readFile(join(dir, `${swapped.id}.json`), 'utf8'))).toEqual({ name: 'Swapped', rows })
+ expect(await store.rows(swapped.id)).toEqual(rows)
+ expect(decodePack(await store.pack(swapped.id)).working.frames.length).toBe(2)
+ // The same choice again is the same pack.
+ expect((await store.prepare(path, 'Swapped', { working: 'review', listening: 'running', asking: 'jumping' })).id).toBe(swapped.id)
+ })
+
+ it('refuses an empty chosen rest or working row', async () => {
+ await expect(store.prepare(await source(120), undefined, { working: 'jumping' })).rejects.toMatchObject({ code: 'NO_WORKING' })
+ await expect(store.prepare(await source(120), undefined, { rest: 'waving' })).rejects.toMatchObject({ code: 'NO_REST' })
+ })
+
+ it('re-prepares an old pack with the row choice it was made with', async () => {
+ const path = join(work, 'rich.png')
+ await writeFile(path, richPng({ 0: 3, 3: 2, 5: 1, 6: 2, 7: 4, 8: 2 }))
+ const a = await store.prepare(path, undefined, { rest: 'review', working: 'waiting' })
+ const file = join(dir, `${a.id}.hpet`)
+ const fresh = await readFile(file)
+ const old = Buffer.from(fresh)
+ old[4] = 0
+ await writeFile(file, old)
+ expect(await store.pack(a.id)).toEqual(fresh)
+ })
+
+ it('rows: null for an unknown id, a sidecar without rows, or one with a bad row', async () => {
+ expect(await store.rows('nope')).toBeNull()
+ expect(await store.rows('ffffffffffffffff')).toBeNull()
+ const a = await store.prepare(await source(130))
+ await writeFile(join(dir, `${a.id}.json`), JSON.stringify({ name: 'old' }))
+ expect(await store.rows(a.id)).toBeNull()
+ await writeFile(join(dir, `${a.id}.json`), JSON.stringify({ name: 'old', rows: { ...DEFAULT_ROWS_IDLE, rest: 'sideways' } }))
+ expect(await store.rows(a.id)).toBeNull()
+ // A pack re-made from a sidecar without rows uses the defaults, as it was made before rows could be chosen.
+ await writeFile(join(dir, `${a.id}.json`), JSON.stringify({ name: 'old' }))
+ const file = join(dir, `${a.id}.hpet`)
+ const fresh = await readFile(file)
+ const old = Buffer.from(fresh)
+ old[4] = 0
+ await writeFile(file, old)
+ expect(await store.pack(a.id)).toEqual(fresh)
+ })
+})
diff --git a/cli/src/cable/pets/store.ts b/cli/src/cable/pets/store.ts
new file mode 100644
index 000000000..9cbe25ec9
--- /dev/null
+++ b/cli/src/cable/pets/store.ts
@@ -0,0 +1,255 @@
+import { createHash } from 'node:crypto'
+import { readFileSync, statSync } from 'node:fs'
+import { mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises'
+import { basename, extname, join } from 'node:path'
+import { convertPet, type ConvertedPet } from './convert.js'
+import { PACK_VERSION, encodePack } from './pack.js'
+import { PET_ROWS, PET_STATES, PetSheetError, parsePetSheet, pickPetRows, readPetSource, resolvePetRows, type PetRows, type PetSheet } from './sheet.js'
+
+export type PetTarget = 'all' | string // 'all', or an engine name
+export interface PetMapping {
+ all: string | null
+ engines: Record<string, string>
+}
+
+export class PetStoreError extends Error {
+ readonly code: 'UNKNOWN_PET' | 'BAD_TARGET'
+ constructor(code: 'UNKNOWN_PET' | 'BAD_TARGET', message: string) {
+ super(message)
+ this.name = 'PetStoreError'
+ this.code = code
+ }
+}
+
+// The dial holds every referenced pack in PSRAM: all + three engines fit in its ~5 MB of free PSRAM.
+export const MAX_PACKS = 4
+// Packs prepared (previewed) but not yet applied are spared by the sweep, so applying one pet cannot delete the one
+// the user is still looking at; only the newest few are spared.
+const MAX_PENDING = 4
+const ID_RE = /^[0-9a-f]{16}$/
+// The dial keeps an engine name in 16 bytes with its NUL (pet_store.c: char engine[16], strlen < 16): 15 characters.
+const ENGINE_RE = /^[\w.-]{1,15}$/
+// ...and a map of MAX_ENGINES = 8 entries; the rest of pet.map is ignored there.
+export const MAX_ENGINES = 8
+const NAME_MAX = 40
+const FORBIDDEN_ENGINES = new Set(['__proto__', 'constructor', 'prototype'])
+
+// <HARNESS_DEVICES_DIR>/pets: <id>.hpet (the pack), <id>.png (its source, to re-convert if the pack format moves on),
+// <id>.json ({name, rows}: the source file's base name, for the app, and which row plays which state) and pets.json (which pack stands for what). The daemon's devices process reads this on its own, so a restart
+// cannot lose the mapping.
+export class PetStore {
+ private map: PetMapping
+ /** Identity of the pets.json that `map` was read from (mtime, size, inode), so another daemon's write is noticed. */
+ private mapStamp: string
+ private pending: string[] = []
+ private queue: Promise<unknown> = Promise.resolve()
+
+ constructor(private readonly dir: string) {
+ this.mapStamp = stampOf(join(dir, 'pets.json'))
+ this.map = loadMapping(join(dir, 'pets.json'))
+ }
+
+ // Two daemons (or a restart) can share the directory: the file is the truth, the field only a cache of it. A cheap
+ // stat decides whether to read again.
+ private refresh(): void {
+ const file = join(this.dir, 'pets.json')
+ const stamp = stampOf(file)
+ if (stamp === this.mapStamp) return
+ this.map = loadMapping(file)
+ this.mapStamp = stamp
+ }
+
+ mapping(): PetMapping {
+ this.refresh()
+ return { all: this.map.all, engines: { ...this.map.engines } }
+ }
+
+ // Distinct pack ids the mapping references, "all" first.
+ mappedIds(): string[] {
+ this.refresh()
+ return [...new Set([this.map.all, ...Object.values(this.map.engines)].filter((v): v is string => !!v))]
+ }
+
+ async pack(id: string): Promise<Buffer> {
+ if (!ID_RE.test(id)) throw new PetStoreError('UNKNOWN_PET', 'That pet is not on this computer any more')
+ let pack: Buffer
+ try {
+ pack = await readFile(join(this.dir, `${id}.hpet`))
+ } catch {
+ throw new PetStoreError('UNKNOWN_PET', 'That pet is not on this computer any more')
+ }
+ // A pack written by an older format is made again from its kept source, never handed to a dial as it is.
+ if (pack.length > 4 && pack[4] !== PACK_VERSION) {
+ let source: Buffer | null = null
+ try {
+ source = await readFile(join(this.dir, `${id}.png`))
+ } catch { /* no source kept: the pack is all there is */ }
+ if (source) {
+ const { pack: fresh } = buildPack(source, (await this.rows(id)) ?? undefined)
+ await writeAtomic(join(this.dir, `${id}.hpet`), fresh)
+ return fresh
+ }
+ }
+ return pack
+ }
+
+ // What the app calls a pack: the base name of the file it was made from ('' when unknown).
+ async name(id: string): Promise<string> {
+ if (!ID_RE.test(id)) return ''
+ try {
+ const raw = JSON.parse(await readFile(join(this.dir, `${id}.json`), 'utf8')) as { name?: unknown }
+ return typeof raw.name === 'string' ? raw.name.slice(0, NAME_MAX) : ''
+ } catch {
+ return ''
+ }
+ }
+
+ // Which row plays which state in a pack (null when unknown: a pack made before rows could be chosen).
+ async rows(id: string): Promise<PetRows | null> {
+ if (!ID_RE.test(id)) return null
+ try {
+ const raw = JSON.parse(await readFile(join(this.dir, `${id}.json`), 'utf8')) as { rows?: Record<string, unknown> }
+ const rows = {} as PetRows
+ for (const state of PET_STATES) {
+ const row = raw.rows?.[state]
+ if (!PET_ROWS.includes(row as PetRows[typeof state])) return null
+ rows[state] = row as PetRows[typeof state]
+ }
+ return rows
+ } catch {
+ return null
+ }
+ }
+
+ // Validate, convert and keep a sheet. The id is the first 8 bytes of the source's sha256 (with the row choice when
+ // it is not the default), so the same file and choice is the same pack however many times and for however many
+ // engines it is chosen.
+ async prepare(sourcePath: string, label?: string, choice?: Partial<PetRows>):
+ Promise<{ id: string; pet: ConvertedPet; bytes: number; rows: PetRows; sheet: PetSheet }> {
+ const source = await readPetSource(sourcePath)
+ const { id, pet, pack, rows, sheet } = buildPack(source, choice)
+ // A name from the app (the pet's own, e.g. petdex's displayName) wins over the file's base name. Control characters
+ // are stripped and an empty result falls back, so the sidecar never holds an unprintable or oversized name.
+ const given = [...(label ?? '').replace(/[\u0000-\u001f\u007f-\u009f]/g, '').trim()].slice(0, NAME_MAX).join('').trim()
+ const name = given || [...basename(sourcePath, extname(sourcePath))].slice(0, NAME_MAX).join('')
+ return this.serial(async () => {
+ await mkdir(this.dir, { recursive: true })
+ // Each to a temp file and renamed, so a crash never leaves half a pack that pack() would hand to a dial.
+ await writeAtomic(join(this.dir, `${id}.hpet`), pack)
+ await writeAtomic(join(this.dir, `${id}.png`), source)
+ await writeAtomic(join(this.dir, `${id}.json`), JSON.stringify({ name, rows }))
+ this.pending = [...this.pending.filter((p) => p !== id), id].slice(-MAX_PENDING)
+ // Previews that were never applied would otherwise pile up: only the newest few are kept beside the mapped ones.
+ await this.sweep()
+ return { id, pet, bytes: pack.length, rows, sheet }
+ })
+ }
+
+ async apply(target: PetTarget, id: string): Promise<PetMapping> {
+ checkTarget(target)
+ if (!ID_RE.test(id)) throw new PetStoreError('UNKNOWN_PET', 'That pet is not on this computer any more')
+ return this.serial(async () => {
+ await this.pack(id) // must exist
+ const next = this.mapping()
+ if (target === 'all') next.all = id
+ else {
+ if (!(target in next.engines) && Object.keys(next.engines).length >= MAX_ENGINES) {
+ throw new PetStoreError('BAD_TARGET', 'Up to 8 engines can have their own pet')
+ }
+ next.engines[target] = id
+ }
+ const distinct = new Set([next.all, ...Object.values(next.engines)].filter(Boolean))
+ if (distinct.size > MAX_PACKS) throw new PetSheetError('TOO_MANY', 'Up to 4 pets at once: reset one first')
+ this.pending = this.pending.filter((p) => p !== id)
+ return this.commit(next)
+ })
+ }
+
+ async reset(target: PetTarget): Promise<PetMapping> {
+ checkTarget(target)
+ return this.serial(async () => {
+ const next = this.mapping()
+ if (target === 'all') next.all = null
+ else delete next.engines[target]
+ return this.commit(next)
+ })
+ }
+
+ // Calls run one at a time: each reads the mapping the previous one left.
+ private serial<T>(job: () => Promise<T>): Promise<T> {
+ const run = this.queue.then(job, job)
+ this.queue = run.catch(() => undefined)
+ return run
+ }
+
+ private async commit(next: PetMapping): Promise<PetMapping> {
+ await mkdir(this.dir, { recursive: true })
+ const file = join(this.dir, 'pets.json')
+ await writeAtomic(file, JSON.stringify(next, null, 2))
+ this.map = next
+ this.mapStamp = stampOf(file)
+ await this.sweep()
+ return this.mapping()
+ }
+
+ private async sweep(): Promise<void> {
+ const keep = new Set([...this.mappedIds(), ...this.pending])
+ for (const name of await readdir(this.dir)) {
+ const m = /^([0-9a-f]{16})\.(hpet|png|json)(\.tmp)?$/.exec(name)
+ if (m && !keep.has(m[1])) await rm(join(this.dir, name), { force: true })
+ }
+ }
+}
+
+function buildPack(source: Buffer, choice?: Partial<PetRows>): { id: string; pet: ConvertedPet; pack: Buffer; rows: PetRows; sheet: PetSheet } {
+ const sheet = parsePetSheet(source)
+ const rows = resolvePetRows(sheet, choice)
+ // The default rows hash the source alone, so a pet made before rows could be chosen keeps its id. Compared after
+ // the fallbacks, so naming a row the defaults fall back to is no choice either: the pack is the same.
+ const defaults = pickPetRows(sheet)
+ const hash = createHash('sha256').update(source)
+ if (PET_STATES.some((state) => rows[state] !== defaults[state])) {
+ hash.update(`\0rows:${PET_STATES.map((state) => rows[state]).join(',')}`)
+ }
+ const digest = hash.digest()
+ const pet = convertPet(sheet, rows)
+ return { id: digest.subarray(0, 8).toString('hex'), pet, pack: encodePack(pet, digest.subarray(0, 8)), rows, sheet }
+}
+
+function stampOf(file: string): string {
+ try {
+ const st = statSync(file)
+ return `${st.mtimeMs}:${st.size}:${st.ino}`
+ } catch {
+ return ''
+ }
+}
+
+async function writeAtomic(file: string, data: string | Buffer): Promise<void> {
+ await writeFile(`${file}.tmp`, data)
+ await rename(`${file}.tmp`, file)
+}
+
+function checkTarget(target: string): void {
+ if (target === 'all') return
+ if (!ENGINE_RE.test(target) || FORBIDDEN_ENGINES.has(target)) {
+ throw new PetStoreError('BAD_TARGET', 'That is not an engine name')
+ }
+}
+
+function loadMapping(file: string): PetMapping {
+ const empty: PetMapping = { all: null, engines: {} }
+ try {
+ const raw = JSON.parse(readFileSync(file, 'utf8')) as { all?: unknown; engines?: unknown }
+ const all = typeof raw.all === 'string' && ID_RE.test(raw.all) ? raw.all : null
+ const engines: Record<string, string> = {}
+ if (raw.engines && typeof raw.engines === 'object') {
+ for (const [k, v] of Object.entries(raw.engines)) {
+ if (Object.keys(engines).length < MAX_ENGINES && typeof v === 'string' && ID_RE.test(v) && ENGINE_RE.test(k) && !FORBIDDEN_ENGINES.has(k)) engines[k] = v
+ }
+ }
+ return { all, engines }
+ } catch {
+ return empty
+ }
+}
diff --git a/cli/src/cable/pets/sync.spec.ts b/cli/src/cable/pets/sync.spec.ts
new file mode 100644
index 000000000..54e8b96c3
--- /dev/null
+++ b/cli/src/cable/pets/sync.spec.ts
@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest'
+import { planPetSync } from './sync.js'
+
+const A = 'a'.repeat(16)
+const B = 'b'.repeat(16)
+const C = 'c'.repeat(16)
+
+describe('planPetSync', () => {
+ it('held nothing → send all mapped, map first', () => {
+ const mapping = { all: A, engines: { codex: B, claude: A, hermes: C } }
+ const plan = planPetSync(mapping, [])
+ expect(plan.map).toEqual(mapping)
+ // all first, then engines by name; the pack both "all" and claude use is listed once.
+ expect(plan.send).toEqual([A, B, C])
+ expect(plan.drop).toEqual([])
+ })
+
+ it('held stale → drop it, send only what is missing', () => {
+ const plan = planPetSync({ all: null, engines: { claude: A, codex: B } }, [B, C])
+ expect(plan.drop).toEqual([C])
+ expect(plan.send).toEqual([A])
+ })
+})
diff --git a/cli/src/cable/pets/sync.ts b/cli/src/cable/pets/sync.ts
new file mode 100644
index 000000000..bbd2750df
--- /dev/null
+++ b/cli/src/cable/pets/sync.ts
@@ -0,0 +1,28 @@
+import type { PetMapping } from './store.js'
+
+/** What a dial's pets look like to the Devices tab (cableSession fills it, lib/harnessDevices passes it on). */
+export interface PetDialState {
+ supported: boolean
+ held: string[]
+ sending: { id: string; percent: number } | null
+ /** Packs the dial refused this link (pack id → reason: memory, busy, crc, version, shape). */
+ errors?: Record<string, string>
+}
+
+// What the dial must be told and sent so it holds exactly the packs the mapping names. Pure: the session decides when.
+// map - always sent first, so the dial knows which pack stands for what even before the bytes arrive
+// send - mapped ids the dial does not hold, de-duplicated, "all" first then engines by name (a stable order, so a
+// retry or a second dial sees the same sequence)
+// drop - ids the dial holds that nothing maps any more (its 4-pack budget is for packs in use)
+export function planPetSync(mapping: PetMapping, held: string[]): { map: PetMapping; send: string[]; drop: string[] } {
+ const mapped: string[] = []
+ if (mapping.all) mapped.push(mapping.all)
+ for (const engine of Object.keys(mapping.engines).sort()) mapped.push(mapping.engines[engine])
+ const unique = [...new Set(mapped)]
+ const holding = new Set(held)
+ return {
+ map: { all: mapping.all, engines: { ...mapping.engines } },
+ send: unique.filter((id) => !holding.has(id)),
+ drop: [...new Set(held)].filter((id) => !unique.includes(id)),
+ }
+}
diff --git a/cli/src/config/env.ts b/cli/src/config/env.ts
index fd067875b..7b595ca00 100644
--- a/cli/src/config/env.ts
+++ b/cli/src/config/env.ts
@@ -216,6 +216,9 @@ const fields = {
// `app-*.log`/`cli-*.log`, so one directory holds everything a bug report needs. Not the data dir:
// `harness.log` there is the daemon's console, and `harness reset` wipes it.
HARNESS_LOGS_DIR: text(join(adapterRootDir, 'logs')),
+ // The dials' own product-root state: `pets/` holds the custom pet packs and which pack stands for what.
+ // Not daemon data (`harness reset` must not lose a user's pets), and shared by this user's daemons.
+ HARNESS_DEVICES_DIR: text(join(adapterRootDir, 'devices')),
// Where each daemon on this computer records its data folder and port under the tag it puts on its
// panes, so an engine's hook reaches the daemon that made its pane whichever daemon installed the hook
// (lib/hookRoutes.ts). Product-root state, shared by every daemon of this user: not in a data folder.
diff --git a/cli/src/core/api.ts b/cli/src/core/api.ts
index e8ae6f257..25b7c61ff 100644
--- a/cli/src/core/api.ts
+++ b/cli/src/core/api.ts
@@ -838,7 +838,7 @@ export type VoiceRouteReply = { t: 'taken' } | { t: 'sent'; agentId: string } |
/** The Devices tab (services/devices.ts): the devices on this computer, and a device's settings. Only
* the owner, on this computer or through the owner's own app, may manage them. */
-export const DEVICES_REQUESTS = ['harness_devices_list', 'harness_device_settings'] as const
+export const DEVICES_REQUESTS = ['harness_devices_list', 'harness_device_settings', 'pet_preview', 'pet_apply', 'pet_reset', 'pet_status'] as const
/**
* The core's calls into the devices: what the windows on this computer said that the dial follows, the
diff --git a/cli/src/lib/harnessDevices.spec.ts b/cli/src/lib/harnessDevices.spec.ts
index 48f6dcd02..4772f0b17 100644
--- a/cli/src/lib/harnessDevices.spec.ts
+++ b/cli/src/lib/harnessDevices.spec.ts
@@ -1,9 +1,21 @@
-import { describe, expect, it, vi } from 'vitest'
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { PNG } from 'pngjs'
+import { afterAll, describe, expect, it, vi } from 'vitest'
+import { decodePack } from '../cable/pets/pack.js'
+import { PetStore } from '../cable/pets/store.js'
import { harnessDevicesRequest, type HarnessDevicesService } from './harnessDevices.js'
import type { DialStatus, DeviceSettings } from '../cable/cableSession.js'
import { encryptDownFrame, encryptRpcResult } from './e2ee/applicationFrames.js'
import { ENCRYPTED_UP_TYPES } from './e2ee/core.js'
+// The real decoder, counted: the status poll must not decode a pack it has already drawn.
+vi.mock('../cable/pets/pack.js', async (original) => {
+ const actual = await original<typeof import('../cable/pets/pack.js')>()
+ return { ...actual, decodePack: vi.fn(actual.decodePack) }
+})
+
const settings: DeviceSettings = { brightness: 80, muted: false, quiet: false, character: 2,
face: 466, round: true, voiceLang: 'en', scrollReversed: false, straightTitle: true, focusFace: false }
describe('owner device management', () => {
@@ -15,7 +27,7 @@ describe('owner device management', () => {
{ id: 'updating', attached: true, settings, updating: 'next' },
]
const set = vi.fn(async () => ({ ok: true }))
- const service: HarnessDevicesService = { status: () => ({ attached: true, devices }), revision: () => 4, set }
+ const service: HarnessDevicesService = { status: () => ({ attached: true, devices }), revision: () => 4, set, ...petStubs() }
return { service, set }
}
it('reads the whole host and sends a sparse patch only to the named device', async () => {
@@ -47,3 +59,151 @@ describe('owner device management', () => {
expect(ENCRYPTED_UP_TYPES.has('harness_devices_changed')).toBe(true)
})
})
+
+const roots: string[] = []
+afterAll(async () => { await Promise.all(roots.map(d => rm(d, { recursive: true, force: true }))) })
+
+function petStubs() {
+ return { pets: () => new PetStore(join(tmpdir(), 'unused-pets')), petDial: () => ({ supported: false, held: [], sending: null }), petsChanged: () => {} }
+}
+
+// What the defaults come to on sheetPng: only idle and running are drawn.
+const DEFAULT_ROWS_IDLE = { rest: 'idle', working: 'running', listening: 'idle', sending: 'idle', asking: 'idle' }
+
+// A 768 x 936 sheet with an idle and a running row.
+function sheetPng(): Buffer {
+ const png = new PNG({ width: 768, height: 936 })
+ for (const row of [0, 7]) for (let c = 0; c < 2; c++) for (let y = 0; y < 30; y++) for (let x = 0; x < 30; x++) {
+ png.data.set([200, 90 + c * 40, (x * 5 + y) & 255, 255], ((row * 104 + 30 + y) * 768 + c * 96 + 30 + x) * 4)
+ }
+ return PNG.sync.write(png)
+}
+
+describe('pet requests', () => {
+ const fixture = async () => {
+ const work = await mkdtemp(join(tmpdir(), 'pet-requests-'))
+ roots.push(work)
+ const petsChanged = vi.fn()
+ const store = new PetStore(join(work, 'pets'))
+ const service: HarnessDevicesService = {
+ status: () => ({ attached: false }), set: async () => ({ ok: true }),
+ pets: () => store, petDial: () => ({ supported: true, held: ['x'], sending: null }), petsChanged,
+ }
+ const sheet = join(work, 'sheet.png')
+ await writeFile(sheet, sheetPng())
+ const bad = join(work, 'bad.png')
+ await writeFile(bad, PNG.sync.write(new PNG({ width: 10, height: 10 })))
+ return { service, petsChanged, sheet, bad, work }
+ }
+ const PNG_URL = /^data:image\/png;base64,/
+
+ it('pet_preview on a valid sheet returns frames per scene as data URLs', async () => {
+ const { service, sheet } = await fixture()
+ const reply = await harnessDevicesRequest(service, 'pet_preview', { path: sheet }) as Record<string, any>
+ expect(reply).toMatchObject({ ok: true, id: expect.stringMatching(/^[0-9a-f]{16}$/), warnings: expect.any(Array), stepMs: { small: 120 } })
+ expect(reply.bytes).toBeGreaterThan(0)
+ expect(reply.colours).toBeGreaterThan(0)
+ for (const scene of ['small', 'working', 'listening', 'sending']) {
+ expect(reply.frames[scene].length).toBeGreaterThan(0)
+ for (const url of reply.frames[scene]) {
+ expect(url).toMatch(PNG_URL)
+ const png = PNG.sync.read(Buffer.from(url.slice(url.indexOf(',') + 1), 'base64'))
+ expect(png.width).toBeGreaterThan(0)
+ }
+ expect(reply.stepMs[scene]).toBeGreaterThan(0)
+ }
+ expect(Object.keys(reply.frames).sort()).toEqual(['asking', 'listening', 'sending', 'small', 'working'])
+ expect(reply.name).toBe('sheet')
+ expect(reply.stepMs).toEqual({ small: 120, asking: 120, working: 120, listening: 120, sending: 120 })
+ })
+ it('pet_preview with a name stores it, sanitized: control characters stripped, trimmed, cut to 40; empty falls back to the file name', async () => {
+ const { service, sheet } = await fixture()
+ const nameOf = async (name: unknown) => {
+ const reply = await harnessDevicesRequest(service, 'pet_preview', { path: sheet, name }) as Record<string, any>
+ return reply.name
+ }
+ expect(await nameOf(' ddo-zvzo ')).toBe('ddo-zvzo')
+ expect(await nameOf('a\u0000b\u001b[31mc\n')).toBe('ab[31mc')
+ expect(await nameOf('x'.repeat(100))).toBe('x'.repeat(40))
+ expect(await nameOf('\u0000\u0007 \n')).toBe('sheet')
+ expect(await harnessDevicesRequest(service, 'pet_preview', { path: sheet, name: 5 })).toEqual({ error: 'BAD_PET_REQUEST' })
+ })
+ it("pet_preview on a bad sheet returns the sheet error's code and message", async () => {
+ const { service, bad } = await fixture()
+ const reply = await harnessDevicesRequest(service, 'pet_preview', { path: bad })
+ expect(reply).toMatchObject({ error: 'BAD_SIZE', message: expect.stringMatching(/\S/) })
+ expect(await harnessDevicesRequest(service, 'pet_preview', {})).toEqual({ error: 'BAD_PET_REQUEST' })
+ })
+ it('pet_preview answers the rows it used and a strip per drawn row of the sheet', async () => {
+ const { service, sheet } = await fixture()
+ const reply = await harnessDevicesRequest(service, 'pet_preview', { path: sheet }) as Record<string, any>
+ expect(reply.rows).toEqual(DEFAULT_ROWS_IDLE)
+ expect(reply.sheetRows.map((r: { row: string; frames: number }) => [r.row, r.frames])).toEqual([['idle', 2], ['running', 2]])
+ for (const { strip } of reply.sheetRows) {
+ const png = PNG.sync.read(Buffer.from(strip.slice(strip.indexOf(',') + 1), 'base64'))
+ expect([png.width, png.height]).toEqual([2 * 59, 64])
+ }
+ })
+ it('pet_preview with rows: a chosen row per state, the defaults for the rest; another choice is another pack', async () => {
+ const { service, sheet } = await fixture()
+ const plain = await harnessDevicesRequest(service, 'pet_preview', { path: sheet }) as Record<string, any>
+ const swapped = await harnessDevicesRequest(service, 'pet_preview', { path: sheet, rows: { rest: 'running', working: 'idle', other: 'x' } }) as Record<string, any>
+ expect(swapped.ok).toBe(true)
+ expect(swapped.id).not.toBe(plain.id)
+ expect(swapped.rows).toEqual({ rest: 'running', working: 'idle', listening: 'running', sending: 'running', asking: 'running' })
+ const same = await harnessDevicesRequest(service, 'pet_preview', { path: sheet, rows: { listening: 'idle' } }) as Record<string, any>
+ expect(same.id).toBe(plain.id)
+ await harnessDevicesRequest(service, 'pet_apply', { target: 'all', id: swapped.id })
+ const status = await harnessDevicesRequest(service, 'pet_status', {}) as { pets: Record<string, { rows: unknown }> }
+ expect(status.pets[swapped.id].rows).toEqual(swapped.rows)
+ })
+ it('pet_preview refuses an unknown row name and explains an empty chosen row', async () => {
+ const { service, sheet } = await fixture()
+ expect(await harnessDevicesRequest(service, 'pet_preview', { path: sheet, rows: { rest: 'sideways' } })).toEqual({ error: 'BAD_PET_REQUEST' })
+ expect(await harnessDevicesRequest(service, 'pet_preview', { path: sheet, rows: { working: 5 } })).toEqual({ error: 'BAD_PET_REQUEST' })
+ expect(await harnessDevicesRequest(service, 'pet_preview', { path: sheet, rows: 'idle' })).toEqual({ error: 'BAD_PET_REQUEST' })
+ expect(await harnessDevicesRequest(service, 'pet_preview', { path: sheet, rows: { working: 'jumping' } }))
+ .toEqual({ error: 'NO_WORKING', message: 'The row chosen for Working is empty' })
+ expect(await harnessDevicesRequest(service, 'pet_preview', { path: sheet, rows: { rest: 'review' } }))
+ .toEqual({ error: 'NO_REST', message: 'The row chosen for Rest is empty' })
+ })
+ it('pet_apply with an unknown id answers UNKNOWN_PET and does not announce a change', async () => {
+ const { service, petsChanged } = await fixture()
+ expect(await harnessDevicesRequest(service, 'pet_apply', { target: 'all', id: '0123456789abcdef' })).toMatchObject({ error: 'UNKNOWN_PET' })
+ expect(await harnessDevicesRequest(service, 'pet_apply', { target: 'all', id: 'nope' })).toMatchObject({ error: 'UNKNOWN_PET' })
+ expect(petsChanged).not.toHaveBeenCalled()
+ })
+ it('pet_apply and pet_reset change the mapping and call petsChanged; pet_status reports it', async () => {
+ const { service, petsChanged, sheet } = await fixture()
+ const { id } = await harnessDevicesRequest(service, 'pet_preview', { path: sheet }) as { id: string }
+ expect(await harnessDevicesRequest(service, 'pet_apply', { target: 'claude', id })).toEqual({ ok: true, mapping: { all: null, engines: { claude: id } } })
+ expect(petsChanged).toHaveBeenCalledTimes(1)
+ expect(await harnessDevicesRequest(service, 'pet_status', {})).toEqual({
+ mapping: { all: null, engines: { claude: id } }, dial: { supported: true, held: ['x'], sending: null },
+ pets: { [id]: { name: 'sheet', thumb: expect.stringMatching(PNG_URL), rows: DEFAULT_ROWS_IDLE } },
+ })
+ expect(await harnessDevicesRequest(service, 'pet_reset', { target: 'claude' })).toEqual({ ok: true, mapping: { all: null, engines: {} } })
+ expect(petsChanged).toHaveBeenCalledTimes(2)
+ expect(await harnessDevicesRequest(service, 'pet_reset', { target: '' })).toMatchObject({ error: 'BAD_PET_REQUEST' })
+ expect(await harnessDevicesRequest(service, 'pet_reset', { target: '../x' })).toMatchObject({ error: 'BAD_TARGET' })
+ })
+ it('pet_status draws a pack once however often it is polled', async () => {
+ const { service, sheet } = await fixture()
+ const { id } = await harnessDevicesRequest(service, 'pet_preview', { path: sheet }) as { id: string }
+ await harnessDevicesRequest(service, 'pet_apply', { target: 'all', id })
+ vi.mocked(decodePack).mockClear()
+ const first = await harnessDevicesRequest(service, 'pet_status', {}) as { pets: Record<string, { thumb: string }> }
+ expect(decodePack).toHaveBeenCalledTimes(1)
+ const second = await harnessDevicesRequest(service, 'pet_status', {}) as { pets: Record<string, { thumb: string }> }
+ expect(decodePack).toHaveBeenCalledTimes(1)
+ expect(second.pets[id].thumb).toBe(first.pets[id].thumb)
+ expect(first.pets[id].thumb).toMatch(PNG_URL)
+ })
+ it('a store that cannot write answers STORAGE with a short reason', async () => {
+ const { service } = await fixture()
+ const denied = (code: string) => ({ ...service, pets: () => ({ mappedIds: () => [], mapping: () => ({ all: null, engines: {} }), reset: async () => { throw Object.assign(new Error('x'), { code }) } }) as unknown as PetStore })
+ expect(await harnessDevicesRequest(denied('EACCES'), 'pet_reset', { target: 'all' })).toEqual({ error: 'STORAGE', message: 'Couldn’t save the pet: permission denied' })
+ expect(await harnessDevicesRequest(denied('ENOSPC'), 'pet_reset', { target: 'all' })).toEqual({ error: 'STORAGE', message: 'Couldn’t save the pet: the disk is full' })
+ expect(await harnessDevicesRequest(denied('EROFS'), 'pet_reset', { target: 'all' })).toMatchObject({ error: 'STORAGE' })
+ })
+})
diff --git a/cli/src/lib/harnessDevices.ts b/cli/src/lib/harnessDevices.ts
index 2bed87078..a8feb81f6 100644
--- a/cli/src/lib/harnessDevices.ts
+++ b/cli/src/lib/harnessDevices.ts
@@ -1,10 +1,96 @@
import { z } from 'zod'
import type { DeviceSettingsPatch, DialStatus } from '../cable/cableSession.js'
+import { DEVICES_REQUESTS } from '../core/api.js'
+import { frameUrl, previewFrames, sheetStrips } from '../cable/pets/preview.js'
+import type { PetDialState } from '../cable/pets/sync.js'
+import { decodePack } from '../cable/pets/pack.js'
+import { PET_ROWS, PetSheetError, type PetRow, type PetRows } from '../cable/pets/sheet.js'
+import { PetStoreError, type PetMapping, type PetStore } from '../cable/pets/store.js'
export interface HarnessDevicesService {
status(): DialStatus
revision?(): number
set(id: string, patch: DeviceSettingsPatch): Promise<{ ok: boolean; error?: string }>
+ pets(): PetStore
+ petDial(): PetDialState
+ /** The mapping changed: the dials are brought in line with it. */
+ petsChanged(): void
+}
+
+// The pet requests are the pet_ names of the devices' request list: one list, so a name cannot be added to one and not the other.
+export const PET_REQUESTS = DEVICES_REQUESTS.filter((name) => name.startsWith('pet_'))
+// Which sheet row plays each state: a state left out takes the default, a row the sheet format has not is refused.
+const petRow = z.enum(PET_ROWS as [PetRow, ...PetRow[]]).optional()
+const petRows = z.object({ rest: petRow, working: petRow, listening: petRow, sending: petRow, asking: petRow })
+const petPath = z.object({ path: z.string().min(1).max(4096), name: z.string().max(1024).optional(), rows: petRows.optional() })
+const petApply = z.object({ target: z.string().min(1).max(64), id: z.string().min(1).max(64) })
+const petReset = z.object({ target: z.string().min(1).max(64) })
+
+const thumbCache = new WeakMap<PetStore, Map<string, string>>()
+function thumbsOf(store: PetStore): Map<string, string> {
+ let cache = thumbCache.get(store)
+ if (!cache) thumbCache.set(store, (cache = new Map()))
+ return cache
+}
+
+// A store that cannot write is the user's disk, not a bug: say what to look at.
+const STORAGE_REASONS: Record<string, string> = {
+ EACCES: 'permission denied', EPERM: 'permission denied', ENOSPC: 'the disk is full', EROFS: 'the disk is read-only',
+}
+
+async function petRequest(service: HarnessDevicesService, type: string, payload: Record<string, unknown>): Promise<Record<string, unknown>> {
+ const store = service.pets()
+ try {
+ if (type === 'pet_status') {
+ const pets: Record<string, { name: string; thumb: string; rows: PetRows | null }> = {}
+ const cache = thumbsOf(store)
+ const ids = store.mappedIds()
+ for (const id of cache.keys()) if (!ids.includes(id)) cache.delete(id)
+ for (const id of ids) {
+ // A pack never changes under its id, so its picture is drawn once; polling must not decode packs every second.
+ let thumb = cache.get(id)
+ if (thumb === undefined) {
+ thumb = ''
+ try {
+ const pet = decodePack(await store.pack(id))
+ thumb = frameUrl(pet.frames[pet.small.loops.idle[0]], pet.palette)
+ cache.set(id, thumb)
+ } catch { /* a pack that cannot be read has no picture (and is tried again); the name still shows */ }
+ }
+ pets[id] = { name: await store.name(id), thumb, rows: await store.rows(id) }
+ }
+ return { mapping: store.mapping(), dial: service.petDial(), pets }
+ }
+ if (type === 'pet_preview') {
+ const parsed = petPath.safeParse(payload)
+ if (!parsed.success) return { error: 'BAD_PET_REQUEST' }
+ const { id, bytes, pet: converted, rows, sheet } = await store.prepare(parsed.data.path, parsed.data.name, parsed.data.rows)
+ // The preview is what the dial gets: drawn from the stored pack, not from the conversion. sheetRows is every
+ // drawn row of the sheet, for the app's row picker.
+ const pet = decodePack(await store.pack(id))
+ return {
+ ok: true, id, name: await store.name(id), bytes, colours: pet.palette.length - 1, warnings: converted.warnings, ...previewFrames(pet),
+ rows, sheetRows: sheetStrips(sheet),
+ }
+ }
+ if (type === 'pet_apply') {
+ const parsed = petApply.safeParse(payload)
+ if (!parsed.success) return { error: 'BAD_PET_REQUEST' }
+ const mapping: PetMapping = await store.apply(parsed.data.target, parsed.data.id)
+ service.petsChanged()
+ return { ok: true, mapping }
+ }
+ const parsed = petReset.safeParse(payload)
+ if (!parsed.success) return { error: 'BAD_PET_REQUEST' }
+ const mapping = await store.reset(parsed.data.target)
+ service.petsChanged()
+ return { ok: true, mapping }
+ } catch (error) {
+ if (error instanceof PetSheetError || error instanceof PetStoreError) return { error: error.code, message: error.message }
+ const reason = STORAGE_REASONS[(error as NodeJS.ErrnoException | null)?.code ?? '']
+ if (reason) return { error: 'STORAGE', message: `Couldn’t save the pet: ${reason}` }
+ throw error
+ }
}
export const deviceSettingsPatchSchema = z.object({
@@ -25,6 +111,7 @@ export async function harnessDevicesRequest(
service: HarnessDevicesService | null, type: string, payload: Record<string, unknown>,
): Promise<Record<string, unknown>> {
if (!service) return { error: 'UNSUPPORTED' }
+ if ((PET_REQUESTS as readonly string[]).includes(type)) return petRequest(service, type, payload)
if (type === 'harness_devices_list') return { protocol: 1, revision: service.revision?.() ?? 0, status: service.status() }
const parsed = change.safeParse({ id: payload.id, patch: payload.patch })
if (!parsed.success) return { error: 'BAD_DEVICE_SETTINGS' }
diff --git a/cli/src/services/devices.spec.ts b/cli/src/services/devices.spec.ts
index f412bc63c..0fbe32efc 100644
--- a/cli/src/services/devices.spec.ts
+++ b/cli/src/services/devices.spec.ts
@@ -51,6 +51,8 @@ vi.mock('../cable/cableFleet.js', async (real) => {
turnDone = recorder('turnDone')
summary = recorder('summary')
turnError = recorder('turnError')
+ petsChanged = recorder('petsChanged')
+ petDial = () => ({ supported: false, held: [] as string[], sending: null })
setSettings = vi.fn(async (id: string, _patch: unknown) => (id === 'usb' ? { ok: true } : { ok: false, error: 'That device is not plugged into this computer.' }))
}
return { ...actual, CableFleet: FakeCable }
@@ -132,6 +134,7 @@ function start(over: { core?: CoreApi; faults?: string[]; cableDisabled?: boolea
const onExit = vi.fn()
const requests = startDevices(core, ports, {
logsDir: join(dataDir, 'logs'),
+ petsDir: join(dataDir, 'pets'),
dialSerials: ['E2E'],
testDialPort: over.testDialPort,
cableDisabled: over.cableDisabled,
@@ -155,6 +158,25 @@ describe('the devices, as the core starts them', () => {
expect(seen.voice.shutdown).toHaveBeenCalled()
})
+ it('keep the custom pets where petsDir says, and under HARNESS_DEVICES_DIR/pets by default', () => {
+ const dir = join(dataDir, 'pets')
+ mkdirSync(dir, { recursive: true })
+ writeFileSync(join(dir, 'pets.json'), JSON.stringify({ all: 'a'.repeat(16), engines: {} }))
+ start()
+ expect(seen.host.pets!()!.mapping()).toEqual({ all: 'a'.repeat(16), engines: {} })
+ // Without the option the store sits under env.HARNESS_DEVICES_DIR (never a path hard-coded in the service).
+ const was = env.HARNESS_DEVICES_DIR
+ ;(env as { HARNESS_DEVICES_DIR: string }).HARNESS_DEVICES_DIR = join(dataDir, 'home-devices')
+ try {
+ mkdirSync(join(dataDir, 'home-devices', 'pets'), { recursive: true })
+ writeFileSync(join(dataDir, 'home-devices', 'pets', 'pets.json'), JSON.stringify({ all: 'b'.repeat(16), engines: {} }))
+ startDevices(fakeCore({ dataDir }), emptyPorts(), { logsDir: join(dataDir, 'logs'), cableDisabled: true, log: () => {}, onExit: vi.fn() })
+ expect(seen.host.pets!()!.mapping().all).toBe('b'.repeat(16))
+ } finally {
+ ;(env as { HARNESS_DEVICES_DIR: string }).HARNESS_DEVICES_DIR = was
+ }
+ })
+
it('leave the serial ports alone when told to, and find the end-to-end suite\'s dial where it says', async () => {
start({ cableDisabled: true, testDialPort: '/dev/ttys042' })
expect(calls('start')).toHaveLength(0)
@@ -489,4 +511,20 @@ describe('the Devices tab', () => {
expect(await requests.harness_device_settings({ id: 'usb', patch: { brightness: 35 } }, owner)).toMatchObject({ ok: true, revision: 1 })
expect(seen.cable.setSettings).toHaveBeenCalledWith('usb', { brightness: 35 })
})
+ it('answers the pet requests to the owner on this computer only', async () => {
+ const { requests } = start()
+ for (const type of ['pet_preview', 'pet_apply', 'pet_reset', 'pet_status'] as const) {
+ expect(await requests[type]({}, { local: false, owner: false })).toEqual({ error: 'OWNER_REQUIRED' })
+ expect(await requests[type]({}, { local: true, owner: false })).toEqual({ error: 'OWNER_REQUIRED' })
+ expect(await requests[type]({}, { local: false, owner: true })).toEqual({ error: 'LOCAL_ONLY' })
+ }
+ expect(await requests.pet_status({}, { local: true, owner: true })).toEqual({
+ mapping: { all: null, engines: {} }, dial: { supported: false, held: [], sending: null }, pets: {},
+ })
+ expect(await requests.pet_apply({ target: 'all', id: '0123456789abcdef' }, { local: true, owner: true })).toMatchObject({ error: 'UNKNOWN_PET' })
+ expect(calls('petsChanged')).toEqual([])
+ // A changed mapping reaches every live dial.
+ expect(await requests.pet_reset({ target: 'all' }, { local: true, owner: true })).toMatchObject({ ok: true })
+ expect(calls('petsChanged')).toEqual([[]])
+ })
})
diff --git a/cli/src/services/devices.ts b/cli/src/services/devices.ts
index 245ddbff0..441839eea 100644
--- a/cli/src/services/devices.ts
+++ b/cli/src/services/devices.ts
@@ -23,6 +23,7 @@ import { DEVICES_REQUESTS, type CoreApi, type CorePorts, type DevicesPort, type
import { CableFleet, testDialDiscovery, type CableFleetOptions } from '../cable/cableFleet.js'
import { cableEventFor, cableQuestionCloseFor, cableQuestionFor, DaemonCableHost } from '../cable/cableHost.js'
import { CableSession } from '../cable/cableSession.js'
+import { PetStore } from '../cable/pets/store.js'
import { DialLog } from '../cable/dialLog.js'
import { DialVerdicts } from '../cable/dialPortVerdicts.js'
import { WindowForm } from '../cable/windowForm.js'
@@ -41,6 +42,8 @@ export { DEVICES_REQUESTS }
export interface DevicesDeps {
/** Where each dial keeps its log, one file a day (cable/dialLog.ts). */
logsDir: string
+ /** Where custom pets are kept; `<HARNESS_DEVICES_DIR>/pets` when unset. */
+ petsDir?: string
/** The dials to look at, by serial number (`HARNESS_DIAL_SERIALS`); every one when empty. */
dialSerials?: string[]
/** The end-to-end suite's dial, a pseudo-terminal (`HARNESSD_TEST_DIAL_PORT`). */
@@ -129,6 +132,8 @@ export function startDevices(core: CoreApi, ports: CorePorts, deps: DevicesDeps)
// the same registry, the same delivery path — and by the fleet's router, because a second
// implementation of any of those is a second set of bugs.
let revision = 0
+ // Built before the cable starts: a dial's first hello may read the mapping.
+ const pets = new PetStore(deps.petsDir ?? join(env.HARNESS_DEVICES_DIR, 'pets'))
const cableHost = new DaemonCableHost({
sessions: () => core.agents.advertised(),
refresh: deps.refresh,
@@ -187,6 +192,7 @@ export function startDevices(core: CoreApi, ports: CorePorts, deps: DevicesDeps)
// Which machine an agent is on, and getting there: the fleet's router, guarded. Null when it never
// started; a member that fails answers "unavailable", and the host routes this computer by itself.
fleet: () => fleet,
+ pets: () => pets,
})
// The dial's log lives with the app's, one file a day (dialLog.ts). The old unbounded `dial.log` in the
// data folder is cut down to a pointer, for anyone with a bookmark.
@@ -322,8 +328,18 @@ export function startDevices(core: CoreApi, ports: CorePorts, deps: DevicesDeps)
status: () => cableHost.currentDialStatus(),
revision: () => revision,
set: (id: string, patch: Parameters<CableFleet['setSettings']>[1]) => cable.setSettings(id, patch),
+ pets: () => pets,
+ // The first attached dial's state; a changed mapping is sent to every live dial.
+ petDial: () => cable.petDial(),
+ petsChanged: () => { void cable.petsChanged() },
}
- const answer = (type: string) => (payload: Record<string, unknown>, asker: { owner: boolean }) =>
+ const answer = (type: string) => (payload: Record<string, unknown>, asker: { local?: boolean; owner: boolean }) =>
asker.owner ? harnessDevicesRequest(tab, type, payload) : { error: 'OWNER_REQUIRED' }
- return { harness_devices_list: answer('harness_devices_list'), harness_device_settings: answer('harness_device_settings') }
+ // Pets name files on this computer by path, so they are answered to a process here only, never the owner's relayed app.
+ const local = (type: string) => (payload: Record<string, unknown>, asker: { local?: boolean; owner: boolean }) =>
+ !asker.owner ? { error: 'OWNER_REQUIRED' } : asker.local ? harnessDevicesRequest(tab, type, payload) : { error: 'LOCAL_ONLY' }
+ return {
+ harness_devices_list: answer('harness_devices_list'), harness_device_settings: answer('harness_device_settings'),
+ pet_preview: local('pet_preview'), pet_apply: local('pet_apply'), pet_reset: local('pet_reset'), pet_status: local('pet_status'),
+ }
}
diff --git a/desktop/lib/devices/device_settings.dart b/desktop/lib/devices/device_settings.dart
index 1f6e81399..24d55fef9 100644
--- a/desktop/lib/devices/device_settings.dart
+++ b/desktop/lib/devices/device_settings.dart
@@ -6,6 +6,7 @@ import '../shared/widgets/app_select_field.dart';
import '../shared/widgets/setting_row.dart';
import '../widgets/desktop_chrome.dart';
import 'devices_controller.dart';
+import 'pet_settings.dart';
/// Face ids belong to the firmware (character.h), not screen dimensions.
/// Add future faces here only when production firmware can actually select them.
@@ -18,9 +19,31 @@ class DeviceSettingsPanel extends StatefulWidget {
super.key,
required this.device,
required this.controller,
+ this.petEditor,
+ this.petViewerBeside = false,
+ this.petKey,
+ this.petGap = 0,
+ this.pickPetFile,
});
final HarnessDevice device;
final DevicesController controller;
+
+ /// The dial's pet edit, when the screen shares it with a viewer of its own.
+ final PetEditor? petEditor;
+
+ /// Whether the screen draws [petEditor]'s row viewer beside this panel, so
+ /// the Pet section leaves it out.
+ final bool petViewerBeside;
+
+ /// Marks the Pet section, so the screen can line the viewer up with it.
+ final Key? petKey;
+
+ /// Extra room above the Pet section, so it starts level with the viewer
+ /// beside it.
+ final double petGap;
+
+ /// Replaces the pet file chooser (tests).
+ final Future<String?> Function()? pickPetFile;
@override
State<DeviceSettingsPanel> createState() => _DeviceSettingsPanelState();
}
@@ -166,6 +189,17 @@ class _DeviceSettingsPanelState extends State<DeviceSettingsPanel> {
),
),
),
+ SizedBox(height: 10 + widget.petGap),
+ KeyedSubtree(
+ key: widget.petKey,
+ child: PetSettingsSection(
+ device: device,
+ controller: controller,
+ editor: widget.petEditor,
+ showViewer: !widget.petViewerBeside,
+ pickFile: widget.pickPetFile,
+ ),
+ ),
const SizedBox(height: 12),
Semantics(
liveRegion: true,
diff --git a/desktop/lib/devices/devices_controller.dart b/desktop/lib/devices/devices_controller.dart
index d7b413773..3553485b1 100644
--- a/desktop/lib/devices/devices_controller.dart
+++ b/desktop/lib/devices/devices_controller.dart
@@ -139,6 +139,7 @@ class DevicesController extends ChangeNotifier {
required String accountId,
this.sendSettings,
this.sendHostSettings,
+ this.petRequest,
this.storage,
this.confirmationTimeout = const Duration(seconds: 8),
}) : storageKey = 'harness_devices_v1.${Uri.encodeComponent(accountId)}' {
@@ -161,6 +162,22 @@ class DevicesController extends ChangeNotifier {
)?
sendHostSettings;
final Duration confirmationTimeout;
+
+ /// Pet requests to the machine's daemon (local connection only). Null hides
+ /// the Pet section: there is nobody to ask.
+ final Future<Map<String, dynamic>> Function(
+ String machineId,
+ String type,
+ Map<String, Object?> payload,
+ )?
+ petRequest;
+ final _petStatus = <String, PetStatus>{};
+ final _polls = <String, Timer>{};
+ final _pollTicks = <String, int>{};
+ final _petUnavailable = <String>{};
+
+ /// How long a pet may stay pending before the poll gives up.
+ static const petPollLimit = Duration(seconds: 120);
final _devices = <String, HarnessDevice>{};
final _pending = <String, Map<String, Object?>>{};
final _timers = <String, Timer>{};
@@ -425,9 +442,150 @@ class DevicesController extends ChangeNotifier {
if (message != null) _errors[key] = message;
}
+ PetStatus? petStatus(String key) => _petStatus[key];
+
+ Future<Map<String, dynamic>> _pet(
+ String key,
+ String type, [
+ Map<String, Object?> payload = const {},
+ ]) async {
+ final device = _devices[key];
+ final send = petRequest;
+ if (device == null || send == null) {
+ return {
+ 'error': 'LOCAL_ONLY',
+ 'message': 'Pets are set on this computer.',
+ };
+ }
+ try {
+ return await send(device.machineId, type, payload);
+ } catch (_) {
+ return {
+ 'error': 'UNREACHABLE',
+ 'message': 'Couldn’t reach Harness on this computer. Try again.',
+ };
+ }
+ }
+
+ /// True when the daemon answered a pet request with UNSUPPORTED: it predates
+ /// custom pets and the section stays locked.
+ bool petUnavailable(String key) => _petUnavailable.contains(key);
+
+ /// Whether the dial still has to take (or refuse) a mapped pet.
+ bool _petPending(String key, PetStatus status) {
+ final device = _devices[key];
+ if (device == null || !device.status.attached || !status.supported) {
+ return false;
+ }
+ if (status.sendingId != null) return true;
+ return status.mapped.any(
+ (id) => !status.held.contains(id) && !status.errors.containsKey(id),
+ );
+ }
+
+ void _stopPoll(String key) {
+ _polls.remove(key)?.cancel();
+ _pollTicks.remove(key);
+ }
+
+ /// Reads the mapping and the dial's pet state; polls every second while the
+ /// dial still has a mapped pet to take, for at most [petPollLimit].
+ Future<void> refreshPetStatus(String key, {bool restart = false}) async {
+ final reply = await _pet(key, 'pet_status');
+ if (_disposed) return;
+ if (reply['error'] != null) {
+ // Nobody answered: stop asking and forget the stale progress.
+ _stopPoll(key);
+ if (reply['error'] == 'UNSUPPORTED') _petUnavailable.add(key);
+ final old = _petStatus[key];
+ if (old != null) _petStatus[key] = old.withoutSending();
+ notifyListeners();
+ return;
+ }
+ _petUnavailable.remove(key);
+ final status = PetStatus.fromJson(reply);
+ _petStatus[key] = status;
+ if (restart) _stopPoll(key);
+ if (_petPending(key, status)) {
+ _polls[key] ??= Timer.periodic(const Duration(seconds: 1), (_) {
+ final ticks = _pollTicks[key] = (_pollTicks[key] ?? 0) + 1;
+ if (ticks >= petPollLimit.inSeconds) {
+ _stopPoll(key);
+ } else {
+ unawaited(refreshPetStatus(key));
+ }
+ });
+ } else {
+ _stopPoll(key);
+ }
+ notifyListeners();
+ }
+
+ /// Converts [path] on the daemon without saving it. [rows] picks the sheet
+ /// row (by petdex row name) for each state (`rest`, `working`, `listening`,
+ /// `sending`, `asking`); the daemon fills in the rest. Null when it failed;
+ /// [petError] then holds why.
+ Future<PetPreview?> previewPet(
+ String key,
+ String path, {
+ String? name,
+ Map<String, String>? rows,
+ }) async {
+ final reply = await _pet(key, 'pet_preview', {
+ 'path': path,
+ 'name': ?name,
+ 'rows': ?rows,
+ });
+ if (reply['error'] != null || reply['ok'] != true) {
+ _petErrors[key] = '${reply['message'] ?? reply['error'] ?? 'Failed'}';
+ return null;
+ }
+ _petErrors.remove(key);
+ return PetPreview.fromJson(reply);
+ }
+
+ final _petErrors = <String, String>{};
+ String? petError(String key) => _petErrors[key];
+
+ /// Engine keys the mapping holds a pet of their own for, from [reply]'s
+ /// mapping and the last known status.
+ Set<String> _engineKeys(String key, Map<String, dynamic> reply) => {
+ ..._petStatus[key]?.engines.keys ?? const <String>[],
+ if (reply['mapping'] case {'engines': final Map engines})
+ for (final engine in engines.keys) '$engine',
+ };
+
+ /// Makes [id] the pet of every agent: sets 'all', then drops each engine's
+ /// own pet so a leftover one no longer overrides it (the protocol keeps
+ /// per-engine pets; the app offers one pet only). Null when applied, else
+ /// the message to show in the row.
+ Future<String?> applyPet(String key, String id) async {
+ final reply = await _pet(key, 'pet_apply', {'target': 'all', 'id': id});
+ if (reply['error'] != null) {
+ return '${reply['message'] ?? reply['error']}';
+ }
+ for (final engine in _engineKeys(key, reply)) {
+ await _pet(key, 'pet_reset', {'target': engine});
+ }
+ await refreshPetStatus(key, restart: true);
+ return null;
+ }
+
+ /// Back to the built-in pet for every agent: 'all' and each engine entry.
+ Future<void> resetPet(String key) async {
+ final reply = await _pet(key, 'pet_reset', {'target': 'all'});
+ for (final engine in _engineKeys(key, reply)) {
+ await _pet(key, 'pet_reset', {'target': engine});
+ }
+ await refreshPetStatus(key, restart: true);
+ }
+
@override
void dispose() {
_disposed = true;
+ for (final timer in _polls.values) {
+ timer.cancel();
+ }
dial?.removeListener(_sync);
hosts?.removeListener(_sync);
for (final timer in _timers.values) {
@@ -436,3 +594,195 @@ class DevicesController extends ChangeNotifier {
super.dispose();
}
}
+
+/// What the daemon converted a sprite sheet into: the frames the dial will draw
+/// (decoded once from the PNG data URLs) and how fast each scene steps.
+@immutable
+class PetPreview {
+ const PetPreview({
+ required this.id,
+ required this.bytes,
+ required this.colours,
+ required this.warnings,
+ required this.frames,
+ required this.stepMs,
+ this.rows = const {},
+ this.sheetRows = const [],
+ });
+
+ final String id;
+ final int bytes, colours;
+ final List<String> warnings;
+
+ /// The row (by petdex row name) each state plays, defaults filled in. Empty
+ /// from a daemon that predates row choice.
+ final Map<String, String> rows;
+
+ /// The sheet's non-empty rows in sheet order, to choose from.
+ final List<PetSheetRow> sheetRows;
+
+ /// Scene (`small`, `working`, `listening`, `sending`) to decoded PNG frames.
+ final Map<String, List<Uint8List>> frames;
+ final Map<String, int> stepMs;
+
+ static PetPreview fromJson(Map<String, dynamic> json) {
+ final frames = <String, List<Uint8List>>{};
+ if (json['frames'] case final Map raw) {
+ for (final entry in raw.entries) {
+ frames['${entry.key}'] = [
+ for (final url in (entry.value as List? ?? const []))
+ if (url is String && url.contains(','))
+ base64Decode(url.substring(url.indexOf(',') + 1)),
+ ];
+ }
+ }
+ final step = <String, int>{};
+ if (json['stepMs'] case final Map raw) {
+ for (final entry in raw.entries) {
+ if (entry.value is num) {
+ step['${entry.key}'] = (entry.value as num).toInt();
+ }
+ }
+ }
+ final rows = <String, String>{};
+ if (json['rows'] case final Map raw) {
+ for (final entry in raw.entries) {
+ if (entry.value is String) rows['${entry.key}'] = entry.value as String;
+ }
+ }
+ return PetPreview(
+ id: '${json['id']}',
+ bytes: (json['bytes'] as num?)?.toInt() ?? 0,
+ colours: (json['colours'] as num?)?.toInt() ?? 0,
+ warnings: [for (final w in (json['warnings'] as List? ?? const [])) '$w'],
+ frames: frames,
+ stepMs: step,
+ rows: rows,
+ sheetRows: [
+ for (final raw in (json['sheetRows'] as List? ?? const []))
+ if (raw is Map && raw['row'] is String)
+ PetSheetRow(
+ row: raw['row'] as String,
+ frames: (raw['frames'] as num?)?.toInt() ?? 0,
+ strip: switch (raw['strip']) {
+ final String url when url.contains(',') => base64Decode(
+ url.substring(url.indexOf(',') + 1),
+ ),
+ _ => null,
+ },
+ ),
+ ],
+ );
+ }
+}
+
+/// One non-empty row of a previewed sheet: its petdex name, how many frames
+/// it holds and those frames side by side (a PNG), when the daemon sent them.
+@immutable
+class PetSheetRow {
+ const PetSheetRow({required this.row, required this.frames, this.strip});
+ final String row;
+ final int frames;
+ final Uint8List? strip;
+}
+
+/// A pet the daemon knows by id: its display name and a still thumbnail.
+@immutable
+class PetInfo {
+ const PetInfo(this.name, this.thumb);
+ final String name;
+ final Uint8List? thumb;
+}
+
+/// The pet mapping (which pet each engine shows) and the dial's pet state.
+@immutable
+class PetStatus {
+ const PetStatus({
+ this.all,
+ this.engines = const {},
+ this.supported = false,
+ this.held = const [],
+ this.sendingId,
+ this.percent = 0,
+ this.errors = const {},
+ this.pets = const {},
+ });
+
+ final String? all;
+ final Map<String, String> engines;
+ final bool supported;
+ final List<String> held;
+
+ /// Why the dial refused a pet: `memory`, `busy`, `crc`, `version`, `shape`
+ /// or `timeout`, by pet id. Absent from an older daemon.
+ final Map<String, String> errors;
+ final Map<String, PetInfo> pets;
+
+ /// The pet going to the dial right now, and how far it is; null when idle.
+ final String? sendingId;
+ final int percent;
+ PetSending? get sending =>
+ sendingId == null ? null : PetSending(sendingId!, percent);
+
+ /// Every pet id the mapping points at.
+ Set<String> get mapped => {?all, ...engines.values};
+
+ PetStatus withoutSending() => PetStatus(
+ all: all,
+ engines: engines,
+ supported: supported,
+ held: held,
+ errors: errors,
+ pets: pets,
+ );
+
+ static PetStatus fromJson(Map<String, dynamic> json) {
+ final mapping = json['mapping'] is Map ? json['mapping'] as Map : const {};
+ final dial = json['dial'] is Map ? json['dial'] as Map : const {};
+ final sending = dial['sending'] is Map ? dial['sending'] as Map : null;
+ final pets = <String, PetInfo>{};
+ if (json['pets'] case final Map raw) {
+ for (final e in raw.entries) {
+ if (e.value is! Map) continue;
+ final v = e.value as Map;
+ Uint8List? thumb;
+ if (v['thumb'] case final String url when url.contains(',')) {
+ try {
+ thumb = base64Decode(url.substring(url.indexOf(',') + 1));
+ } catch (_) {}
+ }
+ pets['${e.key}'] = PetInfo(
+ v['name'] is String && (v['name'] as String).isNotEmpty
+ ? v['name'] as String
+ : 'Custom pet',
+ thumb,
+ );
+ }
+ }
+ return PetStatus(
+ all: mapping['all'] is String ? mapping['all'] as String : null,
+ engines: {
+ if (mapping['engines'] is Map)
+ for (final e in (mapping['engines'] as Map).entries)
+ if (e.value is String) '${e.key}': e.value as String,
+ },
+ supported: dial['supported'] == true,
+ held: [for (final id in (dial['held'] as List? ?? const [])) '$id'],
+ sendingId: sending?['id'] is String ? sending!['id'] as String : null,
+ percent: (sending?['percent'] as num?)?.toInt() ?? 0,
+ errors: {
+ if (dial['errors'] is Map)
+ for (final e in (dial['errors'] as Map).entries)
+ if (e.value is String) '${e.key}': e.value as String,
+ },
+ pets: pets,
+ );
+ }
+}
+
+@immutable
+class PetSending {
+ const PetSending(this.id, this.percent);
+ final String id;
+ final int percent;
+}
diff --git a/desktop/lib/devices/devices_screen.dart b/desktop/lib/devices/devices_screen.dart
index 0eda788e1..da7cb191b 100644
--- a/desktop/lib/devices/devices_screen.dart
+++ b/desktop/lib/devices/devices_screen.dart
@@ -15,6 +15,8 @@ import 'device_artwork.dart';
import 'device_settings.dart';
import 'device_setup_dialog.dart';
import 'devices_controller.dart';
+import 'pet_settings.dart';
+import 'pet_source.dart';
final harnessDeviceShopUrl = Uri.parse(
'https://www.autonomous.ai/harness-device',
@@ -33,6 +35,7 @@ class _DevicesTabState extends State<DevicesTab> {
accountId: widget.notifier.currentUser?.id ?? 'guest',
storage: widget.notifier.deviceLibraryStorage,
sendHostSettings: widget.notifier.setHostDeviceSettings,
+ petRequest: widget.notifier.petRequest,
);
Timer? _refresh;
@override
@@ -67,10 +70,19 @@ class DevicesScreen extends StatefulWidget {
required this.controller,
this.openShop,
this.onRefresh,
+ this.pickPetFile,
+ this.resolvePetSource,
+ this.loadPetSheet,
});
final DevicesController controller;
final Future<bool> Function(Uri)? openShop;
final Future<void> Function()? onRefresh;
+
+ /// Replace the pet file chooser, [resolvePetSource] and [decodePetSheet]
+ /// (tests).
+ final Future<String?> Function()? pickPetFile;
+ final Future<PetSource> Function(String path)? resolvePetSource;
+ final Future<PetSheet?> Function(String path)? loadPetSheet;
@override
State<DevicesScreen> createState() => _DevicesScreenState();
}
@@ -79,19 +91,167 @@ class _DevicesScreenState extends State<DevicesScreen> {
String? _selectedKey;
String? _shopError;
final _cards = ScrollController();
+ final _page = ScrollController();
+
+ /// The selected dial's pet edit, shared by the Pet section and the row
+ /// viewer in the left column. One per dial: another selection drops it.
+ PetEditor? _pet;
+
+ /// While a pet is edited on a wide screen, its row viewer sits in the left
+ /// column beside the Pet section: [_besideKey] marks the two columns,
+ /// [_petKey] the Pet section, [_showcaseKey] what the left column holds
+ /// above the viewer, [_viewerKey] the viewer.
+ final _besideKey = GlobalKey();
+ final _petKey = GlobalKey();
+ final _showcaseKey = GlobalKey();
+ final _viewerKey = GlobalKey();
+
+ /// Where those were last laid out; null until measured.
+ _Beside? _beside;
+
+ /// The viewer's top in the columns, kept beside the part of the Pet
+ /// section in view; null until measured (the viewer is hidden till then).
+ final _viewerTop = ValueNotifier<double?>(null);
+
+ /// Room under the columns for a viewer longer than both.
+ double _room = 0;
+
+ /// Room above the Pet section, so it starts level with the viewer when
+ /// the left column holds more above it than the right.
+ double _petGap = 0;
+ bool _measuring = false;
@override
void initState() {
super.initState();
+ _page.addListener(_place);
unawaited(widget.controller.load());
}
+ @override
+ void didUpdateWidget(DevicesScreen oldWidget) {
+ super.didUpdateWidget(oldWidget);
+ if (oldWidget.controller != widget.controller) _dropPet();
+ }
+
@override
void dispose() {
_cards.dispose();
+ _page.dispose();
+ _viewerTop.dispose();
+ _pet?.removeListener(_petChanged);
+ _pet?.dispose();
super.dispose();
}
+ void _petChanged() {
+ if (mounted) setState(() {});
+ }
+
+ /// Ends the current pet edit. Disposed after the frame, once no widget
+ /// listens to it any more.
+ void _dropPet() {
+ final old = _pet;
+ if (old == null) return;
+ _pet = null;
+ old.removeListener(_petChanged);
+ WidgetsBinding.instance.addPostFrameCallback((_) => old.dispose());
+ }
+
+ /// The pet edit for [device], made on first use; null where pets are not
+ /// offered.
+ PetEditor? _petFor(HarnessDevice? device) {
+ final key =
+ device != null && device.local && widget.controller.petRequest != null
+ ? device.key
+ : null;
+ if (_pet?.deviceKey == key) return _pet;
+ _dropPet();
+ if (key == null) return null;
+ return _pet = PetEditor(
+ controller: widget.controller,
+ deviceKey: key,
+ resolveSource: widget.resolvePetSource,
+ loadSheet: widget.loadPetSheet,
+ )..addListener(_petChanged);
+ }
+
+ /// Measures the columns after this frame, once.
+ void _measureSoon() {
+ if (_measuring) return;
+ _measuring = true;
+ WidgetsBinding.instance.addPostFrameCallback((_) {
+ _measuring = false;
+ if (mounted) _measure();
+ });
+ }
+
+ RenderBox? _box(GlobalKey key) {
+ final box = key.currentContext?.findRenderObject();
+ return box is RenderBox && box.attached && box.hasSize ? box : null;
+ }
+
+ void _measure() {
+ final columns = _box(_besideKey);
+ final pet = _box(_petKey);
+ final showcase = _box(_showcaseKey);
+ final viewer = _box(_viewerKey);
+ final page = _page.hasClients
+ ? _page.position.context.storageContext.findRenderObject()
+ : null;
+ if (columns == null ||
+ pet == null ||
+ showcase == null ||
+ viewer == null ||
+ page is! RenderBox) {
+ _beside = null;
+ _viewerTop.value = null;
+ return;
+ }
+ final petTop = pet.localToGlobal(Offset.zero, ancestor: columns).dy;
+ final beside = _Beside(
+ top:
+ columns.localToGlobal(Offset.zero).dy -
+ page.localToGlobal(Offset.zero).dy +
+ _page.offset,
+ height: columns.size.height,
+ petTop: petTop,
+ petBottom: petTop + pet.size.height,
+ showcaseBottom:
+ showcase.localToGlobal(Offset.zero, ancestor: columns).dy +
+ showcase.size.height,
+ viewer: viewer.size.height,
+ );
+ _beside = beside;
+ final gap = math.max(0.0, beside.showcaseBottom + 16 - (petTop - _petGap));
+ final room = math.max(0.0, beside.highest + beside.viewer - beside.height);
+ if ((gap - _petGap).abs() > .5 || (room - _room).abs() > .5) {
+ // Measured again once laid out with them.
+ setState(() {
+ _petGap = gap;
+ _room = room;
+ });
+ return;
+ }
+ _place();
+ }
+
+ /// Keeps the viewer beside the part of the Pet section in view.
+ void _place() {
+ final beside = _beside;
+ if (beside == null || !_page.hasClients) return;
+ final low = beside.highest;
+ final high = math.max(low, beside.petBottom - beside.viewer);
+ _viewerTop.value = (_page.offset - beside.top + _stickyGap).clamp(
+ low,
+ high,
+ );
+ }
+
+ /// The viewer's distance from the top of the window while it follows the
+ /// Pet section.
+ static const _stickyGap = 16.0;
+
Future<void> _shop() async {
var opened = false;
try {
@@ -111,6 +271,29 @@ class _DevicesScreenState extends State<DevicesScreen> {
}
}
+ /// The left column's width on a wide screen.
+ static const _leftColumn = 340.0;
+
+ /// After this frame, measures the viewer's place when it is [beside] the
+ /// Pet section, else forgets it.
+ void _settle(bool beside) {
+ if (beside) return _measureSoon();
+ if (_beside == null &&
+ _room == 0 &&
+ _petGap == 0 &&
+ _viewerTop.value == null) {
+ return;
+ }
+ WidgetsBinding.instance.addPostFrameCallback((_) {
+ if (!mounted) return;
+ _beside = null;
+ _viewerTop.value = null;
+ if (_room != 0 || _petGap != 0) {
+ setState(() => _room = _petGap = 0);
+ }
+ });
+ }
+
Future<void> _setup({HarnessDevice? editing}) async {
final key = await showDeviceSetup(
context,
@@ -139,9 +322,11 @@ class _DevicesScreenState extends State<DevicesScreen> {
devices.where((d) => d.status.attached).firstOrNull ??
devices.firstOrNull;
_selectedKey = selected?.key;
+ final pet = _petFor(selected);
final pad = bounds.maxWidth < 640 ? 20.0 : 40.0;
return SingleChildScrollView(
key: const PageStorageKey('devices-page'),
+ controller: _page,
padding: EdgeInsets.fromLTRB(pad, 36, pad, 40),
child: Center(
child: ConstrainedBox(
@@ -320,15 +505,24 @@ class _DevicesScreenState extends State<DevicesScreen> {
const SizedBox(height: 24),
LayoutBuilder(
builder: (context, constraints) {
+ final wide =
+ constraints.maxWidth >= 850 &&
+ MediaQuery.textScalerOf(context).scale(1) <=
+ 1.5;
+ final beside = wide && pet != null && pet.editing;
final showcase = _DeviceShowcase(device: selected);
final settings = DeviceSettingsPanel(
key: ValueKey(selected.key),
device: selected,
controller: widget.controller,
+ petEditor: pet,
+ petViewerBeside: beside,
+ petKey: _petKey,
+ petGap: beside ? _petGap : 0,
+ pickPetFile: widget.pickPetFile,
);
- if (constraints.maxWidth < 850 ||
- MediaQuery.textScalerOf(context).scale(1) >
- 1.5) {
+ if (!wide) {
+ _settle(false);
return Column(
crossAxisAlignment: CrossAxisAlignment.stretch,
children: [
@@ -338,14 +532,56 @@ class _DevicesScreenState extends State<DevicesScreen> {
],
);
}
- return Row(
+ final columns = Row(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
- SizedBox(width: 340, child: showcase),
+ SizedBox(
+ width: _leftColumn,
+ child: KeyedSubtree(
+ key: _showcaseKey,
+ child: showcase,
+ ),
+ ),
const SizedBox(width: 36),
Expanded(child: settings),
],
);
+ _settle(beside);
+ if (!beside) return columns;
+ return Padding(
+ padding: EdgeInsets.only(bottom: _room),
+ child: Stack(
+ key: _besideKey,
+ clipBehavior: Clip.none,
+ children: [
+ columns,
+ ValueListenableBuilder<double?>(
+ valueListenable: _viewerTop,
+ builder: (context, top, child) =>
+ Positioned(
+ left: 0,
+ width: _leftColumn,
+ top: top ?? 0,
+ child: Opacity(
+ opacity: top == null ? 0 : 1,
+ child: child,
+ ),
+ ),
+ child: KeyedSubtree(
+ key: _viewerKey,
+ child: PetRowViewer(
+ key: const ValueKey(
+ 'devices-pet-viewer',
+ ),
+ editor: pet,
+ maxViewer: (bounds.maxHeight - 330)
+ .clamp(160.0, 300.0),
+ ),
+ ),
+ ),
+ ],
+ ),
+ );
},
),
],
@@ -511,6 +747,19 @@ class _DeviceShowcase extends StatelessWidget {
),
),
const SizedBox(height: 16),
+ _DeviceFacts(device: device),
+ ],
+ );
+}
+
+/// The dial's firmware, display and hardware address.
+class _DeviceFacts extends StatelessWidget {
+ const _DeviceFacts({required this.device});
+ final HarnessDevice device;
+ @override
+ Widget build(BuildContext context) => Column(
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [
Text(
[
if (device.status.fw != null) 'Firmware ${device.status.fw}',
@@ -527,6 +776,25 @@ class _DeviceShowcase extends StatelessWidget {
);
}
+/// Where the two columns, the Pet section and the viewer were laid out:
+/// [top] is the columns' place in the page, the rest is in the columns.
+@immutable
+class _Beside {
+ const _Beside({
+ required this.top,
+ required this.height,
+ required this.petTop,
+ required this.petBottom,
+ required this.showcaseBottom,
+ required this.viewer,
+ });
+ final double top, height, petTop, petBottom, showcaseBottom, viewer;
+
+ /// The highest the viewer sits: level with the Pet section, below what the
+ /// left column holds above it.
+ double get highest => math.max(petTop, showcaseBottom + 16);
+}
+
class _EmptyDevices extends StatelessWidget {
const _EmptyDevices({
required this.onAdd,
diff --git a/desktop/lib/devices/loose_sheet.dart b/desktop/lib/devices/loose_sheet.dart
new file mode 100644
index 000000000..72367d390
--- /dev/null
+++ b/desktop/lib/devices/loose_sheet.dart
@@ -0,0 +1,505 @@
+import 'dart:io';
+import 'dart:isolate';
+import 'dart:math' as math;
+import 'dart:typed_data';
+import 'dart:ui' as ui;
+
+import 'package:path/path.dart' as p;
+
+import 'pet_source.dart';
+
+/// Rows of a petdex sheet, top to bottom. A loose sheet's row i lands on
+/// `petRows[i]`.
+const petRows = [
+ 'idle',
+ 'runningRight',
+ 'runningLeft',
+ 'waving',
+ 'jumping',
+ 'failed',
+ 'waiting',
+ 'running',
+ 'review',
+];
+
+/// The dial states a sheet row can be chosen for, in the order the app lists
+/// them.
+const petStates = ['rest', 'working', 'listening', 'sending', 'asking'];
+
+const cellWidth = 192, cellHeight = 208, sheetCols = 8, sheetRows = 9;
+const sheetWidth = cellWidth * sheetCols, sheetHeight = cellHeight * sheetRows;
+
+const _maxBytes = 8 * 1024 * 1024;
+const _maxSide = 4096;
+const _margin = 4;
+
+const noFramesMessage =
+ 'Couldn’t find frames on this sheet — it needs a plain or checkered '
+ 'background with gaps between frames';
+
+/// One frame of a loose sheet: its opaque box in the source image, right and
+/// bottom exclusive.
+class LooseFrame {
+ const LooseFrame(this.left, this.top, this.right, this.bottom);
+ final int left, top, right, bottom;
+ int get width => right - left;
+ int get height => bottom - top;
+ @override
+ String toString() => 'LooseFrame($left, $top, $right, $bottom)';
+}
+
+/// (width, height) from a PNG's IHDR or a JPEG's SOF marker, without
+/// decoding; null when [b] is neither, or is cut short.
+(int, int)? imageSize(Uint8List b) {
+ int be(int at) => (b[at] << 8) | b[at + 1];
+ const png = [0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A];
+ var isPng = b.length >= 24;
+ for (var i = 0; isPng && i < png.length; i++) {
+ isPng = b[i] == png[i];
+ }
+ if (isPng) {
+ if (String.fromCharCodes(b.sublist(12, 16)) != 'IHDR') return null;
+ return ((be(16) << 16) | be(18), (be(20) << 16) | be(22));
+ }
+ if (b.length < 4 || b[0] != 0xFF || b[1] != 0xD8) return null;
+ var i = 2;
+ while (i + 3 < b.length) {
+ if (b[i] != 0xFF) return null;
+ final marker = b[i + 1];
+ if (marker == 0xFF) {
+ i++;
+ continue;
+ }
+ if (marker == 0x01 || (marker >= 0xD0 && marker <= 0xD9)) {
+ i += 2;
+ continue;
+ }
+ final length = be(i + 2);
+ final sof =
+ marker >= 0xC0 &&
+ marker <= 0xCF &&
+ marker != 0xC4 &&
+ marker != 0xC8 &&
+ marker != 0xCC;
+ if (sof) {
+ if (i + 9 > b.length) return null;
+ return (be(i + 7), be(i + 5));
+ }
+ if (length < 2) return null;
+ i += 2 + length;
+ }
+ return null;
+}
+
+/// Whether the image already carries a cut-out: a meaningful share of its
+/// pixels (1 %) are mostly transparent.
+bool hasRealAlpha(Uint8List rgba) {
+ final pixels = rgba.length ~/ 4;
+ var clear = 0;
+ for (var i = 3; i < rgba.length; i += 4) {
+ if (rgba[i] < 128) clear++;
+ }
+ return clear * 100 >= pixels;
+}
+
+/// Makes the background transparent in place: a flood fill from every border
+/// pixel through background-ish pixels, so the character's outline stops it
+/// and highlights inside survive. Background-ish is a light grey/white
+/// (a checkerboard baked into the pixels) when most of the border is that,
+/// otherwise close to the border's dominant colour. False when the border has
+/// no clear background, so nothing was changed.
+bool clearBackground(Uint8List rgba, int width, int height) {
+ final border = <int>[
+ for (var x = 0; x < width; x++) ...[x, (height - 1) * width + x],
+ for (var y = 1; y < height - 1; y++) ...[y * width, y * width + width - 1],
+ ];
+ bool checker(int i) {
+ final r = rgba[i * 4], g = rgba[i * 4 + 1], b = rgba[i * 4 + 2];
+ final hi = math.max(r, math.max(g, b)), lo = math.min(r, math.min(g, b));
+ return hi - lo <= 28 && lo >= 140;
+ }
+
+ bool Function(int) background;
+ if (border.where(checker).length * 10 >= border.length * 6) {
+ background = checker;
+ } else {
+ final buckets = <int, int>{};
+ int bucket(int i) =>
+ (rgba[i * 4] >> 3) << 10 |
+ (rgba[i * 4 + 1] >> 3) << 5 |
+ rgba[i * 4 + 2] >> 3;
+ for (final i in border) {
+ buckets.update(bucket(i), (n) => n + 1, ifAbsent: () => 1);
+ }
+ final top = buckets.entries.reduce((a, b) => a.value >= b.value ? a : b);
+ if (top.value * 2 < border.length) return false;
+ var r = 0, g = 0, b = 0;
+ for (final i in border) {
+ if (bucket(i) != top.key) continue;
+ r += rgba[i * 4];
+ g += rgba[i * 4 + 1];
+ b += rgba[i * 4 + 2];
+ }
+ r ~/= top.value;
+ g ~/= top.value;
+ b ~/= top.value;
+ background = (i) =>
+ (rgba[i * 4] - r).abs() <= 24 &&
+ (rgba[i * 4 + 1] - g).abs() <= 24 &&
+ (rgba[i * 4 + 2] - b).abs() <= 24;
+ }
+ final seen = Uint8List(width * height);
+ final queue = Int32List(width * height);
+ var head = 0, tail = 0;
+ void visit(int i) {
+ if (seen[i] != 0) return;
+ seen[i] = 1;
+ if (!background(i)) return;
+ queue[tail++] = i;
+ }
+
+ border.forEach(visit);
+ while (head < tail) {
+ final i = queue[head++];
+ rgba[i * 4 + 3] = 0;
+ final x = i % width;
+ if (x > 0) visit(i - 1);
+ if (x < width - 1) visit(i + 1);
+ if (i >= width) visit(i - width);
+ if (i < (height - 1) * width) visit(i + width);
+ }
+ return true;
+}
+
+/// Runs of at least [minRun] indices whose count is over [over].
+List<(int, int)> _runs(List<int> counts, int over, int minRun) {
+ final runs = <(int, int)>[];
+ int? start;
+ for (var i = 0; i <= counts.length; i++) {
+ final on = i < counts.length && counts[i] > over;
+ if (on) {
+ start ??= i;
+ } else if (start != null) {
+ if (i - start >= minRun) runs.add((start, i));
+ start = null;
+ }
+ }
+ return runs;
+}
+
+/// The frames of a sheet whose background is already transparent, row by row:
+/// row bands are runs of y with more than two opaque pixels (at least 20 px),
+/// frames are runs of x with more than one opaque pixel inside a band (at
+/// least 15 px), each trimmed to its opaque box. At most 9 rows of 8 frames.
+List<List<LooseFrame>> findFrames(Uint8List rgba, int width, int height) {
+ bool opaque(int x, int y) => rgba[(y * width + x) * 4 + 3] >= 128;
+ final perRow = List<int>.filled(height, 0);
+ for (var y = 0; y < height; y++) {
+ var n = 0;
+ for (var x = 0; x < width; x++) {
+ if (opaque(x, y)) n++;
+ }
+ perRow[y] = n;
+ }
+ final rows = <List<LooseFrame>>[];
+ for (final (y0, y1) in _runs(perRow, 2, 20)) {
+ final perCol = List<int>.filled(width, 0);
+ for (var y = y0; y < y1; y++) {
+ for (var x = 0; x < width; x++) {
+ if (opaque(x, y)) perCol[x]++;
+ }
+ }
+ final frames = <LooseFrame>[];
+ for (final (x0, x1) in _runs(perCol, 1, 15)) {
+ var top = y1, bottom = y0, left = x1, right = x0;
+ for (var y = y0; y < y1; y++) {
+ for (var x = x0; x < x1; x++) {
+ if (!opaque(x, y)) continue;
+ top = math.min(top, y);
+ bottom = math.max(bottom, y + 1);
+ left = math.min(left, x);
+ right = math.max(right, x + 1);
+ }
+ }
+ if (bottom > top) frames.add(LooseFrame(left, top, right, bottom));
+ if (frames.length == sheetCols) break;
+ }
+ if (frames.isNotEmpty) rows.add(frames);
+ if (rows.length == sheetRows) break;
+ }
+ return rows;
+}
+
+/// The one scale for the whole sheet: fits its widest and its tallest frame
+/// into a cell less a margin, so the character fills the cell and keeps one
+/// size from row to row. An upscale of 2x or more is a whole number (pixel
+/// art keeps hard pixels).
+///
+/// Each frame is measured on its own, not its row's band: a jump's height
+/// above the ground is room the row needs, which [composeSheet] fits by
+/// lowering the jump, not by shrinking the character.
+double sheetScale(List<List<LooseFrame>> rows) {
+ var maxW = 1, maxH = 1;
+ for (final row in rows) {
+ for (final f in row) {
+ maxW = math.max(maxW, f.width);
+ maxH = math.max(maxH, f.height);
+ }
+ }
+ final fit = math.min(
+ (cellWidth - 2 * _margin) / maxW,
+ (cellHeight - 2 * _margin) / maxH,
+ );
+ return fit >= 2 ? fit.floorToDouble() : fit;
+}
+
+/// How much of each frame's lift above its row's baseline survives at scale
+/// [s]: all of it when the row fits a cell less its margins, else the share
+/// that keeps every lifted frame inside, so a jump still leaves the ground.
+double liftShare(List<LooseFrame> row, double s) {
+ const room = cellHeight - 2 * _margin;
+ final rowBottom = row.map((f) => f.bottom).reduce(math.max);
+ var share = 1.0;
+ for (final f in row) {
+ final lift = (rowBottom - f.bottom) * s;
+ final height = f.height * s;
+ if (lift > 0 && lift + height > room) {
+ share = math.min(share, math.max(0, room - height) / lift);
+ }
+ }
+ return share;
+}
+
+/// A 1536 x 1872 straight RGBA petdex sheet: loose row i in grid row i, frame
+/// j in cell j, all scaled by [sheetScale], centred across the cell and
+/// bottom-aligned on one baseline (a frame keeps its lift within its row,
+/// lowered by [liftShare] when the row is taller than a cell).
+Uint8List composeSheet(Uint8List rgba, int width, List<List<LooseFrame>> rows) {
+ final out = Uint8List(sheetWidth * sheetHeight * 4);
+ final s = sheetScale(rows);
+ for (final (r, row) in rows.indexed) {
+ final rowBottom = row.map((f) => f.bottom).reduce(math.max);
+ final share = liftShare(row, s);
+ for (final (c, f) in row.indexed) {
+ final dw = math.min(cellWidth, math.max(1, (f.width * s).round()));
+ final dh = math.min(cellHeight, math.max(1, (f.height * s).round()));
+ final lift = ((rowBottom - f.bottom) * s * share).round();
+ final ox = c * cellWidth + (cellWidth - dw) ~/ 2;
+ final oy = math.max(
+ r * cellHeight,
+ (r + 1) * cellHeight - _margin - lift - dh,
+ );
+ for (var dy = 0; dy < dh && oy + dy < (r + 1) * cellHeight; dy++) {
+ final sy0 = f.top + (dy * f.height) ~/ dh;
+ final sy1 = math.max(sy0 + 1, f.top + ((dy + 1) * f.height) ~/ dh);
+ for (var dx = 0; dx < dw; dx++) {
+ final sx0 = f.left + (dx * f.width) ~/ dw;
+ final sx1 = math.max(sx0 + 1, f.left + ((dx + 1) * f.width) ~/ dw);
+ // A box filter over premultiplied colour (one pixel when upscaling).
+ var a = 0, rr = 0, gg = 0, bb = 0, n = 0;
+ for (var sy = sy0; sy < sy1; sy++) {
+ for (var sx = sx0; sx < sx1; sx++) {
+ final i = (sy * width + sx) * 4;
+ final al = rgba[i + 3];
+ a += al;
+ rr += rgba[i] * al;
+ gg += rgba[i + 1] * al;
+ bb += rgba[i + 2] * al;
+ n++;
+ }
+ }
+ if (a == 0) continue;
+ final o = ((oy + dy) * sheetWidth + ox + dx) * 4;
+ out[o] = rr ~/ a;
+ out[o + 1] = gg ~/ a;
+ out[o + 2] = bb ~/ a;
+ out[o + 3] = math.max(1, a ~/ n);
+ }
+ }
+ }
+ }
+ return out;
+}
+
+/// How much a row's silhouette changes from frame to frame: each frame's
+/// occupancy on a 16 x 16 grid over the row's box (centred, bottom-aligned),
+/// the mean share of cells that differ between neighbours.
+double motionScore(Uint8List rgba, int width, List<LooseFrame> row) {
+ if (row.length < 2) return 0;
+ const n = 16;
+ final top = row.map((f) => f.top).reduce(math.min);
+ final bottom = row.map((f) => f.bottom).reduce(math.max);
+ final boxW = row.map((f) => f.width).reduce(math.max);
+ final boxH = bottom - top;
+ List<bool> grid(LooseFrame f) {
+ final cells = List<bool>.filled(n * n, false);
+ final left = f.left - (boxW - f.width) ~/ 2;
+ for (var gy = 0; gy < n; gy++) {
+ for (var gx = 0; gx < n; gx++) {
+ final x = left + ((gx + 0.5) * boxW / n).floor();
+ final y = top + ((gy + 0.5) * boxH / n).floor();
+ if (x < f.left || x >= f.right || y < f.top || y >= f.bottom) continue;
+ cells[gy * n + gx] = rgba[(y * width + x) * 4 + 3] >= 128;
+ }
+ }
+ return cells;
+ }
+
+ final grids = row.map(grid).toList();
+ var diff = 0.0;
+ for (var i = 1; i < grids.length; i++) {
+ var d = 0;
+ for (var k = 0; k < n * n; k++) {
+ if (grids[i][k] != grids[i - 1][k]) d++;
+ }
+ diff += d / (n * n);
+ }
+ return diff / (grids.length - 1);
+}
+
+/// A first guess at which row plays which state: the first row rests, listens
+/// and sends, the last asks, and working is the row that moves the most
+/// (other than the first when there are two rows or more, and the last when
+/// there are three or more).
+Map<String, String> guessRows(
+ Uint8List rgba,
+ int width,
+ List<List<LooseFrame>> rows,
+) {
+ final n = rows.length;
+ var working = 0;
+ if (n >= 2) {
+ final candidates = [for (var i = 1; i < (n >= 3 ? n - 1 : n); i++) i];
+ var best = -1.0;
+ for (final i in candidates) {
+ final score = motionScore(rgba, width, rows[i]);
+ if (score > best) {
+ best = score;
+ working = i;
+ }
+ }
+ }
+ return {
+ 'rest': petRows[0],
+ 'working': petRows[working],
+ 'listening': petRows[0],
+ 'sending': petRows[0],
+ 'asking': petRows[n - 1],
+ };
+}
+
+/// What the background isolate hands back: the composed sheet and the guess.
+typedef _Composed = ({
+ Uint8List? sheet,
+ Map<String, String> rows,
+ String? error,
+});
+
+_Composed _process(Uint8List rgba, int width, int height) {
+ if (!hasRealAlpha(rgba) && !clearBackground(rgba, width, height)) {
+ return (sheet: null, rows: const {}, error: noFramesMessage);
+ }
+ final frames = findFrames(rgba, width, height);
+ if (frames.isEmpty) {
+ return (sheet: null, rows: const {}, error: noFramesMessage);
+ }
+ return (
+ sheet: composeSheet(rgba, width, frames),
+ rows: guessRows(rgba, width, frames),
+ error: null,
+ );
+}
+
+/// Turns any PNG or JPEG sprite sheet into a petdex sheet: decodes it (size
+/// read from the header first), removes a plain or checkered background,
+/// finds the frames and lays them on the 8 x 9 grid. The PNG goes to a temp
+/// folder that cleanup removes.
+Future<PetSource> looseSheetSource(String path, {required String name}) async {
+ final file = File(path);
+ if (!file.existsSync()) throw PetSourceError('That file can’t be read');
+ if (file.lengthSync() > _maxBytes) {
+ throw PetSourceError('The image is larger than 8 MB');
+ }
+ final bytes = await file.readAsBytes();
+ final size = imageSize(bytes);
+ if (size == null) throw PetSourceError('That isn’t a PNG or JPEG image');
+ if (size.$1 > _maxSide || size.$2 > _maxSide || size.$1 < 1 || size.$2 < 1) {
+ throw PetSourceError('The image is larger than 4096 × 4096');
+ }
+ final Uint8List rgba;
+ final int width, height;
+ try {
+ final codec = await ui.instantiateImageCodec(bytes);
+ try {
+ final image = (await codec.getNextFrame()).image;
+ try {
+ width = image.width;
+ height = image.height;
+ if (width > _maxSide || height > _maxSide) {
+ throw StateError('too large');
+ }
+ final data = await image.toByteData(
+ format: ui.ImageByteFormat.rawStraightRgba,
+ );
+ if (data == null) throw StateError('no pixels');
+ rgba = data.buffer.asUint8List(data.offsetInBytes, data.lengthInBytes);
+ } finally {
+ image.dispose();
+ }
+ } finally {
+ codec.dispose();
+ }
+ } catch (_) {
+ throw PetSourceError('The image can’t be decoded');
+ }
+ final composed = await Isolate.run(() => _process(rgba, width, height));
+ if (composed.error case final error?) throw PetSourceError(error);
+ final png = await encodePng(composed.sheet!, sheetWidth, sheetHeight);
+ final temp = await Directory.systemTemp.createTemp('harness-pet-');
+ final out = File(p.join(temp.path, 'sheet.png'));
+ await out.writeAsBytes(png);
+ return PetSource(
+ pngPath: out.path,
+ name: name,
+ loose: true,
+ defaultRows: composed.rows,
+ cleanup: () async {
+ if (temp.existsSync()) await temp.delete(recursive: true);
+ },
+ );
+}
+
+/// [rgba] (straight alpha) as a PNG.
+Future<Uint8List> encodePng(Uint8List rgba, int width, int height) async {
+ // A raw image descriptor takes premultiplied pixels.
+ final premultiplied = Uint8List.fromList(rgba);
+ for (var i = 0; i < premultiplied.length; i += 4) {
+ final a = premultiplied[i + 3];
+ if (a == 255) continue;
+ for (var k = 0; k < 3; k++) {
+ premultiplied[i + k] = (premultiplied[i + k] * a + 127) ~/ 255;
+ }
+ }
+ final buffer = await ui.ImmutableBuffer.fromUint8List(premultiplied);
+ final descriptor = ui.ImageDescriptor.raw(
+ buffer,
+ width: width,
+ height: height,
+ pixelFormat: ui.PixelFormat.rgba8888,
+ );
+ final codec = await descriptor.instantiateCodec();
+ try {
+ final image = (await codec.getNextFrame()).image;
+ try {
+ final data = await image.toByteData(format: ui.ImageByteFormat.png);
+ if (data == null) throw PetSourceError('The sheet can’t be encoded');
+ return data.buffer.asUint8List(data.offsetInBytes, data.lengthInBytes);
+ } finally {
+ image.dispose();
+ }
+ } finally {
+ codec.dispose();
+ descriptor.dispose();
+ buffer.dispose();
+ }
+}
diff --git a/desktop/lib/devices/pet_editor.dart b/desktop/lib/devices/pet_editor.dart
new file mode 100644
index 000000000..832422cc5
--- /dev/null
+++ b/desktop/lib/devices/pet_editor.dart
@@ -0,0 +1,473 @@
+import 'dart:async';
+import 'dart:io';
+import 'dart:isolate';
+import 'dart:math' as math;
+import 'dart:ui' as ui;
+
+import 'package:flutter/foundation.dart';
+import 'package:flutter/painting.dart' show Rect;
+import 'package:path/path.dart' as p;
+
+import 'devices_controller.dart';
+import 'loose_sheet.dart';
+import 'pet_source.dart';
+
+/// The dial states a row can be picked for, and their labels.
+const petStateLabels = {
+ 'rest': 'Rest',
+ 'working': 'Working',
+ 'listening': 'Listening',
+ 'sending': 'Sending',
+ 'asking': 'Asking',
+};
+
+/// How long the row picker waits for more changes before asking again.
+const petRowsDebounce = Duration(milliseconds: 250);
+
+/// How long the row viewer shows each frame of the sheet.
+const petViewerStep = Duration(milliseconds: 120);
+
+/// A sheet decoded for the row viewer, with where each row's art sits in its
+/// cells.
+class PetSheet {
+ PetSheet(this.image, {this.crops = const []});
+ final ui.Image image;
+
+ /// Per sheet row, the box (in cell coordinates) that holds every frame of
+ /// it, padded; see [sheetRowCrops]. Missing or null shows the whole cell.
+ final List<Rect?> crops;
+
+ /// Row [row]'s box, or null for the whole cell.
+ Rect? crop(int row) => row >= 0 && row < crops.length ? crops[row] : null;
+
+ void dispose() => image.dispose();
+}
+
+/// Each row's art box on a straight RGBA sheet of 8 x 9 cells: the union of
+/// the opaque pixels (alpha 128 or more) over all of the row's cells, in cell
+/// coordinates, grown by [pad] (a share of its larger side) and kept inside
+/// the cell. One box per row, so a row's frames keep their place against
+/// each other when played. Null for an empty row.
+List<Rect?> sheetRowCrops(
+ Uint8List rgba,
+ int width,
+ int height, {
+ double pad = .06,
+}) {
+ final cw = width ~/ sheetCols, ch = height ~/ sheetRows;
+ final crops = <Rect?>[];
+ for (var r = 0; r < sheetRows; r++) {
+ var left = cw, top = ch, right = -1, bottom = -1;
+ for (var y = 0; y < ch; y++) {
+ final row = (r * ch + y) * width;
+ for (var x = 0; x < width; x++) {
+ if (rgba[(row + x) * 4 + 3] < 128) continue;
+ final cx = x % cw;
+ if (cx < left) left = cx;
+ if (cx > right) right = cx;
+ if (y < top) top = y;
+ if (y > bottom) bottom = y;
+ }
+ }
+ if (right < 0) {
+ crops.add(null);
+ continue;
+ }
+ final box = Rect.fromLTRB(
+ left.toDouble(),
+ top.toDouble(),
+ right + 1.0,
+ bottom + 1.0,
+ );
+ final grow = pad * math.max(box.width, box.height);
+ crops.add(
+ box
+ .inflate(grow)
+ .intersect(Rect.fromLTWH(0, 0, cw.toDouble(), ch.toDouble())),
+ );
+ }
+ return crops;
+}
+
+/// Reads the sheet the daemon converts, for the row viewer's full-resolution
+/// frames, and finds each row's art box; null when it cannot be read or is
+/// not 8 x 9 cells.
+Future<PetSheet?> decodePetSheet(String path) async {
+ ui.Image? image;
+ try {
+ final file = File(path);
+ if (await file.length() > 32 * 1024 * 1024) return null;
+ final codec = await ui.instantiateImageCodec(await file.readAsBytes());
+ final frame = await codec.getNextFrame();
+ codec.dispose();
+ image = frame.image;
+ final w = image.width, h = image.height;
+ if (w % sheetCols != 0 || h % sheetRows != 0) {
+ image.dispose();
+ return null;
+ }
+ var crops = const <Rect?>[];
+ final data = await image.toByteData(
+ format: ui.ImageByteFormat.rawStraightRgba,
+ );
+ if (data != null) {
+ final rgba = data.buffer.asUint8List(
+ data.offsetInBytes,
+ data.lengthInBytes,
+ );
+ crops = await Isolate.run(() => sheetRowCrops(rgba, w, h));
+ }
+ return PetSheet(image, crops: crops);
+ } catch (_) {
+ image?.dispose();
+ return null;
+ }
+}
+
+/// Which frame of the viewed row the row viewer shows, and whether it plays.
+/// Apart from [PetEditor] so a frame step repaints only the viewer.
+class PetPlayback extends ChangeNotifier {
+ Timer? _timer;
+ int _frames = 0, _index = 0;
+ bool _disposed = false;
+
+ int get frames => _frames;
+ int get index => _frames == 0 ? 0 : _index % _frames;
+ bool get playing => _timer != null;
+
+ /// Starts over on a row of [frames] frames, playing.
+ void restart(int frames) {
+ _stop();
+ _frames = frames;
+ _index = 0;
+ play();
+ notifyListeners();
+ }
+
+ void play() {
+ if (_disposed || _timer != null || _frames < 2) return;
+ _timer = Timer.periodic(petViewerStep, (_) {
+ _index = (_index + 1) % _frames;
+ notifyListeners();
+ });
+ notifyListeners();
+ }
+
+ void pause() {
+ if (_timer == null) return;
+ _stop();
+ notifyListeners();
+ }
+
+ void toggle() => playing ? pause() : play();
+
+ /// Pauses on frame [i].
+ void hold(int i) {
+ _stop();
+ _index = i;
+ notifyListeners();
+ }
+
+ /// Stops without a frame (nothing to view).
+ void clear() {
+ _stop();
+ _frames = 0;
+ _index = 0;
+ }
+
+ void _stop() {
+ _timer?.cancel();
+ _timer = null;
+ }
+
+ @override
+ void dispose() {
+ _disposed = true;
+ _stop();
+ super.dispose();
+ }
+}
+
+/// One custom-pet edit for one dial: the sheet the user picked, the daemon's
+/// preview of it, which row plays each state, the row being viewed and its
+/// playback. Shared by the Pet section and the row viewer beside it, so the
+/// two columns of the devices screen show the same edit. Owns the sheet's
+/// temp files and decoded image until the edit is applied, cancelled,
+/// replaced or disposed.
+class PetEditor extends ChangeNotifier {
+ PetEditor({
+ required this.controller,
+ required this.deviceKey,
+ Future<PetSource> Function(String path)? resolveSource,
+ Future<PetSheet?> Function(String path)? loadSheet,
+ }) : resolveSource = resolveSource ?? resolvePetSource,
+ loadSheet = loadSheet ?? decodePetSheet;
+
+ final DevicesController controller;
+ final String deviceKey;
+
+ /// [resolvePetSource], or a test's.
+ final Future<PetSource> Function(String path) resolveSource;
+
+ /// [decodePetSheet], or a test's.
+ final Future<PetSheet?> Function(String path) loadSheet;
+
+ final playback = PetPlayback();
+
+ PetPreview? _preview;
+ String? _error;
+ bool _busy = false, _disposed = false;
+
+ /// The sheet being previewed, kept until it is applied or dropped so a new
+ /// row choice can be converted again.
+ PetSource? _source;
+
+ /// [_source]'s sheet, decoded for the row viewer; null until it is read,
+ /// or when it can't be (the viewer then shows the daemon's strips).
+ PetSheet? _sheet;
+
+ /// The row (by petdex row name) the user has chosen for each state.
+ Map<String, String> _rows = const {};
+
+ /// Whether [_preview] matches [_rows]; false while a new preview is pending
+ /// or after it failed, so Apply never sends an outdated pet.
+ bool _current = true;
+ Timer? _debounce;
+
+ /// Bumped by every preview request; a reply for an older one is ignored.
+ int _seq = 0;
+
+ /// The sheet row in the viewer; starts on the row Working plays.
+ String? _viewed;
+
+ PetPreview? get preview => _preview;
+ String? get error => _error;
+ bool get busy => _busy;
+ bool get current => _current;
+ PetSource? get source => _source;
+ PetSheet? get sheet => _sheet;
+ Map<String, String> get rows => _rows;
+ bool get loose => _source?.loose ?? false;
+
+ /// The edited pet's name: its own, else its sheet's file name.
+ String? get name => switch (_source) {
+ null => null,
+ final source => source.name ?? p.basenameWithoutExtension(source.pngPath),
+ };
+
+ /// True while a preview waits to be applied or cancelled.
+ bool get editing => _preview != null;
+
+ /// The sheet row in the viewer, or null when the preview lists none (an
+ /// older daemon).
+ PetSheetRow? get viewedRow {
+ final rows = _preview?.sheetRows ?? const <PetSheetRow>[];
+ if (rows.isEmpty) return null;
+ for (final row in rows) {
+ if (row.row == _viewed) return row;
+ }
+ final working = _rows['working'];
+ return rows.firstWhere((r) => r.row == working, orElse: () => rows.first);
+ }
+
+ /// The states [row] plays.
+ List<String> statesOf(String row) => [
+ for (final state in petStateLabels.keys)
+ if (_rows[state] == row) state,
+ ];
+
+ /// A row's label: its petdex name ("Running right"), or its place on a
+ /// loose sheet ("Row 3").
+ String rowLabel(String row) {
+ if (loose) {
+ final i = petRows.indexOf(row);
+ return i < 0 ? row : 'Row ${i + 1}';
+ }
+ final words = row.replaceAllMapped(
+ RegExp('[A-Z]'),
+ (m) => ' ${m[0]!.toLowerCase()}',
+ );
+ return words.isEmpty ? row : words[0].toUpperCase() + words.substring(1);
+ }
+
+ void _notify() {
+ if (!_disposed) notifyListeners();
+ }
+
+ /// Restarts the viewer's playback when the viewed row is another one.
+ void _syncPlayback({bool force = false}) {
+ final row = viewedRow;
+ if (row == null) {
+ playback.clear();
+ _viewed = null;
+ return;
+ }
+ if (force || row.row != _viewed || playback.frames != row.frames) {
+ _viewed = row.row;
+ playback.restart(row.frames);
+ }
+ }
+
+ /// Forgets the previewed sheet and removes what it left in the temp folder.
+ void _drop() {
+ _debounce?.cancel();
+ _seq++;
+ final source = _source;
+ _source = null;
+ _preview = null;
+ _sheet?.dispose();
+ _sheet = null;
+ _rows = const {};
+ _current = true;
+ _viewed = null;
+ playback.clear();
+ unawaited(source?.cleanup());
+ }
+
+ /// Decodes [source]'s sheet for the row viewer, unless it was dropped
+ /// meanwhile.
+ Future<void> _loadSheet(PetSource source) async {
+ final image = await loadSheet(source.pngPath);
+ if (_disposed || !identical(source, _source)) {
+ image?.dispose();
+ return;
+ }
+ _sheet = image;
+ _notify();
+ }
+
+ /// Converts what the user picked at [path] and previews it, dropping any
+ /// edit in progress.
+ Future<void> use(String? path) async {
+ if (path == null || _busy || _disposed) return;
+ _drop();
+ _busy = true;
+ _error = null;
+ _notify();
+ final seq = _seq;
+ PetSource? source;
+ PetPreview? preview;
+ String? error;
+ try {
+ source = await resolveSource(path);
+ preview = await controller.previewPet(
+ deviceKey,
+ source.pngPath,
+ name: source.name,
+ // A petdex sheet starts on the daemon's own mapping; a loose one on
+ // the app's guess, since its rows are not named for what they hold.
+ rows: source.loose ? source.defaultRows : null,
+ );
+ if (preview == null) error = controller.petError(deviceKey);
+ } on PetSourceError catch (e) {
+ error = e.message;
+ }
+ if (_disposed || seq != _seq) {
+ await source?.cleanup();
+ return;
+ }
+ if (preview == null) await source?.cleanup();
+ _busy = false;
+ _preview = preview;
+ _error = error;
+ if (preview != null) {
+ _source = source;
+ _rows = {...?source?.defaultRows, ...preview.rows};
+ _syncPlayback(force: true);
+ }
+ _notify();
+ if (preview != null && preview.sheetRows.isNotEmpty) {
+ unawaited(_loadSheet(source!));
+ }
+ }
+
+ /// Shows [row] in the viewer.
+ void view(String row) {
+ if (_preview == null || row == _viewed) return;
+ _viewed = row;
+ _syncPlayback(force: true);
+ _notify();
+ }
+
+ /// The user picked [row] for [state]: asks for a new preview once the
+ /// choices settle.
+ void choose(String state, String row) {
+ if (_preview == null || _rows[state] == row) return;
+ _rows = {..._rows, state: row};
+ _current = false;
+ _notify();
+ _debounce?.cancel();
+ _debounce = Timer(petRowsDebounce, _refresh);
+ }
+
+ Future<void> _refresh() async {
+ final source = _source;
+ if (source == null || _disposed) return;
+ final seq = ++_seq;
+ final rows = Map.of(_rows);
+ final preview = await controller.previewPet(
+ deviceKey,
+ source.pngPath,
+ name: source.name,
+ rows: rows,
+ );
+ if (_disposed || seq != _seq || !identical(source, _source)) return;
+ if (preview == null) {
+ _error = controller.petError(deviceKey);
+ } else {
+ _preview = preview;
+ _rows = {...rows, ...preview.rows};
+ _current = true;
+ _error = null;
+ _syncPlayback();
+ }
+ _notify();
+ }
+
+ /// Sends the previewed pet to every agent; the edit ends when it is taken.
+ Future<void> apply() async {
+ final preview = _preview;
+ if (preview == null || _busy || !_current) return;
+ _busy = true;
+ _error = null;
+ _notify();
+ final message = await controller.applyPet(deviceKey, preview.id);
+ if (_disposed) return;
+ _busy = false;
+ _error = message;
+ if (message == null) _drop();
+ _notify();
+ }
+
+ /// Back to the built-in pet; drops any edit.
+ Future<void> reset() async {
+ _busy = true;
+ _notify();
+ await controller.resetPet(deviceKey);
+ if (_disposed) return;
+ _busy = false;
+ _error = null;
+ _drop();
+ _notify();
+ }
+
+ /// Ends the edit without applying it.
+ void cancel() {
+ if (_busy) return;
+ _drop();
+ _notify();
+ }
+
+ @override
+ void dispose() {
+ _disposed = true;
+ _debounce?.cancel();
+ _sheet?.dispose();
+ _sheet = null;
+ final source = _source;
+ _source = null;
+ unawaited(source?.cleanup());
+ playback.dispose();
+ super.dispose();
+ }
+}
diff --git a/desktop/lib/devices/pet_settings.dart b/desktop/lib/devices/pet_settings.dart
new file mode 100644
index 000000000..6399132c5
--- /dev/null
+++ b/desktop/lib/devices/pet_settings.dart
@@ -0,0 +1,1419 @@
+import 'dart:async';
+import 'dart:math' as math;
+import 'dart:ui' as ui;
+
+import 'package:desktop_drop/desktop_drop.dart';
+import 'package:file_selector/file_selector.dart';
+import 'package:flutter/material.dart';
+import 'package:flutter/services.dart';
+
+import '../core/desktop_window.dart';
+import '../shared/theme/app_icons.dart';
+import '../shared/theme/app_theme.dart' as grid;
+import '../widgets/desktop_chrome.dart';
+import 'devices_controller.dart';
+import 'loose_sheet.dart';
+import 'pet_editor.dart';
+import 'pet_source.dart';
+
+export 'pet_editor.dart'
+ show PetEditor, PetSheet, decodePetSheet, sheetRowCrops;
+
+const _errorText = {
+ 'memory': 'The dial is out of memory for pets',
+ 'busy': 'The dial holds too many pets',
+ 'crc': 'The pet didn’t arrive intact. Reconnect the dial to try again',
+ 'shape': 'The pet didn’t arrive intact. Reconnect the dial to try again',
+ 'version': 'Update the dial’s firmware for this pet',
+ 'timeout': 'The dial stopped answering. Reconnect it to try again',
+};
+
+/// The custom pet for the dial: one for every agent (the protocol still holds
+/// per-engine pets; the app offers one). The app turns what the user picked
+/// (a pet folder or zip, WebP, or any PNG / JPEG sprite sheet) into a PNG
+/// sheet; the daemon converts and sends it. This picks the source, lets the
+/// user choose which row plays each state and applies it. Local computer only.
+///
+/// The edit lives in a [PetEditor]: [editor] when the screen shares it with a
+/// [PetRowViewer] of its own (then [showViewer] is false), else one this
+/// section owns, with the viewer drawn inline.
+class PetSettingsSection extends StatefulWidget {
+ const PetSettingsSection({
+ super.key,
+ required this.device,
+ required this.controller,
+ this.editor,
+ this.showViewer = true,
+ this.pickFile,
+ this.pickFolder,
+ this.resolveSource,
+ this.loadSheet,
+ });
+ final HarnessDevice device;
+ final DevicesController controller;
+
+ /// The edit, owned by the caller; null makes one here.
+ final PetEditor? editor;
+
+ /// Whether the row viewer is drawn in this section, above the row cards.
+ final bool showViewer;
+
+ /// Replaces the native file chooser (tests). Returns a path, or null.
+ final Future<String?> Function()? pickFile;
+
+ /// Replaces the native folder chooser (tests). Returns a path, or null.
+ final Future<String?> Function()? pickFolder;
+
+ /// Replaces [resolvePetSource] in the editor made here (tests).
+ final Future<PetSource> Function(String path)? resolveSource;
+
+ /// Replaces [decodePetSheet] in the editor made here (tests).
+ final Future<PetSheet?> Function(String path)? loadSheet;
+
+ @override
+ State<PetSettingsSection> createState() => _PetSettingsSectionState();
+}
+
+class _PetSettingsSectionState extends State<PetSettingsSection> {
+ DevicesController get _controller => widget.controller;
+
+ /// The editor this section made, when it was given none.
+ PetEditor? _own;
+ PetEditor get _editor => widget.editor ?? (_own ??= _make());
+
+ PetEditor _make() => PetEditor(
+ controller: widget.controller,
+ deviceKey: widget.device.key,
+ resolveSource: widget.resolveSource,
+ loadSheet: widget.loadSheet,
+ )..addListener(_changed);
+
+ @override
+ void initState() {
+ super.initState();
+ _controller.addListener(_changed);
+ widget.editor?.addListener(_changed);
+ unawaited(_controller.refreshPetStatus(widget.device.key));
+ }
+
+ @override
+ void didUpdateWidget(PetSettingsSection oldWidget) {
+ super.didUpdateWidget(oldWidget);
+ if (oldWidget.controller != widget.controller) {
+ oldWidget.controller.removeListener(_changed);
+ widget.controller.addListener(_changed);
+ }
+ if (oldWidget.editor != widget.editor) {
+ oldWidget.editor?.removeListener(_changed);
+ widget.editor?.addListener(_changed);
+ }
+ final own = _own;
+ if (own != null &&
+ (widget.editor != null ||
+ own.deviceKey != widget.device.key ||
+ own.controller != widget.controller)) {
+ _own = null;
+ own.dispose();
+ }
+ if (oldWidget.device.key != widget.device.key) {
+ unawaited(_controller.refreshPetStatus(widget.device.key));
+ }
+ }
+
+ @override
+ void dispose() {
+ _controller.removeListener(_changed);
+ widget.editor?.removeListener(_changed);
+ _own?.dispose();
+ super.dispose();
+ }
+
+ void _changed() {
+ if (mounted) setState(() {});
+ }
+
+ static Future<String?> _choose() async {
+ final file = await whileNativePicker(
+ () => openFile(
+ acceptedTypeGroups: const [
+ XTypeGroup(
+ label: 'Pet',
+ extensions: ['png', 'jpg', 'jpeg', 'webp', 'zip', 'json'],
+ ),
+ ],
+ ),
+ );
+ return file?.path;
+ }
+
+ static Future<String?> _chooseFolder() => whileNativePicker(getDirectoryPath);
+
+ @override
+ Widget build(BuildContext context) {
+ final device = widget.device;
+ if (_controller.petRequest == null || !device.local) {
+ return const SizedBox.shrink();
+ }
+ final editor = _editor;
+ final status = _controller.petStatus(device.key);
+ final outdated = _controller.petUnavailable(device.key);
+ final locked =
+ outdated ||
+ (status != null && !status.supported && device.status.attached);
+ final enabled = !locked && device.hostOnline && device.hostAvailable;
+ return Container(
+ key: const ValueKey('pet-panel'),
+ padding: const EdgeInsets.fromLTRB(18, 16, 18, 18),
+ decoration: BoxDecoration(
+ color: grid.AppGlass.surfaceFill,
+ borderRadius: BorderRadius.circular(14),
+ boxShadow: grid.AppGlass.cardShadow,
+ ),
+ child: Column(
+ crossAxisAlignment: CrossAxisAlignment.stretch,
+ children: [
+ Text('Pet', style: DesktopChrome.heading()),
+ const SizedBox(height: 10),
+ if (locked) ...[
+ Text(
+ outdated
+ ? 'Update Harness on this computer to use custom pets'
+ : 'Update the dial’s firmware to use custom pets',
+ style: DesktopChrome.text(color: DesktopChrome.muted),
+ ),
+ const SizedBox(height: 10),
+ ],
+ _PetRow(
+ key: const ValueKey('pet-row-all'),
+ deviceKey: device.key,
+ controller: _controller,
+ editor: editor,
+ enabled: enabled,
+ attached: device.status.attached,
+ pickFile: widget.pickFile ?? _choose,
+ pickFolder: widget.pickFolder ?? _chooseFolder,
+ ),
+ if (editor.editing)
+ _EditorPanel(editor: editor, showViewer: widget.showViewer)
+ else ...[
+ const SizedBox(height: 10),
+ Text(
+ 'Find pets on petdex.dev, or use any PNG, JPEG or WebP sprite '
+ 'sheet.',
+ style: DesktopChrome.metadata(color: DesktopChrome.muted),
+ ),
+ ],
+ ],
+ ),
+ );
+ }
+}
+
+class _PetRow extends StatefulWidget {
+ const _PetRow({
+ super.key,
+ required this.deviceKey,
+ required this.controller,
+ required this.editor,
+ required this.enabled,
+ required this.attached,
+ required this.pickFile,
+ required this.pickFolder,
+ });
+ final String deviceKey;
+ final DevicesController controller;
+ final PetEditor editor;
+ final bool enabled, attached;
+ final Future<String?> Function() pickFile, pickFolder;
+
+ @override
+ State<_PetRow> createState() => _PetRowState();
+}
+
+class _PetRowState extends State<_PetRow> {
+ bool _hovering = false;
+
+ Future<void> _use(String? path) async {
+ if (!widget.enabled) return;
+ await widget.editor.use(path);
+ }
+
+ @override
+ Widget build(BuildContext context) {
+ final editor = widget.editor;
+ final status = widget.controller.petStatus(widget.deviceKey);
+ final current = status?.all;
+ final sending = status?.sending;
+ final info = current == null ? null : status?.pets[current];
+ final failure = current == null ? null : status?.errors[current];
+ final progress = current != null && sending?.id == current;
+ final onDial = current != null && (status?.held.contains(current) ?? false);
+ // Only a dial that can take pets has anything pending.
+ final live = status?.supported ?? false;
+ final note = current != null && !widget.attached
+ ? 'Will be sent when the dial connects'
+ : null;
+ final can = widget.enabled && !editor.busy;
+ final error = editor.editing ? null : editor.error;
+ final detail = editor.editing
+ ? '${editor.name} · not applied yet'
+ : current == null
+ ? 'Default'
+ : info?.name ?? 'Custom pet';
+ return DropTarget(
+ enable: can,
+ onDragEntered: (_) => setState(() => _hovering = true),
+ onDragExited: (_) => setState(() => _hovering = false),
+ onDragDone: (details) async {
+ setState(() => _hovering = false);
+ if (details.files.isNotEmpty) await _use(details.files.first.path);
+ },
+ child: DecoratedBox(
+ decoration: BoxDecoration(
+ borderRadius: BorderRadius.circular(DesktopChrome.rowRadius),
+ border: Border.all(
+ color: _hovering ? DesktopChrome.accent : Colors.transparent,
+ ),
+ ),
+ child: Padding(
+ padding: const EdgeInsets.symmetric(vertical: 2),
+ child: Column(
+ crossAxisAlignment: CrossAxisAlignment.stretch,
+ children: [
+ _PetRowHead(
+ detail: detail,
+ thumb: editor.editing ? null : info?.thumb,
+ status: status == null
+ ? null
+ : note != null
+ ? Text(note, style: DesktopChrome.metadata())
+ : failure != null
+ ? Text(
+ _errorText[failure] ??
+ 'The dial couldn’t take this pet',
+ style: DesktopChrome.metadata(
+ color: Theme.of(context).colorScheme.error,
+ ),
+ )
+ : progress
+ ? Text(
+ 'Sending to dial… ${sending!.percent} %',
+ style: DesktopChrome.metadata(),
+ )
+ : onDial
+ ? Text('On dial ✓', style: DesktopChrome.metadata())
+ : current != null && live
+ ? Text(
+ 'Waiting for the dial…',
+ style: DesktopChrome.metadata(
+ color: DesktopChrome.muted,
+ ),
+ )
+ : null,
+ buttons: [
+ OutlinedButton(
+ onPressed: can
+ ? () async => _use(await widget.pickFolder())
+ : null,
+ style: _pillButton,
+ child: const Text('Choose folder…'),
+ ),
+ OutlinedButton(
+ onPressed: can
+ ? () async => _use(await widget.pickFile())
+ : null,
+ style: _pillButton,
+ child: const Text('Choose file…'),
+ ),
+ if (current != null && !editor.editing)
+ OutlinedButton(
+ onPressed: can ? editor.reset : null,
+ style: _pillButton,
+ child: const Text('Reset'),
+ ),
+ ],
+ ),
+ if (error != null)
+ _line(
+ Text(
+ error,
+ style: DesktopChrome.metadata(
+ color: Theme.of(context).colorScheme.error,
+ ),
+ ),
+ ),
+ ],
+ ),
+ ),
+ ),
+ );
+ }
+
+ static Widget _line(Widget child) =>
+ Padding(padding: const EdgeInsets.only(top: 6), child: child);
+}
+
+/// The quiet pill buttons of the Pet section.
+final _pillButton = OutlinedButton.styleFrom(
+ shape: const StadiumBorder(),
+ padding: const EdgeInsets.symmetric(horizontal: 14),
+ visualDensity: VisualDensity.compact,
+);
+
+/// "All agents" and what it shows on the left, the choosers side by side on
+/// the right; under the text when the row is too narrow for both.
+class _PetRowHead extends StatelessWidget {
+ const _PetRowHead({
+ required this.detail,
+ required this.buttons,
+ this.thumb,
+ this.status,
+ });
+ final String detail;
+ final List<Widget> buttons;
+
+ /// The current pet's picture, when it has one.
+ final Uint8List? thumb;
+
+ /// Where the pet is: on the dial, being sent, waiting, refused.
+ final Widget? status;
+
+ @override
+ Widget build(BuildContext context) {
+ final words = Column(
+ crossAxisAlignment: CrossAxisAlignment.start,
+ mainAxisSize: MainAxisSize.min,
+ children: [
+ Text(
+ 'All agents',
+ style: DesktopChrome.text(
+ size: 14,
+ medium: true,
+ height: 1.3,
+ ).copyWith(fontWeight: FontWeight.w600),
+ ),
+ const SizedBox(height: 2),
+ Text(
+ detail,
+ maxLines: 2,
+ overflow: TextOverflow.ellipsis,
+ style: DesktopChrome.text(size: 13, color: DesktopChrome.muted),
+ ),
+ if (status case final status?) ...[const SizedBox(height: 2), status],
+ ],
+ );
+ final picture = thumb;
+ final text = picture == null
+ ? words
+ : Row(
+ children: [
+ Container(
+ key: const ValueKey('pet-thumb-all'),
+ width: 44,
+ height: 44,
+ padding: const EdgeInsets.all(4),
+ decoration: BoxDecoration(
+ color: grid.AppSurface.recess,
+ borderRadius: BorderRadius.circular(10),
+ ),
+ child: Image.memory(
+ picture,
+ gaplessPlayback: true,
+ filterQuality: FilterQuality.none,
+ ),
+ ),
+ const SizedBox(width: 12),
+ Flexible(child: words),
+ ],
+ );
+ final row = Row(
+ mainAxisSize: MainAxisSize.min,
+ children: [
+ for (final (i, button) in buttons.indexed) ...[
+ if (i > 0) const SizedBox(width: 8),
+ button,
+ ],
+ ],
+ );
+ return LayoutBuilder(
+ builder: (context, constraints) {
+ final scale = MediaQuery.textScalerOf(context).scale(1);
+ if (constraints.maxWidth >= 520 * scale) {
+ return Row(
+ children: [
+ Expanded(child: text),
+ const SizedBox(width: 16),
+ row,
+ ],
+ );
+ }
+ return Column(
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [
+ text,
+ const SizedBox(height: 10),
+ Wrap(spacing: 8, runSpacing: 8, children: buttons),
+ ],
+ );
+ },
+ );
+ }
+}
+
+String _size(int bytes) => bytes >= 1024 * 1024
+ ? '${(bytes / (1024 * 1024)).toStringAsFixed(1)} MB'
+ : '${(bytes / 1024).round()} KB';
+
+/// [row]'s frames, from the editor's local sheet when it was read.
+_RowArt _art(PetEditor editor, PetSheetRow row) {
+ final index = petRows.indexOf(row.row);
+ return _RowArt(
+ frames: row.frames,
+ sheet: editor.sheet?.image,
+ row: index,
+ crop: editor.sheet?.crop(index),
+ strip: row.strip,
+ );
+}
+
+/// Muted copy in the Pet section: what was found, what a row plays.
+TextStyle _note() =>
+ DesktopChrome.text(size: 13, color: DesktopChrome.muted, height: 1.35);
+
+/// The edit in progress, under the All agents row: what was found, a card
+/// per sheet row to view, the states the viewed row plays, then Apply.
+class _EditorPanel extends StatelessWidget {
+ const _EditorPanel({required this.editor, required this.showViewer});
+ final PetEditor editor;
+ final bool showViewer;
+
+ @override
+ Widget build(BuildContext context) {
+ final preview = editor.preview!;
+ final sheetRows = preview.sheetRows;
+ final viewed = editor.viewedRow;
+ final most = sheetRows
+ .map((r) => r.frames)
+ .fold(0, (a, b) => b > a ? b : a);
+ final found = sheetRows.isEmpty
+ ? null
+ : editor.loose
+ ? 'Background removed · ${sheetRows.length} '
+ '${sheetRows.length == 1 ? 'row' : 'rows'} × $most '
+ '${most == 1 ? 'frame' : 'frames'} found'
+ : '${sheetRows.length} ${sheetRows.length == 1 ? 'row' : 'rows'} found';
+ final error = editor.error;
+ return Padding(
+ padding: const EdgeInsets.only(top: 12),
+ child: Column(
+ crossAxisAlignment: CrossAxisAlignment.stretch,
+ children: [
+ if (showViewer) ...[
+ PetRowViewer(editor: editor),
+ const SizedBox(height: 14),
+ ],
+ Text(
+ [
+ ?found,
+ '${_size(preview.bytes)} · ${preview.colours} colours',
+ ].join(' · '),
+ key: const ValueKey('pet-found'),
+ style: _note(),
+ ),
+ for (final warning in preview.warnings)
+ Text(warning, style: DesktopChrome.metadata()),
+ if (viewed != null) ...[
+ const SizedBox(height: 10),
+ _RowGrid(editor: editor, viewed: viewed.row),
+ const SizedBox(height: 16),
+ Text(
+ '${editor.rowLabel(viewed.row)} plays on the dial as',
+ key: const ValueKey('pet-plays-as'),
+ style: _note(),
+ ),
+ const SizedBox(height: 8),
+ Wrap(
+ spacing: 6,
+ runSpacing: 6,
+ children: [
+ for (final MapEntry(key: state, value: label)
+ in petStateLabels.entries)
+ _StateChip(
+ key: ValueKey('pet-state-$state'),
+ label: label,
+ on: editor.rows[state] == viewed.row,
+ onTap: () => editor.choose(state, viewed.row),
+ ),
+ ],
+ ),
+ const SizedBox(height: 10),
+ Text(
+ 'A state plays exactly one row; picking it here moves it.',
+ style: DesktopChrome.metadata(),
+ ),
+ ],
+ const SizedBox(height: 16),
+ Row(
+ key: const ValueKey('pet-actions'),
+ children: [
+ Expanded(
+ child: error == null
+ ? const SizedBox.shrink()
+ : Text(
+ error,
+ style: DesktopChrome.metadata(
+ color: Theme.of(context).colorScheme.error,
+ ),
+ ),
+ ),
+ const SizedBox(width: 8),
+ TextButton(
+ onPressed: editor.busy ? null : editor.cancel,
+ style: TextButton.styleFrom(
+ backgroundColor: DesktopChrome.field,
+ foregroundColor: DesktopChrome.foreground,
+ padding: const EdgeInsets.symmetric(horizontal: 18),
+ ),
+ child: const Text('Cancel'),
+ ),
+ const SizedBox(width: 8),
+ FilledButton(
+ onPressed: editor.busy || !editor.current ? null : editor.apply,
+ style: FilledButton.styleFrom(
+ padding: const EdgeInsets.symmetric(horizontal: 20),
+ ),
+ child: const Text('Apply'),
+ ),
+ ],
+ ),
+ ],
+ ),
+ );
+ }
+}
+
+/// The sheet's rows as cards of one height, three to a line.
+class _RowGrid extends StatelessWidget {
+ const _RowGrid({required this.editor, required this.viewed});
+ final PetEditor editor;
+ final String viewed;
+
+ @override
+ Widget build(BuildContext context) {
+ final sheetRows = editor.preview!.sheetRows;
+ final scale = MediaQuery.textScalerOf(context).scale(1);
+ return LayoutBuilder(
+ builder: (context, constraints) {
+ final cols = constraints.maxWidth < 380 ? 2 : 3;
+ const gap = 8.0;
+ final cardWidth = (constraints.maxWidth - gap * (cols - 1)) / cols;
+ final thumb = (cardWidth * .37).clamp(44.0, 72.0);
+ final height = _RowCard.heightFor(thumb, scale);
+ return Column(
+ crossAxisAlignment: CrossAxisAlignment.stretch,
+ children: [
+ for (var i = 0; i < sheetRows.length; i += cols) ...[
+ if (i > 0) const SizedBox(height: gap),
+ Row(
+ children: [
+ for (var j = i; j < i + cols; j++) ...[
+ if (j > i) const SizedBox(width: gap),
+ Expanded(
+ child: j < sheetRows.length
+ ? _RowCard(
+ key: ValueKey(
+ 'pet-sheet-row-${sheetRows[j].row}',
+ ),
+ label: editor.rowLabel(sheetRows[j].row),
+ art: _art(editor, sheetRows[j]),
+ thumb: thumb,
+ height: height,
+ selected: sheetRows[j].row == viewed,
+ states: editor.statesOf(sheetRows[j].row),
+ onTap: () => editor.view(sheetRows[j].row),
+ )
+ : const SizedBox.shrink(),
+ ),
+ ],
+ ],
+ ),
+ ],
+ ],
+ );
+ },
+ );
+ }
+}
+
+/// The edit's viewed row, played large with a frame scrubber, then what the
+/// dial will draw. Beside the Pet section on a wide screen, inline in it
+/// otherwise. Draws nothing while [editor] has no edit.
+class PetRowViewer extends StatelessWidget {
+ const PetRowViewer({super.key, required this.editor, this.maxViewer = 300});
+ final PetEditor editor;
+
+ /// The tallest the checkered viewer grows.
+ final double maxViewer;
+
+ /// The dial scenes shown, with their labels. Asking falls back to the small
+ /// pet when the daemon sends no asking frames.
+ static const _dial = [
+ ('Rest', 'small'),
+ ('Working', 'working'),
+ ('Asking', 'asking'),
+ ];
+
+ @override
+ Widget build(BuildContext context) => ListenableBuilder(
+ listenable: editor,
+ builder: (context, _) {
+ final preview = editor.preview;
+ if (preview == null) return const SizedBox.shrink();
+ final viewed = editor.viewedRow;
+ final scenes = [
+ for (final (label, scene) in _dial)
+ (preview.frames[scene] ?? const []).isEmpty
+ ? (
+ label,
+ scene,
+ preview.frames['small'] ?? const <Uint8List>[],
+ preview.stepMs['small'] ?? 200,
+ )
+ : (
+ label,
+ scene,
+ preview.frames[scene]!,
+ preview.stepMs[scene] ?? 200,
+ ),
+ ];
+ // One scale for the three, so each is as big against the others as
+ // the dial draws it.
+ final side = dialFrameSide([for (final s in scenes) s.$3]);
+ return Container(
+ key: const ValueKey('pet-row-viewer'),
+ padding: const EdgeInsets.all(16),
+ decoration: _cardDecoration(),
+ child: LayoutBuilder(
+ builder: (context, constraints) {
+ final width = constraints.maxWidth;
+ final size = math.min(112.0, (width - 2 * 10) / 3);
+ return Column(
+ crossAxisAlignment: CrossAxisAlignment.stretch,
+ children: [
+ if (viewed != null) ...[
+ _ViewerHead(
+ key: ValueKey('pet-viewer-${viewed.row}'),
+ editor: editor,
+ label: editor.rowLabel(viewed.row),
+ art: _art(editor, viewed),
+ width: width,
+ maxViewer: maxViewer,
+ ),
+ const SizedBox(height: 16),
+ ],
+ Text('On the dial', style: _note()),
+ const SizedBox(height: 8),
+ Row(
+ mainAxisAlignment: MainAxisAlignment.spaceBetween,
+ children: [
+ for (final (label, scene, frames, stepMs) in scenes)
+ _DialPreview(
+ key: ValueKey('pet-dial-$scene-${preview.id}'),
+ label: label,
+ size: size,
+ frames: frames,
+ stepMs: stepMs,
+ pixel: side == 0
+ ? null
+ : size * (1 - 2 * _DialPreview.inset) / side,
+ ),
+ ],
+ ),
+ ],
+ );
+ },
+ ),
+ );
+ },
+ );
+}
+
+/// The longest side of the first frame of any of [scenes] (PNGs), 0 when
+/// none can be read.
+@visibleForTesting
+int dialFrameSide(List<List<Uint8List>> scenes) {
+ var side = 0;
+ for (final frames in scenes) {
+ if (frames.isEmpty) continue;
+ final size = imageSize(frames.first);
+ if (size == null) continue;
+ side = math.max(side, math.max(size.$1, size.$2));
+ }
+ return side;
+}
+
+/// The viewer's title, play pill, checkered frame and scrubber; repaints on
+/// each frame step.
+class _ViewerHead extends StatelessWidget {
+ const _ViewerHead({
+ super.key,
+ required this.editor,
+ required this.label,
+ required this.art,
+ required this.width,
+ required this.maxViewer,
+ });
+ final PetEditor editor;
+ final String label;
+ final _RowArt art;
+ final double width, maxViewer;
+
+ @override
+ Widget build(BuildContext context) {
+ final n = art.frames;
+ final checker = _CheckerPainter(
+ DesktopChrome.surface,
+ Color.alphaBlend(
+ DesktopChrome.rim.withValues(alpha: .45),
+ DesktopChrome.surface,
+ ),
+ );
+ const gap = 4.0;
+ final tile = n == 0 ? 30.0 : math.min(30.0, (width - gap * (n - 1)) / n);
+ return ListenableBuilder(
+ listenable: editor.playback,
+ builder: (context, _) {
+ final playback = editor.playback;
+ final playing = playback.playing;
+ final index = n == 0 ? 0 : playback.index % n;
+ return Column(
+ crossAxisAlignment: CrossAxisAlignment.stretch,
+ children: [
+ Row(
+ children: [
+ Expanded(
+ child: Column(
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [
+ Text(
+ 'ROW VIEWER',
+ style: DesktopChrome.text(
+ color: DesktopChrome.accent,
+ size: 11,
+ height: 1.3,
+ ).copyWith(fontWeight: FontWeight.w600),
+ ),
+ const SizedBox(height: 2),
+ Text(
+ label,
+ key: const ValueKey('pet-viewer-title'),
+ maxLines: 1,
+ overflow: TextOverflow.ellipsis,
+ style: DesktopChrome.text(
+ size: 17,
+ height: 1.25,
+ ).copyWith(fontWeight: FontWeight.w600),
+ ),
+ ],
+ ),
+ ),
+ const SizedBox(width: 8),
+ _PlayPill(
+ key: const ValueKey('pet-viewer-play'),
+ frames: n,
+ playing: playing,
+ onPressed: n < 2 ? null : playback.toggle,
+ ),
+ ],
+ ),
+ const SizedBox(height: 12),
+ SizedBox(
+ height: math.min(width * .85, maxViewer),
+ child: ClipRRect(
+ borderRadius: BorderRadius.circular(DesktopChrome.rowRadius),
+ child: CustomPaint(
+ painter: checker,
+ child: Padding(
+ padding: const EdgeInsets.all(10),
+ child: _FrameArt(
+ key: const ValueKey('pet-viewer-art'),
+ art: art,
+ index: index,
+ ),
+ ),
+ ),
+ ),
+ ),
+ const SizedBox(height: 10),
+ Row(
+ children: [
+ for (var i = 0; i < n; i++) ...[
+ if (i > 0) const SizedBox(width: gap),
+ GestureDetector(
+ key: ValueKey('pet-viewer-frame-$i'),
+ onTap: () => playback.hold(i),
+ child: MouseRegion(
+ cursor: SystemMouseCursors.click,
+ child: Container(
+ width: tile,
+ height: tile,
+ padding: const EdgeInsets.all(2),
+ decoration: BoxDecoration(
+ color: DesktopChrome.surface,
+ borderRadius: BorderRadius.circular(
+ DesktopChrome.controlRadius,
+ ),
+ border: Border.all(
+ color: !playing && i == index
+ ? DesktopChrome.accent
+ : DesktopChrome.rim,
+ width: !playing && i == index ? 1.5 : 1,
+ ),
+ ),
+ child: _FrameArt(art: art, index: i),
+ ),
+ ),
+ ),
+ ],
+ ],
+ ),
+ ],
+ );
+ },
+ );
+ }
+}
+
+/// "▷ n frames" when paused, "❚❚ n frames" while playing; toggles playback.
+class _PlayPill extends StatelessWidget {
+ const _PlayPill({
+ super.key,
+ required this.frames,
+ required this.playing,
+ required this.onPressed,
+ });
+ final int frames;
+ final bool playing;
+ final VoidCallback? onPressed;
+
+ @override
+ Widget build(BuildContext context) {
+ final color = onPressed == null
+ ? DesktopChrome.muted
+ : DesktopChrome.foreground;
+ final style = DesktopChrome.control(color: color);
+ final line = MediaQuery.textScalerOf(context).scale(13 * 1.25);
+ return Semantics(
+ button: true,
+ enabled: onPressed != null,
+ label: playing ? 'Pause' : 'Play',
+ child: Material(
+ color: Colors.transparent,
+ shape: StadiumBorder(side: BorderSide(color: DesktopChrome.rim)),
+ child: InkWell(
+ customBorder: const StadiumBorder(),
+ onTap: onPressed,
+ child: Padding(
+ padding: const EdgeInsets.symmetric(horizontal: 12, vertical: 6),
+ child: Row(
+ mainAxisSize: MainAxisSize.min,
+ crossAxisAlignment: CrossAxisAlignment.center,
+ children: [
+ SizedBox(
+ height: line,
+ child: Center(
+ child: Icon(
+ playing ? AppIcons.pause : AppIcons.play,
+ size: 12,
+ color: color,
+ ),
+ ),
+ ),
+ const SizedBox(width: 6),
+ SizedBox(
+ height: line,
+ child: Center(
+ child: Text(
+ '$frames ${frames == 1 ? 'frame' : 'frames'}',
+ style: style,
+ textHeightBehavior: const TextHeightBehavior(
+ leadingDistribution: TextLeadingDistribution.even,
+ ),
+ ),
+ ),
+ ),
+ ],
+ ),
+ ),
+ ),
+ ),
+ );
+ }
+}
+
+/// Where a sheet row's frames come from: the decoded sheet at full
+/// resolution ([sheet], row index [row], cut to [crop] of each cell), or
+/// else the daemon's [strip] of them side by side.
+@immutable
+class _RowArt {
+ const _RowArt({
+ required this.frames,
+ required this.sheet,
+ required this.row,
+ required this.strip,
+ this.crop,
+ });
+ final int frames, row;
+ final ui.Image? sheet;
+ final Rect? crop;
+ final Uint8List? strip;
+}
+
+/// Where frame [index] of sheet row [row] is read from on a sheet of
+/// [cell]-sized cells: [crop] (the row's art box, in cell coordinates) of
+/// that cell, or the whole cell without one.
+@visibleForTesting
+Rect frameSource(Size cell, int row, int index, Rect? crop) {
+ final origin = Offset(index * cell.width, row * cell.height);
+ return (crop ?? Offset.zero & cell).shift(origin);
+}
+
+/// Frame [index] of [art], fitted inside the space it is given.
+class _FrameArt extends StatelessWidget {
+ const _FrameArt({super.key, required this.art, required this.index});
+ final _RowArt art;
+ final int index;
+
+ @override
+ Widget build(BuildContext context) {
+ final sheet = art.sheet;
+ if (sheet != null && art.row >= 0) {
+ final cell = Size(sheet.width / sheetCols, sheet.height / sheetRows);
+ return SizedBox.expand(
+ child: CustomPaint(
+ painter: _CellPainter(
+ sheet,
+ frameSource(cell, art.row, index, art.crop),
+ ),
+ ),
+ );
+ }
+ final strip = art.strip;
+ if (strip == null) return const SizedBox.expand();
+ // The strip scaled to the frame's height, slid so frame [index] shows.
+ final n = art.frames;
+ return Center(
+ child: AspectRatio(
+ aspectRatio: cellWidth / cellHeight,
+ child: ClipRect(
+ child: Image.memory(
+ strip,
+ fit: BoxFit.cover,
+ alignment: Alignment(n > 1 ? -1 + 2 * index / (n - 1) : 0, 0),
+ gaplessPlayback: true,
+ filterQuality: FilterQuality.medium,
+ ),
+ ),
+ ),
+ );
+ }
+}
+
+/// One cell of the sheet (or the part of it [source] names), scaled to fit.
+/// Upscaled 2x or more it keeps hard pixels (pixel art); otherwise it is
+/// filtered.
+class _CellPainter extends CustomPainter {
+ const _CellPainter(this.sheet, this.source);
+ final ui.Image sheet;
+ final Rect source;
+
+ @override
+ void paint(Canvas canvas, Size size) {
+ final scale = math.min(
+ size.width / source.width,
+ size.height / source.height,
+ );
+ final w = source.width * scale, h = source.height * scale;
+ final target = Rect.fromLTWH(
+ (size.width - w) / 2,
+ (size.height - h) / 2,
+ w,
+ h,
+ );
+ canvas.drawImageRect(
+ sheet,
+ source,
+ target,
+ Paint()
+ ..filterQuality = scale >= 2
+ ? FilterQuality.none
+ : FilterQuality.medium,
+ );
+ }
+
+ @override
+ bool shouldRepaint(_CellPainter old) =>
+ old.sheet != sheet || old.source != source;
+}
+
+/// The checkered backdrop that shows where a frame is clear.
+class _CheckerPainter extends CustomPainter {
+ const _CheckerPainter(this.light, this.dark);
+ final Color light, dark;
+
+ @override
+ void paint(Canvas canvas, Size size) {
+ const square = 14.0;
+ canvas.drawRect(Offset.zero & size, Paint()..color = light);
+ final paint = Paint()..color = dark;
+ for (var y = 0; y * square < size.height; y++) {
+ for (var x = y % 2; x * square < size.width; x += 2) {
+ canvas.drawRect(
+ Rect.fromLTWH(x * square, y * square, square, square),
+ paint,
+ );
+ }
+ }
+ }
+
+ @override
+ bool shouldRepaint(_CheckerPainter old) =>
+ old.light != light || old.dark != dark;
+}
+
+/// The surface the viewer and the cards sit on.
+BoxDecoration _cardDecoration({bool selected = false}) => BoxDecoration(
+ color: selected ? DesktopChrome.selection : DesktopChrome.field,
+ borderRadius: BorderRadius.circular(DesktopChrome.dialogRadius),
+ border: Border.all(
+ color: selected ? DesktopChrome.accent : DesktopChrome.rim,
+ width: selected ? 1.5 : 1,
+ ),
+);
+
+/// A sheet row to pick for the viewer: its name and frame count, its first
+/// frame at the right, the states it plays along the bottom.
+class _RowCard extends StatelessWidget {
+ const _RowCard({
+ super.key,
+ required this.label,
+ required this.art,
+ required this.thumb,
+ required this.height,
+ required this.selected,
+ required this.states,
+ required this.onTap,
+ });
+ final String label;
+ final _RowArt art;
+ final double thumb, height;
+ final bool selected;
+ final List<String> states;
+ final VoidCallback onTap;
+
+ static const _pad = EdgeInsets.fromLTRB(10, 8, 8, 8);
+ static const _badgeGap = 4.0;
+
+ /// The line of state badges, [scale] being the text scale.
+ static double badgeLine(double scale) => 11 * 1.3 * scale + 2;
+
+ /// One card height for every card of a grid: the thumbnail or the text
+ /// beside it (a title of up to two lines, the frame count), whichever is
+ /// taller, then the badge line.
+ static double heightFor(double thumb, double scale) =>
+ _pad.vertical +
+ math.max(thumb, (2 * 13 * 1.3 + 12 * 1.35) * scale + 2) +
+ _badgeGap +
+ badgeLine(scale);
+
+ @override
+ Widget build(BuildContext context) {
+ final scale = MediaQuery.textScalerOf(context).scale(1);
+ return Semantics(
+ button: true,
+ selected: selected,
+ child: Material(
+ color: Colors.transparent,
+ child: InkWell(
+ onTap: onTap,
+ borderRadius: BorderRadius.circular(DesktopChrome.dialogRadius),
+ child: Ink(
+ height: height,
+ padding: _pad,
+ decoration: _cardDecoration(selected: selected),
+ child: Column(
+ crossAxisAlignment: CrossAxisAlignment.stretch,
+ children: [
+ Expanded(
+ child: Row(
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [
+ Expanded(
+ child: Column(
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [
+ const SizedBox(height: 2),
+ Text(
+ label,
+ maxLines: 2,
+ overflow: TextOverflow.ellipsis,
+ style: DesktopChrome.text(
+ size: 13,
+ height: 1.3,
+ ).copyWith(fontWeight: FontWeight.w600),
+ ),
+ Text(
+ '${art.frames} '
+ '${art.frames == 1 ? 'frame' : 'frames'}',
+ maxLines: 1,
+ style: DesktopChrome.metadata(),
+ ),
+ ],
+ ),
+ ),
+ const SizedBox(width: 6),
+ Container(
+ width: thumb,
+ height: thumb,
+ padding: const EdgeInsets.all(4),
+ decoration: BoxDecoration(
+ color: DesktopChrome.surface,
+ borderRadius: BorderRadius.circular(
+ DesktopChrome.controlRadius,
+ ),
+ ),
+ child: _FrameArt(art: art, index: 0),
+ ),
+ ],
+ ),
+ ),
+ const SizedBox(height: _badgeGap),
+ SizedBox(
+ height: badgeLine(scale),
+ child: _Badges(
+ labels: [for (final s in states) petStateLabels[s]!],
+ ),
+ ),
+ ],
+ ),
+ ),
+ ),
+ ),
+ );
+ }
+}
+
+/// How many of the badges [widths] fit [maxWidth] on one line with [gap]
+/// between them, leaving room for a "+n" badge [more] wide when some don't.
+@visibleForTesting
+int fitBadges(
+ List<double> widths,
+ double maxWidth, {
+ required double Function(int hidden) more,
+ double gap = 4,
+}) {
+ for (var k = widths.length; k > 0; k--) {
+ var w = 0.0;
+ for (var i = 0; i < k; i++) {
+ w += widths[i] + (i > 0 ? gap : 0);
+ }
+ if (k < widths.length) w += gap + more(widths.length - k);
+ if (w <= maxWidth) return k;
+ }
+ return 0;
+}
+
+/// The states a row plays, as badges on one line: the first ones that fit,
+/// then "+n" for the rest.
+class _Badges extends StatelessWidget {
+ const _Badges({required this.labels});
+ final List<String> labels;
+
+ static const _hPad = 6.0;
+
+ @override
+ Widget build(BuildContext context) {
+ if (labels.isEmpty) return const SizedBox.shrink();
+ final scaler = MediaQuery.textScalerOf(context);
+ final style = DesktopChrome.text(size: 11, height: 1.3);
+ double width(String text) {
+ final painter = TextPainter(
+ text: TextSpan(text: text, style: style),
+ textDirection: TextDirection.ltr,
+ textScaler: scaler,
+ maxLines: 1,
+ )..layout();
+ final w = painter.width + 2 * _hPad;
+ painter.dispose();
+ return w.ceilToDouble();
+ }
+
+ final fill = Theme.of(context).colorScheme.primary.withValues(alpha: .35);
+ Widget badge(String text) => Container(
+ padding: const EdgeInsets.symmetric(horizontal: _hPad, vertical: 1),
+ decoration: BoxDecoration(
+ color: fill,
+ borderRadius: BorderRadius.circular(999),
+ ),
+ child: Text(text, maxLines: 1, softWrap: false, style: style),
+ );
+ return LayoutBuilder(
+ builder: (context, constraints) {
+ final shown = fitBadges(
+ [for (final l in labels) width(l)],
+ constraints.maxWidth,
+ more: (hidden) => width('+$hidden'),
+ );
+ final hidden = labels.length - shown;
+ return ClipRect(
+ child: Row(
+ children: [
+ for (var i = 0; i < shown; i++) ...[
+ if (i > 0) const SizedBox(width: 4),
+ badge(labels[i]),
+ ],
+ if (hidden > 0) ...[
+ if (shown > 0) const SizedBox(width: 4),
+ badge('+$hidden'),
+ ],
+ ],
+ ),
+ );
+ },
+ );
+ }
+}
+
+/// What the dial draws for one scene, on a round black face: its frames at
+/// [pixel] logical px per frame pixel (one scale for all the scenes shown),
+/// or fitted when that is unknown.
+class _DialPreview extends StatelessWidget {
+ const _DialPreview({
+ super.key,
+ required this.label,
+ required this.size,
+ required this.frames,
+ required this.stepMs,
+ this.pixel,
+ });
+ final String label;
+ final double size;
+ final List<Uint8List> frames;
+ final int stepMs;
+ final double? pixel;
+
+ /// The share of the face left clear on each side: the square inside the
+ /// circle.
+ static const inset = .14;
+
+ @override
+ Widget build(BuildContext context) => Column(
+ mainAxisSize: MainAxisSize.min,
+ children: [
+ Container(
+ width: size,
+ height: size,
+ decoration: const BoxDecoration(
+ color: Colors.black,
+ shape: BoxShape.circle,
+ ),
+ padding: EdgeInsets.all(size * inset),
+ child: _FrameCycler(frames: frames, stepMs: stepMs, pixel: pixel),
+ ),
+ const SizedBox(height: 6),
+ Text(label, style: _note()),
+ ],
+ );
+}
+
+/// A state the viewed row can play: filled when it plays it.
+class _StateChip extends StatelessWidget {
+ const _StateChip({
+ super.key,
+ required this.label,
+ required this.on,
+ required this.onTap,
+ });
+ final String label;
+ final bool on;
+ final VoidCallback onTap;
+
+ @override
+ Widget build(BuildContext context) {
+ final scheme = Theme.of(context).colorScheme;
+ return Semantics(
+ button: true,
+ selected: on,
+ child: Material(
+ color: on ? scheme.primary : Colors.transparent,
+ shape: StadiumBorder(
+ side: BorderSide(color: on ? scheme.primary : DesktopChrome.rim),
+ ),
+ child: InkWell(
+ customBorder: const StadiumBorder(),
+ onTap: on ? null : onTap,
+ child: Padding(
+ padding: const EdgeInsets.symmetric(horizontal: 12, vertical: 5),
+ child: Text(
+ label,
+ style: DesktopChrome.control(
+ color: on ? scheme.onPrimary : DesktopChrome.foreground,
+ ),
+ ),
+ ),
+ ),
+ ),
+ );
+ }
+}
+
+/// Cycles already-decoded frames, at [pixel] logical px per frame pixel or
+/// scaled down to fit; no timer for a single frame.
+class _FrameCycler extends StatefulWidget {
+ const _FrameCycler({required this.frames, required this.stepMs, this.pixel});
+ final List<Uint8List> frames;
+ final int stepMs;
+ final double? pixel;
+
+ @override
+ State<_FrameCycler> createState() => _FrameCyclerState();
+}
+
+class _FrameCyclerState extends State<_FrameCycler> {
+ Timer? _timer;
+ int _index = 0;
+
+ @override
+ void initState() {
+ super.initState();
+ if (widget.frames.length > 1) {
+ _timer = Timer.periodic(
+ Duration(milliseconds: widget.stepMs.clamp(40, 2000)),
+ (_) => setState(() => _index = (_index + 1) % widget.frames.length),
+ );
+ }
+ }
+
+ @override
+ void dispose() {
+ _timer?.cancel();
+ super.dispose();
+ }
+
+ @override
+ Widget build(BuildContext context) {
+ if (widget.frames.isEmpty) return const SizedBox.expand();
+ final pixel = widget.pixel;
+ return Center(
+ child: Image.memory(
+ widget.frames[_index % widget.frames.length],
+ scale: pixel == null ? 1 : 1 / pixel,
+ fit: BoxFit.scaleDown,
+ gaplessPlayback: true,
+ filterQuality: pixel != null && pixel < 1
+ ? FilterQuality.medium
+ : FilterQuality.none,
+ ),
+ );
+ }
+}
diff --git a/desktop/lib/devices/pet_source.dart b/desktop/lib/devices/pet_source.dart
new file mode 100644
index 000000000..27b92b68d
--- /dev/null
+++ b/desktop/lib/devices/pet_source.dart
@@ -0,0 +1,336 @@
+import 'dart:convert';
+import 'dart:io';
+import 'dart:typed_data';
+import 'dart:ui' as ui;
+
+import 'package:archive/archive.dart';
+import 'package:path/path.dart' as p;
+
+import 'loose_sheet.dart';
+
+/// Why a dropped or chosen pet could not be turned into a PNG sheet. [message]
+/// is shown to the user as is.
+class PetSourceError implements Exception {
+ PetSourceError(this.message);
+ final String message;
+ @override
+ String toString() => 'PetSourceError: $message';
+}
+
+/// A sheet ready for the daemon: a PNG on disk and the pet's own name, if the
+/// package had one. [cleanup] removes whatever this made in the temp folder
+/// (never the user's files); call it once the daemon no longer needs the PNG.
+///
+/// [loose] marks a sheet the app laid out itself from any PNG or JPEG sprite
+/// sheet: its row i holds the sheet's i-th row of frames, whatever the petdex
+/// row is called. [defaultRows] is then the app's first guess at which row
+/// (by petdex row name) plays each state (`rest`, `working`, `listening`,
+/// `sending`, `asking`); null for a petdex sheet, whose rows the daemon maps.
+class PetSource {
+ const PetSource({
+ required this.pngPath,
+ this.name,
+ required this.cleanup,
+ this.loose = false,
+ this.defaultRows,
+ });
+ final String pngPath;
+ final String? name;
+ final Future<void> Function() cleanup;
+ final bool loose;
+ final Map<String, String>? defaultRows;
+}
+
+const _sheetMessage =
+ 'The sheet must be 1536 × 1872 (8 × 9 cells of 192 × 208)';
+const _maxWebp = 8 * 1024 * 1024;
+const _maxZipBytes = 32 * 1024 * 1024;
+const _maxZipEntries = 64;
+const _maxJson = 64 * 1024;
+
+Future<void> _noCleanup() async {}
+
+/// Turns what the user picked into a PNG sheet. Accepts a petdex package
+/// (folder, `pet.json`, or a zip of either), a `.webp`, or a `.png` / `.jpg`
+/// sprite sheet: a PNG of the petdex size is used as is, any other is laid
+/// out by [looseSheetSource]. Everything
+/// from outside the app is untrusted: paths stay inside the package folder, a
+/// zip is bounded in entries and size, and a WebP's size is read from its header
+/// before any decoding.
+Future<PetSource> resolvePetSource(String path) async {
+ if (FileSystemEntity.isDirectorySync(path)) {
+ return _fromDirectory(path, cleanup: _noCleanup);
+ }
+ switch (p.extension(path).toLowerCase()) {
+ case '.png':
+ if (_petdexSized(path)) {
+ return PetSource(pngPath: path, cleanup: _noCleanup);
+ }
+ return looseSheetSource(path, name: p.basenameWithoutExtension(path));
+ case '.jpg' || '.jpeg':
+ return looseSheetSource(path, name: p.basenameWithoutExtension(path));
+ case '.webp':
+ return _fromWebp(path, name: p.basenameWithoutExtension(path));
+ case '.json':
+ return _fromDirectory(p.dirname(path), cleanup: _noCleanup);
+ case '.zip':
+ return _fromZip(path);
+ }
+ throw PetSourceError('Choose a pet folder, zip, pet.json, WebP, PNG or JPEG');
+}
+
+/// Whether the PNG at [path] has a petdex sheet's size, or a header this can't
+/// read (the daemon then says what is wrong with it).
+bool _petdexSized(String path) {
+ final Uint8List head;
+ try {
+ final file = File(path).openSync();
+ try {
+ head = file.readSync(32);
+ } finally {
+ file.closeSync();
+ }
+ } on FileSystemException {
+ return true;
+ }
+ final size = imageSize(head);
+ return size == null || size == (1536, 1872) || size == (768, 936);
+}
+
+Future<PetSource> _fromDirectory(
+ String dir, {
+ required Future<void> Function() cleanup,
+}) async {
+ final String root;
+ try {
+ root = Directory(dir).resolveSymbolicLinksSync();
+ } on FileSystemException {
+ throw PetSourceError('That folder can’t be read');
+ }
+ String? name;
+ String? sheetRel;
+ final json = File(p.join(root, 'pet.json'));
+ if (json.existsSync()) {
+ final meta = await _readMeta(json);
+ name = meta.$1;
+ sheetRel = meta.$2;
+ }
+ if (sheetRel == null) {
+ final found = [
+ for (final ext in ['webp', 'png'])
+ if (File(p.join(root, 'spritesheet.$ext')).existsSync())
+ 'spritesheet.$ext',
+ ];
+ if (found.length != 1) {
+ throw PetSourceError(
+ found.isEmpty
+ ? 'No pet found: expected pet.json or a spritesheet.webp / .png'
+ : 'The folder holds both spritesheet.webp and spritesheet.png',
+ );
+ }
+ sheetRel = found.single;
+ }
+ final sheet = _inside(root, sheetRel);
+ final ext = p.extension(sheet).toLowerCase();
+ if (ext == '.png') {
+ return PetSource(pngPath: sheet, name: name, cleanup: cleanup);
+ }
+ if (ext != '.webp') {
+ throw PetSourceError('The sprite sheet must be a WebP or PNG');
+ }
+ final decoded = await _fromWebp(
+ sheet,
+ name: name ?? p.basenameWithoutExtension(sheet),
+ );
+ return PetSource(
+ pngPath: decoded.pngPath,
+ name: decoded.name,
+ cleanup: () async {
+ await decoded.cleanup();
+ await cleanup();
+ },
+ );
+}
+
+/// (name, spritesheetPath) from a petdex `pet.json`.
+Future<(String?, String?)> _readMeta(File json) async {
+ if (json.lengthSync() > _maxJson) {
+ throw PetSourceError('pet.json is too large');
+ }
+ final Object? raw;
+ try {
+ raw = jsonDecode(await json.readAsString());
+ } on FormatException {
+ throw PetSourceError('pet.json isn’t valid JSON');
+ }
+ if (raw is! Map) throw PetSourceError('pet.json isn’t valid');
+ String? text(Object? v) =>
+ v is String && v.trim().isNotEmpty ? v.trim() : null;
+ final sheet = raw['spritesheetPath'];
+ if (sheet != null && text(sheet) == null) {
+ throw PetSourceError('pet.json has no usable spritesheetPath');
+ }
+ return (text(raw['displayName']) ?? text(raw['id']), text(sheet));
+}
+
+/// [relative] resolved under [root]; refuses `..`, absolute paths and links
+/// that lead out of [root].
+String _inside(String root, String relative) {
+ final parts = relative.split(RegExp(r'[\\/]'));
+ if (relative.contains('\u0000') ||
+ relative.startsWith('/') ||
+ relative.startsWith(r'\') ||
+ RegExp(r'^[A-Za-z]:').hasMatch(relative) ||
+ parts.contains('..')) {
+ throw PetSourceError('The sprite sheet path in pet.json isn’t allowed');
+ }
+ final file = File(p.joinAll([root, ...parts.where((s) => s.isNotEmpty)]));
+ final String real;
+ try {
+ real = file.resolveSymbolicLinksSync();
+ } on FileSystemException {
+ throw PetSourceError('The sprite sheet “$relative” wasn’t found');
+ }
+ if (!p.isWithin(root, real) || !File(real).existsSync()) {
+ throw PetSourceError('The sprite sheet path in pet.json isn’t allowed');
+ }
+ return real;
+}
+
+Future<PetSource> _fromZip(String path) async {
+ final file = File(path);
+ if (!file.existsSync()) throw PetSourceError('That file can’t be read');
+ if (file.lengthSync() > _maxZipBytes) {
+ throw PetSourceError('The zip is too large');
+ }
+ final Archive archive;
+ try {
+ archive = ZipDecoder().decodeBytes(await file.readAsBytes());
+ } catch (_) {
+ throw PetSourceError('That zip can’t be read');
+ }
+ final files = <(String, ArchiveFile)>[];
+ var declared = 0;
+ for (final entry in archive) {
+ final name = entry.name.replaceAll('\\', '/');
+ // Finder adds these; they are not part of the pet.
+ if (name.startsWith('__MACOSX/') || name.endsWith('.DS_Store')) continue;
+ if (name.contains('\u0000') ||
+ name.startsWith('/') ||
+ RegExp(r'^[A-Za-z]:').hasMatch(name) ||
+ name.split('/').contains('..')) {
+ throw PetSourceError('The zip has an entry outside its folder');
+ }
+ if (entry.isSymbolicLink) {
+ throw PetSourceError('The zip holds a link, which isn’t allowed');
+ }
+ if (!entry.isFile) continue;
+ files.add((name, entry));
+ declared += entry.size;
+ if (files.length > _maxZipEntries) {
+ throw PetSourceError('The zip has too many files');
+ }
+ if (declared > _maxZipBytes) throw PetSourceError('The zip is too large');
+ }
+ final temp = await Directory.systemTemp.createTemp('harness-pet-');
+ Future<void> cleanup() async {
+ if (temp.existsSync()) await temp.delete(recursive: true);
+ }
+
+ try {
+ var written = 0;
+ for (final (name, entry) in files) {
+ final bytes = entry.content as List<int>;
+ written += bytes.length;
+ if (written > _maxZipBytes) throw PetSourceError('The zip is too large');
+ final target = File(p.joinAll([temp.path, ...name.split('/')]));
+ await target.parent.create(recursive: true);
+ await target.writeAsBytes(bytes);
+ }
+ var root = temp.resolveSymbolicLinksSync();
+ bool holdsPet(String dir) =>
+ File(p.join(dir, 'pet.json')).existsSync() ||
+ File(p.join(dir, 'spritesheet.webp')).existsSync() ||
+ File(p.join(dir, 'spritesheet.png')).existsSync();
+ if (!holdsPet(root)) {
+ final children = Directory(root).listSync();
+ if (children.length == 1 && children.single is Directory) {
+ root = children.single.path;
+ }
+ }
+ return await _fromDirectory(root, cleanup: cleanup);
+ } catch (_) {
+ await cleanup();
+ rethrow;
+ }
+}
+
+/// (width, height) from a WebP's header, without decoding; null when [b] isn't
+/// a WebP this can read.
+(int, int)? webpSize(Uint8List b) {
+ String tag(int at) =>
+ at + 4 <= b.length ? String.fromCharCodes(b.sublist(at, at + 4)) : '';
+ if (b.length < 30 || tag(0) != 'RIFF' || tag(8) != 'WEBP') return null;
+ int le(int at, int n) {
+ var v = 0;
+ for (var i = n - 1; i >= 0; i--) {
+ v = (v << 8) | b[at + i];
+ }
+ return v;
+ }
+
+ switch (tag(12)) {
+ case 'VP8X':
+ return (le(24, 3) + 1, le(27, 3) + 1);
+ case 'VP8L':
+ if (b[20] != 0x2f) return null;
+ final bits = le(21, 4);
+ return ((bits & 0x3fff) + 1, ((bits >> 14) & 0x3fff) + 1);
+ case 'VP8 ':
+ if (b[23] != 0x9d || b[24] != 0x01 || b[25] != 0x2a) return null;
+ return (le(26, 2) & 0x3fff, le(28, 2) & 0x3fff);
+ }
+ return null;
+}
+
+Future<PetSource> _fromWebp(String path, {required String name}) async {
+ final file = File(path);
+ if (!file.existsSync()) throw PetSourceError('That file can’t be read');
+ if (file.lengthSync() > _maxWebp) {
+ throw PetSourceError('The WebP is larger than 8 MB');
+ }
+ final bytes = await file.readAsBytes();
+ final size = webpSize(bytes);
+ if (size == null) throw PetSourceError('That isn’t a WebP image');
+ if (size != (1536, 1872) && size != (768, 936)) {
+ throw PetSourceError(_sheetMessage);
+ }
+ final Uint8List png;
+ try {
+ final codec = await ui.instantiateImageCodec(bytes);
+ try {
+ final image = (await codec.getNextFrame()).image;
+ try {
+ final data = await image.toByteData(format: ui.ImageByteFormat.png);
+ if (data == null) throw StateError('no PNG data');
+ png = data.buffer.asUint8List(data.offsetInBytes, data.lengthInBytes);
+ } finally {
+ image.dispose();
+ }
+ } finally {
+ codec.dispose();
+ }
+ } catch (_) {
+ throw PetSourceError('The WebP can’t be decoded');
+ }
+ final temp = await Directory.systemTemp.createTemp('harness-pet-');
+ final out = File(p.join(temp.path, 'sheet.png'));
+ await out.writeAsBytes(png);
+ return PetSource(
+ pngPath: out.path,
+ name: name,
+ cleanup: () async {
+ if (temp.existsSync()) await temp.delete(recursive: true);
+ },
+ );
+}
diff --git a/desktop/lib/state/app_state.dart b/desktop/lib/state/app_state.dart
index d048f6c38..808cee1db 100644
--- a/desktop/lib/state/app_state.dart
+++ b/desktop/lib/state/app_state.dart
@@ -1629,6 +1629,47 @@ class AppNotifier extends ChangeNotifier {
}
}
+ /// A pet request (`pet_preview`, `pet_apply`, `pet_reset`, `pet_status`) to
+ /// this computer's daemon. They read files and drive the cable, so a relayed
+ /// machine is refused here without sending anything. A refusal comes back as
+ /// `{error, message}`, the same shape the daemon uses, not as an exception.
+ Future<Map<String, dynamic>> petRequest(
+ String machineId,
+ String type,
+ Map<String, Object?> payload,
+ ) async {
+ final machine = machineStates[machineId];
+ if (machine == null ||
+ !machine.isLocalMachine ||
+ (_pool == null && connectionForTest == null)) {
+ return {
+ 'error': 'LOCAL_ONLY',
+ 'message': 'Pets are set on this computer.',
+ };
+ }
+ try {
+ return await _conn(machineId).request(
+ type,
+ payload: payload,
+ timeout: type == 'pet_preview'
+ ? const Duration(seconds: 30)
+ : const Duration(seconds: 6),
+ );
+ } on WsRequestFailure catch (failure) {
+ return {
+ 'error': failure.code,
+ 'message': failure.payload['message'] is String
+ ? failure.payload['message']
+ : failure.detail ?? failure.code,
+ };
+ } catch (_) {
+ return {
+ 'error': 'UNREACHABLE',
+ 'message': 'Couldn’t reach Harness on this computer. Try again.',
+ };
+ }
+ }
+
/// One utility tab for physical devices. The experiment must be explicitly
/// acknowledged before any entry point, including restored history, opens it.
void openDevices() {
@@ -2599,7 +2640,9 @@ class AppNotifier extends ChangeNotifier {
return;
}
pane.claimOnFirstAttach = true;
- if (panes.contains(pane) && _paneNeedsAttach(pane) && _canAttachPane(pane)) {
+ if (panes.contains(pane) &&
+ _paneNeedsAttach(pane) &&
+ _canAttachPane(pane)) {
pane.claimOnFirstAttach = false;
await _reattachPane(pane, intent: AttachIntent.person);
}
@@ -4450,7 +4493,10 @@ class AppNotifier extends ChangeNotifier {
// Which sign-in this app is under is the device log's to know before anything below can read it
// (a restored pane, the dial, the pool, a connection's push): synchronous, ahead of the first await.
// A sign-in by hand just now is `fresh`; a stored session (the app opening) is not.
- if (signedIn) _deviceLog?.beginSignIn(fresh: viewer?.auth.consumeFreshSignIn() ?? false);
+ if (signedIn)
+ _deviceLog?.beginSignIn(
+ fresh: viewer?.auth.consumeFreshSignIn() ?? false,
+ );
// Stays on the pre-navigation `bootstrapping` screen (main.dart) until the daemon is
// confirmed reachable — flipping to `authenticated` any earlier is what let the home UI
// race `harness start`'s own backend handshake and surface a bogus 30s "Could not load
@@ -4811,7 +4857,8 @@ class AppNotifier extends ChangeNotifier {
if (me != null) {
currentUser = CurrentUserProfile.fromMe(me);
// A sign-in by hand: the device log keeps which account it was made to.
- if (currentUser!.id case final id?) unawaited(_deviceLog?.signedInAs(id));
+ if (currentUser!.id case final id?)
+ unawaited(_deviceLog?.signedInAs(id));
notifyListeners();
}
} catch (error) {
@@ -6856,7 +6903,8 @@ class AppNotifier extends ChangeNotifier {
/// Whether [departed] was removed by a key that is itself new and unlooked-at (or one that left that
/// way): someone who just got in clearing up after themselves. A key's own sign-out is never red.
bool departedIsRed(DeviceLogDeparted departed) {
- if (departed.selfRemoved || departed.removedBy == departed.pub) return false;
+ if (departed.selfRemoved || departed.removedBy == departed.pub)
+ return false;
return newDevices.any((d) => d.pub == departed.removedBy) ||
departedDevices.any((d) => d.pub == departed.removedBy);
}
@@ -6937,7 +6985,10 @@ class AppNotifier extends ChangeNotifier {
// This app's own key rides each read, so the backend counts it as used (not as abandoned).
fetch: (since) async => api.deviceKeys(
since,
- self: await services.keys.identity().then<String?>((i) => b64e(i.pub), onError: (Object _) => null),
+ self: await services.keys.identity().then<String?>(
+ (i) => b64e(i.pub),
+ onError: (Object _) => null,
+ ),
),
append: (entry) => api.appendDeviceKey(entry),
label: _deviceLabel,
@@ -7062,7 +7113,10 @@ class AppNotifier extends ChangeNotifier {
registerError = listing.registerError;
pending = listing.pending;
departed = listing.departed;
- known = [for (final r in listing.members) NewDeviceNotice.fromMember(r.member, suspended: r.suspended)];
+ known = [
+ for (final r in listing.members)
+ NewDeviceNotice.fromMember(r.member, suspended: r.suspended),
+ ];
} else {
final raw = await api.daemonDevices();
if (raw == null) return;
@@ -7091,11 +7145,15 @@ class AppNotifier extends ChangeNotifier {
// before it would drop the listing for good. A sign-out bumps the generation instead
// ([_clearDeviceNoticeState]), and a daemon's listing is the daemon's current account.
// Nor after a sign-out: a read already in flight must not put the old account's banner back.
- if (_disposed || generation != _pendingSyncGeneration || status == AppStatus.unauthenticated) return;
+ if (_disposed ||
+ generation != _pendingSyncGeneration ||
+ status == AppStatus.unauthenticated)
+ return;
_pendingBootReadDone = true;
if (legacyDaemon) return;
final tooMany = registerError == 'TOO_MANY';
- var changed = frozen != _deviceListFrozen || tooMany != _deviceListTooMany;
+ var changed =
+ frozen != _deviceListFrozen || tooMany != _deviceListTooMany;
_deviceListFrozen = frozen;
_deviceListTooMany = tooMany;
// Oldest first: the band names the first, and "(+n more)" the rest.
@@ -7121,7 +7179,9 @@ class AppNotifier extends ChangeNotifier {
changed = true;
}
if (conflict == null) _dismissedConflict = null;
- if (daemon && deviceConflict?.pub != (conflict?.pub == _dismissedConflict ? null : conflict?.pub)) {
+ if (daemon &&
+ deviceConflict?.pub !=
+ (conflict?.pub == _dismissedConflict ? null : conflict?.pub)) {
deviceConflict = conflict?.pub == _dismissedConflict ? null : conflict;
changed = true;
}
@@ -7138,10 +7198,14 @@ class AppNotifier extends ChangeNotifier {
/// changes and the daemon's frames say when to read, so a recovery tick every few seconds does not.
bool _pendingBootReadDone = false;
- static bool _sameDeparted(List<DeviceLogDeparted> a, List<DeviceLogDeparted> b) {
+ static bool _sameDeparted(
+ List<DeviceLogDeparted> a,
+ List<DeviceLogDeparted> b,
+ ) {
if (a.length != b.length) return false;
for (var i = 0; i < a.length; i++) {
- if (a[i].pub != b[i].pub || a[i].removedAt != b[i].removedAt) return false;
+ if (a[i].pub != b[i].pub || a[i].removedAt != b[i].removedAt)
+ return false;
}
return true;
}
@@ -7149,7 +7213,8 @@ class AppNotifier extends ChangeNotifier {
static bool _samePubs(List<NewDeviceNotice> a, List<NewDeviceNotice> b) {
if (a.length != b.length) return false;
for (var i = 0; i < a.length; i++) {
- if (a[i].pub != b[i].pub || a[i].suspended != b[i].suspended) return false;
+ if (a[i].pub != b[i].pub || a[i].suspended != b[i].suspended)
+ return false;
}
return true;
}
@@ -7157,11 +7222,17 @@ class AppNotifier extends ChangeNotifier {
/// Persists "seen" for [pub] (one), every device (neither) or the baseline panel, in whichever copy
/// of the log this end keeps. Only when that cannot be — a daemon that predates it — does it stay
/// in memory ([_dismissedDevices]).
- Future<void> _persistSeen({String? pub, List<String>? pubs, bool baseline = false}) async {
+ Future<void> _persistSeen({
+ String? pub,
+ List<String>? pubs,
+ bool baseline = false,
+ }) async {
// Which dismissals this write settles; the baseline panel's "Got it" settles none of them.
void settled() {
if (baseline) return;
- _dismissedDevices.removeWhere((p) => pub != null ? p == pub : (pubs?.contains(p) ?? true));
+ _dismissedDevices.removeWhere(
+ (p) => pub != null ? p == pub : (pubs?.contains(p) ?? true),
+ );
}
try {
@@ -7174,7 +7245,11 @@ class AppNotifier extends ChangeNotifier {
settled();
return;
}
- if (await api.daemonDismissDevices(pub: pub, pubs: pubs, baseline: baseline)) {
+ if (await api.daemonDismissDevices(
+ pub: pub,
+ pubs: pubs,
+ baseline: baseline,
+ )) {
settled();
}
} catch (_) {}
@@ -7236,7 +7311,9 @@ class AppNotifier extends ChangeNotifier {
_dismissedDevices.add(pub);
_pendingSyncGeneration++;
notifyListeners();
- unawaited(liftSuspension ? _persistSeen(pub: pub) : _persistSeen(pubs: [pub]));
+ unawaited(
+ liftSuspension ? _persistSeen(pub: pub) : _persistSeen(pubs: [pub]),
+ );
}
/// "Got it" on a key that joined and left before anyone looked: the one way its flag goes away (the
@@ -7279,7 +7356,8 @@ class AppNotifier extends ChangeNotifier {
void _announceRemoval(DeviceRemovalNotice notice) {
// A red notice (a new device nobody looked at removed it) is never softened by a later one for the
// same key — only the person's own dismissal takes it down.
- if (!notice.red && deviceRemovals.any((n) => n.pub == notice.pub && n.red)) return;
+ if (!notice.red && deviceRemovals.any((n) => n.pub == notice.pub && n.red))
+ return;
deviceRemovals.removeWhere((n) => n.pub == notice.pub);
deviceRemovals.add(notice);
devicesRevision++;
@@ -7318,7 +7396,9 @@ class AppNotifier extends ChangeNotifier {
///
/// [onListed] hears the banner's devices the moment the listing is read — before the last-seen
/// request, which the backend can delay — so the list marks as seen only what was shown with it.
- Future<AccountDevices?> loadDevices({void Function(List<String> banner)? onListed}) async {
+ Future<AccountDevices?> loadDevices({
+ void Function(List<String> banner)? onListed,
+ }) async {
if (_deviceLog case final log?) {
final listing = AccountDevices.fromListing(await log.list());
onListed?.call([for (final d in newDevices) d.pub]);
@@ -7346,15 +7426,24 @@ class AppNotifier extends ChangeNotifier {
/// A confirm names the [head] the preview showed: if the backend's list is another by now, nothing is
/// trusted and the answer is [DevicesRebaseline.logChanged]. Another account's list than the one
/// signed in to is never trusted by a review ([DevicesRebaseline.otherAccount]): signing in again is.
- Future<DevicesRebaseline?> rebaselineDevices({required bool confirm, DevLogHead? head}) async {
+ Future<DevicesRebaseline?> rebaselineDevices({
+ required bool confirm,
+ DevLogHead? head,
+ }) async {
final DevicesRebaseline? result;
if (_deviceLog case final log?) {
- final r = await log.rebaseline(confirm: confirm, expectedHead: confirm ? head : null);
+ final r = await log.rebaseline(
+ confirm: confirm,
+ expectedHead: confirm ? head : null,
+ );
// Null is a log that could not be read; a head that moved is a result of its own.
result = r == null ? null : DevicesRebaseline.fromViewer(r);
} else {
result = DevicesRebaseline.fromDaemon(
- await api.daemonRebaselineDevices(confirm: confirm, head: confirm ? head?.toJson() : null),
+ await api.daemonRebaselineDevices(
+ confirm: confirm,
+ head: confirm ? head?.toJson() : null,
+ ),
);
}
if (confirm && result != null && !result.refused) {
@@ -15829,7 +15918,8 @@ class AppNotifier extends ChangeNotifier {
case 'device_key_removed':
// Only this computer's own daemon says this (see [_isOwnDaemonMachine]).
if (_isOwnDaemonMachine(machineId)) {
- if (DeviceRemovalNotice.fromJson(payload) case final notice?) _announceRemoval(notice);
+ if (DeviceRemovalNotice.fromJson(payload) case final notice?)
+ _announceRemoval(notice);
}
break;
case 'device_conflict':
diff --git a/desktop/test/loose_sheet_test.dart b/desktop/test/loose_sheet_test.dart
new file mode 100644
index 000000000..5e67e7e7e
--- /dev/null
+++ b/desktop/test/loose_sheet_test.dart
@@ -0,0 +1,444 @@
+import 'dart:io';
+import 'dart:typed_data';
+import 'dart:ui' as ui;
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/devices/loose_sheet.dart';
+import 'package:harness/devices/pet_source.dart';
+
+/// A synthetic RGBA image to draw sprite sheets on.
+class _Canvas {
+ _Canvas(this.width, this.height) : rgba = Uint8List(width * height * 4);
+ final int width, height;
+ final Uint8List rgba;
+
+ void set(int x, int y, List<int> c) {
+ final i = (y * width + x) * 4;
+ rgba[i] = c[0];
+ rgba[i + 1] = c[1];
+ rgba[i + 2] = c[2];
+ rgba[i + 3] = c.length > 3 ? c[3] : 255;
+ }
+
+ List<int> at(int x, int y) {
+ final i = (y * width + x) * 4;
+ return rgba.sublist(i, i + 4);
+ }
+
+ void fill(int x0, int y0, int x1, int y1, List<int> c) {
+ for (var y = y0; y < y1; y++) {
+ for (var x = x0; x < x1; x++) {
+ set(x, y, c);
+ }
+ }
+ }
+
+ /// The "transparent" checkerboard an editor bakes into an export.
+ void checker() {
+ for (var y = 0; y < height; y++) {
+ for (var x = 0; x < width; x++) {
+ final v = ((x ~/ 10) + (y ~/ 10)).isEven ? 180 : 252;
+ set(x, y, [v, v, v]);
+ }
+ }
+ }
+
+ /// A character: a dark outline around a red body with a white highlight.
+ void blob(int x, int y, int w, int h) {
+ fill(x, y, x + w, y + h, [10, 10, 20]);
+ fill(x + 2, y + 2, x + w - 2, y + h - 2, [200, 60, 60]);
+ fill(x + 5, y + 5, x + 9, y + 9, [252, 252, 252]);
+ }
+}
+
+int _alpha(Uint8List rgba, int width, int x, int y) =>
+ rgba[(y * width + x) * 4 + 3];
+
+/// The opaque box (alpha 128 or more) of cell [col] of row [row] of a
+/// composed sheet, in cell coordinates, right and bottom exclusive.
+({int left, int top, int right, int bottom, int width, int height}) _box(
+ Uint8List sheet,
+ int row,
+ int col,
+) {
+ var left = cellWidth, top = cellHeight, right = 0, bottom = 0;
+ for (var y = 0; y < cellHeight; y++) {
+ for (var x = 0; x < cellWidth; x++) {
+ final a = _alpha(
+ sheet,
+ sheetWidth,
+ col * cellWidth + x,
+ row * cellHeight + y,
+ );
+ if (a < 128) continue;
+ if (x < left) left = x;
+ if (y < top) top = y;
+ if (x + 1 > right) right = x + 1;
+ if (y + 1 > bottom) bottom = y + 1;
+ }
+ }
+ return (
+ left: left,
+ top: top,
+ right: right,
+ bottom: bottom,
+ width: right - left,
+ height: bottom - top,
+ );
+}
+
+/// Two rows on a checkerboard: three frames, then two.
+_Canvas _twoRows() {
+ final c = _Canvas(200, 140)..checker();
+ for (final x in [10, 60, 110]) {
+ c.blob(x, 10, 30, 30);
+ }
+ c
+ ..blob(10, 80, 30, 40)
+ ..blob(70, 90, 30, 30);
+ return c;
+}
+
+void main() {
+ test('a baked checkerboard is cleared, the highlight inside survives', () {
+ final c = _twoRows();
+ expect(hasRealAlpha(c.rgba), isFalse);
+ expect(clearBackground(c.rgba, c.width, c.height), isTrue);
+ expect(_alpha(c.rgba, c.width, 0, 0), 0);
+ expect(_alpha(c.rgba, c.width, 50, 60), 0);
+ expect(_alpha(c.rgba, c.width, 12, 12), 255); // body
+ expect(_alpha(c.rgba, c.width, 16, 16), 255); // white highlight
+ final rows = findFrames(c.rgba, c.width, c.height);
+ expect(rows.map((r) => r.length), [3, 2]);
+ final f = rows[0][1];
+ expect((f.left, f.top, f.right, f.bottom), (60, 10, 90, 40));
+ expect((rows[1][0].top, rows[1][0].bottom), (80, 120));
+ });
+
+ test('a solid background is cleared by its border colour', () {
+ final c = _Canvas(160, 80)..fill(0, 0, 160, 80, [40, 90, 200]);
+ c
+ ..blob(10, 20, 30, 40)
+ ..blob(60, 20, 30, 40)
+ ..blob(110, 25, 30, 35);
+ expect(clearBackground(c.rgba, c.width, c.height), isTrue);
+ expect(_alpha(c.rgba, c.width, 50, 5), 0);
+ expect(_alpha(c.rgba, c.width, 15, 25), 255);
+ expect(findFrames(c.rgba, c.width, c.height).single.length, 3);
+ });
+
+ test('a busy border with no background is refused', () {
+ final c = _Canvas(100, 100);
+ for (var y = 0; y < 100; y++) {
+ for (var x = 0; x < 100; x++) {
+ c.set(x, y, [(x * 37) % 256, (y * 91) % 256, (x * y) % 256]);
+ }
+ }
+ expect(clearBackground(c.rgba, c.width, c.height), isFalse);
+ });
+
+ test('real transparency is kept as it is', () {
+ final c = _Canvas(120, 60);
+ c
+ ..blob(10, 10, 30, 40)
+ ..blob(70, 10, 30, 40);
+ expect(hasRealAlpha(c.rgba), isTrue);
+ expect(findFrames(c.rgba, c.width, c.height).single.length, 2);
+ });
+
+ test('a sheet with nothing on it has no frames', () {
+ final c = _Canvas(100, 100)..checker();
+ clearBackground(c.rgba, c.width, c.height);
+ expect(findFrames(c.rgba, c.width, c.height), isEmpty);
+ });
+
+ test('at most 9 rows of 8 frames are kept', () {
+ final c = _Canvas(10 * 40 + 10, 11 * 40 + 10);
+ for (var r = 0; r < 11; r++) {
+ for (var k = 0; k < 10; k++) {
+ c.blob(10 + k * 40, 10 + r * 40, 25, 25);
+ }
+ }
+ final rows = findFrames(c.rgba, c.width, c.height);
+ expect(rows.length, 9);
+ expect(rows.every((r) => r.length == 8), isTrue);
+ });
+
+ test('frames land in their cells, bottom-aligned, upscaled when tiny', () {
+ final c = _twoRows();
+ clearBackground(c.rgba, c.width, c.height);
+ final rows = findFrames(c.rgba, c.width, c.height);
+ // Widest 30, tallest row 40 (30 + a 10 px drop): 5x fits 192 x 208.
+ expect(sheetScale(rows), 5);
+ final sheet = composeSheet(c.rgba, c.width, rows);
+ expect(sheet.length, sheetWidth * sheetHeight * 4);
+ // Row 0, cell 0: 150 x 150 centred, on the baseline (4 px margin).
+ expect(_alpha(sheet, sheetWidth, 96, 208 - 5), 255);
+ expect(_alpha(sheet, sheetWidth, 96, 208 - 4), 0);
+ expect(_alpha(sheet, sheetWidth, 96, 208 - 4 - 150), 255);
+ expect(_alpha(sheet, sheetWidth, 96, 208 - 4 - 151), 0);
+ expect(_alpha(sheet, sheetWidth, 21, 150), 255);
+ expect(_alpha(sheet, sheetWidth, 20, 150), 0);
+ // Cells 3+ of row 0 and 2+ of row 1 stay empty, as does row 2.
+ expect(_alpha(sheet, sheetWidth, 3 * 192 + 96, 150), 0);
+ expect(_alpha(sheet, sheetWidth, 2 * 192 + 96, 208 + 150), 0);
+ expect(_alpha(sheet, sheetWidth, 96, 2 * 208 + 150), 0);
+ // Row 1, cell 0 is the taller frame, its bottom on the baseline; cell 1
+ // sits on that same baseline (its bottom is the row's bottom too).
+ expect(_alpha(sheet, sheetWidth, 96, 2 * 208 - 5), 255);
+ expect(_alpha(sheet, sheetWidth, 192 + 96, 2 * 208 - 5), 255);
+ });
+
+ test('a big sheet is scaled down to fit a cell', () {
+ final rows = [
+ [const LooseFrame(0, 0, 400, 300)],
+ ];
+ expect(sheetScale(rows), closeTo(184 / 400, 1e-9));
+ });
+
+ test('the tallest frame fills the cell less its margin, a jump too', () {
+ // Row 0: three 60 x 150 frames on the ground. Row 1: two on the ground
+ // and one 90 px up, so the row's band is 240 tall, more than a cell.
+ final c = _Canvas(400, 500);
+ for (final x in [10, 110, 210]) {
+ c.blob(x, 10, 60, 150);
+ }
+ c
+ ..blob(10, 340, 60, 150)
+ ..blob(110, 250, 60, 150)
+ ..blob(210, 340, 60, 150);
+ final rows = findFrames(c.rgba, c.width, c.height);
+ expect(rows.map((r) => r.length), [3, 3]);
+ expect(sheetScale(rows), closeTo(200 / 150, 1e-9));
+ final sheet = composeSheet(c.rgba, c.width, rows);
+ for (var r = 0; r < 2; r++) {
+ for (var col = 0; col < 3; col++) {
+ final box = _box(sheet, r, col);
+ expect(box.height, inInclusiveRange(199, 200), reason: 'r$r c$col');
+ expect(box.top, greaterThanOrEqualTo(4));
+ expect(box.bottom, lessThanOrEqualTo(208 - 4));
+ }
+ }
+ // No room is left above a cell-tall frame: the jump lands on the ground.
+ expect(_box(sheet, 1, 1).bottom, _box(sheet, 1, 0).bottom);
+ });
+
+ test('a jump keeps its lift while the row fits a cell', () {
+ final c = _Canvas(300, 200);
+ c
+ ..blob(10, 60, 40, 100)
+ ..blob(110, 20, 40, 100);
+ final rows = findFrames(c.rgba, c.width, c.height);
+ final s = sheetScale(rows);
+ expect(s, 2, reason: 'a whole-number upscale: 200 / 100');
+ // 2x makes the frames 200 tall: no room is left to lift one.
+ expect(liftShare(rows.single, s), 0);
+ final short = _Canvas(300, 200)
+ ..blob(10, 60, 40, 60)
+ ..blob(110, 55, 40, 60);
+ final shortRows = findFrames(short.rgba, short.width, short.height);
+ final k = sheetScale(shortRows);
+ expect(k, 3);
+ expect(liftShare(shortRows.single, k), 1, reason: '(60 + 5) x 3 fits');
+ final sheet = composeSheet(short.rgba, short.width, shortRows);
+ expect(
+ _box(sheet, 0, 0).bottom - _box(sheet, 0, 1).bottom,
+ 15,
+ reason: 'lifted 5 px x 3',
+ );
+ });
+
+ test('the guess: first row rests, last asks, the busiest works', () {
+ final c = _Canvas(300, 300);
+ // Row 0 still, row 1 still, row 2 moving, row 3 last.
+ for (var k = 0; k < 4; k++) {
+ c.blob(10 + k * 70, 10, 40, 40);
+ c.blob(10 + k * 70, 80, 40, 40);
+ c.blob(
+ 10 + k * 70 + (k.isEven ? 0 : 10),
+ 150 + (k.isEven ? 0 : 15),
+ k.isEven ? 40 : 25,
+ 40,
+ );
+ c.blob(10 + k * 70, 240, 40, 40);
+ }
+ final rows = findFrames(c.rgba, c.width, c.height);
+ expect(rows.length, 4);
+ expect(guessRows(c.rgba, c.width, rows), {
+ 'rest': 'idle',
+ 'working': 'runningLeft',
+ 'listening': 'idle',
+ 'sending': 'idle',
+ 'asking': 'waving',
+ });
+ });
+
+ test('reads PNG and JPEG sizes from the header', () {
+ final png = Uint8List.fromList([
+ 0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A, //
+ 0, 0, 0, 13, 0x49, 0x48, 0x44, 0x52,
+ 0, 0, 0x02, 0xE0, 0, 0, 0x04, 0x49,
+ ]);
+ expect(imageSize(png), (736, 1097));
+ final jpeg = Uint8List.fromList([
+ 0xFF, 0xD8, 0xFF, 0xE0, 0, 4, 0, 0, //
+ 0xFF, 0xC0, 0, 17, 8, 0x04, 0x49, 0x02, 0xE0, 3,
+ ]);
+ expect(imageSize(jpeg), (736, 1097));
+ expect(imageSize(Uint8List.fromList([1, 2, 3])), isNull);
+ });
+
+ late Directory work;
+ setUp(() => work = Directory.systemTemp.createTempSync('loose-sheet-'));
+ tearDown(() => work.deleteSync(recursive: true));
+
+ Future<void> expectError(Future<Object?> future, Object matcher) =>
+ expectLater(
+ future,
+ throwsA(
+ isA<PetSourceError>().having((e) => e.message, 'message', matcher),
+ ),
+ );
+
+ testWidgets('a checkered PNG becomes a petdex sheet with a guess', (
+ tester,
+ ) async {
+ final c = _twoRows();
+ final png = await tester.runAsync(
+ () => encodePng(c.rgba, c.width, c.height),
+ );
+ final file = File('${work.path}/hero.png')..writeAsBytesSync(png!);
+ final source = await tester.runAsync(() => resolvePetSource(file.path));
+ expect(source!.loose, isTrue);
+ expect(source.name, 'hero');
+ expect(source.defaultRows!['rest'], 'idle');
+ expect(source.defaultRows!['asking'], 'runningRight');
+ final out = File(source.pngPath).readAsBytesSync();
+ expect(imageSize(out), (1536, 1872));
+ final pixels = await tester.runAsync(() async {
+ final codec = await ui.instantiateImageCodec(out);
+ final image = (await codec.getNextFrame()).image;
+ final data = await image.toByteData(
+ format: ui.ImageByteFormat.rawStraightRgba,
+ );
+ return data!.buffer.asUint8List();
+ });
+ expect(_alpha(pixels!, sheetWidth, 96, 208 - 5), 255);
+ expect(_alpha(pixels, sheetWidth, 0, 0), 0);
+ await tester.runAsync(source.cleanup);
+ expect(File(source.pngPath).existsSync(), isFalse);
+ });
+
+ testWidgets('semi-transparent pixels survive the PNG round trip', (
+ tester,
+ ) async {
+ final rgba = Uint8List.fromList([255, 0, 0, 128, 0, 0, 255, 255]);
+ final png = await tester.runAsync(() => encodePng(rgba, 2, 1));
+ final out = await tester.runAsync(() async {
+ final codec = await ui.instantiateImageCodec(png!);
+ final image = (await codec.getNextFrame()).image;
+ final data = await image.toByteData(
+ format: ui.ImageByteFormat.rawStraightRgba,
+ );
+ return data!.buffer.asUint8List();
+ });
+ expect(out![0], greaterThan(250));
+ expect(out.sublist(1, 4), [0, 0, 128]);
+ expect(out.sublist(4), [0, 0, 255, 255]);
+ });
+
+ testWidgets('a petdex-sized PNG is used as is', (tester) async {
+ final rgba = Uint8List(768 * 936 * 4);
+ final png = await tester.runAsync(() => encodePng(rgba, 768, 936));
+ final file = File('${work.path}/pet.png')..writeAsBytesSync(png!);
+ final source = await tester.runAsync(() => resolvePetSource(file.path));
+ expect(source!.pngPath, file.path);
+ expect(source.loose, isFalse);
+ });
+
+ testWidgets('a sheet with no frames says why', (tester) async {
+ final c = _Canvas(100, 100)..checker();
+ final png = await tester.runAsync(
+ () => encodePng(c.rgba, c.width, c.height),
+ );
+ final file = File('${work.path}/empty.png')..writeAsBytesSync(png!);
+ await tester.runAsync(
+ () => expectError(resolvePetSource(file.path), noFramesMessage),
+ );
+ });
+
+ testWidgets('an image over 4096 px is refused before decoding', (
+ tester,
+ ) async {
+ final jpeg = Uint8List.fromList([
+ 0xFF, 0xD8, 0xFF, 0xC0, 0, 17, 8, 0x13, 0x88, 0x13, 0x88, 3, //
+ ]);
+ final file = File('${work.path}/huge.jpg')..writeAsBytesSync(jpeg);
+ await tester.runAsync(
+ () => expectError(resolvePetSource(file.path), contains('4096')),
+ );
+ });
+
+ testWidgets('a JPEG over 8 MB is refused', (tester) async {
+ final file = File('${work.path}/fat.jpeg')
+ ..writeAsBytesSync(Uint8List(8 * 1024 * 1024 + 1));
+ await tester.runAsync(
+ () => expectError(resolvePetSource(file.path), contains('8 MB')),
+ );
+ });
+
+ const real = '/Users/duynguyen/Downloads/character sprite sheet.jpeg';
+ testWidgets('the real JPEG sheet: 4 rows of 5 frames', (tester) async {
+ final bytes = File(real).readAsBytesSync();
+ final pixels = await tester.runAsync(() async {
+ final codec = await ui.instantiateImageCodec(bytes);
+ final image = (await codec.getNextFrame()).image;
+ final data = await image.toByteData(
+ format: ui.ImageByteFormat.rawStraightRgba,
+ );
+ return (data!.buffer.asUint8List(), image.width, image.height);
+ });
+ final (rgba, w, h) = pixels!;
+ expect(clearBackground(rgba, w, h), isTrue);
+ final rows = findFrames(rgba, w, h);
+ expect(rows.map((r) => r.length), [5, 5, 5, 5]);
+ final source = await tester.runAsync(() => resolvePetSource(real));
+ expect(source!.loose, isTrue);
+ expect(source.defaultRows, {
+ 'rest': 'idle',
+ 'working': isNot('idle'),
+ 'listening': 'idle',
+ 'sending': 'idle',
+ 'asking': 'waving',
+ });
+ // The prototype's row bands.
+ expect(
+ [
+ for (final r in rows)
+ (
+ r.map((f) => f.top).reduce((a, b) => a < b ? a : b),
+ r.map((f) => f.bottom).reduce((a, b) => a > b ? a : b),
+ ),
+ ],
+ [(40, 225), (291, 482), (553, 733), (774, 1066)],
+ );
+ expect(source.defaultRows!['working'], 'runningLeft');
+ // Composed, the tallest frame fills its cell less the 4 px margins; the
+ // shortest row is not much less.
+ final sheet = composeSheet(rgba, w, rows);
+ final heights = [
+ for (var r = 0; r < 4; r++)
+ for (var c = 0; c < 5; c++) _box(sheet, r, c).height,
+ ];
+ expect(heights.reduce((a, b) => a > b ? a : b), inInclusiveRange(198, 200));
+ expect(heights.reduce((a, b) => a < b ? a : b), greaterThan(208 * .8));
+ for (var r = 0; r < 4; r++) {
+ for (var c = 0; c < 5; c++) {
+ final box = _box(sheet, r, c);
+ expect(box.top, greaterThanOrEqualTo(4), reason: 'r$r c$c');
+ expect(box.bottom, lessThanOrEqualTo(208 - 4), reason: 'r$r c$c');
+ }
+ }
+ await tester.runAsync(source.cleanup);
+ }, skip: !File(real).existsSync());
+}
diff --git a/desktop/test/pet_settings_test.dart b/desktop/test/pet_settings_test.dart
new file mode 100644
index 000000000..80abffe4e
--- /dev/null
+++ b/desktop/test/pet_settings_test.dart
@@ -0,0 +1,1526 @@
+import 'dart:async';
+import 'dart:convert';
+import 'dart:io';
+import 'dart:typed_data';
+import 'dart:ui' as ui;
+
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/devices/devices_controller.dart';
+import 'package:harness/devices/devices_screen.dart';
+import 'package:harness/devices/loose_sheet.dart' show petRows;
+import 'package:harness/devices/pet_editor.dart' show petStateLabels;
+import 'package:harness/devices/pet_settings.dart';
+import 'package:harness/devices/pet_source.dart';
+import 'package:harness/shared/theme/app_theme.dart' as grid;
+import 'package:harness/state/dial_status.dart';
+
+import 'devices_controller_test.dart' show deviceStatus, report;
+import 'support/real_fonts.dart';
+
+/// A 1 x 1 transparent PNG, as the daemon sends it: a data URL.
+final _png =
+ 'data:image/png;base64,${base64Encode(base64Decode('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=='))}';
+
+Map<String, dynamic> _preview() => {
+ 'ok': true,
+ 'id': 'boba',
+ 'bytes': 412 * 1024,
+ 'colours': 87,
+ 'warnings': ['Soft edges will look jagged on the dial'],
+ 'frames': {
+ 'small': [_png, _png],
+ 'working': [_png],
+ 'listening': [_png],
+ 'sending': [_png],
+ 'asking': [_png, _png, _png],
+ },
+ 'stepMs': {
+ 'small': 200,
+ 'working': 120,
+ 'listening': 160,
+ 'sending': 160,
+ 'asking': 90,
+ },
+};
+
+/// A preview of a sheet with [rows] non-empty, each with a strip.
+Map<String, dynamic> sheetPreview(
+ String id,
+ List<String> rows, {
+ Map<String, String>? mapping,
+ int frames = 4,
+}) => _preview()
+ ..['id'] = id
+ ..['rows'] =
+ mapping ??
+ {
+ 'rest': 'idle',
+ 'working': 'running',
+ 'listening': 'review',
+ 'sending': 'waving',
+ 'asking': 'waiting',
+ }
+ ..['sheetRows'] = [
+ for (final row in rows) {'row': row, 'frames': frames, 'strip': _png},
+ ];
+
+class _Daemon {
+ Map<String, dynamic> mapping = {'all': null, 'engines': <String, String>{}};
+ bool supported = true;
+ Map<String, dynamic>? sending;
+ List<String> held = [];
+ Map<String, String> errors = {};
+ Map<String, dynamic>? pets;
+ Map<String, dynamic>? statusError;
+
+ /// Called on each pet_status, to move the dial along.
+ void Function()? onStatus;
+ Map<String, dynamic> previewReply = _preview();
+
+ /// Answers pet_preview in place of [previewReply] when set.
+ Future<Map<String, dynamic>> Function(Map<String, Object?> payload)?
+ onPreview;
+ Map<String, dynamic>? applyReply;
+ final requests = <String>[];
+ final payloads = <String, List<Map<String, Object?>>>{};
+
+ Future<Map<String, dynamic>> call(
+ String machine,
+ String type,
+ Map<String, Object?> payload,
+ ) async {
+ requests.add(type);
+ (payloads[type] ??= []).add(payload);
+ switch (type) {
+ case 'pet_status':
+ onStatus?.call();
+ if (statusError != null) return statusError!;
+ return {
+ 'mapping': mapping,
+ 'pets': ?pets,
+ 'dial': {
+ 'supported': supported,
+ 'held': held,
+ 'sending': sending,
+ if (errors.isNotEmpty) 'errors': errors,
+ },
+ };
+ case 'pet_preview':
+ return onPreview?.call(payload) ?? previewReply;
+ case 'pet_apply':
+ if (applyReply != null) return applyReply!;
+ final target = payload['target'] as String;
+ mapping = target == 'all'
+ ? {...mapping, 'all': payload['id']}
+ : {
+ ...mapping,
+ 'engines': {
+ ...(mapping['engines'] as Map),
+ target: payload['id'],
+ },
+ };
+ return {'ok': true, 'mapping': mapping};
+ default:
+ final target = payload['target'] as String;
+ mapping = target == 'all'
+ ? {...mapping, 'all': null}
+ : {
+ ...mapping,
+ 'engines': {...(mapping['engines'] as Map)}..remove(target),
+ };
+ return {'ok': true, 'mapping': mapping};
+ }
+ }
+}
+
+void main() {
+ var daemon = _Daemon();
+ setUp(() => daemon = _Daemon());
+
+ late DevicesController controller;
+ late DialState dial;
+
+ Future<void> build(
+ WidgetTester tester, {
+ bool attached = true,
+ Future<String?> Function()? pick,
+ Future<PetSource> Function(String path)? resolve,
+ Future<PetSheet?> Function(String path)? loadSheet,
+ Size size = const Size(1200, 2400),
+ }) async {
+ dial = DialState();
+ controller = DevicesController(
+ dial: dial,
+ accountId: 'pets',
+ sendSettings: (_, _) async => true,
+ petRequest: daemon.call,
+ );
+ await controller.load();
+ report(dial, [deviceStatus('one', attached: attached)]);
+ addTearDown(controller.dispose);
+ tester.view.physicalSize = size;
+ tester.view.devicePixelRatio = 1;
+ addTearDown(tester.view.resetPhysicalSize);
+ addTearDown(tester.view.resetDevicePixelRatio);
+ await tester.pumpWidget(
+ MaterialApp(
+ theme: grid.buildAppTheme(brightness: Brightness.light),
+ home: Scaffold(
+ body: SingleChildScrollView(
+ child: PetSettingsSection(
+ device: controller.devices.single,
+ controller: controller,
+ pickFile: pick ?? () async => '/tmp/boba.png',
+ resolveSource: resolve,
+ loadSheet: loadSheet ?? (_) async => null,
+ ),
+ ),
+ ),
+ ),
+ );
+ await tester.pumpAndSettle();
+ addTearDown(() => tester.pumpWidget(const SizedBox()));
+ }
+
+ testWidgets('locked when the dial lacks pets', (tester) async {
+ daemon.supported = false;
+ await build(tester);
+ expect(
+ find.text('Update the dial’s firmware to use custom pets'),
+ findsOneWidget,
+ );
+ final choose = tester.widget<OutlinedButton>(
+ find.widgetWithText(OutlinedButton, 'Choose file…'),
+ );
+ expect(choose.onPressed, isNull);
+ });
+
+ testWidgets('one row for every agent, no per-engine choice', (tester) async {
+ daemon
+ ..held = ['boba', 'old', 'older']
+ ..mapping = {
+ 'all': null,
+ 'engines': {'claude': 'old'},
+ };
+ await build(tester);
+ expect(find.text('Pet'), findsOneWidget);
+ expect(find.text('Default'), findsOneWidget);
+ expect(find.byKey(const ValueKey('pet-row-all')), findsOneWidget);
+ expect(find.text('Per engine'), findsNothing);
+ expect(find.text('Apply to all'), findsNothing);
+ expect(find.byType(SegmentedButton<bool>), findsNothing);
+ expect(find.text('Choose file…'), findsOneWidget);
+ expect(find.text('Choose folder…'), findsOneWidget);
+ expect(find.text('Download template'), findsNothing);
+ expect(find.textContaining('petdex.dev'), findsOneWidget);
+ });
+
+ testWidgets('apply sets all, then resets engine pets left from before', (
+ tester,
+ ) async {
+ daemon
+ ..held = ['boba', 'old', 'older']
+ ..mapping = {
+ 'all': null,
+ 'engines': {'claude': 'old', 'codex': 'older'},
+ };
+ await build(tester);
+ await tester.tap(find.text('Choose file…'));
+ await tester.pumpAndSettle();
+ daemon.requests.clear();
+ daemon.payloads.clear();
+ await tester.tap(find.text('Apply'));
+ await tester.pumpAndSettle();
+ expect(daemon.payloads['pet_apply'], [
+ {'target': 'all', 'id': 'boba'},
+ ]);
+ expect(
+ {for (final r in daemon.payloads['pet_reset']!) r['target']},
+ {'claude', 'codex'},
+ );
+ expect(
+ daemon.requests.indexOf('pet_apply'),
+ lessThan(daemon.requests.indexOf('pet_reset')),
+ );
+ expect(daemon.mapping, {'all': 'boba', 'engines': <String, String>{}});
+ });
+
+ testWidgets('a failed apply leaves the engine pets alone', (tester) async {
+ daemon
+ ..held = ['boba', 'old', 'older']
+ ..mapping = {
+ 'all': null,
+ 'engines': {'claude': 'old'},
+ };
+ await build(tester);
+ await tester.tap(find.text('Choose file…'));
+ await tester.pumpAndSettle();
+ daemon.applyReply = {'error': 'TOO_MANY', 'message': 'Up to 4 pets'};
+ await tester.tap(find.text('Apply'));
+ await tester.pumpAndSettle();
+ expect(find.text('Up to 4 pets'), findsOneWidget);
+ expect(daemon.payloads['pet_reset'], isNull);
+ });
+
+ testWidgets('a folder with pet.json previews under the pet\u2019s own name', (
+ tester,
+ ) async {
+ final dir = Directory.systemTemp.createTempSync('pet-folder-');
+ addTearDown(() => dir.deleteSync(recursive: true));
+ File('${dir.path}/sheet.png').writeAsBytesSync([1, 2, 3]);
+ File('${dir.path}/pet.json').writeAsStringSync(
+ jsonEncode({'displayName': 'ddo', 'spritesheetPath': 'sheet.png'}),
+ );
+ await build(tester, pick: () async => dir.path);
+ await tester.runAsync(() async {
+ await tester.tap(find.text('Choose file…'));
+ await Future<void>.delayed(const Duration(milliseconds: 200));
+ });
+ await tester.pumpAndSettle();
+ final sent = daemon.payloads['pet_preview']!.single;
+ expect((sent['path'] as String).endsWith('/sheet.png'), isTrue);
+ expect(sent['name'], 'ddo');
+ expect(find.text('Apply'), findsOneWidget);
+ });
+
+ testWidgets('an unsupported file shows a message and asks nothing', (
+ tester,
+ ) async {
+ await build(tester, pick: () async => '/tmp/boba.gif');
+ await tester.tap(find.text('Choose file…'));
+ await tester.pumpAndSettle();
+ expect(daemon.payloads['pet_preview'], isNull);
+ expect(find.textContaining('Choose a pet folder'), findsOneWidget);
+ });
+
+ testWidgets('choosing a file shows the dial previews and size', (
+ tester,
+ ) async {
+ await build(tester);
+ await tester.tap(find.text('Choose file…'));
+ await tester.pumpAndSettle();
+ expect(find.text('On the dial'), findsOneWidget);
+ for (final label in ['Rest', 'Working', 'Asking']) {
+ expect(find.text(label), findsOneWidget);
+ }
+ expect(find.text('412 KB · 87 colours'), findsOneWidget);
+ expect(
+ find.text('Soft edges will look jagged on the dial'),
+ findsOneWidget,
+ );
+ expect(find.text('Apply'), findsOneWidget);
+ await tester.tap(find.text('Cancel'));
+ await tester.pumpAndSettle();
+ expect(find.text('Apply'), findsNothing);
+ });
+
+ testWidgets('a sheet error is shown in the row', (tester) async {
+ await build(tester);
+ daemon.previewReply = {
+ 'error': 'BAD_SIZE',
+ 'message': 'The sheet must be 1536 × 1872 (8 × 9 cells of 192 × 208)',
+ };
+ await tester.tap(find.text('Choose file…'));
+ await tester.pumpAndSettle();
+ expect(
+ find.text('The sheet must be 1536 × 1872 (8 × 9 cells of 192 × 208)'),
+ findsOneWidget,
+ );
+ expect(find.text('Apply'), findsNothing);
+ });
+
+ testWidgets('apply shows progress then On dial ✓', (tester) async {
+ await build(tester);
+ await tester.tap(find.text('Choose file…'));
+ await tester.pumpAndSettle();
+ daemon.sending = {'id': 'boba', 'percent': 40};
+ await tester.tap(find.text('Apply'));
+ await tester.pumpAndSettle();
+ expect(find.text('Sending to dial… 40 %'), findsOneWidget);
+ daemon
+ ..sending = null
+ ..held = ['boba'];
+ await tester.pump(const Duration(seconds: 1));
+ await tester.pumpAndSettle();
+ expect(find.text('Sending to dial… 40 %'), findsNothing);
+ expect(find.text('On dial ✓'), findsOneWidget);
+ });
+
+ testWidgets('reset clears all and every engine entry', (tester) async {
+ await build(tester);
+ daemon.mapping = {
+ 'all': 'boba',
+ 'engines': {'claude': 'old', 'muse': 'older'},
+ };
+ await controller.refreshPetStatus(controller.devices.single.key);
+ await tester.pumpAndSettle();
+ expect(find.text('Custom pet'), findsOneWidget);
+ await tester.tap(find.text('Reset'));
+ await tester.pumpAndSettle();
+ expect(find.text('Default'), findsOneWidget);
+ expect(find.text('Custom pet'), findsNothing);
+ expect(
+ {for (final r in daemon.payloads['pet_reset']!) r['target']},
+ {'all', 'claude', 'muse'},
+ );
+ expect(daemon.mapping, {'all': null, 'engines': <String, String>{}});
+ });
+
+ Future<void> chooseAndApply(WidgetTester tester) async {
+ await tester.tap(find.text('Choose file…'));
+ await tester.pumpAndSettle();
+ await tester.tap(find.text('Apply'));
+ await tester.pumpAndSettle();
+ }
+
+ testWidgets('a stranded apply keeps polling until the pet is on the dial', (
+ tester,
+ ) async {
+ await build(tester);
+ // After apply the dial reports nothing sending and nothing held yet.
+ await chooseAndApply(tester);
+ expect(find.text('Waiting for the dial…'), findsOneWidget);
+ daemon.sending = {'id': 'boba', 'percent': 55};
+ await tester.pump(const Duration(seconds: 1));
+ await tester.pumpAndSettle();
+ expect(find.text('Sending to dial… 55 %'), findsOneWidget);
+ expect(find.text('Waiting for the dial…'), findsNothing);
+ daemon
+ ..sending = null
+ ..held = ['boba'];
+ await tester.pump(const Duration(seconds: 1));
+ await tester.pumpAndSettle();
+ expect(find.text('On dial ✓'), findsOneWidget);
+ final polled = daemon.requests.length;
+ await tester.pump(const Duration(seconds: 5));
+ expect(daemon.requests.length, polled, reason: 'poll stopped');
+ });
+
+ testWidgets('the poll gives up after two minutes', (tester) async {
+ await build(tester);
+ await chooseAndApply(tester);
+ await tester.pump(const Duration(seconds: 121));
+ final polled = daemon.requests.length;
+ await tester.pump(const Duration(seconds: 10));
+ expect(daemon.requests.length, polled);
+ });
+
+ testWidgets('without a dial the row says it will be sent on connect', (
+ tester,
+ ) async {
+ daemon.mapping = {'all': 'boba', 'engines': <String, String>{}};
+ await build(tester, attached: false);
+ expect(find.text('Will be sent when the dial connects'), findsOneWidget);
+ expect(find.text('Waiting for the dial…'), findsNothing);
+ });
+
+ for (final (code, text) in [
+ ('memory', 'The dial is out of memory for pets'),
+ ('busy', 'The dial holds too many pets'),
+ ('crc', 'The pet didn’t arrive intact. Reconnect the dial to try again'),
+ ('shape', 'The pet didn’t arrive intact. Reconnect the dial to try again'),
+ ('version', 'Update the dial’s firmware for this pet'),
+ ('timeout', 'The dial stopped answering. Reconnect it to try again'),
+ ]) {
+ testWidgets('dial error $code is shown in the row', (tester) async {
+ daemon
+ ..mapping = {'all': 'boba', 'engines': <String, String>{}}
+ ..errors = {'boba': code};
+ await build(tester);
+ expect(find.text(text), findsOneWidget);
+ expect(find.text('Waiting for the dial…'), findsNothing);
+ });
+ }
+
+ testWidgets('rows show the pet name and thumbnail, not the pack id', (
+ tester,
+ ) async {
+ daemon
+ ..mapping = {'all': 'boba-1a2b', 'engines': <String, String>{}}
+ ..held = ['boba-1a2b']
+ ..pets = {
+ 'boba-1a2b': {'name': 'Boba', 'thumb': _png},
+ };
+ await build(tester);
+ expect(find.text('Boba'), findsOneWidget);
+ expect(find.text('boba-1a2b'), findsNothing);
+ final tile = find.byKey(const ValueKey('pet-thumb-all'));
+ expect(tester.getSize(tile), const Size(44, 44));
+ expect(
+ find.descendant(of: tile, matching: find.byType(Image)),
+ findsOneWidget,
+ );
+ });
+
+ /// The frame cycler of the dial preview for [scene].
+ dynamic dialCycler(WidgetTester tester, String scene) => tester.widget(
+ find.descendant(
+ of: find.byKey(ValueKey('pet-dial-$scene-boba')),
+ matching: find.byWidgetPredicate(
+ (w) => w.runtimeType.toString() == '_FrameCycler',
+ ),
+ ),
+ );
+
+ testWidgets('the Asking preview plays the asking frames when sent', (
+ tester,
+ ) async {
+ await build(tester);
+ await tester.tap(find.text('Choose file…'));
+ await tester.pumpAndSettle();
+ final asking = dialCycler(tester, 'asking');
+ expect(asking.frames.length, 3);
+ expect(asking.stepMs, 90);
+ final working = dialCycler(tester, 'working');
+ expect(working.frames.length, 1);
+ expect(working.stepMs, 120);
+ });
+
+ testWidgets('the Asking preview falls back to the small pet', (tester) async {
+ daemon.previewReply = _preview()
+ ..['frames'] = {
+ 'small': [_png, _png],
+ }
+ ..['stepMs'] = {'small': 200};
+ await build(tester);
+ await tester.tap(find.text('Choose file…'));
+ await tester.pumpAndSettle();
+ final asking = dialCycler(tester, 'asking');
+ expect(asking.frames.length, 2);
+ expect(asking.stepMs, 200);
+ });
+
+ testWidgets('locked when the daemon lacks pet requests', (tester) async {
+ daemon.statusError = {'error': 'UNSUPPORTED', 'message': 'nope'};
+ await build(tester);
+ expect(
+ find.text('Update Harness on this computer to use custom pets'),
+ findsOneWidget,
+ );
+ final choose = tester.widget<OutlinedButton>(
+ find.widgetWithText(OutlinedButton, 'Choose file…'),
+ );
+ expect(choose.onPressed, isNull);
+ });
+
+ testWidgets('an unreachable daemon stops the poll and clears progress', (
+ tester,
+ ) async {
+ await build(tester);
+ daemon.sending = {'id': 'boba', 'percent': 40};
+ await chooseAndApply(tester);
+ expect(find.text('Sending to dial… 40 %'), findsOneWidget);
+ daemon.statusError = {'error': 'UNREACHABLE', 'message': 'down'};
+ await tester.pump(const Duration(seconds: 1));
+ await tester.pumpAndSettle();
+ expect(find.text('Sending to dial… 40 %'), findsNothing);
+ final polled = daemon.requests.length;
+ await tester.pump(const Duration(seconds: 5));
+ expect(daemon.requests.length, polled);
+ });
+
+ group('row viewer', () {
+ Finder card(String row) => find.byKey(ValueKey('pet-sheet-row-$row'));
+ Finder chip(String state) => find.byKey(ValueKey('pet-state-$state'));
+ Finder inCard(String row, String text) =>
+ find.descendant(of: card(row), matching: find.text(text));
+ String title(WidgetTester tester) => tester
+ .widget<Text>(find.byKey(const ValueKey('pet-viewer-title')))
+ .data!;
+ bool chipOn(WidgetTester tester, String state) => tester
+ .widget<Semantics>(
+ find
+ .descendant(of: chip(state), matching: find.byType(Semantics))
+ .first,
+ )
+ .properties
+ .selected!;
+ int frame(WidgetTester tester) => (tester.widget(
+ find.byKey(const ValueKey('pet-viewer-art')),
+ ) as dynamic).index;
+ FilledButton apply(WidgetTester tester) =>
+ tester.widget<FilledButton>(find.widgetWithText(FilledButton, 'Apply'));
+
+ /// Shows [row] in the viewer, then moves [state] onto it.
+ Future<void> move(WidgetTester tester, String state, String row) async {
+ await tester.tap(card(row));
+ await tester.pump();
+ await tester.tap(chip(state));
+ await tester.pump();
+ }
+
+ const petdexRows = [
+ 'idle',
+ 'runningRight',
+ 'waving',
+ 'waiting',
+ 'running',
+ 'review',
+ ];
+
+ testWidgets('a petdex sheet lists a card per row, viewing Working’s', (
+ tester,
+ ) async {
+ daemon.previewReply = sheetPreview('boba', petdexRows);
+ await build(tester);
+ await tester.tap(find.text('Choose file…'));
+ await tester.pumpAndSettle();
+ // The first preview leaves the mapping to the daemon.
+ expect(daemon.payloads['pet_preview']!.single.containsKey('rows'), false);
+ for (final (row, label) in [
+ ('idle', 'Idle'),
+ ('runningRight', 'Running right'),
+ ('running', 'Running'),
+ ('review', 'Review'),
+ ]) {
+ expect(inCard(row, label), findsOneWidget);
+ expect(inCard(row, '4 frames'), findsOneWidget);
+ }
+ expect(card('jumping'), findsNothing);
+ for (final (state, row) in [
+ ('Rest', 'idle'),
+ ('Working', 'running'),
+ ('Listening', 'review'),
+ ('Sending', 'waving'),
+ ('Asking', 'waiting'),
+ ]) {
+ expect(inCard(row, state), findsOneWidget);
+ }
+ expect(inCard('runningRight', 'Working'), findsNothing);
+ expect(title(tester), 'Running');
+ expect(chipOn(tester, 'working'), isTrue);
+ expect(chipOn(tester, 'rest'), isFalse);
+ expect(find.text('Running plays on the dial as'), findsOneWidget);
+ expect(find.text('6 rows found · 412 KB · 87 colours'), findsOneWidget);
+ expect(find.textContaining('Background removed'), findsNothing);
+ expect(find.text('boba · not applied yet'), findsOneWidget);
+ });
+
+ testWidgets('tapping a card shows that row in the viewer', (tester) async {
+ daemon.previewReply = sheetPreview('boba', petdexRows);
+ await build(tester);
+ await tester.tap(find.text('Choose file…'));
+ await tester.pumpAndSettle();
+ await tester.tap(card('idle'));
+ await tester.pump();
+ expect(title(tester), 'Idle');
+ expect(chipOn(tester, 'rest'), isTrue);
+ expect(chipOn(tester, 'working'), isFalse);
+ expect(daemon.payloads['pet_preview']!.length, 1, reason: 'only viewed');
+ });
+
+ testWidgets('a chip moves its state here and asks again, debounced', (
+ tester,
+ ) async {
+ daemon.held = ['boba-2'];
+ daemon.previewReply = sheetPreview('boba', petdexRows);
+ await build(tester);
+ await tester.tap(find.text('Choose file…'));
+ await tester.pumpAndSettle();
+ daemon.previewReply = sheetPreview(
+ 'boba-2',
+ petdexRows,
+ mapping: {
+ 'rest': 'idle',
+ 'working': 'runningRight',
+ 'listening': 'waving',
+ 'sending': 'waving',
+ 'asking': 'waiting',
+ },
+ );
+ await move(tester, 'working', 'runningRight');
+ expect(chipOn(tester, 'working'), isTrue);
+ expect(inCard('runningRight', 'Working'), findsOneWidget);
+ expect(inCard('running', 'Working'), findsNothing, reason: 'moved');
+ await tester.pump(const Duration(milliseconds: 100));
+ await move(tester, 'listening', 'waving');
+ expect(apply(tester).onPressed, isNull, reason: 'preview is outdated');
+ await tester.pump(const Duration(milliseconds: 200));
+ expect(daemon.payloads['pet_preview']!.length, 1, reason: 'debounced');
+ await tester.pump(const Duration(milliseconds: 100));
+ await tester.pumpAndSettle();
+ final sent = daemon.payloads['pet_preview']!;
+ expect(sent.length, 2);
+ expect(sent.last['rows'], {
+ 'rest': 'idle',
+ 'working': 'runningRight',
+ 'listening': 'waving',
+ 'sending': 'waving',
+ 'asking': 'waiting',
+ });
+ expect(sent.last['path'], sent.first['path']);
+ expect(inCard('waving', 'Listening'), findsOneWidget);
+ expect(inCard('review', 'Listening'), findsNothing);
+ expect(apply(tester).onPressed, isNotNull);
+ await tester.tap(find.text('Apply'));
+ await tester.pumpAndSettle();
+ expect(daemon.payloads['pet_apply'], [
+ {'target': 'all', 'id': 'boba-2'},
+ ]);
+ });
+
+ testWidgets('a stale reply is ignored; Apply takes the latest preview', (
+ tester,
+ ) async {
+ daemon.held = ['newest'];
+ daemon.previewReply = sheetPreview('boba', petdexRows);
+ await build(tester);
+ await tester.tap(find.text('Choose file…'));
+ await tester.pumpAndSettle();
+ final replies = <Completer<Map<String, dynamic>>>[];
+ daemon.onPreview = (_) {
+ final reply = Completer<Map<String, dynamic>>();
+ replies.add(reply);
+ return reply.future;
+ };
+ await move(tester, 'working', 'waving');
+ await tester.pump(const Duration(milliseconds: 300));
+ await move(tester, 'working', 'review');
+ await tester.pump(const Duration(milliseconds: 300));
+ expect(replies.length, 2);
+ replies[1].complete(
+ sheetPreview(
+ 'newest',
+ petdexRows,
+ mapping: {
+ 'rest': 'idle',
+ 'working': 'review',
+ 'listening': 'review',
+ 'sending': 'waving',
+ 'asking': 'waiting',
+ },
+ ),
+ );
+ await tester.pump();
+ replies[0].complete(sheetPreview('older', petdexRows));
+ await tester.pumpAndSettle();
+ expect(inCard('review', 'Working'), findsOneWidget);
+ expect(inCard('waving', 'Working'), findsNothing);
+ await tester.tap(find.text('Apply'));
+ await tester.pumpAndSettle();
+ expect(daemon.payloads['pet_apply'], [
+ {'target': 'all', 'id': 'newest'},
+ ]);
+ });
+
+ testWidgets('an empty chosen row shows the daemon’s message', (
+ tester,
+ ) async {
+ daemon.previewReply = sheetPreview('boba', petdexRows);
+ await build(tester);
+ await tester.tap(find.text('Choose file…'));
+ await tester.pumpAndSettle();
+ daemon.previewReply = {
+ 'error': 'EMPTY_ROW',
+ 'message': 'The waving row is empty',
+ };
+ await move(tester, 'rest', 'waving');
+ await tester.pump(const Duration(milliseconds: 300));
+ await tester.pumpAndSettle();
+ expect(find.text('The waving row is empty'), findsOneWidget);
+ expect(card('idle'), findsOneWidget);
+ expect(apply(tester).onPressed, isNull);
+ });
+
+ testWidgets('play pauses and resumes; a scrubber tile holds its frame', (
+ tester,
+ ) async {
+ daemon.previewReply = sheetPreview('boba', petdexRows);
+ await build(tester);
+ await tester.tap(find.text('Choose file…'));
+ await tester.pump();
+ await tester.pump();
+ final start = frame(tester);
+ await tester.pump(const Duration(milliseconds: 120));
+ expect(frame(tester), (start + 1) % 4, reason: 'plays at 120 ms');
+ final play = find.byKey(const ValueKey('pet-viewer-play'));
+ expect(
+ find.descendant(of: play, matching: find.text('4 frames')),
+ findsOneWidget,
+ );
+ await tester.tap(play);
+ await tester.pump();
+ final paused = frame(tester);
+ await tester.pump(const Duration(milliseconds: 600));
+ expect(frame(tester), paused, reason: 'paused');
+ await tester.tap(play);
+ await tester.pump(const Duration(milliseconds: 120));
+ expect(frame(tester), (paused + 1) % 4, reason: 'playing again');
+ await tester.tap(find.byKey(const ValueKey('pet-viewer-frame-2')));
+ await tester.pump();
+ expect(frame(tester), 2);
+ await tester.pump(const Duration(milliseconds: 600));
+ expect(frame(tester), 2, reason: 'a tile pauses on its frame');
+ final tile = tester.widget<Container>(
+ find
+ .descendant(
+ of: find.byKey(const ValueKey('pet-viewer-frame-2')),
+ matching: find.byType(Container),
+ )
+ .first,
+ );
+ expect(
+ ((tile.decoration as BoxDecoration).border as Border).top.width,
+ 1.5,
+ reason: 'highlighted',
+ );
+ });
+
+ testWidgets('the viewer draws the local sheet at full size', (
+ tester,
+ ) async {
+ final image = (await tester.runAsync(
+ () => createTestImage(width: 8 * 96, height: 9 * 104, cache: false),
+ ))!;
+ daemon.previewReply = sheetPreview('boba', petdexRows);
+ final read = <String>[];
+ await build(
+ tester,
+ loadSheet: (path) async {
+ read.add(path);
+ return PetSheet(image);
+ },
+ );
+ await tester.tap(find.text('Choose file…'));
+ await tester.pumpAndSettle();
+ expect(read, ['/tmp/boba.png']);
+ final painter =
+ tester
+ .widget<CustomPaint>(
+ find.descendant(
+ of: find.byKey(const ValueKey('pet-viewer-art')),
+ matching: find.byType(CustomPaint),
+ ),
+ )
+ .painter!
+ as dynamic;
+ // Row "running" is sheet row 7; cells are 96 x 104.
+ final Rect source = painter.source;
+ expect(source.top, 7 * 104);
+ expect(source.size, const Size(96, 104));
+ expect(
+ find.byType(Image).evaluate().where((e) {
+ final w = e.widget as Image;
+ return w.image is MemoryImage &&
+ find
+ .descendant(
+ of: find.byKey(const ValueKey('pet-viewer-art')),
+ matching: find.byWidget(w),
+ )
+ .evaluate()
+ .isNotEmpty;
+ }),
+ isEmpty,
+ reason: 'no daemon strip in the viewer',
+ );
+ });
+
+ testWidgets('the viewer and the cards crop to the row’s art', (
+ tester,
+ ) async {
+ final image = (await tester.runAsync(
+ () => createTestImage(width: 8 * 96, height: 9 * 104, cache: false),
+ ))!;
+ daemon.previewReply = sheetPreview('boba', petdexRows);
+ const art = Rect.fromLTRB(30, 40, 70, 100);
+ await build(
+ tester,
+ loadSheet: (_) async =>
+ PetSheet(image, crops: [for (var r = 0; r < 9; r++) art]),
+ );
+ await tester.tap(find.text('Choose file…'));
+ await tester.pumpAndSettle();
+ Rect source(Finder of) =>
+ (tester
+ .widget<CustomPaint>(
+ find
+ .descendant(
+ of: of,
+ matching: find.byType(CustomPaint),
+ )
+ .last,
+ )
+ .painter!
+ as dynamic)
+ .source;
+ final viewed = frame(tester);
+ expect(
+ source(find.byKey(const ValueKey('pet-viewer-art'))),
+ art.shift(Offset(viewed * 96.0, 7 * 104)),
+ reason: 'row "running" is sheet row 7',
+ );
+ expect(
+ source(find.byKey(const ValueKey('pet-viewer-frame-2'))),
+ art.shift(const Offset(2 * 96.0, 7 * 104)),
+ );
+ expect(source(card('idle')), art, reason: 'frame 0 of row 0');
+ });
+
+ testWidgets('a card’s badges stay on one line, the rest as +n', (
+ tester,
+ ) async {
+ daemon.previewReply = sheetPreview(
+ 'boba',
+ petdexRows,
+ mapping: {for (final s in petStateLabels.keys) s: 'idle'},
+ );
+ await build(tester, size: const Size(560, 2400));
+ await tester.tap(find.text('Choose file…'));
+ await tester.pumpAndSettle();
+ expect(tester.takeException(), isNull);
+ final shown = [
+ for (final label in petStateLabels.values)
+ if (tester.any(inCard('idle', label))) label,
+ ];
+ expect(shown, isNotEmpty);
+ expect(shown.length, lessThan(5));
+ expect(shown, petStateLabels.values.take(shown.length));
+ final more = inCard('idle', '+${5 - shown.length}');
+ expect(more, findsOneWidget);
+ final line = tester.getCenter(more).dy;
+ for (final label in shown) {
+ expect(tester.getCenter(inCard('idle', label)).dy, line);
+ }
+ final box = tester.getRect(card('idle'));
+ expect(tester.getRect(more).right, lessThanOrEqualTo(box.right));
+ expect(
+ tester.getRect(inCard('idle', shown.first)).top,
+ greaterThan(tester.getRect(inCard('idle', '4 frames')).bottom),
+ reason: 'under the title, at the bottom',
+ );
+ // Every card of the grid is as tall.
+ expect({
+ for (final row in petdexRows) tester.getSize(card(row)).height,
+ }, hasLength(1));
+ });
+
+ testWidgets('the choosers sit side by side, folder first', (tester) async {
+ await build(tester);
+ final folder = tester.getRect(find.text('Choose folder…'));
+ final file = tester.getRect(find.text('Choose file…'));
+ expect(folder.center.dy, file.center.dy);
+ expect(folder.right, lessThan(file.left));
+ expect(
+ file.center.dy,
+ lessThan(tester.getRect(find.text('Default')).bottom),
+ reason: 'beside All agents',
+ );
+ });
+
+ testWidgets('a loose sheet numbers its rows and sends the guess first', (
+ tester,
+ ) async {
+ var cleaned = 0;
+ const guess = {
+ 'rest': 'idle',
+ 'working': 'runningLeft',
+ 'listening': 'idle',
+ 'sending': 'idle',
+ 'asking': 'waving',
+ };
+ const loose = ['idle', 'runningRight', 'runningLeft', 'waving'];
+ daemon.previewReply = sheetPreview(
+ 'hero',
+ loose,
+ mapping: guess,
+ frames: 5,
+ );
+ await build(
+ tester,
+ pick: () async => '/tmp/hero.jpeg',
+ resolve: (path) async => PetSource(
+ pngPath: '/tmp/hero-sheet.png',
+ name: 'hero',
+ loose: true,
+ defaultRows: guess,
+ cleanup: () async => cleaned++,
+ ),
+ );
+ await tester.tap(find.text('Choose file…'));
+ await tester.pumpAndSettle();
+ final first = daemon.payloads['pet_preview']!.single;
+ expect(first['rows'], guess);
+ expect(first['name'], 'hero');
+ expect(
+ find.text(
+ 'Background removed · 4 rows × 5 frames found · 412 KB · 87 colours',
+ ),
+ findsOneWidget,
+ );
+ expect(find.text('hero · not applied yet'), findsOneWidget);
+ for (final (i, row) in loose.indexed) {
+ expect(inCard(row, 'Row ${i + 1}'), findsOneWidget);
+ }
+ expect(title(tester), 'Row 3');
+ expect(cleaned, 0, reason: 'kept for the next row choice');
+ await move(tester, 'working', 'waving');
+ expect(title(tester), 'Row 4');
+ await tester.pump(const Duration(milliseconds: 300));
+ await tester.pumpAndSettle();
+ expect(daemon.payloads['pet_preview']!.last['rows'], {
+ ...guess,
+ 'working': 'waving',
+ });
+ expect(
+ daemon.payloads['pet_preview']!.last['path'],
+ '/tmp/hero-sheet.png',
+ );
+ await tester.tap(find.text('Cancel'));
+ await tester.pumpAndSettle();
+ expect(cleaned, 1);
+ expect(card('idle'), findsNothing);
+ });
+
+ testWidgets('a daemon without sheet rows shows only the dial preview', (
+ tester,
+ ) async {
+ await build(tester);
+ await tester.tap(find.text('Choose file…'));
+ await tester.pumpAndSettle();
+ expect(find.textContaining('plays on the dial as'), findsNothing);
+ expect(find.byKey(const ValueKey('pet-viewer-title')), findsNothing);
+ expect(chip('rest'), findsNothing);
+ expect(find.text('On the dial'), findsOneWidget);
+ expect(find.text('Apply'), findsOneWidget);
+ });
+ });
+ group('editor', () {
+ const petdexRows = ['idle', 'runningRight', 'waving', 'waiting', 'running'];
+
+ /// An editor for one attached dial; [cleaned] counts each source's
+ /// cleanup by its path.
+ Future<PetEditor> editor(
+ WidgetTester tester,
+ Map<String, int> cleaned, {
+ Future<PetSheet?> Function(String path)? loadSheet,
+ }) async {
+ final dial = DialState();
+ final controller = DevicesController(
+ dial: dial,
+ accountId: 'pets',
+ sendSettings: (_, _) async => true,
+ petRequest: daemon.call,
+ );
+ await controller.load();
+ report(dial, [deviceStatus('one')]);
+ addTearDown(controller.dispose);
+ final editor = PetEditor(
+ controller: controller,
+ deviceKey: controller.devices.single.key,
+ resolveSource: (path) async => PetSource(
+ pngPath: path,
+ name: 'boba',
+ cleanup: () async => cleaned[path] = (cleaned[path] ?? 0) + 1,
+ ),
+ loadSheet: loadSheet ?? (_) async => null,
+ );
+ return editor;
+ }
+
+ testWidgets('a move debounces one re-request; Apply sends its id', (
+ tester,
+ ) async {
+ daemon
+ ..held = ['boba-2']
+ ..previewReply = sheetPreview('boba', petdexRows);
+ final cleaned = <String, int>{};
+ final pet = await editor(tester, cleaned);
+ await pet.use('/tmp/a.png');
+ expect(pet.editing, isTrue);
+ expect(pet.viewedRow!.row, 'running', reason: 'starts on Working’s');
+ expect(pet.playback.playing, isTrue);
+ pet.view('idle');
+ expect(pet.viewedRow!.row, 'idle');
+ daemon.previewReply = sheetPreview(
+ 'boba-2',
+ petdexRows,
+ mapping: {
+ 'rest': 'idle',
+ 'working': 'idle',
+ 'listening': 'review',
+ 'sending': 'waving',
+ 'asking': 'waiting',
+ },
+ );
+ pet.choose('working', 'idle');
+ expect(pet.statesOf('idle'), ['rest', 'working']);
+ expect(pet.statesOf('running'), isEmpty);
+ expect(pet.current, isFalse);
+ await tester.pump(const Duration(milliseconds: 100));
+ pet.choose('asking', 'idle');
+ await tester.pump(const Duration(milliseconds: 200));
+ expect(daemon.payloads['pet_preview']!.length, 1, reason: 'debounced');
+ await tester.pump(const Duration(milliseconds: 100));
+ expect(daemon.payloads['pet_preview']!.length, 2);
+ expect(daemon.payloads['pet_preview']!.last['rows'], {
+ 'rest': 'idle',
+ 'working': 'idle',
+ 'listening': 'review',
+ 'sending': 'waving',
+ 'asking': 'idle',
+ });
+ expect(pet.current, isTrue);
+ expect(pet.preview!.id, 'boba-2');
+ await pet.apply();
+ expect(daemon.payloads['pet_apply'], [
+ {'target': 'all', 'id': 'boba-2'},
+ ]);
+ expect(pet.editing, isFalse);
+ expect(cleaned, {'/tmp/a.png': 1});
+ expect(pet.playback.playing, isFalse);
+ pet.dispose();
+ });
+
+ testWidgets('a stale reply is ignored', (tester) async {
+ daemon.previewReply = sheetPreview('boba', petdexRows);
+ final pet = await editor(tester, {});
+ await pet.use('/tmp/a.png');
+ final replies = <Completer<Map<String, dynamic>>>[];
+ daemon.onPreview = (_) {
+ final reply = Completer<Map<String, dynamic>>();
+ replies.add(reply);
+ return reply.future;
+ };
+ pet.choose('working', 'waving');
+ await tester.pump(const Duration(milliseconds: 300));
+ pet.choose('working', 'idle');
+ await tester.pump(const Duration(milliseconds: 300));
+ expect(replies.length, 2);
+ replies[1].complete(sheetPreview('newest', petdexRows));
+ await tester.pump();
+ replies[0].complete(sheetPreview('older', petdexRows));
+ await tester.pump();
+ expect(pet.preview!.id, 'newest');
+ expect(pet.current, isTrue);
+ pet.dispose();
+ });
+
+ testWidgets('cancel, a new pick and dispose clean up the sheet', (
+ tester,
+ ) async {
+ daemon.previewReply = sheetPreview('boba', petdexRows);
+ final image = (await tester.runAsync(
+ () => createTestImage(width: 8, height: 9, cache: false),
+ ))!;
+ final images = <ui.Image>[];
+ final cleaned = <String, int>{};
+ final pet = await editor(
+ tester,
+ cleaned,
+ loadSheet: (_) async {
+ if (images.isNotEmpty) return null;
+ images.add(image);
+ return PetSheet(image);
+ },
+ );
+ await pet.use('/tmp/a.png');
+ await tester.pump();
+ expect(pet.sheet, isNotNull);
+ pet.cancel();
+ expect(pet.editing, isFalse);
+ expect(pet.sheet, isNull);
+ expect(images.single.debugDisposed, isTrue);
+ expect(cleaned, {'/tmp/a.png': 1});
+ await pet.use('/tmp/b.png');
+ await pet.use('/tmp/c.png');
+ expect(cleaned, {'/tmp/a.png': 1, '/tmp/b.png': 1});
+ expect(pet.editing, isTrue);
+ pet.dispose();
+ expect(cleaned, {'/tmp/a.png': 1, '/tmp/b.png': 1, '/tmp/c.png': 1});
+ expect(pet.playback.playing, isFalse);
+ });
+ });
+
+ group('devices screen', () {
+ setUpAll(loadRealFonts);
+
+ Finder card(String row) => find.byKey(ValueKey('pet-sheet-row-$row'));
+ Finder chip(String state) => find.byKey(ValueKey('pet-state-$state'));
+ final viewer = find.byKey(const ValueKey('devices-pet-viewer'));
+ final panel = find.byKey(const ValueKey('pet-panel'));
+ String title(WidgetTester tester) => tester
+ .widget<Text>(find.byKey(const ValueKey('pet-viewer-title')))
+ .data!;
+ var cleaned = <String, int>{};
+
+ Future<void> screen(
+ WidgetTester tester, {
+ Size size = const Size(1280, 940),
+ Brightness brightness = Brightness.light,
+ int dials = 1,
+ }) async {
+ cleaned = {};
+ final dial = DialState();
+ controller = DevicesController(
+ dial: dial,
+ accountId: 'pets',
+ sendSettings: (_, _) async => true,
+ petRequest: daemon.call,
+ );
+ await controller.load();
+ report(dial, [
+ for (final id in ['one', 'two'].take(dials)) deviceStatus(id),
+ ]);
+ addTearDown(controller.dispose);
+ tester.view.physicalSize = size;
+ tester.view.devicePixelRatio = 1;
+ addTearDown(tester.view.resetPhysicalSize);
+ addTearDown(tester.view.resetDevicePixelRatio);
+ grid.AppTheme.brightness.value = brightness;
+ await tester.pumpWidget(
+ MaterialApp(
+ debugShowCheckedModeBanner: false,
+ theme: grid.buildAppTheme(brightness: brightness),
+ home: Scaffold(
+ body: DevicesScreen(
+ controller: controller,
+ pickPetFile: () async => '/tmp/boba.png',
+ resolvePetSource: (path) async => PetSource(
+ pngPath: path,
+ name: 'boba',
+ cleanup: () async => cleaned[path] = (cleaned[path] ?? 0) + 1,
+ ),
+ loadPetSheet: (_) async => null,
+ ),
+ ),
+ ),
+ );
+ await tester.pumpAndSettle();
+ addTearDown(() => tester.pumpWidget(const SizedBox()));
+ }
+
+ Future<void> choose(WidgetTester tester) async {
+ await tester.ensureVisible(find.text('Choose file…'));
+ await tester.pumpAndSettle();
+ await tester.tap(find.text('Choose file…'));
+ await tester.pumpAndSettle();
+ }
+
+ ScrollPosition page(WidgetTester tester) => tester
+ .state<ScrollableState>(
+ find
+ .descendant(
+ of: find.byKey(const PageStorageKey('devices-page')),
+ matching: find.byType(Scrollable),
+ )
+ .first,
+ )
+ .position;
+
+ testWidgets('the viewer sits in the left column, level with the Pet '
+ 'section, while the page stays as it is', (tester) async {
+ daemon.previewReply = sheetPreview('boba', petRows);
+ await screen(tester);
+ expect(viewer, findsNothing);
+ await choose(tester);
+ expect(viewer, findsOneWidget);
+ for (final text in [
+ 'Devices',
+ 'Brightness',
+ 'Sound',
+ 'Voice language',
+ 'Faces',
+ ]) {
+ expect(find.text(text), findsOneWidget, reason: text);
+ }
+ expect(
+ tester.getRect(viewer).right,
+ lessThan(tester.getRect(panel).left),
+ );
+ expect(
+ tester.getRect(viewer).top,
+ moreOrLessEquals(tester.getRect(panel).top, epsilon: .5),
+ reason: 'level with the Pet section',
+ );
+ expect(
+ tester.getRect(viewer).top,
+ greaterThan(
+ tester.getRect(find.byKey(const Key('devices-faces'))).bottom,
+ ),
+ reason: 'under what the left column holds',
+ );
+ expect(
+ find.descendant(of: panel, matching: find.byType(PetRowViewer)),
+ findsNothing,
+ reason: 'not drawn twice',
+ );
+ expect(title(tester), 'Running');
+ await tester.ensureVisible(card('idle'));
+ await tester.pumpAndSettle();
+ await tester.tap(card('idle'));
+ await tester.pump();
+ expect(title(tester), 'Idle');
+ expect(find.text('Idle plays on the dial as'), findsOneWidget);
+ await tester.ensureVisible(chip('working'));
+ await tester.pumpAndSettle();
+ await tester.tap(chip('working'));
+ await tester.pump();
+ expect(
+ find.descendant(of: card('idle'), matching: find.text('Working')),
+ findsOneWidget,
+ );
+ expect(
+ find.descendant(of: card('running'), matching: find.text('Working')),
+ findsNothing,
+ );
+ await tester.pump(const Duration(milliseconds: 300));
+ await tester.pumpAndSettle();
+ expect(
+ (daemon.payloads['pet_preview']!.last['rows'] as Map)['working'],
+ 'idle',
+ );
+ await tester.ensureVisible(find.text('Cancel'));
+ await tester.pumpAndSettle();
+ await tester.tap(find.text('Cancel'));
+ await tester.pumpAndSettle();
+ expect(viewer, findsNothing);
+ expect(find.text('Brightness'), findsOneWidget);
+ expect(cleaned, {'/tmp/boba.png': 1});
+ });
+
+ testWidgets('the viewer follows the Pet section as the page scrolls', (
+ tester,
+ ) async {
+ daemon.previewReply = sheetPreview('boba', petRows, frames: 8);
+ await screen(tester, size: const Size(1100, 560));
+ await choose(tester);
+ final position = page(tester);
+ // The Pet section's top 16 px under the window's.
+ final start = position.pixels + tester.getRect(panel).top - 16;
+ for (final down in [0.0, 40.0, 120.0]) {
+ position.jumpTo(start + down);
+ await tester.pump();
+ await tester.pump();
+ final v = tester.getRect(viewer), p = tester.getRect(panel);
+ expect(v.top, moreOrLessEquals(16, epsilon: .5), reason: '+$down');
+ expect(v.bottom, lessThanOrEqualTo(p.bottom + .5), reason: '+$down');
+ }
+ // Past the end of the Pet section, it stops at its bottom.
+ position.jumpTo(position.maxScrollExtent);
+ await tester.pump();
+ await tester.pump();
+ final v = tester.getRect(viewer), p = tester.getRect(panel);
+ expect(v.top, greaterThanOrEqualTo(p.top - .5));
+ expect(v.bottom, lessThanOrEqualTo(p.bottom + .5));
+ expect(tester.takeException(), isNull);
+ });
+
+ testWidgets('choosing another dial ends the edit and cleans up', (
+ tester,
+ ) async {
+ daemon.previewReply = sheetPreview('boba', petRows);
+ await screen(tester, dials: 2);
+ await choose(tester);
+ expect(viewer, findsOneWidget);
+ // The first dial is selected; the second takes over.
+ final other = find.byKey(
+ ValueKey('device-card-${controller.devices.last.key}'),
+ );
+ await tester.ensureVisible(other);
+ await tester.pumpAndSettle();
+ await tester.tap(other);
+ await tester.pumpAndSettle();
+ expect(
+ tester
+ .widget<Semantics>(
+ find.ancestor(of: other, matching: find.byType(Semantics)).first,
+ )
+ .properties
+ .selected,
+ isTrue,
+ );
+ expect(viewer, findsNothing);
+ expect(find.text('Apply'), findsNothing);
+ expect(find.text('Brightness'), findsOneWidget);
+ expect(cleaned, {'/tmp/boba.png': 1});
+ expect(tester.takeException(), isNull);
+ });
+
+ testWidgets('Apply ends the edit', (tester) async {
+ daemon
+ ..held = ['boba']
+ ..previewReply = sheetPreview('boba', petRows);
+ await screen(tester);
+ await choose(tester);
+ expect(viewer, findsOneWidget);
+ await tester.ensureVisible(find.text('Apply'));
+ await tester.pumpAndSettle();
+ await tester.tap(find.text('Apply'));
+ await tester.pumpAndSettle();
+ expect(daemon.payloads['pet_apply'], [
+ {'target': 'all', 'id': 'boba'},
+ ]);
+ expect(viewer, findsNothing);
+ expect(find.text('Devices'), findsOneWidget);
+ });
+
+ testWidgets('narrow, the viewer is drawn in the Pet section', (
+ tester,
+ ) async {
+ daemon.previewReply = sheetPreview('boba', petRows);
+ await screen(tester, size: const Size(700, 900));
+ await choose(tester);
+ expect(viewer, findsNothing);
+ expect(
+ find.descendant(of: panel, matching: find.byType(PetRowViewer)),
+ findsOneWidget,
+ );
+ expect(find.text('Brightness'), findsOneWidget);
+ expect(tester.takeException(), isNull);
+ });
+
+ for (final brightness in Brightness.values) {
+ testWidgets('${brightness.name}: a 9-row sheet at 1000 x 780', (
+ tester,
+ ) async {
+ daemon.previewReply = sheetPreview('boba', petRows, frames: 8);
+ await screen(
+ tester,
+ size: const Size(1000, 780),
+ brightness: brightness,
+ );
+ await choose(tester);
+ expect(tester.takeException(), isNull);
+ const labels = [
+ 'Idle',
+ 'Running right',
+ 'Running left',
+ 'Waving',
+ 'Jumping',
+ 'Failed',
+ 'Waiting',
+ 'Running',
+ 'Review',
+ ];
+ final heights = <double>{};
+ for (final (i, row) in petRows.indexed) {
+ expect(
+ find.descendant(of: card(row), matching: find.text(labels[i])),
+ findsOneWidget,
+ );
+ heights.add(tester.getSize(card(row)).height);
+ }
+ expect(heights, hasLength(1), reason: 'one card height');
+ // Scrolled to the Pet section, the viewer and the section share the
+ // window.
+ final position = page(tester);
+ position.jumpTo(
+ (position.pixels + tester.getRect(panel).top - 16).clamp(
+ 0,
+ position.maxScrollExtent,
+ ),
+ );
+ await tester.pump();
+ await tester.pump();
+ final window = Offset.zero & const Size(1000, 780);
+ bool inside(Finder f) {
+ final r = tester.getRect(f);
+ return window.contains(r.topLeft) &&
+ window.contains(r.bottomRight - const Offset(.01, .01));
+ }
+
+ for (final scene in ['small', 'working', 'asking']) {
+ expect(
+ inside(find.byKey(ValueKey('pet-dial-$scene-boba'))),
+ isTrue,
+ reason: scene,
+ );
+ }
+ expect(
+ inside(find.byKey(const ValueKey('pet-viewer-frame-7'))),
+ isTrue,
+ );
+ for (final state in petStateLabels.keys) {
+ expect(inside(chip(state)), isTrue, reason: state);
+ }
+ expect(inside(find.text('Apply')), isTrue);
+ // Cancel and Apply sit right under the content, at the right.
+ final hint = tester.getRect(
+ find.text('A state plays exactly one row; picking it here moves it.'),
+ );
+ final apply = tester.getRect(
+ find.widgetWithText(FilledButton, 'Apply'),
+ );
+ expect(apply.top - hint.bottom, lessThan(32));
+ expect(tester.getRect(panel).right - apply.right, lessThan(24));
+ expect(
+ tester.getRect(find.widgetWithText(TextButton, 'Cancel')).right,
+ lessThan(apply.left),
+ );
+ });
+ }
+ });
+
+ group('crops', () {
+ /// A straight RGBA sheet of 8 x 9 cells of [w] x [h], clear but for
+ /// [boxes]: (row, column, box in the cell).
+ Uint8List sheet(int w, int h, List<(int, int, Rect)> boxes) {
+ final width = 8 * w;
+ final rgba = Uint8List(width * 9 * h * 4);
+ for (final (r, c, box) in boxes) {
+ for (var y = box.top.toInt(); y < box.bottom; y++) {
+ for (var x = box.left.toInt(); x < box.right; x++) {
+ rgba[((r * h + y) * width + c * w + x) * 4 + 3] = 255;
+ }
+ }
+ }
+ return rgba;
+ }
+
+ test('one box per row: the union of its frames, padded', () {
+ final rgba = sheet(40, 50, [
+ (2, 0, const Rect.fromLTRB(10, 20, 20, 40)),
+ (2, 3, const Rect.fromLTRB(14, 10, 30, 38)),
+ (5, 7, const Rect.fromLTRB(0, 0, 40, 50)),
+ ]);
+ final crops = sheetRowCrops(rgba, 8 * 40, 9 * 50, pad: 0);
+ expect(crops, hasLength(9));
+ expect(crops[2], const Rect.fromLTRB(10, 10, 30, 40));
+ expect(crops[5], const Rect.fromLTRB(0, 0, 40, 50));
+ expect([crops[0], crops[1], crops[8]], everyElement(isNull));
+ // Padding grows the box by a share of its larger side, inside the cell.
+ final padded = sheetRowCrops(rgba, 8 * 40, 9 * 50, pad: .1);
+ expect(padded[2], const Rect.fromLTRB(7, 7, 33, 43));
+ expect(padded[5], const Rect.fromLTRB(0, 0, 40, 50));
+ });
+
+ test('a frame is read from its cell, cut to the row’s box', () {
+ const cell = Size(192, 208);
+ expect(
+ frameSource(cell, 7, 2, null),
+ const Rect.fromLTWH(384, 1456, 192, 208),
+ );
+ expect(
+ frameSource(cell, 7, 2, const Rect.fromLTRB(40, 60, 150, 200)),
+ const Rect.fromLTRB(424, 1516, 534, 1656),
+ );
+ });
+
+ test('badges: as many as fit, room left for +n', () {
+ double more(int n) => 20;
+ expect(fitBadges([30, 30, 30], 100, more: more), 3);
+ expect(fitBadges([30, 30, 30], 90, more: more), 2);
+ expect(fitBadges([30, 30, 30, 30], 80, more: more), 1);
+ expect(fitBadges([60], 40, more: more), 0);
+ expect(fitBadges([], 40, more: more), 0);
+ });
+
+ test('the dial previews share the largest frame’s side', () {
+ Uint8List png(int w, int h) => Uint8List.fromList([
+ 0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A, //
+ 0, 0, 0, 13, 0x49, 0x48, 0x44, 0x52,
+ 0, 0, w >> 8, w & 255, 0, 0, h >> 8, h & 255,
+ ]);
+ expect(
+ dialFrameSide([
+ [png(102, 112)],
+ [png(192, 208)],
+ [],
+ ]),
+ 208,
+ );
+ expect(dialFrameSide([[], []]), 0);
+ });
+ });
+}
diff --git a/desktop/test/pet_source_test.dart b/desktop/test/pet_source_test.dart
new file mode 100644
index 000000000..4d880121a
--- /dev/null
+++ b/desktop/test/pet_source_test.dart
@@ -0,0 +1,343 @@
+import 'dart:convert';
+import 'dart:io';
+import 'dart:typed_data';
+
+import 'package:archive/archive.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/devices/pet_source.dart';
+
+/// A 768 x 936 RGBA PNG, solid colour.
+final _png = base64Decode(
+ 'iVBORw0KGgoAAAANSUhEUgAAAwAAAAOoCAYAAABmzpMNAAAS3klEQVR4nO3XMQHAIADAMJgk/AvA'
+ 'FXMBRxMFfTv3WmcAAAAJ3+sAAADgHgMAAAAhBgAAAEIMAAAAhBgAAAAIMQAAABBiAAAAIMQAAABA'
+ 'iAEAAIAQAwAAACEGAAAAQgwAAACEGAAAAAgxAAAAEGIAAAAgxAAAAECIAQAAgBADAAAAIQYAAABC'
+ 'DAAAAIQYAAAACDEAAAAQYgAAACDEAAAAQIgBAACAEAMAAAAhBgAAAEIMAAAAhBgAAAAIMQAAABBi'
+ 'AAAAIMQAAABAiAEAAIAQAwAAACEGAAAAQgwAAACEGAAAAAgxAAAAEGIAAAAgxAAAAECIAQAAgBAD'
+ 'AAAAIQYAAABCDAAAAIQYAAAACDEAAAAQYgAAACDEAAAAQIgBAACAEAMAAAAhBgAAAEIMAAAAhBgA'
+ 'AAAIMQAAABBiAAAAIMQAAABAiAEAAIAQAwAAACEGAAAAQgwAAACEGAAAAAgxAAAAEGIAAAAgxAAA'
+ 'AECIAQAAgBADAAAAIQYAAABCDAAAAIQYAAAACDEAAAAQYgAAACDEAAAAQIgBAACAEAMAAAAhBgAA'
+ 'AEIMAAAAhBgAAAAIMQAAABBiAAAAIMQAAABAiAEAAIAQAwAAACEGAAAAQgwAAACEGAAAAAgxAAAA'
+ 'EGIAAAAgxAAAAECIAQAAgBADAAAAIQYAAABCDAAAAIQYAAAACDEAAAAQYgAAACDEAAAAQIgBAACA'
+ 'EAMAAAAhBgAAAEIMAAAAhBgAAAAIMQAAABBiAAAAIMQAAABAiAEAAIAQAwAAACEGAAAAQgwAAACE'
+ 'GAAAAAgxAAAAEGIAAAAgxAAAAECIAQAAgBADAAAAIQYAAABCDAAAAIQYAAAACDEAAAAQYgAAACDE'
+ 'AAAAQIgBAACAEAMAAAAhBgAAAEIMAAAAhBgAAAAIMQAAABBiAAAAIMQAAABAiAEAAIAQAwAAACEG'
+ 'AAAAQgwAAACEGAAAAAgxAAAAEGIAAAAgxAAAAECIAQAAgBADAAAAIQYAAABCDAAAAIQYAAAACDEA'
+ 'AAAQYgAAACDEAAAAQIgBAACAEAMAAAAhBgAAAEIMAAAAhBgAAAAIMQAAABBiAAAAIMQAAABAiAEA'
+ 'AIAQAwAAACEGAAAAQgwAAACEGAAAAAgxAAAAEGIAAAAgxAAAAECIAQAAgBADAAAAIQYAAABCDAAA'
+ 'AIQYAAAACDEAAAAQYgAAACDEAAAAQIgBAACAEAMAAAAhBgAAAEIMAAAAhBgAAAAIMQAAABBiAAAA'
+ 'IMQAAABAiAEAAIAQAwAAACEGAAAAQgwAAACEGAAAAAgxAAAAEGIAAAAgxAAAAECIAQAAgBADAAAA'
+ 'IQYAAABCDAAAAIQYAAAACDEAAAAQYgAAACDEAAAAQIgBAACAEAMAAAAhBgAAAEIMAAAAhBgAAAAI'
+ 'MQAAABBiAAAAIMQAAABAiAEAAIAQAwAAACEGAAAAQgwAAACEGAAAAAgxAAAAEGIAAAAgxAAAAECI'
+ 'AQAAgBADAAAAIQYAAABCDAAAAIQYAAAACDEAAAAQYgAAACDEAAAAQIgBAACAEAMAAAAhBgAAAEIM'
+ 'AAAAhBgAAAAIMQAAABBiAAAAIMQAAABAiAEAAIAQAwAAACEGAAAAQgwAAACEGAAAAAgxAAAAEGIA'
+ 'AAAgxAAAAECIAQAAgBADAAAAIQYAAABCDAAAAIQYAAAACDEAAAAQYgAAACDEAAAAQIgBAACAEAMA'
+ 'AAAhBgAAAEIMAAAAhBgAAAAIMQAAABBiAAAAIMQAAABAiAEAAIAQAwAAACEGAAAAQgwAAACEGAAA'
+ 'AAgxAAAAEGIAAAAgxAAAAECIAQAAgBADAAAAIQYAAABCDAAAAIQYAAAACDEAAAAQYgAAACDEAAAA'
+ 'QIgBAACAEAMAAAAhBgAAAEIMAAAAhBgAAAAIMQAAABBiAAAAIMQAAABAiAEAAIAQAwAAACEGAAAA'
+ 'QgwAAACEGAAAAAgxAAAAEGIAAAAgxAAAAECIAQAAgBADAAAAIQYAAABCDAAAAIQYAAAACDEAAAAQ'
+ 'YgAAACDEAAAAQIgBAACAEAMAAAAhBgAAAEIMAAAAhBgAAAAIMQAAABBiAAAAIMQAAABAiAEAAIAQ'
+ 'AwAAACEGAAAAQgwAAACEGAAAAAgxAAAAEGIAAAAgxAAAAECIAQAAgBADAAAAIQYAAABCDAAAAIQY'
+ 'AAAACDEAAAAQYgAAACDEAAAAQIgBAACAEAMAAAAhBgAAAEIMAAAAhBgAAAAIMQAAABBiAAAAIMQA'
+ 'AABAiAEAAIAQAwAAACEGAAAAQgwAAACEGAAAAAgxAAAAEGIAAAAgxAAAAECIAQAAgBADAAAAIQYA'
+ 'AABCDAAAAIQYAAAACDEAAAAQYgAAACDEAAAAQIgBAACAEAMAAAAhBgAAAEIMAAAAhBgAAAAIMQAA'
+ 'ABBiAAAAIMQAAABAiAEAAIAQAwAAACEGAAAAQgwAAACEGAAAAAgxAAAAEGIAAAAgxAAAAECIAQAA'
+ 'gBADAAAAIQYAAABCDAAAAIQYAAAACDEAAAAQYgAAACDEAAAAQIgBAACAEAMAAAAhBgAAAEIMAAAA'
+ 'hBgAAAAIMQAAABBiAAAAIMQAAABAiAEAAIAQAwAAACEGAAAAQgwAAACEGAAAAAgxAAAAEGIAAAAg'
+ 'xAAAAECIAQAAgBADAAAAIQYAAABCDAAAAIQYAAAACDEAAAAQYgAAACDEAAAAQIgBAACAEAMAAAAh'
+ 'BgAAAEIMAAAAhBgAAAAIMQAAABBiAAAAIMQAAABAiAEAAIAQAwAAACEGAAAAQgwAAACEGAAAAAgx'
+ 'AAAAEGIAAAAgxAAAAECIAQAAgBADAAAAIQYAAABCDAAAAIQYAAAACDEAAAAQYgAAACDEAAAAQIgB'
+ 'AACAEAMAAAAhBgAAAEIMAAAAhBgAAAAIMQAAABBiAAAAIMQAAABAiAEAAIAQAwAAACEGAAAAQgwA'
+ 'AACEGAAAAAgxAAAAEGIAAAAgxAAAAECIAQAAgBADAAAAIQYAAABCDAAAAIQYAAAACDEAAAAQYgAA'
+ 'ACDEAAAAQIgBAACAEAMAAAAhBgAAAEIMAAAAhBgAAAAIMQAAABBiAAAAIMQAAABAiAEAAIAQAwAA'
+ 'ACEGAAAAQgwAAACEGAAAAAgxAAAAEGIAAAAgxAAAAECIAQAAgBADAAAAIQYAAABCDAAAAIQYAAAA'
+ 'CDEAAAAQYgAAACDEAAAAQIgBAACAEAMAAAAhBgAAAEIMAAAAhBgAAAAIMQAAABBiAAAAIMQAAABA'
+ 'iAEAAIAQAwAAACEGAAAAQgwAAACEGAAAAAgxAAAAEGIAAAAgxAAAAECIAQAAgBADAAAAIQYAAABC'
+ 'DAAAAIQYAAAACDEAAAAQYgAAACDEAAAAQIgBAACAEAMAAAAhBgAAAEIMAAAAhBgAAAAIMQAAABBi'
+ 'AAAAIMQAAABAiAEAAIAQAwAAACEGAAAAQgwAAACEGAAAAAgxAAAAEGIAAAAgxAAAAECIAQAAgBAD'
+ 'AAAAIQYAAABCDAAAAIQYAAAACDEAAAAQYgAAACDEAAAAQIgBAACAEAMAAAAhBgAAAEIMAAAAhBgA'
+ 'AAAIMQAAABBiAAAAIMQAAABAiAEAAIAQAwAAACEGAAAAQgwAAACEGAAAAAgxAAAAEGIAAAAgxAAA'
+ 'AECIAQAAgBADAAAAIQYAAABCDAAAAIQYAAAACDEAAAAQYgAAACDEAAAAQIgBAACAEAMAAAAhBgAA'
+ 'AEIMAAAAhBgAAAAIMQAAABBiAAAAIMQAAABAiAEAAIAQAwAAACEGAAAAQgwAAACEGAAAAAgxAAAA'
+ 'EGIAAAAgxAAAAECIAQAAgBADAAAAIQYAAABCDAAAAIQYAAAACDEAAAAQYgAAACDEAAAAQIgBAACA'
+ 'EAMAAAAhBgAAAEIMAAAAhBgAAAAIMQAAABBiAAAAIMQAAABAiAEAAIAQAwAAACEGAAAAQgwAAACE'
+ 'GAAAAAgxAAAAEGIAAAAgxAAAAECIAQAAgBADAAAAIQYAAABCDAAAAIQYAAAACDEAAAAQYgAAACDE'
+ 'AAAAQIgBAACAEAMAAAAhBgAAAEIMAAAAhBgAAAAIMQAAABBiAAAAIMQAAABAiAEAAIAQAwAAACEG'
+ 'AAAAQgwAAACEGAAAAAgxAAAAEGIAAAAgxAAAAECIAQAAgBADAAAAIQYAAABCDAAAAIQYAAAACDEA'
+ 'AAAQYgAAACDEAAAAQIgBAACAEAMAAAAhBgAAAEIMAAAAhBgAAAAIMQAAABBiAAAAIMQAAABAiAEA'
+ 'AIAQAwAAACEGAAAAQgwAAACEGAAAAAgxAAAAEGIAAAAgxAAAAECIAQAAgBADAAAAIQYAAABCDAAA'
+ 'AIQYAAAACDEAAAAQYgAAACDEAAAAQIgBAACAEAMAAAAhBgAAAEIMAAAAhBgAAAAIMQAAABBiAAAA'
+ 'IMQAAABAiAEAAIAQAwAAACEGAAAAQgwAAACEGAAAAAgxAAAAEGIAAAAgxAAAAECIAQAAgBADAAAA'
+ 'IQYAAABCDAAAAIQYAAAACDEAAAAQYgAAACDEAAAAQIgBAACAEAMAAAAhBgAAAEIMAAAAhBgAAAAI'
+ 'MQAAABBiAAAAIMQAAABAiAEAAIAQAwAAACEGAAAAQgwAAACEGAAAAAgxAAAAEGIAAAAgxAAAAECI'
+ 'AQAAgBADAAAAIQYAAABCDAAAAIQYAAAACDEAAAAQYgAAACDEAAAAQIgBAACAEAMAAAAhBgAAAEIM'
+ 'AAAAhBgAAAAIMQAAABBiAAAAIMQAAABAiAEAAIAQAwAAACEGAAAAQgwAAACEGAAAAAgxAAAAEGIA'
+ 'AAAgxAAAAECIAQAAgBADAAAAIQYAAABCDAAAAIQYAAAACDEAAAAQYgAAACDEAAAAQIgBAACAEAMA'
+ 'AAAhBgAAAEIMAAAAhBgAAAAIMQAAABBiAAAAIMQAAABAiAEAAIAQAwAAACEGAAAAQgwAAACEGAAA'
+ 'AAgxAAAAEGIAAAAgxAAAAECIAQAAgBADAAAAIQYAAABCDAAAAIQYAAAACDEAAAAQYgAAACDEAAAA'
+ 'QIgBAACAEAMAAAAhBgAAAEIMAAAAhBgAAAAIMQAAABBiAAAAIMQAAABAiAEAAIAQAwAAACEGAAAA'
+ 'QgwAAACEGAAAAAgxAAAAEGIAAAAgxAAAAECIAQAAgBADAAAAIQYAAABCDAAAAIQYAAAACDEAAAAQ'
+ 'YgAAACDEAAAAQIgBAACAEAMAAAAhBgAAAEIMAAAAhBgAAAAIMQAAABBiAAAAIMQAAABAiAEAAIAQ'
+ 'AwAAACEGAAAAQgwAAACEGAAAAAgxAAAAEGIAAAAgxAAAAECIAQAAgBADAAAAIQYAAABCDAAAAIQY'
+ 'AAAACDEAAAAQYgAAACDEAAAAQIgBAACAEAMAAAAhBgAAAEIMAAAAhBgAAAAIMQAAABBiAAAAIMQA'
+ 'AABAiAEAAIAQAwAAACEGAAAAQgwAAACEGAAAAAgxAAAAEGIAAAAgxAAAAECIAQAAgBADAAAAIQYA'
+ 'AABCDAAAAIQYAAAACDEAAAAQYgAAACDEAAAAQIgBAACAEAMAAAAhBgAAAEIMAAAAhBgAAAAIMQAA'
+ 'ABBiAAAAIMQAAABAiAEAAIAQAwAAACEGAAAAQgwAAACEGAAAAAgxAAAAEGIAAAAgxAAAAECIAQAA'
+ 'gBADAAAAIQYAAABCDAAAAIQYAAAACDEAAAAQYgAAACDEAAAAQIgBAACAEAMAAAAhBgAAAEIMAAAA'
+ 'hBgAAAAIMQAAABBiAAAAIMQAAABAiAEAAIAQAwAAACEGAAAAQgwAAACEGAAAAAgxAAAAEGIAAAAg'
+ 'xAAAAECIAQAAgBADAAAAIQYAAABCDAAAAIQYAAAACDEAAAAQYgAAACDEAAAAQIgBAACAEAMAAAAh'
+ 'BgAAAEIMAAAAhBgAAAAIMQAAABBiAAAAIMQAAABAiAEAAIAQAwAAACEGAAAAQgwAAACEGAAAAAgx'
+ 'AAAAEGIAAAAgxAAAAECIAQAAgBADAAAAIQYAAABCDAAAAIQYAAAACDEAAAAQYgAAACDEAAAAQIgB'
+ 'AACAEAMAAAAhBgAAAEIMAAAAhBgAAAAIMQAAABBiAAAAIMQAAABAiAEAAIAQAwAAACEGAAAAQgwA'
+ 'AACEGAAAAAgxAAAAEGIAAAAgxAAAAECIAQAAgBADAAAAIQYAAABCDAAAAIQYAAAACDEAAAAQYgAA'
+ 'ACDEAAAAQIgBAACAEAMAAAAhBgAAAEIMAAAAhBgAAAAIMQAAABBiAAAAIMQAAABAiAEAAIAQAwAA'
+ 'ACEGAAAAQgwAAACEGAAAAAgxAAAAEGIAAAAgxAAAAECIAQAAgBADAAAAIQYAAABCDAAAAIQYAAAA'
+ 'CDEAAAAQYgAAACDEAAAAQIgBAACAEAMAAAAhBgAAAEIMAAAAhBgAAAAIMQAAABBiAAAAIMQAAABA'
+ 'iAEAAIAQAwAAACEGAAAAQgwAAACEGAAAAAgxAAAAEGIAAAAgxAAAAECIAQAAgBADAAAAIQYAAABC'
+ 'DAAAAIQYAAAACDEAAAAQYgAAAGB0/McZCXshDR9LAAAAAElFTkSuQmCC',
+);
+
+/// The same size as a lossless WebP (72 bytes).
+final _webp = base64Decode(
+ 'UklGRkAAAABXRUJQVlA4TDQAAAAv/8LpAAdQmSJXpv8BAEX6/58i+p/63//+97///e9///vf//73v//973//+9///ve//ycG',
+);
+
+/// A RIFF/WEBP header declaring a VP8X canvas of [w] x [h]; no pixel data.
+Uint8List _vp8x(int w, int h) {
+ final b = BytesBuilder();
+ void le(int v, int n) {
+ for (var i = 0; i < n; i++) {
+ b.addByte((v >> (8 * i)) & 0xff);
+ }
+ }
+
+ b
+ ..add(ascii.encode('RIFF'))
+ ..add([0, 0, 0, 0])
+ ..add(ascii.encode('WEBPVP8X'));
+ le(10, 4);
+ le(0, 4); // flags + reserved
+ le(w - 1, 3);
+ le(h - 1, 3);
+ return b.toBytes();
+}
+
+Future<void> _expectError(Future<Object?> run, [Object? message]) async {
+ await expectLater(
+ run,
+ throwsA(
+ isA<PetSourceError>().having(
+ (e) => e.message,
+ 'message',
+ message ?? isNotEmpty,
+ ),
+ ),
+ );
+}
+
+void main() {
+ late Directory work;
+ // Resolved, as the resolver reports real paths (macOS /var is a link).
+ setUp(
+ () => work = Directory(
+ Directory.systemTemp
+ .createTempSync('pet-source-test-')
+ .resolveSymbolicLinksSync(),
+ ),
+ );
+ tearDown(() => work.deleteSync(recursive: true));
+
+ Directory petDir(String name, {String sheet = 'sheet.png', Object? json}) {
+ final dir = Directory('${work.path}/$name')..createSync();
+ File('${dir.path}/$sheet')
+ ..createSync(recursive: true)
+ ..writeAsBytesSync(_png);
+ File('${dir.path}/pet.json').writeAsStringSync(
+ jsonEncode(
+ json ??
+ {'id': 'boba-id', 'displayName': 'Boba', 'spritesheetPath': sheet},
+ ),
+ );
+ return dir;
+ }
+
+ Uint8List zipOf(Map<String, List<int>> files) {
+ final archive = Archive();
+ files.forEach(
+ (name, data) => archive.add(ArchiveFile(name, data.length, data)),
+ );
+ return Uint8List.fromList(ZipEncoder().encode(archive));
+ }
+
+ test(
+ 'a folder with pet.json: the sheet it names and the display name',
+ () async {
+ final dir = petDir('folder', sheet: 'art/sheet.png')..createSync();
+ final source = await resolvePetSource(dir.path);
+ expect(source.pngPath, '${dir.path}/art/sheet.png');
+ expect(source.name, 'Boba');
+ await source.cleanup();
+ expect(
+ File(source.pngPath).existsSync(),
+ isTrue,
+ reason: 'user files stay',
+ );
+ },
+ );
+
+ test('falls back to the id when there is no displayName', () async {
+ final dir = petDir(
+ 'folder',
+ json: {'id': 'just-id', 'spritesheetPath': 'sheet.png'},
+ );
+ expect((await resolvePetSource(dir.path)).name, 'just-id');
+ });
+
+ test('a pet.json file resolves like its folder', () async {
+ final dir = petDir('folder');
+ final source = await resolvePetSource('${dir.path}/pet.json');
+ expect(source.pngPath, '${dir.path}/sheet.png');
+ expect(source.name, 'Boba');
+ });
+
+ test('without pet.json, exactly one spritesheet.(webp|png)', () async {
+ final dir = Directory('${work.path}/bare')..createSync();
+ await _expectError(resolvePetSource(dir.path));
+ File('${dir.path}/spritesheet.png').writeAsBytesSync(_png);
+ final source = await resolvePetSource(dir.path);
+ expect(source.pngPath, '${dir.path}/spritesheet.png');
+ expect(source.name, isNull);
+ File('${dir.path}/spritesheet.webp').writeAsBytesSync(_webp);
+ await _expectError(resolvePetSource(dir.path));
+ });
+
+ test('a sheet path that leaves the folder is refused', () async {
+ File('${work.path}/x.png').writeAsBytesSync(_png);
+ for (final bad in [
+ '../x.png',
+ '/etc/hosts',
+ 'a/../../x.png',
+ r'..\x.png',
+ ]) {
+ final dir = petDir('evil', json: {'spritesheetPath': bad});
+ await _expectError(resolvePetSource(dir.path));
+ dir.deleteSync(recursive: true);
+ }
+ });
+
+ test('a symlink pointing out of the folder is refused', () async {
+ File('${work.path}/outside.png').writeAsBytesSync(_png);
+ final dir = Directory('${work.path}/linked')..createSync();
+ Link('${dir.path}/sheet.png').createSync('${work.path}/outside.png');
+ File('${dir.path}/pet.json')
+ .writeAsStringSync(jsonEncode({'spritesheetPath': 'sheet.png'}));
+ await _expectError(resolvePetSource(dir.path));
+ });
+
+ test('a zip with a top-level folder is extracted, then cleaned up', () async {
+ final zip = File('${work.path}/pet.zip')
+ ..writeAsBytesSync(
+ zipOf({
+ 'boba/pet.json': utf8.encode(
+ jsonEncode({
+ 'displayName': 'Zipped',
+ 'spritesheetPath': 'sheet.png',
+ }),
+ ),
+ 'boba/sheet.png': _png,
+ '__MACOSX/boba/._sheet.png': [1, 2, 3],
+ }),
+ );
+ final source = await resolvePetSource(zip.path);
+ expect(source.name, 'Zipped');
+ expect(File(source.pngPath).readAsBytesSync(), _png);
+ expect(source.pngPath.startsWith(work.path), isFalse, reason: 'temp dir');
+ await source.cleanup();
+ expect(File(source.pngPath).existsSync(), isFalse);
+ });
+
+ test('a zip with ../ or absolute entries is refused', () async {
+ for (final name in ['../evil.png', 'a/../../evil.png', '/abs/evil.png']) {
+ final zip = File('${work.path}/bad.zip')
+ ..writeAsBytesSync(zipOf({name: _png, 'pet.json': utf8.encode('{}')}));
+ await _expectError(resolvePetSource(zip.path));
+ }
+ expect(File('${work.path}/evil.png').existsSync(), isFalse);
+ });
+
+ test('a zip over the entry or size caps is refused', () async {
+ final many = File('${work.path}/many.zip')
+ ..writeAsBytesSync(
+ zipOf({
+ for (var i = 0; i < 65; i++) 'f$i.txt': [i],
+ }),
+ );
+ await _expectError(resolvePetSource(many.path), contains('too many'));
+ final big = File('${work.path}/big.zip')
+ ..writeAsBytesSync(
+ zipOf({
+ 'a.bin': Uint8List(20 * 1024 * 1024),
+ 'b.bin': Uint8List(20 * 1024 * 1024),
+ }),
+ );
+ await _expectError(resolvePetSource(big.path), contains('too large'));
+ });
+
+ test('a PNG is used as is, with no name', () async {
+ final file = File('${work.path}/boba.png')..writeAsBytesSync(_png);
+ final source = await resolvePetSource(file.path);
+ expect(source.pngPath, file.path);
+ expect(source.name, isNull);
+ });
+
+ test('an unsupported file type is refused', () async {
+ final file = File('${work.path}/boba.gif')..writeAsBytesSync(_png);
+ await _expectError(resolvePetSource(file.path));
+ });
+
+ group('WebP header', () {
+ test('reads VP8X, VP8L and VP8 dimensions', () {
+ expect(webpSize(_vp8x(1536, 1872)), (1536, 1872));
+ expect(webpSize(_webp), (768, 936)); // VP8L, from a real file
+ final vp8 = BytesBuilder()
+ ..add(ascii.encode('RIFF'))
+ ..add([0, 0, 0, 0])
+ ..add(ascii.encode('WEBPVP8 '))
+ ..add([0, 0, 0, 0])
+ ..add([0, 0, 0]) // frame tag
+ ..add([0x9d, 0x01, 0x2a])
+ ..add([0x00, 0x06, 0x50, 0x07]); // 1536, 1872 (little endian)
+ expect(webpSize(vp8.toBytes()), (1536, 1872));
+ });
+
+ test('rejects a non-WebP', () {
+ expect(webpSize(Uint8List.fromList([1, 2, 3])), isNull);
+ });
+ });
+
+ test('a WebP declaring 12000 x 12000 is refused before decoding', () async {
+ final file = File('${work.path}/huge.webp')
+ ..writeAsBytesSync(_vp8x(12000, 12000));
+ await _expectError(
+ resolvePetSource(file.path),
+ 'The sheet must be 1536 × 1872 (8 × 9 cells of 192 × 208)',
+ );
+ });
+
+ test('a WebP over 8 MB is refused', () async {
+ final file = File('${work.path}/fat.webp')
+ ..writeAsBytesSync(Uint8List(8 * 1024 * 1024 + 1));
+ await _expectError(resolvePetSource(file.path), contains('8 MB'));
+ });
+
+ testWidgets('a real WebP is decoded to a PNG in a temp dir', (tester) async {
+ final file = File('${work.path}/boba.webp')..writeAsBytesSync(_webp);
+ final source = await tester.runAsync(() => resolvePetSource(file.path));
+ expect(source!.name, 'boba');
+ final out = File(source.pngPath).readAsBytesSync();
+ expect(out.sublist(0, 8), [0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A]);
+ final data = ByteData.sublistView(out);
+ expect((data.getUint32(16), data.getUint32(20)), (768, 936));
+ await tester.runAsync(source.cleanup);
+ expect(File(source.pngPath).existsSync(), isFalse);
+ });
+}
diff --git a/devices/harness-device/firmware/main/CMakeLists.txt b/devices/harness-device/firmware/main/CMakeLists.txt
index e3e33f637..554dad958 100644
--- a/devices/harness-device/firmware/main/CMakeLists.txt
+++ b/devices/harness-device/firmware/main/CMakeLists.txt
@@ -29,6 +29,7 @@ set(BOARD_SRCS
"cable_features.c"
"last_words.c"
"fw_update.c"
+ "pet_store.c"
"audio_capture.c"
"audio_client_habitat.c"
"audio_probe.c"
diff --git a/devices/harness-device/firmware/main/cable_client.c b/devices/harness-device/firmware/main/cable_client.c
index cc9b391cf..a5f0ee955 100644
--- a/devices/harness-device/firmware/main/cable_client.c
+++ b/devices/harness-device/firmware/main/cable_client.c
@@ -18,6 +18,7 @@
#include "esp_timer.h"
#include "fw_update.h"
#include "last_words.h"
+#include "pet_store.h"
#include "board/board.h"
#include "freertos/FreeRTOS.h"
#include "freertos/semphr.h"
@@ -325,6 +326,19 @@ static void send_hello(void)
// Carried on every greeting so the app's pane opens on what the device holds rather than on what
// this computer last sent it — which after a reboot, a reset or a second window is not the same.
msg_settings(&root);
+ // Custom pets: the pack version this build understands (a number, so a later format can say 2), and
+ // these packs are already held, so the daemon sends only what is missing.
+ msg_number(&root, "pets", 1);
+ {
+ char held[PET_STORE_MAX_PACKS][17];
+ const size_t n = pet_store_held(held, PET_STORE_MAX_PACKS);
+ cJSON *ids = msg_array(&root, "petIds");
+ for (size_t i = 0; root && ids && i < n; i++) {
+ cJSON *id = cJSON_CreateString(held[i]);
+ if (!msg_check(&root, id != NULL)) break;
+ if (!cJSON_AddItemToArray(ids, id)) { cJSON_Delete(id); msg_check(&root, false); }
+ }
+ }
send_json(root);
}
@@ -920,6 +934,7 @@ static void session_up(const cJSON *p)
}
}
+static void pet_forget_transfer(void);
static void session_down(const char *why)
{
if (!s_session) return;
@@ -951,6 +966,7 @@ static void session_down(const char *why)
// a serial monitor, which is exactly the situation a dropped session puts them in.
cable_link_set_log_framing(false);
fw_update_abort("session down"); // no more slices are coming; the running image is untouched
+ pet_forget_transfer(); // likewise a half-received pet pack; the held packs stay
ESP_LOGI(TAG, "session down (%s)", why);
ui_set_connected(false);
}
@@ -1102,6 +1118,103 @@ static void handle_notifications(const cJSON *p)
ui_notif_replace(rows, n);
}
+// ── custom pets ─────────────────────────────────────────────────────────────────────────────────────
+// A pack arrives as CABLE_TYPE_PET slices on the reader task, like firmware: each slice is acknowledged with
+// `pet.progress`, which is what opens the daemon's credit window (docs/specs/cable-protocol.md §7).
+
+static char s_pet_id[17];
+static uint32_t s_pet_size, s_pet_written; // reader task only
+
+static void pet_reply(const char *t, const char *id, const char *reason)
+{
+ cJSON *root = msg(t);
+ if (!root) return;
+ msg_string(&root, "id", id ? id : "");
+ if (reason) msg_string(&root, "reason", reason);
+ send_json(root);
+}
+
+static void pet_forget_transfer(void)
+{
+ s_pet_id[0] = 0;
+ s_pet_size = s_pet_written = 0;
+ pet_store_abort();
+}
+
+static void handle_pet_offer(const cJSON *p)
+{
+ const char *id = str_of(p, "id");
+ const cJSON *size = cJSON_GetObjectItemCaseSensitive(p, "size");
+ const cJSON *crc = cJSON_GetObjectItemCaseSensitive(p, "crc");
+ if (!id || strlen(id) != 16) {
+ pet_reply("pet.error", id, "shape");
+ return;
+ }
+ if (!cJSON_IsNumber(size) || !cJSON_IsNumber(crc) || size->valuedouble <= 22 || size->valuedouble > PET_STORE_MAX_BYTES ||
+ crc->valuedouble < 0 || crc->valuedouble > 4294967295.0) {
+ pet_reply("pet.error", id, "shape");
+ return;
+ }
+ pet_forget_transfer();
+ if (!pet_store_offer(id, (uint32_t)size->valuedouble, (uint32_t)crc->valuedouble)) {
+ // Four other packs held is `busy` (the daemon drops one and offers again); anything else is memory.
+ char held[PET_STORE_MAX_PACKS][17];
+ const size_t n = pet_store_held(held, PET_STORE_MAX_PACKS);
+ bool same = false;
+ for (size_t i = 0; i < n; i++) if (!strcmp(held[i], id)) same = true;
+ bool hex = true;
+ for (int i = 0; i < 16; i++) if (!((id[i] >= '0' && id[i] <= '9') || (id[i] >= 'a' && id[i] <= 'f'))) hex = false;
+ pet_reply("pet.error", id, !hex ? "shape" : n >= PET_STORE_MAX_PACKS && !same ? "busy" : "memory");
+ return;
+ }
+ memcpy(s_pet_id, id, sizeof(s_pet_id) - 1);
+ s_pet_id[16] = 0;
+ s_pet_size = (uint32_t)size->valuedouble;
+ s_pet_written = 0;
+ pet_reply("pet.accept", id, NULL);
+}
+
+static void handle_pet_slice(const uint8_t *data, size_t len)
+{
+ if (!s_pet_id[0] || len == 0) return;
+ if (!pet_store_slice(data, len)) {
+ // The only way a slice fails with an offer open is more bytes than were offered: a shape error.
+ pet_reply("pet.error", s_pet_id, "shape");
+ pet_forget_transfer();
+ return;
+ }
+ s_pet_written += (uint32_t)len;
+ cJSON *root = msg("pet.progress");
+ if (root) {
+ msg_string(&root, "id", s_pet_id);
+ msg_number(&root, "written", (double)s_pet_written);
+ send_json(root);
+ }
+ if (s_pet_written < s_pet_size) return;
+ const int err = pet_store_finish();
+ if (err == 0) { pet_reply("pet.done", s_pet_id, NULL); ui_pets_changed(); }
+ else pet_reply("pet.error", s_pet_id, err == PET_ERR_CRC ? "crc" : err == PET_ERR_VERSION ? "version" : "shape");
+ s_pet_id[0] = 0;
+ s_pet_size = s_pet_written = 0;
+}
+
+static void handle_pet_map(const cJSON *p)
+{
+ const char *all = str_of(p, "all");
+ const char *engines[8], *ids[8];
+ size_t n = 0;
+ const cJSON *map = cJSON_GetObjectItemCaseSensitive(p, "engines");
+ const cJSON *e;
+ cJSON_ArrayForEach(e, map) {
+ if (n >= 8) break;
+ if (!cJSON_IsString(e) || !e->string || !e->valuestring) continue;
+ engines[n] = e->string;
+ ids[n++] = e->valuestring;
+ }
+ pet_store_map(all, engines, ids, n);
+ ui_pets_changed();
+}
+
static void handle_message(const cJSON *root)
{
const char *t = str_of(root, "t");
@@ -1313,6 +1426,16 @@ static void handle_message(const cJSON *root)
return;
}
+ if (strcmp(t, "pet.map") == 0) { handle_pet_map(p); return; }
+ if (strcmp(t, "pet.offer") == 0) { handle_pet_offer(p); return; }
+ if (strcmp(t, "pet.drop") == 0) {
+ const char *did = str_of(p, "id");
+ if (did && !strcmp(did, s_pet_id)) pet_forget_transfer(); // an in-flight id: the daemon abandoned it
+ pet_store_drop(did);
+ ui_pets_changed();
+ return;
+ }
+
// A message this build has no case for. Counted, never fatal: it means a daemon running ahead of this
// firmware, which is a version mismatch someone can act on rather than a fault.
s_unknown++;
@@ -1331,6 +1454,11 @@ static void on_frame(uint8_t version, uint8_t type, const uint8_t *payload, size
fw_update_slice(payload, payload_len);
return;
}
+ if (type == CABLE_TYPE_PET) {
+ s_last_rx_us = esp_timer_get_time();
+ handle_pet_slice(payload, payload_len);
+ return;
+ }
if (type != CABLE_TYPE_JSON) {
// PCM travels the other way; anything else is a peer that knows a payload kind this build does not.
s_unknown++;
diff --git a/devices/harness-device/firmware/main/cable_frame.h b/devices/harness-device/firmware/main/cable_frame.h
index eafaf1ac5..9fd331684 100644
--- a/devices/harness-device/firmware/main/cable_frame.h
+++ b/devices/harness-device/firmware/main/cable_frame.h
@@ -76,6 +76,7 @@
#define CABLE_TYPE_PCM 0x02 // one chunk of 16-bit mono PCM, device → daemon, during a voice turn
#define CABLE_TYPE_FW 0x03 // one slice of a firmware image, daemon → device only
#define CABLE_TYPE_LOG 0x04 // one ESP_LOG line, device → daemon, raw bytes (no JSON escaping)
+#define CABLE_TYPE_PET 0x05 // one slice of a custom pet pack (HPET), daemon → device only
// CRC-16/CCITT-FALSE — poly 0x1021, init 0xFFFF, no reflection, no final xor.
//
diff --git a/devices/harness-device/firmware/main/pet_store.c b/devices/harness-device/firmware/main/pet_store.c
new file mode 100644
index 000000000..ba00a81e8
--- /dev/null
+++ b/devices/harness-device/firmware/main/pet_store.c
@@ -0,0 +1,444 @@
+#include "pet_store.h"
+
+#include <assert.h>
+#include <stdlib.h>
+#include <string.h>
+
+#ifdef ESP_PLATFORM
+#include "esp_heap_caps.h"
+#include "freertos/FreeRTOS.h"
+#include "freertos/semphr.h"
+static SemaphoreHandle_t s_lock;
+// Created before the scheduler starts, so there is no race to create it lazily.
+__attribute__((constructor)) static void pet_lock_init(void) { s_lock = xSemaphoreCreateMutex(); }
+static void lock(void) { assert(s_lock); xSemaphoreTake(s_lock, portMAX_DELAY); }
+static void unlock(void) { assert(s_lock); xSemaphoreGive(s_lock); }
+#ifndef PET_MALLOC
+#define PET_MALLOC(n) heap_caps_malloc((n), MALLOC_CAP_SPIRAM)
+#endif
+#else
+#include <pthread.h>
+static pthread_mutex_t s_mutex = PTHREAD_MUTEX_INITIALIZER;
+static void lock(void) { pthread_mutex_lock(&s_mutex); }
+static void unlock(void) { pthread_mutex_unlock(&s_mutex); }
+#ifndef PET_MALLOC
+#define PET_MALLOC(n) malloc(n)
+#endif
+#endif
+// Hooks the host test overrides to count allocations.
+#ifndef PET_CALLOC
+#ifdef ESP_PLATFORM
+// PSRAM, so the metadata stays out of internal RAM (SPIRAM_MALLOC_ALWAYSINTERNAL would put it there with calloc).
+static void *pet_calloc(size_t n, size_t s)
+{
+ void *p = heap_caps_calloc(n, s, MALLOC_CAP_SPIRAM);
+ return p ? p : calloc(n, s);
+}
+#define PET_CALLOC(n, s) pet_calloc((n), (s))
+#else
+#define PET_CALLOC(n, s) calloc((n), (s))
+#endif
+#endif
+#ifndef PET_FREE
+#define PET_FREE(p) free(p)
+#endif
+
+/*
+ * LIFETIME AND THE PER-FRAME SNAPSHOT. A pack is immutable once published. The cable task edits only the STAGED
+ * state (s_packs and s_stage_map: offer/finish/map/drop), under the mutex. The UI task reads only the LIVE state
+ * (s_live and s_live_map), which pet_store_release_frame replaces with the staged state, once per scene take.
+ * So every lookup between two releases sees the same snapshot, however the cable task edits meanwhile: a face
+ * built from several lookups can never see one of them disagree with another.
+ * - a pack leaves the staged table at drop/replace; if the live snapshot still holds it, it stays allocated
+ * (the frame being built or painted may use it) and release_frame frees it when it applies the new snapshot;
+ * a pack the live snapshot never saw is freed at once;
+ * - a pack published by finish is invisible to lookup until the next release_frame.
+ * The UI therefore holds any pointer it got until its next release_frame call, with no lock held while drawing.
+ * The partial pack being received (s_in) is never visible to lookup.
+ */
+
+enum { HEADER = 22, MAX_ENGINES = 8, LOOPS = 3, SCENES = 4, MAX_ID = 17, STEP_MS = 120 };
+
+typedef struct pack {
+ char id[MAX_ID];
+ uint8_t *buf; // the whole pack; the frames' cells point into it
+ uint32_t size, got, crc;
+ ht_pet_t pet;
+ uint16_t palette[256];
+ ht_cell_frame_t *frames;
+ uint16_t *row_at;
+ ht_pet_step_t loops[HT_PET_STATES][HT_PET_STEPS];
+ uint16_t step_ms[HT_PET_STATES];
+ ht_pet_scene_t scenes[3]; // working, listening, sending
+ uint8_t *scene_loop[3];
+ struct pack *next; // the list release_frame frees
+} pack_t;
+
+typedef struct {
+ char all[MAX_ID];
+ struct { char engine[16]; char id[MAX_ID]; } engines[MAX_ENGINES];
+} map_t;
+
+static pack_t *s_packs[PET_STORE_MAX_PACKS]; // staged: what the cable task has published
+static map_t s_stage_map;
+static pack_t *s_in; // partially received
+static pack_t *s_live[PET_STORE_MAX_PACKS]; // live: what lookup sees until the next release_frame
+static map_t s_live_map;
+
+static void pack_free(pack_t *p)
+{
+ if (!p) return;
+ PET_FREE(p->buf);
+ PET_FREE(p->frames);
+ PET_FREE(p->row_at);
+ for (int i = 0; i < 3; i++) PET_FREE(p->scene_loop[i]);
+ PET_FREE(p);
+}
+
+// Take a pack out of the staged table (mutex held). The live snapshot may still be drawing it: then release_frame
+// frees it; otherwise nobody can hold it and it goes now.
+static void retire(pack_t *p)
+{
+ if (!p) return;
+ for (int i = 0; i < PET_STORE_MAX_PACKS; i++)
+ if (s_live[i] == p) return;
+ pack_free(p);
+}
+
+static bool valid_id(const char *id)
+{
+ if (!id || strlen(id) != 16) return false;
+ for (int i = 0; i < 16; i++)
+ if (!((id[i] >= '0' && id[i] <= '9') || (id[i] >= 'a' && id[i] <= 'f'))) return false;
+ return true;
+}
+
+static uint32_t crc32_ieee(const uint8_t *d, size_t n)
+{
+ static const uint32_t t[16] = {0x00000000, 0x1db71064, 0x3b6e20c8, 0x26d930ac, 0x76dc4190, 0x6b6b51f4,
+ 0x4db26158, 0x5005713c, 0xedb88320, 0xf00f9344, 0xd6d6a3e8, 0xcb61b38c,
+ 0x9b64c2b0, 0x86d3d2d4, 0xa00ae278, 0xbdbdf21c};
+ uint32_t c = 0xffffffffu;
+ for (size_t i = 0; i < n; i++) {
+ c ^= d[i];
+ c = (c >> 4) ^ t[c & 15];
+ c = (c >> 4) ^ t[c & 15];
+ }
+ return ~c;
+}
+
+// ── parsing: every read is bounds-checked against the pack length ─────────────────────────────────────
+
+typedef struct { const uint8_t *p; size_t n, at; bool bad; } rd_t;
+static uint8_t rd8(rd_t *r) { if (r->at + 1 > r->n) { r->bad = true; return 0; } return r->p[r->at++]; }
+static uint16_t rd16(rd_t *r)
+{
+ if (r->n - r->at < 2 || r->at > r->n) { r->bad = true; return 0; }
+ uint16_t v = (uint16_t)(r->p[r->at] | r->p[r->at + 1] << 8);
+ r->at += 2;
+ return v;
+}
+
+// Walk one packed row (ht_cell_frame_t) at `start + off`, never leaving [0, n). Returns the offset past it, or 0.
+static size_t walk_row(const uint8_t *buf, size_t n, size_t at, unsigned cols)
+{
+ unsigned x = 0;
+ while (x < cols) {
+ if (n - at < 2 || at > n) return 0;
+ unsigned skip = buf[at], run = buf[at + 1];
+ at += 2;
+ if (!skip && !run) return 0; // no progress: ht_cell_at would never finish
+ if (x + skip + run > cols || n - at < run) return 0;
+ at += run;
+ x += skip + run;
+ }
+ return at;
+}
+
+typedef struct { uint8_t n; uint16_t ms; int16_t dx, dy; uint16_t idx[255]; } scene_raw_t;
+
+// parse's working arrays (~3.7 KB), kept off the 6 KiB cable reader task's stack. parse runs only on the cable
+// task (from pet_store_finish), one at a time, so one static copy is enough.
+static struct { uint16_t small[LOOPS][255]; scene_raw_t sc[SCENES]; } s_scratch;
+
+static unsigned gcd(unsigned a, unsigned b) { while (b) { unsigned t = a % b; a = b; b = t; } return a; }
+
+// Build the ht_pet_t of `p` from p->buf. 0 or PET_ERR_SHAPE.
+static int parse(pack_t *p)
+{
+ rd_t r = {p->buf, p->size, HEADER, false};
+ unsigned pal = rd8(&r);
+ if (r.bad || pal == 0) return PET_ERR_SHAPE;
+ for (unsigned i = 0; i < pal; i++) p->palette[i] = rd16(&r);
+ unsigned w = rd16(&r), h = rd16(&r);
+ if (r.bad || !w || !h) return PET_ERR_SHAPE;
+
+ uint16_t (*small)[255] = s_scratch.small;
+ uint8_t small_n[LOOPS];
+ for (int l = 0; l < LOOPS; l++) {
+ small_n[l] = rd8(&r);
+ for (unsigned i = 0; i < small_n[l]; i++) small[l][i] = rd16(&r);
+ }
+ scene_raw_t *sc = s_scratch.sc;
+ for (int s = 0; s < SCENES; s++) {
+ sc[s].n = rd8(&r);
+ sc[s].ms = rd16(&r);
+ sc[s].dx = (int16_t)rd16(&r);
+ sc[s].dy = (int16_t)rd16(&r);
+ if (sc[s].dx > 480 || sc[s].dx < -480 || sc[s].dy > 480 || sc[s].dy < -480) return PET_ERR_SHAPE;
+ for (unsigned i = 0; i < sc[s].n; i++) sc[s].idx[i] = rd16(&r);
+ }
+ unsigned count = rd16(&r);
+ if (r.bad || !count || !small_n[0]) return PET_ERR_SHAPE;
+ if (count > (p->size - r.at) / 3) return PET_ERR_SHAPE; // a frame is at least 3 bytes
+
+ // Two passes over the frames: validate and count the rows, then fill.
+ size_t frames_at = r.at, total_rows = 0;
+ for (int pass = 0; pass < 2; pass++) {
+ r.at = frames_at;
+ size_t row_base = 0;
+ for (unsigned f = 0; f < count; f++) {
+ unsigned cols = rd8(&r), rows = rd8(&r), cell = rd8(&r);
+ if (r.bad || !cols || !rows || !cell || cols * cell > 480 || rows * cell > 480) return PET_ERR_SHAPE;
+ size_t table = r.at;
+ if (p->size - r.at < (size_t)rows * 2) return PET_ERR_SHAPE;
+ r.at += (size_t)rows * 2;
+ size_t start = r.at, end = start;
+ for (unsigned y = 0; y < rows; y++) {
+ size_t off = (size_t)(p->buf[table + y * 2] | p->buf[table + y * 2 + 1] << 8);
+ if (start + off >= p->size) return PET_ERR_SHAPE;
+ size_t row_end = walk_row(p->buf, p->size, start + off, cols);
+ if (!row_end) return PET_ERR_SHAPE;
+ if (row_end > end) end = row_end;
+ if (pass) p->row_at[row_base + y] = (uint16_t)off;
+ }
+ if (end - start > 0xffff) return PET_ERR_SHAPE;
+ if (pass) {
+ p->frames[f] = (ht_cell_frame_t){(uint8_t)cols, (uint8_t)rows, (uint8_t)cell, p->palette,
+ p->buf + start, p->row_at + row_base};
+ }
+ row_base += rows;
+ r.at = end;
+ }
+ if (r.at != p->size) return PET_ERR_SHAPE; // trailing bytes
+ if (!pass) {
+ total_rows = row_base;
+ p->frames = PET_CALLOC(count, sizeof *p->frames);
+ p->row_at = PET_CALLOC(total_rows, sizeof *p->row_at);
+ if (!p->frames || !p->row_at) return PET_ERR_SHAPE;
+ }
+ }
+
+ // Frame indices must exist; the engine's loops hold them in a byte, so a referenced index > 255 is a
+ // shape error (a pack with more frames than that is fine while its loops stay among the first 256).
+ for (int l = 0; l < LOOPS; l++)
+ for (unsigned i = 0; i < small_n[l]; i++)
+ if (small[l][i] >= count || small[l][i] > 255) return PET_ERR_SHAPE;
+ for (int s = 0; s < SCENES; s++)
+ for (unsigned i = 0; i < sc[s].n; i++)
+ if (sc[s].idx[i] >= count || sc[s].idx[i] > 255) return PET_ERR_SHAPE;
+
+ // The small pet. A loop longer than HT_PET_STEPS is cut; the loops share one length (the least common
+ // multiple of theirs when it fits, else the longest) and shorter ones repeat to fill it.
+ unsigned len[LOOPS], steps = 1, longest = 0;
+ for (int l = 0; l < LOOPS; l++) {
+ unsigned n = small_n[l] ? small_n[l] : small_n[0];
+ len[l] = n > HT_PET_STEPS ? HT_PET_STEPS : n;
+ if (len[l] > longest) longest = len[l];
+ steps = steps / gcd(steps, len[l]) * len[l];
+ if (steps > HT_PET_STEPS) steps = HT_PET_STEPS;
+ }
+ if (steps < longest || steps % longest) steps = longest;
+ static const int state_of[LOOPS] = {HT_PET_IDLE, HT_PET_DONE, HT_PET_ASKING};
+ for (int l = 0; l < LOOPS; l++) {
+ const uint16_t *src = small_n[l] ? small[l] : small[0];
+ for (unsigned i = 0; i < steps; i++)
+ p->loops[state_of[l]][i] = (ht_pet_step_t){(uint8_t)src[i % len[l]], 0};
+ }
+ memcpy(p->loops[HT_PET_WORKING], p->loops[HT_PET_IDLE], sizeof p->loops[0]);
+ for (int s = 0; s < HT_PET_STATES; s++) p->step_ms[s] = STEP_MS;
+
+ // The scenes: working, listening, sending (failed, the fourth, is validated above and not drawn).
+ for (int s = 0; s < 3; s++) {
+ if (!sc[s].n || !sc[s].ms) continue; // absent: the built-in fallback draws
+ unsigned levels = s == 1 ? HT_PET_SCENE_LEVELS : 1;
+ p->scene_loop[s] = PET_CALLOC((size_t)sc[s].n * levels, 1);
+ if (!p->scene_loop[s]) return PET_ERR_SHAPE;
+ unsigned sw = 0, sh = 0;
+ for (unsigned i = 0; i < sc[s].n; i++) {
+ const ht_cell_frame_t *f = &p->frames[sc[s].idx[i]];
+ if (f->cols * f->cell > sw) sw = (unsigned)f->cols * f->cell;
+ if (f->rows * f->cell > sh) sh = (unsigned)f->rows * f->cell;
+ for (unsigned lv = 0; lv < levels; lv++) p->scene_loop[s][lv * sc[s].n + i] = (uint8_t)sc[s].idx[i];
+ }
+ p->scenes[s] = (ht_pet_scene_t){.w = (uint16_t)sw, .h = (uint16_t)sh, .frames = p->frames,
+ .loop = p->scene_loop[s], .steps = sc[s].n, .step_ms = sc[s].ms,
+ .dx = sc[s].dx, .dy = sc[s].dy};
+ }
+
+ p->pet = (ht_pet_t){.engine = NULL, .w = (uint16_t)w, .h = (uint16_t)h, .frames = NULL,
+ .loops = p->loops, .step_ms = p->step_ms,
+ .working_scene = sc[0].n && sc[0].ms ? &p->scenes[0] : NULL,
+ .listening_scene = sc[1].n && sc[1].ms ? &p->scenes[1] : NULL,
+ .sending_scene = sc[2].n && sc[2].ms ? &p->scenes[2] : NULL,
+ .cells = p->frames, .alert_scene = NULL,
+ .steps = (uint8_t)(steps == HT_PET_STEPS ? 0 : steps)};
+ return 0;
+}
+
+// ── the API ───────────────────────────────────────────────────────────────────────────────────────────
+
+bool pet_store_offer(const char *id, uint32_t size, uint32_t crc)
+{
+ if (!valid_id(id) || size <= HEADER || size > PET_STORE_MAX_BYTES) return false;
+ lock();
+ bool ok = false;
+ pack_free(s_in); // a resent pack replaces a cut one
+ s_in = NULL;
+ unsigned held = 0;
+ bool same = false;
+ for (int i = 0; i < PET_STORE_MAX_PACKS; i++)
+ if (s_packs[i]) { held++; if (!strcmp(s_packs[i]->id, id)) same = true; }
+ if (held < PET_STORE_MAX_PACKS || same) {
+ pack_t *p = PET_CALLOC(1, sizeof *p);
+ if (p) p->buf = PET_MALLOC(size);
+ if (p && p->buf) {
+ memcpy(p->id, id, MAX_ID);
+ p->size = size;
+ p->crc = crc;
+ s_in = p;
+ ok = true;
+ } else {
+ pack_free(p);
+ }
+ }
+ unlock();
+ return ok;
+}
+
+bool pet_store_slice(const uint8_t *data, size_t len)
+{
+ lock();
+ bool ok = s_in && data && len <= s_in->size - s_in->got;
+ if (ok) {
+ memcpy(s_in->buf + s_in->got, data, len);
+ s_in->got += (uint32_t)len;
+ } else {
+ pack_free(s_in);
+ s_in = NULL;
+ }
+ unlock();
+ return ok;
+}
+
+int pet_store_finish(void)
+{
+ lock();
+ pack_t *p = s_in;
+ s_in = NULL;
+ unlock();
+ if (!p) return PET_ERR_SHAPE;
+
+ int err = 0;
+ const uint8_t *b = p->buf;
+ uint32_t stored_crc = (uint32_t)(b[18] | b[19] << 8 | b[20] << 16 | (uint32_t)b[21] << 24);
+ uint32_t stored_len = (uint32_t)(b[14] | b[15] << 8 | b[16] << 16 | (uint32_t)b[17] << 24);
+ char hex[MAX_ID];
+ for (int i = 0; i < 8; i++) { hex[i * 2] = "0123456789abcdef"[b[6 + i] >> 4]; hex[i * 2 + 1] = "0123456789abcdef"[b[6 + i] & 15]; }
+ hex[16] = 0;
+ if (p->got != p->size || memcmp(b, "HPET", 4) || stored_len != p->size || strcmp(hex, p->id)) err = PET_ERR_SHAPE;
+ else if (b[4] != 1) err = PET_ERR_VERSION;
+ else if (crc32_ieee(b + HEADER, p->size - HEADER) != stored_crc || stored_crc != p->crc) err = PET_ERR_CRC;
+ else err = parse(p);
+ if (err) { pack_free(p); return err; }
+
+ lock();
+ for (int i = 0; i < PET_STORE_MAX_PACKS; i++) // the same id replaces its older copy
+ if (s_packs[i] && !strcmp(s_packs[i]->id, p->id)) { retire(s_packs[i]); s_packs[i] = NULL; }
+ int slot = -1;
+ for (int i = 0; i < PET_STORE_MAX_PACKS && slot < 0; i++) if (!s_packs[i]) slot = i;
+ if (slot < 0) { unlock(); pack_free(p); return PET_ERR_SHAPE; } // offer() checked; only a racing offer gets here
+ s_packs[slot] = p;
+ unlock();
+ return 0;
+}
+
+void pet_store_abort(void)
+{
+ lock();
+ pack_free(s_in);
+ s_in = NULL;
+ unlock();
+}
+
+void pet_store_map(const char *all, const char *const *engines, const char *const *ids, size_t n)
+{
+ lock();
+ map_t *m = &s_stage_map;
+ memset(m, 0, sizeof *m);
+ if (all && strlen(all) < MAX_ID) strcpy(m->all, all);
+ size_t k = 0;
+ for (size_t i = 0; i < n && k < MAX_ENGINES; i++) {
+ if (!engines[i] || !ids[i] || strlen(engines[i]) >= sizeof m->engines[0].engine || strlen(ids[i]) >= MAX_ID) continue;
+ strcpy(m->engines[k].engine, engines[i]);
+ strcpy(m->engines[k].id, ids[i]);
+ k++;
+ }
+ unlock();
+}
+
+void pet_store_drop(const char *id)
+{
+ if (!id) return;
+ lock();
+ if (s_in && !strcmp(s_in->id, id)) { pack_free(s_in); s_in = NULL; } // the daemon gave up on this transfer
+ for (int i = 0; i < PET_STORE_MAX_PACKS; i++)
+ if (s_packs[i] && !strcmp(s_packs[i]->id, id)) { retire(s_packs[i]); s_packs[i] = NULL; }
+ unlock();
+}
+
+static pack_t *live_pack(const char *id)
+{
+ if (!id || !id[0]) return NULL;
+ for (int i = 0; i < PET_STORE_MAX_PACKS; i++)
+ if (s_live[i] && !strcmp(s_live[i]->id, id)) return s_live[i];
+ return NULL;
+}
+
+const ht_pet_t *pet_store_lookup(const char *engine)
+{
+ lock();
+ pack_t *p = NULL;
+ for (int i = 0; engine && !p && i < MAX_ENGINES; i++)
+ if (s_live_map.engines[i].engine[0] && !strcmp(s_live_map.engines[i].engine, engine))
+ p = live_pack(s_live_map.engines[i].id);
+ if (!p) p = live_pack(s_live_map.all);
+ unlock();
+ return p ? &p->pet : NULL;
+}
+
+size_t pet_store_held(char ids[][17], size_t max)
+{
+ size_t n = 0;
+ lock();
+ for (int i = 0; i < PET_STORE_MAX_PACKS && n < max; i++)
+ if (s_packs[i]) memcpy(ids[n++], s_packs[i]->id, MAX_ID);
+ unlock();
+ return n;
+}
+
+void pet_store_release_frame(void)
+{
+ pack_t *dead = NULL;
+ lock();
+ for (int i = 0; i < PET_STORE_MAX_PACKS; i++) {
+ pack_t *p = s_live[i];
+ bool kept = false;
+ for (int j = 0; p && j < PET_STORE_MAX_PACKS; j++) if (s_packs[j] == p) kept = true;
+ if (p && !kept) { p->next = dead; dead = p; }
+ }
+ memcpy(s_live, s_packs, sizeof s_live);
+ s_live_map = s_stage_map;
+ unlock();
+ while (dead) { pack_t *next = dead->next; pack_free(dead); dead = next; }
+}
diff --git a/devices/harness-device/firmware/main/pet_store.h b/devices/harness-device/firmware/main/pet_store.h
new file mode 100644
index 000000000..995634e8b
--- /dev/null
+++ b/devices/harness-device/firmware/main/pet_store.h
@@ -0,0 +1,53 @@
+// The custom pets the daemon sends over the cable (cli/src/cable/pets/pack.ts is the source of truth for
+// the HPET pack format). Up to four packs are held in PSRAM; a mapping says which pack draws for which
+// engine, and `pet_store_lookup` hands the UI an ht_pet_t built from the pack.
+//
+// DELIBERATELY FREE OF ESP-IDF headers except where ESP_PLATFORM is defined: pet_store.c also compiles on a
+// host, which is how test/test_pet_store.c runs.
+//
+// Threads: the cable task calls everything except lookup and release_frame; the UI task calls those two.
+// One mutex guards the table. A pack is immutable once published, so the pointer lookup returns stays valid
+// without the mutex until the UI calls `pet_store_release_frame`; a pack dropped or replaced meanwhile is
+// parked and freed by that call (see pet_store.c).
+#pragma once
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+
+#include "ui/habitat/pets.h"
+
+#define PET_STORE_MAX_PACKS 4
+#define PET_STORE_MAX_BYTES (1024u * 1024u)
+
+// pet_store_finish results besides 0.
+#define PET_ERR_CRC 1
+#define PET_ERR_VERSION 2
+#define PET_ERR_SHAPE 3
+
+// Start receiving pack `id` (16 hex chars) of `size` bytes whose CRC-32 is `crc`. Replaces a partial pack
+// still being received. False: not enough memory, a bad size/id, or four other packs already held (the
+// caller tells the two apart with pet_store_held and answers `busy` or `memory`).
+bool pet_store_offer(const char *id, uint32_t size, uint32_t crc);
+// Append received bytes. False: nothing is being received or more bytes than offered; the partial pack is
+// discarded.
+bool pet_store_slice(const uint8_t *data, size_t len);
+// Verify and parse the received pack and hold it. 0 or PET_ERR_*; on error the partial pack is discarded
+// and every held pack is untouched.
+int pet_store_finish(void);
+// Discard only the partial pack being received (the link dropped). Held packs stay.
+void pet_store_abort(void);
+
+// Replace the mapping: `all` (NULL = none) and engines[i] -> ids[i].
+void pet_store_map(const char *all, const char *const *engines, const char *const *ids, size_t n);
+// Forget a held pack, or abort the partial pack still being received under that id. A held pack is is freed once the frame that may still draw it is over.
+void pet_store_drop(const char *id);
+// The pet for `engine`: the engine's own mapping, else "all", else NULL, from the snapshot the last
+// pet_store_release_frame took: map, drop and finish only STAGE a change, so every lookup between two releases
+// agrees. Valid until the next release_frame.
+const ht_pet_t *pet_store_lookup(const char *engine);
+// The ids of the held packs, 16 chars + NUL each; returns how many were written (<= max).
+size_t pet_store_held(char ids[][17], size_t max);
+// The UI is done with the pointers lookup returned this frame: apply the staged mapping and packs (the new snapshot
+// for the lookups that follow) and free the packs the old snapshot held that are gone. Render task, once per take.
+void pet_store_release_frame(void);
diff --git a/devices/harness-device/firmware/main/ui/habitat/focus.c b/devices/harness-device/firmware/main/ui/habitat/focus.c
index 76bfef85c..27e6d9341 100644
--- a/devices/harness-device/firmware/main/ui/habitat/focus.c
+++ b/devices/harness-device/firmware/main/ui/habitat/focus.c
@@ -2,6 +2,7 @@
#include "pets.h"
#include "focus_faces.h"
#include "theme.h"
+#include "../../pet_store.h"
#include <math.h>
#include <stdio.h>
#include <string.h>
@@ -162,10 +163,14 @@ static bool pet_holds(const ht_character_face_t *f)
return !f->clock_ms || f->mood == HT_CHARACTER_ASLEEP || f->mood == HT_CHARACTER_OFFLINE;
}
-// The pet of the face's engine, or NULL: the face draws the engine's mark.
+// The pet of the face's engine, or NULL: the face draws the engine's mark. A pack the person sent (pet_store.c:
+// the engine's own, else "all") wins over the built-in pet; its pointers stay good until ui_habitat.c's next
+// pet_store_release_frame, which comes only after the frame built from them has been painted.
static const ht_pet_t *pet_for(const ht_character_face_t *f)
{
if (!f->engine) return NULL;
+ const ht_pet_t *custom = pet_store_lookup(f->engine);
+ if (custom) return custom;
for (unsigned i = 0; i < ht_pet_count; i++)
if (!strcmp(f->engine, ht_pets[i].engine)) return &ht_pets[i];
return NULL;
@@ -195,7 +200,7 @@ static const ht_pet_scene_t *alert_scene(const ht_character_face_t *f, const cha
{
const ht_pet_scene_t *work = working_scene(f, recap);
const ht_pet_t *pet = pet_for(f);
- if (!work || !pet->alert_scene || !f->notice_ms || !f->notices) return NULL;
+ if (!work || !pet || !pet->alert_scene || !f->notice_ms || !f->notices) return NULL;
const ht_pet_scene_t *a = pet->alert_scene;
uint32_t age = f->clock_ms - f->notice_ms;
bool past = age >= (uint32_t)a->steps * a->step_ms;
@@ -203,15 +208,48 @@ static const ht_pet_scene_t *alert_scene(const ht_character_face_t *f, const cha
if (held) *held = past;
return a;
}
+/*
+ * THE ALERT OF A PET WITHOUT ONE (a custom pack has no alert_scene: the person's art has no bubble): drawn in code, a
+ * blue box ALERT_W x ALERT_H (gen_pets.py's bubble size) centred on the working scene's top-right corner inset
+ * ALERT_INSET px, the count in it at once (there is no pop-in, so ht_focus_alert_pop_ms is 0). It takes the same run
+ * slots the built-in bubble does (the second recap slot the box, the third the count), so the face's runs never change.
+ * Pulled toward the glass's centre until its rounded outline lies inside r 230 (a scene placed far out by its dx, dy).
+ */
+enum { ALERT_W = 68, ALERT_H = 44, ALERT_INSET = 8, ALERT_R = 13, ALERT_GLASS_R = 230 };
+#define ALERT_BLUE 0x006fffu
+static bool code_alert(const ht_character_face_t *f, const char *recap, ht_rect_t *box)
+{
+ const ht_pet_scene_t *work = working_scene(f, recap);
+ const ht_pet_t *pet = pet_for(f);
+ if (!work || !pet || pet->alert_scene || !f->notice_ms || !f->notices) return false;
+ if (box) {
+ int sx, sy;
+ scene_origin(work, 4, &sx, &sy);
+ int x = sx + work->w - ALERT_INSET - ALERT_W / 2, y = sy + ALERT_INSET - ALERT_H / 2;
+ for (int guard = 0; guard < 240; guard++) { // the farthest corner's arc centre, plus the radius, inside r 230
+ int cx = x + ALERT_W / 2 >= HT_WIDTH / 2 ? x + ALERT_W - ALERT_R : x + ALERT_R;
+ int cy = y + ALERT_H / 2 >= HT_HEIGHT / 2 ? y + ALERT_H - ALERT_R : y + ALERT_R;
+ int dx = cx - HT_WIDTH / 2, dy = cy - HT_HEIGHT / 2, room = ALERT_GLASS_R - ALERT_R - 1;
+ if (dx * dx + dy * dy <= room * room) break;
+ if (x + ALERT_W / 2 > HT_WIDTH / 2) x--; else if (x + ALERT_W / 2 < HT_WIDTH / 2) x++;
+ if (y + ALERT_H / 2 > HT_HEIGHT / 2) y--; else if (y + ALERT_H / 2 < HT_HEIGHT / 2) y++;
+ }
+ *box = (ht_rect_t){x, y, ALERT_W, ALERT_H};
+ }
+ return true;
+}
bool ht_focus_alert_shown(const ht_character_face_t *f, const char *recap, ht_rect_t *at)
{
+ if (code_alert(f, recap, at)) return true;
uint32_t step = 0;
const ht_pet_scene_t *a = alert_scene(f, recap, &step, NULL);
if (!a) return false;
+ const ht_pet_scene_t *work = working_scene(f, recap);
+ if (!work) return false;
if (at) { // the step's bubble on the glass (nothing while it has not popped in yet)
const ht_cell_frame_t *b = &a->overlay->frames[a->overlay->loop[step]];
int ox, oy;
- scene_origin(working_scene(f, recap), 4, &ox, &oy);
+ scene_origin(work, 4, &ox, &oy);
bool none = !a->overlay->at[step][0] && !a->overlay->at[step][1];
*at = none ? (ht_rect_t){0} : (ht_rect_t){ox + a->overlay->at[step][0], oy + a->overlay->at[step][1],
b->cols * b->cell, b->rows * b->cell};
@@ -423,7 +461,7 @@ uint32_t ht_focus_pet_next_ms(const ht_character_face_t *f, const char *recap)
bool held;
const ht_pet_scene_t *alert = alert_scene(f, recap, &alert_step, &held);
const ht_pet_scene_t *sc = working_scene(f, recap);
- if (alert && !held) { // its next step (the last one then holds), or the work's next frame if that comes first
+ if (alert && !held && sc) { // its next step (the last one then holds), or the work's next frame if that comes first
uint32_t next = f->notice_ms + (alert_step + 1) * alert->step_ms, work = scene_next_ms(sc, 0, f->clock_ms);
return work && work < next ? work : next;
}
@@ -804,7 +842,9 @@ void ht_focus_face(ht_scene_t *s, const ht_character_face_t *f, uint8_t frame, u
const ht_pet_t *pet = pet_for(f);
const ht_pet_scene_t *scene = working_scene(f, recap);
uint32_t alert_step = 0;
- const ht_pet_scene_t *alert = alert_scene(f, recap, &alert_step, NULL);
+ const ht_pet_scene_t *alert = scene ? alert_scene(f, recap, &alert_step, NULL) : NULL; // never without its scene
+ ht_rect_t drawn_alert;
+ bool coded = !alert && code_alert(f, recap, &drawn_alert); // a custom pet's alert, drawn in code
if (scene) {
// The working scene in the mark's slot: centred on the glass, a touch low for its hat.
int sx, sy;
@@ -849,7 +889,7 @@ void ht_focus_face(ht_scene_t *s, const ht_character_face_t *f, uint8_t frame, u
// The scene's overlay takes the first line's slot, empty without a recap; the alert's bubble the second, its
// count the third.
int sx = 0, sy = 0;
- if (alert) scene_origin(scene, 4, &sx, &sy);
+ if (alert && scene) scene_origin(scene, 4, &sx, &sy);
if (alert && n == 1) {
ht_cell_sprite(s, sx + alert->overlay->at[alert_step][0], sy + alert->overlay->at[alert_step][1],
&alert->overlay->frames[alert->overlay->loop[alert_step]]);
@@ -866,6 +906,17 @@ void ht_focus_face(ht_scene_t *s, const ht_character_face_t *f, uint8_t frame, u
(cy - sy - alert->overlay->at[alert_step][1]) / b->cell)];
uint16_t fill = (uint16_t)((p >> 8) | (p << 8));
ht_text(s, cx - cw / 2, cy - cf->height / 2, cw, cf, ht_rgb(0x006fff), fill, count);
+ } else if (coded && n == 1) {
+ ht_box(s, drawn_alert.x, drawn_alert.y, ALERT_W, ALERT_H, ALERT_R, ht_rgb(ALERT_BLUE), ht_rgb(ALERT_BLUE));
+ } else if (coded && n == 2) {
+ // The built-in count's fonts; on this blue bubble the digit is the soft white of the bell pill's.
+ const ht_font_t *cf = f->notices > 9 ? &ht_lv_inter_20.base : &ht_lv_inter_med_26.base;
+ char count[4];
+ if (f->notices > 9) snprintf(count, sizeof count, "9+");
+ else snprintf(count, sizeof count, "%u", (unsigned)f->notices);
+ int cw = ht_measure(cf, count);
+ ht_text(s, drawn_alert.x + (ALERT_W - cw) / 2, drawn_alert.y + (ALERT_H - cf->height) / 2, cw, cf,
+ ht_rgb(FOCUS_FG), ht_rgb(ALERT_BLUE), count);
} else if (n == 0 && scene && scene->overlay)
scene_overlay(s, scene, 4, 0, f->clock_ms, rf);
else no_text(s, rf);
diff --git a/devices/harness-device/firmware/main/ui/habitat/ui_habitat.c b/devices/harness-device/firmware/main/ui/habitat/ui_habitat.c
index 6b2f23d52..95fc822b4 100644
--- a/devices/harness-device/firmware/main/ui/habitat/ui_habitat.c
+++ b/devices/harness-device/firmware/main/ui/habitat/ui_habitat.c
@@ -25,6 +25,7 @@ static ht_gallery_t gallery;
#include "audio_capture.h"
#include "config_store.h"
#include "cable_client.h"
+#include "pet_store.h"
#include "esp_attr.h"
#include "esp_timer.h"
#include "esp_log.h"
@@ -2087,6 +2088,7 @@ bool habitat_scene_take(ht_scene_t *f)
{
#ifdef DEVICE_CREATURE_GALLERY
// App snapshots never choose a scene in this visual-only build.
+ pet_store_release_frame();
if (!s.ready) return false;
return ht_gallery_take(&gallery, f, ms());
#endif
@@ -2095,6 +2097,14 @@ bool habitat_scene_take(ht_scene_t *f)
s.dirty = false;
s.notice_frame = 0;
s.hit_count = 0;
+ // The custom pets' memory (pet_store.c): a pack dropped or replaced since the last scene was built is freed here.
+ // The render task is the only caller, and it paints each scene before it takes the next (display_habitat.c), so
+ // nothing drawn from those packs is still being rasterised. The scene it keeps as `front` (for the next damage
+ // diff, or a forced repaint of a wake) was built before this call, so its sprites may point at packs freed here.
+ // That is safe only because ht_damage compares sprite pointers and bounds and never dereferences them; any change
+ // that reads sprite data of the previous frame must keep that frame's packs alive. This call also applies the
+ // staged pet mapping, so every pet lookup while building this scene sees one snapshot.
+ pet_store_release_frame();
ht_scene_clear(f, BG);
switch (s.view) {
case FORM:
@@ -3561,6 +3571,14 @@ void ui_set_brightness(uint8_t level)
display_unlock();
}
+// The cable task staged a pet change (pet_store.c); mark the scene dirty so the next take applies it.
+void ui_pets_changed(void)
+{
+ display_lock();
+ change();
+ display_unlock();
+}
+
// Protocol-facing adapter. The cable reader never waits for rendering or a DMA transaction.
void ui_set_connected(bool value)
{
diff --git a/devices/harness-device/firmware/main/ui/ui_screens.h b/devices/harness-device/firmware/main/ui/ui_screens.h
index a5d82cec9..0eb58742a 100644
--- a/devices/harness-device/firmware/main/ui/ui_screens.h
+++ b/devices/harness-device/firmware/main/ui/ui_screens.h
@@ -76,6 +76,8 @@ void ui_enter_link_guide(void);
void ui_leave_remote_offline_loading(void);
// Global commander connection indicator (shown on every tile's header).
void ui_set_connected(bool connected);
+// The custom pets changed (pet.map, a finished pack, pet.drop): redraw so the dial applies them at the next scene.
+void ui_pets_changed(void);
// Node (paired machine) online↔offline from the `node_status` frame — distinct from ui_set_connected
// Ensure a tile exists for project_id (creates one if new). Safe to call repeatedly.
// Set/refresh the human name shown on a project's tile.
diff --git a/devices/harness-device/firmware/test/run.sh b/devices/harness-device/firmware/test/run.sh
index ee424b0a0..227a97009 100644
--- a/devices/harness-device/firmware/test/run.sh
+++ b/devices/harness-device/firmware/test/run.sh
@@ -20,14 +20,24 @@ python3 "$here/../scripts/gen_pets.py" --check
python3 "$here/../scripts/gen_arc_geometry.py" --check
cc -std=c11 -Wall -Wextra -Werror -O1 -g -fsanitize="${SANITIZERS:-undefined,bounds}" \
- -o "$out/test_character" "$here/test_character.c" \
+ -I "$here/../main" -o "$out/test_character" "$here/test_character.c" "$here/../main/pet_store.c" \
"$here/../main/ui/habitat/character.c" "$here/../main/ui/habitat/illustrated.c" "$here/../main/ui/habitat/character_motion.c" \
"$here/../main/ui/habitat/character_layout.c" "$here/../main/ui/habitat/tux.c" \
"$here/../main/ui/habitat/focus.c" "$here/../main/ui/habitat/lvgl_fonts.c" "$here/../main/ui/habitat/lvgl_icons.c" "$here/../main/ui/habitat/focus_marks.c" "$here/../main/ui/habitat/focus_faces.c" "$here/../main/ui/habitat/pets.c" \
"$here/../main/ui/habitat/octopus.c" "$here/../main/ui/habitat/octopus_font.c" \
"$here/../main/ui/habitat/ascii_clip.c" \
"$here/../main/ui/habitat/terminal.c" "$here/../main/ui/habitat/fonts.c"
-"$out/test_character"
+"$out/test_character" "$here/vectors/pet_min.hpet"
+# The same source again, only the custom-pet cases, under the address sanitizer: a pack read after it is freed.
+cc -std=c11 -Wall -Wextra -Werror -O1 -g -fsanitize="${PET_SANITIZERS:-address,undefined}" \
+ -I "$here/../main" -o "$out/test_character_asan" "$here/test_character.c" "$here/../main/pet_store.c" \
+ "$here/../main/ui/habitat/character.c" "$here/../main/ui/habitat/illustrated.c" "$here/../main/ui/habitat/character_motion.c" \
+ "$here/../main/ui/habitat/character_layout.c" "$here/../main/ui/habitat/tux.c" \
+ "$here/../main/ui/habitat/focus.c" "$here/../main/ui/habitat/lvgl_fonts.c" "$here/../main/ui/habitat/lvgl_icons.c" "$here/../main/ui/habitat/focus_marks.c" "$here/../main/ui/habitat/focus_faces.c" "$here/../main/ui/habitat/pets.c" \
+ "$here/../main/ui/habitat/octopus.c" "$here/../main/ui/habitat/octopus_font.c" \
+ "$here/../main/ui/habitat/ascii_clip.c" \
+ "$here/../main/ui/habitat/terminal.c" "$here/../main/ui/habitat/fonts.c" -lm
+"$out/test_character_asan" "$here/vectors/pet_min.hpet" --custom-only
python3 "$here/test_character_preferences.py"
cc -std=c11 -Wall -Wextra -Werror -O1 \
@@ -85,6 +95,13 @@ cc -std=c11 -Wall -Wextra -Werror -O1 -g -fsanitize="${SANITIZERS:-undefined,bou
"$here/../main/ui/habitat/terminal.c" "$here/../main/ui/habitat/fonts.c" -lm
"$out/test_cell_zoom"
+# Custom pets: the pack parser and store, on the daemon's own vector (cli/src/cable/pets/pack.ts). Address sanitizer
+# where the host has it, so a read past a pack or a use after the dropped pack's frame is an error, not a guess.
+cc -std=c11 -Wall -Wextra -Werror -O1 -g -fsanitize="${PET_SANITIZERS:-address,undefined}" \
+ -I "$here/../main" -o "$out/test_pet_store" "$here/test_pet_store.c" \
+ "$here/../main/ui/habitat/terminal.c" "$here/../main/ui/habitat/fonts.c" -lm
+"$out/test_pet_store" "$here/vectors/pet_min.hpet"
+
cc -std=c11 -Wall -Wextra -Werror -O1 -g -fsanitize="${SANITIZERS:-undefined,bounds}" \
-o "$out/test_voice_buffer" "$here/test_voice_buffer.c" "$here/../main/voice_buffer.c"
"$out/test_voice_buffer"
diff --git a/devices/harness-device/firmware/test/test_character.c b/devices/harness-device/firmware/test/test_character.c
index a9a00f166..7dd4a66e7 100644
--- a/devices/harness-device/firmware/test/test_character.c
+++ b/devices/harness-device/firmware/test/test_character.c
@@ -4,6 +4,7 @@
#include "../main/ui/habitat/pets.h"
#include "../main/ui/habitat/focus.h"
#include "../main/ui/habitat/focus_faces.h"
+#include "../main/pet_store.h"
#include <assert.h>
#include <math.h>
#include <stdio.h>
@@ -1670,11 +1671,230 @@ static void inbox_layout(void)
puts("Inbox layout: desktop status colors, neutral prose, balanced short/long blocks, fixed gap, circle bounds and exact incremental redraws PASS");
}
-int main(void)
+/*
+ * THE CUSTOM PET (docs/superpowers/plans/2026-10-08-custom-pet.md, Task 7): a pack the daemon sent, mapped as "all",
+ * draws on the Focus face in place of the built-in pet — the same run count and order, the working alert drawn in
+ * code, the ink inside r 230, and a pack dropped mid-frame still readable until the frame is released. The vector is
+ * the daemon's own encoder output (test/vectors/pet_min.hpet): two 8 x 8 frames, a working scene of the second.
+ */
+static uint8_t vec_buf[4096];
+static size_t vec_len;
+static const char *VEC_ID = "0102030405060708";
+static uint32_t crc32_of(const uint8_t *p, size_t n)
+{
+ uint32_t c = 0xffffffffu;
+ for (size_t i = 0; i < n; i++) {
+ c ^= p[i];
+ for (int k = 0; k < 8; k++) c = (c >> 1) ^ (0xedb88320u & (0u - (c & 1u)));
+ }
+ return ~c;
+}
+static void put32le(uint8_t *p, uint32_t v) { for (int i = 0; i < 4; i++) p[i] = (uint8_t)(v >> (8 * i)); }
+// Offer + slice + finish + map as "all", the way the cable does; the bytes as given (a patched copy is resealed here).
+static void pack_load(const uint8_t *b, size_t n)
+{
+ put32le((uint8_t *)b + 14, (uint32_t)n);
+ put32le((uint8_t *)b + 18, crc32_of(b + 22, n - 22));
+ uint32_t crc = (uint32_t)(b[18] | b[19] << 8 | b[20] << 16 | (uint32_t)b[21] << 24);
+ assert(pet_store_offer(VEC_ID, (uint32_t)n, crc));
+ for (size_t at = 0; at < n; at += 50) assert(pet_store_slice(b + at, n - at < 50 ? n - at : 50));
+ assert(pet_store_finish() == 0);
+ pet_store_map(VEC_ID, NULL, NULL, 0);
+ pet_store_release_frame(); // the next take: the staged pack and mapping go live
+}
+static void pack_unload(void)
+{
+ pet_store_drop(VEC_ID);
+ pet_store_map(NULL, NULL, NULL, 0);
+ pet_store_release_frame();
+}
+// The offset of the working scene's dx in the vector (the walk test_pet_store.c does): palette, size, three loops.
+static size_t working_dx_at(void)
+{
+ size_t pos = 22;
+ pos += 1 + 2u * vec_buf[pos];
+ pos += 4;
+ for (int l = 0; l < 3; l++) pos += 1 + 2u * vec_buf[pos];
+ return pos + 3;
+}
+static ht_character_face_t custom_face(bool working, unsigned notices)
+{
+ ht_character_face_t f = {.recipient = "Payments refactor", .tab = "", .engine = "claude",
+ .activity = working ? "Coalescing" : "", .status = "", .hint = "", .detail = "",
+ .mood = working ? HT_CHARACTER_WORKING : HT_CHARACTER_IDLE, .clock_ms = 1000,
+ .foreground = 0xffff, .dim = 0x8410, .ink = 0xffff};
+ if (notices) { f.notice_ms = 500; f.notices = (uint16_t)notices; }
+ return f;
+}
+static void ink_inside_r230(const ht_scene_t *scene)
+{
+ ht_raster(scene, (ht_rect_t){0, 0, HT_WIDTH, HT_HEIGHT}, full);
+ for (int y = 0; y < HT_HEIGHT; y++) for (int x = 0; x < HT_WIDTH; x++)
+ if (full[y * HT_WIDTH + x]) assert((x - 233) * (x - 233) + (y - 233) * (y - 233) < 230 * 230);
+}
+// The code-drawn bubble of a scene: the 68 x 44 box filled 0x006fff; NULL when there is none.
+static const ht_run_t *alert_box(const ht_scene_t *scene)
+{
+ for (int i = 0; i < scene->count; i++)
+ if (scene->runs[i].box.h == 44 && scene->runs[i].w == 68 && scene->runs[i].box.fill == ht_rgb(0x006fff))
+ return &scene->runs[i];
+ return NULL;
+}
+static void focus_custom_pet_resting(void)
+{
+ ht_character_t c = {0};
+ assert(ht_character_select(&c, HT_CHARACTER_FOCUS));
+ ht_character_face_t f = custom_face(false, 0);
+ ht_scene_t builtin; ht_scene_clear(&builtin, 0);
+ ht_character_face(&builtin, &c, &f, 0xffff, "");
+ pack_load(vec_buf, vec_len);
+ ht_scene_t scene; ht_scene_clear(&scene, 0);
+ ht_character_face(&scene, &c, &f, 0xffff, "");
+ assert(scene.count == builtin.count); // THE RULE: same runs, same order
+ const ht_pet_t *pet = pet_store_lookup("claude");
+ assert(pet && pet->cells && !pet->alert_scene);
+ bool drawn = false;
+ for (int i = 0; i < scene.count; i++)
+ for (unsigned k = 0; k < 2; k++)
+ if (scene.runs[i].sprite.cells && scene.runs[i].sprite.cells == pet->cells[k].cells) drawn = true;
+ assert(drawn);
+ ink_inside_r230(&scene);
+ pet_store_release_frame();
+ pack_unload();
+}
+static void focus_custom_pet_working_alert(void)
+{
+ ht_character_t c = {0};
+ assert(ht_character_select(&c, HT_CHARACTER_FOCUS));
+ pack_load(vec_buf, vec_len);
+ const ht_pet_t *pet = pet_store_lookup("claude");
+ assert(pet && pet->working_scene && !pet->alert_scene);
+ int sw = pet->working_scene->w, sh = pet->working_scene->h;
+ int sx = (HT_WIDTH - sw) / 2 + pet->working_scene->dx, sy = HT_HEIGHT / 2 - sh / 2 + 4 + pet->working_scene->dy;
+ ht_character_face_t quiet = custom_face(true, 0), told = custom_face(true, 3), many = custom_face(true, 12);
+ ht_scene_t a, b, m;
+ ht_scene_clear(&a, 0); ht_character_face(&a, &c, &quiet, 0xffff, "");
+ ht_scene_clear(&b, 0); ht_character_face(&b, &c, &told, 0xffff, "");
+ ht_scene_clear(&m, 0); ht_character_face(&m, &c, &many, 0xffff, "");
+ assert(a.count == b.count && b.count == m.count); // the alert takes the slots the built-in one does
+ assert(!alert_box(&a));
+ const ht_run_t *box = alert_box(&b);
+ assert(box);
+ // Centred on the scene's top-right corner, inset 8 px: the scene's corner is at (sx + sw, sy).
+ assert(box->x + 34 == sx + sw - 8 && box->y + 22 == sy + 8);
+ ht_rect_t at = {0};
+ assert(ht_focus_alert_shown(&told, "", &at));
+ assert(at.x == box->x && at.y == box->y && at.w == 68 && at.h == 44); // the tap target covers it
+ assert(!ht_focus_alert_shown(&quiet, "", &at));
+ assert(ht_focus_alert_pop_ms(&told) == 0);
+ // The count: Inter Medium 26 for one digit, Inter 20 for "9+", on the bubble's fill, inside the box.
+ bool one = false, nine = false;
+ for (int i = 0; i < b.count; i++) if (b.runs[i].font == &ht_lv_inter_med_26.base && !strcmp(b.runs[i].text, "3")) one = true;
+ for (int i = 0; i < m.count; i++) if (m.runs[i].font == &ht_lv_inter_20.base && !strcmp(m.runs[i].text, "9+")) nine = true;
+ assert(one && nine);
+ ht_raster(&b, (ht_rect_t){0, 0, HT_WIDTH, HT_HEIGHT}, full);
+ const uint16_t blue = (uint16_t)((ht_rgb(0x006fff) >> 8) | (ht_rgb(0x006fff) << 8)); // the raster is in panel order
+ assert(full[(box->y + 22) * HT_WIDTH + box->x + 8] == blue); // the fill reaches the glass
+ int lit = 0; // ... and the digit is drawn in it
+ for (int y = box->y + 4; y < box->y + 40; y++) for (int x = box->x + 20; x < box->x + 48; x++)
+ lit += full[y * HT_WIDTH + x] != blue && full[y * HT_WIDTH + x] != 0;
+ assert(lit > 10);
+ ink_inside_r230(&b);
+ ink_inside_r230(&m);
+ // The alert is a notice's, not the pet's: a pack without a working scene leaves the pill to ui_habitat.c.
+ ht_character_face_t idle = custom_face(false, 3);
+ assert(!ht_focus_alert_shown(&idle, "", &at));
+ pet_store_release_frame();
+ pack_unload();
+}
+static void focus_custom_ink_inside_r230(void)
+{
+ ht_character_t c = {0};
+ assert(ht_character_select(&c, HT_CHARACTER_FOCUS));
+ // Moves the working scene to the glass's upper right so the bubble at its corner would leave r 230 unclamped.
+ uint8_t b[4096];
+ memcpy(b, vec_buf, vec_len);
+ size_t dx = working_dx_at();
+ b[dx] = 165; b[dx + 1] = 0;
+ b[dx + 2] = (uint8_t)(-135 & 0xff); b[dx + 3] = (uint8_t)((-135 >> 8) & 0xff);
+ pack_load(b, vec_len);
+ const ht_pet_t *pet = pet_store_lookup("claude");
+ assert(pet && pet->working_scene->dx == 165 && pet->working_scene->dy == -135);
+ ht_character_face_t f = custom_face(true, 12);
+ ht_scene_t scene; ht_scene_clear(&scene, 0);
+ ht_character_face(&scene, &c, &f, 0xffff, "");
+ const ht_run_t *box = alert_box(&scene);
+ assert(box);
+ int sx = (HT_WIDTH - 8) / 2 + 165, sy = HT_HEIGHT / 2 - 4 + 4 - 135;
+ assert(box->x + 34 < sx + 8 - 8 || box->y + 22 > sy + 8); // pulled inward
+ ink_inside_r230(&scene);
+ ht_rect_t at;
+ assert(ht_focus_alert_shown(&f, "", &at) && at.x == box->x && at.y == box->y);
+ // ... and the same for the other three quarters of the glass.
+ for (int q = 0; q < 4; q++) {
+ int sdx = (q & 1) ? -165 : 165, sdy = (q & 2) ? 135 : -135;
+ pet_store_release_frame();
+ pack_unload();
+ memcpy(b, vec_buf, vec_len);
+ b[dx] = (uint8_t)(sdx & 0xff); b[dx + 1] = (uint8_t)((sdx >> 8) & 0xff);
+ b[dx + 2] = (uint8_t)(sdy & 0xff); b[dx + 3] = (uint8_t)((sdy >> 8) & 0xff);
+ pack_load(b, vec_len);
+ ht_scene_clear(&scene, 0);
+ ht_character_face(&scene, &c, &f, 0xffff, "");
+ assert(alert_box(&scene));
+ ink_inside_r230(&scene);
+ }
+ pet_store_release_frame();
+ pack_unload();
+}
+// Draw, drop the pack under the drawn scene, draw again, release: under the address sanitizer (the --custom-only
+// build) a pointer used after the free is an error.
+static void focus_swap_mid_scene(void)
+{
+ ht_character_t c = {0};
+ assert(ht_character_select(&c, HT_CHARACTER_FOCUS));
+ pack_load(vec_buf, vec_len);
+ ht_character_face_t f = custom_face(true, 2);
+ ht_scene_t first; ht_scene_clear(&first, 0);
+ ht_character_face(&first, &c, &f, 0xffff, "");
+ assert(alert_box(&first));
+ ht_raster(&first, (ht_rect_t){0, 0, HT_WIDTH, HT_HEIGHT}, full);
+ pet_store_drop(VEC_ID); // the cable task: the pack is replaced under the frame
+ pet_store_map(NULL, NULL, NULL, 0);
+ assert(pet_store_lookup("claude")); // staged only: this frame's snapshot is unchanged
+ ht_raster(&first, (ht_rect_t){0, 0, HT_WIDTH, HT_HEIGHT}, scratch); // the scene still reads the pack
+ assert(!memcmp(full, scratch, sizeof full));
+ pet_store_release_frame(); // the next take: the pack is freed, the mapping is gone
+ ht_scene_t second; ht_scene_clear(&second, 0);
+ ht_character_face(&second, &c, &f, 0xffff, ""); // now the built-in claude
+ assert(!pet_store_lookup("claude"));
+ assert(first.count == second.count); // the same runs either way
+ ht_damage_t d; ht_damage(&first, &second, &d); // compares the frames by pointer, never reads them
+ ht_raster(&second, (ht_rect_t){0, 0, HT_WIDTH, HT_HEIGHT}, full);
+ pet_store_release_frame();
+ ht_raster(&second, (ht_rect_t){0, 0, HT_WIDTH, HT_HEIGHT}, full); // the built-in scene needs no pack
+}
+static void custom_pet(void)
+{
+ focus_custom_pet_resting();
+ focus_custom_pet_working_alert();
+ focus_custom_ink_inside_r230();
+ focus_swap_mid_scene();
+ puts("Custom pet: resting, code-drawn working alert, r 230 clamp and a swap mid-scene PASS");
+}
+
+int main(int argc, char **argv)
{
+ if (argc < 2) { fprintf(stderr, "usage: test_character <pet_min.hpet> [--custom-only]\n"); return 2; }
+ FILE *fp = fopen(argv[1], "rb");
+ assert(fp);
+ vec_len = fread(vec_buf, 1, sizeof vec_buf, fp);
+ fclose(fp);
+ assert(vec_len > 22 && vec_len < sizeof vec_buf);
+ if (argc > 2 && !strcmp(argv[2], "--custom-only")) { custom_pet(); return 0; }
assert(!strcmp(ht_character_name(HT_CHARACTER_TIM), "Tim"));
assert(!strcmp(ht_character_name(HT_CHARACTER_TUX), "Tux"));
clocks(); portraits(); delivery_and_caption(); recap_budget(); focus_face();
- footer_layout(); inbox_layout();
+ footer_layout(); inbox_layout(); custom_pet();
printf("Characters: both adapters, eight moods, five sizes, pause/mic/wrap/swap and %u exact incremental redraws PASS\n", redraws);
}
diff --git a/devices/harness-device/firmware/test/test_character_preferences.py b/devices/harness-device/firmware/test/test_character_preferences.py
index 666ece77c..d97e42aff 100644
--- a/devices/harness-device/firmware/test/test_character_preferences.py
+++ b/devices/harness-device/firmware/test/test_character_preferences.py
@@ -117,10 +117,10 @@ with tempfile.TemporaryDirectory(prefix='harness-character-pref-') as directory:
out = Path(directory)
(out / 'test.c').write_text(code)
sources = ['character.c', 'illustrated.c', 'character_motion.c', 'character_layout.c', 'tux.c', 'focus.c', 'lvgl_fonts.c', 'lvgl_icons.c', 'focus_marks.c', 'focus_faces.c', 'pets.c',
- 'octopus.c', 'octopus_font.c', 'ascii_clip.c', 'terminal.c', 'fonts.c']
+ 'octopus.c', 'octopus_font.c', 'ascii_clip.c', 'terminal.c', 'fonts.c', '../../pet_store.c']
for flags in ([], ['-DDEVICE_DEFAULT_CHARACTER_TUX=1']):
subprocess.run(['cc', '-std=c11', '-D_POSIX_C_SOURCE=200809L', '-Wall', '-Wextra', '-Werror', '-O1', '-g',
'-fsanitize=' + os.environ.get('SANITIZERS', 'undefined,bounds'), *flags,
- '-I', str(native), str(out / 'test.c'), *(str(native / f) for f in sources),
+ '-I', str(native), '-I', str(native.parent.parent), str(out / 'test.c'), *(str(native / f) for f in sources),
'-o', str(out / 'test')], check=True)
subprocess.run([str(out / 'test')], check=True)
diff --git a/devices/harness-device/firmware/test/test_companions.py b/devices/harness-device/firmware/test/test_companions.py
index a598cc719..03bdcf5aa 100644
--- a/devices/harness-device/firmware/test/test_companions.py
+++ b/devices/harness-device/firmware/test/test_companions.py
@@ -20,9 +20,9 @@ _binary_companion_art_pack_end:
''')
sources = ['character.c', 'illustrated.c', 'illustrated_cache.c', 'character_motion.c',
'character_layout.c', 'octopus.c', 'octopus_font.c', 'ascii_clip.c', 'tux.c',
- 'focus.c', 'lvgl_fonts.c', 'lvgl_icons.c', 'focus_marks.c', 'focus_faces.c', 'pets.c', 'terminal.c', 'fonts.c']
+ 'focus.c', 'lvgl_fonts.c', 'lvgl_icons.c', 'focus_marks.c', 'focus_faces.c', 'pets.c', 'terminal.c', 'fonts.c', '../../pet_store.c']
subprocess.run(['cc', '-std=c11', '-D_POSIX_C_SOURCE=200809L', '-Wall', '-Wextra', '-Werror', '-O1', '-g',
- '-fsanitize=' + os.environ.get('SANITIZERS', 'undefined,bounds'), '-I', str(NATIVE),
+ '-fsanitize=' + os.environ.get('SANITIZERS', 'undefined,bounds'), '-I', str(NATIVE), '-I', str(NATIVE.parent.parent),
str(HERE / 'test_companions.c'), *(str(NATIVE / name) for name in sources),
str(out / 'pack.S'), '-lz', '-o', str(out / 'test')], check=True)
captures = os.environ.get('COMPANION_CAPTURES')
diff --git a/devices/harness-device/firmware/test/test_device_settings.py b/devices/harness-device/firmware/test/test_device_settings.py
index 7a213359e..c19c1e801 100644
--- a/devices/harness-device/firmware/test/test_device_settings.py
+++ b/devices/harness-device/firmware/test/test_device_settings.py
@@ -244,9 +244,9 @@ with tempfile.TemporaryDirectory(prefix='harness-device-settings-') as directory
out = Path(directory)
(out / 'test.c').write_text(code)
sources = ['character.c', 'illustrated.c', 'character_motion.c', 'character_layout.c', 'tux.c', 'focus.c', 'lvgl_fonts.c', 'lvgl_icons.c', 'focus_marks.c', 'focus_faces.c', 'pets.c',
- 'octopus.c', 'octopus_font.c', 'ascii_clip.c', 'terminal.c', 'fonts.c']
+ 'octopus.c', 'octopus_font.c', 'ascii_clip.c', 'terminal.c', 'fonts.c', '../../pet_store.c']
subprocess.run(['cc', '-std=c11', '-D_POSIX_C_SOURCE=200809L', '-Wall', '-Wextra', '-Werror', '-O1', '-g',
'-fsanitize=' + os.environ.get('SANITIZERS', 'undefined,bounds'),
- '-I', str(native), str(out / 'test.c'), *(str(native / f) for f in sources),
+ '-I', str(native), '-I', str(native.parent.parent), str(out / 'test.c'), *(str(native / f) for f in sources),
'-o', str(out / 'test')], check=True)
subprocess.run([str(out / 'test')], check=True)
diff --git a/devices/harness-device/firmware/test/test_pet_store.c b/devices/harness-device/firmware/test/test_pet_store.c
new file mode 100644
index 000000000..68364577e
--- /dev/null
+++ b/devices/harness-device/firmware/test/test_pet_store.c
@@ -0,0 +1,404 @@
+// The firmware pet store on a laptop: the 241-byte vector from the daemon's pack encoder, then packs broken
+// in every way a cable or a hostile daemon could break them. Run under the sanitizers by test/run.sh.
+//
+// test_pet_store <path to test/vectors/pet_min.hpet>
+//
+// pet_store.c is included, not linked, so the allocations can be counted: "freed after the frame" is an
+// assertion here, not a hope that a leak checker is available on this host.
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+static long g_live;
+static void *t_alloc(size_t n, size_t s) { void *p = calloc(n, s); if (p) g_live++; return p; }
+static void t_free(void *p) { if (p) { g_live--; free(p); } }
+#define PET_MALLOC(n) t_alloc((n), 1)
+#define PET_CALLOC(n, s) t_alloc((n), (s))
+#define PET_FREE(p) t_free(p)
+#include "../main/pet_store.c"
+
+static int failures, checks;
+static void check(int cond, const char *what)
+{
+ checks++;
+ if (!cond) { printf(" FAIL %s\n", what); failures++; }
+}
+
+static uint8_t vec[4096];
+static size_t vec_len;
+
+static uint32_t get32(const uint8_t *p) { return (uint32_t)(p[0] | p[1] << 8 | p[2] << 16 | (uint32_t)p[3] << 24); }
+static void put32(uint8_t *p, uint32_t v) { for (int i = 0; i < 4; i++) p[i] = (uint8_t)(v >> (8 * i)); }
+static void put16(uint8_t *p, unsigned v) { p[0] = (uint8_t)v; p[1] = (uint8_t)(v >> 8); }
+
+// Make the header agree with the body again after a test edited it.
+static void reseal(uint8_t *b, size_t n)
+{
+ put32(b + 14, (uint32_t)n);
+ put32(b + 18, crc32_ieee(b + HEADER, n - HEADER));
+}
+
+static const char *ID = "0102030405060708";
+
+// Offer + slices (in 50-byte pieces) + finish.
+static int send_pack(const char *id, const uint8_t *b, size_t n, bool *offered)
+{
+ bool ok = pet_store_offer(id, (uint32_t)n, get32(b + 18));
+ if (offered) *offered = ok;
+ if (!ok) return -1;
+ for (size_t at = 0; at < n; at += 50) {
+ size_t k = n - at < 50 ? n - at : 50;
+ if (!pet_store_slice(b + at, k)) return -2;
+ }
+ return pet_store_finish();
+}
+
+// Offsets inside the vector, found by walking its layout.
+static size_t working_idx0, frame0_row_at;
+static void locate(void)
+{
+ size_t pos = HEADER;
+ pos += 1 + 2u * vec[pos];
+ pos += 4;
+ for (int l = 0; l < 3; l++) pos += 1 + 2u * vec[pos];
+ working_idx0 = pos + 7;
+ for (int s = 0; s < 4; s++) pos += 7 + 2u * vec[pos];
+ frame0_row_at = pos + 2 + 3;
+}
+
+static void reset_store(void)
+{
+ char ids[PET_STORE_MAX_PACKS][17];
+ size_t n = pet_store_held(ids, PET_STORE_MAX_PACKS);
+ for (size_t i = 0; i < n; i++) pet_store_drop(ids[i]);
+ pet_store_abort();
+ pet_store_map(NULL, NULL, NULL, 0);
+ pet_store_release_frame();
+}
+
+// Every cell of every frame through ht_cell_at: a bad row table would be an ASan error.
+static void touch_all(const ht_pet_t *pet, unsigned frames)
+{
+ for (unsigned f = 0; f < frames; f++)
+ for (int y = 0; y < pet->cells[f].rows; y++)
+ for (int x = 0; x < pet->cells[f].cols; x++) (void)ht_cell_at(&pet->cells[f], x, y);
+}
+
+static void parse_vector(void)
+{
+ uint8_t b[4096];
+ memcpy(b, vec, vec_len);
+ check(send_pack(ID, b, vec_len, NULL) == 0, "vector parses");
+ pet_store_map(ID, NULL, NULL, 0);
+ check(pet_store_lookup("claude") == NULL, "a mapped, published pack is staged until the next frame");
+ pet_store_release_frame();
+ const ht_pet_t *pet = pet_store_lookup("claude");
+ check(pet != NULL, "lookup(claude) after map all");
+ if (pet) {
+ check(pet->engine == NULL && pet->w == 8 && pet->h == 8, "small size 8x8");
+ check(pet->cells && pet->cells[0].cell == 2 && pet->cells[1].cell == 1, "frame cells 2 and 1");
+ check(pet->cells[0].cols == 8 && pet->cells[0].rows == 8, "frame 0 is 8x8");
+ check(pet->cells[0].palette[1] == 0x00f8 && pet->cells[0].palette[3] == 0x1f00, "palette in panel order");
+ touch_all(pet, 2);
+ // idle [0,1,0], done [0], asking [1]: all repeat to the lcm (3)
+ check(ht_pet_steps(pet) == 3, "steps = 3");
+ check(pet->loops[HT_PET_IDLE][1].frame == 1 && pet->loops[HT_PET_DONE][2].frame == 0 &&
+ pet->loops[HT_PET_ASKING][0].frame == 1, "loops");
+ check(pet->working_scene && pet->working_scene->steps == 2 && pet->working_scene->loop[0] == 1 &&
+ pet->working_scene->step_ms == 120, "working scene");
+ check(pet->listening_scene && pet->listening_scene->steps == 1 &&
+ pet->listening_scene->loop[4 * 1 + 0] == 0, "listening scene has five levels");
+ check(pet->sending_scene && pet->sending_scene->dx == -3 && pet->sending_scene->dy == 5 &&
+ pet->sending_scene->steps == 3, "sending scene dx dy");
+ check(pet->alert_scene == NULL, "no alert scene");
+ }
+ pet_store_release_frame();
+ char ids[4][17];
+ check(pet_store_held(ids, 4) == 1 && !strcmp(ids[0], ID), "held lists the id");
+ reset_store();
+ check(g_live == 0, "parse_vector leaves nothing allocated");
+}
+
+static void reject_bad_crc(void)
+{
+ uint8_t b[4096];
+ memcpy(b, vec, vec_len);
+ b[vec_len - 3] ^= 0x40; // the body changed, the header did not
+ check(send_pack(ID, b, vec_len, NULL) == PET_ERR_CRC, "flipped body byte -> CRC");
+ char ids[4][17];
+ check(pet_store_held(ids, 4) == 0, "nothing held after a bad CRC");
+ memcpy(b, vec, vec_len);
+ check(pet_store_offer(ID, (uint32_t)vec_len, get32(b + 18) ^ 1), "offer with a wrong crc");
+ pet_store_slice(b, vec_len);
+ check(pet_store_finish() == PET_ERR_CRC, "offer crc != pack crc -> CRC");
+ reset_store();
+ check(g_live == 0, "reject_bad_crc leaves nothing allocated");
+}
+
+static void reject_version_2(void)
+{
+ uint8_t b[4096];
+ memcpy(b, vec, vec_len);
+ b[4] = 2;
+ check(send_pack(ID, b, vec_len, NULL) == PET_ERR_VERSION, "version 2 -> VERSION");
+ reset_store();
+}
+
+static void pet_store_abort_keeps_current(void)
+{
+ uint8_t b[4096];
+ memcpy(b, vec, vec_len);
+ check(send_pack(ID, b, vec_len, NULL) == 0, "A held");
+ pet_store_map(ID, NULL, NULL, 0);
+ pet_store_release_frame();
+ const ht_pet_t *a = pet_store_lookup("claude");
+ pet_store_release_frame();
+ b[13] = 9; // another id: 0102030405060709
+ reseal(b, vec_len);
+ check(pet_store_offer("0102030405060709", (uint32_t)vec_len, get32(b + 18)), "B offered");
+ pet_store_slice(b, 100);
+ pet_store_abort();
+ check(pet_store_lookup("claude") == a, "lookup still A after abort");
+ pet_store_release_frame();
+ check(pet_store_slice(b + 100, 10) == false, "a slice after abort is refused");
+ char ids[4][17];
+ check(pet_store_held(ids, 4) == 1, "only A held");
+ reset_store();
+ check(g_live == 0, "abort leaves nothing allocated");
+}
+
+static void drop_aborts_partial(void)
+{
+ uint8_t b[4096];
+ memcpy(b, vec, vec_len);
+ check(send_pack(ID, b, vec_len, NULL) == 0, "A held");
+ pet_store_map(ID, NULL, NULL, 0);
+ pet_store_release_frame();
+ const ht_pet_t *a = pet_store_lookup("claude");
+ const int before = g_live;
+ b[13] = 9; // another id: 0102030405060709
+ reseal(b, vec_len);
+ check(pet_store_offer("0102030405060709", (uint32_t)vec_len, get32(b + 18)), "B offered");
+ check(pet_store_slice(b, vec_len / 2), "half of B sliced");
+ check(g_live > before, "partial buffer allocated");
+ pet_store_drop("0102030405060709");
+ check(g_live == before, "drop of the in-flight id frees the partial buffer");
+ check(pet_store_slice(b + vec_len / 2, 10) == false, "a slice after the drop is refused");
+ check(pet_store_lookup("claude") == a, "lookup unaffected");
+ check(pet_store_offer("0102030405060709", (uint32_t)vec_len, get32(b + 18)), "a new offer works");
+ check(pet_store_slice(b, vec_len) && pet_store_finish() == 0, "and completes");
+ reset_store();
+ check(g_live == 0, "drop_aborts_partial leaves nothing allocated");
+}
+
+static void engine_before_all(void)
+{
+ uint8_t b[4096];
+ memcpy(b, vec, vec_len);
+ send_pack(ID, b, vec_len, NULL);
+ b[13] = 9;
+ reseal(b, vec_len);
+ send_pack("0102030405060709", b, vec_len, NULL);
+ const char *engines[] = {"codex"}, *ids[] = {"0102030405060709"};
+ pet_store_map(ID, engines, ids, 1);
+ pet_store_release_frame();
+ const ht_pet_t *all = pet_store_lookup("claude"), *codex = pet_store_lookup("codex");
+ check(all && codex && all != codex, "codex has its own pack, claude falls to all");
+ check(pet_store_lookup("muse") == all, "unmapped engine -> all");
+ const char *gone[] = {"0aaaaaaaaaaaaaaa"};
+ pet_store_map(NULL, engines, gone, 1);
+ pet_store_release_frame();
+ check(pet_store_lookup("codex") == NULL, "mapped to an id not held, no all -> NULL");
+ check(pet_store_lookup("claude") == NULL, "no all -> NULL");
+ pet_store_release_frame();
+ reset_store();
+ check(g_live == 0, "engine_before_all leaves nothing allocated");
+}
+
+static void fifth_offer_busy(void)
+{
+ uint8_t b[4096];
+ memcpy(b, vec, vec_len);
+ for (int i = 0; i < 4; i++) {
+ char id[17];
+ b[13] = (uint8_t)(0x10 + i);
+ reseal(b, vec_len);
+ snprintf(id, sizeof id, "01020304050607%02x", 0x10 + i);
+ check(send_pack(id, b, vec_len, NULL) == 0, "pack held");
+ }
+ bool offered = true;
+ b[13] = 0x20;
+ reseal(b, vec_len);
+ send_pack("0102030405060720", b, vec_len, &offered);
+ check(!offered, "fifth offer refused");
+ // the same id again is a replacement, not a fifth pack
+ b[13] = 0x10;
+ reseal(b, vec_len);
+ check(send_pack("0102030405060710", b, vec_len, &offered) == 0 && offered, "re-offer of a held id");
+ char ids[8][17];
+ check(pet_store_held(ids, 8) == 4, "still four held");
+ pet_store_drop("0102030405060711");
+ b[13] = 0x20;
+ reseal(b, vec_len);
+ check(send_pack("0102030405060720", b, vec_len, &offered) == 0 && offered, "offer fits after a drop");
+ reset_store();
+ check(g_live == 0, "fifth_offer_busy leaves nothing allocated");
+}
+
+static void drop_frees_after_release(void)
+{
+ uint8_t b[4096];
+ memcpy(b, vec, vec_len);
+ send_pack(ID, b, vec_len, NULL);
+ pet_store_map(ID, NULL, NULL, 0);
+ pet_store_release_frame();
+ const ht_pet_t *pet = pet_store_lookup("claude");
+ long live = g_live;
+ pet_store_drop(ID);
+ check(g_live == live, "a pack the frame may still draw is not freed by drop");
+ touch_all(pet, 2); // still readable: ASan would say otherwise
+ pet_store_release_frame();
+ check(g_live == 0, "freed once the frame is released");
+ check(pet_store_lookup("claude") == NULL, "dropped pack is gone");
+ // replaced while referenced
+ send_pack(ID, b, vec_len, NULL);
+ pet_store_map(ID, NULL, NULL, 0);
+ pet_store_release_frame();
+ pet = pet_store_lookup("claude");
+ send_pack(ID, b, vec_len, NULL);
+ touch_all(pet, 2);
+ pet_store_release_frame();
+ reset_store();
+ check(g_live == 0, "replaced pack freed after release");
+}
+
+// H1: the cable task re-maps between two lookups of one frame; both must agree, and the change lands at the release.
+static void snapshot_per_frame(void)
+{
+ uint8_t b[4096];
+ memcpy(b, vec, vec_len);
+ check(send_pack(ID, b, vec_len, NULL) == 0, "pack held");
+ pet_store_map(ID, NULL, NULL, 0);
+ pet_store_release_frame();
+ const ht_pet_t *first = pet_store_lookup("claude");
+ check(first != NULL, "mapped after the release");
+ pet_store_map(NULL, NULL, NULL, 0); // the cable task clears "all" mid-frame
+ check(pet_store_lookup("claude") == first, "a second lookup in the frame agrees");
+ pet_store_drop(ID);
+ check(pet_store_lookup("codex") == first, "so does a lookup after a drop");
+ touch_all(first, 2);
+ pet_store_release_frame();
+ check(pet_store_lookup("claude") == NULL, "after the release the new mapping applies");
+ pet_store_release_frame();
+ reset_store();
+ check(g_live == 0, "snapshot_per_frame leaves nothing allocated");
+}
+
+// L1: frames and scenes outside the 480 px glass are refused.
+static void geometry_limits(void)
+{
+ uint8_t b[4096];
+ memcpy(b, vec, vec_len);
+ b[frame0_row_at - 1] = 241; // 8 cols * 241 > 480
+ reseal(b, vec_len);
+ check(send_pack(ID, b, vec_len, NULL) == PET_ERR_SHAPE, "frame wider than 480 px -> SHAPE");
+ memcpy(b, vec, vec_len);
+ b[frame0_row_at - 2] = 241;
+ reseal(b, vec_len);
+ check(send_pack(ID, b, vec_len, NULL) == PET_ERR_SHAPE, "frame taller than 480 px -> SHAPE");
+ memcpy(b, vec, vec_len);
+ put16(b + working_idx0 - 4, 481);
+ reseal(b, vec_len);
+ check(send_pack(ID, b, vec_len, NULL) == PET_ERR_SHAPE, "scene dx 481 -> SHAPE");
+ memcpy(b, vec, vec_len);
+ put16(b + working_idx0 - 2, (unsigned)(uint16_t)-481);
+ reseal(b, vec_len);
+ check(send_pack(ID, b, vec_len, NULL) == PET_ERR_SHAPE, "scene dy -481 -> SHAPE");
+ memcpy(b, vec, vec_len);
+ put16(b + working_idx0 - 4, (unsigned)(uint16_t)-480);
+ reseal(b, vec_len);
+ check(send_pack(ID, b, vec_len, NULL) == 0, "scene dx -480 is allowed");
+ reset_store();
+ check(g_live == 0, "geometry_limits leaves nothing allocated");
+}
+
+// A pack the daemon would never send: each must be refused as a shape error, with the sanitizers silent.
+static void bounds(void)
+{
+ uint8_t b[4096];
+ memcpy(b, vec, vec_len);
+ // (a) the cable cut it: header and body disagree
+ check(send_pack(ID, b, vec_len - 5, NULL) == PET_ERR_SHAPE, "truncated, header says more -> SHAPE");
+ // (b) truncated and sealed again: the parser must stop at the end of the data
+ for (size_t cut = HEADER + 1; cut < vec_len; cut++) {
+ memcpy(b, vec, vec_len);
+ reseal(b, cut);
+ int r = send_pack(ID, b, cut, NULL);
+ if (r != PET_ERR_SHAPE) { check(0, "every truncation is a SHAPE error"); printf(" cut=%zu got %d\n", cut, r); break; }
+ }
+ // (c) a frame index past the frame count
+ memcpy(b, vec, vec_len);
+ put16(b + working_idx0, 2);
+ reseal(b, vec_len);
+ check(send_pack(ID, b, vec_len, NULL) == PET_ERR_SHAPE, "frame index == count -> SHAPE");
+ put16(b + working_idx0, 300);
+ reseal(b, vec_len);
+ check(send_pack(ID, b, vec_len, NULL) == PET_ERR_SHAPE, "frame index 300 -> SHAPE");
+ // (d) a row offset past the end
+ memcpy(b, vec, vec_len);
+ put16(b + frame0_row_at, 0xff00);
+ reseal(b, vec_len);
+ check(send_pack(ID, b, vec_len, NULL) == PET_ERR_SHAPE, "row_at past the end -> SHAPE");
+ // (e) a run longer than the row; a row that never advances
+ memcpy(b, vec, vec_len);
+ b[frame0_row_at + 2 * 8 + 1] = 200; // first row's first run: far past cols
+ reseal(b, vec_len);
+ check(send_pack(ID, b, vec_len, NULL) == PET_ERR_SHAPE, "run wider than the row -> SHAPE");
+ memcpy(b, vec, vec_len);
+ b[frame0_row_at + 2 * 8] = 0;
+ b[frame0_row_at + 2 * 8 + 1] = 0;
+ reseal(b, vec_len);
+ check(send_pack(ID, b, vec_len, NULL) == PET_ERR_SHAPE, "empty run (no progress) -> SHAPE");
+ // (f) zero cell size, magic, id mismatch, an offer whose size is not the pack's
+ memcpy(b, vec, vec_len);
+ b[frame0_row_at - 1] = 0;
+ reseal(b, vec_len);
+ check(send_pack(ID, b, vec_len, NULL) == PET_ERR_SHAPE, "cell 0 -> SHAPE");
+ memcpy(b, vec, vec_len);
+ b[0] = 'X';
+ check(send_pack(ID, b, vec_len, NULL) == PET_ERR_SHAPE, "bad magic -> SHAPE");
+ memcpy(b, vec, vec_len);
+ check(send_pack("0102030405060799", b, vec_len, NULL) == PET_ERR_SHAPE, "offer id != pack id -> SHAPE");
+ check(!pet_store_offer("xyz", 100, 0) && !pet_store_offer(ID, 0, 0) && !pet_store_offer(ID, 10u << 20, 0),
+ "bad id or size refused at the offer");
+ check(pet_store_offer(ID, (uint32_t)vec_len, 0) && !pet_store_slice(vec, vec_len + 1), "more bytes than offered refused");
+ check(pet_store_finish() == PET_ERR_SHAPE, "finish with nothing received -> SHAPE");
+ char ids[4][17];
+ check(pet_store_held(ids, 4) == 0, "nothing held after all of that");
+ reset_store();
+ check(g_live == 0, "bounds leaves nothing allocated");
+}
+
+int main(int argc, char **argv)
+{
+ if (argc < 2) { printf("usage: test_pet_store pet_min.hpet\n"); return 2; }
+ FILE *f = fopen(argv[1], "rb");
+ if (!f) { printf("cannot open %s\n", argv[1]); return 2; }
+ vec_len = fread(vec, 1, sizeof vec, f);
+ fclose(f);
+ check(vec_len == 241, "vector is 241 bytes");
+ locate();
+ parse_vector();
+ reject_bad_crc();
+ reject_version_2();
+ pet_store_abort_keeps_current();
+ drop_aborts_partial();
+ engine_before_all();
+ fifth_offer_busy();
+ drop_frees_after_release();
+ bounds();
+ snapshot_per_frame();
+ geometry_limits();
+ printf("test_pet_store: %d checks, %d failures\n", checks, failures);
+ return failures ? 1 : 0;
+}
diff --git a/devices/harness-device/firmware/test/test_touch_ui.py b/devices/harness-device/firmware/test/test_touch_ui.py
index 4587dd4c3..37d58e108 100644
--- a/devices/harness-device/firmware/test/test_touch_ui.py
+++ b/devices/harness-device/firmware/test/test_touch_ui.py
@@ -2773,7 +2773,7 @@ with tempfile.TemporaryDirectory(prefix='harness-touch-ui-') as d:
subprocess.run(['cc','-std=c11', '-D_POSIX_C_SOURCE=200809L','-Wall','-Wextra','-Werror','-O1','-g',
'-fsanitize='+os.environ.get('SANITIZERS','undefined,bounds'),
*extra_includes, '-I',str(native),str(out/'touch_ui.c'), *extra_sources, str(native/'gestures.c'),
- str(native/'form.c'),str(native/'visit.c'),str(native/'draft.c'), str(native/'scroll.c'),str(native/'selection.c'),str(native/'carry.c'),str(native/'tim.c'),str(native/'character_motion.c'),str(native/'character_layout.c'),str(native/'character.c'),str(native/'illustrated.c'),str(native/'tux.c'),str(native/'focus.c'),str(native/'lvgl_fonts.c'),str(native/'lvgl_icons.c'),str(native/'focus_marks.c'),str(native/'focus_faces.c'),str(native/'pets.c'),str(native/'terminal.c'),
+ str(native/'form.c'),str(native/'visit.c'),str(native/'draft.c'), str(native/'scroll.c'),str(native/'selection.c'),str(native/'carry.c'),str(native/'tim.c'),str(native/'character_motion.c'),str(native/'character_layout.c'),str(native/'character.c'),str(native/'illustrated.c'),str(native/'tux.c'),str(native/'focus.c'),str(native/'lvgl_fonts.c'),str(native/'lvgl_icons.c'),str(native/'focus_marks.c'),str(native/'focus_faces.c'),str(native/'pets.c'),str(native/'../../pet_store.c'),str(native/'terminal.c'),
str(native/'fonts.c'),str(native/'octopus.c'),str(native/'ascii_clip.c'),str(native/'octopus_font.c'),str(native/'workspace.c'),str(native/'command_face.c'),'-o',str(out/'touch_ui'),'-lm'],check=True)
args=[str(out/'touch_ui')]
if os.environ.get('HABITAT_PREVIEW_DIR'):
diff --git a/devices/harness-device/firmware/test/vectors/pet_min.hpet b/devices/harness-device/firmware/test/vectors/pet_min.hpet
new file mode 100644
index 000000000..cf94eb97b
Binary files /dev/null and b/devices/harness-device/firmware/test/vectors/pet_min.hpet differ
diff --git a/docs/superpowers/plans/2026-10-08-custom-pet.md b/docs/superpowers/plans/2026-10-08-custom-pet.md
new file mode 100644
index 000000000..7e71ddbe2
--- /dev/null
+++ b/docs/superpowers/plans/2026-10-08-custom-pet.md
@@ -0,0 +1,272 @@
+# Custom Pets on the Dial Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** A user picks a petdex-layout sprite sheet in the desktop app's Device settings, for all agents or per engine, and the round dial's Focus face shows it, kept in PSRAM and re-sent by the daemon on every attach.
+
+**Architecture:** The daemon's devices subsystem (`cli/src/cable/pets/`) decodes and validates the PNG, converts it into an `HPET` pack in the firmware's own cell-sprite format, stores packs and the mapping under `~/.harness/devices/pets/`, and syncs them over the cable with JSON `pet.*` messages plus binary `CableType.Pet` slices (the firmware-update credit scheme, reused). The firmware's `pet_store` parses packs into PSRAM and builds `ht_pet_t`s that `focus.c` looks up before the built-in pets. The app adds a Pet section that talks to the local daemon with four requests.
+
+**Tech Stack:** TypeScript (Node 22, vitest, zod), `pngjs` (new dependency), C11 (ESP-IDF 5.5.0 for the dial, host tests with cc + sanitizers), Flutter/Dart (desktop).
+
+**Spec:** `docs/superpowers/specs/2026-10-08-custom-pet-design.md`
+
+## Global Constraints
+
+- Code, comments and docs in English. Match each file's comment density and naming.
+- Never commit, push or stage anything unless the owner asks in that turn; each task ends with its tests green and its files listed, not committed. Never `git add -A`.
+- Dial host features live in the devices subsystem (`cli/src/cable/`, `cli/src/services/devices.ts`, `cli/src/lib/harnessDevices.ts`); the core (`cli/src/core/`) changes only by adding request names to `DEVICES_REQUESTS`.
+- Sheet layout: 8 columns x 9 rows of 192 x 208 cells (1536 x 1872), or half size 768 x 936 (96 x 104 cells). Rows: idle, running-right, running-left, waving, jumping, failed, waiting, running, review. A row ends at its first fully transparent cell.
+- Required rows: idle, running. Substitutes: listening ← review, sending ← waving, asking ← waiting, each falling back to idle.
+- Alpha >= 128 is opaque, < 128 transparent. Soft-edge warning when more than 2 % of a frame's opaque edge pixels had partial alpha.
+- Palette: one per pet, <= 255 colours + index 0 transparent, RGB565 in panel order (byte-swapped, as `ht_cell_frame_t` palettes are).
+- Limits: source file <= 8 MB; pack <= 1 MB (1 048 576 B); at most 4 packs mapped (all + 3 engines); default `step_ms` 120.
+- Resolution order: the engine's own pet → the "all" pet → the built-in pet.
+- The source PNG is read by the daemon from a local path (the app and daemon share the machine; pet requests are local-only, never relayed, never in the E2EE request lists).
+- Focus rule: the face emits the same runs in the same order every frame; a custom pet uses the built-in pet's run slots.
+- Firmware host tests run with `bash devices/harness-device/firmware/test/run.sh` outside the IDF environment.
+
+## Review Focus
+
+- A PNG that is a valid sheet but palette-heavy (a photo-like render, thousands of colours): conversion must still finish under 2 s and stay <= 255 colours — Task 2 adds `quantize: 40k-colour sheet → 255 colours in under 2 s`.
+- The cable pulled in the middle of a pack: the dial must keep showing the old pet and the daemon must resend on the next attach — Task 5 adds `sync: a cut transfer is resent after reattach`, Task 6 adds `pet_store_abort_keeps_current`.
+- The same PNG applied to two engines: one pack, two mapping entries, sent once — Task 3 adds `store: same source twice → one pack`.
+- Changing pets while a turn is on screen: no use-after-free — Task 7 adds `focus_swap_mid_scene` under the address sanitizer.
+- An older daemon or older firmware on one side: nothing breaks, the app locks the section — Task 5 (`hello without pets: no pet traffic`) and Task 8 (`locked when the dial lacks pets`).
+
+---
+
+### Task 1: Read and validate a sprite sheet
+
+**Files:**
+- Create: `cli/src/cable/pets/sheet.ts`
+- Test: `cli/src/cable/pets/sheet.spec.ts`
+- Modify: `cli/package.json` (add `"pngjs": "^7.0.0"` and `"@types/pngjs"` dev)
+
+**Interfaces:**
+- Produces:
+ - `type PetRow = 'idle' | 'runningRight' | 'runningLeft' | 'waving' | 'jumping' | 'failed' | 'waiting' | 'running' | 'review'`
+ - `interface RgbaFrame { width: number; height: number; data: Uint8Array /* RGBA */ }`
+ - `interface PetSheet { cellW: number; cellH: number; rows: Record<PetRow, RgbaFrame[]> }`
+ - `class PetSheetError extends Error { code: 'NOT_PNG' | 'BAD_SIZE' | 'NO_IDLE' | 'NO_RUNNING' | 'TOO_BIG' }`
+ - `readPetSheet(path: string): Promise<PetSheet>` (throws `PetSheetError`)
+ - `parsePetSheet(png: Buffer): PetSheet`
+
+- [ ] **Step 1: Write the failing tests** — build sheets in memory with `PNG` from pngjs:
+ - `accepts 1536x1872 and 768x936` → `cellW/cellH` 192/208 and 96/104.
+ - `rejects 1000x1000` → `code === 'BAD_SIZE'`, message `The sheet must be 1536 × 1872 (8 × 9 cells of 192 × 208)`.
+ - `row ends at the first transparent cell` → idle with 3 drawn cells gives `rows.idle.length === 3`.
+ - `empty running row` → `code === 'NO_RUNNING'`, message `The running row is empty`.
+ - `file over 8 MB` → `code === 'TOO_BIG'` (stat before reading).
+ - `not a PNG` → `code === 'NOT_PNG'`.
+- [ ] **Step 2: Run** `cd cli && npx vitest run src/cable/pets/sheet.spec.ts` — Expected: FAIL (module missing).
+- [ ] **Step 3: Implement `sheet.ts`** with `PNG.sync.read`; row order from Global Constraints.
+- [ ] **Step 4: Run the same command** — Expected: PASS.
+
+### Task 2: Convert frames — pixel-art factor, alpha, palette, small pet
+
+**Files:**
+- Create: `cli/src/cable/pets/convert.ts`
+- Test: `cli/src/cable/pets/convert.spec.ts`
+
+**Interfaces:**
+- Consumes: `PetSheet`, `RgbaFrame` (Task 1).
+- Produces:
+ - `interface IndexedFrame { cols: number; rows: number; cell: number; cells: Uint8Array /* cols*rows, 0 = transparent */ }`
+ - `interface PetScene { frames: number[] /* indices into ConvertedPet.frames */; stepMs: number; dx: number; dy: number }`
+ - `interface ConvertedPet { palette: number[] /* RGB565 panel order, palette[0] unused */; frames: IndexedFrame[]; small: { w: number; h: number; loops: Record<'idle' | 'done' | 'asking', number[]> }; working: PetScene; listening: PetScene; sending: PetScene; failed: PetScene; warnings: string[] }`
+ - `pixelArtFactor(frames: RgbaFrame[]): number` — the largest k dividing the cell size with every k x k block uniform in every frame; 1 otherwise.
+ - `convertPet(sheet: PetSheet): ConvertedPet`
+
+The small pet (`small`) replaces the spec's separate `rest` / `rest_small` scenes: its frames are the idle and waiting rows scaled so the 2x art fits 150 x 112 (aspect kept; nearest-neighbour when the pixel-art factor is even, box filter otherwise, then mapped onto the same palette), and `small.w/h` is half that 2x size — what `ht_pet_t.cells` expects. Loops: idle → idle frames with one waving pass every fourth cycle, done → idle, asking → waiting (idle if empty). `failed` is packed but the dial has no failed state yet; it is not drawn in this version.
+
+- [ ] **Step 1: Write the failing tests:**
+ - `pixelArtFactor: 4x-upscaled art → 4`, `photo-like → 1`, `factor 3 is refused when the cell is not divisible`.
+ - `alpha 127 is transparent, 128 opaque`.
+ - `palette has <= 256 entries and index 0 is unused`.
+ - `quantize: 40k-colour sheet → 255 colours in under 2 s` (generate a gradient sheet; `performance.now()`).
+ - `soft-edge warning above 2 %` → `warnings` contains `Soft edges will look jagged on the dial`.
+ - `review row empty → listening uses idle's frame indices` (same numbers, no new frames).
+ - `small pet 2x art fits 150 x 112`.
+ - `RGB565 panel order`: pure red `#ff0000` → `0x00f8` (byte-swapped 0xf800).
+- [ ] **Step 2: Run** `cd cli && npx vitest run src/cable/pets/convert.spec.ts` — Expected: FAIL.
+- [ ] **Step 3: Implement `convert.ts`.** Palette by median cut over all opaque pixels of every used frame (all rows' frames at their cell resolution after dividing by the factor), then nearest-colour mapping. Frames are de-duplicated by content so substituted scenes share indices.
+- [ ] **Step 4: Run** — Expected: PASS.
+
+### Task 3: The HPET pack and the pet store
+
+**Files:**
+- Create: `cli/src/cable/pets/pack.ts`, `cli/src/cable/pets/store.ts`
+- Create: `devices/harness-device/firmware/test/vectors/pet_min.hpet` (written by the test below with `UPDATE_VECTORS=1`, checked otherwise)
+- Test: `cli/src/cable/pets/pack.spec.ts`, `cli/src/cable/pets/store.spec.ts`
+
+**Interfaces:**
+- Consumes: `ConvertedPet` (Task 2), `readPetSheet` (Task 1).
+- Produces:
+ - `PACK_VERSION = 1`, `PACK_MAX_BYTES = 1_048_576`
+ - `encodePack(pet: ConvertedPet, id: Uint8Array /* 8 bytes */): Buffer` (throws `PetSheetError('TOO_BIG')` with message `This pet is {x.x} MB; the limit is 1 MB`)
+ - `decodePack(buf: Buffer): ConvertedPet & { id: string /* hex */ }` (throws on bad magic, version, length or CRC)
+ - `type PetTarget = 'all' | string /* engine name */`
+ - `interface PetMapping { all: string | null; engines: Record<string, string> }`
+ - `class PetStore { constructor(dir: string); prepare(sourcePath: string): Promise<{ id: string; pet: ConvertedPet; bytes: number }>; apply(target: PetTarget, id: string): Promise<PetMapping>; reset(target: PetTarget): Promise<PetMapping>; mapping(): PetMapping; pack(id: string): Promise<Buffer>; mappedIds(): string[] }`
+
+Layout (little-endian), exactly:
+
+```
+"HPET" · version u8 · flags u8 · id u8[8] (sha256(source)[0..8]) · length u32 (whole pack) · crc32 u32 (of every byte after this field)
+palette: count u8 (entries incl. index 0) · count × u16
+small: w u16 · h u16 · loops idle/done/asking: each n u8 · n × u16 frame index
+scenes: working, listening, sending, failed: each n u8 · step_ms u16 · dx i16 · dy i16 · n × u16 frame index
+frames: count u16 · per frame: cols u8 · rows u8 · cell u8 · row_at u16[rows] · packed rows
+```
+
+Packed rows use the firmware's encoding (`terminal.h` `ht_cell_frame_t`): per row, pairs of (transparent cells to skip u8, opaque cells u8) each followed by those cells' indices, until `cols` are covered; `row_at[r]` is the byte offset of row r from the frame's first row byte.
+
+`PetStore` keeps `<dir>/<id>.hpet`, `<dir>/<id>.png` (the source, for re-conversion when `PACK_VERSION` changes) and `<dir>/pets.json` (`PetMapping`). `apply` refuses with `PetSheetError('TOO_BIG', 'Up to 4 pets at once: reset one first')` when the mapping would reference a fifth distinct pack. Unreferenced packs are deleted on `apply`/`reset`.
+
+- [ ] **Step 1: Write the failing tests:**
+ - `round-trip: decodePack(encodePack(p)) deep-equals p`.
+ - `bad CRC / bad magic / version 2 → throws`.
+ - `over 1 MB → TOO_BIG with the MB message`.
+ - `vector: encodePack(fixture) equals test/vectors/pet_min.hpet` (fixture = a 2-frame 8x8 pet built in code; `UPDATE_VECTORS=1` rewrites the file).
+ - `store: same source twice → one pack` (apply to claude and codex, `mappedIds()` has one id, one `.hpet` on disk).
+ - `store: fifth distinct pack is refused`.
+ - `store: reset removes the mapping and deletes the unreferenced pack`.
+ - `store: mapping survives a new PetStore on the same dir`.
+- [ ] **Step 2: Run** `cd cli && npx vitest run src/cable/pets/pack.spec.ts src/cable/pets/store.spec.ts` — Expected: FAIL.
+- [ ] **Step 3: Implement `pack.ts` and `store.ts`.** CRC-32 is IEEE (`zlib.crc32` in Node 22).
+- [ ] **Step 4: Run** with `UPDATE_VECTORS=1` once, then without — Expected: PASS both times.
+
+### Task 4: Requests the app calls
+
+**Files:**
+- Modify: `cli/src/lib/harnessDevices.ts` (add pet requests), `cli/src/services/devices.ts:315-325` (answer them), `cli/src/core/api.ts:833` (`DEVICES_REQUESTS` gains the four names)
+- Test: `cli/src/lib/harnessDevices.spec.ts` (create if absent)
+
+**Interfaces:**
+- Consumes: `PetStore` (Task 3).
+- Produces (request → reply):
+ - `pet_preview {path}` → `{ ok: true, id, bytes, colours, warnings, frames: { small: string[], working: string[], listening: string[], sending: string[] } /* PNG data URLs rendered from the decoded pack */ }` or `{ error: code, message }`
+ - `pet_apply {target, id}` → `{ ok: true, mapping }` or `{ error, message }`
+ - `pet_reset {target}` → `{ ok: true, mapping }`
+ - `pet_status {}` → `{ mapping, dial: { supported: boolean, held: string[], sending: { id: string, percent: number } | null } }`
+ - `HarnessDevicesService` gains `pets(): PetStore` and `petDial(): { supported: boolean; held: string[]; sending: { id: string; percent: number } | null }` and `petsChanged(): void` (Task 5 implements the last two).
+- These four are answered for the owner on a local connection only: `asker.owner` as today, and they are NOT added to `cli/src/lib/e2ee/core.ts`'s lists.
+
+- [ ] **Step 1: Write the failing tests:** `pet_preview on a valid sheet returns frames per scene as data URLs`; `pet_preview on a bad sheet returns the sheet error's code and message`; `pet_apply with an unknown id → { error: 'UNKNOWN_PET' }`; `pet_apply calls petsChanged`; `non-owner → OWNER_REQUIRED`.
+- [ ] **Step 2: Run** `cd cli && npx vitest run src/lib/harnessDevices.spec.ts` — Expected: FAIL.
+- [ ] **Step 3: Implement.** Preview frames are rendered from `decodePack(encodePack(...))` so the preview is exactly what the dial gets; the store lives at `join(harnessHome, 'devices', 'pets')` created by `services/devices.ts`.
+- [ ] **Step 4: Run** — Expected: PASS. Also `cd cli && npx vitest run src/services/devices.spec.ts` stays green.
+
+### Task 5: Cable sync
+
+**Files:**
+- Modify: `cli/src/cable/cableFrame.ts` (`CableType.Pet = 0x05`), `cli/src/cable/cableSession.ts` (hello fields, `pet.*` handling, sync), `cli/src/cable/cableHost.ts` / `cableFleet.ts` (fan `petsChanged` out to sessions; expose `petDial()`)
+- Create: `cli/src/cable/pets/sync.ts`
+- Test: `cli/src/cable/pets/sync.spec.ts`, additions in `cli/src/cable/cableSession.spec.ts`
+- Modify: `devices/harness-device/firmware/scripts/gen_cable_vectors.py` and `test/vectors/` only if the vectors enumerate frame types
+
+**Interfaces:**
+- Consumes: `PetStore` (Task 3), `FirmwareTransfer` (existing, `cableSession.ts`; constructed with the pack bytes, a label, a slice writer that sends `encodeCableFrame(CableType.Pet, slice)`, and the log).
+- Produces:
+ - `planPetSync(mapping: PetMapping, held: string[]): { map: PetMapping; send: string[]; drop: string[] }` — send = mapped ids not held, drop = held ids not mapped.
+ - Messages daemon → dial: `pet.map {all, engines}`, `pet.offer {id, size, crc}`, `pet.drop {id}`. Dial → daemon: `pet.accept {id}`, `pet.progress {id, written}`, `pet.done {id}`, `pet.error {id, reason: 'memory' | 'crc' | 'version' | 'busy'}`.
+ - `hello` from the dial: `pets: 1` and `petIds: string[]`.
+
+Sequencing: after `hello` with `pets: 1`, the session runs `planPetSync(store.mapping(), petIds)`: `pet.map` first, then each `pet.drop`, then one transfer at a time (`pet.offer` → `pet.accept` → slices on credit from `pet.progress` → `pet.done`). Never interleave a pet transfer with a firmware transfer: pets wait while `this.transfer` (firmware) exists. The store is read by the devices process itself, so a daemon restart cannot lose the mapping (the app_swarms start-up race of 2026-10-08 does not apply).
+
+- [ ] **Step 1: Write the failing tests:**
+ - `planPetSync: held nothing → send all mapped, map first`.
+ - `planPetSync: held stale → drop it`.
+ - `session: hello without pets: no pet traffic`.
+ - `session: hello with pets:1 and petIds [] → pet.map then pet.offer for each mapped pack`.
+ - `session: a cut transfer is resent after reattach` (close the fake link mid-slices; new hello with `petIds: []` → offered again).
+ - `session: pet.error memory → reported in petDial and not retried this session`.
+ - `session: firmware offer pending → pet transfer waits`.
+- [ ] **Step 2: Run** `cd cli && npx vitest run src/cable/pets/sync.spec.ts src/cable/cableSession.spec.ts` — Expected: FAIL on the new cases.
+- [ ] **Step 3: Implement.**
+- [ ] **Step 4: Run** the same, then `cd cli && npx vitest run src/cable` — Expected: PASS.
+
+### Task 6: Firmware pet store
+
+**Files:**
+- Create: `devices/harness-device/firmware/main/pet_store.c`, `main/pet_store.h`
+- Modify: `main/cable_frame.h` (`CABLE_TYPE_PET 0x05`), `main/cable_client.c` (hello `pets`/`petIds`; `pet.map`, `pet.offer`, `pet.drop` handlers; `CABLE_TYPE_PET` slices in `on_frame`), `main/CMakeLists.txt` (add `pet_store.c`)
+- Test: `devices/harness-device/firmware/test/test_pet_store.c`, wired into `test/run.sh`
+
+**Interfaces:**
+- Consumes: `test/vectors/pet_min.hpet` (Task 3), `ht_pet_t` / `ht_cell_frame_t` (`pets.h`, `terminal.h`).
+- Produces:
+ - `bool pet_store_offer(const char *id, uint32_t size, uint32_t crc)` — allocates `size` bytes (PSRAM on the device via `heap_caps_malloc(..., MALLOC_CAP_SPIRAM)`, `malloc` on the host); false → caller sends `pet.error memory`.
+ - `bool pet_store_slice(const uint8_t *data, size_t len)`; `int pet_store_finish(void)` → 0 ok, else `PET_ERR_CRC` / `PET_ERR_VERSION` / `PET_ERR_SHAPE`.
+ - `void pet_store_abort(void)` — discards a partial pack (called when the link drops).
+ - `void pet_store_map(const char *all, const char *const *engines, const char *const *ids, size_t n)`; `void pet_store_drop(const char *id)`.
+ - `const ht_pet_t *pet_store_lookup(const char *engine)` — engine's → all → NULL.
+ - `size_t pet_store_held(char ids[][17], size_t max)` — for `petIds` in hello.
+ - `void pet_store_release_frame(void)` — called by the UI after each frame; a dropped pack is freed only after the frame that last referenced it.
+- At most 4 packs held; a fifth `offer` while 4 are held answers `busy`.
+
+The `ht_pet_t` built per pack: `engine` = NULL (not used for lookup), `w/h` = `small.w/h`, `cells` = the small frames, `loops[HT_PET_IDLE|HT_PET_DONE|HT_PET_ASKING]` from the pack, `loops[HT_PET_WORKING]` = idle (unused while the working scene plays), `working_scene`/`listening_scene`/`sending_scene` from the scenes, `alert_scene` = NULL, `steps` = the longest loop (<= `HT_PET_STEPS`, longer loops are cut).
+
+- [ ] **Step 1: Write the failing tests** in `test_pet_store.c`: `parse_vector` (offer+slices+finish of `pet_min.hpet` → 0, lookup("claude") after mapping all → non-NULL with the vector's w/h and frame cells); `reject_bad_crc`; `reject_version_2`; `pet_store_abort_keeps_current` (map A, start B, abort → lookup still A); `engine_before_all`; `fifth_offer_busy`; `drop_frees_after_release` (drop while referenced, run `pet_store_release_frame`, then ASan sees no leak/use-after-free).
+- [ ] **Step 2: Run** `bash devices/harness-device/firmware/test/run.sh` — Expected: FAIL at `test_pet_store` (missing source).
+- [ ] **Step 3: Implement `pet_store.c` and the `cable_client.c` handlers.** `on_frame` routes `CABLE_TYPE_PET` like `CABLE_TYPE_FW` (straight to `pet_store_slice`, then `pet.progress` credit as `fw` does). On link loss call `pet_store_abort()`.
+- [ ] **Step 4: Run** `run.sh` — Expected: all PASS. Then `source ~/esp/esp-idf/export.sh && idf.py build` in `devices/harness-device/firmware` — Expected: builds.
+
+### Task 7: Focus draws the custom pet
+
+**Files:**
+- Modify: `devices/harness-device/firmware/main/ui/habitat/focus.c:166-173` (`pet_for`), the working-alert drawing (the count bubble), and the frame end (`pet_store_release_frame`)
+- Test: `devices/harness-device/firmware/test/test_character.c` (add cases; add `pet_store.c` to its `cc` line in `run.sh`)
+
+**Interfaces:**
+- Consumes: `pet_store_lookup`, `pet_store_release_frame` (Task 6).
+- Produces: `pet_for(f)` returns `pet_store_lookup(f->engine)` when non-NULL, else the built-in lookup as today.
+
+The working alert for a pet without `alert_scene`: a blue `0x006fff` rounded bubble 68 x 44 (the built-in `ALERT_W, ALERT_H`) whose centre is the working scene's top-right corner inset 8 px, the count in `ht_lv_inter_med_26` (`9+` in `ht_lv_inter_20`), occupying the same run slots (n == 1 bubble, n == 2 count) the built-in alert uses, so the run count is unchanged.
+
+- [ ] **Step 1: Write the failing tests:** `focus_custom_pet_resting` (map the vector as "all"; resting face draws a cell sprite from the custom frames; run count equals the built-in pet's); `focus_custom_pet_working_alert` (bubble fill `0x006fff` at the top-right, count drawn); `focus_custom_ink_inside_r230`; `focus_swap_mid_scene` (draw, drop the pack, draw again, release; ASan clean); `focus_builtin_unchanged` (no custom mapping → existing golden rasters equal).
+- [ ] **Step 2: Run** `bash devices/harness-device/firmware/test/run.sh` — Expected: FAIL on the new cases.
+- [ ] **Step 3: Implement.**
+- [ ] **Step 4: Run** — Expected: PASS, existing tests unchanged.
+
+### Task 8: The Pet section in the app
+
+**Files:**
+- Create: `desktop/lib/devices/pet_settings.dart`
+- Modify: `desktop/lib/devices/device_settings.dart` (insert the section after "Faces"), `desktop/lib/devices/devices_controller.dart` (pet calls and state), `desktop/lib/state/app_state.dart` (requests, local connection only, next to `setHostDeviceSettings`)
+- Test: `desktop/test/pet_settings_test.dart`
+
+**Interfaces:**
+- Consumes: the four requests (Task 4).
+- Produces:
+ - `AppState`: `Future<Map<String, dynamic>> petRequest(String machineId, String type, Map<String, Object?> payload)` (6 s timeout; 30 s for `pet_preview`).
+ - `DevicesController`: `Future<PetPreview?> previewPet(String key, String path)`, `Future<String?> applyPet(String key, String target, String id)` (null = ok, else the message), `Future<void> resetPet(String key, String target)`, `PetStatus? petStatus(String key)`, refreshed every 1 s while `sending` is non-null.
+ - `PetSettingsSection({required HarnessDevice device, required DevicesController controller})`.
+
+Copy (exact): section title `Pet`; toggle `Apply to all` / `Per engine`; row value `Default`; buttons `Choose file…`, `Reset to default`, `Apply`, `Cancel`; progress `Sending to dial… {n} %`, done `On dial ✓`; links `Download template`, `Browse pets on petdex.dev` (`https://petdex.dev`); locked `Update the dial’s firmware to use custom pets`. Per-engine rows list the engines of the user's agents (from the agents the app already knows), Claude, Codex, Muse first. The preview shows tabs `Rest`, `Working`, `Listening`, `Asking` cycling the data-URL frames at the pack's `step_ms`, plus `{bytes} · {colours} colours` and each warning. "Choose file…" uses the app's existing file picker; dropping a `.png` on the row does the same.
+
+- [ ] **Step 1: Write the failing widget tests:** `locked when the dial lacks pets`; `all mode shows one row, per-engine one per engine`; `choosing a file shows the preview tabs and size`; `a sheet error is shown in the row`; `apply shows progress then On dial ✓`; `reset returns the row to Default`.
+- [ ] **Step 2: Run** `cd desktop && flutter test test/pet_settings_test.dart` — Expected: FAIL.
+- [ ] **Step 3: Implement.**
+- [ ] **Step 4: Run** the test, then `cd desktop && flutter analyze lib/devices` — Expected: PASS, no issues.
+
+### Task 9: The template
+
+**Files:**
+- Create: `devices/harness-device/firmware/scripts/gen_pet_template.py` (writes `desktop/assets/pets/pet-template.zip` containing `pet-blank.png`, `pet-guide.png`, `README.md`; `--check` mode compares)
+- Modify: `desktop/pubspec.yaml` (asset), `test/run.sh` (`gen_pet_template.py --check` beside the other generators), `desktop/lib/devices/pet_settings.dart` (`Download template` saves the asset via the save dialog)
+
+`pet-blank.png`: 1536 x 1872, fully transparent. `pet-guide.png`: same size, 1 px grid at every cell edge, each row's name at its left cell's top-left in 14 px text, rows idle and running marked `required`. `README.md`: the row table and fallbacks from Global Constraints, the alpha and palette limits, the 1 MB limit, a link to petdex.dev.
+
+- [ ] **Step 1:** Run `python3 devices/harness-device/firmware/scripts/gen_pet_template.py --check` — Expected: FAIL (script missing).
+- [ ] **Step 2: Implement** with `/usr/local/bin/python3` + PIL; deterministic output (fixed zip timestamps).
+- [ ] **Step 3:** Run it without `--check`, then with `--check` — Expected: PASS. Feed `pet-guide.png` with the grid removed into `pet_preview` via the Task 4 test helper — Expected: `BAD_SIZE` never; `NO_IDLE` (blank sheet) as the documented error.
+
+### Task 10: On the device
+
+**Files:** none new; this is the acceptance run.
+
+- [ ] **Step 1:** Flash the dial following the owner's procedure (quit Harness, set the flasher flag, `harness stop`, verify the MAC with `esptool read_mac`, `idf.py -p /dev/cu.usbmodem21301 flash`, remove the flag, `harness start`, `open -a Harness`).
+- [ ] **Step 2:** Run the dev daemon and app from this branch; apply a petdex sheet to all and a template-drawn sheet to Claude. Expected: both appear within 3 s; dial log shows `pet.done`; `raster_max_us` in the `habitat: alive` line stays within 10 % of the built-in pet's.
+- [ ] **Step 3:** Unplug and replug, then `harness stop && harness start`. Expected: the pets come back by themselves; daemon log shows `pet.offer` only for packs the dial lacked.
+- [ ] **Step 4:** Report times, sizes and `raster_max_us` to the owner.
diff --git a/docs/superpowers/specs/2026-10-08-custom-pet-design.md b/docs/superpowers/specs/2026-10-08-custom-pet-design.md
new file mode 100644
index 000000000..26b5374f1
--- /dev/null
+++ b/docs/superpowers/specs/2026-10-08-custom-pet-design.md
@@ -0,0 +1,174 @@
+# Custom pets on the dial
+
+Status: design, approved in conversation 2026-10-08 · owner: device team
+
+## Goal
+
+A user can give the round dial's Focus face a pet of their own: a sprite sheet downloaded (petdex.dev or anywhere
+else), chosen in the desktop app's Device settings and sent to the dial over the cable. One pet for
+every agent. (The protocol and store also hold a pet per engine; the app offers one pet for all agents for now.)
+
+Success: the user picks a PNG in Settings, sees it animate in a preview for each state, presses Apply, and within
+a few seconds the dial shows that pet moving with the agent's state; it comes back by itself after the cable is
+replugged or the daemon restarts.
+
+## Decisions
+
+| Question | Decision |
+|---|---|
+| How far does "custom" go | The user brings their own sprite sheet (option C); no recolouring or accessories of the built-in pets |
+| Where the pet lives on the dial | PSRAM, sent again by the daemon on every attach (option A). No partition change, no USB reflash of dials in the field; a dial booting without its daemon shows the built-in pet until the daemon sends the custom one |
+| Scope | The app offers one pet for all agents. Per-engine pets stay in the protocol and store for later (resolution: engine's own → all → built-in); applying a pet in the app resets any engine-specific entry so it cannot override the all pet |
+| How a pet is made | Import only, with a one-line hint pointing at petdex.dev; no template. No in-app editor, no AI generation in this version |
+| Where the sheet is converted | The daemon's devices subsystem (`cli/src/services/devices`), not the core, not the app, not the firmware |
+
+Out of scope: per-engine pets in the app, Harness Pro, Wi-Fi devices, per-agent pets, an in-app editor, AI generation, pets persisted in
+flash.
+
+## Input: the sprite sheet
+
+The petdex / Codex pet-pack layout, which the Codex pet in `assets/pets/codex` already follows: a PNG of 8 columns
+x 9 rows of 192 x 208 cells (1536 x 1872), RGBA. The half size (768 x 936, cells 96 x 104) is accepted too. Rows,
+top to bottom: idle, running-right, running-left, waving, jumping, failed, waiting, running, review. A row may be
+shorter than 8: the first fully transparent cell ends it.
+
+The daemon only reads PNG. What petdex.dev hands out is a package, a folder (often a .zip) with `pet.json`
+(`id`, `displayName`, `spritesheetPath`) and `spritesheet.webp` of the same 1536 x 1872 layout. The desktop app
+resolves it (`desktop/lib/devices/pet_source.dart`): it takes a folder, a zip, a `pet.json`, a `.webp` or a `.png`,
+keeps the sheet path inside the folder, bounds a zip (64 entries, 32 MB), checks a WebP's size from its header
+(1536 x 1872 or 768 x 936, at most 8 MB) before decoding it to a PNG, and sends the daemon that PNG with the pet's
+`displayName` (`pet_preview` takes an optional `name`, control characters stripped, at most 40 characters).
+
+Loose sheets: any other PNG or JPEG (<= 8 MB, <= 4096 px) is normalised in the app (`loose_sheet.dart`): a real
+alpha channel is kept, otherwise a flood fill from the border clears a checkered (baked "transparent" squares) or
+solid background; frames are found from the gaps between them (<= 9 rows x 8 frames) and laid onto a 1536 x 1872
+sheet, loose row i on sheet row i, one scale for the whole sheet, bottom-aligned per row. The app guesses a
+mapping (Rest = row 1, Working = the row that moves most, Asking = the last row) and sends it as `rows`.
+
+The default mapping, which `pet_preview {rows: {rest, working, listening, sending, asking}}` (each a row name from
+`PET_ROWS`, camelCase) overrides; the pack id hashes the mapping when it differs from the default, and `<id>.json`
+keeps it for re-conversion:
+
+| Dial state | Row | If the row is empty |
+|---|---|---|
+| Rest (resting face, recap, small question) | idle, a waving pass now and then | required |
+| Working | running (row 8) | required |
+| Listening (voice) | review | idle |
+| Sending | waving | idle |
+| Asking (a question waits) | waiting | idle |
+| Failed turn | failed | idle |
+
+running-left, running-right and jumping are not used.
+
+## Conversion (daemon, devices subsystem)
+
+1. Validate: PNG decodes, size is one of the two accepted, the rows chosen for Rest and Working are non-empty, file <= 8 MB.
+2. Pixel-art factor: the largest k (dividing the cell size) for which every k x k block of every used frame is one
+ colour. Cell size = k, so a 4x-upscaled 48 x 52 drawing becomes 48 x 52 cells. Otherwise k = 1.
+3. Alpha: >= 128 opaque, < 128 transparent (cell sprites have no partial alpha). If more than 2 % of a frame's
+ opaque-edge pixels had partial alpha, warn ("soft edges will look jagged").
+4. Palette: one per pet, median cut over every used frame, <= 255 colours + transparent (index 0), RGB565 in panel
+ order as `ht_cell_frame_t` expects.
+5. The small resting pet: the idle frames at half size, made here so the firmware never scales.
+6. Pack rows with the firmware's transparent-run encoding (`row_at`, skip/opaque pairs).
+7. Pack <= 1 MB, or refuse.
+
+Errors are returned to the app with a message it shows as is, e.g. "The sheet must be 1536 x 1872 (8 x 9 cells of
+192 x 208)", "The row chosen for Working is empty", "This pet is 1.4 MB; the limit is 1 MB".
+
+## The pet pack (little-endian)
+
+```
+header "HPET" · version u8 (1) · flags u8 · id u8[8] (first 8 bytes of sha256 of the source PNG) · length u32 · crc32 u32
+palette count u8 (entries incl. index 0) · count x u16 RGB565 panel order
+small w u16 · h u16 · loops idle/done/asking: each n u8 · n x u16 frame index
+scenes working, listening, sending, failed: each n u8 · step_ms u16 · dx i16 · dy i16 · n x u16 frame index
+frames count u16 · per frame: cols u8 · rows u8 · cell u8 · row_at u16[rows] · packed rows
+```
+
+The small pet (rest, recap, small question) is one frame pool with per-state loops, which is what `ht_pet_t.cells`
+and `loops` already are; it replaces separate rest and rest_small scenes. Frames are de-duplicated, so a substituted
+scene points at idle's frames. `step_ms` defaults to 120. `dx`, `dy` place the scene from Focus's home position
+(0, 0 = centred as the built-in pets are). `failed` is packed but not drawn in version 1: the dial has no failed
+state yet.
+
+The app hands the daemon the PNG's local path, not its bytes: pet requests are local-only, and the 8 MB source would
+not fit the local socket's message limit.
+
+## Storage and mapping (daemon)
+
+- Packs: `~/.harness/devices/pets/<id>.pack`, plus the source PNG beside it for re-conversion when the format version
+ changes.
+- `~/.harness/devices/pets/pets.json`: `{ "all": "<id>" | null, "engines": { "claude": "<id>", ... } }`.
+- At most 4 packs referenced at once (all + 3 engines) so the dial holds <= 4 MB of pets in its ~5 MB free PSRAM.
+ An apply that would exceed it is refused with a message naming the limit.
+
+## Protocol (cable)
+
+- `hello` from a supporting dial carries `pets: 1` and `petIds: [...]`, the packs it holds (empty after a reboot).
+- `pet.map {all, engines}`: which pack stands for what. Sent after attach and on every change.
+- `pet.begin {id, length, crc}` → dial allocates in PSRAM or answers `pet.error {id, reason: "memory"}`.
+- `pet.chunk {id, offset, data}` → ack per chunk. Reuse fwPush's chunking if it fits; otherwise ~4 KB chunks.
+- `pet.end {id}` → dial checks length and CRC, parses, answers `pet.ok {id}` or `pet.error {id, reason}`.
+- `pet.drop {id}` → dial frees a pack no longer mapped.
+- The daemon sends only packs the dial lacks. A transfer cut halfway is discarded by the dial; the daemon sends it
+ again on the next attach.
+- Older firmware ignores `pet.*`; the app reads the absent capability and locks the Pet section.
+- Sequencing: the pet map and packs are sent from the devices' own state after `hello`, never only from a window's
+ frame, so a daemon restart cannot lose them (see the app_swarms start-up race found 2026-10-08).
+
+## Firmware (round dial)
+
+- `pet_store.c`: receives packs into PSRAM, validates CRC and version, builds an `ht_pet_t` per pack whose scenes
+ point at `ht_cell_frame_t` frames in PSRAM.
+- Lookup in `focus.c`: engine's custom pet → "all" pet → built-in pet by engine name.
+- Drawing reuses the cell-sprite path. The Focus rule holds: the same runs in the same order every frame; a custom
+ pet occupies the built-in pet's run slots.
+- The working alert: a custom pet has no drawn alert scene, so the count bubble (blue `0x006fff`, the count in
+ `ht_lv_inter_med_26`) is drawn in code at the pet's top-right.
+- Swapping a pet: the new one takes effect on the next frame from step 0; the old pack is freed only once no frame
+ references it.
+- Capability `pets: 1` in `hello`.
+
+## Desktop app
+
+A "Pet" section in Device settings (`desktop/lib/devices/device_settings.dart`):
+
+- One row, "All agents": the pet's thumbnail and name ("Default" when none), "Choose file…" (png, jpeg, webp, zip
+ or pet.json), "Choose folder…", "Reset to default"; a file, folder or zip can be dropped on the row too.
+- A row picker for every source: the sheet's non-empty rows (the daemon's `sheetRows` strips, labelled by petdex
+ name, or "Row N" for a loose sheet) and five pickers, Rest · Working · Listening · Sending · Asking. A change
+ re-requests `pet_preview` with `rows` (debounced, stale replies ignored); Apply uses the latest preview's id.
+- Apply sets the pet for 'all' and then resets every engine entry in the mapping, so a pet left from earlier
+ testing no longer overrides it. Reset clears 'all' and every engine entry.
+- After choosing: the daemon's preview (the converted frames, exactly what the dial will draw) with tabs Rest /
+ Working / Listening / Asking, the pack's size and colour count, warnings. Apply / Cancel.
+- Apply shows "Sending to dial… n %" then "On dial ✓". No dial attached: saved and sent on the next attach.
+- Under the row, a muted hint: "Find pets on petdex.dev, or use any PNG, JPEG or WebP sprite sheet."
+- The row itself: the pet's 44 px thumbnail, its name and its status (On dial ✓, Sending…, Waiting…), with
+ Choose folder… · Choose file… · Reset as same-size pills on the right.
+- Dial firmware without `pets: 1`: the section is locked with "Update the dial's firmware to use custom pets".
+
+Requests to the daemon (local WS, devices): `pet_preview`, `pet_apply`, `pet_reset`, `pet_status`.
+
+## Errors
+
+| Case | Behaviour |
+|---|---|
+| Conversion fails | The app shows the message in the row; nothing saved |
+| Transfer cut (cable pulled, timeout) | The dial discards the partial pack, keeps the current pet; resent on next attach |
+| Dial out of PSRAM | `pet.error memory`; the app says "The dial is out of memory for pets"; the dial keeps its current pet |
+| Pack corrupt / unknown version | The dial drops it and reports; the daemon re-converts from the kept PNG if the version is old |
+| Daemon restart | `pets.json` is on disk; the dial is re-synced on attach |
+
+## Testing
+
+- Daemon unit tests: pixel-art factor detection, palette <= 255, alpha threshold, row substitution, size limits and
+ messages, pack round-trip (written then parsed equals the frames), cable sync against a fake dial (only missing
+ packs sent, resend after a cut, map change, drop).
+- Firmware host tests (`test/run.sh`): parse a real daemon-made pack, reject corrupt / bad CRC / bad version,
+ lookup order, raster of a custom pet (constant run count, ink inside r 230), the code-drawn bell bubble, a swap
+ mid-frame without use-after-free.
+- App widget tests: the Pet section in both modes, preview, error display, locked state.
+- On device: a petdex pet and a loose JPEG sheet; transfer time, `raster_max_us`; replug and daemon restart bring
+ the pet back.