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.

Merge batch 11-05 i2440: #3199 #3131 (#3205)

0xken15f87df0416bf6
diff --git a/backend/src/superTabs/commands.ts b/backend/src/superTabs/commands.ts
index d43bc84c4..8c00085f2 100644
--- a/backend/src/superTabs/commands.ts
+++ b/backend/src/superTabs/commands.ts
@@ -1,4 +1,4 @@
-import { applyPushOrigin, failPushUnknown, failTeamWritten, hasStep, mainAccountMembers, markTeamWritten, mayName, requireNameable, requireTeamWrittenAccount, requireTeamWrittenMachine, TEAM_WRITTEN_REASON, TEAM_WRITTEN_STOP, teamWrittenTask } from './teamWritten.js'
+import { applyPushOrigin, failPushUnknown, failTeamWritten, hasStep, mainAccountMembers, markTeamWritten, mayName, requireTeamWrittenAccount, requireTeamWrittenMachine, TEAM_WRITTEN_REASON, TEAM_WRITTEN_STOP, teamWrittenTask } from './teamWritten.js'
import type { PushOrigin } from '../github/pushOrigin.js'
import { requireRepositoryReach, unknownPushReason, type RepositoryReach } from './repositoryReach.js'
import { admitByRoom, admitMachineStart, noRepositoryStart, failOwnAccountTeamEntry, ownAccountTeamEntry, defaultProfileId, storedProfileId, BUDDY_WINDOWS_REFUSAL, refusesWindowsBuddy, buddyHomeFolder, buddyProjectsOn, SWARM_BUDDY_CAPABILITY, cleanupOverdue, dropIdleBuddyMachines, machineLimitReached, MACHINE_LIMIT_MESSAGE, NOT_SWARM_MACHINE, downSince, expireRemoval, expireRemovals, failTeamWork, machineContribution, machineOffline, machineSlots, contributedEngines, ownedMachine, productManagerOn, projectFolder, projectsOnMachine, requireTeamWork, teamMachineFor, teamAccountPool, teamPoolsOf, teamStartRequest, teamWorkCheck, movedToTeamAccount, type ContributedMachine } from './machines.js'
@@ -608,6 +608,9 @@ export interface CommandContext {
/** What an agent's post that reached no agent tells its sender, in the result every CLI prints (Egret6's review of #2963):
* since #2963 an unnamed post outside a task's assignee reaches no one, and a sender that meant someone to act would not know. */
+/** Said in a post's result when it went out without agents it named that may not join Team-written work (teamWritten.ts mayName). */
+export const notReachedLine = (names: string[]): string => `Your post was delivered, but not to ${names.join(', ')}: a Harness Team agent wrote this task's code, so an agent in the main account may not join it. `
+ + 'Nothing is wrong with your post or with you. Ask the PM to hand the work on, or name an agent in a Team account.'
export const REACHED_NO_AGENT = 'This post reached no agent; people read it in the conversation. Name an agent with --to or @Name when it must act.'
/** Messages in a row between two agents after which their project's Lead is told, once (project instructions, phase 1:
@@ -3409,10 +3412,15 @@ function applyCommandOnce(original: SuperTabState, actor: Actor, input: Command,
const poster = actor.kind === 'agent' ? agent(state, actor.agentId) : null
const textNamed = poster && !command.agentOnly
? agentsNamedIn(state, group, command.text, names).filter(id => mayName(state, group, poster, agent(state, id))) : []
- const addressed = command.agentOnly || !poster ? command.recipientIds
+ const asked = command.agentOnly || !poster ? command.recipientIds
: [...new Set([...command.recipientIds, ...textNamed])].filter(id => id !== poster.id)
+ // Naming an agent asks it to act, and a re-test is asked this way: a post's default addressee is only told (audit H2). An
+ // agent that may not join Team-written work is left out of the post, which goes out without it, and the result names it:
+ // refusing the whole post read as being about the sender (Heron21, #3245).
+ const barred = poster && !command.agentOnly ? asked.filter(id => !mayName(state, group, poster, agent(state, id))) : []
+ const addressed = asked.filter(id => !barred.includes(id))
const assigned = activeWork(group) ? group.assignment!.agentId : null
- const toAssignee = actor.kind === 'agent' && !command.agentOnly && !addressed.length && assigned && assigned !== actor.agentId
+ const toAssignee = actor.kind === 'agent' && !command.agentOnly && !asked.length && assigned && assigned !== actor.agentId
&& group.agentIds.includes(assigned) ? assigned : null
// An agent with work in the project posts in its project chat without joining it (worksInProjectChat): an answer to its
// line reaches it there too.
@@ -3441,11 +3449,10 @@ function applyCommandOnce(original: SuperTabState, actor: Actor, input: Command,
const doneWith = actor.kind === 'person' && !isBuddyChat(group) && automatic && automatic === replyAgent && automatic !== answered
&& group.assignment?.agentId === automatic && group.assignment.status === 'done' && group.leadId && group.leadId !== automatic
&& group.agentIds.includes(group.leadId) ? group.leadId : null
- const recipients = [...new Set([...addressed, ...answeredAgent ? [answeredAgent] : [], ...(addressed.length ? [] : [below, automatic, doneWith].filter((id): id is string => !!id))])]
+ // An agent the post named and may not be named is no recipient by any route: not the assignee, nor the author it answers.
+ const recipients = [...new Set([...addressed, ...answeredAgent ? [answeredAgent] : [], ...(addressed.length ? [] : [below, automatic, doneWith].filter((id): id is string => !!id))])].filter(id => !barred.includes(id))
for (const id of recipients) {
const target = agent(state, id)
- // Naming an agent asks it to act, and a re-test is asked this way: a post's default addressee is only told (audit H2).
- if (poster && addressed.includes(id)) requireNameable(state, group, poster, target)
// In a Buddy chat a session hears its own thread alone, and the main Buddy none of it.
if (session && (session.inSession ? id !== session.to : !!target.buddySession)) fail('INVALID_RECIPIENT', 'Choose an agent in this conversation.', 400)
// An agent of this project that another agent names from outside the group joins it, so it can read and answer there
@@ -3468,6 +3475,7 @@ function applyCommandOnce(original: SuperTabState, actor: Actor, input: Command,
// After the person's message: nobody answers it, so its person is told why (Dee, review of #2447).
if (buddyDown) buddyDownLine(group, buddyDown)
if (poster && !command.agentOnly && !recipients.length) effects.result.reachedNoAgent = REACHED_NO_AGENT
+ if (barred.length) effects.result.notReached = notReachedLine(barred.map(id => agent(state, id).displayName ?? agent(state, id).name))
// A Personal Swarm project chat with no Lead: the message waits for the Lead its person's Desktop starts (task #2633).
// A Team Swarm's says Not sent, as before.
const unled = actor.kind === 'person' && !recipients.length && !isBuddyChat(group) && isPersonalSwarm(state) ? groupProject(state, group) : undefined
diff --git a/backend/src/superTabs/teamWritten.test.ts b/backend/src/superTabs/teamWritten.test.ts
index ba1efe848..ac6ee4d8e 100644
--- a/backend/src/superTabs/teamWritten.test.ts
+++ b/backend/src/superTabs/teamWritten.test.ts
@@ -75,11 +75,13 @@ describe('a task a Team agent worked on', () => {
expect(refusal(() => f.run({ type: 'work.assign', conversationId: task, agentId: main }))).toBe(TEAM_WRITTEN_WORK)
})
- it('refuses joining the main account\'s agent to it, by a person or by another agent\'s post', () => {
+ it('refuses adding the main account\'s agent to it, and another agent\'s post naming it does not add it', () => {
const f = swarm(), task = f.written(), main = f.member('main-reviewer', 'mac')
expect(refusal(() => f.run({ type: 'conversation.agent', conversationId: task, agentId: main, present: true, lead: false }))).toBe(TEAM_WRITTEN_WORK)
- expect(refusal(() => f.run({ type: 'message.send', conversationId: task, text: 'Please test this.', replyTo: null, recipientIds: [main] },
- { kind: 'agent', agentId: 'team-builder', machineOwnerId: 'owner' }))).toBe(TEAM_WRITTEN_WORK)
+ const sent = f.run({ type: 'message.send', conversationId: task, text: 'Please test this.', replyTo: null, recipientIds: [main] },
+ { kind: 'agent', agentId: 'team-builder', machineOwnerId: 'owner' })
+ expect(f.state.conversations.find(c => c.id === task)!.agentIds).not.toContain(main)
+ expect(sent.result.notReached).toContain('main-reviewer')
})
it('takes a Team agent as its Reviewer, and that does not mark a clean task', () => {
@@ -166,21 +168,84 @@ describe('a task a Team agent worked on', () => {
expect(effects.messages.find(m => m.text === TEAM_WRITTEN_STOP)?.recipients).toEqual([builder])
})
- it('refuses a post that names a main-account member of a marked task: the re-test the workflow asks for', () => {
+ it('delivers a post without a main-account member it names in a marked task, and says who was left out', () => {
const f = swarm(), task = f.group(), builder = f.member('main-builder', 'mac'), tester = f.member('main-tester', 'mac')
f.run({ type: 'work.assign', conversationId: task, agentId: builder })
- const step = f.group({ reviewOf: task, step: 'Test' })
- f.run({ type: 'work.assign', conversationId: step, agentId: tester })
+ f.run({ type: 'conversation.agent', conversationId: task, agentId: tester, present: true, lead: false })
f.state.conversations.find(c => c.id === task)!.teamWritten = true
const asBuilder: Actor = { kind: 'agent', agentId: builder, machineOwnerId: 'owner' }
const post = (conversationId: string, recipientIds: string[], actor: Actor) => f.run({ type: 'message.send', conversationId, text: 'Please test again.', replyTo: null, recipientIds }, actor)
- expect(refusal(() => post(step, [tester], asBuilder))).toBe(TEAM_WRITTEN_WORK)
- expect(refusal(() => post(task, [tester], asBuilder))).toBe(TEAM_WRITTEN_WORK)
+ const sent = post(task, [tester], asBuilder)
+ expect(sent.messages.find(m => m.text === 'Please test again.')!.recipients).not.toContain(tester)
+ // The result names the agent who was left out, and says the post itself went out.
+ expect(sent.result.notReached).toContain('main-tester')
+ expect(sent.result.notReached).toContain('post was delivered')
// A Team agent may still be named, and a person speaks to whom they choose.
const team = f.member('team-tester', 'mac-team')
f.run({ type: 'conversation.agent', conversationId: task, agentId: team, present: true, lead: false })
- expect(refusal(() => post(task, [team], asBuilder))).toBeNull()
- expect(refusal(() => post(task, [tester], owner))).toBeNull()
+ const toTeam = post(task, [team], asBuilder)
+ expect(toTeam.messages.find(m => m.text === 'Please test again.')!.recipients).toEqual([team])
+ expect(toTeam.result).not.toHaveProperty('notReached')
+ const byPerson = post(task, [tester], owner)
+ expect(byPerson.messages.find(m => m.text === 'Please test again.')!.recipients).toEqual([tester])
+ expect(byPerson.result).not.toHaveProperty('notReached')
+ })
+
+ // Heron21 (Team Reviewer of #3245) named the Integrator, a main-account agent outside the group: the whole post was refused with a
+ // reason about Team accounts that read as being about Heron21. The post goes out; only the recipient is left out, and by name.
+ it('a Team agent\'s post naming a main-account agent outside the group goes out without it, and the agent does not join', () => {
+ const f = swarm(), task = f.written(), integrator = f.member('main-integrator', 'mac'), team = f.member('team-reviewer', 'mac-team')
+ const step = f.group({ reviewOf: task, step: 'Review' })
+ f.run({ type: 'work.assign', conversationId: step, agentId: team })
+ const asTeam: Actor = { kind: 'agent', agentId: team, machineOwnerId: 'owner' }
+ const sent = f.run({ type: 'message.send', conversationId: step, text: 'Ready to merge: Yes.', replyTo: null, recipientIds: [integrator] }, asTeam)
+ expect(sent.messages.find(m => m.text === 'Ready to merge: Yes.')!.recipients).not.toContain(integrator)
+ expect(sent.result.notReached).toContain('main-integrator')
+ expect(f.state.conversations.find(c => c.id === step)!.agentIds).not.toContain(integrator)
+ expect(f.state.conversations.find(c => c.id === task)!.agentIds).not.toContain(integrator)
+ })
+
+ it('leaves out only the barred recipient when a post names a main-account agent and a Team agent', () => {
+ const f = swarm(), task = f.written(), integrator = f.member('main-integrator', 'mac'), team = f.member('team-reviewer', 'mac-team'), other = f.member('team-other', 'mac-team')
+ const step = f.group({ reviewOf: task, step: 'Review' })
+ f.run({ type: 'work.assign', conversationId: step, agentId: team })
+ f.run({ type: 'conversation.agent', conversationId: step, agentId: other, present: true, lead: false })
+ const sent = f.run({ type: 'message.send', conversationId: step, text: 'Verdict.', replyTo: null, recipientIds: [integrator, other] }, { kind: 'agent', agentId: team, machineOwnerId: 'owner' })
+ expect(sent.messages.find(m => m.text === 'Verdict.')!.recipients).toEqual([other])
+ expect(sent.result.notReached).toContain('main-integrator')
+ expect(sent.result.notReached).not.toContain('team-other')
+ })
+
+ // Security review of #3199: with the barred id gone, the post fell back to the task's assignee, or to the author it replies to,
+ // and reached the very agent it was said not to reach.
+ it('does not fall back to the barred agent: its assignee, or the author of the message it answers', () => {
+ const f = swarm(), task = f.group(), engineer = f.member('main-engineer', 'mac'), team = f.member('team-reviewer', 'mac-team')
+ f.run({ type: 'work.assign', conversationId: task, agentId: engineer })
+ f.run({ type: 'conversation.agent', conversationId: task, agentId: team, present: true, lead: false })
+ // Marked by GitHub's push record: the main-account Engineer is still assigned and in the group.
+ f.state.conversations.find(c => c.id === task)!.teamWritten = true
+ const asTeam: Actor = { kind: 'agent', agentId: team, machineOwnerId: 'owner' }
+ const sent = f.run({ type: 'message.send', conversationId: task, text: 'Please test again.', replyTo: null, recipientIds: [engineer] }, asTeam)
+ expect(sent.messages.find(m => m.text === 'Please test again.')!.recipients).toEqual([])
+ expect(sent.result.notReached).toContain('main-engineer')
+ const replied = f.run({ type: 'message.send', conversationId: task, text: 'And again.', replyTo: 'earlier', recipientIds: [engineer] }, asTeam,
+ { reply: { id: 'earlier', conversationId: task, author: { kind: 'agent', id: engineer, name: 'main-engineer' } } as never })
+ expect(replied.messages.find(m => m.text === 'And again.')!.recipients).toEqual([])
+ expect(replied.result.notReached).toContain('main-engineer')
+ })
+
+ it('does not change a post in a task no Team agent wrote: the main-account agent is named and joins as before', () => {
+ const f = swarm(), task = f.group(), builder = f.member('main-builder', 'mac'), integrator = f.member('main-integrator', 'mac')
+ f.run({ type: 'work.assign', conversationId: task, agentId: builder })
+ const sent = f.run({ type: 'message.send', conversationId: task, text: 'Merge it.', replyTo: null, recipientIds: [integrator] }, { kind: 'agent', agentId: builder, machineOwnerId: 'owner' })
+ expect(sent.messages.find(m => m.text === 'Merge it.')!.recipients).toEqual([integrator])
+ expect(sent.result).not.toHaveProperty('notReached')
+ })
+
+ it('a main-account agent\'s own post in a Team-written group is still refused: the rule about itself is unchanged', () => {
+ const f = swarm(), task = f.written(), main = f.member('main-reviewer', 'mac')
+ const own = () => f.run({ type: 'message.send', conversationId: task, text: 'Looks fine.', replyTo: null, recipientIds: [] }, { kind: 'agent', agentId: main, machineOwnerId: 'owner' })
+ expect(refusal(own)).toBe(TEAM_WRITTEN_WORK)
})
// #2963: @Name in the text names an agent too, but only one the sender may name; it never turns a post into a refusal.
diff --git a/backend/src/superTabs/teamWritten.ts b/backend/src/superTabs/teamWritten.ts
index 585a09b21..65bdc1f42 100644
--- a/backend/src/superTabs/teamWritten.ts
+++ b/backend/src/superTabs/teamWritten.ts
@@ -62,15 +62,10 @@ export const hasStep = (state: SuperTabState, group: Conversation, worker: Agent
state.conversations.some(c => c.reviewOf === group.id && (c.assignment?.agentId === worker.id || c.agentIds.includes(worker.id)))
/** Whether [sender] may name [named] in a post: not a main-account member of Team-written work, how a re-test or re-check is
- * asked for, unless [sender] coordinates. */
+ * asked for, unless [sender] coordinates. A post that names one it may not goes out without it (commands.ts message.send). */
export const mayName = (state: SuperTabState, group: Conversation, sender: Agent, named: Agent): boolean =>
coordinates(state, group, sender) || named.id === sender.id || !barredFromTeamWritten(state, group, named)
-/** Refuses an agent naming one it may not ([mayName]) with --to. */
-export function requireNameable(state: SuperTabState, group: Conversation, sender: Agent, named: Agent): void {
- if (!mayName(state, group, sender, named)) failTeamWritten()
-}
-
/** Everyone to tell when [group]'s task has just been marked, by the conversation that reaches them, each once: the main-account
* members of the task and of every step, finished steps included, as the workflow asks them again. Not the coordinator. */
export function mainAccountMembers(state: SuperTabState, group: Conversation, except?: string): Array<{ conversationId: string; agentIds: string[] }> {
diff --git a/cli/src/lib/swarmTools.spec.ts b/cli/src/lib/swarmTools.spec.ts
index de19cc1a1..9c19d4c7e 100644
--- a/cli/src/lib/swarmTools.spec.ts
+++ b/cli/src/lib/swarmTools.spec.ts
@@ -43,6 +43,7 @@ describe('SWARM_TOOLS_SKILL', () => {
expect(section).toContain('The coordinator gets a post only when it is named: your status (done, needs_human, blocked) is how it hears your work')
expect(section).not.toContain('reaches the project\'s coordinator')
expect(section).toContain('its result says when it reached no agent.')
+ expect(section).toContain('notReached')
expect(section).not.toContain('Nothing is dropped')
})
// Task #2901 (Ken, 2026-11-04): PMs took the route's top line against the project's Routing instructions.
diff --git a/cli/src/lib/swarmTools.ts b/cli/src/lib/swarmTools.ts
index 97cd35ec2..63cf48d18 100644
--- a/cli/src/lib/swarmTools.ts
+++ b/cli/src/lib/swarmTools.ts
@@ -38,6 +38,7 @@ Every command starts \`harness super-tab --tab TAB\` (your tab id is in your lau
- \`@Name\` in TEXT names an agent of this conversation the same way, when only one agent there goes by that name and no person does.
- A reply (\`--reply-to\`) also reaches the agent who wrote the message it answers.
- A post that names no one reaches no agent, except in a task or step, where it reaches the agent assigned there unless that is you. It stays readable in its conversation, and the people it tags are still told; its result says when it reached no agent.
+- In a task a Harness Team agent wrote, an agent of the main account may not join: a post naming it is still delivered, without it, and its result says notReached with that agent named. Nothing is wrong with your post; the PM hands that work on.
- The coordinator gets a post only when it is named: your status (done, needs_human, blocked) is how it hears your work, so never post it a result, a verdict, a Ready or an acknowledgement.
- In the project chat, an agent with a task or step in the project posts and reacts without joining it, and a person's answer to its line reaches it; \`--to\` there adds no agent, so name only the coordinator.
- A post stays inside your project. Private chats and Buddy chats keep their own members.
diff --git a/desktop/lib/state/app_state.dart b/desktop/lib/state/app_state.dart
index 77e57577f..c37bc54da 100644
--- a/desktop/lib/state/app_state.dart
+++ b/desktop/lib/state/app_state.dart
@@ -102,6 +102,8 @@ import '../core/local_key_value_store.dart';
import '../core/harness_file_store.dart';
import '../super_tabs/swarm_accounts.dart';
import '../super_tabs/attachment_upload.dart';
+import '../super_tabs/attachment_viewer.dart' show superTabForgetPictures;
+import '../super_tabs/image_cache.dart' show superTabImageCache;
import '../super_tabs/avatar_upload.dart';
import '../super_tabs/backend_transport.dart';
import '../super_tabs/client.dart';
@@ -8213,6 +8215,9 @@ class AppNotifier extends ChangeNotifier {
if (viewer != null) return;
final machineId = authStatus.loggedIn ? authStatus.machineId : null;
_provenMachineId = machineId;
+ // The chat's pictures are tied the same way (task #3178): a sign-out this
+ // app never saw, or another account on this computer, clears them here.
+ unawaited(superTabImageCache.claim(machineId));
_keptProfileId = null;
_profileConfirmed = false;
final kept = machineId == null ? null : await _profileCache.read(machineId);
@@ -8253,6 +8258,7 @@ class AppNotifier extends ChangeNotifier {
_keptProfileId = profile.id;
}
await _profileCache.write(machineId, profile);
+ unawaited(superTabImageCache.owned(machineId));
}
/// Saves the signed-in person's own account name (Profile, task #2654) and
@@ -8668,6 +8674,8 @@ class AppNotifier extends ChangeNotifier {
void _clearAccountWorkspace({bool notices = true}) {
if (notices) _clearDeviceNoticeState();
experimentalFeatures.bind(null);
+ // The chat's pictures are the account's (task #3178).
+ unawaited(superTabForgetPictures());
agentMessages.reset();
sharedTabs.reset();
_sharedPlaced = null;
diff --git a/desktop/lib/super_tabs/attachment_image.dart b/desktop/lib/super_tabs/attachment_image.dart
index b47632cfa..940cd1c07 100644
--- a/desktop/lib/super_tabs/attachment_image.dart
+++ b/desktop/lib/super_tabs/attachment_image.dart
@@ -1,4 +1,5 @@
import 'dart:async';
+import 'dart:math' as math;
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
@@ -10,6 +11,7 @@ import '../widgets/desktop_chrome.dart';
import 'attachment_upload.dart';
import 'attachment_viewer.dart';
import 'file_links.dart';
+import 'image_cache.dart';
import 'message_more_menu.dart';
import 'model.dart';
@@ -57,6 +59,30 @@ class _SuperTabInlineImageState extends State<SuperTabInlineImage> {
void initState() {
super.initState();
_start();
+ _awaitShape();
+ }
+
+ /// A shape an earlier launch kept is known once the cache is listed: the
+ /// placeholder takes it then, if the picture has not arrived first.
+ void _awaitShape() {
+ if (_shapeOf(_ref.file) != null) return;
+ unawaited(
+ superTabImageCache.ready.then((_) {
+ if (mounted && _shapeOf(_ref.file) != null) setState(() {});
+ }),
+ );
+ }
+
+ /// [file]'s width and height: as a load here read them, else as the server
+ /// sent them, else its thumbnail's, which has the same shape.
+ static Size? _shapeOf(SuperTabAttachment file) {
+ final cache = superTabImageCache;
+ final width = file.width, height = file.height;
+ return cache.shapeOf(file.id) ??
+ (width != null && height != null
+ ? Size(width.toDouble(), height.toDouble())
+ : null) ??
+ cache.shapeOf(superTabThumbId(file.id));
}
@override
@@ -74,6 +100,7 @@ class _SuperTabInlineImageState extends State<SuperTabInlineImage> {
_askAgain?.cancel();
_waited = 0;
_start();
+ _awaitShape();
}
void _start() {
@@ -169,7 +196,9 @@ class _SuperTabInlineImageState extends State<SuperTabInlineImage> {
final url = _url;
// No link at all: nothing to open either. A link that failed to draw
// stays a click away, as the full-screen viewer may still read it.
- if (url == null) return _failed ? _broken(file) : _loading();
+ if (url == null) return _failed ? _broken(file) : _loading(file);
+ // The thumbnail is kept apart from the original (image_cache.dart).
+ final cacheId = _thumb ? superTabThumbId(file.id) : file.id;
final radius = BorderRadius.circular(DesktopChrome.controlRadius);
return Semantics(
button: true,
@@ -192,17 +221,22 @@ class _SuperTabInlineImageState extends State<SuperTabInlineImage> {
borderRadius: radius,
child: ExcludeSemantics(
child: Image(
- // One state per address: a failed thumbnail's error must not
- // greet the original that takes its place.
- key: ValueKey(url.toString()),
- image: attachmentPicture(url),
+ // One state per picture: a failed thumbnail's error must not
+ // greet the original that takes its place. Not per link, so
+ // a fresh link to the same picture keeps what is drawn.
+ key: ValueKey(cacheId),
+ image: attachmentPicture(
+ url,
+ fileId: cacheId,
+ side: SuperTabInlineImage.maxSide,
+ ),
fit: BoxFit.contain,
frameBuilder: (_, child, frame, synchronous) =>
- frame == null && !synchronous ? _loading() : child,
+ frame == null && !synchronous ? _loading(file) : child,
errorBuilder: (_, _, _) {
if (_failed) return _broken(file);
_broke(url);
- return _loading();
+ return _loading(file);
},
),
),
@@ -213,12 +247,22 @@ class _SuperTabInlineImageState extends State<SuperTabInlineImage> {
);
}
- /// Still, not pulsing: a picture's shape is unknown until it arrives.
- static Widget _loading() => SizedBox(
- width: SuperTabInlineImage.maxSide * 2 / 3,
- height: SuperTabInlineImage.maxSide / 2,
- child: ColoredBox(color: DesktopChrome.field),
- );
+ /// Still, not pulsing, at the size the picture will take when its shape is
+ /// known (an earlier load kept it), so the chat does not jump when it
+ /// arrives; else a fixed one.
+ static Widget _loading(SuperTabAttachment file) {
+ final size =
+ superTabInlineSize(_shapeOf(file)) ??
+ const Size(
+ SuperTabInlineImage.maxSide * 2 / 3,
+ SuperTabInlineImage.maxSide / 2,
+ );
+ return SizedBox.fromSize(
+ key: ValueKey('super-attachment-placeholder:${file.id}'),
+ size: size,
+ child: ColoredBox(color: DesktopChrome.field),
+ );
+ }
static Widget _broken(SuperTabAttachment file) => Container(
color: DesktopChrome.field,
@@ -243,6 +287,19 @@ class _SuperTabInlineImageState extends State<SuperTabInlineImage> {
);
}
+/// Where a picture of [shape] sits in a message: its own size, made smaller
+/// with its shape kept until it fits [SuperTabInlineImage.maxSide] each way,
+/// as `BoxFit.contain` draws it there. Null for an unknown or empty shape.
+Size? superTabInlineSize(Size? shape) {
+ if (shape == null || shape.isEmpty) return null;
+ const side = SuperTabInlineImage.maxSide;
+ final scale = math.min(
+ 1.0,
+ math.min(side / shape.width, side / shape.height),
+ );
+ return Size(shape.width * scale, shape.height * scale);
+}
+
/// The pictures of one chat or thread, oldest first, for the viewer to page
/// through: the chat view puts one above each list of rows.
class SuperTabImageGallery extends InheritedWidget {
@@ -617,7 +674,7 @@ class _SuperTabImageViewerState extends State<SuperTabImageViewer> {
quarterTurns: _turns,
child: Image(
key: ValueKey('super-attachment-image:${file.id}'),
- image: attachmentPicture(url),
+ image: attachmentPicture(url, fileId: file.id),
fit: BoxFit.contain,
loadingBuilder: (_, child, progress) => progress == null
? child
diff --git a/desktop/lib/super_tabs/attachment_viewer.dart b/desktop/lib/super_tabs/attachment_viewer.dart
index 6a4eeeba1..353b76935 100644
--- a/desktop/lib/super_tabs/attachment_viewer.dart
+++ b/desktop/lib/super_tabs/attachment_viewer.dart
@@ -1,4 +1,6 @@
+import 'dart:async';
import 'dart:io';
+import 'dart:math' as math;
import 'dart:typed_data';
import 'dart:ui' as ui;
@@ -13,6 +15,7 @@ import '../measurement/speed_marks.dart';
import '../widgets/desktop_chrome.dart';
import 'attachment_upload.dart' show kSuperTabFormAttachmentMaxBytes;
import 'file_links.dart';
+import 'image_cache.dart';
import 'model.dart';
/// The largest file read into the chat's text viewer; a bigger one opens in
@@ -28,12 +31,18 @@ Future<Uint8List> Function(Uri url, {int? maxBytes}) attachmentFetcher =
/// A picture off the attachments host, drawn where the chat shows it; tests
/// hand it bytes instead.
@visibleForTesting
-ImageProvider Function(Uri url) attachmentImage = _networkImage;
+ImageProvider Function(AttachmentImage picture) attachmentImage = _asItIs;
-ImageProvider _networkImage(Uri url) => AttachmentImage(url);
+ImageProvider _asItIs(AttachmentImage picture) => picture;
-/// The picture at [url] through [attachmentImage].
-ImageProvider attachmentPicture(Uri url) => attachmentImage(url);
+/// File [fileId]'s picture, read from [url] unless this computer already has
+/// it, through [attachmentImage]: no more than [side] points each way, or the
+/// original without one.
+ImageProvider attachmentPicture(
+ Uri url, {
+ required String fileId,
+ double? side,
+}) => attachmentImage(AttachmentImage(url, fileId: fileId, side: side));
/// The file at [url] through [attachmentFetcher], for the text viewer
/// (`attachment_text_viewer.dart`), which a browser downloads apart.
@@ -240,38 +249,134 @@ class _AttachmentViewerActionsState extends State<AttachmentViewerActions> {
}
}
-/// The picture at [url], read through [attachmentFetcher] like any chat file:
-/// a redirect is refused, so nothing from another host is fetched or drawn
-/// (`NetworkImage` follows one).
+/// File [fileId]'s picture, read at [url] through [attachmentFetcher] like any
+/// chat file: a redirect is refused, so nothing from another host is fetched
+/// or drawn (`NetworkImage` follows one). It is the file's, whatever link it
+/// came by: Flutter holds it by [fileId], and the disk keeps its bytes
+/// ([superTabImageCache]), so a fresh short-lived link to a file already seen
+/// downloads nothing. With [side], it is decoded no larger than [side] points
+/// each way at the screen's pixel ratio, as the chat shows it; without, whole,
+/// as the full-screen viewer does.
+///
+/// Built only with a link that opens now, the message's own or a fresh one the
+/// server granted, so the cache serves only a file this reader may read.
@immutable
-class AttachmentImage extends ImageProvider<AttachmentImage> {
- const AttachmentImage(this.url);
+class AttachmentImage extends ImageProvider<AttachmentPictureKey> {
+ const AttachmentImage(this.url, {required this.fileId, this.side});
final Uri url;
+ final String fileId;
+ final double? side;
@override
- Future<AttachmentImage> obtainKey(ImageConfiguration configuration) =>
- SynchronousFuture(this);
+ Future<AttachmentPictureKey> obtainKey(ImageConfiguration configuration) {
+ final side = this.side;
+ final ratio = configuration.devicePixelRatio ?? 1;
+ return SynchronousFuture(
+ AttachmentPictureKey(fileId, side == null ? null : (side * ratio).ceil()),
+ );
+ }
@override
ImageStreamCompleter loadImage(
- AttachmentImage key,
+ AttachmentPictureKey key,
ImageDecoderCallback decode,
) => MultiFrameImageStreamCompleter(
- codec: _decode(decode),
+ codec: _load(key, decode),
scale: 1,
- debugLabel: url.toString(),
+ debugLabel: 'attachment ${key.fileId}',
);
- // No more than a picture shown in place may weigh, whatever its row says:
- // a larger one fails to draw rather than being read whole.
- Future<ui.Codec> _decode(ImageDecoderCallback decode) async =>
- decode(await ui.ImmutableBuffer.fromUint8List(await readPicture(url)));
+ Future<ui.Codec> _load(
+ AttachmentPictureKey key,
+ ImageDecoderCallback decode,
+ ) async {
+ final cache = superTabImageCache;
+ final began = cache.generation;
+ try {
+ if (await cache.read(fileId) case final kept?) {
+ try {
+ return (await _decode(kept, key, decode)).codec;
+ } catch (_) {
+ // A write a crash cut short: read it again.
+ await cache.drop(fileId);
+ }
+ }
+ // Only a real download is timed (readPicture): a picture this computer
+ // already had costs no fetch.
+ final bytes = await readPicture(url);
+ final (:codec, :shape) = await _decode(bytes, key, decode);
+ if (shape != null) {
+ unawaited(cache.keep(fileId, bytes, shape, generation: began));
+ }
+ return codec;
+ } catch (_) {
+ // Held by the file's id, a failure would answer every later link to
+ // it, the fresh one asked for because this one ended included.
+ PaintingBinding.instance.imageCache.evict(key);
+ rethrow;
+ }
+ }
+
+ /// [bytes] decoded no larger than [key]'s pixels, and the picture's own
+ /// width and height.
+ static Future<({ui.Codec codec, Size? shape})> _decode(
+ Uint8List bytes,
+ AttachmentPictureKey key,
+ ImageDecoderCallback decode,
+ ) async {
+ Size? shape;
+ final codec = await decode(
+ await ui.ImmutableBuffer.fromUint8List(bytes),
+ getTargetSize: (width, height) {
+ shape = Size(width.toDouble(), height.toDouble());
+ final pixels = key.pixels;
+ if (pixels == null || math.max(width, height) <= pixels) {
+ return const ui.TargetImageSize();
+ }
+ return width >= height
+ ? ui.TargetImageSize(width: pixels)
+ : ui.TargetImageSize(height: pixels);
+ },
+ );
+ return (codec: codec, shape: shape);
+ }
+
+ @override
+ bool operator ==(Object other) =>
+ other is AttachmentImage &&
+ other.fileId == fileId &&
+ other.side == side &&
+ other.url == url;
+
+ @override
+ int get hashCode => Object.hash(fileId, side, url);
+}
+
+/// Signing out, or a session that ends: the chat's pictures are the
+/// account's, and none outlives it, on disk or decoded in memory.
+Future<void> superTabForgetPictures() {
+ PaintingBinding.instance.imageCache
+ ..clear()
+ ..clearLiveImages();
+ return superTabImageCache.clear();
+}
+
+/// What Flutter holds a chat picture by: its file, and the pixels it was
+/// decoded at (null: the original). Never its link, which changes.
+@immutable
+class AttachmentPictureKey {
+ const AttachmentPictureKey(this.fileId, this.pixels);
+
+ final String fileId;
+ final int? pixels;
@override
bool operator ==(Object other) =>
- other is AttachmentImage && other.url == url;
+ other is AttachmentPictureKey &&
+ other.fileId == fileId &&
+ other.pixels == pixels;
@override
- int get hashCode => url.hashCode;
+ int get hashCode => Object.hash(fileId, pixels);
}
diff --git a/desktop/lib/super_tabs/image_cache.dart b/desktop/lib/super_tabs/image_cache.dart
new file mode 100644
index 000000000..67ac409d0
--- /dev/null
+++ b/desktop/lib/super_tabs/image_cache.dart
@@ -0,0 +1,341 @@
+import 'dart:async';
+import 'dart:convert';
+import 'dart:ui';
+
+import 'package:flutter/foundation.dart';
+
+import '../core/test_run.dart';
+import '../logging/app_log.dart';
+import 'image_shelf_native.dart'
+ if (dart.library.js_interop) 'image_shelf_web.dart';
+
+/// The most the chat's pictures may take on disk: 200 MB, about two hundred
+/// screenshots. A browser keeps them in memory, and less ([kDefaultShelfBytes]).
+const kSuperTabImageCacheBytes = 200 * 1024 * 1024;
+
+/// One picture on a shelf: its name, its weight, and when it was last shown.
+@immutable
+class SuperTabShelfEntry {
+ const SuperTabShelfEntry({
+ required this.name,
+ required this.bytes,
+ required this.usedAt,
+ });
+
+ final String name;
+ final int bytes;
+ final DateTime usedAt;
+}
+
+/// Where [SuperTabImageCache] keeps its pictures, by name: a private folder on
+/// a computer ([DirectoryImageShelf]), memory in a browser and in tests.
+abstract interface class SuperTabImageShelf {
+ /// Every picture kept, a write left half done excepted (and removed).
+ Future<List<SuperTabShelfEntry>> list();
+
+ /// The picture [name], or null when there is none.
+ Future<Uint8List?> read(String name);
+
+ /// Keeps [bytes] as [name], whole or not at all.
+ Future<void> write(String name, Uint8List bytes);
+
+ /// Marks [name] shown now.
+ Future<void> touch(String name);
+
+ Future<void> delete(String name);
+
+ /// Every picture gone.
+ Future<void> clear();
+}
+
+/// A shelf in memory: a browser's, which has no Harness home, and every test's,
+/// where a real file write never completes inside `testWidgets`.
+class MemoryImageShelf implements SuperTabImageShelf {
+ final _pictures = <String, (Uint8List, int)>{};
+
+ /// Shown order, not wall time: two writes in one microsecond stay ordered.
+ int _tick = 0;
+
+ @override
+ Future<List<SuperTabShelfEntry>> list() async => [
+ for (final MapEntry(:key, value: (bytes, used)) in _pictures.entries)
+ SuperTabShelfEntry(
+ name: key,
+ bytes: bytes.length,
+ usedAt: DateTime.fromMicrosecondsSinceEpoch(used),
+ ),
+ ];
+
+ @override
+ Future<Uint8List?> read(String name) async => _pictures[name]?.$1;
+
+ @override
+ Future<void> write(String name, Uint8List bytes) async =>
+ _pictures[name] = (bytes, ++_tick);
+
+ @override
+ Future<void> touch(String name) async {
+ if (_pictures[name] case (final bytes, _)) {
+ _pictures[name] = (bytes, ++_tick);
+ }
+ }
+
+ @override
+ Future<void> delete(String name) async => _pictures.remove(name);
+
+ @override
+ Future<void> clear() async => _pictures.clear();
+}
+
+/// The chat's pictures by file id, so a fresh short-lived link to a file
+/// already seen downloads nothing (task #3178). Each is kept under
+/// `<file id>~<width>x<height>`, its shape read back by the next launch from
+/// the name alone, so the chat holds each picture's place at its shape before
+/// its bytes are read. Above [capBytes], the least recently shown go first.
+///
+/// It holds only what the reader may read: a picture is asked of it only by a
+/// load that began with a link the server signed for this reader
+/// (`AttachmentImage`), and it is emptied on sign-out.
+class SuperTabImageCache {
+ SuperTabImageCache(this._shelf, {this.capBytes = kSuperTabImageCacheBytes});
+
+ final SuperTabImageShelf _shelf;
+ final int capBytes;
+
+ /// What is kept, by file id: its name on the shelf and its shape.
+ final _kept = <String, ({String name, Size shape, int bytes})>{};
+ int _total = 0;
+
+ int _generation = 0;
+
+ /// Moves on at each [clear]: a load that began before it keeps nothing.
+ int get generation => _generation;
+
+ Future<void>? _listed;
+
+ /// Done once the shelf has been listed (and, at launch, [claim]ed), so
+ /// [shapeOf] knows what an earlier launch kept.
+ Future<void> get ready => _listed ??= _serial(_list);
+
+ /// The shelf's writes, clears and claims, one after another: a clear waits
+ /// for a write under way, then takes it too.
+ Future<void>? _tail;
+
+ Future<T> _serial<T>(Future<T> Function() work) {
+ // Chained from the caller's own zone: a finished future made elsewhere
+ // would run the work in the zone that made it.
+ final next = switch (_tail) {
+ null => Future<T>.sync(work),
+ final tail => tail.then((_) => work()),
+ };
+ _tail = next.then((_) {}, onError: (Object _) {});
+ return next;
+ }
+
+ /// Whose pictures these are: the CLI's machine id they were kept under, the
+ /// one id that proves an account with no network (as `ProfileCache` keeps
+ /// it). Not a picture's name, so never listed, shown or evicted.
+ static const _ownerName = 'owner';
+
+ /// At launch: the pictures stay only when [owner], the machine id the CLI is
+ /// signed in under now (null: signed out), is the one they were kept under.
+ /// A sign-out this app never saw (in a terminal, while it was closed, or a
+ /// clear that failed) leaves them to this, and so does another account
+ /// signing in on this computer. Reads wait for it.
+ Future<void> claim(String? owner) => _listed = _serial(() async {
+ try {
+ final mark = await _shelf.read(_ownerName);
+ final was = mark == null ? null : utf8.decode(mark, allowMalformed: true);
+ final pictures = (await _shelf.list()).any(
+ (entry) => entry.name != _ownerName,
+ );
+ if (owner == null || (was != owner && (was != null || pictures))) {
+ _forgetAll();
+ await _shelf.clear();
+ }
+ if (owner != null && was != owner) {
+ await _shelf.write(_ownerName, utf8.encode(owner));
+ }
+ } catch (error) {
+ appLog.warn(
+ 'super-tabs',
+ 'image cache not claimed: ${error.runtimeType}',
+ );
+ }
+ await _list();
+ });
+
+ /// A sign-in this session proved [owner]: what it keeps is its, at the next
+ /// launch too. Pictures under another owner are not adopted but cleared.
+ Future<void> owned(String owner) => _serial(() async {
+ try {
+ final mark = await _shelf.read(_ownerName);
+ final was = mark == null ? null : utf8.decode(mark, allowMalformed: true);
+ if (was == owner) return;
+ if (was != null) {
+ _forgetAll();
+ await _shelf.clear();
+ }
+ await _shelf.write(_ownerName, utf8.encode(owner));
+ } catch (error) {
+ appLog.warn('super-tabs', 'image cache not owned: ${error.runtimeType}');
+ }
+ });
+
+ void _forgetAll() {
+ _generation++;
+ _kept.clear();
+ _total = 0;
+ }
+
+ /// A file id that can name a file anywhere, and its thumbnail (#3177):
+ /// nothing that can leave the folder or clash with `~`.
+ static final _plainId = RegExp(r'^[A-Za-z0-9_-]{1,128}(\.thumb)?$');
+
+ static final _named = RegExp(r'^(.+)~(\d{1,6})x(\d{1,6})$');
+
+ Future<void> _list() async {
+ final List<SuperTabShelfEntry> entries;
+ try {
+ entries = await _shelf.list();
+ } catch (error) {
+ appLog.warn('super-tabs', 'image cache unreadable: ${error.runtimeType}');
+ return;
+ }
+ for (final entry in entries) {
+ final named = _named.firstMatch(entry.name);
+ if (named == null || !_plainId.hasMatch(named[1]!)) continue;
+ _forget(named[1]!);
+ _kept[named[1]!] = (
+ name: entry.name,
+ shape: Size(double.parse(named[2]!), double.parse(named[3]!)),
+ bytes: entry.bytes,
+ );
+ _total += entry.bytes;
+ }
+ }
+
+ void _forget(String fileId) {
+ if (_kept.remove(fileId) case final old?) _total -= old.bytes;
+ }
+
+ /// [fileId]'s width and height, as an earlier load read them; null when
+ /// unknown, or before the shelf is listed ([ready]).
+ Size? shapeOf(String fileId) {
+ unawaited(ready);
+ return _kept[fileId]?.shape;
+ }
+
+ /// [fileId]'s bytes, or null when not kept.
+ Future<Uint8List?> read(String fileId) async {
+ await ready;
+ final kept = _kept[fileId];
+ if (kept == null) return null;
+ try {
+ final bytes = await _shelf.read(kept.name);
+ if (bytes == null) {
+ _forget(fileId);
+ return null;
+ }
+ unawaited(_shelf.touch(kept.name).catchError((Object _) {}));
+ return bytes;
+ } catch (error) {
+ appLog.warn(
+ 'super-tabs',
+ 'image cache read failed: ${error.runtimeType}',
+ );
+ return null;
+ }
+ }
+
+ /// Keeps [bytes] as [fileId]'s, [shape] its width and height. Nothing is
+ /// kept when the cache was cleared since [generation] (the load's own, from
+ /// when it began), for a picture larger than [capBytes], or for an id that
+ /// is not a plain one.
+ Future<void> keep(
+ String fileId,
+ Uint8List bytes,
+ Size shape, {
+ int? generation,
+ }) async {
+ final began = generation ?? _generation;
+ if (began != _generation) return;
+ if (!_plainId.hasMatch(fileId) || bytes.length > capBytes) return;
+ await ready;
+ final name = '$fileId~${shape.width.round()}x${shape.height.round()}';
+ try {
+ await _serial(() async {
+ // Cleared while this waited its turn: nothing of it is kept.
+ if (began != _generation) return;
+ final old = _kept[fileId];
+ await _shelf.write(name, bytes);
+ if (old != null && old.name != name) await _shelf.delete(old.name);
+ _forget(fileId);
+ _kept[fileId] = (name: name, shape: shape, bytes: bytes.length);
+ _total += bytes.length;
+ if (_total > capBytes) await _evict();
+ });
+ } catch (error) {
+ appLog.warn(
+ 'super-tabs',
+ 'image cache write failed: ${error.runtimeType}',
+ );
+ }
+ }
+
+ /// Down to the cap, the least recently shown first. The shelf is listed
+ /// again, since another window may have kept or dropped pictures meanwhile.
+ Future<void> _evict() async {
+ final entries = await _shelf.list()
+ ..sort((a, b) => a.usedAt.compareTo(b.usedAt));
+ final pictures = [
+ for (final entry in entries)
+ if (_named.firstMatch(entry.name) case final named?) (entry, named[1]!),
+ ];
+ var total = pictures.fold<int>(0, (sum, p) => sum + p.$1.bytes);
+ for (final (entry, fileId) in pictures) {
+ if (total <= capBytes) break;
+ await _shelf.delete(entry.name);
+ total -= entry.bytes;
+ if (_kept[fileId]?.name == entry.name) _forget(fileId);
+ }
+ }
+
+ /// [fileId]'s picture gone: what was kept did not read as a picture.
+ Future<void> drop(String fileId) async {
+ final kept = _kept[fileId];
+ if (kept == null) return;
+ _forget(fileId);
+ try {
+ await _shelf.delete(kept.name);
+ } catch (error) {
+ appLog.warn(
+ 'super-tabs',
+ 'image cache drop failed: ${error.runtimeType}',
+ );
+ }
+ }
+
+ /// Every picture gone, and their shapes: signing out.
+ Future<void> clear() async {
+ _forgetAll();
+ try {
+ await _serial(_shelf.clear);
+ } catch (error) {
+ appLog.warn(
+ 'super-tabs',
+ 'image cache not cleared: ${error.runtimeType}',
+ );
+ }
+ }
+}
+
+/// This app's picture cache: a private folder on a computer, memory in a
+/// browser and in tests, which may set their own.
+SuperTabImageCache superTabImageCache = kUnderTest
+ ? SuperTabImageCache(MemoryImageShelf())
+ : SuperTabImageCache(defaultImageShelf(), capBytes: kDefaultShelfBytes);
+
+/// What the cache keeps file [fileId]'s thumbnail (#3177) under, apart from
+/// the original: the two are different pictures of one file.
+String superTabThumbId(String fileId) => '$fileId.thumb';
diff --git a/desktop/lib/super_tabs/image_shelf_native.dart b/desktop/lib/super_tabs/image_shelf_native.dart
new file mode 100644
index 000000000..4087ed4a4
--- /dev/null
+++ b/desktop/lib/super_tabs/image_shelf_native.dart
@@ -0,0 +1,153 @@
+import 'dart:io';
+import 'dart:typed_data';
+
+import '../core/harness_file_store.dart';
+import '../core/posix_file_mode.dart';
+import '../logging/app_log.dart';
+import 'image_cache.dart';
+
+/// A computer keeps its chat pictures on disk, up to the cache's cap.
+const kDefaultShelfBytes = kSuperTabImageCacheBytes;
+
+/// `~/.harness/desktop-app/image-cache/`; memory where nothing names a home
+/// folder, so signing out never stops at a cache with nowhere to be.
+SuperTabImageShelf defaultImageShelf({Map<String, String>? environment}) {
+ try {
+ return DirectoryImageShelf(
+ Directory(
+ '${HarnessFileStore.defaultDirectoryPath(environment: environment)}'
+ '${Platform.pathSeparator}image-cache',
+ ),
+ );
+ } on StateError {
+ return MemoryImageShelf();
+ }
+}
+
+/// The chat's pictures in a folder of their own, kept to this user (0700, each
+/// file 0600 from its first byte) since they are the account's content. Each
+/// write goes to a temporary of its own and is renamed into place, so two
+/// windows never read half a picture; the time a file was last changed is
+/// when it was last shown.
+///
+/// A write is not synced to the disk: an fsync per picture cost a first open
+/// about 5 ms a picture (chat_image_benchmark.dart), and a picture a power cut
+/// leaves short fails to decode and is read again (`AttachmentImage`).
+class DirectoryImageShelf implements SuperTabImageShelf {
+ DirectoryImageShelf(this.directory);
+
+ final Directory directory;
+
+ static const _part = '.part';
+
+ String _path(String name) =>
+ '${directory.path}${Platform.pathSeparator}$name';
+
+ @override
+ Future<List<SuperTabShelfEntry>> list() async {
+ final entries = <SuperTabShelfEntry>[];
+ try {
+ await for (final entry in directory.list()) {
+ if (entry is! File) continue;
+ final name = entry.uri.pathSegments.last;
+ // A write half done: never a picture. One a stop left is removed;
+ // one under way in this window or another (a minute is far longer
+ // than any write) is left to finish.
+ if (name.endsWith(_part)) {
+ try {
+ final age = DateTime.now().difference(await entry.lastModified());
+ if (age > const Duration(minutes: 1)) await _delete(entry);
+ } on FileSystemException {
+ // Renamed into place meanwhile.
+ }
+ continue;
+ }
+ try {
+ final stat = await entry.stat();
+ entries.add(
+ SuperTabShelfEntry(
+ name: name,
+ bytes: stat.size,
+ usedAt: stat.modified,
+ ),
+ );
+ } on FileSystemException {
+ // Gone under the listing: another window evicted it.
+ }
+ }
+ } on PathNotFoundException {
+ return const [];
+ }
+ return entries;
+ }
+
+ @override
+ Future<Uint8List?> read(String name) async {
+ try {
+ return await File(_path(name)).readAsBytes();
+ } on PathNotFoundException {
+ return null;
+ }
+ }
+
+ @override
+ Future<void> write(String name, Uint8List bytes) async {
+ await directory.create(recursive: true);
+ _restrict(directory.path, 0x1c0);
+ final temporary = File(
+ _path('$name.$pid.${DateTime.now().microsecondsSinceEpoch}$_part'),
+ );
+ try {
+ if (PosixFileMode.supported) {
+ PosixFileMode.createExclusive(temporary.path, 0x180);
+ }
+ await temporary.writeAsBytes(bytes);
+ await temporary.rename(_path(name));
+ } catch (_) {
+ await _delete(temporary);
+ rethrow;
+ }
+ }
+
+ @override
+ Future<void> touch(String name) async {
+ try {
+ await File(_path(name)).setLastModified(DateTime.now());
+ } on FileSystemException {
+ // Evicted meanwhile: nothing to mark.
+ }
+ }
+
+ @override
+ Future<void> delete(String name) => _delete(File(_path(name)));
+
+ @override
+ Future<void> clear() async {
+ try {
+ await directory.delete(recursive: true);
+ } on PathNotFoundException {
+ // Nothing was kept.
+ }
+ }
+
+ static Future<void> _delete(File file) async {
+ try {
+ await file.delete();
+ } on PathNotFoundException {
+ // Already gone: another window evicted it.
+ } on FileSystemException catch (error) {
+ appLog.warn(
+ 'super-tabs',
+ 'image cache file not deleted: '
+ '${error.osError?.message ?? error.runtimeType}',
+ );
+ }
+ }
+
+ /// Windows has no POSIX modes, and a phone's sandbox is already the app's.
+ static void _restrict(String path, int mode) {
+ if (!PosixFileMode.supported) return;
+ if (FileStat.statSync(path).mode & 0xfff == mode) return;
+ PosixFileMode.chmod(path, mode);
+ }
+}
diff --git a/desktop/lib/super_tabs/image_shelf_web.dart b/desktop/lib/super_tabs/image_shelf_web.dart
new file mode 100644
index 000000000..28c7c87a3
--- /dev/null
+++ b/desktop/lib/super_tabs/image_shelf_web.dart
@@ -0,0 +1,8 @@
+import 'image_cache.dart';
+
+/// A browser keeps its chat pictures in memory, so less of them.
+const kDefaultShelfBytes = 64 * 1024 * 1024;
+
+/// A browser has no Harness home: memory, gone with the page.
+SuperTabImageShelf defaultImageShelf({Map<String, String>? environment}) =>
+ MemoryImageShelf();
diff --git a/desktop/test/benchmarks/chat_image_benchmark.dart b/desktop/test/benchmarks/chat_image_benchmark.dart
new file mode 100644
index 000000000..3b692519d
--- /dev/null
+++ b/desktop/test/benchmarks/chat_image_benchmark.dart
@@ -0,0 +1,118 @@
+// Run explicitly: flutter test test/benchmarks/chat_image_benchmark.dart --reporter expanded
+// Task #3178: an image-heavy chat on a loopback attachments host, opened, then
+// opened again once every link was replaced (signed links last minutes), then
+// after a relaunch. It counts what the chat downloads and what it holds
+// decoded; times are loopback and headless, not network or display claims.
+import 'dart:async';
+import 'dart:io';
+import 'dart:math';
+import 'dart:typed_data';
+import 'dart:ui' as ui;
+
+import 'package:flutter/painting.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/super_tabs/attachment_viewer.dart';
+import 'package:harness/super_tabs/image_cache.dart';
+import 'package:harness/super_tabs/image_shelf_native.dart';
+
+const _pictures = 30;
+const _width = 2400, _height = 1600;
+
+/// A screenshot-like picture: flat blocks with noise, so it compresses as a
+/// real one does rather than to nothing.
+Future<Uint8List> _screenshot(int seed) async {
+ final random = Random(seed);
+ final recorder = ui.PictureRecorder();
+ final canvas = ui.Canvas(recorder);
+ for (var y = 0; y < _height; y += 6) {
+ for (var x = 0; x < _width; x += 6) {
+ canvas.drawRect(
+ ui.Rect.fromLTWH(x.toDouble(), y.toDouble(), 6, 6),
+ ui.Paint()..color = ui.Color(0xff000000 | random.nextInt(0xffffff)),
+ );
+ }
+ }
+ final image = await recorder.endRecording().toImage(_width, _height);
+ final data = await image.toByteData(format: ui.ImageByteFormat.png);
+ image.dispose();
+ return data!.buffer.asUint8List();
+}
+
+void main() {
+ TestWidgetsFlutterBinding.ensureInitialized();
+
+ test('an image-heavy chat: downloads, bytes and decoded memory', () async {
+ final files = [for (var i = 0; i < _pictures; i++) await _screenshot(i)];
+ var downloads = 0, served = 0;
+ final server = await HttpServer.bind(InternetAddress.loopbackIPv4, 0);
+ server.listen((request) {
+ final bytes = files[int.parse(request.uri.pathSegments.first)];
+ downloads++;
+ served += bytes.length;
+ request.response
+ ..add(bytes)
+ ..close();
+ });
+ final home = await Directory.systemTemp.createTemp('chat-image-bench.');
+ final shelf = DirectoryImageShelf(Directory('${home.path}/image-cache'));
+ final original = superTabImageCache;
+ superTabImageCache = SuperTabImageCache(shelf);
+
+ /// Every picture as the chat shows it, on a 2x screen, by links of
+ /// generation [links]: what it downloaded, held decoded, and took.
+ Future<String> open(String step, int links) async {
+ downloads = served = 0;
+ var decoded = 0;
+ final clock = Stopwatch()..start();
+ await Future.wait([
+ for (var i = 0; i < _pictures; i++)
+ () {
+ final done = Completer<void>();
+ final url = Uri.parse(
+ 'http://127.0.0.1:${server.port}/$i/shot.png?sig=$links',
+ );
+ attachmentPicture(url, fileId: 'f$i', side: 360)
+ .resolve(const ImageConfiguration(devicePixelRatio: 2))
+ .addListener(
+ ImageStreamListener((info, _) {
+ decoded += info.image.width * info.image.height * 4;
+ if (!done.isCompleted) done.complete();
+ }, onError: (error, _) => done.completeError(error)),
+ );
+ return done.future;
+ }(),
+ ]);
+ final ms = clock.elapsedMilliseconds;
+ // Out of Flutter's memory, as pictures scrolled away or a relaunch
+ // leave it; what stays is what the disk kept.
+ imageCache
+ ..clear()
+ ..clearLiveImages();
+ await Future<void>.delayed(const Duration(milliseconds: 200));
+ return '| $step | $downloads | ${(served / 1e6).toStringAsFixed(1)} MB '
+ '| ${(decoded / 1e6).toStringAsFixed(1)} MB | $ms ms |';
+ }
+
+ final rows = [
+ await open('open the chat', 1),
+ await open('open it again, every link new', 2),
+ ];
+ superTabImageCache = SuperTabImageCache(shelf);
+ rows.add(await open('after a relaunch', 3));
+
+ // ignore: avoid_print
+ print(
+ [
+ '$_pictures pictures, ${_width}x$_height, '
+ '${(files.fold<int>(0, (s, f) => s + f.length) / 1e6).toStringAsFixed(1)} MB in all',
+ '| step | downloads | bytes downloaded | decoded in memory | time |',
+ '|---|---|---|---|---|',
+ ...rows,
+ ].join('\n'),
+ );
+
+ superTabImageCache = original;
+ await server.close(force: true);
+ await home.delete(recursive: true);
+ }, timeout: const Timeout(Duration(minutes: 5)));
+}
diff --git a/desktop/test/profile_cache_test.dart b/desktop/test/profile_cache_test.dart
index cb0999b4d..ed1df3b6f 100644
--- a/desktop/test/profile_cache_test.dart
+++ b/desktop/test/profile_cache_test.dart
@@ -1,5 +1,7 @@
import 'dart:async';
import 'dart:convert';
+import 'dart:typed_data';
+import 'dart:ui';
import 'package:flutter_test/flutter_test.dart';
import 'package:harness/api/api_client.dart';
@@ -13,6 +15,7 @@ import 'package:harness/core/models.dart';
import 'package:harness/state/app_state.dart';
import 'package:harness/state/pane_layout_store.dart';
import 'package:harness/state/profile_cache.dart';
+import 'package:harness/super_tabs/image_cache.dart';
import 'package:harness/ws/local_cli_discovery.dart';
// Task #2169: the last profile of the same signed-in account shows at once, and another account's never does. A machine
@@ -284,6 +287,75 @@ void main() {
expect(storage.values, isNot(contains(ProfileCache.key)));
});
+ group("the chat's pictures (#3178)", () {
+ late SuperTabImageCache original;
+ late MemoryImageShelf shelf;
+
+ setUp(() async {
+ original = superTabImageCache;
+ shelf = MemoryImageShelf();
+ superTabImageCache = SuperTabImageCache(shelf);
+ await superTabImageCache.keep('a1', Uint8List(8), const Size(4, 3));
+ });
+ tearDown(() => superTabImageCache = original);
+
+ test('signing out clears them, and their shapes', () async {
+ await signedInBefore('machine-a', 'ada');
+ final again = await open('machine-a');
+ await superTabImageCache.keep('a1', Uint8List(8), const Size(4, 3));
+ expect(await superTabImageCache.read('a1'), isNotNull);
+
+ await again.app.logout();
+ await _ticks();
+
+ expect(await shelf.list(), isEmpty);
+ expect(superTabImageCache.shapeOf('a1'), isNull);
+ });
+
+ /// A relaunch: the same folder, a new cache over it.
+ void relaunch() => superTabImageCache = SuperTabImageCache(shelf);
+
+ test('kept across a launch signed in on the same computer', () async {
+ await signedInBefore('machine-a', 'ada');
+ await superTabImageCache.keep('a2', Uint8List(8), const Size(4, 3));
+
+ relaunch();
+ await open('machine-a');
+
+ expect(await superTabImageCache.read('a2'), isNotNull);
+ });
+
+ test('a launch after signing out in a terminal clears them', () async {
+ await signedInBefore('machine-a', 'ada');
+ await superTabImageCache.keep('a2', Uint8List(8), const Size(4, 3));
+
+ relaunch();
+ await open(null, loggedIn: false);
+
+ expect(await shelf.list(), isEmpty);
+ });
+
+ test('a launch as another computer sign-in clears them', () async {
+ await signedInBefore('machine-a', 'ada');
+ await superTabImageCache.keep('a2', Uint8List(8), const Size(4, 3));
+
+ relaunch();
+ await open('machine-b');
+
+ expect(await superTabImageCache.read('a2'), isNull);
+ });
+
+ test('a session that ends clears them too', () async {
+ await signedInBefore('machine-a', 'ada');
+ final again = await open('machine-a');
+
+ again.app.expireSessionForTest('Your sign-in expired. Sign in again.');
+ await _ticks();
+
+ expect(await shelf.list(), isEmpty);
+ });
+ });
+
test(
'a sign-out during a write leaves nothing: the store takes them in order',
() async {
diff --git a/desktop/test/super_tab_attachment_image_test.dart b/desktop/test/super_tab_attachment_image_test.dart
index 39e35affd..f338b57ff 100644
--- a/desktop/test/super_tab_attachment_image_test.dart
+++ b/desktop/test/super_tab_attachment_image_test.dart
@@ -1,13 +1,17 @@
// The chat's picture loader against a real server: it draws the picture the
// attachments host serves, and refuses a redirect, so nothing from another
-// host is ever fetched or drawn.
+// host is ever fetched or drawn. A picture is the file's, whatever link it
+// came by: a fresh link to a file already seen downloads nothing (#3178), and
+// the chat decodes it no larger than it shows it.
import 'dart:async';
import 'dart:io';
+import 'dart:typed_data';
import 'dart:ui' as ui;
import 'package:flutter/painting.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:harness/super_tabs/attachment_viewer.dart';
+import 'package:harness/super_tabs/image_cache.dart';
/// A real 1×1 PNG.
const _png = <int>[
@@ -19,16 +23,31 @@ const _png = <int>[
0x00, 0x00, 0x49, 0x45, 0x4E, 0x44, 0xAE, 0x42, 0x60, 0x82,
];
+Future<Uint8List> _picture(int width, int height) async {
+ final recorder = ui.PictureRecorder();
+ ui.Canvas(recorder).drawRect(
+ ui.Rect.fromLTWH(0, 0, width.toDouble(), height.toDouble()),
+ ui.Paint()..color = const ui.Color(0xff3366cc),
+ );
+ final image = await recorder.endRecording().toImage(width, height);
+ final data = await image.toByteData(format: ui.ImageByteFormat.png);
+ image.dispose();
+ return data!.buffer.asUint8List();
+}
+
void main() {
TestWidgetsFlutterBinding.ensureInitialized();
late HttpServer server, elsewhere;
- late int elsewhereHits;
+ late int hits, elsewhereHits;
late Future<void> Function(HttpResponse) answer;
+ late SuperTabImageCache original;
Uri link(String path) => Uri.parse('http://127.0.0.1:${server.port}$path');
setUp(() async {
- elsewhereHits = 0;
+ hits = elsewhereHits = 0;
+ original = superTabImageCache;
+ superTabImageCache = SuperTabImageCache(MemoryImageShelf());
elsewhere = await HttpServer.bind(InternetAddress.loopbackIPv4, 0);
elsewhere.listen((request) {
elsewhereHits++;
@@ -38,19 +57,32 @@ void main() {
..close();
});
server = await HttpServer.bind(InternetAddress.loopbackIPv4, 0);
- server.listen((request) => answer(request.response));
+ server.listen((request) {
+ hits++;
+ answer(request.response);
+ });
});
tearDown(() async {
await server.close(force: true);
await elsewhere.close(force: true);
- imageCache.clear();
+ // Held by file id: one test's a1 must not answer the next's.
+ imageCache
+ ..clear()
+ ..clearLiveImages();
+ superTabImageCache = original;
});
- /// What [url]'s picture comes to: its image, or the error it ends in.
- Future<Object> load(Uri url) {
+ /// What file [fileId]'s picture at [url] comes to: its image, or the error
+ /// it ends in.
+ Future<Object> load(
+ Uri url, {
+ String fileId = 'a1',
+ double? side,
+ double pixelRatio = 1,
+ }) {
final done = Completer<Object>();
- attachmentPicture(url)
- .resolve(ImageConfiguration.empty)
+ attachmentPicture(url, fileId: fileId, side: side)
+ .resolve(ImageConfiguration(devicePixelRatio: pixelRatio))
.addListener(
ImageStreamListener(
(image, _) => done.complete(image.image),
@@ -68,6 +100,116 @@ void main() {
expect((image as ui.Image).width, 1);
});
+ test(
+ "a new signed link for the same file id doesn't download again",
+ () async {
+ answer = (response) => (response..add(_png)).close();
+
+ expect(await load(link('/a1.png?sig=1'), side: 360), isA<ui.Image>());
+ expect(await load(link('/a1.png?sig=2'), side: 360), isA<ui.Image>());
+ expect(hits, 1);
+
+ // Flutter's own copy gone, as after a while or a relaunch: the cache
+ // answers, not the server.
+ imageCache
+ ..clear()
+ ..clearLiveImages();
+ expect(await load(link('/a1.png?sig=3'), side: 360), isA<ui.Image>());
+ expect(hits, 1);
+ },
+ );
+
+ test('another file is another picture', () async {
+ answer = (response) => (response..add(_png)).close();
+
+ await load(link('/a1.png?sig=1'));
+ await load(link('/a2.png?sig=1'), fileId: 'a2');
+
+ expect(hits, 2);
+ });
+
+ test('decodes no larger than the chat shows it', () async {
+ final wide = await _picture(2000, 1000);
+ answer = (response) => (response..add(wide)).close();
+
+ final shown = await load(link('/a1.png'), side: 360, pixelRatio: 2);
+ expect((shown as ui.Image).width, 720);
+ expect(shown.height, 360);
+ expect(superTabImageCache.shapeOf('a1'), const ui.Size(2000, 1000));
+
+ // The full-screen viewer: the original, from the bytes already here.
+ final whole = await load(link('/a1.png?sig=2'));
+ expect((whole as ui.Image).width, 2000);
+ expect(hits, 1);
+ });
+
+ test('a tall picture is held to the chat by its height', () async {
+ final tall = await _picture(500, 1500);
+ answer = (response) => (response..add(tall)).close();
+
+ final shown = await load(link('/a1.png'), side: 360);
+ expect((shown as ui.Image).height, 360);
+ expect(shown.width, 120);
+ });
+
+ test('a small picture keeps its size', () async {
+ answer = (response) => (response..add(_png)).close();
+
+ final shown = await load(link('/a1.png'), side: 360, pixelRatio: 2);
+ expect((shown as ui.Image).width, 1);
+ });
+
+ test('a failed load is not kept: a fresh link loads it', () async {
+ var first = true;
+ answer = (response) {
+ if (first) {
+ first = false;
+ response.statusCode = HttpStatus.forbidden;
+ return response.close();
+ }
+ return (response..add(_png)).close();
+ };
+
+ expect(
+ await load(link('/a1.png?sig=old'), side: 360),
+ isNot(isA<ui.Image>()),
+ );
+ expect(await load(link('/a1.png?sig=new'), side: 360), isA<ui.Image>());
+ expect(hits, 2);
+ });
+
+ test('a kept picture that does not decode is read again', () async {
+ answer = (response) => (response..add(_png)).close();
+ // What a write cut short by a crash may leave.
+ await superTabImageCache.keep(
+ 'a1',
+ Uint8List.fromList([1, 2, 3]),
+ const ui.Size(1, 1),
+ );
+
+ expect(await load(link('/a1.png'), side: 360), isA<ui.Image>());
+ expect(hits, 1);
+ await Future<void>.delayed(Duration.zero);
+ expect(await superTabImageCache.read('a1'), _png);
+ });
+
+ test('a picture whose load began before sign-out is not kept', () async {
+ final gate = Completer<void>();
+ answer = (response) async {
+ await gate.future;
+ return (response..add(_png)).close();
+ };
+
+ final loading = load(link('/a1.png'), side: 360);
+ await Future<void>.delayed(Duration.zero);
+ await superTabImageCache.clear();
+ gate.complete();
+ await loading;
+ await Future<void>.delayed(Duration.zero);
+
+ expect(await superTabImageCache.read('a1'), isNull);
+ });
+
for (final status in [
HttpStatus.movedPermanently,
HttpStatus.found,
@@ -86,6 +228,7 @@ void main() {
expect(await load(link('/a.png')), isNot(isA<ui.Image>()));
expect(elsewhereHits, 0);
+ expect(await superTabImageCache.read('a1'), isNull);
});
}
}
diff --git a/desktop/test/super_tab_file_links_test.dart b/desktop/test/super_tab_file_links_test.dart
index 32840593e..d57faa185 100644
--- a/desktop/test/super_tab_file_links_test.dart
+++ b/desktop/test/super_tab_file_links_test.dart
@@ -65,7 +65,7 @@ void main() {
late List<Uri> drawn;
late Map<String, Uint8List> pictures;
late Future<bool> Function(Uri) browser;
- late ImageProvider Function(Uri) image;
+ late ImageProvider Function(AttachmentImage) image;
setUp(() {
opened = [];
@@ -78,7 +78,8 @@ void main() {
opened.add(url);
return true;
};
- attachmentImage = (url) {
+ attachmentImage = (picture) {
+ final url = picture.url;
drawn.add(url);
return MemoryImage(pictures[url.toString()] ?? Uint8List(3));
};
diff --git a/desktop/test/super_tab_image_cache_test.dart b/desktop/test/super_tab_image_cache_test.dart
new file mode 100644
index 000000000..ec4acac37
--- /dev/null
+++ b/desktop/test/super_tab_image_cache_test.dart
@@ -0,0 +1,281 @@
+// The chat's picture cache: kept by file id, under its cap with the least
+// recently shown out first, its shapes remembered across launches, and
+// emptied whole on sign-out.
+import 'dart:async';
+import 'dart:io';
+import 'dart:typed_data';
+import 'dart:ui';
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness/core/posix_file_mode.dart';
+import 'package:harness/super_tabs/image_cache.dart';
+import 'package:harness/super_tabs/image_shelf_native.dart';
+
+/// A shelf whose writes wait until [release] completes.
+class _SlowShelf extends MemoryImageShelf {
+ final release = Completer<void>();
+ final started = Completer<void>();
+ @override
+ Future<void> write(String name, Uint8List bytes) async {
+ if (!started.isCompleted) started.complete();
+ await release.future;
+ await super.write(name, bytes);
+ }
+}
+
+Uint8List _bytes(int length, [int fill = 1]) =>
+ Uint8List(length)..fillRange(0, length, fill);
+
+void main() {
+ late MemoryImageShelf shelf;
+ late SuperTabImageCache cache;
+
+ setUp(() {
+ shelf = MemoryImageShelf();
+ cache = SuperTabImageCache(shelf, capBytes: 100);
+ });
+
+ Future<int> held() async =>
+ (await shelf.list()).fold<int>(0, (sum, entry) => sum + entry.bytes);
+
+ test('keeps a picture by its file id', () async {
+ await cache.keep('a1', _bytes(10), const Size(800, 600));
+
+ expect(await cache.read('a1'), _bytes(10));
+ expect(cache.shapeOf('a1'), const Size(800, 600));
+ expect(await cache.read('a2'), isNull);
+ expect(cache.shapeOf('a2'), isNull);
+ });
+
+ test('keeps a thumbnail apart from its original', () async {
+ await cache.keep('a1', _bytes(10, 1), const Size(4000, 3000));
+ await cache.keep('a1.thumb', _bytes(5, 2), const Size(720, 540));
+
+ expect(await cache.read('a1'), _bytes(10, 1));
+ expect(await cache.read('a1.thumb'), _bytes(5, 2));
+ });
+
+ test('stays under its cap, least recently shown out first', () async {
+ await cache.keep('a1', _bytes(40), const Size(1, 1));
+ await cache.keep('a2', _bytes(40), const Size(1, 1));
+ // Shown again: a2 is now the one least recently shown.
+ expect(await cache.read('a1'), isNotNull);
+ await cache.keep('a3', _bytes(40), const Size(1, 1));
+
+ expect(await cache.read('a2'), isNull);
+ expect(cache.shapeOf('a2'), isNull);
+ expect(await cache.read('a1'), isNotNull);
+ expect(await cache.read('a3'), isNotNull);
+ expect(await held(), lessThanOrEqualTo(100));
+ });
+
+ test('a picture larger than the cap is not kept', () async {
+ await cache.keep('a1', _bytes(40), const Size(1, 1));
+ await cache.keep('big', _bytes(101), const Size(1, 1));
+
+ expect(await cache.read('big'), isNull);
+ expect(await cache.read('a1'), isNotNull);
+ });
+
+ test('clear empties it and forgets its shapes', () async {
+ await cache.keep('a1', _bytes(10), const Size(800, 600));
+ final before = cache.generation;
+
+ await cache.clear();
+
+ expect(await cache.read('a1'), isNull);
+ expect(cache.shapeOf('a1'), isNull);
+ expect(await shelf.list(), isEmpty);
+ expect(cache.generation, isNot(before));
+ });
+
+ test('a picture whose load began before a clear is not kept', () async {
+ final began = cache.generation;
+ await cache.clear();
+
+ await cache.keep('a1', _bytes(10), const Size(1, 1), generation: began);
+
+ expect(await cache.read('a1'), isNull);
+ expect(await shelf.list(), isEmpty);
+ });
+
+ test('a write under way at sign-out is not kept', () async {
+ final slow = _SlowShelf();
+ final cache = SuperTabImageCache(slow);
+ final writing = cache.keep(
+ 'a1',
+ _bytes(10),
+ const Size(1, 1),
+ generation: cache.generation,
+ );
+ await slow.started.future;
+
+ final clearing = cache.clear();
+ slow.release.complete();
+ await Future.wait([writing, clearing]);
+
+ expect(await slow.list(), isEmpty);
+ expect(await cache.read('a1'), isNull);
+ expect(cache.shapeOf('a1'), isNull);
+ });
+
+ group('whose pictures they are', () {
+ Future<SuperTabImageCache> launched(String? owner) async {
+ final next = SuperTabImageCache(shelf, capBytes: 100);
+ await next.claim(owner);
+ return next;
+ }
+
+ test('kept for the same computer sign-in', () async {
+ await cache.claim('machine-a');
+ await cache.keep('a1', _bytes(10), const Size(1, 1));
+
+ final next = await launched('machine-a');
+ expect(await next.read('a1'), isNotNull);
+ });
+
+ test('cleared at launch when the CLI is signed out', () async {
+ await cache.claim('machine-a');
+ await cache.keep('a1', _bytes(10), const Size(1, 1));
+
+ final next = await launched(null);
+ expect(await next.read('a1'), isNull);
+ expect(await shelf.list(), isEmpty);
+ });
+
+ test('cleared at launch when the CLI names another machine', () async {
+ await cache.claim('machine-a');
+ await cache.keep('a1', _bytes(10), const Size(1, 1));
+
+ final next = await launched('machine-b');
+ expect(await next.read('a1'), isNull);
+ // Now machine-b's: its pictures stay at its next launch.
+ await next.keep('b1', _bytes(10), const Size(1, 1));
+ expect(await (await launched('machine-b')).read('b1'), isNotNull);
+ });
+
+ test('pictures nobody claimed are cleared at launch', () async {
+ await cache.keep('a1', _bytes(10), const Size(1, 1));
+
+ final next = await launched('machine-a');
+ expect(await next.read('a1'), isNull);
+ });
+
+ test(
+ 'a sign-in this session keeps its pictures for the next launch',
+ () async {
+ await cache.claim(null);
+ await cache.keep('a1', _bytes(10), const Size(1, 1));
+ await cache.owned('machine-a');
+
+ final next = await launched('machine-a');
+ expect(await next.read('a1'), isNotNull);
+ },
+ );
+
+ test('a launch waits for its claim before reading', () async {
+ await cache.claim('machine-a');
+ await cache.keep('a1', _bytes(10), const Size(1, 1));
+
+ final next = SuperTabImageCache(shelf, capBytes: 100);
+ final claiming = next.claim(null);
+ expect(await next.read('a1'), isNull);
+ await claiming;
+ });
+ });
+
+ test('reads the shapes kept by an earlier launch', () async {
+ await cache.keep('a1', _bytes(10), const Size(1600, 900));
+
+ final next = SuperTabImageCache(shelf, capBytes: 100);
+ expect(next.shapeOf('a1'), isNull, reason: 'not listed yet');
+ await next.ready;
+
+ expect(next.shapeOf('a1'), const Size(1600, 900));
+ expect(await next.read('a1'), _bytes(10));
+ });
+
+ test('a file id that is not a plain id is never kept', () async {
+ for (final id in ['../x', 'a/b', '', 'a~1x1', 'a:thumb', 'a.b']) {
+ await cache.keep(id, _bytes(1), const Size(1, 1));
+ }
+
+ expect(await shelf.list(), isEmpty);
+ });
+
+ group('on disk', () {
+ late Directory home;
+
+ setUp(() async {
+ home = await Directory.systemTemp.createTemp('image-cache-test.');
+ });
+ tearDown(() => home.delete(recursive: true));
+
+ test('keeps pictures between launches', () async {
+ final folder = Directory('${home.path}/image-cache');
+ final first = SuperTabImageCache(DirectoryImageShelf(folder));
+ await first.keep('a1', _bytes(10), const Size(800, 600));
+
+ final next = SuperTabImageCache(DirectoryImageShelf(folder));
+ await next.ready;
+
+ expect(next.shapeOf('a1'), const Size(800, 600));
+ expect(await next.read('a1'), _bytes(10));
+ });
+
+ test('a write left half done is never read', () async {
+ final folder = Directory('${home.path}/image-cache')..createSync();
+ final part = File('${folder.path}/a1~2x2.4242.1.part')
+ ..writeAsBytesSync([1, 2])
+ ..setLastModifiedSync(
+ DateTime.now().subtract(const Duration(hours: 1)),
+ );
+
+ final cache = SuperTabImageCache(DirectoryImageShelf(folder));
+ await cache.ready;
+
+ expect(cache.shapeOf('a1'), isNull);
+ expect(await cache.read('a1'), isNull);
+ expect(part.existsSync(), isFalse);
+ });
+
+ test('a write another window has under way is left alone', () async {
+ final folder = Directory('${home.path}/image-cache')..createSync();
+ final fresh = File('${folder.path}/a1~2x2.4242.1.part')
+ ..writeAsBytesSync([1, 2]);
+
+ await SuperTabImageCache(DirectoryImageShelf(folder)).ready;
+
+ expect(fresh.existsSync(), isTrue);
+ });
+
+ test('with no home folder it keeps pictures in memory', () async {
+ final shelf = defaultImageShelf(environment: const {});
+ expect(shelf, isA<MemoryImageShelf>());
+ });
+
+ test('is kept to this user', () async {
+ final folder = Directory('${home.path}/image-cache');
+ await SuperTabImageCache(DirectoryImageShelf(folder))
+ .keep('a1', _bytes(10), const Size(1, 1));
+ if (!PosixFileMode.supported) return;
+
+ expect(folder.statSync().mode & 0x1ff, 0x1c0);
+ final file = folder.listSync().single;
+ expect(file.statSync().mode & 0x1ff, 0x180);
+ });
+
+ test('clear empties the folder', () async {
+ final folder = Directory('${home.path}/image-cache');
+ final cache = SuperTabImageCache(DirectoryImageShelf(folder));
+ await cache.keep('a1', _bytes(10), const Size(1, 1));
+
+ await cache.clear();
+
+ expect(
+ folder.existsSync() ? folder.listSync() : const <FileSystemEntity>[],
+ isEmpty,
+ );
+ });
+ });
+}
diff --git a/desktop/test/super_tab_image_viewer_test.dart b/desktop/test/super_tab_image_viewer_test.dart
index 34067e15b..be9a1b87b 100644
--- a/desktop/test/super_tab_image_viewer_test.dart
+++ b/desktop/test/super_tab_image_viewer_test.dart
@@ -50,7 +50,7 @@ SuperTabImageItem _item(
);
void main() {
- late ImageProvider Function(Uri) original;
+ late ImageProvider Function(AttachmentImage) original;
late Uint8List png;
setUp(() => original = attachmentImage);
@@ -354,7 +354,8 @@ void main() {
});
}),
]);
- attachmentImage = (url) {
+ attachmentImage = (picture) {
+ final url = picture.url;
drawn.add(url);
return MemoryImage(png);
};
diff --git a/desktop/test/super_tab_inline_image_retry_test.dart b/desktop/test/super_tab_inline_image_retry_test.dart
index 06fb75a62..0ecd36ff7 100644
--- a/desktop/test/super_tab_inline_image_retry_test.dart
+++ b/desktop/test/super_tab_inline_image_retry_test.dart
@@ -23,7 +23,7 @@ void main() {
'https://$kSuperTabFilesHost/bucket/super-tabs/tab/a1/shot.png'
'?X-Goog-Signature=$sig';
- late ImageProvider Function(Uri) original;
+ late ImageProvider Function(AttachmentImage) original;
setUp(() {
original = attachmentImage;
attachmentImage = (_) => MemoryImage(_png);
diff --git a/desktop/test/super_tab_message_media_test.dart b/desktop/test/super_tab_message_media_test.dart
index 150257b2d..bc07d058d 100644
--- a/desktop/test/super_tab_message_media_test.dart
+++ b/desktop/test/super_tab_message_media_test.dart
@@ -4,6 +4,7 @@
import 'dart:async';
import 'dart:ui' as ui;
+import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:flutter_test/flutter_test.dart';
@@ -11,6 +12,7 @@ import 'package:harness/shared/theme/app_theme.dart' as grid;
import 'package:harness/super_tabs/attachment_upload.dart';
import 'package:harness/super_tabs/attachment_viewer.dart';
import 'package:harness/super_tabs/controller.dart';
+import 'package:harness/super_tabs/image_cache.dart';
import 'package:harness/super_tabs/thread_panel.dart';
import 'package:harness/super_tabs/view.dart';
@@ -29,6 +31,17 @@ Future<Uint8List> _png(WidgetTester tester, int width, int height) async =>
return data!.buffer.asUint8List();
}))!;
+/// A picture that never arrives: what is shown is its placeholder.
+class _Pending extends ImageProvider<_Pending> {
+ @override
+ Future<_Pending> obtainKey(ImageConfiguration configuration) =>
+ SynchronousFuture(this);
+
+ @override
+ ImageStreamCompleter loadImage(_Pending key, ImageDecoderCallback decode) =>
+ OneFrameImageStreamCompleter(Completer<ImageInfo>().future);
+}
+
Map<String, dynamic> _file(
String id,
String name,
@@ -45,27 +58,40 @@ Map<String, dynamic> _file(
void main() {
late List<Uri> loaded;
+ late List<AttachmentImage> asked;
late Map<String, Uint8List> pictures;
- late ImageProvider Function(Uri) original;
+ late SuperTabImageCache cache;
+ late ImageProvider Function(AttachmentImage) original;
setUp(() {
loaded = [];
+ asked = [];
pictures = {};
+ cache = superTabImageCache;
+ superTabImageCache = SuperTabImageCache(MemoryImageShelf());
original = attachmentImage;
- attachmentImage = (url) {
+ attachmentImage = (picture) {
+ final url = picture.url;
+ asked.add(picture);
loaded.add(url);
return MemoryImage(pictures[url.pathSegments.last]!);
};
});
- tearDown(() => attachmentImage = original);
+ tearDown(() {
+ attachmentImage = original;
+ superTabImageCache = cache;
+ });
/// A conversation whose one message says [text] and carries [files].
Future<SuperTabController> show(
WidgetTester tester, {
String text = 'Here',
List<Map<String, dynamic>> files = const [],
+ FutureOr<Map<String, dynamic>> Function(String id)? fileLink,
}) async {
- final server = ConversationServer()..append(text, attachments: files);
+ final server = ConversationServer()
+ ..append(text, attachments: files)
+ ..fileLink = fileLink;
final controller = server.controller();
await controller.refresh();
await tester.binding.setSurfaceSize(const Size(1100, 800));
@@ -181,6 +207,7 @@ void main() {
final failed = Completer<Object>();
AttachmentImage(
Uri.parse('https://cdn.harness.autonomous.ai/a1/lies.png'),
+ fileId: 'a1',
)
.resolve(ImageConfiguration.empty)
.addListener(
@@ -275,6 +302,102 @@ void main() {
expect(find.text('shot.png can’t be shown here.'), findsOneWidget);
await close(tester, c);
});
+
+ Finder placeholder(String id) =>
+ find.byKey(ValueKey('super-attachment-placeholder:$id'));
+
+ testWidgets('a picture whose shape is known holds its place at that shape', (
+ tester,
+ ) async {
+ await tester.runAsync(
+ () =>
+ superTabImageCache.keep('a1', Uint8List(8), const Size(1600, 900)),
+ );
+ attachmentImage = (_) => _Pending();
+ final c = await show(
+ tester,
+ files: [_file('a1', 'shot.png', 'image/png')],
+ );
+
+ // Fitted in 360×360 as the picture will be: nothing moves when it comes.
+ expect(tester.getSize(placeholder('a1')), const Size(360, 202.5));
+ await close(tester, c);
+ });
+
+ testWidgets('a shape an earlier launch kept is read before it is shown', (
+ tester,
+ ) async {
+ final shelf = MemoryImageShelf();
+ await tester.runAsync(
+ () =>
+ SuperTabImageCache(shelf)
+ .keep('a1', Uint8List(8), const Size(200, 800)),
+ );
+ superTabImageCache = SuperTabImageCache(shelf);
+ attachmentImage = (_) => _Pending();
+ final c = await show(
+ tester,
+ files: [_file('a1', 'shot.png', 'image/png')],
+ );
+
+ expect(tester.getSize(placeholder('a1')), const Size(90, 360));
+ await close(tester, c);
+ });
+
+ testWidgets('an unknown shape keeps the plain placeholder', (tester) async {
+ attachmentImage = (_) => _Pending();
+ final c = await show(
+ tester,
+ files: [_file('a1', 'shot.png', 'image/png')],
+ );
+
+ expect(tester.getSize(placeholder('a1')), const Size(240, 180));
+ await close(tester, c);
+ });
+
+ testWidgets('no link, no picture, even when it is cached', (tester) async {
+ await tester.runAsync(
+ () => superTabImageCache.keep('a1', Uint8List(8), const Size(10, 10)),
+ );
+ final c = await show(
+ tester,
+ files: [
+ {..._file('a1', 'shot.png', 'image/png'), 'unlinked': true},
+ ],
+ // The server's answer for a reader who may no longer read it; an
+ // error of the ask itself is asked again (file_links.dart).
+ fileLink: (_) => throw const SuperTabFailure(
+ 'FORBIDDEN',
+ 'no longer yours',
+ statusCode: 403,
+ ),
+ );
+
+ expect(find.text('shot.png can’t be shown here.'), findsOneWidget);
+ expect(asked, isEmpty);
+ await close(tester, c);
+ });
+
+ testWidgets(
+ 'the chat asks for it at its size, the viewer for the original',
+ (tester) async {
+ pictures['shot.png'] = await _png(tester, 720, 360);
+ final c = await show(
+ tester,
+ files: [_file('a1', 'shot.png', 'image/png')],
+ );
+ expect(asked.map((p) => (p.fileId, p.side)).toSet(), {('a1', 360.0)});
+
+ await tester.tap(
+ find.byKey(const ValueKey('super-attachment-inline:a1')),
+ );
+ await tester.pumpAndSettle();
+
+ expect(asked.last.fileId, 'a1');
+ expect(asked.last.side, isNull);
+ await close(tester, c);
+ },
+ );
});
group('the viewer over the chat', () {
diff --git a/desktop/test/super_tab_thumbnails_test.dart b/desktop/test/super_tab_thumbnails_test.dart
index 663cf1992..91d8424c5 100644
--- a/desktop/test/super_tab_thumbnails_test.dart
+++ b/desktop/test/super_tab_thumbnails_test.dart
@@ -11,6 +11,7 @@ import 'package:flutter_test/flutter_test.dart';
import 'package:harness/super_tabs/attachment_viewer.dart';
import 'package:harness/super_tabs/controller.dart';
import 'package:harness/super_tabs/file_links.dart';
+import 'package:harness/super_tabs/image_cache.dart';
import 'package:harness/super_tabs/model.dart';
import 'package:harness/super_tabs/view.dart';
@@ -73,16 +74,16 @@ Future<Uint8List> _png(WidgetTester tester) async =>
void main() {
late List<Uri> drawn;
late Map<String, Uint8List> pictures;
- late ImageProvider Function(Uri) image;
+ late ImageProvider Function(AttachmentImage) image;
setUp(() {
drawn = [];
pictures = {};
image = attachmentImage;
superTabFileClock = () => _now;
- attachmentImage = (url) {
- drawn.add(url);
- return MemoryImage(pictures[url.toString()] ?? Uint8List(3));
+ attachmentImage = (picture) {
+ drawn.add(picture.url);
+ return MemoryImage(pictures[picture.url.toString()] ?? Uint8List(3));
};
});
tearDown(() {
@@ -238,4 +239,74 @@ void main() {
await close(tester, c);
});
});
+
+ // Task #3178 under #3177: the thumbnail and the original are two pictures
+ // of one file, kept apart on disk, and the placeholder has the picture's
+ // shape before anything loads.
+ group('the picture cache', () {
+ late List<Uri> fetched;
+ late Map<String, Uint8List> served;
+ late Future<Uint8List> Function(Uri url, {int? maxBytes}) fetcher;
+ late SuperTabImageCache cache;
+
+ setUp(() {
+ fetched = [];
+ served = {};
+ fetcher = attachmentFetcher;
+ cache = superTabImageCache;
+ superTabImageCache = SuperTabImageCache(MemoryImageShelf());
+ // The real loader, through the cache; only the download is faked.
+ attachmentImage = (picture) => picture;
+ attachmentFetcher = (url, {maxBytes}) async {
+ fetched.add(url);
+ final bytes = served[url.toString()];
+ if (bytes == null) return Completer<Uint8List>().future;
+ return bytes;
+ };
+ });
+ tearDown(() {
+ attachmentFetcher = fetcher;
+ superTabImageCache = cache;
+ PaintingBinding.instance.imageCache
+ ..clear()
+ ..clearLiveImages();
+ });
+
+ testWidgets('the viewer downloads the original, not the kept thumbnail', (
+ tester,
+ ) async {
+ served[_signed(_thumbKey)] = await _png(tester);
+ served[_signed(_original)] = await _png(tester);
+ final (_, c) = await show(tester, _picture());
+ expect(fetched, [Uri.parse(_signed(_thumbKey))]);
+
+ await tester.tap(inline);
+ await tester.pumpAndSettle();
+ await tester.runAsync(() => Future<void>.delayed(Durations.short2));
+ await tester.pumpAndSettle();
+
+ expect(fetched, [
+ Uri.parse(_signed(_thumbKey)),
+ Uri.parse(_signed(_original)),
+ ]);
+ await tester.tap(find.byKey(const ValueKey('super-image-close')));
+ await tester.pumpAndSettle();
+ await close(tester, c);
+ });
+
+ testWidgets('the placeholder has the shape the server sent', (
+ tester,
+ ) async {
+ // Nothing served: the thumbnail is still loading.
+ final (_, c) = await show(tester, _picture());
+
+ final placeholder = find.byKey(
+ const ValueKey('super-attachment-placeholder:p1'),
+ );
+ expect(placeholder, findsOneWidget);
+ // 4000 × 3000 shown at most 360 each way.
+ expect(tester.getSize(placeholder), const Size(360, 270));
+ await close(tester, c);
+ });
+ });
}
diff --git a/docs/plans/2026-11-05-chat-image-cache-plan.md b/docs/plans/2026-11-05-chat-image-cache-plan.md
new file mode 100644
index 000000000..1da088f9e
--- /dev/null
+++ b/docs/plans/2026-11-05-chat-image-cache-plan.md
@@ -0,0 +1,204 @@
+# Chat images cached by file id Implementation Plan
+
+> **For agentic workers:** this plan is carried out by its Engineer in this one session, task by task, test first
+> (superpowers:test-driven-development), as the project's instructions say. Steps use checkbox (`- [ ]`) syntax.
+
+**Goal:** A chat picture is downloaded once per file, kept on disk under a size cap, decoded at the size the chat shows
+it, and its placeholder already has its shape (task #3178, Huy's speed plan B1).
+
+**Architecture:** `AttachmentImage` (attachment_viewer.dart) is keyed by the file's id and the pixel size it is decoded
+at, not by its short-lived link, so a fresh link for the same file finds the picture Flutter already holds. Under it, a
+new `SuperTabImageCache` keeps each file's bytes on disk (`~/.harness/desktop-app/image-cache/`), one file per picture
+named by its id and its width and height, least recently shown out first above 200 MB; the web keeps them in memory.
+The chat asks for a decode no larger than 360 points at the screen's pixel ratio; the full-screen viewer asks for the
+original. Sign-out and a session that ends clear the cache (`AppState._clearAccountWorkspace`).
+
+**Tech Stack:** Flutter 3.47.2 / Dart 3.13, `dart:io` files, `ImageDecoderCallback.getTargetSize`, flutter_test with a
+memory shelf.
+
+**Spec:** task #3178's brief (Goal, Changes, Constraints, Checks), copied into the pull request body. #3177 (server
+thumbnails with width and height) is a separate task and is not built here.
+
+## Global Constraints
+
+- Owns `desktop/lib/super_tabs`; the only line outside it is the cache clear in `desktop/lib/state/app_state.dart`.
+- The cache holds only what this person may read: a picture is drawn from it only once the app holds a link that opens
+ now (the message's own, or a fresh one the server granted); it is cleared on sign-out.
+- Desktop tests use a memory shelf and a fake sign-in; nothing signs the real CLI out. Temp folders only through
+ `Directory.systemTemp.createTemp` (a `mktemp -d` equivalent).
+- No setting or on/off switch (ENGINEERING.md §1). No new dependency.
+- Network reads stay through `readAttachment` / `attachmentFetcher` (no redirect, 10 MB cap) and, once #3125 merges,
+ through its timed `readPicture`, so task A's image marks count only real downloads.
+- PR body first line: `Requested by phamngochuy.1989 through Harness.`
+
+## Design (docs/feature-design-rules.md)
+
+1. Growth: each picture file is deleted by eviction (least recently shown first, above
+ `kSuperTabImageCacheBytes` = 200 MB on disk, 64 MB in memory on the web), by sign-out or a session that ends, and
+ by the next open of the cache for a `.part` left by a crash. Limit: 200 MB per computer account.
+2. Concurrency: no index file. A write goes to its own `<name>.<pid>.<micros>.part` and is renamed into place, so two
+ windows never see half a picture; eviction lists the folder again before deleting, and a file another window
+ already deleted is skipped. A download that finishes after a clear is not written (a generation counter).
+3. Read cost: a chat image reads its bytes from disk once per launch, then from Flutter's memory cache; the network
+ only on a miss. The folder is listed once per launch (names and sizes, no contents).
+4. Scale: at 10x pictures the cap holds the disk; the first warning is the hit rate falling, seen in task A's
+ image marks (downloads per chat open).
+5. Compatibility: no wire change; older servers' unsigned links still load (same fetch path).
+6. Migration and rollback: nothing to migrate. Rolling back leaves `image-cache/` unused on disk until the folder is
+ removed by hand or by a later sign-out from a build that has it; it holds at most 200 MB.
+7. Audience: the server enforces it: a picture is read from the cache only inside a load that began with a link the
+ server signed for this reader in this session. Cleared on sign-out and session end. Folder 0700, files 0600.
+8. Identity: N/A because nothing runs as anyone; it is a local cache of the signed-in person's own reads.
+9. Failure: a disk read or write that fails logs `super-tabs image cache ...` (no id, no path) and the picture loads
+ from the network as today; a failed download shows "can't be shown" as today, and is not cached.
+10. Platforms: macOS, Linux and Windows keep a disk cache; the web keeps a memory one (no Harness home); iOS and
+ Android builds of this code use the app's container through `HarnessFileStore.defaultDirectoryPath`.
+
+## Review Focus
+
+- A link that ended under a picture, then a fresh one: the picture must load, not stay broken because its file-id
+ key holds the failed load (Task 2 test `a failed load is not kept`).
+- A person who may no longer read a file (fresh link refused) with the file cached: it must say it can't be shown,
+ not draw from disk (Task 3 test `no link, no picture, even when cached`).
+- Two windows writing the same picture, and a crash mid-write: no half picture is ever drawn (Task 1 test
+ `a write left half done is never read`).
+- Sign-out while a picture is downloading: it is not written after the clear (Task 4 test).
+- A tiny picture (smaller than 360 points): drawn at its own size, not blown up (Task 2 test `a small picture keeps
+ its size`).
+
+---
+
+### Task 1: The cache: shelf, cap, last-shown order, shapes, clear
+
+**Files:**
+- Create: `desktop/lib/super_tabs/image_cache.dart`
+- Test: `desktop/test/super_tab_image_cache_test.dart`
+
+**Interfaces:**
+- Produces:
+ - `const kSuperTabImageCacheBytes = 200 * 1024 * 1024;`
+ - `abstract interface class SuperTabImageShelf` with `Future<List<SuperTabShelfEntry>> list()`,
+ `Future<Uint8List?> read(String name)`, `Future<void> write(String name, Uint8List bytes)`,
+ `Future<void> touch(String name)`, `Future<void> delete(String name)`, `Future<void> clear()`;
+ `SuperTabShelfEntry({required String name, required int bytes, required DateTime usedAt})`.
+ - `class MemoryImageShelf implements SuperTabImageShelf` (tests, web) and
+ `class DirectoryImageShelf implements SuperTabImageShelf` (`Directory`; private 0700/0600, temp-and-rename writes,
+ `.part` files removed by `list`).
+ - `class SuperTabImageCache` — `SuperTabImageCache(SuperTabImageShelf shelf, {int capBytes})`;
+ `Future<Uint8List?> read(String fileId)`;
+ `Future<void> keep(String fileId, Uint8List bytes, Size shape, {int? generation})`;
+ `Future<void> drop(String fileId)` (a kept picture that does not decode);
+ `Size? shapeOf(String fileId)` (synchronous, null until the folder is listed); `Future<void> get ready`;
+ `Future<void> clear()`; `int get generation`.
+ - `SuperTabImageCache superTabImageCache` (`@visibleForTesting` settable): disk shelf off the web, memory on it.
+- File name: `<fileId>~<width>x<height>`; a file id outside `[A-Za-z0-9_-]{1,128}` is never kept.
+
+- [ ] **Step 1: Write the failing tests** (`super_tab_image_cache_test.dart`), each on a `MemoryImageShelf` unless named:
+ - `keeps a picture by its file id`: `keep('a1', bytes, Size(800, 600))` then `read('a1')` equals bytes and
+ `shapeOf('a1') == Size(800, 600)`.
+ - `stays under its cap, least recently shown out first`: cap 100; keep a1 (40), a2 (40), read a1, keep a3 (40) →
+ `read('a2')` null, a1 and a3 kept, `list()` bytes sum ≤ 100.
+ - `a picture larger than the cap is not kept`.
+ - `clear empties it and forgets shapes`: after `clear()`, `read` null, `shapeOf` null, `generation` advanced.
+ - `reads the shapes kept by an earlier launch`: a second cache over the same shelf answers `shapeOf` after `ready`.
+ - `a file id that is not a plain id is never kept`: `keep('../x', …)` writes nothing.
+ - `a write left half done is never read` (`DirectoryImageShelf` in a temp folder): a `.part` file in it is not
+ listed, is deleted by `list()`, and the folder mode is 0700 where POSIX modes are supported.
+- [ ] **Step 2: Run** `flutter test test/super_tab_image_cache_test.dart` — FAIL (no `image_cache.dart`).
+- [ ] **Step 3: Implement** `image_cache.dart`. `keep` writes after the read it came from (no await by the caller),
+ skipped when `generation` moved since the caller's load began (the caller passes the `generation` it read when the
+ load began). Eviction lists the shelf again, sorts by `usedAt`, deletes oldest until ≤ cap.
+ Failures log through `appLog.warn('super-tabs', 'image cache …')` with no id or path.
+- [ ] **Step 4: Run** the same command — PASS.
+- [ ] **Step 5: Commit** test first (`test(desktop): chat image cache …` — failing), then code.
+
+### Task 2: The picture keyed by file id and decoded at the size shown
+
+**Files:**
+- Modify: `desktop/lib/super_tabs/attachment_viewer.dart` (`AttachmentImage`, `attachmentImage`, `attachmentPicture`)
+- Modify: the tests that set `attachmentImage` (`super_tab_message_media_test.dart`,
+ `super_tab_message_rows_shots_test.dart`, `super_tab_image_viewer_shots_test.dart`, `super_tab_file_links_test.dart`,
+ `super_tab_image_viewer_test.dart`) to the new hook type
+- Test: `desktop/test/super_tab_attachment_image_test.dart`
+
+**Interfaces:**
+- Consumes: `superTabImageCache` (Task 1).
+- Produces:
+ - `AttachmentImage(Uri url, {required String fileId, double? side})` — `side` null decodes the original; a key of
+ `(fileId, pixels)` where `pixels = (side * devicePixelRatio).round()` from `obtainKey`'s configuration.
+ - `ImageProvider Function(AttachmentImage picture) attachmentImage` (`@visibleForTesting`, default returns
+ `picture`); `ImageProvider attachmentPicture(AttachmentImage picture)`.
+
+- [ ] **Step 1: Write the failing tests** in `super_tab_attachment_image_test.dart` (its local server, a memory cache):
+ - `a new signed link for the same file id doesn't download again`: resolve `AttachmentImage(link('/a.png?sig=1'),
+ fileId: 'a1', side: 360)`, then `…?sig=2` for `a1` → the server answered once; after `imageCache.clear()` a third
+ link still makes no request (the disk cache answers).
+ - `decodes no larger than the chat shows it`: a 2000×1000 PNG at `side: 360`, pixel ratio 2 → image width 720; the
+ same file with `side: null` → width 2000; `shapeOf('a1') == Size(2000, 1000)`.
+ - `a small picture keeps its size`: a 1×1 PNG at `side: 360` → width 1.
+ - `a failed load is not kept`: first link answers 403, a second link for the same id answers the PNG → an image.
+ - The redirect tests stay as they are (now with `fileId`).
+- [ ] **Step 2: Run** `flutter test test/super_tab_attachment_image_test.dart` — FAIL (no `fileId`).
+- [ ] **Step 3: Implement.** `loadImage`: `superTabImageCache.read(fileId)` → else `readAttachment(url, maxBytes:
+ kSuperTabFormAttachmentMaxBytes)`; decode through `decode(buffer, getTargetSize: …)`, which records the intrinsic
+ size and returns a `TargetImageSize` with only the longer side set when it is over `pixels`; then `keep` the bytes
+ with that shape. On a failure, `PaintingBinding.instance.imageCache.evict(key)` before rethrowing, so a fresh link
+ loads anew. `==`/`hashCode` on the key, not the link.
+- [ ] **Step 4: Run** the test file and every test file changed in Files — PASS.
+- [ ] **Step 5: Commit** test first, then code.
+
+### Task 3: The chat shows the picture's shape before it arrives
+
+**Files:**
+- Modify: `desktop/lib/super_tabs/attachment_image.dart` (`SuperTabInlineImage`, `SuperTabImageViewer._picture`)
+- Test: `desktop/test/super_tab_message_media_test.dart`
+
+**Interfaces:**
+- Consumes: `AttachmentImage(url, fileId:, side:)`, `superTabImageCache.shapeOf`, `.ready` (Tasks 1–2).
+
+- [ ] **Step 1: Write the failing tests** in `super_tab_message_media_test.dart`:
+ - `a picture whose shape is known holds its place at that shape`: cache knows `a1` is 1600×900; while its bytes
+ have not arrived, the placeholder is 360×202.5 (fitted in 360×360, as the picture will be), and the same once
+ drawn.
+ - `an unknown shape keeps today's placeholder` (240×180).
+ - `no link, no picture, even when cached`: `a1` cached, its link ended and a fresh one refused as gone → "can't be
+ shown here", and nothing read from the cache.
+ - `the chat asks for the picture at its size, the viewer for the original`: the hook sees `side: 360` from the chat
+ and `side: null` from the full-screen viewer.
+- [ ] **Step 2: Run** `flutter test test/super_tab_message_media_test.dart` — FAIL.
+- [ ] **Step 3: Implement.** `_loading()` takes the fitted size when `shapeOf` knows it; when the cache is not
+ `ready` yet, the state awaits it once and rebuilds. The inline `Image` gets `side: SuperTabInlineImage.maxSide`;
+ the viewer's gets none.
+- [ ] **Step 4: Run** it and `super_tab_image_viewer_test.dart`, `super_tab_file_links_test.dart` — PASS.
+- [ ] **Step 5: Commit** test first, then code.
+
+### Task 4: Sign-out clears it
+
+**Files:**
+- Modify: `desktop/lib/state/app_state.dart` (`_clearAccountWorkspace`)
+- Modify: `desktop/lib/super_tabs/image_cache.dart` (clear also evicts Flutter's memory copies it made)
+- Test: `desktop/test/super_tab_image_cache_sign_out_test.dart`
+
+- [ ] **Step 1: Write the failing tests** with `AppState` on a memory store and a fake sign-in (as the existing
+ sign-out tests do), and a memory cache holding `a1`:
+ - `signing out clears the picture cache`: after `logout()`, `read('a1')` null and Flutter's image cache holds no
+ picture of `a1`.
+ - `a session that ends clears it too` (`_signedOutAtRuntime` path, as its existing test triggers it).
+ - `a picture arriving after sign-out is not kept` (cache level): a load misses, `clear()`, then its `keep` → nothing
+ written.
+- [ ] **Step 2: Run** — FAIL.
+- [ ] **Step 3: Implement**: `unawaited(superTabImageCache.clear())` in `_clearAccountWorkspace`.
+- [ ] **Step 4: Run** it and the sign-out tests of `app_state` that exercise `logout` — PASS.
+- [ ] **Step 5: Commit** test first, then code.
+
+### Task 5: Before and after numbers
+
+**Files:**
+- Test: `desktop/test/benchmarks/chat_image_benchmark.dart` (a measurement; not a `_test` file, so the suite skips
+ it)
+
+- [ ] **Step 1:** An image-heavy chat on a local server (30 screenshot-like pictures, 2400×1600, about 0.5 MB each): open it, scroll it,
+ reopen it with fresh links, relaunch (new memory cache, same shelf). Record downloads, bytes downloaded, and decoded
+ bytes held, on main (before) and on this branch (after), with task A's image marks (#3125) when it has merged.
+- [ ] **Step 2:** Post the table in the task and the pull request; a run on a real Mac against production with task
+ A's tool goes in the test step.