From 532742d5a56be300ea66bb58dcc4128f696d9ada Mon Sep 17 00:00:00 2001 From: Thiago Moura Date: Sat, 20 Jun 2026 15:28:07 -0300 Subject: [PATCH 1/5] chore: minor formatting Signed-off-by: Thiago Moura --- README.md | 28 +++++++++---------- content-sources.yaml | 1 - package-lock.json | 6 ++-- package.json | 6 ++-- .../blog/code-is-cheap-verification-is-not.md | 6 ++-- src/content/projects/website.md | 2 +- 6 files changed, 24 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index a85136b..5a55be1 100644 --- a/README.md +++ b/README.md @@ -49,7 +49,7 @@ Register the repository in `content-sources.yaml`: sources: - owner: thiagogcm repo: adf4j - slug: adf4j-docs + slug: adf4j order: 0 ``` @@ -74,11 +74,11 @@ During sync, the site validates frontmatter and page order, removes source-owned Cloudflare Workers is both the request entrypoint and the runtime for the few features that need server-side behavior: -| Runtime path | Cloudflare responsibility | Result | -| --- | --- | --- | -| Normal page request | Serve the built site and run server-rendered fragments | Most content remains pre-rendered; dynamic work stays isolated. | -| Scheduled event | Query GitHub every six hours and write the aggregate to KV | Page requests read cached activity data instead of calling GitHub. | -| Cold stats cache | Start a background refresh with the request context | The response can show a fallback without waiting on GitHub. | +| Runtime path | Cloudflare responsibility | Result | +| -------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | +| Normal page request | Serve the built site and run server-rendered fragments | Most content remains pre-rendered; dynamic work stays isolated. | +| Scheduled event | Query GitHub every six hours and write the aggregate to KV | Page requests read cached activity data instead of calling GitHub. | +| Cold stats cache | Start a background refresh with the request context | The response can show a fallback without waiting on GitHub. | | `/api/confluence-adf.json` | Validate a public Confluence Cloud URL and fetch its ADF body | The browser receives a narrow JSON response, then performs the Markdown conversion locally. | The Worker delegates regular requests to the site runtime. Its scheduled handler refreshes GitHub statistics. The status island reads those statistics from the `GITHUB_STATS` KV namespace, while the Confluence route accepts only HTTPS `*.atlassian.net` wiki page URLs containing a numeric page ID. @@ -87,14 +87,14 @@ This boundary is intentional: content assembly belongs to the build, presentatio ## Working locally -| Command | Purpose | -| --- | --- | -| `npm run dev` | Sync external content, then start the development server. | -| `npm run sync:content` | Rebuild generated content from registered sources. | -| `npm run validate:sources` | Validate sources without writing generated output. | -| `npm run test:content-sync` | Test content normalization and link rewriting. | -| `npm run check` | Type-check the site and Worker integration. | -| `npm run build` | Sync content and produce the deployment build. | +| Command | Purpose | +| --------------------------- | --------------------------------------------------------- | +| `npm run dev` | Sync external content, then start the development server. | +| `npm run sync:content` | Rebuild generated content from registered sources. | +| `npm run validate:sources` | Validate sources without writing generated output. | +| `npm run test:content-sync` | Test content normalization and link rewriting. | +| `npm run check` | Type-check the site and Worker integration. | +| `npm run build` | Sync content and produce the deployment build. | ## Deployment diff --git a/content-sources.yaml b/content-sources.yaml index 00fad30..cbd1c35 100644 --- a/content-sources.yaml +++ b/content-sources.yaml @@ -14,4 +14,3 @@ sources: - owner: thiagogcm repo: helm4j order: 2 - diff --git a/package-lock.json b/package-lock.json index 143ad69..ea36ca4 100644 --- a/package-lock.json +++ b/package-lock.json @@ -11,10 +11,10 @@ "@astrojs/cloudflare": "13.7.0", "@nthings.dev/adf4j-wasm": "1.0.2", "astro": "6.4.8", - "chart.js": "^4.5.1", + "chart.js": "4.5.1", "dompurify": "3.4.11", "markdown-it": "14.2.0", - "markdown-it-github-alerts": "^1.0.1", + "markdown-it-github-alerts": "1.0.1", "mermaid": "11.15.0", "prismjs": "1.30.0", "wrangler": "4.103.0" @@ -23,7 +23,7 @@ "@astrojs/check": "0.9.9", "@astrojs/markdown-remark": "7.2.0", "@tailwindcss/vite": "4.3.1", - "@types/markdown-it": "^14.1.2", + "@types/markdown-it": "14.1.2", "@types/prismjs": "1.26.6", "degit": "3.4.7", "tailwindcss": "4.3.1", diff --git a/package.json b/package.json index 5a92f53..ea5ec61 100644 --- a/package.json +++ b/package.json @@ -22,10 +22,10 @@ "@astrojs/cloudflare": "13.7.0", "@nthings.dev/adf4j-wasm": "1.0.2", "astro": "6.4.8", - "chart.js": "^4.5.1", + "chart.js": "4.5.1", "dompurify": "3.4.11", "markdown-it": "14.2.0", - "markdown-it-github-alerts": "^1.0.1", + "markdown-it-github-alerts": "1.0.1", "mermaid": "11.15.0", "prismjs": "1.30.0", "wrangler": "4.103.0" @@ -34,7 +34,7 @@ "@astrojs/check": "0.9.9", "@astrojs/markdown-remark": "7.2.0", "@tailwindcss/vite": "4.3.1", - "@types/markdown-it": "^14.1.2", + "@types/markdown-it": "14.1.2", "@types/prismjs": "1.26.6", "degit": "3.4.7", "tailwindcss": "4.3.1", diff --git a/src/content/blog/code-is-cheap-verification-is-not.md b/src/content/blog/code-is-cheap-verification-is-not.md index e115b0c..5ee68e9 100644 --- a/src/content/blog/code-is-cheap-verification-is-not.md +++ b/src/content/blog/code-is-cheap-verification-is-not.md @@ -23,13 +23,13 @@ This was a greenfield project, and the regulator's specifications were authorita Reading the Authorization Server source was not enough. A locally correct implementation could still fail when a participant registered, a customer completed a consent journey, a token reached a resource server, or a grant was revoked. -So I developed the ecosystem around the Authorization Server as actual simulators. These running components exercised participant registration, consent journeys, protected resource access, and trust relationships. They were not static mocks with canned responses. +So I built a simulated Open Finance ecosystem around the Authorization Server, with running components representing the other participants. These components exercised participant registration, consent journeys, protected resource access, and trust relationships. They were not static mocks with canned responses. Every component was fully instrumented and emitted telemetry, making behavior observable across service boundaries. The biggest leverage was Atacama, a command-line tool that runs ecosystem flows through protocols and APIs, or through Playwright for browser interactions. -I gave Atacama to the agents as a form of chaos engineering. They could execute valid and invalid flows, vary inputs, probe boundaries, interrupt journeys, and look for behavior that contradicted the specifications. Every experiment produced evidence they could inspect. +I gave Atacama to the agents as an adversarial testing interface for the ecosystem. They could execute valid and invalid flows, vary inputs, probe boundaries, interrupt journeys, and look for behavior that contradicted the specifications. Every experiment produced evidence they could inspect. ## Closing the Loop with Atacama and Telemetry @@ -37,7 +37,7 @@ The workflow connected Atacama agents, monitoring agents, and coding agents with ```mermaid flowchart TD - A[Atacama agents run API and UI flows] --> B[Instrumented ecosystem emits telemetry] + A[Agents use Atacama to run API and UI flows] --> B[Instrumented ecosystem emits telemetry] B --> C[Monitoring agents collect runtime evidence] C --> D[Coding agents compare evidence with the regulatory corpus] D --> E[Implement and verify relevant changes] diff --git a/src/content/projects/website.md b/src/content/projects/website.md index c109bf2..2a743d0 100644 --- a/src/content/projects/website.md +++ b/src/content/projects/website.md @@ -4,7 +4,7 @@ description: "A build-time content aggregator with a small edge backend." repository: "https://github.com/thiagomoura/nthings.dev" website: "https://nthings.dev" order: 1 -tags: [ "content federation", "edge backend" ] +tags: [ "cloudflare", "architecture" ] --- nthings.dev keeps the website separate from the projects it documents. Project repositories remain the source of truth for their own pages and posts; this site assembles them into one consistent publication during the build. From 30b3171ce83273c0c8d7f5e1a7c28da1e218557a Mon Sep 17 00:00:00 2001 From: Thiago Moura Date: Sat, 20 Jun 2026 15:40:29 -0300 Subject: [PATCH 2/5] feat(home): refine hero and status panel layout --- src/pages/index.astro | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/src/pages/index.astro b/src/pages/index.astro index 64c3927..1995170 100644 --- a/src/pages/index.astro +++ b/src/pages/index.astro @@ -26,8 +26,11 @@ const featuredProject = projectCards[0];

nthings.dev

-

Thiago Moura | Stuff Engineer

-

Experiments, thoughts, and anything in between.

+

Thiago Moura

+

Stuff Engineer

+

+ Experiments, thoughts, and anything in between. +

@@ -212,7 +215,7 @@ const featuredProject = projectCards[0]; .home-hero { display: grid; - grid-template-columns: minmax(0, 1fr) minmax(18rem, 0.45fr); + grid-template-columns: minmax(0, 1fr) minmax(28rem, 0.65fr); gap: clamp(1.75rem, 4vw, 3.5rem); align-items: stretch; } @@ -222,6 +225,11 @@ const featuredProject = projectCards[0]; max-width: 44rem; } + .home-hero__description { + margin-top: 0.35rem; + color: var(--color-fg-muted); + } + .home-hero__actions { display: flex; flex-wrap: wrap; From 01800e9820b70ff9a4219078605bff3803b1ae6d Mon Sep 17 00:00:00 2001 From: Thiago Moura Date: Sat, 20 Jun 2026 16:52:04 -0300 Subject: [PATCH 3/5] refactor: cleanup Signed-off-by: Thiago Moura --- astro.config.mjs | 38 +-- biome.json | 64 ++++ package-lock.json | 194 +++++++++++ package.json | 4 + src/components/Adf4jDemo.astro | 2 +- src/components/DirectoryEntry.astro | 4 +- src/components/Footer.astro | 6 +- src/components/Header.astro | 10 +- src/components/Icon.astro | 24 +- src/components/MermaidDiagrams.astro | 328 +----------------- src/components/MetricPanel.astro | 2 +- src/components/MobileDocsNav.astro | 55 +-- src/components/ProjectDocsNav.astro | 12 +- src/components/ProjectPageHeader.astro | 2 +- src/components/SearchModal.astro | 332 +------------------ src/components/StatusIsland.astro | 8 +- src/components/TableOfContents.astro | 173 +--------- src/components/Tabs.astro | 6 +- src/components/ThemeToggle.astro | 54 +-- src/consts.ts | 67 ++-- src/content.config.ts | 34 +- src/layouts/BaseLayout.astro | 39 +-- src/layouts/DocsLayout.astro | 70 +--- src/lib/collections.ts | 32 +- src/lib/confluence.ts | 25 +- src/lib/format-date.ts | 10 +- src/lib/github-stats.test.ts | 24 +- src/lib/github-stats.ts | 96 ++++-- src/lib/html.ts | 12 + src/lib/markdown-preview.ts | 30 +- src/lib/nav.ts | 29 +- src/lib/project-actions.ts | 2 +- src/lib/search.test.ts | 61 ++++ src/lib/search.ts | 108 ++++++ src/lib/site-owned-pages.ts | 14 +- src/pages/404.astro | 4 +- src/pages/about.astro | 4 +- src/pages/api/confluence-adf.json.ts | 26 +- src/pages/blog/[id].astro | 6 +- src/pages/blog/index.astro | 8 +- src/pages/index.astro | 20 +- src/pages/projects/[id].astro | 6 +- src/pages/projects/[project]/[...page].astro | 6 +- src/pages/projects/adf4j/demo.astro | 8 +- src/pages/projects/index.astro | 38 +-- src/pages/search.json.ts | 46 +-- src/scripts/activity-chart.ts | 9 +- src/scripts/adf4j-demo.ts | 140 ++++---- src/scripts/header-scroll.ts | 25 ++ src/scripts/heading-permalinks.ts | 52 +++ src/scripts/init-once.ts | 15 + src/scripts/mermaid.ts | 317 ++++++++++++++++++ src/scripts/mobile-docs-nav.ts | 43 +++ src/scripts/search.ts | 251 ++++++++++++++ src/scripts/theme-toggle.ts | 54 +++ src/scripts/toc.ts | 170 ++++++++++ src/worker.ts | 10 +- tsconfig.json | 12 +- 58 files changed, 1825 insertions(+), 1416 deletions(-) create mode 100644 biome.json create mode 100644 src/lib/html.ts create mode 100644 src/lib/search.test.ts create mode 100644 src/lib/search.ts create mode 100644 src/scripts/header-scroll.ts create mode 100644 src/scripts/heading-permalinks.ts create mode 100644 src/scripts/init-once.ts create mode 100644 src/scripts/mermaid.ts create mode 100644 src/scripts/mobile-docs-nav.ts create mode 100644 src/scripts/search.ts create mode 100644 src/scripts/theme-toggle.ts create mode 100644 src/scripts/toc.ts diff --git a/astro.config.mjs b/astro.config.mjs index c0c88c5..fe74856 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -1,11 +1,11 @@ -import { defineConfig, fontProviders } from 'astro/config'; -import cloudflare from '@astrojs/cloudflare'; -import { unified } from '@astrojs/markdown-remark'; -import adf4jWasm from '@nthings.dev/adf4j-wasm/vite'; -import tailwindcss from '@tailwindcss/vite'; +import cloudflare from "@astrojs/cloudflare"; +import { unified } from "@astrojs/markdown-remark"; +import adf4jWasm from "@nthings.dev/adf4j-wasm/vite"; +import tailwindcss from "@tailwindcss/vite"; +import { defineConfig, fontProviders } from "astro/config"; export default defineConfig({ - site: 'https://nthings.dev', + site: "https://nthings.dev", adapter: cloudflare({ platformProxy: { enabled: true }, }), @@ -13,40 +13,40 @@ export default defineConfig({ plugins: [tailwindcss(), adf4jWasm()], }, markdown: { - syntaxHighlight: 'shiki', + syntaxHighlight: "shiki", // Dual themes: light colors inline, dark swapped via --shiki-dark in global.css. shikiConfig: { themes: { - light: 'github-light', - dark: 'github-dark', + light: "github-light", + dark: "github-dark", }, }, processor: unified({ smartypants: { - dashes: 'oldschool', + dashes: "oldschool", }, }), }, prefetch: { prefetchAll: true, - defaultStrategy: 'hover', + defaultStrategy: "hover", }, fonts: [ { provider: fontProviders.google(), - name: 'Inter', - cssVariable: '--font-body', + name: "Inter", + cssVariable: "--font-body", weights: [400, 500, 600, 700], - subsets: ['latin'], - fallbacks: ['system-ui', '-apple-system', 'sans-serif'], + subsets: ["latin"], + fallbacks: ["system-ui", "-apple-system", "sans-serif"], }, { provider: fontProviders.google(), - name: 'JetBrains Mono', - cssVariable: '--font-code', + name: "JetBrains Mono", + cssVariable: "--font-code", weights: [400, 500], - subsets: ['latin'], - fallbacks: ['ui-monospace', 'monospace'], + subsets: ["latin"], + fallbacks: ["ui-monospace", "monospace"], }, ], }); diff --git a/biome.json b/biome.json new file mode 100644 index 0000000..093aeb9 --- /dev/null +++ b/biome.json @@ -0,0 +1,64 @@ +{ + "$schema": "https://biomejs.dev/schemas/2.5.0/schema.json", + "vcs": { + "enabled": true, + "clientKind": "git", + "useIgnoreFile": true + }, + "files": { + "ignoreUnknown": true, + "includes": [ + "src/**", + "!src/**/*.css", + "astro.config.mjs", + "tsconfig.json", + "package.json" + ] + }, + "formatter": { + "enabled": true, + "indentStyle": "space", + "indentWidth": 2, + "lineWidth": 80, + "lineEnding": "lf" + }, + "linter": { + "enabled": true, + "rules": { + "preset": "recommended", + "style": { + "noNonNullAssertion": "off" + } + } + }, + "javascript": { + "formatter": { + "quoteStyle": "double", + "semicolons": "always" + } + }, + "assist": { + "enabled": true, + "actions": { + "source": { + "organizeImports": "on" + } + } + }, + "overrides": [ + { + "includes": [ + "**/*.astro" + ], + "linter": { + "rules": { + "correctness": { + "noUnusedVariables": "off", + "noUnusedImports": "off", + "noUnusedFunctionParameters": "off" + } + } + } + } + ] +} diff --git a/package-lock.json b/package-lock.json index ea36ca4..f3f8bcb 100644 --- a/package-lock.json +++ b/package-lock.json @@ -22,8 +22,10 @@ "devDependencies": { "@astrojs/check": "0.9.9", "@astrojs/markdown-remark": "7.2.0", + "@biomejs/biome": "2.5.0", "@tailwindcss/vite": "4.3.1", "@types/markdown-it": "14.1.2", + "@types/node": "24.13.0", "@types/prismjs": "1.26.6", "degit": "3.4.7", "tailwindcss": "4.3.1", @@ -294,6 +296,181 @@ "node": ">=6.9.0" } }, + "node_modules/@biomejs/biome": { + "version": "2.5.0", + "resolved": "https://registry.npmjs.org/@biomejs/biome/-/biome-2.5.0.tgz", + "integrity": "sha512-4kURkd9hAPrdDM3C9n82ycYgx8hvQcW6MjKTEejruj8rK0N8P3OPpdy8BvI8kt3KWY4ycF5XtDOrktetEfhfuw==", + "dev": true, + "license": "MIT OR Apache-2.0", + "bin": { + "biome": "bin/biome" + }, + "engines": { + "node": ">=14.21.3" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/biome" + }, + "optionalDependencies": { + "@biomejs/cli-darwin-arm64": "2.5.0", + "@biomejs/cli-darwin-x64": "2.5.0", + "@biomejs/cli-linux-arm64": "2.5.0", + "@biomejs/cli-linux-arm64-musl": "2.5.0", + "@biomejs/cli-linux-x64": "2.5.0", + "@biomejs/cli-linux-x64-musl": "2.5.0", + "@biomejs/cli-win32-arm64": "2.5.0", + "@biomejs/cli-win32-x64": "2.5.0" + } + }, + "node_modules/@biomejs/cli-darwin-arm64": { + "version": "2.5.0", + "resolved": "https://registry.npmjs.org/@biomejs/cli-darwin-arm64/-/cli-darwin-arm64-2.5.0.tgz", + "integrity": "sha512-Mn3Fwi3SA5fgmfCPqmzpWF2DLZnms3BVAhM088nTnGrTZmHS3wwIjcoZPqpXeNgd3DrrLH6xp8vTLIBuJoZiXw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT OR Apache-2.0", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=14.21.3" + } + }, + "node_modules/@biomejs/cli-darwin-x64": { + "version": "2.5.0", + "resolved": "https://registry.npmjs.org/@biomejs/cli-darwin-x64/-/cli-darwin-x64-2.5.0.tgz", + "integrity": "sha512-rg3VPL5P8mYro6pqlXYXuJWph21slVp3SZtAqWSrkZs40d2gTzYmHF8E/X1iTID25btmNKltNDJ926sqVBp7DQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT OR Apache-2.0", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=14.21.3" + } + }, + "node_modules/@biomejs/cli-linux-arm64": { + "version": "2.5.0", + "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-arm64/-/cli-linux-arm64-2.5.0.tgz", + "integrity": "sha512-tl+LW8fdD96/xdeWtWwc82LIOc5CoY7N2AsogLTp5R4ECErYt+8Jl/N68ezN9vzSiqPTxw6vjcihoLPYKZHrlw==", + "cpu": [ + "arm64" + ], + "dev": true, + "libc": [ + "glibc" + ], + "license": "MIT OR Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=14.21.3" + } + }, + "node_modules/@biomejs/cli-linux-arm64-musl": { + "version": "2.5.0", + "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-arm64-musl/-/cli-linux-arm64-musl-2.5.0.tgz", + "integrity": "sha512-vQdM4oSGaf7ZNeGO9w5+Y8SBtyser9M6znxYbm7Ec8wInxJu1WiKxFYZW5Auj2d80bcVvefuGGRxoFOE0eee8g==", + "cpu": [ + "arm64" + ], + "dev": true, + "libc": [ + "musl" + ], + "license": "MIT OR Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=14.21.3" + } + }, + "node_modules/@biomejs/cli-linux-x64": { + "version": "2.5.0", + "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-x64/-/cli-linux-x64-2.5.0.tgz", + "integrity": "sha512-zpEGf4RQbFEh8Vt7OmavLyyOzRbtcE9osCqrS1kfvt8jDvxwhKXLSf7n0ebr/ov0RJ9ssP+lhs6C8a9WwFvrQA==", + "cpu": [ + "x64" + ], + "dev": true, + "libc": [ + "glibc" + ], + "license": "MIT OR Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=14.21.3" + } + }, + "node_modules/@biomejs/cli-linux-x64-musl": { + "version": "2.5.0", + "resolved": "https://registry.npmjs.org/@biomejs/cli-linux-x64-musl/-/cli-linux-x64-musl-2.5.0.tgz", + "integrity": "sha512-+9hIcMngJ+yGUahXqZuZ8CoWKJE9SAZsFsM3QDvXpNsLbXZ9lqVzgBhOk/jTSYkOA0GLP9eu3teukqpLUojHMg==", + "cpu": [ + "x64" + ], + "dev": true, + "libc": [ + "musl" + ], + "license": "MIT OR Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=14.21.3" + } + }, + "node_modules/@biomejs/cli-win32-arm64": { + "version": "2.5.0", + "resolved": "https://registry.npmjs.org/@biomejs/cli-win32-arm64/-/cli-win32-arm64-2.5.0.tgz", + "integrity": "sha512-jB0wAvTLI4itx5VidqVUejPQFhRUxiZ9l9FvZ26D5fl6t3qme+ZB4PD3bTSeL1vZ8NI2Rx/zj6H9zcESuGHKGw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT OR Apache-2.0", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=14.21.3" + } + }, + "node_modules/@biomejs/cli-win32-x64": { + "version": "2.5.0", + "resolved": "https://registry.npmjs.org/@biomejs/cli-win32-x64/-/cli-win32-x64-2.5.0.tgz", + "integrity": "sha512-VT/lF+GId+67j8aDfLkxdxNoVApsPSTbyAtB3jJq0IWTrY77WXfbPfpngxq0bA6JCEv/7k8C9qWjDRKRznDlyw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT OR Apache-2.0", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=14.21.3" + } + }, "node_modules/@braintree/sanitize-url": { "version": "7.1.2", "resolved": "https://registry.npmjs.org/@braintree/sanitize-url/-/sanitize-url-7.1.2.tgz", @@ -3234,6 +3411,16 @@ "@types/unist": "*" } }, + "node_modules/@types/node": { + "version": "24.13.0", + "resolved": "https://registry.npmjs.org/@types/node/-/node-24.13.0.tgz", + "integrity": "sha512-5vtOqGQr4NJKeEzV441FcOi2MeG9UTWq9LqVLGneDdu4vlX17H8kQ2PA2UmNwCUGPVDj4oBjNhS7ReVEIWJJrg==", + "devOptional": true, + "license": "MIT", + "dependencies": { + "undici-types": "~7.18.0" + } + }, "node_modules/@types/prismjs": { "version": "1.26.6", "resolved": "https://registry.npmjs.org/@types/prismjs/-/prismjs-1.26.6.tgz", @@ -7690,6 +7877,13 @@ "node": ">=20.18.1" } }, + "node_modules/undici-types": { + "version": "7.18.2", + "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.18.2.tgz", + "integrity": "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w==", + "devOptional": true, + "license": "MIT" + }, "node_modules/unenv": { "version": "2.0.0-rc.24", "resolved": "https://registry.npmjs.org/unenv/-/unenv-2.0.0-rc.24.tgz", diff --git a/package.json b/package.json index ea5ec61..4754013 100644 --- a/package.json +++ b/package.json @@ -8,6 +8,8 @@ "scripts": { "dev": "astro dev", "check": "astro check", + "lint": "biome check .", + "format": "biome format --write .", "sync:content": "node scripts/sync-content-sources.mjs", "validate:sources": "node scripts/sync-content-sources.mjs --validate-only", "test:content-sync": "node --test \"scripts/content-sources/**/*.test.mjs\"", @@ -33,8 +35,10 @@ "devDependencies": { "@astrojs/check": "0.9.9", "@astrojs/markdown-remark": "7.2.0", + "@biomejs/biome": "2.5.0", "@tailwindcss/vite": "4.3.1", "@types/markdown-it": "14.1.2", + "@types/node": "24.13.0", "@types/prismjs": "1.26.6", "degit": "3.4.7", "tailwindcss": "4.3.1", diff --git a/src/components/Adf4jDemo.astro b/src/components/Adf4jDemo.astro index 63ea794..a5f9182 100644 --- a/src/components/Adf4jDemo.astro +++ b/src/components/Adf4jDemo.astro @@ -111,5 +111,5 @@ const EXAMPLE_URL =
diff --git a/src/components/DirectoryEntry.astro b/src/components/DirectoryEntry.astro index 98cbf6d..752fa36 100644 --- a/src/components/DirectoryEntry.astro +++ b/src/components/DirectoryEntry.astro @@ -1,6 +1,6 @@ --- -import Icon from "./Icon.astro"; -import type { EntryAction } from "../lib/project-actions"; +import Icon from "@/components/Icon.astro"; +import type { EntryAction } from "@/lib/project-actions"; interface Props { title: string; diff --git a/src/components/Footer.astro b/src/components/Footer.astro index a738faf..8837cf1 100644 --- a/src/components/Footer.astro +++ b/src/components/Footer.astro @@ -1,7 +1,7 @@ --- -import Icon from "./Icon.astro"; -import Logo from "./Logo.astro"; -import { SITE, SOCIAL_LINKS } from "../consts"; +import Icon from "@/components/Icon.astro"; +import Logo from "@/components/Logo.astro"; +import { SITE, SOCIAL_LINKS } from "@/consts"; const year = new Date().getFullYear(); --- diff --git a/src/components/Header.astro b/src/components/Header.astro index 5180738..f779e01 100644 --- a/src/components/Header.astro +++ b/src/components/Header.astro @@ -1,9 +1,9 @@ --- -import Icon from "./Icon.astro"; -import Logo from "./Logo.astro"; -import Tabs from "./Tabs.astro"; -import ThemeToggle from "./ThemeToggle.astro"; -import { SOCIAL_LINKS } from "../consts"; +import Icon from "@/components/Icon.astro"; +import Logo from "@/components/Logo.astro"; +import Tabs from "@/components/Tabs.astro"; +import ThemeToggle from "@/components/ThemeToggle.astro"; +import { SOCIAL_LINKS } from "@/consts"; ---
diff --git a/src/components/Icon.astro b/src/components/Icon.astro index 9c986b7..6b3aad5 100644 --- a/src/components/Icon.astro +++ b/src/components/Icon.astro @@ -7,22 +7,21 @@ interface Props { } const ICONS = { - 'arrow-right': + "arrow-right": '', - 'arrow-up-right': + "arrow-up-right": '', - 'chevron-right': + "chevron-right": '', - 'badge-check': + "badge-check": '', - 'code-xml': + "code-xml": '', - 'folder-kanban': + "folder-kanban": '', github: '', - home: - '', + home: '', search: '', monitor: @@ -31,17 +30,16 @@ const ICONS = { linkedin: '', moon: '', - menu: - '', + menu: '', sun: '', - 'sun-moon': + "sun-moon": '', - 'notebook-tabs': + "notebook-tabs": '', } as const; const { name, title, size = 24, class: className, ...rest } = Astro.props; -const iconName = name.replace(/^lucide:/, '') as keyof typeof ICONS; +const iconName = name.replace(/^lucide:/, "") as keyof typeof ICONS; const body = ICONS[iconName]; if (!body) { diff --git a/src/components/MermaidDiagrams.astro b/src/components/MermaidDiagrams.astro index 720c309..c919960 100644 --- a/src/components/MermaidDiagrams.astro +++ b/src/components/MermaidDiagrams.astro @@ -1,329 +1,3 @@ diff --git a/src/components/MetricPanel.astro b/src/components/MetricPanel.astro index 1dc539d..e47a957 100644 --- a/src/components/MetricPanel.astro +++ b/src/components/MetricPanel.astro @@ -1,5 +1,5 @@ --- -import { activityMetricQuery, type GitHubStats } from "../lib/github-stats"; +import { activityMetricQuery, type GitHubStats } from "@/lib/github-stats"; interface Props { stats: GitHubStats; diff --git a/src/components/MobileDocsNav.astro b/src/components/MobileDocsNav.astro index 31c24e4..e928579 100644 --- a/src/components/MobileDocsNav.astro +++ b/src/components/MobileDocsNav.astro @@ -1,8 +1,8 @@ --- import type { MarkdownHeading } from "astro"; -import Icon from "./Icon.astro"; -import type { ProjectNavItem } from "../lib/collections"; -import { isNavItemActive, tocHeadings } from "../lib/nav"; +import Icon from "@/components/Icon.astro"; +import type { ProjectNavItem } from "@/lib/collections"; +import { isActive, tocHeadings } from "@/lib/nav"; interface Props { headings?: MarkdownHeading[]; @@ -44,7 +44,7 @@ const hasToc = toc.length > 0; class:list={[ "mobile-doc-nav__page-link", { - "is-active": isNavItemActive( + "is-active": isActive( pathname, item.href, item.isOverview, @@ -101,50 +101,5 @@ const hasToc = toc.length > 0; } diff --git a/src/components/ProjectDocsNav.astro b/src/components/ProjectDocsNav.astro index 34962bb..ea80325 100644 --- a/src/components/ProjectDocsNav.astro +++ b/src/components/ProjectDocsNav.astro @@ -1,6 +1,6 @@ --- -import type { ProjectNavItem } from "../lib/collections"; -import { isNavItemActive } from "../lib/nav"; +import type { ProjectNavItem } from "@/lib/collections"; +import { isActive } from "@/lib/nav"; interface Props { items: ProjectNavItem[]; @@ -23,15 +23,11 @@ const pathname = Astro.url.pathname; class:list={[ "project-docs-nav__link", { - "is-active": isNavItemActive( - pathname, - item.href, - item.isOverview, - ), + "is-active": isActive(pathname, item.href, item.isOverview), }, ]} aria-current={ - isNavItemActive(pathname, item.href, item.isOverview) + isActive(pathname, item.href, item.isOverview) ? "page" : undefined } diff --git a/src/components/ProjectPageHeader.astro b/src/components/ProjectPageHeader.astro index 8a94e5b..241e3b6 100644 --- a/src/components/ProjectPageHeader.astro +++ b/src/components/ProjectPageHeader.astro @@ -1,6 +1,6 @@ --- -import Icon from "./Icon.astro"; import type { CollectionEntry } from "astro:content"; +import Icon from "@/components/Icon.astro"; interface Props { project: CollectionEntry<"projects">; diff --git a/src/components/SearchModal.astro b/src/components/SearchModal.astro index dfc5d18..7a8d5c8 100644 --- a/src/components/SearchModal.astro +++ b/src/components/SearchModal.astro @@ -1,5 +1,5 @@ --- -import Icon from "./Icon.astro"; +import Icon from "@/components/Icon.astro"; --- @@ -44,333 +44,5 @@ import Icon from "./Icon.astro"; diff --git a/src/components/StatusIsland.astro b/src/components/StatusIsland.astro index baaea59..aff3a57 100644 --- a/src/components/StatusIsland.astro +++ b/src/components/StatusIsland.astro @@ -1,18 +1,20 @@ --- import { env } from "cloudflare:workers"; +import MetricPanel from "@/components/MetricPanel.astro"; import { ACTIVITY_DAYS, activityMetricQuery, getGitHubStats, refreshGitHubStats, -} from "../lib/github-stats"; -import MetricPanel from "./MetricPanel.astro"; +} from "@/lib/github-stats"; const stats = await getGitHubStats(env); // Entries cached before the activity chart shipped lack `dailyActivity`; treat a // missing/empty series as a cold cache and kick a non-blocking refresh. const hasChart = - !!stats && Array.isArray(stats.dailyActivity) && stats.dailyActivity.length > 0; + !!stats && + Array.isArray(stats.dailyActivity) && + stats.dailyActivity.length > 0; if (!hasChart) { Astro.locals.cfContext?.waitUntil( diff --git a/src/components/TableOfContents.astro b/src/components/TableOfContents.astro index e0e5de6..f898031 100644 --- a/src/components/TableOfContents.astro +++ b/src/components/TableOfContents.astro @@ -1,6 +1,6 @@ --- import type { MarkdownHeading } from "astro"; -import { tocHeadings } from "../lib/nav"; +import { tocHeadings } from "@/lib/nav"; interface Props { headings: MarkdownHeading[]; @@ -28,174 +28,5 @@ const toc = tocHeadings(headings); } diff --git a/src/components/Tabs.astro b/src/components/Tabs.astro index 0ad8c2f..6d42358 100644 --- a/src/components/Tabs.astro +++ b/src/components/Tabs.astro @@ -1,7 +1,7 @@ --- -import Icon from "./Icon.astro"; -import { NAV_LINKS } from "../consts"; -import { isActive } from "../lib/nav"; +import Icon from "@/components/Icon.astro"; +import { NAV_LINKS } from "@/consts"; +import { isActive } from "@/lib/nav"; const pathname = Astro.url.pathname; --- diff --git a/src/components/ThemeToggle.astro b/src/components/ThemeToggle.astro index 3c2bbc9..c6c8c95 100644 --- a/src/components/ThemeToggle.astro +++ b/src/components/ThemeToggle.astro @@ -1,5 +1,5 @@ --- -import Icon from "./Icon.astro"; +import Icon from "@/components/Icon.astro"; --- + + `; + + const diagramPanel = document.createElement("div"); + diagramPanel.className = + "mermaid-diagram__panel mermaid-diagram__panel--diagram"; + diagramPanel.dataset.mermaidPanel = "diagram"; + diagramPanel.setAttribute("role", "tabpanel"); + diagramPanel.innerHTML = ` +
+

Rendering diagram

+ `; + + const codePanel = document.createElement("div"); + codePanel.className = "mermaid-diagram__panel mermaid-diagram__panel--code"; + codePanel.dataset.mermaidPanel = "code"; + codePanel.setAttribute("role", "tabpanel"); + codePanel.hidden = true; + + card.appendChild(toolbar); + card.appendChild(diagramPanel); + card.appendChild(codePanel); + pre.replaceWith(card); + codePanel.appendChild(pre); + card.__nthingsRenderMermaid = () => renderCard(card); + + toolbar.addEventListener("click", (event) => { + const button = (event.target as Element).closest( + "[data-mermaid-view]", + ); + if (!button) { + return; + } + setView(card, button.dataset.mermaidView === "code" ? "code" : "diagram"); + }); + + renderCard(card); +} + +function enhanceMermaidBlocks() { + document + .querySelectorAll( + ".prose pre[data-language='mermaid']:not([data-mermaid-enhanced])", + ) + .forEach((pre) => { + void enhanceBlock(pre); + }); +} + +function rerenderMermaidBlocks() { + document.querySelectorAll(".mermaid-diagram").forEach((card) => { + card.__nthingsRenderMermaid?.(); + }); +} + +initOnce("mermaid", () => { + document.addEventListener("astro:page-load", enhanceMermaidBlocks); + + const themeMedia = window.matchMedia("(prefers-color-scheme: dark)"); + themeMedia.addEventListener("change", rerenderMermaidBlocks); + + new MutationObserver((mutations) => { + if (mutations.some((mutation) => mutation.attributeName === "data-theme")) { + rerenderMermaidBlocks(); + } + }).observe(document.documentElement, { attributes: true }); +}); + +enhanceMermaidBlocks(); diff --git a/src/scripts/mobile-docs-nav.ts b/src/scripts/mobile-docs-nav.ts new file mode 100644 index 0000000..b90ff6d --- /dev/null +++ b/src/scripts/mobile-docs-nav.ts @@ -0,0 +1,43 @@ +import { initOnce } from "@/scripts/init-once"; + +initOnce("mobile-docs-nav", () => { + // `toggle` doesn't bubble, so listen in the capture phase. + let openPanel: HTMLDetailsElement | null = null; + let openedAtY = 0; + document.addEventListener( + "toggle", + (event) => { + const details = event.target; + if ( + details instanceof HTMLDetailsElement && + details.closest(".mobile-doc-nav") + ) { + openPanel = details.open ? details : null; + openedAtY = window.scrollY; + } + }, + true, + ); + + document.addEventListener("click", (event) => { + const target = event.target; + if (!openPanel || !(target instanceof Element)) { + return; + } + if (target.closest(".mobile-doc-nav a") || !openPanel.contains(target)) { + openPanel.open = false; + } + }); + + // The open panel is sticky and covers content; close it once the page + // scrolls away beneath it. + window.addEventListener( + "scroll", + () => { + if (openPanel && Math.abs(window.scrollY - openedAtY) > 24) { + openPanel.open = false; + } + }, + { passive: true }, + ); +}); diff --git a/src/scripts/search.ts b/src/scripts/search.ts new file mode 100644 index 0000000..9100ebf --- /dev/null +++ b/src/scripts/search.ts @@ -0,0 +1,251 @@ +import { escapeHtml } from "@/lib/html"; +import { + buildSnippet, + type IndexedDoc, + indexDoc, + type SearchDoc, + scoreDoc, +} from "@/lib/search"; +import { initOnce } from "@/scripts/init-once"; + +const MAX_RESULTS = 12; + +let indexPromise: Promise | null = null; +let activeIndex = 0; +let current: string[] = []; + +const loadIndex = (): Promise => { + indexPromise ??= fetch("/search.json") + .then((r) => (r.ok ? (r.json() as Promise) : [])) + .then((docs) => docs.map(indexDoc)) + .catch(() => [] as IndexedDoc[]); + return indexPromise; +}; + +const dialog = () => + document.getElementById("search-dialog") as HTMLDialogElement | null; +const input = () => + document.getElementById("search-input") as HTMLInputElement | null; +const list = () => document.getElementById("search-results"); + +// Prebuilt per-term regexes (built once per render) wrap matches in . +const highlight = (text: string, regexes: RegExp[]) => { + let out = escapeHtml(text); + for (const re of regexes) { + out = out.replace(re, "$1"); + } + return out; +}; + +const render = async (query: string) => { + const ul = list(); + const empty = document.querySelector( + "[data-search-empty]", + ) as HTMLElement | null; + const hint = document.querySelector( + "[data-search-hint]", + ) as HTMLElement | null; + if (!ul) { + return; + } + + const q = query.trim().toLowerCase(); + if (!q) { + ul.innerHTML = ""; + current = []; + if (empty) { + empty.hidden = true; + } + if (hint) { + hint.hidden = false; + } + return; + } + if (hint) { + hint.hidden = true; + } + + const terms = q.split(/\s+/).filter(Boolean); + const regexes = terms.map( + (t) => new RegExp(`(${t.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")})`, "gi"), + ); + const docs = await loadIndex(); + const ranked = docs + .map((doc) => ({ doc, s: scoreDoc(doc, terms) })) + .filter((r) => r.s > 0) + .sort((a, b) => b.s - a.s) + .slice(0, MAX_RESULTS); + + current = ranked.map((r) => r.doc.url); + activeIndex = 0; + + if (ranked.length === 0) { + ul.innerHTML = ""; + if (empty) { + empty.hidden = false; + } + return; + } + if (empty) { + empty.hidden = true; + } + + ul.innerHTML = ranked + .map( + ({ doc }, i) => ` +
  • + ${escapeHtml(doc.section)} + ${highlight(doc.title, regexes)} + ${highlight(buildSnippet(doc, terms), regexes)} +
    • `, + ) + .join(""); +}; + +const setActive = (next: number) => { + const items = Array.from( + document.querySelectorAll("[data-search-result]"), + ); + if (items.length === 0) { + return; + } + activeIndex = (next + items.length) % items.length; + items.forEach((el, i) => { + const on = i === activeIndex; + el.classList.toggle("is-active", on); + el.setAttribute("aria-selected", String(on)); + if (on) { + el.scrollIntoView({ block: "nearest" }); + } + }); + const inp = input(); + if (inp) { + inp.setAttribute("aria-activedescendant", `search-result-${activeIndex}`); + } +}; + +const openDialog = () => { + const d = dialog(); + if (!d) { + return; + } + if (!d.open) { + d.showModal(); + } + const inp = input(); + if (inp) { + inp.value = ""; + inp.focus(); + } + render(""); +}; + +const closeDialog = () => { + const d = dialog(); + if (d?.open) { + d.close(); + } +}; + +const go = (url: string) => { + closeDialog(); + window.location.href = url; +}; + +initOnce("search", () => { + // Document-level delegation survives view-transition swaps. + document.addEventListener("keydown", (e) => { + if ((e.key === "k" || e.key === "K") && (e.metaKey || e.ctrlKey)) { + e.preventDefault(); + const d = dialog(); + if (d?.open) { + closeDialog(); + } else { + openDialog(); + } + return; + } + if ( + e.key === "/" && + !/^(INPUT|TEXTAREA|SELECT)$/.test((e.target as HTMLElement)?.tagName) && + !dialog()?.open + ) { + e.preventDefault(); + openDialog(); + return; + } + const d = dialog(); + if (!d?.open) { + return; + } + if (e.key === "ArrowDown") { + e.preventDefault(); + setActive(activeIndex + 1); + } else if (e.key === "ArrowUp") { + e.preventDefault(); + setActive(activeIndex - 1); + } else if (e.key === "Enter") { + const url = current[activeIndex]; + if (url) { + e.preventDefault(); + go(url); + } + } + }); + + document.addEventListener("click", (e) => { + const t = e.target as HTMLElement; + if (t.closest("[data-search-trigger]")) { + e.preventDefault(); + openDialog(); + return; + } + if (t.closest("[data-search-close]")) { + closeDialog(); + return; + } + const result = t.closest("[data-search-result]") as HTMLElement | null; + if (result) { + const url = result.getAttribute("data-url"); + if (url) { + go(url); + } + return; + } + // Click on backdrop (the dialog element itself) closes. + if (t.id === "search-dialog") { + closeDialog(); + } + }); + + document.addEventListener("input", (e) => { + const t = e.target as HTMLElement; + if (t.id === "search-input") { + render((t as HTMLInputElement).value); + } + }); + + document.addEventListener("mousemove", (e) => { + if (!dialog()?.open) { + return; + } + const result = (e.target as HTMLElement).closest?.( + "[data-search-result]", + ) as HTMLElement | null; + if (result) { + const idx = Number(result.getAttribute("data-index")); + if (!Number.isNaN(idx) && idx !== activeIndex) { + setActive(idx); + } + } + }); + + // Warm the index on first idle so the first query is instant. + if (typeof window.requestIdleCallback === "function") { + window.requestIdleCallback(() => loadIndex()); + } else { + window.setTimeout(() => loadIndex(), 1200); + } +}); diff --git a/src/scripts/theme-toggle.ts b/src/scripts/theme-toggle.ts new file mode 100644 index 0000000..eeaa59b --- /dev/null +++ b/src/scripts/theme-toggle.ts @@ -0,0 +1,54 @@ +import { initOnce } from "@/scripts/init-once"; + +const order = ["system", "light", "dark"] as const; +const labels = { + system: "Theme: system. Activate to use light theme", + light: "Theme: light. Activate to use dark theme", + dark: "Theme: dark. Activate to use system theme", +} as const; + +const apply = (theme: string) => { + const root = document.documentElement; + if (theme === "light" || theme === "dark") { + root.dataset.theme = theme; + } else { + delete root.dataset.theme; + } + document + .querySelectorAll("[data-theme-toggle]") + .forEach((btn) => { + const label = + labels[(theme as keyof typeof labels) || "system"] ?? labels.system; + btn.setAttribute("aria-label", label); + btn.setAttribute("title", label); + }); +}; + +const sync = () => { + apply(document.documentElement.dataset.theme || "system"); +}; + +initOnce("theme-toggle", () => { + document.addEventListener("click", (e) => { + const btn = (e.target as HTMLElement).closest("[data-theme-toggle]"); + if (!btn) { + return; + } + const cur = document.documentElement.dataset.theme || "system"; + const next = + order[(order.indexOf(cur as (typeof order)[number]) + 1) % order.length]; + try { + if (next === "system") { + localStorage.removeItem("theme"); + } else { + localStorage.setItem("theme", next); + } + } catch { + // Ignore storage failures (private mode, blocked cookies). + } + apply(next); + }); + document.addEventListener("astro:page-load", sync); + document.addEventListener("astro:after-swap", sync); + sync(); +}); diff --git a/src/scripts/toc.ts b/src/scripts/toc.ts new file mode 100644 index 0000000..ddfe843 --- /dev/null +++ b/src/scripts/toc.ts @@ -0,0 +1,170 @@ +import { initOnce } from "@/scripts/init-once"; + +let links: HTMLAnchorElement[] = []; +let headings: HTMLElement[] = []; +let activeId: string | null = null; +let lastHash: string | null = null; +let ticking = false; + +// Cached once per setup/resize so the per-frame scroll handler avoids reflows. +// `thresholds[i]` is the scrollY at which heading i becomes active. +let thresholds: number[] = []; +let firstActivate = 0; + +const measure = () => { + const header = document.querySelector(".site-header"); + const mobileNav = document.querySelector(".mobile-doc-nav"); + const mobileNavVisible = + mobileNav && getComputedStyle(mobileNav).display !== "none"; + const baseHeaderOffset = + (header ? header.getBoundingClientRect().height : 0) + 28; + const headerOffset = mobileNavVisible + ? Math.max(baseHeaderOffset, window.innerHeight * 0.32) + : baseHeaderOffset; + const sy = window.scrollY; + const tops = headings.map((h) => h.getBoundingClientRect().top + sy); + const maxScrollTop = Math.max( + 0, + document.documentElement.scrollHeight - window.innerHeight, + ); + + // scrollY at which each heading reaches the line just below the header. + const natural = tops.map((t) => Math.max(0, t - headerOffset)); + firstActivate = natural[0] ?? 0; + + // Trailing headings on a short page can't reach the line; pull out-of-reach + // thresholds back into range (from the end), kept ordered so each gets a turn. + const n = natural.length; + const gap = Math.max( + 1, + Math.min(0.25 * window.innerHeight, maxScrollTop / n), + ); + const out = natural.slice(); + out[n - 1] = Math.min(out[n - 1], maxScrollTop); + for (let i = n - 2; i >= 0; i--) { + out[i] = Math.min(out[i], out[i + 1] - gap); + } + thresholds = out; +}; + +// Reflect the current section in the URL, except above the first heading. +const syncHash = (id: string, sy: number) => { + const hash = sy + 1 >= firstActivate ? `#${id}` : ""; + if (hash === lastHash) { + return; + } + lastHash = hash; + history.replaceState( + history.state, + "", + location.pathname + location.search + hash, + ); +}; + +const mark = (id: string | null) => { + if (id === activeId) { + return; + } + activeId = id; + const activeLinks: HTMLAnchorElement[] = []; + for (const l of links) { + const on = l.getAttribute("data-toc-link") === id; + l.classList.toggle("is-active", on); + if (on) { + l.setAttribute("aria-current", "true"); + activeLinks.push(l); + } else { + l.removeAttribute("aria-current"); + } + } + const active = + activeLinks.find((l) => l.getClientRects().length > 0) ?? + activeLinks[0] ?? + null; + const rail = active?.closest(".site-toc, .mobile-doc-nav__body"); + // Keep the active link in view inside its independently scrollable rail. + if (active && rail && rail.scrollHeight > rail.clientHeight + 4) { + const lr = active.getBoundingClientRect(); + const rr = rail.getBoundingClientRect(); + if (lr.top < rr.top + 8) { + rail.scrollTop -= rr.top + 8 - lr.top; + } else if (lr.bottom > rr.bottom - 8) { + rail.scrollTop += lr.bottom - (rr.bottom - 8); + } + } +}; + +const update = () => { + ticking = false; + if (headings.length === 0) { + return; + } + // Last heading whose (remapped) activation point has been scrolled past. + const sy = window.scrollY; + let idx = 0; + for (let i = 0; i < thresholds.length; i++) { + if (sy + 1 >= thresholds[i]) { + idx = i; + } else { + break; + } + } + const id = headings[idx].id; + mark(id); + syncHash(id, sy); +}; + +const onScroll = () => { + if (ticking) { + return; + } + ticking = true; + requestAnimationFrame(update); +}; + +const remeasure = () => { + if (headings.length === 0) { + return; + } + measure(); + update(); +}; + +const setup = () => { + links = Array.from( + document.querySelectorAll("[data-toc-link]"), + ); + const seen = new Set(); + const ids = links + .map((l) => l.getAttribute("data-toc-link")) + .filter((id): id is string => { + if (!id || seen.has(id)) { + return false; + } + seen.add(id); + return true; + }); + headings = ids + .map((id) => document.getElementById(id)) + .filter((el): el is HTMLElement => !!el); + activeId = null; + lastHash = null; + if (headings.length === 0) { + return; + } + measure(); + update(); +}; + +initOnce("toc", () => { + window.addEventListener("scroll", onScroll, { passive: true }); + window.addEventListener("resize", remeasure, { passive: true }); + // Late image/asset loads can shift heading positions after first paint. + window.addEventListener("load", remeasure); + // Web-font swaps shift heading positions; re-measure once they settle. + if (document.fonts?.ready) { + document.fonts.ready.then(remeasure); + } + document.addEventListener("astro:page-load", setup); + setup(); +}); diff --git a/src/worker.ts b/src/worker.ts index b6164d4..6f6033a 100644 --- a/src/worker.ts +++ b/src/worker.ts @@ -1,9 +1,13 @@ -import astro from '@astrojs/cloudflare/entrypoints/server'; -import { refreshGitHubStats } from './lib/github-stats'; +import astro from "@astrojs/cloudflare/entrypoints/server"; +import { refreshGitHubStats } from "@/lib/github-stats"; export default { fetch: astro.fetch, - async scheduled(_controller: ScheduledController, env: Env, ctx: ExecutionContext) { + async scheduled( + _controller: ScheduledController, + env: Env, + ctx: ExecutionContext, + ) { ctx.waitUntil(refreshGitHubStats(env)); }, } satisfies ExportedHandler; diff --git a/tsconfig.json b/tsconfig.json index cf126fb..9512564 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -1,11 +1,21 @@ { "extends": "astro/tsconfigs/strict", "compilerOptions": { + "types": [ + "markdown-it", + "node", + "prismjs" + ], "lib": [ "ESNext", "DOM", "DOM.Iterable" - ] + ], + "paths": { + "@/*": [ + "./src/*" + ] + } }, "include": [ ".astro/types.d.ts", From 584e6966291e75e08242065e14cf9c7832f39328 Mon Sep 17 00:00:00 2001 From: Thiago Moura Date: Sat, 20 Jun 2026 17:28:25 -0300 Subject: [PATCH 4/5] fix(scripts): correct TOC threshold clamping and link mermaid tab ARIA - toc: drop the 1px gap floor and skip remapping on non-scrollable pages so threshold remapping can't push earlier thresholds negative and mark a later heading active at the top of the page - mermaid: give each diagram unique ids and wire aria-controls/aria-labelledby between tabs and panels so assistive tech announces the relationship Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_016SPYm9CnBdi9BzuUfjW7Xt --- src/scripts/mermaid.ts | 17 +++++++++++++++-- src/scripts/toc.ts | 18 +++++++++++------- 2 files changed, 26 insertions(+), 9 deletions(-) diff --git a/src/scripts/mermaid.ts b/src/scripts/mermaid.ts index 5b3edc3..d8f181a 100644 --- a/src/scripts/mermaid.ts +++ b/src/scripts/mermaid.ts @@ -13,6 +13,7 @@ const pendingRenders = new WeakMap>(); let mermaidPromise: Promise | undefined; let prismPromise: Promise | undefined; let renderIndex = 0; +let cardIndex = 0; function loadMermaid() { mermaidPromise ??= import("mermaid").then((module) => module.default); @@ -240,20 +241,30 @@ async function enhanceBlock(pre: HTMLPreElement) { card.className = "mermaid-diagram"; card.dataset.view = "diagram"; + // Unique per card so multiple diagrams on a page don't share ids when wiring + // each tab to the panel it controls (and vice versa) for assistive tech. + const base = `nthings-mermaid-${cardIndex++}`; + const diagramTabId = `${base}-tab-diagram`; + const codeTabId = `${base}-tab-code`; + const diagramPanelId = `${base}-panel-diagram`; + const codePanelId = `${base}-panel-code`; + const toolbar = document.createElement("figcaption"); toolbar.className = "mermaid-diagram__toolbar"; toolbar.setAttribute("role", "tablist"); toolbar.setAttribute("aria-label", "Mermaid diagram view"); toolbar.innerHTML = ` - - + + `; const diagramPanel = document.createElement("div"); diagramPanel.className = "mermaid-diagram__panel mermaid-diagram__panel--diagram"; diagramPanel.dataset.mermaidPanel = "diagram"; + diagramPanel.id = diagramPanelId; diagramPanel.setAttribute("role", "tabpanel"); + diagramPanel.setAttribute("aria-labelledby", diagramTabId); diagramPanel.innerHTML = `

    Rendering diagram

    @@ -262,7 +273,9 @@ async function enhanceBlock(pre: HTMLPreElement) { const codePanel = document.createElement("div"); codePanel.className = "mermaid-diagram__panel mermaid-diagram__panel--code"; codePanel.dataset.mermaidPanel = "code"; + codePanel.id = codePanelId; codePanel.setAttribute("role", "tabpanel"); + codePanel.setAttribute("aria-labelledby", codeTabId); codePanel.hidden = true; card.appendChild(toolbar); diff --git a/src/scripts/toc.ts b/src/scripts/toc.ts index ddfe843..99c6cb2 100644 --- a/src/scripts/toc.ts +++ b/src/scripts/toc.ts @@ -34,15 +34,19 @@ const measure = () => { // Trailing headings on a short page can't reach the line; pull out-of-reach // thresholds back into range (from the end), kept ordered so each gets a turn. + // A non-scrollable page keeps its natural thresholds so the first heading + // stays active at the top instead of every threshold collapsing toward 0. const n = natural.length; - const gap = Math.max( - 1, - Math.min(0.25 * window.innerHeight, maxScrollTop / n), - ); const out = natural.slice(); - out[n - 1] = Math.min(out[n - 1], maxScrollTop); - for (let i = n - 2; i >= 0; i--) { - out[i] = Math.min(out[i], out[i + 1] - gap); + if (maxScrollTop > 0) { + // Sub-pixel gaps are intentional: a 1px minimum on very short pages (or many + // headings vs. little scroll range) drives earlier thresholds negative, which + // would mark a later heading active at the top. + const gap = Math.min(0.25 * window.innerHeight, maxScrollTop / n); + out[n - 1] = Math.min(out[n - 1], maxScrollTop); + for (let i = n - 2; i >= 0; i--) { + out[i] = Math.min(out[i], out[i + 1] - gap); + } } thresholds = out; }; From a0082c92cbb0870a0c8bc131225e9299bd807a3a Mon Sep 17 00:00:00 2001 From: Thiago Moura Date: Sat, 20 Jun 2026 17:45:56 -0300 Subject: [PATCH 5/5] fix(scripts): clear stale mobile-nav ref and harden search highlight - mobile-docs-nav: reset the cached openPanel/openedAtY on astro:after-swap so handlers don't act on (or pin) a
    detached by a view transition - search: highlight against the raw text with one combined matcher, escaping only around matches, so a later term can't match markup/entities an earlier term inserted (e.g. "code a" no longer produces broken HTML) Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_016SPYm9CnBdi9BzuUfjW7Xt --- src/scripts/mobile-docs-nav.ts | 8 ++++++++ src/scripts/search.ts | 33 ++++++++++++++++++++++----------- 2 files changed, 30 insertions(+), 11 deletions(-) diff --git a/src/scripts/mobile-docs-nav.ts b/src/scripts/mobile-docs-nav.ts index b90ff6d..44f9828 100644 --- a/src/scripts/mobile-docs-nav.ts +++ b/src/scripts/mobile-docs-nav.ts @@ -4,6 +4,14 @@ initOnce("mobile-docs-nav", () => { // `toggle` doesn't bubble, so listen in the capture phase. let openPanel: HTMLDetailsElement | null = null; let openedAtY = 0; + + // A view-transition swap detaches the previous page's
    ; drop the + // cached reference so the handlers don't operate on (or pin) stale DOM. + document.addEventListener("astro:after-swap", () => { + openPanel = null; + openedAtY = 0; + }); + document.addEventListener( "toggle", (event) => { diff --git a/src/scripts/search.ts b/src/scripts/search.ts index 9100ebf..05bf207 100644 --- a/src/scripts/search.ts +++ b/src/scripts/search.ts @@ -28,13 +28,21 @@ const input = () => document.getElementById("search-input") as HTMLInputElement | null; const list = () => document.getElementById("search-results"); -// Prebuilt per-term regexes (built once per render) wrap matches in . -const highlight = (text: string, regexes: RegExp[]) => { - let out = escapeHtml(text); - for (const re of regexes) { - out = out.replace(re, "$1"); +// Wrap query matches in , matching against the raw text and escaping only +// around each match. Escaping after matching keeps inserted markup (and HTML +// entities) from being re-matched, which produced broken HTML for queries whose +// terms overlapped the tags an earlier term inserted (e.g. "code a"). +const highlight = (text: string, matcher: RegExp | null) => { + if (!matcher) { + return escapeHtml(text); } - return out; + let out = ""; + let last = 0; + for (const match of text.matchAll(matcher)) { + out += `${escapeHtml(text.slice(last, match.index))}${escapeHtml(match[0])}`; + last = match.index + match[0].length; + } + return out + escapeHtml(text.slice(last)); }; const render = async (query: string) => { @@ -66,9 +74,12 @@ const render = async (query: string) => { } const terms = q.split(/\s+/).filter(Boolean); - const regexes = terms.map( - (t) => new RegExp(`(${t.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")})`, "gi"), - ); + // One combined matcher; longest term first so it wins over a shorter prefix. + const pattern = [...terms] + .sort((a, b) => b.length - a.length) + .map((t) => t.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")) + .join("|"); + const matcher = pattern ? new RegExp(pattern, "gi") : null; const docs = await loadIndex(); const ranked = docs .map((doc) => ({ doc, s: scoreDoc(doc, terms) })) @@ -97,8 +108,8 @@ const render = async (query: string) => { class="search-result${i === 0 ? " is-active" : ""}" data-search-result data-url="${escapeHtml(doc.url)}" data-index="${i}"> ${escapeHtml(doc.section)} - ${highlight(doc.title, regexes)} - ${highlight(buildSnippet(doc, terms), regexes)} + ${highlight(doc.title, matcher)} + ${highlight(buildSnippet(doc, terms), matcher)} `, ) .join("");