@escape-game-over/atlas 0.1.24 → 0.1.26

package/README.md

@@ -61,7 +61,7 @@ Linking to a page the active deployment switched off is a compile error, not a
 One file per deployment, saying only what differs:
 
 ```ts
-export default defineProject(config, defaultMessages, defaultRoutes, {
+export default atlas.project(defaultMessages, defaultRoutes, {
   url: "https://acme.example",
   siteName: "Acme Rome",
   icon,
@@ -92,22 +92,22 @@ never writes a type argument:
 
 ```ts
 // 1. which languages exist, how URLs are shaped
-export default defineSiteConfig({ locales: {...}, defaultRouting: {...} })
+export const atlas = defineSite({ locales: {...}, defaultRouting: {...} })
 
 // 2. the base copy and routes
-export const baseMessages = defineMessages(config, {...})
-export const baseRoutes   = defineRoutes(config, {...})
+export const baseMessages = atlas.messages({...})
+export const baseRoutes   = atlas.routes({...})
 
 // 3. one deployment
-export default defineProject(config, baseMessages, baseRoutes, {...})
+export default atlas.project(baseMessages, baseRoutes, {...})
 
 // 4. the API the pages use
-export const site = createSite(config, baseMessages, baseRoutes, project)
+export const site = atlas.site(baseMessages, baseRoutes, project)
 ```
 
 Step 4 returns `t()`, `rich()`, `plain()`, `pathFor()`, `urlFor()`, `fileUrl()`,
-`alternatesFor()`, `localeLinksFor()`, `metaFor()`, `breadcrumbFor()`,
-`staticPaths()`, `routes`, `entries`, `sitemap()`, `robots()`, `llms()` and
+`localeLinksFor()`, `metaFor()`, `breadcrumbFor()`,
+`getStaticPaths()`, `routes`, `sitemap()`, `robots()`, `llms()` and
 `redirects()` already wired.
 
 `t()` is bound to a locale and knows each message's `{placeholders}` from its
@@ -233,7 +233,7 @@ worded.
 The same question answers it every time: *would this differ between two pages of
 the same site?*
 
-| Per page — passed to `metaFor()` | Site-level — declared in `defineProject()` |
+| Per page — passed to `metaFor()` | Site-level — declared in `atlas.project()` |
 | -------------------------------- | ------------------------------------------ |
 | `title`, `description`           | `siteName`, `twitterSite`                  |
 | `image` (asset **and** its alt)  | `icon`, `themeColor`, `colorScheme`        |
@@ -251,16 +251,9 @@ actually renders, and why `twitter:card` is pinned.
 
 A project switches routes off. Anything defined *alongside* a route then has two
 ways to rot: the page is built and its config is missing, or the page is gone and
-its config lingers. Two types, differing only in how many routes they speak for:
+its config lingers. `PerRoute<typeof site, T>` rejects both.
 
-|                       | `PerRoute<typeof site, T>`           | `WhenEnabled<typeof site, "careers", T>`         |
-| --------------------- | ------------------------------------ | ------------------------------------------------ |
-| Shape                 | a table keyed by route id            | a single value                                   |
-| Says                  | "every built route has one of these" | "this value belongs to *that* page"              |
-| When the route is off | that key is rejected                 | the type is `never` — the field cannot be filled |
-| Use with              | `satisfies`                          | a normal annotation                              |
-
-`PerRoute` must be used with `satisfies`, not as an annotation: excess-property
+It must be used with `satisfies`, not as an annotation: excess-property
 checking is what catches the stale half, and only an object literal checked
 against a known target gets it.
 
@@ -269,8 +262,6 @@ const heroes = {
     home: { variant: "wide" },
     about: { variant: "tall" },
 } satisfies PerRoute<typeof site, Hero>;   // ✗ if `about` is off, ✗ if `contact` is on
-
-const careers: WhenEnabled<typeof site, "careers", Careers> = { ats: "…" };  // ✗ if off
 ```
 
 ## The rules this package keeps
@@ -299,16 +290,8 @@ const careers: WhenEnabled<typeof site, "careers", Careers> = { ats: "…" };  /
   ".":                  "./src/index.ts",
   "./astro":                  "./src/astro/index.ts",
   "./astro/images":           "./src/astro/images.ts",
-  "./astro/background-video": "./src/astro/background-video.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/filters":          "./src/astro/filters.ts",
-  "./astro/filters-view":     "./src/astro/filters-view.ts",
-  "./astro/meta-tags":        "./src/astro/MetaTags.astro",
-  "./astro/youtube":          "./src/astro/youtube.ts"
+  "./astro/document":         "./src/astro/Document.astro",
+  "./client":                 "./src/astro/client.ts"
 }
 ```
 
@@ -324,27 +307,27 @@ may use `node:` built-ins but not `astro:assets`. `./astro/images` is the
 opposite: it runs inside the build, from a page, and is unusable from a config.
 Merging them breaks whichever caller loads first.
 
-The rest of `astro/` is the browser half — `carousel`, `filters`, `filters-view`,
-`youtube`, `background-video`, `consent`, `element`, `dom`, `dev-log` — which
-runs in a reader's browser rather
-than in the build, and is separate again for the same reason: none of it can be
-reached from a config, and none of it draws. See
+`./client` is the browser half — `carousel`, `filters`, `filters-view`,
+`youtube`, `background-video`, `consent`, `element` — one path
+for all of it. See
 [`docs/client-scripts.md`](docs/client-scripts.md).
 
 **The package ships TypeScript source, and there is no build step.**
-`MetaTags.astro` could not go through `tsc` anyway, and Astro's own
+`Document.astro` could not go through `tsc` anyway, and Astro's own
 `tsconfigs/base.json` already sets `allowImportingTsExtensions`, so every
 consumer gets it for free.
 
 ## The `atlas` command
 
 ```bash
-atlas use <project>          # copies config/projects/<name> -> config/project
+atlas use <project>          # links config/project -> config/projects/<name>
 atlas use --fallback rome    # only when nothing else named one
 ```
 
-The whole directory is copied, so extra files and nested folders come along
-without touching the tool — the contract is just that it contains `project.ts`.
+A link, not a copy: an edit made through `config/project` lands in the real
+file. A directory junction on Windows, which needs no admin rights. Ignore it with
+`**/config/project` — no trailing slash, since git sees a link as a file. The
+contract is just that the project contains `project.ts`.
 It resolves paths from the working directory, so a workspace's own
 `package.json` passes nothing. A deployment pipeline can skip it and write its
 own `config/project`.
@@ -358,7 +341,7 @@ command whose output gets deployed has to say what it is building.
 ```txt
 src/            the package — see the export map above for what is reachable
   index.ts        the public API
-  site/           createSite() and the Site it returns
+  site/           defineSite(), createSite() and the Site it returns
   meta/           head tags: canonical, hreflang, Open Graph, Twitter, robots
   jsonld/         the @graph — one file per node, each linked to Google's docs
   i18n/           defineMessages(), t(), placeholder extraction
@@ -400,9 +383,9 @@ 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
+the `.astro` components need a checker that can parse `.astro` at all — `tsc` reads
+zero `.astro` files no matter how they are globbed. Without this pass the
+components the package ships are 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.
 
@@ -412,7 +395,7 @@ practical reason: `astro check` writes a `.astro/` types directory and a
 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
+`Document.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

package/bin/use-project.mjs

@@ -1,16 +1,19 @@
 #!/usr/bin/env node
 /**
- * Copies a project overlay into `config/project`, the folder the whole build
+ * Links `config/project` to one project overlay, the folder the whole build
  * reads from. Run automatically before `dev`, `build` and `check`.
  *
+ * A link rather than a copy, so an edit made through `config/project` — where
+ * an editor's go-to-definition lands — is an edit to the real file. A
+ * junction on Windows, which needs no admin rights; a symlink elsewhere.
+ *
  *   atlas use acme
  *   PROJECT=acme npm run build
  *
- * The entire project directory is copied, so extra files and nested folders come
- * along automatically. A deployment pipeline can skip this command and write its
- * own `config/project` — the contract is just that it contains `project.ts`.
+ * A deployment pipeline can skip this command and write its own
+ * `config/project` — the contract is just that it contains `project.ts`.
  */
-import { cp, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { lstat, readdir, rm, stat, symlink, unlink } from "node:fs/promises";
 import { join } from "node:path";
 
 /**
@@ -26,10 +29,7 @@ import { join } from "node:path";
 const ROOT = process.cwd();
 const PROJECTS_DIR = join(ROOT, "config", "projects");
 const TARGET_DIR = join(ROOT, "config", "project");
-/**
- * Only an entry-point check — the whole directory is copied recursively, so a
- * project can add files and folders freely without touching this script.
- */
+/** Only an entry-point check: a project can add files and folders freely. */
 const ENTRY_FILE = "project.ts";
 
 /**
@@ -122,10 +122,15 @@ if (!(await exists(join(sourceDir, ENTRY_FILE)))) {
     process.exit(1);
 }
 
-await rm(TARGET_DIR, { recursive: true, force: true });
-await cp(sourceDir, TARGET_DIR, { recursive: true });
-await writeFile(join(TARGET_DIR, ".project"), `${name}\n`, "utf8");
+// Only the link goes, never what it points at. A real directory is a copy left
+// by an older version of this command.
+const existing = await lstat(TARGET_DIR).catch(() => undefined);
+if (existing?.isSymbolicLink()) await unlink(TARGET_DIR);
+else if (existing !== undefined) await rm(TARGET_DIR, { recursive: true });
+
+// "junction" is Windows' no-admin directory link, and ignored everywhere else.
+await symlink(sourceDir, TARGET_DIR, "junction");
 
 console.log(
-    `Using project "${name}" (config/projects/${name} -> config/project)`
+    `Using project "${name}" (config/project -> config/projects/${name})`
 );

package/docs/NOT-BUILT.md

@@ -230,7 +230,7 @@ type could — a property that is not valid for the type it sits on.
 ### Should a paragraph be authored as an array of translation keys?
 
 **No. One sentence is one message, and the styling lives in the copy as
-`[marks]`. `content/` carries the parser, the runs and `plain()`; nothing
+`[marks]`. `content/` carries the parser, the runs and `site.plain()`; nothing
 carries a `ContentItem[]`.**
 
 This is the shape the sibling B2C template uses, and it is the one thing from