@escape-game-over/atlas 0.1.1

package/src/astro/images.ts

@@ -0,0 +1,315 @@
+/**
+ * Share images, derived rather than hand-cut.
+ *
+ * Its own entry point, not part of `…/astro`: that module is imported by an
+ * Astro config, and `astro:assets` does not exist yet when a config is
+ * evaluated. Everything here runs inside the build, from a page or a component.
+ */
+
+import { getImage } from "astro:assets";
+import type { ImageAsset } from "../image.ts";
+import type { ThemeColor } from "../meta/index.ts";
+import type { Percentage } from "../types.ts";
+import { warn } from "../warn.ts";
+
+/**
+ * What every major platform crops a share image to — 1200×630, near enough to
+ * 1.91:1.
+ *
+ * Not an option by default, because it is not a preference: Open Graph,
+ * Twitter's `summary_large_image` and LinkedIn all target this box, and an image
+ * that misses it is letterboxed or centre-cropped by someone else's rules.
+ */
+const SHARE_WIDTH = 1200;
+const SHARE_HEIGHT = 630;
+
+interface ShareImageBase {
+    /** Defaults to 1200. */
+    readonly width?: number;
+    /** Defaults to 630. */
+    readonly height?: number;
+    /**
+     * Defaults to `png`: lossless, and accepted by every scraper. `jpeg` is far
+     * smaller for photographs. Avoid `avif`, which several scrapers still
+     * cannot read.
+     */
+    readonly format?: "png" | "jpeg" | "webp";
+    /** Ignored by `png`, which is lossless. */
+    readonly quality?: Percentage;
+}
+
+/**
+ * Which part of an oversized source survives a `cover` crop.
+ *
+ * A closed union rather than a string, for the reason `RobotsDirective` is one:
+ * the underlying resizer ignores anything it does not recognise, so `"centre
+ * top"` or `"top center"` would crop from the middle and never say why.
+ *
+ * The nine placements are the CSS spellings. The resizer also accepts compass
+ * synonyms — `north` for `top`, `southeast` for `right bottom` — which are left
+ * out deliberately: two ways to say one thing, and neither reads better.
+ *
+ * `entropy` and `attention` are not placements but strategies, and are worth
+ * knowing about for photographs: they pick the crop by looking at the image,
+ * which beats guessing where a subject sits when the same rule has to serve
+ * every photo a venue supplies.
+ */
+export type CropPosition =
+    | "center"
+    | "top"
+    | "right top"
+    | "right"
+    | "right bottom"
+    | "bottom"
+    | "left bottom"
+    | "left"
+    | "left top"
+    /** Crops to the busiest region — the most detail, by Shannon entropy. */
+    | "entropy"
+    /** Crops to what draws the eye: faces, skin tones, saturated colour. */
+    | "attention";
+
+/**
+ * How a source that is not already 1.91:1 reaches the box.
+ *
+ * The two are not interchangeable, and the right one depends on what the image
+ * *is*:
+ *
+ * - `cover` — fill the box and crop the overflow. For photographs, where the
+ *   edges are scenery and losing them costs nothing.
+ * - `contain` — fit the whole image in and pad the rest. For logos, screenshots
+ *   and anything with a shape: a square logo under `cover` is cropped to a
+ *   1200×630 slice through its middle.
+ *
+ * `contain` requires a `background`, because the padding has to be *some*
+ * colour. Leaving it transparent only defers the choice to whatever composites
+ * the card, which is how a dark logo ends up invisible on a dark card.
+ */
+export type ShareImageOptions =
+    | (ShareImageBase & {
+          readonly fit?: "cover";
+          /**
+           * Which part survives the crop — e.g. `"top"` to keep faces in
+           * frame on a tall source, or `"attention"` to let the resizer find
+           * them.
+           */
+          readonly position?: CropPosition;
+      })
+    | (ShareImageBase & {
+          readonly fit: "contain";
+          /**
+           * The padding colour.
+           *
+           * Takes a `ThemeColor`, so a project hands over `site.themeColor`
+           * rather than restating a hex value the head already carries. Given
+           * one colour per scheme, the light one is used: a share image is
+           * composited by someone else's client and has no scheme to follow.
+           */
+          readonly background: ThemeColor;
+      });
+
+/** One colour from a `ThemeColor`; see `background` for why it is the light one. */
+function resolveColor(color: ThemeColor): string {
+    return typeof color === "string" ? color : color.light;
+}
+
+/**
+ * Crops an imported image to the share box and returns it ready for `metaFor`.
+ *
+ * ```ts
+ * import hero from "~/assets/hero.png";
+ * import { shareImage } from "@escape-game-over/atlas/astro/images";
+ *
+ * const image = { asset: await shareImage(hero), alt: "…" };
+ * ```
+ *
+ * A square logo, which is the shape most product and room images come in, wants
+ * the other fit:
+ *
+ * ```ts
+ * await shareImage(roomLogo, { fit: "contain", background: "#1d51e0" });
+ * ```
+ *
+ * The point is that one source image serves both the page and the card: without
+ * this a project keeps a second, hand-cut file per page and nothing checks that
+ * the two still show the same thing — or, more often, it reuses whatever is to
+ * hand and ships a card with a logo floating in the middle of it.
+ *
+ * What this does *not* do is compose: no logo laid over a background, no title
+ * burnt into the image. That needs a renderer rather than a resizer — satori or
+ * `astro-og-canvas` — and is a different tool from this one.
+ */
+export async function shareImage(
+    source: ImageMetadata,
+    options: ShareImageOptions = {}
+): Promise<ImageAsset> {
+    const width = options.width ?? SHARE_WIDTH;
+    const height = options.height ?? SHARE_HEIGHT;
+    const format = options.format ?? "png";
+    const fit = options.fit ?? "cover";
+
+    // Astro's image service never enlarges: ask for a box bigger than the
+    // source and it hands back the source, at its own size. So this cannot pad
+    // a small logo onto a large field however the options are written — the
+    // request is simply not honoured, and the only wrong thing to do is claim
+    // otherwise in `og:image:width`.
+    //
+    // Not warned about here. `metaFor` already warns about an undersized
+    // `og:image`, on every page and whether or not this helper made it, so
+    // saying it twice would only halve the chance either line is read.
+    //
+    // Measured as a scale factor, not by comparing dimensions, because the two
+    // fits reach the box differently. `cover` scales until *both* sides are
+    // covered, so a source short in either dimension would be enlarged.
+    // `contain` scales until the *first* side fits, so an 800x800 logo lands at
+    // 630x630 — a reduction, though it is narrower than 1200.
+    const scale =
+        fit === "cover"
+            ? Math.max(width / source.width, height / source.height)
+            : Math.min(width / source.width, height / source.height);
+    const image = await getImage({
+        src: source,
+        width,
+        height,
+        format,
+        fit,
+        ...(options.quality === undefined ? {} : { quality: options.quality }),
+        // The two fits take different extra options, and neither accepts the
+        // other's: `contain` pads, so it needs a colour; `cover` crops, so it
+        // needs to know what to keep.
+        ...((): { background?: string; position?: string } => {
+            if (options.fit === "contain") {
+                return { background: resolveColor(options.background) };
+            }
+            if (options.position === undefined) return {};
+            return { position: options.position };
+        })(),
+    });
+
+    // The size that came *back*, not the size asked for.
+    //
+    // Neither `attributes` nor `options` can be trusted here: both echo the
+    // request, and the request is exactly what was not honoured. What is known
+    // is the rule — Astro refuses to enlarge — so a source too small for the box
+    // comes back untouched, at its own size. Reporting the request instead would
+    // put an `og:image:width` in every head that the file does not match, which
+    // is worse than a small image: a scraper lays out a space and finds
+    // something else in it.
+    const produced =
+        scale > 1
+            ? { width: source.width, height: source.height }
+            : { width, height };
+    return { src: image.src, ...produced, format };
+}
+
+/**
+ * The aspect ratios Google asks a business to publish photos in.
+ *
+ * Three, and not negotiable per project: they exist because a result renders
+ * the photo in whichever shape that surface uses, and supplying one ratio means
+ * the other two are cropped by rules you do not control. 1200 wide throughout,
+ * which clears the 50 000-pixel floor by an order of magnitude and is a
+ * reasonable size to serve.
+ */
+const PHOTO_RATIOS = [
+    { label: "16:9", width: 1200, height: 675 },
+    { label: "4:3", width: 1200, height: 900 },
+    { label: "1:1", width: 1200, height: 1200 },
+] as const;
+
+/** The largest side any ratio above asks for, in either dimension. */
+const PHOTO_SIDE = 1200;
+
+export interface PhotoSetOptions {
+    /** Defaults to `jpeg`: these are photographs, and png would be enormous. */
+    readonly format?: "png" | "jpeg" | "webp";
+    /** Defaults to Astro's own. */
+    readonly quality?: Percentage;
+    /**
+     * Which part survives the crop.
+     *
+     * Worth setting on a photograph with a subject: the 1:1 crop takes a square
+     * out of the middle of a landscape shot, and a shopfront photographed from
+     * across the road can lose its own doorway. `"attention"` is the option to
+     * reach for when one setting has to serve every photo a venue supplies.
+     */
+    readonly position?: CropPosition;
+}
+
+/**
+ * One photograph, cropped to each ratio a search result may render it in.
+ *
+ * ```ts
+ * import frontage from "~/assets/venue/frontage.jpg";
+ * import { photoSet } from "@escape-game-over/atlas/astro/images";
+ *
+ * const crops = await photoSet(frontage, { position: "center top" });
+ * ```
+ *
+ * Derived rather than hand-cut for the same reason `shareImage` is: three files
+ * per photograph is three chances for one of them to be of something else, and
+ * nothing in a build would notice. `cover` throughout, with no option to
+ * `contain` — a padded photograph is not a photograph of anything, and these
+ * are the images that claim to depict the place.
+ *
+ * ## What the source has to be
+ *
+ * - **At least 1200 x 1200**, and *both* sides matter. The square crop needs
+ *   1200 of each, so a 3000x800 panorama is too short however wide it is. A
+ *   photograph off any modern phone clears this several times over.
+ * - **Landscape**, or at least not tall. The three ratios are all wider than
+ *   they are high except the square, so a portrait source is cropped hardest
+ *   where it has least to give.
+ * - **Of this venue.** The room itself, the frontage, people playing. Not a
+ *   logo, not a share card, not a stock interior — see `image` on
+ *   `LocalBusinessInput` for why that distinction is the whole point.
+ * - **Framed with room around the subject.** Every ratio is cut from the same
+ *   file, so anything tight against an edge is lost in one of them. A doorway
+ *   centred with space either side survives all three; the same doorway at the
+ *   far left survives the 16:9 and nothing else.
+ *
+ * Warns when the source cannot fill the boxes. Astro never enlarges, so a small
+ * source comes back at its own size and the set silently becomes three copies
+ * of one thumbnail — which is what the warning has to say, because the files
+ * are still produced and still look fine individually.
+ */
+export async function photoSet(
+    source: ImageMetadata,
+    options: PhotoSetOptions = {}
+): Promise<readonly ImageAsset[]> {
+    const format = options.format ?? "jpeg";
+
+    // Both dimensions, because the 1:1 crop asks for 1200 of each. A landscape
+    // photograph 1200 tall covers every ratio here; one 1200 wide but shorter
+    // does not.
+    if (source.width < PHOTO_SIDE || source.height < PHOTO_SIDE) {
+        warn(
+            "photoSet",
+            `source is ${source.width}x${source.height}, short of the ${PHOTO_SIDE}x${PHOTO_SIDE} the square crop needs. Astro does not enlarge, so the set will be three copies of the same small image.`
+        );
+    }
+
+    return await Promise.all(
+        PHOTO_RATIOS.map(async (ratio) => {
+            const image = await getImage({
+                src: source,
+                width: ratio.width,
+                height: ratio.height,
+                format,
+                fit: "cover",
+                ...(options.quality === undefined
+                    ? {}
+                    : { quality: options.quality }),
+                ...(options.position === undefined
+                    ? {}
+                    : { position: options.position }),
+            });
+            return {
+                src: image.src,
+                width: ratio.width,
+                height: ratio.height,
+                format,
+            };
+        })
+    );
+}

package/src/astro/index.ts

@@ -0,0 +1,44 @@
+/**
+ * The Astro half of the library — the only part that knows what framework this
+ * is. Everything outside `src/astro/` stays framework-free and is checked in
+ * isolation; this entry point is where the two are joined.
+ *
+ * ```ts
+ * // astro.config.ts
+ * import { publicFiles, siteRoutes } from "@escape-game-over/atlas/astro";
+ * import { redirects, site } from "./config/site.ts";
+ *
+ * export default defineConfig({
+ *     integrations: [siteRoutes({ site, redirects }), publicFiles()],
+ * });
+ * ```
+ *
+ * Two integrations, and they share nothing but the hook API:
+ *
+ * - `site-routes.ts` writes the files a site owes the outside world — sitemap,
+ *   `robots.txt`, `llms.txt`, `_redirects` — replacing the endpoint files every
+ *   consuming repo would otherwise copy, and keeping their names and content
+ *   types owned by the library rather than restated per project.
+ * - `public-files.ts` types the contents of `public/`, the one part of a site
+ *   the compiler cannot otherwise see.
+ *
+ * The rest of this folder is imported directly rather than from here, because
+ * each is reached from a different place in a project: `…/astro/images` from
+ * a view or a config, `…/astro/consent` from a client-side script, and
+ * `…/astro/meta-tags` from a layout.
+ *
+ * That last one is a `.astro` component, and the only one lib carries. It is
+ * here rather than in a project's `src/` because it holds no design and no
+ * copy — it renders the `MetaTag` union and nothing else, which makes it the
+ * mirror of `asMetaTag` in `lib/meta/tag.ts` rather than a piece of a theme.
+ */
+
+export {
+    type PublicFilesOptions,
+    publicFiles,
+} from "./public-files.ts";
+export {
+    type SiteFiles,
+    type SiteRoutesOptions,
+    siteRoutes,
+} from "./site-routes.ts";

package/src/astro/public-files.ts

@@ -0,0 +1,129 @@
+import type { Dirent } from "node:fs";
+import { readdir } from "node:fs/promises";
+import type { AstroIntegration } from "astro";
+
+/**
+ * The module the generated union is declared in.
+ *
+ * Types only, so nothing has to exist at runtime: a consumer reaches it with
+ * `import type`, which is erased before anything tries to resolve it.
+ */
+const PUBLIC_MODULE = "atlas:public";
+
+/** Files in `public/` that are not content: editor litter and placeholders. */
+const IGNORED = new Set([".DS_Store", "Thumbs.db", ".gitkeep"]);
+
+/** Every file under a directory, as root-relative POSIX paths. */
+async function walk(dir: URL, prefix = ""): Promise<string[]> {
+    let entries: Dirent[];
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+        // No `public/` at all is a normal state, not an error.
+        return [];
+    }
+
+    const found: string[] = [];
+    for (const entry of entries) {
+        if (IGNORED.has(entry.name)) continue;
+
+        const path = `${prefix}/${entry.name}`;
+        if (entry.isDirectory()) {
+            found.push(...(await walk(new URL(`${entry.name}/`, dir), path)));
+        } else {
+            found.push(path);
+        }
+    }
+    return found;
+}
+
+/**
+ * Types every file in `public/`, so linking to one is checked.
+ *
+ * ```ts
+ * import type { PublicFile } from "atlas:public";
+ *
+ * const statement: PublicFile = "/reports/annual-2026.pdf";
+ * ```
+ *
+ * `public/` is the one part of a site the compiler cannot see: files are copied
+ * to the output verbatim, so a link to one is a string nothing verifies, and a
+ * renamed or deleted file becomes a 404 that no build reports. Every other URL
+ * on the site is derived from the route registry and checked.
+ *
+ * Generated at config time and written through `injectTypes`, which puts it in
+ * `.astro/` where Astro already references it — so there is nothing to import,
+ * commit or add to a tsconfig. A file added while the dev server runs is picked
+ * up when it restarts.
+ */
+export interface PublicFilesOptions {
+    /**
+     * How the consuming project imports this package.
+     *
+     * Defaults to the published name, which is what a project installing it
+     * from the registry writes. State it only where that is not the specifier
+     * in the import statements — a path alias, or a fork under another name.
+     *
+     * Needed because the generated file *augments* that module: the union has to
+     * reach `fileUrl` and the redirect target, and a declaration can only be
+     * merged into a module named the way the consumer names it.
+     */
+    readonly libModule?: string;
+}
+
+export function publicFiles(
+    options: PublicFilesOptions = {}
+): AstroIntegration {
+    const libModule = options.libModule ?? "@escape-game-over/atlas";
+
+    return {
+        name: "public-files",
+        hooks: {
+            "astro:config:done": async ({ config, injectTypes, logger }) => {
+                const files = (await walk(config.publicDir)).sort();
+                /**
+                 * The union, one file per line, indented by `spaces`.
+                 *
+                 * A count rather than the whitespace itself: the two call sites
+                 * sit at different depths in the emitted file, and passing the
+                 * indent as a literal means counting spaces by eye in a string
+                 * that looks identical whether it holds eight of them or nine.
+                 */
+                const union = (spaces: number) =>
+                    files.length === 0
+                        ? "never"
+                        : files
+                              .map((file) => `"${file}"`)
+                              .join(`\n${" ".repeat(spaces)}| `);
+
+                injectTypes({
+                    filename: "public-files.d.ts",
+                    // `export {}` is load-bearing: without a top-level import or
+                    // export this file is a *script*, and `declare module …`
+                    // then declares an ambient module that replaces the real one
+                    // rather than merging into it — silently untyping every other
+                    // export lib has.
+                    content: `export {};
+
+declare module "${PUBLIC_MODULE}" {
+    /** Every file in \`public/\`, as it is served. */
+    export type PublicFile =
+        | ${union(8)};
+}
+
+declare module "${libModule}" {
+    /** Merged so \`fileUrl\` and redirect targets accept only these. */
+    interface PublicFileRegistry {
+        path:
+            | ${union(12)};
+    }
+}
+`,
+                });
+                logger.info(
+                    `typed ${files.length} file${files.length === 1 ? "" : "s"} in public/`
+                );
+            },
+        },
+    };
+}