@escape-game-over/atlas 0.1.35 → 0.1.37

package/docs/share-images.md

@@ -22,11 +22,16 @@ So **1200×630 for everything**, and let the square surfaces crop.
 
 That crop is the whole reason `shareImage` takes a fit at all:
 
-| The page's art        | `shareImage` call                                 | Why                                                                                  |
-| --------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------ |
-| A photograph          | `shareImage(src)` — `cover`                       | edges are scenery; a square crop takes the middle, which is the subject              |
-| A logo, square source | `shareImage(src, { fit: "contain", background })` | scaled to 630×630 and centred, so a square crop lands **exactly on the logo**        |
-| A logo under ~630px   | neither — compose one or get a bigger file        | `contain` would enlarge it, and `shareImage` refuses rather than ship a blurred card |
+| The page's art        | `shareImage` call                                                | Why                                                                                  |
+| --------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| A photograph          | `shareImage(src)` — `cover`, `jpeg`                              | edges are scenery; a square crop takes the middle, which is the subject              |
+| A logo, square source | `shareImage(src, { fit: "contain", background, format: "png" })` | scaled to 630×630 and centred, so a square crop lands **exactly on the logo**        |
+| A logo under ~630px   | neither — compose one or get a bigger file                       | `contain` would enlarge it, and `shareImage` refuses rather than ship a blurred card |
+
+The format follows the art, not the surface. A photograph is `jpeg`, the default:
+as `png` it runs to 1–2MB, and WhatsApp shows no preview for an image past
+about 300kB. A logo on a flat field is `png`, which is smaller and sharper for
+flat colour than `jpeg`'s blocks.
 
 Both examples use the second row for their catalogue pages: a room's own mark on
 the brand field, so a chat thumbnail shows which room it is rather than a

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.35",
+    "version": "0.1.37",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,

package/src/analytics/consent-storage.ts

@@ -0,0 +1,26 @@
+/**
+ * Where a visitor's consent answer is kept, and for how long it counts.
+ *
+ * Shared by the two halves that read it: the banner's module script
+ * (`astro/consent.ts`), and the inline head block Google's tags emit, which
+ * restores an answer before any tag fires. Two readers with their own copies of
+ * the key or the expiry would disagree the first time either changed.
+ */
+
+/**
+ * How long an answer stands before the question is asked again.
+ *
+ * Consent is not forever and regulators say so: France's CNIL puts the outside
+ * limit at 13 months and recommends six, and the EDPB's position is that a
+ * choice made long enough ago is no longer informed. Six is the conservative
+ * reading, and the reason the record carries a date at all — without one there
+ * is no way to expire it, and no way to answer "when did this visitor agree?",
+ * which is a question only ever asked when somebody is already unhappy.
+ */
+export const CONSENT_MONTHS = 6;
+
+/**
+ * The `localStorage` key the answer is kept under. Prefixed to keep clear of the
+ * bare `"consent"` a third-party widget would reach for.
+ */
+export const CONSENT_KEY = "atlas-consent";

package/src/analytics/google.ts

@@ -1,5 +1,6 @@
 import type { NonEmpty } from "../types.ts";
 import { warn } from "../warn.ts";
+import { CONSENT_KEY, CONSENT_MONTHS } from "./consent-storage.ts";
 import { type AnalyticsTags, literal, preconnect } from "./tags.ts";
 
 /**
@@ -131,6 +132,17 @@ export interface GoogleSettings {
      * unstated case emits.
      */
     readonly consent?: NonEmpty<ConsentDefaults>;
+    /**
+     * Whether a visitor's yes also grants the three advertising signals —
+     * `ad_storage`, `ad_user_data`, `ad_personalization`. **Off unless stated.**
+     *
+     * They are for ads and remarketing: showing a visitor ads elsewhere for
+     * having been here. A banner that asks about analytics and then grants
+     * those as well has not asked about them, which is not consent under the
+     * GDPR. So `__consent('granted')` leaves them denied, and a site that does
+     * run ads says so here — and says so in its banner.
+     */
+    readonly advertising?: true;
 }
 
 /**
@@ -208,22 +220,52 @@ const SIGNAL_KEYS = [
     "securityStorage",
 ] as const satisfies readonly (keyof ConsentDefaults)[];
 
+/** The signals only a site that runs ads may grant — see `advertising`. */
+const AD_KEYS: ReadonlySet<keyof ConsentDefaults> = new Set([
+    "adStorage",
+    "adUserData",
+    "adPersonalization",
+]);
+
 /**
  * `window.__consent(state)`, updating precisely what was defaulted.
  *
- * Every signal any default mentioned, and nothing else. Updating one that was
- * never defaulted is legal and pointless — Google reads it as a change from its
- * own implicit grant, which was never in force here.
+ * Every signal any default mentioned, and nothing else — less the advertising
+ * ones unless the site runs ads. Updating one that was never defaulted is legal
+ * and pointless — Google reads it as a change from its own implicit grant,
+ * which was never in force here.
  */
-function consentUpdater(defaults: readonly ConsentDefaults[]): string {
-    const signals = SIGNAL_KEYS.filter((key) =>
-        defaults.some((given) => given[key] !== undefined)
+function consentUpdater(
+    defaults: readonly ConsentDefaults[],
+    advertising: boolean
+): string {
+    const signals = SIGNAL_KEYS.filter(
+        (key) =>
+            (advertising || !AD_KEYS.has(key)) &&
+            defaults.some((given) => given[key] !== undefined)
     ).map((key) => `${literal(CONSENT_KEYS[key])}:s`);
 
     if (signals.length === 0) return "";
     return `window.${CONSENT_UPDATE_GLOBAL}=function(s){gtag('consent','update',{${signals.join(",")}})};`;
 }
 
+/**
+ * A returning visitor's answer, handed to Google before any tag fires.
+ *
+ * It has to happen here, in the head, ahead of `gtag('config', …)`. Left to the
+ * banner's module script it arrives after `gtag.js` has already sent the page
+ * view on the defaults — so every page a consenting visitor opened was recorded
+ * as denied: no cookie, no returning user, no session. Measured, not supposed:
+ * `gcs=G100` on the `page_view`, `G111` only on the hits after it.
+ *
+ * The same key and expiry `astro/consent.ts` reads, from the one place both
+ * take them. Anything unreadable, expired or absent leaves the defaults
+ * standing — the banner will ask.
+ */
+function restoredConsent(): string {
+    return `try{var c=JSON.parse(localStorage.getItem(${literal(CONSENT_KEY)})),e=new Date(c.at);e.setMonth(e.getMonth()+${CONSENT_MONTHS});if((c.choice==="granted"||c.choice==="denied")&&e>new Date())window.${CONSENT_UPDATE_GLOBAL}(c.choice)}catch(_){}`;
+}
+
 /** One `gtag('consent','default',{…})` per stated default, in order. */
 function consentCalls(defaults: readonly ConsentDefaults[]): string {
     return defaults
@@ -333,13 +375,17 @@ export function googleScripts(
     }
 
     const consent = google.consent ?? DENIED_BY_DEFAULT;
+    // The way back out of the defaults, covering what they denied — the ad
+    // signals only for a site that runs ads.
+    const updater = consentUpdater(consent, google.advertising === true);
     const inline = [
         "window.dataLayer=window.dataLayer||[];",
         "function gtag(){dataLayer.push(arguments)}",
         // Ahead of everything, which is the entire point of emitting this here.
         consentCalls(consent),
-        // And the way back out of it, covering exactly what was just denied.
-        consentUpdater(consent),
+        updater,
+        // Then a remembered answer, still ahead of the first tag.
+        updater === "" ? "" : restoredConsent(),
         tags.length > 0 ? "gtag('js',new Date());" : "",
         ...tags.map((id) => `gtag('config',${literal(id)});`),
         // Tag Manager's own loader, once per container. It appends its script

package/src/astro/consent-element.ts

@@ -1,9 +1,4 @@
-import {
-    applyConsent,
-    type ConsentChoice,
-    readConsent,
-    recordConsent,
-} from "./consent.ts";
+import { type ConsentChoice, readConsent, recordConsent } from "./consent.ts";
 import { element } from "./element.ts";
 import { data, refs } from "./ref.ts";
 
@@ -51,9 +46,9 @@ export const consentBanner = element("atlas-consent", ({ root, signal }) => {
         button.addEventListener("click", show, { signal });
     }
 
-    // Applied, not re-recorded: recording stamps today's date, and an answer
-    // renewed on every page view never expires.
-    const stored = readConsent();
-    if (stored === undefined) show();
-    else applyConsent(stored.choice);
+    // A stored answer is already applied: the head block hands it to Google
+    // before any tag fires, which this module runs too late to do. Nor is it
+    // re-recorded — that stamps today's date, and an answer renewed on every
+    // page view never expires.
+    if (readConsent() === undefined) show();
 });

package/src/astro/consent.ts

@@ -1,3 +1,4 @@
+import { CONSENT_KEY, CONSENT_MONTHS } from "../analytics/consent-storage.ts";
 import { CONSENT_UPDATE_GLOBAL } from "../analytics/google.ts";
 
 /**
@@ -27,24 +28,6 @@ export interface ConsentRecord {
     readonly at: string;
 }
 
-/**
- * How long an answer stands before the question is asked again.
- *
- * Consent is not forever and regulators say so: France's CNIL puts the outside
- * limit at 13 months and recommends six, and the EDPB's position is that a
- * choice made long enough ago is no longer informed. Six is the conservative
- * reading, and the reason the record carries a date at all — without one there
- * is no way to expire it, and no way to answer "when did this visitor agree?",
- * which is a question only ever asked when somebody is already unhappy.
- */
-const MONTHS = 6;
-
-/**
- * The `localStorage` key the answer is kept under. Prefixed to keep clear of the
- * bare `"consent"` a third-party widget would reach for.
- */
-const KEY = "atlas-consent";
-
 /**
  * The answer this visitor gave, if it still counts.
  *
@@ -55,7 +38,7 @@ const KEY = "atlas-consent";
 export function readConsent(): ConsentRecord | undefined {
     let raw: string | null = null;
     try {
-        raw = localStorage.getItem(KEY);
+        raw = localStorage.getItem(CONSENT_KEY);
     } catch {
         // Private browsing, or storage disabled. Nothing was remembered, so
         // nothing is assumed.
@@ -72,7 +55,7 @@ export function readConsent(): ConsentRecord | undefined {
 
         const expiry = new Date(parsed.at);
         if (Number.isNaN(expiry.getTime())) return undefined;
-        expiry.setMonth(expiry.getMonth() + MONTHS);
+        expiry.setMonth(expiry.getMonth() + CONSENT_MONTHS);
         if (expiry < new Date()) return undefined;
 
         return { choice: parsed.choice, at: parsed.at };
@@ -88,7 +71,7 @@ export function readConsent(): ConsentRecord | undefined {
 export function recordConsent(choice: ConsentChoice): void {
     const record: ConsentRecord = { choice, at: new Date().toISOString() };
     try {
-        localStorage.setItem(KEY, JSON.stringify(record));
+        localStorage.setItem(CONSENT_KEY, JSON.stringify(record));
     } catch {
         // Unable to remember it, which is a worse experience and not a wrong
         // one — the choice still applies to this page.

package/src/astro/images.ts

@@ -30,9 +30,11 @@ interface ShareImageBase {
     /** 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.
+     * Defaults to `jpeg`: accepted by every scraper, and a 1200×630 photograph
+     * lands near 150kB where `png` makes it 1–2MB — past the ~300kB WhatsApp
+     * will fetch for a preview at all. Ask for `png` for flat art, a logo on
+     * its field, where it is both smaller and sharper. Avoid `avif`, which
+     * several scrapers still cannot read.
      */
     readonly format?: "png" | "jpeg" | "webp";
     /** Ignored by `png`, which is lossless. */
@@ -146,7 +148,7 @@ export async function shareImage(
 ): Promise<ImageAsset> {
     const width = options.width ?? SHARE_WIDTH;
     const height = options.height ?? SHARE_HEIGHT;
-    const format = options.format ?? "png";
+    const format = options.format ?? "jpeg";
     const fit = options.fit ?? "cover";
 
     // Astro's image service never enlarges: ask for a box bigger than the