diff --git a/.agent/archive/site-asset-performance-optimization-history.md b/.agent/archive/site-asset-performance-optimization-history.md index 183fa03..4ba37b9 100644 --- a/.agent/archive/site-asset-performance-optimization-history.md +++ b/.agent/archive/site-asset-performance-optimization-history.md @@ -36,3 +36,10 @@ Completed 2026-08-10. A tested canonical budget module protects generated raster GIF, total-media, home, and get-started output while source masters remain report-only. PR CI and Pages enforce budgets in build order. A validated repository skill routes future media work through Astro optimization, provenance review, and the same checks. + +## M4 — v1.0.1 production closure + +Completed 2026-08-10. The release candidate passed the combined Level 3 matrix and an +isolated clean-clone Level 4 matrix, merged through required PR CI, and deployed through +the validated Pages workflow. Production HTTP checks proved routes, metadata, optimized +picture/video resources, asset sizes, 404 handling, and HTTPS behavior without Browser. diff --git a/.agent/evidence/site-asset-performance-optimization.md b/.agent/evidence/site-asset-performance-optimization.md index 5d6ae15..29736d8 100644 --- a/.agent/evidence/site-asset-performance-optimization.md +++ b/.agent/evidence/site-asset-performance-optimization.md @@ -67,3 +67,14 @@ SPDX-License-Identifier: MIT picture AVIF/WebP markup, autoplay/muted/loop/playsinline WebM+MP4 delivery, no GIF reference, five fetchable optimized assets each below 1 MiB, and combined video plus poster below 2 MiB. It remains deferred until the candidate is deployed. +- 2026-08-10, Level 4 candidate: a fresh isolated clone at exact `e60db61` completed + `npm ci` with zero vulnerabilities, 17 tests, 174/174 license policy, release and + workflow policy, zero Astro diagnostics, 18-page build, asset budgets, and site/ + content validation. The branch was pushed without force and PR #13 passed required + CI before normal merge as `cd7f67323285afb7fb31cfa7e92c75ca9b202727`. +- 2026-08-10, production: Pages run 31446277556 built, checked asset budgets, uploaded, + and deployed `cd7f673` successfully. The first production invocation exposed only an + over-exact checker regex (`` versus Astro's ``); live + HTML already contained AVIF/WebP sets. After narrowing it to ` + +# Site asset performance optimization editorial report + +## Editorial Summary + +The correction cycle turned a visually faithful Astro migration into a production- +efficient one. Large source photographs now become responsive AVIF/WebP output, the +embedded demonstration uses compact web video instead of an 8.3 MB GIF, and generated +asset budgets make those gains enforceable in both pull requests and Pages deployment. + +## Original Plan versus Actual Outcome + +All M0-M4 outcomes were delivered in order. The implementation retained source masters +and their provenance while changing normal browser delivery. Browser tooling was not +required: generated-output inspection, Playwright screenshots/playback, clean-clone +validation, GitHub Actions, and production HTTP checks established acceptance. + +## What Changed + +- Added deterministic source/generated media and fallback-resource proxy reporting. +- Routed home, samples, hero backgrounds, and article imagery through Astro assets. +- Replaced the GIF with WebM, MP4, and a WebP poster using recorded ffmpeg commands. +- Added tested output budgets and enforced them after builds in CI and Pages. +- Added a reusable asset-optimization skill and repository routing instructions. +- Prepared and deployed the v1.0.1 correction release through normal PR review. + +## Decisions and Trade-offs + +Generated output, not large preserved source masters, is the hard-policy boundary. +Two WebP fallbacks at 605,226 and 727,056 bytes remain visible warnings because they +are below the 1 MiB ceiling and preserve reviewed quality. The payload measurement is +a deterministic fallback-resource proxy, not a browser transfer simulation. + +## Unexpected Problems and Discoveries + +The original build copied every tracked media byte, confirming delivery architecture +as the high-leverage defect. A post-deployment check initially required literal +`` markup, while Astro correctly adds scoped attributes to that element; the +selector was narrowed to the semantic tag boundary after live asset sets were proven. + +## Validation and Measurable Results + +Static generated media excluding the deferred GIF fell 81.0%. The homepage proxy fell +from 17,129,268 to 2,111,330 bytes (87.7%), and get-started fell from 9,511,556 to +1,647,783 bytes (82.7%). The animation delivery fell from 8,325,288 to 461,046 bytes +(94.5%). Final budgets report 4,882,580 generated bytes, zero failures, and two warnings. + +The final candidate passed 17 tests, 174/174 license policy files, release/workflow +checks, zero Astro diagnostics, an 18-page build, route/link/SPDX/content checks, and +the same matrix in a clean clone. Production proved 14 legacy routes, 28 required +resources, five optimized assets, video size, 404 behavior, and HTTPS redirect. + +## Useful Evidence and Examples + +Exact commands, hashes, before/after bytes, screenshot hashes, PR #13, merge commit +`cd7f673`, and Pages run 31446277556 are recorded in the corresponding evidence file. +Completed milestone detail and decisions are preserved in the archive and ExecPlan. + +## Limitations, Remaining Work, and Open Questions + +Large historical source masters remain by design and still appear in reports. The two +sub-1-MiB raster warnings are the only current review items; neither needs an exception. +Human brand review may still choose different artwork, but no visual judgment remains +necessary for this release's technical acceptance. + +## Possible Article Angles + +- Why generated-output budgets are better than deleting source masters. +- Replacing an animated GIF with semantic video without redesigning the page. +- Measuring migration performance with deterministic fallback-resource proxies. + +## Suggested Narrative + +Frame the work as a correction to delivery semantics: Astro already supplied the right +image pipeline, but metadata URLs bypassed it. Once page contracts used that pipeline, +performance gains became measurable, enforceable, and deployable without a new service. + +## Claims Requiring Human Review + +The proxy reductions must not be presented as exact network transfer savings because +they intentionally exclude browser `srcset` choice, compression, cache, and protocol +behavior. Brand and customer-material provenance remains governed by existing REUSE +mappings and may be reviewed independently by rights holders. diff --git a/.agent/state/site-asset-performance-optimization.md b/.agent/state/site-asset-performance-optimization.md index 84f58cb..72712bb 100644 --- a/.agent/state/site-asset-performance-optimization.md +++ b/.agent/state/site-asset-performance-optimization.md @@ -5,15 +5,15 @@ SPDX-License-Identifier: MIT # Site asset performance optimization state -- Active milestone: M4 — prepare v1.0.1 and complete review/deployment closure. -- Active slice: Level 3 release candidate is complete; recheck remote/tags/workflows, - commit the candidate, then prove it in a clean clone before push/PR/merge/deploy. -- Last completed logical slice: M3 tested generated-output budgets now run after builds - in PR CI and Pages; the repository asset-optimization skill is routed from `AGENTS.md`. -- Active paths: package release metadata, changelog, release checker, plan reporting, - then clean-clone/GitHub/production evidence. -- Next concrete action: run targeted license/diff checks, commit the v1.0.1 candidate, - recheck remote state, and execute the Level 4 clean-clone matrix. +- Active milestone: complete — v1.0.1 correction and asset-performance cycle. +- Active slice: final evidence-only closure after verified production deployment. +- Last completed logical slice: M4 candidate merged through PR #13, Pages deployed + merge `cd7f673`, and production HTTP/asset validation passed after narrowing one + overly strict `` checker pattern. +- Active paths: final plan state, evidence/archive, editorial report, and the focused + production-check selector correction. +- Next concrete action: merge this closure through normal review, verify its Pages run, + rerun production proof, and create annotated `v1.0.1` at that exact deployed commit. - Focused validation completed: skill validation passed; assets tests 4/4; license coverage 170/170; workflow policy passed; Astro checked 54 files with zero diagnostics; Node 24 built 18 pages; asset and site/content checks passed. @@ -23,10 +23,13 @@ SPDX-License-Identifier: MIT - Final Level 3: 17 tests passed; license coverage 174/174; release/workflow checks passed; Astro checked 54 files with zero diagnostics; Node 24 built 18 pages; asset, route/link/SPDX, and content checks passed. -- Deferred validation: Level 4 clean clone, PR checks, merged Pages deployment, - production HTTP/asset proof, final closure reporting, and v1.0.1 tag. -- Active decisions: release through normal review without bypass; tag only the exact - deployed source commit after production proof; Browser remains optional and unused. +- Level 4: clean clone `e60db61` passed install and the release matrix; PR #13 CI + passed; Pages run 31446277556 deployed `cd7f673`; production validated 14 legacy + routes, 28 resources, five optimized assets, 461,046 video bytes, 404, and HTTPS. +- Deferred validation: closure PR/Pages run, repeat production proof, and annotated + `v1.0.1` at the exact final deployed commit. +- Active decisions: do not bypass review; Browser was unnecessary; preserve the two + sub-1-MiB raster warnings and large source masters because delivered output passes. - Blockers: none. - Deliberate out of scope: no v1.0.2 feature work or unrelated redesign in this cycle. - Resume command: `sed -n '1,180p' .agent/state/site-asset-performance-optimization.md && git status --short --branch`. diff --git a/scripts/check-production.mjs b/scripts/check-production.mjs index ea74b0d..daf411e 100644 --- a/scripts/check-production.mjs +++ b/scripts/check-production.mjs @@ -65,7 +65,7 @@ function requireNoMatch(path, pattern, label) { requireMatch("/", //, "responsive picture markup"); +requireMatch("/", /]*autoplay[^>]*muted[^>]*loop[^>]*playsinline/, "animated video behavior");