msmfa · Sep 30, 2026 · Sep 11, 2026 · Sep 11, 2026 · Sep 30, 2026 · Sep 30, 2026
diff --git a/.gitignore b/.gitignore
@@ -7,6 +7,7 @@
 
 # testing
 /coverage
+/reports/lighthouse/
 
 # production
 /build
@@ -22,4 +23,4 @@
 /.claude
 npm-debug.log*
 yarn-debug.log*
-yarn-error.log*
+yarn-error.log*
diff --git a/README.md b/README.md
@@ -31,6 +31,19 @@ Each concept page has a collapsible AI panel. Expand it, connect your OpenAI or
 
 Your key stays in page memory and is never sent to our server — requests go straight from your browser to the provider. It clears when you leave or reload the page, unless you choose to remember it for that tab.
 
+The AI code downloads only when you open the panel, keeping the definitions and examples light.
+
+## Content and checks
+
+The site now covers 40 concepts. New definitions stay under 30 words, and every code example is tested.
+
+```sh
+npm test
+npm run build
+```
+
+See the [maintenance notes](docs/maintenance.md) for editing content and AI crawler access, and the [Lighthouse audit](docs/lighthouse-audit.md) for performance and SEO results.
+
 ---
 
 ## Ready to go further?

diff --git a/docs/lighthouse-audit.md b/docs/lighthouse-audit.md
@@ -0,0 +1,67 @@
+# Lighthouse and SEO audit — 30 September 2026
+
+The existing live site already passed Lighthouse's accessibility, best practices, and SEO checks. The live mobile performance scores were 96 for the homepage and 98 for Variables. The updated local production build scored 100 in all four categories on every page/device combination tested below.
+
+## Measurements
+
+Lighthouse 13.5.0; a separate headless Chrome session per audit, default simulated mobile throttling or the desktop preset. These are individual laboratory runs, not field Core Web Vitals or measurements from India. Scores can vary by device, location, and run.
+
+| Page and environment | Performance | Accessibility | Best practices | SEO | LCP | Blocking time | Layout shift |
+|---|---:|---:|---:|---:|---:|---:|---:|
+| Live homepage · mobile | 96 | 100 | 100 | 100 | 1.8 s | 170 ms | 0 |
+| Live Variables · mobile | 98 | 100 | 100 | 100 | 1.0 s | 160 ms | 0 |
+| Local Arrays before · mobile | 100 | 100 | 100 | 100 | 1.3 s | 0 ms | 0 |
+| Updated homepage · mobile | 100 | 100 | 100 | 100 | 1.1 s | 0 ms | 0 |
+| Updated Variables · mobile | 100 | 100 | 100 | 100 | 1.2 s | 0 ms | 0 |
+| Updated Arrays · mobile | 100 | 100 | 100 | 100 | 1.2 s | 0 ms | 0 |
+| Updated homepage · desktop | 100 | 100 | 100 | 100 | 0.3 s | 0 ms | 0 |
+| Updated Arrays · desktop | 100 | 100 | 100 | 100 | 0.3 s | 0 ms | 0 |
+
+Local analytics are disabled by the site's existing production-host allowlist. The live and local performance scores therefore cannot be treated as a before/after measurement of these edits. The local Arrays before/after comparison uses the same environment. Its score was already 100; the measurable reduction is in first-party JavaScript loaded before interaction: **21,817 bytes → 6,777 bytes (69% less, before compression)**. The two AI bundles are fetched only after opening the panel. The baseline and final network logs verify this.
+
+The live reports identify Google Analytics and PostHog as the largest remaining JavaScript cost, including about 123 KiB of unused vendor code during initial loading. Analytics behavior and its event collection are unchanged. Post-deployment auditing is needed to measure the changes with the production hosting and analytics together.
+
+## Changes
+
+- Load the optional AI panel and provider client on demand through a 457-byte loader. Reopening the panel does not duplicate initialization; failed downloads show a recovery message.
+- Use “JavaScript concepts explained simply” as the homepage H1 and a beginner-focused meta description.
+- Put each concept's descriptive MDN documentation link outside the collapsed AI panel, available with JavaScript disabled.
+- Enforce an 8 KiB ceiling on initial first-party JavaScript and verify generated lazy imports, unique titles, and metadata in the test suite.
+
+All 40 concept definitions and examples retain their approved wording. The five new definitions remain under 30 words.
+
+## SEO verification
+
+The site generates the homepage and all 40 concept pages as static HTML, with one H1 per page, unique titles and descriptions, self-referencing canonical URLs, real internal links, and structured WebSite, WebPage, BreadcrumbList, TechArticle, and DefinedTerm data. All 41 indexable URLs appear in the sitemap; robots.txt points to it. The 404 page is marked noindex. Tests resolve every internal link and execute all examples.
+
+The live non-www Variables URL redirects to the canonical www URL. At audit time the five new topics and these optimizations remained local; the live Arrays URL returned 404. They need publishing before Google can discover the new pages.
+
+Lighthouse's SEO category covers technical checks. Search visibility also depends on useful content and links, as described in [Google's SEO Starter Guide](https://developers.google.com/search/docs/fundamentals/seo-starter-guide). See [Lighthouse documentation](https://developer.chrome.com/docs/lighthouse/overview/) for audit interpretation.
+
+## Reproduce
+
+Use Node.js 22 and an installed Chrome browser. Start the production-output preview with `npm run dev`, then substitute its printed port:
+
+```sh
+npm test
+mkdir -p reports/lighthouse
+npx --yes lighthouse@13.5.0 http://127.0.0.1:PORT/javascript-arrays/ --chrome-flags="--headless --no-sandbox" --output=json --output=html --output-path=reports/lighthouse/arrays-mobile
+npx --yes lighthouse@13.5.0 http://127.0.0.1:PORT/javascript-arrays/ --preset=desktop --chrome-flags="--headless --no-sandbox" --output=json --output=html --output-path=reports/lighthouse/arrays-desktop
+```
+
+Repeat for the homepage and Variables. After publishing, run the same commands with the production URLs to include real hosting and analytics. Reports are ignored by Git.
+
+## Saved evidence
+
+The eight HTML and JSON reports are saved locally under `reports/lighthouse/2026-09-30/`:
+
+- [Live homepage · mobile](../reports/lighthouse/2026-09-30/live-home-mobile.report.html)
+- [Live Variables · mobile](../reports/lighthouse/2026-09-30/live-variables-mobile.report.html)
+- [Local Arrays before · mobile](../reports/lighthouse/2026-09-30/before-arrays-mobile.report.html)
+- [Updated homepage · mobile](../reports/lighthouse/2026-09-30/after-home-mobile.report.html)
+- [Updated Variables · mobile](../reports/lighthouse/2026-09-30/after-variables-mobile.report.html)
+- [Updated Arrays · mobile](../reports/lighthouse/2026-09-30/after-arrays-mobile.report.html)
+- [Updated homepage · desktop](../reports/lighthouse/2026-09-30/after-home-desktop.report.html)
+- [Updated Arrays · desktop](../reports/lighthouse/2026-09-30/after-arrays-desktop.report.html)
+
+Validation: **85 tests passed**; all 40 examples executed; all five updated Lighthouse runs scored 100 in all four categories. The AI panel and connection dialog were also opened successfully in the browser after lazy loading.
diff --git a/docs/maintenance.md b/docs/maintenance.md
@@ -0,0 +1,30 @@
+# Site maintenance
+
+The AI panel and provider client load only when opened. Tests keep initial first-party JavaScript below 8 KiB and verify that repeated opens share one load.
+
+## Content and checks
+
+Edit `src/data.js` to change an example, updating `output` to match its console output. Descriptions and `definitionItems` preserve the original site's wording; intentional copy changes must also update the source snapshot in `test/fixtures/original-descriptions.json`. New topics use `test/fixtures/new-descriptions.json` and must keep their complete definition under 30 words. Preserve existing slugs so shared links keep working.
+
+```sh
+npm test
+npm run build
+```
+
+Tests run all 40 examples, compare every description and bullet list with its source snapshot, check the rendered HTML and internal links, and validate the sitemap. The original 35 definitions are preserved even where they exceed 30 words. The five new beginner topics—arrays, objects, if/else, DOM, and events—have definitions of fewer than 30 words, enforced by the tests. Examples marked `environment: 'browser'` run with a document supplied by LinkeDOM during tests; readers can paste them into a browser console. LinkeDOM is only a development dependency and is not shipped to visitors. The generated site is written to `build/`. The archived image assets in `src/assets/` use lossless WebP; they are not shipped with the site. Code examples are selectable text, with JavaScript syntax highlighting generated at build time using highlight.js.
+
+AI tests use simulated provider responses to check request formats, conversation context, connection validation, storage opt-in, cancellation, and error handling without using a real key or incurring API charges. A live explanation requires a valid visitor-supplied API key and API credits.
+
+The header and favicon share the optimised 64px `src/logo.webp`, served with a content hash and immutable cache headers. `src/logo.svg` is its editable vector source and is not deployed. When changing the logo, export the vector at 64 × 64 pixels with transparency and encode it using lossless WebP before rebuilding.
+
+The interface uses a locally served Latin variable subset of [Manrope](https://fonts.google.com/specimen/Manrope), with regular and medium weights. The 24 KB WOFF2 file is preloaded, content-hashed, and cached; no external font request is made by visitors. Code examples keep their monospace font. The font’s SIL Open Font License is in `src/fonts/OFL.txt` and is copied into the generated assets.
+
+## Lighthouse and SEO
+
+See [the Lighthouse audit](lighthouse-audit.md) for measured mobile and desktop scores, the audit commands, and the distinction between production and local results. Site tests also verify unique page titles and descriptions, canonical URLs, crawlable links, structured data, the sitemap, and the non-indexable 404 page.
+
+## AI crawler access
+
+The current `robots.txt` permits all crawlers, including search and training crawlers. Search visibility and training permissions are separate controls; see the [OpenAI crawler documentation](https://developers.openai.com/api/docs/bots), [Anthropic crawler documentation](https://support.claude.com/en/articles/8896518-does-anthropic-crawl-data-from-the-web-and-how-can-site-owners-block-the-crawler), and [Perplexity crawler documentation](https://docs.perplexity.ai/docs/resources/perplexity-crawlers). Keep hosting-level bot restrictions in mind when diagnosing blocked requests; a successful request with a crawler user-agent does not verify access from that provider's actual IP addresses or prove indexing.
+
+The build generates `/llms.txt` from `src/data.js`, with links to every canonical concept page and its existing definition. Indexable HTML pages point to it with `rel="describedby"`. This follows the optional [llms.txt proposal](https://llmstxt.org/) as a discovery aid and adds no client-side JavaScript. The HTML remains the complete source for examples and expected output. This file does not guarantee citations or rankings; [Google's AI search guidance](https://developers.google.com/search/docs/appearance/ai-features) says no special AI text file or schema is required.