@escape-game-over/atlas 0.1.1 → 0.1.2

package/README.md

@@ -305,6 +305,7 @@ src/            the package — see the export map above for what is reachable
 bin/            the `atlas` CLI
 tests/          runtime behaviour — what a merge resolves to, what a builder rejects
 type-tests/     what the types must reject, via @ts-expect-error
+checks/astro/   the astro check root for src/astro — config only, nothing to read
 docs/           the long-form reasoning
 examples/       two complete consumers
 ```
@@ -321,16 +322,34 @@ npm test            # everything else
 `npm test` runs three suites in order, and stops at the first failure:
 
 ```bash
-npm run test:types      # tsc --noEmit — the package compiles, and 137 type
-                        #   assertions in type-tests/ still reject what they must
+npm run test:types      # tsc --noEmit, then astro check — the package compiles,
+                        #   and 137 type assertions in type-tests/ still reject
+                        #   what they must
 npm run test:unit       # vitest — 355 runtime tests
 npm run test:examples   # every example, every deployment: astro check + astro build
 npm run test:watch      # vitest, watching
 ```
 
-`test:types` is also the isolation contract: no consumer paths, no ambient types,
-`src/astro/` excluded. If it passes, the package is genuinely independent of
-anything consuming it.
+`test:types` runs two passes, and the split is the isolation contract. The `tsc`
+pass — no consumer paths, no ambient types, `src/astro/` excluded — is what
+proves the package is genuinely independent of anything consuming it.
+
+The `astro check` pass covers `src/astro/`, the one directory that cannot meet
+that bar. It needs `astro/client` for `astro:assets` and `ImageMetadata`, and
+`MetaTags.astro` needs a checker that can parse `.astro` at all — `tsc` reads
+zero `.astro` files no matter how they are globbed. Without this pass the one
+component the package ships is checked by nothing: `astro check` in
+`test:examples` only ever walks an example's own `src/`, so it never reaches it,
+and a type error there passes the entire gate.
+
+It runs from [`checks/astro`](checks/astro) rather than `src/astro` for one
+practical reason: `astro check` writes a `.astro/` types directory and a
+1 MB Vite cache beside whatever it is rooted at, and `files: ["src"]` would
+publish both. The `tsconfig.json` there adds nothing — it extends
+`src/astro/tsconfig.json` and only widens the glob, so the rules stay in one
+place. `src/astro/tsconfig.json` is what an editor finds; without it, opening
+`MetaTags.astro` resolves against the root config, which supplies no ambient
+types, and every prop degrades to `any`.
 
 `test:examples` **builds every deployment**, not just type-checks one, and both
 halves of that matter. `astro check` only ever sees whichever project
@@ -342,6 +361,28 @@ merged data or on a real file. Type-checking alone would pass all of it.
 
 The whole gate is about 15 seconds.
 
+### Open Biome issues
+
+Three things the `.astro` setup works around rather than fixes. Each is open
+upstream, and each explains a rule that would otherwise read as an oversight.
+
+- [biomejs/biome#10321](https://github.com/biomejs/biome/issues/10321) —
+  *Astro: not formatting inside `{( … )}`* (`S-Bug-confirmed`). Biome formats
+  `.astro` markup but not the interior of an expression, so the 31 `.map()`
+  blocks across the templates keep their own indentation while the markup around
+  them follows `indentWidth`. Hand-aligned until this lands.
+- [biomejs/biome#9944](https://github.com/biomejs/biome/issues/9944) —
+  *Astro: Parser error inside expression*. Biome parses the inside of `{ }` as
+  strict JSX, which rejects things Astro itself accepts. This is why every
+  comment in a template is `{/* … */}` and never `<!-- … -->`: an HTML comment
+  anywhere inside an expression is a parse error, and the JSX form is also
+  stripped from the built HTML rather than shipped to readers.
+- [biomejs/biome#11275](https://github.com/biomejs/biome/issues/11275) —
+  *LSP formatting deletes Astro frontmatter/HTML in multi-project workspaces*
+  (`S-Bug-confirmed`). It names `html.experimentalFullSupportEnabled`, which this
+  repository sets, and a workspace of several projects, which this repository is.
+  The gate above is CLI-only and unaffected; editor format-on-save is the thing
+  to be careful with.
 
 ## Documentation
 
@@ -349,8 +390,8 @@ The whole gate is about 15 seconds.
   how the type tests and runtime tests divide the work.
 - [`docs/share-images.md`](docs/share-images.md) — what each social surface
   crops, and why one 1200×630 image serves all of them.
-- [`docs/toolchain.md`](docs/toolchain.md) — the pinned TypeScript, the Biome
-  trade-off for `.astro`, and the traps.
+- [`docs/toolchain.md`](docs/toolchain.md) — the pinned TypeScript, the two
+  switches `.astro` support needs from Biome, and the traps.
 - [`docs/NOT-BUILT.md`](docs/NOT-BUILT.md) — what we deliberately do not build,
   as questions and answers. Kept beside the code rather than in a backlog,
   because a backlog is a list of things still to do and every one of these is a

package/docs/NOT-BUILT.md

@@ -281,6 +281,66 @@ wrote — the files it emits at build time, and the slash-free URLs it publishes
 as canonical — so a project that changed one would silently break the other. The
 integration sets all three and logs that it did, so nothing is hidden.
 
+### Should the generated files be routes, so a dev server keeps them current?
+
+**No. They stay files written at `astro:build:done`, and in dev they are a
+snapshot of the moment the config was evaluated.**
+
+Start with the fact underneath, because it is not written down anywhere else and
+it surprises people. `astro.config.ts` imports `site`, `redirects` and `llms`,
+and Astro loads that config through a throwaway Vite server without recording
+what it imported — `core/config/vite-load.js` returns the module and closes the
+server. A dev server restarts only for the config file itself, `.astro/settings.json`,
+or an exact path in `settings.watchFiles`, which holds `package.json` and the
+tsconfig sources and nothing else. So editing `config/messages.ts` refreshes
+every page that renders it, through Vite's module graph, and leaves the same
+string in `llms.txt` untouched until you restart. **Builds are never affected**:
+`astro build` evaluates the config in a fresh process. This is a dev-only
+staleness, and `generate()` rebuilding per request does not cure it — it derives
+the same answer from the same frozen inputs.
+
+Routes look like the fix, and they genuinely are one. Measured on the b2b
+example: an injected endpoint that reaches the site through the *page* graph
+served the edited string immediately, side by side with the integration's
+middleware still serving the old one.
+
+**And `_redirects` can be one of those routes** — worth recording, because the
+old comment in `site-routes.ts` said it could not be, and that was wrong. Astro's
+page walker skips a *filename* beginning with `_`; an injected route names its
+pattern and its entrypoint separately, so the underscore lands only on the URL.
+It was built, served in dev, and written to `dist/_redirects` by the route alone.
+
+What sinks it is reaching the caller's live `site` from an entrypoint compiled
+into another module graph. Two ways, both built and both rejected:
+
+- **Name the modules.** `siteRoutes({ modules: { site, redirects, llms } })`.
+  Dies on contact with a real project: `redirects` and `llms` are values computed
+  from files scattered wherever a project put them, and a list that misses one is
+  worse than no list — a control test confirmed the neighbours refresh while the
+  missed file stays stale, which teaches you the wrong rule about when dev can be
+  trusted.
+- **Skip the names.** Each endpoint imports the consumer's `astro.config.ts` for
+  its side effect, which re-enters `siteRoutes()` in the page graph, and reads the
+  options back out of a `Symbol.for` slot on `globalThis`. This works — all four
+  files, fresh in dev, correct in a build, whole suite green — and it is the
+  version that was actually written. It was still thrown away: a global written by
+  one module graph and read by another, kept correct by importing a config file
+  for its side effects, is only safe while everyone remembers why. It also made
+  `site-routes.ts` longer, not shorter, and entangled the orphan warning with
+  codegen badly enough that an unrelated test needed a temp directory.
+
+So the cost of the current design is one line of dev output being a snapshot, and
+the cost of curing it is a mechanism nobody can infer from reading it. The first
+is cheaper.
+
+**What would flip it.** Astro tracking its config's dependency graph — then
+`addWatchFile` over those paths would restart the server on any config edit and
+the whole question dissolves, with no cleverness anywhere. Worth re-checking on a
+major Astro release. Failing that, endpoint files written by each consuming
+project (four small ones per repo, each importing its own `site`) buy the same
+freshness with no mechanism at all — the trade is four files against a snapshot,
+and today the snapshot wins.
+
 ### Should `/` serve a meta-refresh stub when every locale is prefixed?
 
 **No. A real 301 in `_redirects`.**
@@ -319,6 +379,30 @@ Reading order is the relationship a reader actually has with an article, so a
 post carries newer/older links instead. Browser back covers "the list I was
 looking at" better than any link can.
 
+### Should `/en-US/about-us` redirect when the default locale is unprefixed?
+
+**No. Only `/en-US` itself does.**
+
+With `prefixDefaultLocale: false` the default locale is served at `/about-us`
+and nothing is built under `/en-US/`. Claiming the prefixed root is one rule and
+answers the URL people actually type, having seen every other language wear a
+prefix. Claiming the pages under it is a different proposition: a rule per page,
+and slugs are translated per locale, so the URL a reader lands on by editing
+`/el-GR/sxetika-me-emas` down to English keeps the *Greek* slug —
+`/en-US/sxetika-me-emas`. Covering that means the cross product of the prefix
+with every locale's spelling of every slug, which is a `_redirects` of hundreds
+against the 2000 a host reads, all of it for URLs nothing has ever linked.
+
+This was built first, in the one-rule-per-default-locale-page form, which is
+worth naming because it looks complete and is not: it answers `/en-US/about-us`
+and misses `/en-US/sxetika-me-emas`, so the case that motivated it is the case
+it does not cover.
+
+A wildcard would sidestep the count — `/en-US/* /:splat 301` is one line — but
+not the translated slug, and it is Cloudflare's syntax rather than something
+`ResolvedRedirect` can carry to another host. The pages get the 404 page, which
+is what it is for.
+
 ---
 
 ## Adding to this

package/docs/toolchain.md

@@ -16,19 +16,29 @@ means most of what this package guarantees stops being verified in the one place
 it matters. Track
 [withastro/roadmap#1321](https://github.com/withastro/roadmap/discussions/1321).
 
-## `noUnusedVariables` / `noUnusedImports` are off for `.astro`
+## `.astro` runs on Biome's full HTML support, and needs both switches
 
-Biome's Astro support has two modes and neither does both jobs:
-
-- **Default mode** formats and lints frontmatter, but cannot see the template —
-  so every const the markup uses is reported unused.
-- **`html.experimentalFullSupportEnabled`** lints accurately, but no longer
-  formats frontmatter.
+```json
+"html": {
+    "experimentalFullSupportEnabled": true,
+    "formatter": { "enabled": true }
+}
+```
 
-This repo takes the default mode plus Biome's documented rule exclusions, and
-nothing is lost: `astro check` reports unused frontmatter variables and imports
-itself (`ts(6133)`) while correctly resolving template usage. The two tools cover
-each other.
+One without the other is the trap. `experimentalFullSupportEnabled` moves
+`.astro` onto the HTML-family path, where the formatter is off unless it is
+asked for — so setting only the first drops every `.astro` file from
+`biome format` entirely. It reports them as *ignored* rather than as errors, so
+`check-fmt` stays green while nothing is being formatted at all.
+
+With both set, `noUnusedVariables` and `noUnusedImports` resolve template usage
+correctly: a const the markup uses is not reported, a genuinely unused one is.
+The `overrides` block that used to switch them off for `.astro` is gone. It
+existed because the old default mode could not see the template and called every
+const the markup uses unused; keeping it now would only suppress rules that
+work. Removing it while still in default mode is the one combination to avoid —
+the false positives come back as `FIXABLE`, and `lint:fix` will rename a const
+the template still references.
 
 ## `biome.json` must not contain `//` comments
 
@@ -46,8 +56,9 @@ single catch-all page in each example, from the route registry.
 ## Formatting
 
 4-space indent, double quotes, `es5` trailing commas, LF. Biome formats `.astro`
-frontmatter but leaves the markup below it alone, which is why the templates in
-the examples are hand-aligned.
+frontmatter *and* markup, but not the inside of a `{ }` expression — so the
+`.map()` blocks in the examples stay hand-aligned while the markup around them
+follows `indentWidth`. See the open Biome issues in the README.
 
 ```bash
 npm run lint       # check
@@ -71,13 +82,29 @@ The practical consequence: `/about-us` is `about-us.html`, not
 `about-us/index.html`. `dist/` is plain files — any static host works, and no
 server rules are required.
 
-## Claiming `/` when every locale is prefixed
-
-When a project sets `prefixDefaultLocale: true`, nothing owns `/` and no page is
-generated for it. `site.redirects()` claims it with a real **301** in
-`_redirects` instead, pointing at the default locale's root — a redirect rather
+## The URLs `site.redirects()` claims on its own
+
+Two of this toolchain's decisions leave a URL unpublished that people still ask
+for. Each is answered with a real **301** written into `_redirects` alongside
+the rules a project states — derived from the route table, so a retranslated
+slug or a switched-off page moves the rule with the page:
+
+| Asked for      | Answered with | Because                                        |
+| -------------- | ------------- | ---------------------------------------------- |
+| `/`            | `/en-US`      | `prefixDefaultLocale: true` leaves `/` unowned |
+| `/en-US`       | `/`           | `prefixDefaultLocale: false` leaves it unbuilt |
+| `/news/page/1` | `/news`       | page one is the bare slug, never `page/1`      |
+
+The first two are the same rule in its two directions: whichever root the
+routing mode does not serve points at the one it does. Both together cost one
+rule; the third costs one per paginated list per language. Nothing here scales
+with the number of pages a site has — see [`NOT-BUILT.md`](NOT-BUILT.md) for why
+the prefixed form of every *page* is left to the 404 instead. A project that
+states its own rule for one of these paths keeps it: the inferred one steps
+aside.
+
+The root points at whichever route has an empty slug, so nothing has to name a
+"home" page, and no rule is written if no route claims it. A redirect rather
 than a rendered stub, so a crawler is told the destination is canonical instead
-of following a refresh.
-
-The target is whichever route has an empty slug, so nothing has to name a "home"
-page. See [`NOT-BUILT.md`](NOT-BUILT.md) for why no meta-refresh stub is emitted.
+of following a refresh — `NOT-BUILT.md` again for why no meta-refresh stub is
+emitted.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.1",
+    "version": "0.1.2",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,
@@ -15,7 +15,11 @@
         ".": "./src/index.ts",
         "./astro": "./src/astro/index.ts",
         "./astro/images": "./src/astro/images.ts",
+        "./astro/carousel": "./src/astro/carousel.ts",
         "./astro/consent": "./src/astro/consent.ts",
+        "./astro/dev-log": "./src/astro/dev-log.ts",
+        "./astro/dom": "./src/astro/dom.ts",
+        "./astro/element": "./src/astro/element.ts",
         "./astro/meta-tags": "./src/astro/MetaTags.astro"
     },
     "bin": {
@@ -29,23 +33,23 @@
     ],
     "scripts": {
         "test": "npm run test:types && npm run test:unit && npm run test:examples",
-        "test:types": "tsc --noEmit",
+        "test:types": "tsc --noEmit && astro check --root checks/astro",
         "test:unit": "vitest run",
         "test:watch": "vitest",
         "test:examples": "npm run test --workspaces",
         "lint": "biome check .",
         "lint:fix": "biome check --write .",
-        "format": "biome format --write .",
+        "fmt": "biome format --write .",
         "check-fmt": "biome check . --error-on-warnings"
     },
     "peerDependencies": {
         "astro": ">=7"
     },
     "devDependencies": {
-        "@biomejs/biome": "2.5.8",
+        "@biomejs/biome": "2.5.10",
         "@types/node": "26.2.0",
-        "astro": "7.2.2",
+        "astro": "7.2.4",
         "typescript": "6.0.3",
-        "vitest": "4.1.10"
+        "vitest": "4.1.11"
     }
 }

package/src/astro/MetaTags.astro

@@ -39,8 +39,7 @@ interface Props {
 const { tags } = Astro.props;
 ---
 
-{
-  tags.map((tag) => {
+{tags.map((tag) => {
     if (tag.kind === "title") return <title>{tag.text}</title>;
     if (tag.kind === "link") return <link {...tag.attrs} />;
     // `set:html` writes the JSON raw. `serializeJsonLd` has already replaced
@@ -83,5 +82,4 @@ const { tags } = Astro.props;
     // copied into every project.
     const unhandled: never = tag;
     throw new Error(`Unhandled meta tag: ${JSON.stringify(unhandled)}`);
-  })
-}
+  })}