@volter/twin-googlefonts 1.0.1 → 1.0.3

package/api/spec/sources.json

@@ -1,6 +1,16 @@
 {
   "https://developers.google.com/fonts/docs/developer_api": {
     "status": 200,
-    "checked": "2026-10-12"
+    "checked": "2026-11-11",
+    "quotes": {
+      "by including an API key with each request": true
+    }
+  },
+  "https://docs.cloud.google.com/docs/authentication/api-keys": {
+    "status": 200,
+    "checked": "2026-11-11",
+    "quotes": {
+      "Standard API keys provide a way to associate a request with a project for billing and quota purposes.": true
+    }
   }
 }

package/api/src/semantics/doors.ts

@@ -1,9 +1,13 @@
 // Google supplies catalog records and keys outside the read-only Fonts API.
 import type { HandlerContext } from '@volter/world-core';
-import { FONT, CATALOG, CSS, FILE, KEY, object, assetKey, cssKey, css2Key, css2Query, googleError } from './shared.ts';
+import { FONT, CATALOG, CSS, FILE, KEY, object, assetKey, browserClass, cssKey, css2Key, css2Query, googleError } from './shared.ts';
 
 // source: https://developers.google.com/fonts/docs/developer_api
 export async function appCredentials(ctx: HandlerContext): Promise<Response> {
+  // An app's key is a standard API key, made on a Google Cloud project's Credentials page and associating each request
+  // with that project for billing and quota; the Fonts Developer API takes it as `key=` and nothing else.
+  // source: https://docs.cloud.google.com/docs/authentication/api-keys "Standard API keys provide a way to associate a request with a project for billing and quota purposes."
+  // source: https://developers.google.com/fonts/docs/developer_api "by including an API key with each request"
   const project = await ctx.tenant('_project', async organization =>
     String((await ctx.create('_project', { name: organization.label, owner: organization.members[0] }, 'project.create')).id));
   const value = async (id: string): Promise<string> => 'AIza' + (await ctx.secret(`googlefonts:application-api-key:${id}`)).slice(0, 35);
@@ -79,8 +83,9 @@ export async function publishCatalog(ctx: HandlerContext): Promise<Response> {
       if (!font || !(font.variants as string[]).includes(variant) ||
           sheet.subset.split(',').some(s => !(font.subsets as string[]).includes(s)))
         throw new Error('Stylesheet request must name a published font, variant and subset');
+      // a stylesheet is one browser class's representation (shared.ts browserClass): its user agent is that class's sample
       const key = cssKey(ctx, sheet.family, sheet.subset, sheet.userAgent);
-      if (representations.has(key)) throw new Error('Duplicate stylesheet request');
+      if (representations.has(key)) throw new Error('Duplicate stylesheet request for browser class ' + browserClass(sheet.userAgent));
       representations.add(key);
       const urls = [...sheet.css.matchAll(/url\((https?:\/\/[^)]+)\)/g)].map(m => m[1]!);
       if (urls.length === 0 || urls.some(url => !decoded.has(assetKey(url))))
@@ -91,7 +96,7 @@ export async function publishCatalog(ctx: HandlerContext): Promise<Response> {
       if (!pairs || typeof sheet.userAgent !== 'string' || typeof sheet.css !== 'string' || !sheet.css.includes('@font-face'))
         throw new Error('Invalid CSS2 stylesheet representation');
       const key = css2Key(ctx, pairs, sheet.userAgent);
-      if (representations.has(key)) throw new Error('Duplicate stylesheet request');
+      if (representations.has(key)) throw new Error('Duplicate stylesheet request for browser class ' + browserClass(sheet.userAgent));
       representations.add(key);
       const urls = [...sheet.css.matchAll(/url\((https?:\/\/[^)]+)\)/g)].map(m => m[1]!);
       if (urls.length === 0 || urls.some(url => !decoded.has(assetKey(url))))
@@ -118,13 +123,13 @@ export async function publishCatalog(ctx: HandlerContext): Promise<Response> {
     const key = cssKey(ctx, sheet.family as string, sheet.subset as string, sheet.userAgent as string);
     const blob = 'css-' + ctx.crypto.digest('sha256', sheet.css as string);
     await ctx.blobs.put(blob, new TextEncoder().encode(sheet.css as string));
-    await ctx.record(CSS, { family: sheet.family, subset: sheet.subset, userAgent: sheet.userAgent, blob }, fingerprint + ':' + key);
+    await ctx.record(CSS, { family: sheet.family, subset: sheet.subset, userAgent: sheet.userAgent, browserClass: browserClass(sheet.userAgent as string), blob }, fingerprint + ':' + key);
   }
   for (const sheet of sheets2) {
     const key = css2Key(ctx, css2Query(new URLSearchParams(sheet.query as string))!, sheet.userAgent as string);
     const blob = 'css-' + ctx.crypto.digest('sha256', sheet.css as string);
     await ctx.blobs.put(blob, new TextEncoder().encode(sheet.css as string));
-    await ctx.record(CSS, { query: sheet.query, userAgent: sheet.userAgent, blob }, fingerprint + ':' + key);
+    await ctx.record(CSS, { query: sheet.query, userAgent: sheet.userAgent, browserClass: browserClass(sheet.userAgent as string), blob }, fingerprint + ':' + key);
   }
   await ctx.record(CATALOG, { families: [...names], fingerprint }, 'published');
   return Response.json({ families: [...names] }, { status: 201 });

package/api/src/semantics/index.ts

@@ -1,4 +1,4 @@
-// GENERATED by scripts/create-pack.ts --index: the handler map, by operationId, from the families' files (each
+// GENERATED by twin-standard create --index: the handler map, by operationId, from the families' files (each
 // handler named as its operation). Do not edit; add a handler to its family's file and generate again.
 import type { Handler } from '@volter/world-core';
 import * as webfonts from './webfonts.ts';

package/assets/src/semantics/index.ts

@@ -1,4 +1,4 @@
-// GENERATED by scripts/create-pack.ts --index: the handler map, by operationId, from the families' files (each
+// GENERATED by twin-standard create --index: the handler map, by operationId, from the families' files (each
 // handler named as its operation). Do not edit; add a handler to its family's file and generate again.
 import type { Handler } from '@volter/world-core';
 import * as l from './l.ts';

package/css/spec/SOURCE.md

@@ -7,9 +7,17 @@ GET /css?family=<family>:<variant>&subset=<subsets> with the exact configured
 User-Agent and consumes each @font-face's font-family, style, weight and src URL.
 Dub's Open Graph routes call GET /css2?family=Inter:wght@<weight> and Rallly's
 calls GET /css2?family=Noto+Sans+SC:wght@<weight>&text=<text>, both from a server
-without a browser User-Agent, and read the truetype src URL.
+without a browser User-Agent, and read the truetype src URL. next/font/google's build (Rallly's and
+Cal.diy's `next build`) calls GET /css2?family=Inter:wght@100..900&display=swap with a Chrome User-Agent and
+reads each woff2 src URL of its unicode-range faces.
+Twenty's front end (twentyhq/twenty 323e664, packages/twenty-front/index.html:33,37) links
+GET /css2?family=Inter:wght@400;500;600&display=swap and GET /css2?family=DM+Mono:wght@400;500;600&display=swap
+from the browser, which loads the woff2 faces its text needs.
+A representation is published for a browser class (src/semantics/shared.ts browserClass): Google serves any
+browser, choosing WOFF 2.0 and unicode-range subsets by the browser its User-Agent names, and the classes are
+the agents Google answered the same bytes (vendor/browser-classes.json).
 The supplied representations retain actual vendor CSS. Requests without a
-published representation answer a refusal, never an invented font format.
+representation published for their class answer a refusal, never an invented font format.
 text/display/effect on /css are outside this client's demand.
 
 SHA-256 `openapi.json`: bf7b9a3b70c3a75712fb784e22bfe07c0008dd55e1aa93b31cba8da26a64fb60

package/css/src/semantics/css.ts

@@ -1,5 +1,5 @@
 import type { HandlerContext } from '@volter/world-core';
-import { CATALOG, CSS, cssKey, htmlError } from './shared.ts';
+import { browserClass, CATALOG, CSS, cssKey, htmlError } from './shared.ts';
 
 // source: spec:getStylesheet "The representation is selected for the requesting browser."
 export async function getStylesheet(ctx: HandlerContext): Promise<Response> {
@@ -8,11 +8,13 @@ export async function getStylesheet(ctx: HandlerContext): Promise<Response> {
   if (!family || [...query.keys()].some(k => !['family','subset'].includes(k)))
     return htmlError(400, 'Bad font request');
   const generation = ctx.row(CATALOG, 'published')?.fingerprint;
-  const key = cssKey(ctx, family, subset, ctx.call.request.headers.get('user-agent') ?? '');
+  // the representation published for the browser class the agent belongs to (shared.ts browserClass)
+  const userAgent = ctx.call.request.headers.get('user-agent') ?? '';
+  const key = cssKey(ctx, family, subset, userAgent);
   const row = generation === undefined ? undefined : ctx.row(CSS, String(generation) + ':' + key);
   // Where the documentation stops: no supplied representation is a named
   // refusal, not an invented conversion or another browser's font format.
-  if (!row) return htmlError(400, 'Font family or browser representation is not published');
+  if (!row) return htmlError(400, 'Font family or browser representation is not published (' + browserClass(userAgent) + ')');
   const body = await ctx.blobs.get(String(row.blob));
   if (!body) return htmlError(404, 'Font stylesheet not found');
   return new Response(Uint8Array.from(body).buffer, { headers: { 'content-type': 'text/css; charset=utf-8', 'content-length': String(body.length), 'vary': 'User-Agent' } });

package/css/src/semantics/css2.ts

@@ -1,5 +1,5 @@
 import type { HandlerContext } from '@volter/world-core';
-import { CATALOG, CSS, css2Key, css2Query, htmlError } from './shared.ts';
+import { browserClass, CATALOG, CSS, css2Key, css2Query, htmlError } from './shared.ts';
 
 // source: spec:getStylesheet2 "To request multiple families, specify the family= param for each family."
 export async function getStylesheet2(ctx: HandlerContext): Promise<Response> {
@@ -7,13 +7,14 @@ export async function getStylesheet2(ctx: HandlerContext): Promise<Response> {
   if (!pairs) return htmlError(400, 'Bad font request');
   const generation = ctx.row(CATALOG, 'published')?.fingerprint;
   const userAgent = ctx.call.request.headers.get('user-agent') ?? '';
-  const sheet = (agent: string) => generation === undefined ? undefined : ctx.row(CSS, String(generation) + ':' + css2Key(ctx, pairs, agent));
-  // Where the evidence stops: Google answered the same truetype stylesheet to no User-Agent, "node" and "undici"
-  // (vendor/inter.json). A request whose agent is not a browser's ("Mozilla/...") and has no representation of its
-  // own reads the one published for no agent; a browser without its own representation is refused, never sent
-  // another browser's format.
-  const row = sheet(userAgent) ?? (userAgent.startsWith('Mozilla/') ? undefined : sheet(''));
-  if (!row) return htmlError(400, 'Font family or browser representation is not published');
+  // The representation is the one published for the browser class the agent belongs to (shared.ts browserClass): a
+  // request with no browser's agent ("node", "undici", none) reads the truetype class, as Google answered the same CSS
+  // to all three (vendor/inter.json).
+  // source: spec:getStylesheet2 "The representation is selected for the requesting browser."
+  const row = generation === undefined ? undefined : ctx.row(CSS, String(generation) + ':' + css2Key(ctx, pairs, userAgent));
+  // Where the documentation stops: a class with no published representation is a named refusal, never another
+  // class's font format.
+  if (!row) return htmlError(400, 'Font family or browser representation is not published (' + browserClass(userAgent) + ')');
   const body = await ctx.blobs.get(String(row.blob));
   if (!body) return htmlError(404, 'Font stylesheet not found');
   return new Response(Uint8Array.from(body).buffer, { headers: { 'content-type': 'text/css; charset=utf-8', 'content-length': String(body.length), 'access-control-allow-origin': '*' } });

package/css/src/semantics/index.ts

@@ -1,4 +1,4 @@
-// GENERATED by scripts/create-pack.ts --index: the handler map, by operationId, from the families' files (each
+// GENERATED by twin-standard create --index: the handler map, by operationId, from the families' files (each
 // handler named as its operation). Do not edit; add a handler to its family's file and generate again.
 import type { Handler } from '@volter/world-core';
 import * as css from './css.ts';

package/dist/api/spec/sources.json

@@ -1,6 +1,16 @@
 {
   "https://developers.google.com/fonts/docs/developer_api": {
     "status": 200,
-    "checked": "2026-10-12"
+    "checked": "2026-11-11",
+    "quotes": {
+      "by including an API key with each request": true
+    }
+  },
+  "https://docs.cloud.google.com/docs/authentication/api-keys": {
+    "status": 200,
+    "checked": "2026-11-11",
+    "quotes": {
+      "Standard API keys provide a way to associate a request with a project for billing and quota purposes.": true
+    }
   }
 }

package/dist/api/src/semantics/doors.js

@@ -1,6 +1,10 @@
-import { FONT, CATALOG, CSS, FILE, KEY, object, assetKey, cssKey, css2Key, css2Query, googleError } from "./shared.js";
+import { FONT, CATALOG, CSS, FILE, KEY, object, assetKey, browserClass, cssKey, css2Key, css2Query, googleError } from "./shared.js";
 // source: https://developers.google.com/fonts/docs/developer_api
 export async function appCredentials(ctx) {
+    // An app's key is a standard API key, made on a Google Cloud project's Credentials page and associating each request
+    // with that project for billing and quota; the Fonts Developer API takes it as `key=` and nothing else.
+    // source: https://docs.cloud.google.com/docs/authentication/api-keys "Standard API keys provide a way to associate a request with a project for billing and quota purposes."
+    // source: https://developers.google.com/fonts/docs/developer_api "by including an API key with each request"
     const project = await ctx.tenant('_project', async (organization) => String((await ctx.create('_project', { name: organization.label, owner: organization.members[0] }, 'project.create')).id));
     const value = async (id) => 'AIza' + (await ctx.secret(`googlefonts:application-api-key:${id}`)).slice(0, 35);
     const key = await ctx.accountKey('api-key', KEY, {
@@ -78,9 +82,10 @@ export async function publishCatalog(ctx) {
             if (!font || !font.variants.includes(variant) ||
                 sheet.subset.split(',').some(s => !font.subsets.includes(s)))
                 throw new Error('Stylesheet request must name a published font, variant and subset');
+            // a stylesheet is one browser class's representation (shared.ts browserClass): its user agent is that class's sample
             const key = cssKey(ctx, sheet.family, sheet.subset, sheet.userAgent);
             if (representations.has(key))
-                throw new Error('Duplicate stylesheet request');
+                throw new Error('Duplicate stylesheet request for browser class ' + browserClass(sheet.userAgent));
             representations.add(key);
             const urls = [...sheet.css.matchAll(/url\((https?:\/\/[^)]+)\)/g)].map(m => m[1]);
             if (urls.length === 0 || urls.some(url => !decoded.has(assetKey(url))))
@@ -92,7 +97,7 @@ export async function publishCatalog(ctx) {
                 throw new Error('Invalid CSS2 stylesheet representation');
             const key = css2Key(ctx, pairs, sheet.userAgent);
             if (representations.has(key))
-                throw new Error('Duplicate stylesheet request');
+                throw new Error('Duplicate stylesheet request for browser class ' + browserClass(sheet.userAgent));
             representations.add(key);
             const urls = [...sheet.css.matchAll(/url\((https?:\/\/[^)]+)\)/g)].map(m => m[1]);
             if (urls.length === 0 || urls.some(url => !decoded.has(assetKey(url))))
@@ -125,13 +130,13 @@ export async function publishCatalog(ctx) {
         const key = cssKey(ctx, sheet.family, sheet.subset, sheet.userAgent);
         const blob = 'css-' + ctx.crypto.digest('sha256', sheet.css);
         await ctx.blobs.put(blob, new TextEncoder().encode(sheet.css));
-        await ctx.record(CSS, { family: sheet.family, subset: sheet.subset, userAgent: sheet.userAgent, blob }, fingerprint + ':' + key);
+        await ctx.record(CSS, { family: sheet.family, subset: sheet.subset, userAgent: sheet.userAgent, browserClass: browserClass(sheet.userAgent), blob }, fingerprint + ':' + key);
     }
     for (const sheet of sheets2) {
         const key = css2Key(ctx, css2Query(new URLSearchParams(sheet.query)), sheet.userAgent);
         const blob = 'css-' + ctx.crypto.digest('sha256', sheet.css);
         await ctx.blobs.put(blob, new TextEncoder().encode(sheet.css));
-        await ctx.record(CSS, { query: sheet.query, userAgent: sheet.userAgent, blob }, fingerprint + ':' + key);
+        await ctx.record(CSS, { query: sheet.query, userAgent: sheet.userAgent, browserClass: browserClass(sheet.userAgent), blob }, fingerprint + ':' + key);
     }
     await ctx.record(CATALOG, { families: [...names], fingerprint }, 'published');
     return Response.json({ families: [...names] }, { status: 201 });

package/dist/css/spec/SOURCE.md

@@ -7,9 +7,17 @@ GET /css?family=<family>:<variant>&subset=<subsets> with the exact configured
 User-Agent and consumes each @font-face's font-family, style, weight and src URL.
 Dub's Open Graph routes call GET /css2?family=Inter:wght@<weight> and Rallly's
 calls GET /css2?family=Noto+Sans+SC:wght@<weight>&text=<text>, both from a server
-without a browser User-Agent, and read the truetype src URL.
+without a browser User-Agent, and read the truetype src URL. next/font/google's build (Rallly's and
+Cal.diy's `next build`) calls GET /css2?family=Inter:wght@100..900&display=swap with a Chrome User-Agent and
+reads each woff2 src URL of its unicode-range faces.
+Twenty's front end (twentyhq/twenty 323e664, packages/twenty-front/index.html:33,37) links
+GET /css2?family=Inter:wght@400;500;600&display=swap and GET /css2?family=DM+Mono:wght@400;500;600&display=swap
+from the browser, which loads the woff2 faces its text needs.
+A representation is published for a browser class (src/semantics/shared.ts browserClass): Google serves any
+browser, choosing WOFF 2.0 and unicode-range subsets by the browser its User-Agent names, and the classes are
+the agents Google answered the same bytes (vendor/browser-classes.json).
 The supplied representations retain actual vendor CSS. Requests without a
-published representation answer a refusal, never an invented font format.
+representation published for their class answer a refusal, never an invented font format.
 text/display/effect on /css are outside this client's demand.
 
 SHA-256 `openapi.json`: bf7b9a3b70c3a75712fb784e22bfe07c0008dd55e1aa93b31cba8da26a64fb60

package/dist/css/src/semantics/css.js

@@ -1,4 +1,4 @@
-import { CATALOG, CSS, cssKey, htmlError } from "./shared.js";
+import { browserClass, CATALOG, CSS, cssKey, htmlError } from "./shared.js";
 // source: spec:getStylesheet "The representation is selected for the requesting browser."
 export async function getStylesheet(ctx) {
     const query = new URL(ctx.call.request.url).searchParams;
@@ -6,12 +6,14 @@ export async function getStylesheet(ctx) {
     if (!family || [...query.keys()].some(k => !['family', 'subset'].includes(k)))
         return htmlError(400, 'Bad font request');
     const generation = ctx.row(CATALOG, 'published')?.fingerprint;
-    const key = cssKey(ctx, family, subset, ctx.call.request.headers.get('user-agent') ?? '');
+    // the representation published for the browser class the agent belongs to (shared.ts browserClass)
+    const userAgent = ctx.call.request.headers.get('user-agent') ?? '';
+    const key = cssKey(ctx, family, subset, userAgent);
     const row = generation === undefined ? undefined : ctx.row(CSS, String(generation) + ':' + key);
     // Where the documentation stops: no supplied representation is a named
     // refusal, not an invented conversion or another browser's font format.
     if (!row)
-        return htmlError(400, 'Font family or browser representation is not published');
+        return htmlError(400, 'Font family or browser representation is not published (' + browserClass(userAgent) + ')');
     const body = await ctx.blobs.get(String(row.blob));
     if (!body)
         return htmlError(404, 'Font stylesheet not found');

package/dist/css/src/semantics/css2.js

@@ -1,4 +1,4 @@
-import { CATALOG, CSS, css2Key, css2Query, htmlError } from "./shared.js";
+import { browserClass, CATALOG, CSS, css2Key, css2Query, htmlError } from "./shared.js";
 // source: spec:getStylesheet2 "To request multiple families, specify the family= param for each family."
 export async function getStylesheet2(ctx) {
     const pairs = css2Query(new URL(ctx.call.request.url).searchParams);
@@ -6,14 +6,15 @@ export async function getStylesheet2(ctx) {
         return htmlError(400, 'Bad font request');
     const generation = ctx.row(CATALOG, 'published')?.fingerprint;
     const userAgent = ctx.call.request.headers.get('user-agent') ?? '';
-    const sheet = (agent) => generation === undefined ? undefined : ctx.row(CSS, String(generation) + ':' + css2Key(ctx, pairs, agent));
-    // Where the evidence stops: Google answered the same truetype stylesheet to no User-Agent, "node" and "undici"
-    // (vendor/inter.json). A request whose agent is not a browser's ("Mozilla/...") and has no representation of its
-    // own reads the one published for no agent; a browser without its own representation is refused, never sent
-    // another browser's format.
-    const row = sheet(userAgent) ?? (userAgent.startsWith('Mozilla/') ? undefined : sheet(''));
+    // The representation is the one published for the browser class the agent belongs to (shared.ts browserClass): a
+    // request with no browser's agent ("node", "undici", none) reads the truetype class, as Google answered the same CSS
+    // to all three (vendor/inter.json).
+    // source: spec:getStylesheet2 "The representation is selected for the requesting browser."
+    const row = generation === undefined ? undefined : ctx.row(CSS, String(generation) + ':' + css2Key(ctx, pairs, userAgent));
+    // Where the documentation stops: a class with no published representation is a named refusal, never another
+    // class's font format.
     if (!row)
-        return htmlError(400, 'Font family or browser representation is not published');
+        return htmlError(400, 'Font family or browser representation is not published (' + browserClass(userAgent) + ')');
     const body = await ctx.blobs.get(String(row.blob));
     if (!body)
         return htmlError(404, 'Font stylesheet not found');

package/dist/generated/pack-facts.json

@@ -0,0 +1,68 @@
+{
+  "//": "GENERATED by twin-standard facts from the pack descriptor; no prior-artifact entries are retained.",
+  "packs": {
+    "googlefonts": {
+      "adoption": {
+        "sdks": [],
+        "envStems": [
+          "GOOGLE_FONTS"
+        ],
+        "modules": [
+          "next/font/google"
+        ]
+      },
+      "hosts": [
+        {
+          "host": "www.googleapis.com",
+          "pathPattern": "^/webfonts/v1/webfonts$"
+        },
+        {
+          "host": "webfonts.googleapis.com",
+          "pathPattern": "^/v1/webfonts$"
+        },
+        {
+          "host": "fonts.googleapis.com",
+          "pathPattern": "^/css2?$"
+        },
+        {
+          "host": "fonts.gstatic.com",
+          "pathPattern": "^/(s/|l/font$)"
+        }
+      ],
+      "archetype": "crud",
+      "protocol": {
+        "declared": "3",
+        "major": 3,
+        "standing": "current"
+      },
+      "transport": "rest",
+      "resources": [
+        "webfont",
+        "_api_key",
+        "_font_catalog",
+        "_stylesheet",
+        "_font_file"
+      ],
+      "endpointEnvNone": "Pinned helper hardcodes the vendor API and CSS hosts, then downloads their returned gstatic URLs. Scoped host routing preserves these URLs.",
+      "credentialDoor": {
+        "path": "/_twin/app-credentials",
+        "body": {},
+        "account": {
+          "field": "account",
+          "tenancy": "Google Cloud project",
+          "source": "https://developers.google.com/fonts/docs/developer_api"
+        },
+        "deployment": {
+          "field": "deployment",
+          "object": "Project API key",
+          "source": "https://docs.cloud.google.com/docs/authentication/api-keys"
+        },
+        "fill": {
+          "GOOGLE_FONTS_API_KEY": "api_key"
+        }
+      },
+      "serveExport": "createGooglefontsTwinServer"
+    }
+  },
+  "undeclared": []
+}