fix: cache project favicons across web and mobile

[gabrielelpidio]

What Changed

• Added versioned project favicon asset URLs based on file modification time and size.
• Added shared cache-key generation scoped to environment, workspace, and favicon revision.
• Enabled persistent favicon caching on mobile and reused loaded favicon URLs on web.
• Added coverage for stable URLs, cache identity, and favicon updates.

Why

Signed asset URLs change as tokens rotate, which caused browsers and mobile clients to reload unchanged project favicons. Versioning the asset by the favicon's file metadata provides a stable cache identity while still invalidating the cache when the favicon changes.

Checklist

• This PR is small and focused
• I explained what changed and why
• I included before/after screenshots for any UI changes
• I included a video for animation/interaction changes

---

Note

Medium Risk
Changes signed asset URL shape and expiry for project favicons plus client caching behavior; scope is limited to favicon assets and is covered by new tests, but incorrect hashing or cache logic could show stale or missing icons.

Overview
Signed project favicon URLs change whenever tokens rotate, which forced web and mobile to reload unchanged icons. This PR makes asset filenames content-addressed (SHA-256 hash in the path) and aligns favicon token expiry to 30-minute buckets, so the same file keeps a stable URL identity across re-issues.

Shared getProjectFaviconCacheKey ties cache identity to environment, workspace root, and the versioned filename—not the signed token.

Web keeps showing the last successfully loaded favicon while a new URL loads in a hidden <img>, and only drops to the folder icon when the displayed image errors.

Mobile adds a small request lifecycle cache so stale onLoad/onError from superseded URLs are ignored, and wires expo-image with cacheKey, recyclingKey, and memory-disk policy.

Tests cover bucketed expiry, hash-based filenames, cache-key stability, refresh/fallback behavior, and mobile supersession.

^{Reviewed by Cursor Bugbot for commit 0d0779c. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Cache project favicons by content-hash key across web and mobile

• Adds getProjectFaviconCacheKey in packages/shared/src/projectFavicon.ts to derive a stable cache identity from environmentId, workspace root, and a versioned filename, independent of transient signed tokens.
• Server-side favicon URLs now include a SHA-256 content-hash in the filename and use bucketed 30-minute expiry, so repeated calls return the same URL until file content changes.
• Web's ProjectFaviconImage holds the previous image on screen while preloading a refreshed URL, only swapping on success and guarding error handlers by src match.
• Mobile's ProjectFaviconImage replaces a local Set-based cache with coordinated per-cacheKey request tracking, ignoring load/error callbacks from superseded URLs.
• Behavioral Change: favicon token expiry on the server is now aligned to 30-minute buckets rather than the general token TTL, which may extend the lifetime of issued URLs.

^{Macroscope summarized 0d0779c.}

Summary by CodeRabbit

• Bug Fixes
  • Improved project favicon caching with deterministic cache keys and smarter reuse, so refreshes can retain the last working favicon and only discard it when the matching request fails.
  • Updated server-issued project-favicon URL expiry and filename generation to be time-bucketed and content-hashed, producing stable signed fallback behavior.
• Tests
  • Expanded server, web, shared, and mobile test coverage for cache-key identity, refresh/failure fallback behavior, request supersession/eviction, and bucketed expiry plus filename signing stability.

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces a new content-based caching mechanism for project favicons across web and mobile, including SHA-256 versioning on the server, new cache key generation, and request lifecycle tracking. The scope of new logic and behavioral changes across multiple platforms warrants human review.

^{You can customize Macroscope's approvability policy. Learn more.}

[coderabbitai]

📝 Walkthrough

Walkthrough

Project favicon asset URLs now include content revisions, with shared cache-key derivation and updated web and mobile loading behavior. Web rendering preserves valid images across refresh failures, while mobile image caching uses project-specific keys.

Changes

Project favicon refresh flow

Layer / File(s)	Summary
Versioned favicon asset issuance apps/server/src/assets/AssetAccess.ts, apps/server/src/assets/AssetAccess.test.ts	Project favicon capabilities use bucketed expiration and SHA-256 content revisions; tests cover stable URLs, changed revisions, and expiry bucketing.
Shared favicon cache identity packages/shared/src/projectFavicon.ts, packages/shared/src/projectFavicon.test.ts	A shared helper derives cache keys from environment, workspace, and the versioned URL filename, with coverage for matching and differing identities.
Web favicon loading and fallback apps/web/src/components/ProjectFavicon.tsx, apps/web/src/components/ProjectFavicon.test.tsx	The component caches displayed sources by cache key, preloads refreshed URLs, invalidates failed entries, and preserves valid images through refresh errors.
Mobile request cache lifecycle apps/mobile/src/components/projectFaviconCache.ts, apps/mobile/src/components/projectFaviconCache.test.ts	Mobile request objects track active URLs by cache key, ignore stale callbacks, restore remaining active revisions, and bound remembered entries.
Mobile image request integration apps/mobile/src/components/ProjectFavicon.tsx	Mobile rendering derives cache identities, manages active requests, and passes cache and recycling metadata to expo-image.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant AssetAccess
  participant ProjectFavicon
  participant ProjectFaviconImage
  participant ImageLoader
  AssetAccess->>ProjectFavicon: return content-versioned favicon URL
  ProjectFavicon->>ProjectFaviconImage: provide cacheKey and favicon URL
  ProjectFaviconImage->>ImageLoader: begin active image request
  ImageLoader-->>ProjectFaviconImage: report load or failure
  ProjectFaviconImage->>ProjectFaviconImage: record or invalidate cache entry

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title is concise and accurately summarizes the main change: cross-platform favicon caching.
Description check	✅ Passed	The description includes the required What Changed, Why, and Checklist sections and is mostly complete.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch t3code/cache-favicons-web-mobile

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[gabrielelpidio]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

packages/shared/src/projectFavicon.ts (1)

7-7: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Prefer the inferred return type.

The return annotation is redundant here.

Proposed change

-): string {
+) {

As per coding guidelines, “Prefer inferred types over explicit annotations and do not use any.”

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/shared/src/projectFavicon.ts` at line 7, Remove the explicit string
return annotation from the function in projectFavicon.ts and let TypeScript
infer its return type, while leaving the function implementation unchanged.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@apps/server/src/assets/AssetAccess.test.ts`:
- Around line 223-228: Update the test around issueAssetUrl to provide the
repository’s controllable Clock test layer and freeze the timestamp before both
project-favicon URL calls. Ensure both invocations run under the same fixed
clock value so the existing equality assertion remains deterministic.

In `@apps/server/src/assets/AssetAccess.ts`:
- Around line 344-346: Update the favicon revision construction in
AssetAccess.ts around modifiedAt/revision to use a content digest or durable
content version, ensuring every content change—including equal-size
updates—produces a new filename. In AssetAccess.test.ts lines 238-244, add a
controlled equal-size content replacement and assert that the generated revision
filename changes.

---

Nitpick comments:
In `@packages/shared/src/projectFavicon.ts`:
- Line 7: Remove the explicit string return annotation from the function in
projectFavicon.ts and let TypeScript infer its return type, while leaving the
function implementation unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: e38efc06-abce-43f3-bbf0-a91f691d3cae

📥 Commits

Reviewing files that changed from the base of the PR and between 6efcf3e and f77304e.

📒 Files selected for processing (7)

• apps/mobile/src/components/ProjectFavicon.tsx
• apps/server/src/assets/AssetAccess.test.ts
• apps/server/src/assets/AssetAccess.ts
• apps/web/src/components/ProjectFavicon.test.tsx
• apps/web/src/components/ProjectFavicon.tsx
• packages/shared/src/projectFavicon.test.ts
• packages/shared/src/projectFavicon.ts

[gabrielelpidio]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

apps/server/src/assets/AssetAccess.ts (1)

173-173: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick win

Narrow the Crypto service dependency to favicon issuance.

Line 173 resolves Crypto.Crypto before the resource switch, so workspace-file and attachment URL issuance now requires a Crypto layer even though those branches never hash bytes. Move the lookup into the project-favicon branch, after confirming a canonical favicon exists.

Proposed adjustment

-  const crypto = yield* Crypto.Crypto;
...
      if (relativePath && canonicalFaviconPath) {
+        const crypto = yield* Crypto.Crypto;

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/server/src/assets/AssetAccess.ts` at line 173, Move the Crypto.Crypto
service lookup from the shared resource-issuance setup into the project-favicon
branch in AssetAccess, resolving it only after confirming a canonical favicon
exists. Keep workspace-file and attachment URL issuance independent of the
Crypto service.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@apps/mobile/src/components/ProjectFavicon.tsx`:
- Around line 104-107: Update the ProjectFavicon error handling around the image
URL/request generation so onError deletes the shared loadedFaviconKeys entry
only when the failed request still matches the current generation; ignore stale
errors after a newer revision has loaded. Add a regression test covering a stale
error arriving after the same revision succeeds and verify it does not evict the
shared key or trigger fallback/reload flicker.

---

Nitpick comments:
In `@apps/server/src/assets/AssetAccess.ts`:
- Line 173: Move the Crypto.Crypto service lookup from the shared
resource-issuance setup into the project-favicon branch in AssetAccess,
resolving it only after confirming a canonical favicon exists. Keep
workspace-file and attachment URL issuance independent of the Crypto service.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: d67bccd0-2fd2-470f-849f-a8baa9c88d9b

📥 Commits

Reviewing files that changed from the base of the PR and between f77304e and 275cf65.

📒 Files selected for processing (4)

• apps/mobile/src/components/ProjectFavicon.tsx
• apps/server/src/assets/AssetAccess.test.ts
• apps/server/src/assets/AssetAccess.ts
• packages/shared/src/projectFavicon.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/shared/src/projectFavicon.ts

[gabrielelpidio]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

apps/server/src/assets/AssetAccess.ts (1)

177-181: 🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

Compute the favicon expiry after the hashing work.

The expiry is bucketed from the clock before path resolution, file I/O, SHA-256 hashing, secret loading, and signing. A request started in the final milliseconds of a bucket can therefore return an already-expired token. Recompute the bucket from a fresh clock reading immediately before building/signing the claims, and add a bucket-boundary regression test.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/server/src/assets/AssetAccess.ts` around lines 177 - 181, Move the
project-favicon expiresAt calculation out of the initial timestamp section and
recompute it from a fresh clock reading immediately before constructing and
signing the claims, after path resolution, I/O, hashing, and secret loading
complete. Preserve the existing non-favicon TTL behavior, and add a regression
test covering a request that crosses a favicon token-bucket boundary.

♻️ Duplicate comments (1)

apps/mobile/src/components/ProjectFavicon.tsx (1)

104-110: 🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win

Ignore callbacks from superseded favicon requests.

key={props.faviconUrl} remounts the native image, but an old native callback may still arrive after the URL changes. If that old request errors before the refreshed URL loads, markProjectFaviconFailed evicts the still-valid entry and this component shows the fallback. A late old onLoad can also overwrite the recorded URL. Track the latest requested URL/generation and guard both callbacks; add a regression covering an old callback arriving before the new URL loads.

Proposed guard

+  const latestFaviconUrl = useRef(props.faviconUrl);
+  latestFaviconUrl.current = props.faviconUrl;
+
           onLoad={() => {
+            if (latestFaviconUrl.current !== props.faviconUrl) return;
             markProjectFaviconLoaded(props.cacheKey, props.faviconUrl);
             setStatus("loaded");
           }}
           onError={() => {
+            if (latestFaviconUrl.current !== props.faviconUrl) return;
             if (!markProjectFaviconFailed(props.cacheKey, props.faviconUrl)) return;
             setStatus("error");
           }}

Import useRef and add a component-level regression test.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/mobile/src/components/ProjectFavicon.tsx` around lines 104 - 110, Update
ProjectFavicon’s load and error callbacks to track the latest requested favicon
URL or request generation via useRef, and ignore callbacks from superseded
native image requests before mutating cache state or component status. Ensure
only callbacks for the current props.faviconUrl can call
markProjectFaviconLoaded, markProjectFaviconFailed, or setStatus, and add a
regression test covering an old callback arriving before the new URL loads.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@apps/server/src/assets/AssetAccess.ts`:
- Around line 177-181: Move the project-favicon expiresAt calculation out of the
initial timestamp section and recompute it from a fresh clock reading
immediately before constructing and signing the claims, after path resolution,
I/O, hashing, and secret loading complete. Preserve the existing non-favicon TTL
behavior, and add a regression test covering a request that crosses a favicon
token-bucket boundary.

---

Duplicate comments:
In `@apps/mobile/src/components/ProjectFavicon.tsx`:
- Around line 104-110: Update ProjectFavicon’s load and error callbacks to track
the latest requested favicon URL or request generation via useRef, and ignore
callbacks from superseded native image requests before mutating cache state or
component status. Ensure only callbacks for the current props.faviconUrl can
call markProjectFaviconLoaded, markProjectFaviconFailed, or setStatus, and add a
regression test covering an old callback arriving before the new URL loads.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 1d0b1fa4-5e10-4096-aaae-1092add5aef9

📥 Commits

Reviewing files that changed from the base of the PR and between 275cf65 and fb71493.

📒 Files selected for processing (4)

• apps/mobile/src/components/ProjectFavicon.tsx
• apps/mobile/src/components/projectFaviconCache.test.ts
• apps/mobile/src/components/projectFaviconCache.ts
• apps/server/src/assets/AssetAccess.ts

[gabrielelpidio]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[gabrielelpidio]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 6ada303. Configure here.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@apps/mobile/src/components/projectFaviconCache.ts`:
- Around line 6-7: Bound the module-level bookkeeping in currentFaviconUrls and
loadedFaviconKeys so favicon revision updates do not accumulate indefinitely.
Evict superseded revision entries only when they are no longer active or needed
by concurrent requests, preserving in-flight request tracking and current
favicon behavior.
- Around line 13-17: Update beginProjectFaviconRequest and the corresponding
onLoad/onError stale-callback handling so URL-bearing requests cannot bypass
validation when cacheKey is null. Prefer enforcing a non-null cacheKey for
requests with faviconUrl; otherwise add per-request URL/session tracking for
uncached images, and add a regression test covering a null-key A→B remount where
the stale A callback cannot update B’s status.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: c81f8034-3eb9-41ed-a49b-06c1c4655b4b

📥 Commits

Reviewing files that changed from the base of the PR and between 6ca94bf and 6ada303.

📒 Files selected for processing (3)

• apps/mobile/src/components/ProjectFavicon.tsx
• apps/mobile/src/components/projectFaviconCache.test.ts
• apps/mobile/src/components/projectFaviconCache.ts

[gabrielelpidio]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[gabrielelpidio]

@coderabbitai resume

[coderabbitai]

✅ Action performed

Reviews resumed.