Docs: refresh cache semantics after PR #166 (1d fresh + 7d SWR) - #169
Merged
Conversation
PR #166 swapped the deterministic cache header from 1-year immutable to 1-day fresh + 7-day stale-while-revalidate. The ?v= versioning story we shipped in PRs #164–#165 assumed the old immutable headers, so the docs overclaimed how long stale animations linger. Updates: - api.mdx intro / embedding blurb / caching section reflect the SWR window (≤ 1 day fresh, up to 8 days long-tail). - Animation-versioning section frames ?v=N as the escape hatch for instant propagation rather than "the only way out of an immutable trap." - openapi.json descriptions match. - Root CLAUDE.md points agents at DETERMINISTIC_CACHE in app/src/lib/api.ts. No code changes — /frames route was already switched to DETERMINISTIC_CACHE in PR #168. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
pablostanley
added a commit
that referenced
this pull request
Apr 20, 2026
… cache policy
Rolls the important stuff from this long session into the living docs
so next-agent (or next-me) doesn't have to reread the whole thread.
CLAUDE.md
- **Key conventions**: replace the old 8-frame-bounce line with the
16-tick super-loop model; add sub-animation `kind` (static/blink/
sequence) + `resolveFrameIndex` as the one source for frame picks;
document `TOTAL_COMBOS_LABEL` as the single-source for the count;
add the keydown `hasModifier` rule (earned from the ⌘R bug).
- **Adding new parts**: split static vs animated workflows. Static
is flat PNG + stitcher copy-through. Animated uses subdir layouts
(blink: open/closed pair, sequence: numbered) that the stitcher
detects automatically; updated the parts.ts entry shape
(`'name'` vs `{ name, frames, kind }`).
- **npm**: drop the stale "CLI token caveat" note — first-publish
is done, token allow-list extended.
- **API**: refresh the endpoint list (frames metadata, batch, palette
+ bg params); document the 1d fresh / 7d SWR cache policy and the
same-origin rate-limit bypass.
ROADMAP.md
- Appends Done entries for PR #158 (⌘R guard), #160 (SW bump),
#162 (TOTAL_COMBOS dedupe), #166/#168/#169 (cache revalidate),
and #170 (browse 429s). Each entry includes the "why we needed it"
so future readers see the failure mode, not just the fix.
Memory (not in this commit; lives outside the repo):
- New `feedback_keyboard_modifier_guard.md` — the ⌘R lesson promoted
to a rule.
- New `project_animation_infra.md` — the sub-animation mental model.
- Updated `project_npm_published.md` with current versions of core /
react / cli.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
pablostanley
added a commit
that referenced
this pull request
Apr 20, 2026
… cache policy (#171) Rolls the important stuff from this long session into the living docs so next-agent (or next-me) doesn't have to reread the whole thread. CLAUDE.md - **Key conventions**: replace the old 8-frame-bounce line with the 16-tick super-loop model; add sub-animation `kind` (static/blink/ sequence) + `resolveFrameIndex` as the one source for frame picks; document `TOTAL_COMBOS_LABEL` as the single-source for the count; add the keydown `hasModifier` rule (earned from the ⌘R bug). - **Adding new parts**: split static vs animated workflows. Static is flat PNG + stitcher copy-through. Animated uses subdir layouts (blink: open/closed pair, sequence: numbered) that the stitcher detects automatically; updated the parts.ts entry shape (`'name'` vs `{ name, frames, kind }`). - **npm**: drop the stale "CLI token caveat" note — first-publish is done, token allow-list extended. - **API**: refresh the endpoint list (frames metadata, batch, palette + bg params); document the 1d fresh / 7d SWR cache policy and the same-origin rate-limit bypass. ROADMAP.md - Appends Done entries for PR #158 (⌘R guard), #160 (SW bump), #162 (TOTAL_COMBOS dedupe), #166/#168/#169 (cache revalidate), and #170 (browse 429s). Each entry includes the "why we needed it" so future readers see the failure mode, not just the fix. Memory (not in this commit; lives outside the repo): - New `feedback_keyboard_modifier_guard.md` — the ⌘R lesson promoted to a rule. - New `project_animation_infra.md` — the sub-animation mental model. - Updated `project_npm_published.md` with current versions of core / react / cli. Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
?v=(PRs Anim: ANIM_VERSION + ?v= cache-bust on animated URLs #164, API: GET /api/pixabot/{id}/frames — animation metadata endpoint #165) still described the old immutable behavior, making the versioning story more alarming than it actually is.api.mdx,openapi.json, and the rootCLAUDE.mdwith the currentDETERMINISTIC_CACHEconstant.Findings from post-merge review
/framesroute hardcodedmax-age=31536000, immutableon ship — already fixed in PR Frames endpoint: align cache header with DETERMINISTIC_CACHE #168.api.mdxclaimed "immutably cached for a year" in two places — fixed here.openapi.jsonandCLAUDE.mdhad the same stale language — fixed here.Test plan
openapi.jsonparses as valid JSONcache-control: public, max-age=86400, stale-while-revalidate=604800on/api/pixabot/{id}and/api/pixabot/{id}/frames?v=Nstill cache-busts (verified against prod; identical bytes, distinct cache entries)🤖 Generated with Claude Code