From 33e7a18ed3ae0d08ab7eefd1cb86efac01122337 Mon Sep 17 00:00:00 2001 From: Fabio Sobral Date: Mon, 10 Aug 2026 20:38:25 -0300 Subject: [PATCH 01/10] docs(plan): record visual correction baseline --- ...st-migration-visual-corrections-history.md | 15 + .../post-migration-visual-corrections.md | 24 ++ .../post-migration-visual-corrections.md | 333 ++++++++++++++++++ .../post-migration-visual-corrections.md | 26 ++ 4 files changed, 398 insertions(+) create mode 100644 .agent/archive/post-migration-visual-corrections-history.md create mode 100644 .agent/evidence/post-migration-visual-corrections.md create mode 100644 .agent/plans/post-migration-visual-corrections.md create mode 100644 .agent/state/post-migration-visual-corrections.md diff --git a/.agent/archive/post-migration-visual-corrections-history.md b/.agent/archive/post-migration-visual-corrections-history.md new file mode 100644 index 0000000..5b6854f --- /dev/null +++ b/.agent/archive/post-migration-visual-corrections-history.md @@ -0,0 +1,15 @@ + + +# Post-migration visual corrections history + +## M0 — Narrow regression baseline + +Completed 2026-08-10 without implementation changes. The source head contract, +favicon/icon binaries, footer, legacy social component, license header model, and one +existing generated artifact were inspected directly. The regression is bounded to a +malformed tiny favicon plus incomplete head metadata, six footer text placeholders, +missing external-link protections, and source SPDX comments emitted into 19 generated +HTML documents. Large-image delivery remains assigned to the follow-up ExecPlan. diff --git a/.agent/evidence/post-migration-visual-corrections.md b/.agent/evidence/post-migration-visual-corrections.md new file mode 100644 index 0000000..3afee87 --- /dev/null +++ b/.agent/evidence/post-migration-visual-corrections.md @@ -0,0 +1,24 @@ + + +# Post-migration visual corrections evidence + +- 2026-08-10, M0 branch baseline: focused branch and remote `main` both resolve to + `5a1abc26f751f3680ac4cbff47d98d3169454d6f`; the two supplied ExecPlans were the + only untracked paths. +- 2026-08-10, M0 favicon/head: `BaseLayout.astro` links only `/favicon.ico` with + `sizes="any"` and omits the 32px PNG, Apple touch icon, and web manifest. The ICO is + a 16×16 two-color Windows resource. The 32×32 PNG visibly contains only a small red + mark, while `public/icons/icon-192x192.png` is a complete TotalCross emblem; all + eight manifest PNGs have the dimensions declared by their filenames. +- 2026-08-10, M0 social parity: the current footer emits two-character placeholders + for GitHub, X, Telegram, YouTube, Instagram, and LinkedIn with neither `target` nor + `rel`. Legacy `site` used the corresponding Font Awesome brand glyphs. Destinations + survived the migration unchanged. +- 2026-08-10, M0 SPDX emission: the existing generated `dist/` contains recognized + project SPDX header comments in 19 HTML documents; `dist/index.html` begins with + both authoring tags. Policy classifies Astro/HTML/Markdown/MDX as HTML-comment + style, and the fixer inserts that header immediately after frontmatter, where Astro + renders it into output. diff --git a/.agent/plans/post-migration-visual-corrections.md b/.agent/plans/post-migration-visual-corrections.md new file mode 100644 index 0000000..cbb3d44 --- /dev/null +++ b/.agent/plans/post-migration-visual-corrections.md @@ -0,0 +1,333 @@ + + +# Correct post-migration favicon, iconography, and rendered SPDX metadata + +This ExecPlan follows `AGENTS.md` and `.agent/PLANS.md` in +`TotalCross/totalcross.github.io`. Execute it before +`.agent/plans/site-asset-performance-optimization.md`. + +## Purpose / Big Picture + +Correct the visible regressions found after the Gatsby-to-Astro production cutover +without redesigning the site. + +At completion: + +- the TotalCross favicon and manifest/site icons work consistently; +- social/external-link iconography uses meaningful brand icons rather than text + initials or placeholders; +- the current TotalCross visual identity and destinations remain intact; +- project SPDX metadata stays present and automatically validated in source but is + not emitted repeatedly into generated HTML; +- renderable Markdown/MDX follows the same source-only SPDX rule; +- all changes remain compatible with the current Astro `main` -> GitHub Pages + artifact deployment. + +Do not change the large-image delivery strategy in this plan. Asset performance is +handled by the follow-up ExecPlan. + +## Working Set and Resume Protocol + +Use: + +- `.agent/state/post-migration-visual-corrections.md` — first read on resume; +- `.agent/evidence/post-migration-visual-corrections.md` — concise commands, + generated-output checks, and screenshot/manual evidence; +- `.agent/archive/post-migration-visual-corrections-history.md` — completed detail; +- `.agent/reports/post-migration-visual-corrections-editorial.md` — final factual + handoff using the headings required by `.agent/PLANS.md`. + +Read `AGENTS.md` and `.agent/PLANS.md` once at start. Read +`.agents/skills/license-validation/SKILL.md` when modifying header policy and +`.agents/skills/logical-commits/SKILL.md` before staging. Use the legacy `site` +branch and `.agent/baseline/screenshots/` only for targeted parity questions; do +not reopen the complete migration audit. + +Keep implementation and active planning files ideally below 20 KB or about 600 +lines. Split a helper/test when responsibility becomes unclear rather than growing +a monolithic file. + +## Progress + +- [x] M0 — Confirm the narrow regression baseline. +- [ ] M1 — Restore favicon and social/external icon parity. +- [ ] M2 — Keep SPDX metadata source-only while preserving validation/fix behavior. +- [ ] M3 — Final correction validation and handoff to asset optimization. + +Update only at logical commits or milestone closure. + +## Current Architecture and Scope + +Production source is `main`; ignored `dist/` is deployed by +`.github/workflows/pages.yml` as a GitHub Pages artifact. Do not reintroduce Gatsby, +React, or a generated deployment branch. + +`public/favicon.ico`, `public/favicon-32x32.png`, `public/icons/**`, and +`public/manifest.webmanifest` exist. `src/layouts/BaseLayout.astro` currently links +the ICO but favicon behavior is visibly broken, so the icon files and head contract +need verification rather than assumption. + +`src/components/SiteFooter.astro` contains GitHub, Twitter/X, Telegram, YouTube, +Instagram, and LinkedIn destinations but renders short text initials. The legacy +Gatsby footer used Font Awesome Free brand icons and external links opened with +`target="_blank"` plus `rel="noopener noreferrer"`. + +The license validator currently classifies `.astro` as HTML-comment content and +inserts its header after frontmatter. Astro emits that comment into HTML. Similar +rendered comments must not leak from Markdown/MDX content. Existing REUSE ownership +boundaries remain authoritative, especially for brand/customer/third-party files. + +## Execution Policy + +Start from current `main` on a focused branch such as +`fix/post-migration-visual-corrections`. Preserve unrelated local changes. + +Commits must be logical, descriptive, in English, and follow Conventional Commits. +Suggested boundaries: + +- `fix(icons): restore site and social iconography` +- `fix(license): keep SPDX metadata out of rendered pages` +- `docs(plan): close visual correction milestone` + +Do not create WIP commits. For this plan, the `logical-commits` skill's focused +validation means diff/scope checks such as `git diff --check` during implementation. +Do not run Astro builds, test suites, or visual matrices before each commit. Finish +the milestone implementation first and run its validation as the final stage. + +Keep token use low: inspect known paths first, record conclusions once in evidence, +and avoid repeated repository listings or full-plan rereads. + +Interactive Browser availability is optional. Generated-output inspection and +repository-local tooling are sufficient for plan continuation. Record only a narrow +manual visual verification item when human judgment is genuinely required. + +## Plan of Work + +### M0 — Confirm the narrow regression baseline + +Goal: record only the evidence needed to prove these corrections. + +Inspect: + +- `src/layouts/BaseLayout.astro`; +- `src/components/SiteFooter.astro`; +- `public/favicon.ico`, `public/favicon-32x32.png`, `public/icons/**`, and + `public/manifest.webmanifest`; +- legacy `site` branch footer/social components only as needed; +- `scripts/license-validation.mjs`, `scripts/license/policy.mjs`, + `scripts/license/headers.mjs`, and their tests; +- `REUSE.toml` and the two existing agent skills. + +Do not perform a broad site audit. Record one generated-HTML example showing SPDX +leakage and one targeted footer/icon comparison. Verify favicon binary type and +icon dimensions with lightweight local tools; do not modify files in M0. + +Acceptance: the evidence file identifies the exact favicon/head issue, current +social placeholder behavior, and current SPDX emission mechanism. + +Final validation: one focused inspection/report only; no production build is +required unless needed to capture the SPDX example and no prior `dist/` exists. + +### M1 — Restore favicon and social/external icons + +Goal: fix user-visible icon regressions while preserving the legacy identity. + +For favicon/site icons: + +- validate existing favicon/manifest files before replacing them; +- regenerate only broken/malformed derivatives from an existing canonical + TotalCross brand asset; do not redraw or reinterpret the logo; +- update `BaseLayout.astro` with explicit valid favicon relationships, including the + existing PNG/ICO and `manifest.webmanifest`; +- add an Apple touch icon only when it can be derived from the existing brand set + without introducing a new design; +- keep all brand derivatives under the existing + `LicenseRef-TotalCross-Brand` REUSE policy. + +For social/external icons: + +- replace footer initials with accessible SVG brand icons for GitHub, Twitter/X as + intentionally selected from the legacy baseline, Telegram, YouTube, Instagram, + and LinkedIn; +- do not reintroduce React or a client-side FontAwesome runtime; +- prefer one small `SocialIcon.astro` abstraction and either static SVG data with + preserved upstream licensing or a build-time-only free icon source; +- keep link text available to assistive technology with `aria-label`; +- restore `target="_blank"` and `rel="noopener noreferrer"` for true external + social destinations unless a current repository convention deliberately differs; +- audit migrated pages only for obvious confirmed missing icon affordances; do not + redesign navigation or add speculative icons. + +If an icon package is introduced, ensure no client-side JS is shipped merely to +render static brand SVG and record its license/provenance as required by existing +repository policy. + +Acceptance: local output contains valid favicon/manifest links; the footer presents +recognizable icons at the intended size/hover behavior; destinations and accessible +labels are correct; no text-initial placeholder remains for the known social links. + +Final milestone validation: run `npm run license:check`, `npm run check`, one fresh +`npm run build`, `npm run validate`, and a targeted local icon/head check once. +Capture only representative desktop/mobile evidence for the footer if automated +screenshots are already available; otherwise record one narrow manual check. + +### M2 — Keep SPDX metadata source-only + +Goal: preserve automatic licensing guarantees without inflating rendered HTML. + +Update the license header model so renderable authored formats have non-emitting +metadata placement. + +For `.astro`: + +- add a dedicated header style that places the canonical JavaScript block comment + inside Astro frontmatter rather than after it; +- when a component has no frontmatter, the fixer may create minimal frontmatter to + contain the source-only header; +- inspection must recognize the new canonical placement; +- migration/fix logic may normalize the repository's exact known legacy HTML header + form, but must continue refusing conflicting holders/licenses or unrelated + third-party notices. + +For `.md`/`.mdx`: + +- use a source-only frontmatter comment or reviewed REUSE mapping that does not + become article HTML; +- preserve editorial CC-BY-4.0 versus third-party/customer classifications already + defined by policy; +- do not insert visible license boilerplate into article bodies solely to satisfy + source validation. + +Update `scripts/license/policy.mjs`, `scripts/license/headers.mjs`, and focused tests. +Keep files small; split Astro/frontmatter parsing helpers if the current module +would otherwise become difficult to understand. + +Update `.agents/skills/license-validation/SKILL.md` only if its documented supported +placement/fix behavior changes. Do not weaken its conservative refusal policy. + +Add a generated-output assertion to an appropriate existing site validation script +or a small focused helper: built `dist/**/*.html` must contain zero occurrences of +`SPDX-FileCopyrightText` and `SPDX-License-Identifier` authoring metadata. Avoid +checking legitimate visible prose that might discuss SPDX in future blog content; +scope the assertion to recognized header/comment forms when needed. + +Acceptance: repository-wide licensing validation passes; fixer tests cover Astro and +renderable content placement; generated HTML no longer contains source headers; no +third-party ownership classification changes unintentionally. + +Final milestone validation: run `npm run license:test`, `npm run license:check:all`, +`npm run check`, one fresh build, and `npm run validate` once. If a command fails, +fix the specific cause and rerun only the failed/dependent checks. + +### M3 — Final correction validation and handoff + +Goal: close visible corrections cleanly without duplicating the later performance +plan. + +Update `CHANGELOG.md` `[Unreleased]` with favicon/social icon and source-only SPDX +corrections. Do not bump the package version yet; the follow-up asset-performance +plan owns the combined patch release unless the user explicitly chooses to release +these corrections independently. + +Reconcile state/evidence/history and produce the factual editorial report. Record +any remaining manual icon/browser check as a narrow item, not as a blocker for asset +optimization if generated output is otherwise correct. + +Level 3 closure runs once after implementation is complete: + + npm test + npm run license:check:all + npm run release:check + npm run workflow:check + npm run check + npm run build + npm run validate + +Do not run `production:check` unless this plan is being independently published. + +Acceptance: all commands pass, changelog is current, the branch is coherent, and the +state file points explicitly to the asset-performance ExecPlan as the next work. + +## Surprises & Discoveries + +- Observation: footer destinations survived migration but their legacy brand icons + were replaced by text initials. + Evidence: keep one focused before/after reference in evidence. + +- Observation: SPDX HTML comments placed after Astro frontmatter are part of the + rendered template and therefore appear in generated HTML. + Evidence: keep one concise generated before/after sample. + +- Observation: the 32px favicon derivative contains only a small red mark while the + existing 192px manifest icon retains the complete TotalCross emblem. + Evidence: file/dimension inspection and the focused M0 image comparison recorded + in `.agent/evidence/post-migration-visual-corrections.md`. + +Move resolved detail to the archive at milestone closure. + +## Decision Log + +- Decision: restore icons as static/build-time SVG rather than React runtime. + Rationale: preserve the affordance without undoing the Astro static migration. + Date: 2026-08-10. + +- Decision: require SPDX metadata in source but not generated site HTML. + Rationale: source ownership remains machine-verifiable while repeated rendered + comments add no user value. + Date: 2026-08-10. + +- Decision: defer package version bump to the asset-performance follow-up plan. + Rationale: these post-migration corrections should normally ship as one patch + release rather than multiple artificial releases during one correction cycle. + Date: 2026-08-10. + +## Validation and Acceptance + +Use validation levels from `AGENTS.md`. M1 and M2 normally close at Level 2/3 only +after implementation. M3 is the one combined Level 3 checkpoint. + +Overall acceptance requires: + +- functioning favicon/site icon relationships; +- recognizable social icons with accessible labels and correct external behavior; +- no known migrated icon placeholders for the audited scope; +- no source SPDX header comments emitted into generated HTML; +- unchanged routes, blog semantics, and GitHub Pages architecture; +- repository licensing policy and conservative fixer behavior preserved. + +## Risks and Open Questions + +- Brand/social icons have their own trademark/license context. Preserve upstream + notices and do not treat third-party brand glyphs as Amalgam-authored MIT assets. +- Favicon cache can make a correct build look stale. Verify generated files/links + before changing filenames repeatedly to defeat a local browser cache. +- Markdown/MDX frontmatter handling must not break content collection schemas. +- A future article may legitimately contain the string `SPDX-License-Identifier` in + prose. Generated-output checks should detect emitted authoring headers rather than + ban educational content indiscriminately. + +## Idempotence and Recovery + +Header fix operations must be idempotent. Running the fixer twice must not duplicate +frontmatter or headers. It must continue refusing ambiguous/third-party conflicts. + +Favicon/icon generation must write explicit known paths and preserve REUSE mapping. +Do not mass-replace assets or alter unrelated branding. + +If a visual correction is rejected, revert only that icon slice. SPDX work should +remain independently recoverable. Never force-update `main` or deployment refs. + +## Outcomes & Retrospective + +At each checkpoint record only commits, behavior restored, generated-output proof, +and validation result. Final narrative and article angles belong in the editorial +report, not the active plan. + +## Revision Note + +2026-08-10: Split from the broader post-migration correction milestone to keep the +active ExecPlan below repository size limits and separate visible regressions/license +output from media performance work. diff --git a/.agent/state/post-migration-visual-corrections.md b/.agent/state/post-migration-visual-corrections.md new file mode 100644 index 0000000..d95e35c --- /dev/null +++ b/.agent/state/post-migration-visual-corrections.md @@ -0,0 +1,26 @@ + + +# Post-migration visual corrections state + +- Active milestone: M1 — restore favicon and social/external icons. +- Active slice: derive valid favicon/touch metadata from the existing TotalCross + emblem and replace six footer text placeholders with static accessible SVG icons. +- Last completed logical slice: M0 narrow regression baseline. +- Active paths: `src/layouts/BaseLayout.astro`, `src/components/SiteFooter.astro`, a + focused `SocialIcon.astro`, public favicon/manifest derivatives, and REUSE mappings. +- Next concrete action: choose the smallest provenance-safe static SVG source, repair + the broken favicon derivatives, and implement the complete M1 behavior before its + one milestone build/validation pass. +- Focused validation completed: favicon/icon file types and dimensions inspected; + existing brand derivatives viewed; legacy footer compared; existing `dist/` + reported 19 HTML documents with emitted SPDX header comments. +- Deferred validation: M1 Astro check/build/site validation and representative footer + evidence wait until the full M1 implementation is complete. +- Active decisions: preserve the legacy destinations and TotalCross emblem; render + social glyphs as static/build-time SVG with no React or client runtime. +- Blockers: none. +- Deliberate out of scope: image payload optimization belongs to the next ExecPlan. +- Resume command: `sed -n '1,180p' .agent/state/post-migration-visual-corrections.md && git status --short --branch`. From 1f5e0febdab0397c31cd65df97395bdee290c344 Mon Sep 17 00:00:00 2001 From: Fabio Sobral Date: Mon, 10 Aug 2026 20:47:40 -0300 Subject: [PATCH 02/10] fix(icons): restore site and social iconography --- ...st-migration-visual-corrections-history.md | 13 +++++ .../post-migration-visual-corrections.md | 18 +++++++ .../corrections-m1-home-1440x900.png | Bin 0 -> 1526770 bytes .../corrections-m1-home-390x844.png | Bin 0 -> 669606 bytes .../post-migration-visual-corrections.md | 2 +- .../post-migration-visual-corrections.md | 33 ++++++------- NOTICE.md | 5 ++ REUSE.toml | 1 + package-lock.json | 24 ++++++++++ package.json | 1 + public/apple-touch-icon.png | Bin 0 -> 15384 bytes public/favicon-32x32.png | Bin 1516 -> 2293 bytes public/favicon.ico | Bin 198 -> 4414 bytes public/manifest.webmanifest | 22 ++++++++- src/components/SiteFooter.astro | 24 +++++++++- src/components/SocialIcon.astro | 45 ++++++++++++++++++ src/layouts/BaseLayout.astro | 6 ++- 17 files changed, 173 insertions(+), 21 deletions(-) create mode 100644 .agent/evidence/screenshots/corrections-m1-home-1440x900.png create mode 100644 .agent/evidence/screenshots/corrections-m1-home-390x844.png create mode 100644 public/apple-touch-icon.png create mode 100644 src/components/SocialIcon.astro diff --git a/.agent/archive/post-migration-visual-corrections-history.md b/.agent/archive/post-migration-visual-corrections-history.md index 5b6854f..f609c96 100644 --- a/.agent/archive/post-migration-visual-corrections-history.md +++ b/.agent/archive/post-migration-visual-corrections-history.md @@ -13,3 +13,16 @@ existing generated artifact were inspected directly. The regression is bounded t malformed tiny favicon plus incomplete head metadata, six footer text placeholders, missing external-link protections, and source SPDX comments emitted into 19 generated HTML documents. Large-image delivery remains assigned to the follow-up ExecPlan. + +## M1 — Favicon and social/external icon parity + +Completed 2026-08-10. Broken 16/32px favicon derivatives were regenerated from the +existing 512px TotalCross emblem, and a matching 180px Apple-touch icon was added. +The shared head now links ICO, PNG, touch, and manifest metadata; the cleaned manifest +describes all eight existing icon sizes under the root application scope. + +The footer keeps all legacy destinations but replaces initials with the corresponding +Font Awesome Free Brands paths rendered by a small Astro component. Links have labels, +titles, new-tab behavior, and noopener/noreferrer protection; the generated site ships +no icon JavaScript. Build, route, content, icon-contract, and desktop/mobile visual +checks passed without a design or navigation change. diff --git a/.agent/evidence/post-migration-visual-corrections.md b/.agent/evidence/post-migration-visual-corrections.md index 3afee87..acca5a5 100644 --- a/.agent/evidence/post-migration-visual-corrections.md +++ b/.agent/evidence/post-migration-visual-corrections.md @@ -22,3 +22,21 @@ SPDX-License-Identifier: MIT both authoring tags. Policy classifies Astro/HTML/Markdown/MDX as HTML-comment style, and the fixer inserts that header immediately after frontmatter, where Astro renders it into output. +- 2026-08-10, M1 implementation: regenerated 32px PNG/ICO and 180px Apple-touch + derivatives from the existing 512px TotalCross brand emblem. The head now declares + ICO, PNG, Apple touch, manifest, and theme color metadata; the manifest declares + stable root scope plus eight verified PNG sizes. Font Awesome Free Brands 7.3.1 is + build-time-only, with CC BY 4.0/MIT provenance recorded in `NOTICE.md`. +- 2026-08-10, M1 social output: GitHub, legacy Twitter bird labeled X (Twitter), + Telegram, YouTube, Instagram, and LinkedIn render as static SVG paths inside labeled + links with `target="_blank"` and `rel="noopener noreferrer"`. Generated home HTML + contains all six and no client `