@volter/twin-googlefonts 0.0.0-stage → 1.0.1

package/api/src/index.ts

@@ -0,0 +1,3 @@
+// The api lane of the googlefonts pack: the vendor's manifest routes its requests here.
+export { createApiLaneFetch } from './fetch.ts';
+export { manifest } from './manifest.ts';

package/api/src/manifest.ts

@@ -0,0 +1,31 @@
+// Vendor wire facts; the surface is derived from the retained spec.
+import type { DerivedManifest } from '@volter/world-core';
+import { states } from './semantics/states.ts';
+export const manifest: DerivedManifest = {
+  vendor: 'googlefonts', service: 'googlefonts', body: { json: 'always' },
+  ids: { template: '{uuid}' }, time: 'iso',
+  error: { error: { code: '{status}', message: '{message}', status: '{kind}' } },
+  readOnly: { status: 403, kind: 'PERMISSION_DENIED', message: 'Read-only World' },
+  notFound: { status: 404, kind: 'NOT_FOUND', message: 'Not Found' },
+  gap: { status: 404, kind: 'NOT_FOUND', message: 'Not Found' },
+  list: { style: 'envelope', envelope: { items: '{data}' }, limit: { param: 'limit', default: 100, max: 100 } },
+  deleted: {},
+  resources: { webfont: { idPrefix: '', ...states.webfont,
+    refresh: { none: 'The selected reference snapshot is publisher data, not an account-owned font mutation; no full-live-catalog refresh is claimed.' } },
+    _project: { idPrefix: '' },
+    _api_key: { idPrefix: '', ...states._api_key } },
+  discovery: { twinOf: 'Google Fonts Developer API', stores: 'Published catalog and font representations in the shared googlefonts store' },
+  // The pinned helper uses the older documented prefix; no app request is rewritten.
+  pathPrefix: '^/webfonts(?=/v1/webfonts$)',
+  // The core reads query keys and gates against actual issued hashes. Doors bypass the API gate.
+  auth: { header: 'x-goog-api-key', scheme: '', also: [{ query: 'key' }], paths: '^/(webfonts/)?v1/webfonts$',
+    missing: { status: 403, kind: 'PERMISSION_DENIED', message: 'The request is missing a valid API key.' },
+    invalid: { status: 400, kind: 'INVALID_ARGUMENT', message: 'API key not valid. Please pass a valid API key.' },
+    invalidKeys: [], gateWhenAbsent: true, held: { storedAs: '_api_key', hashField: 'sha256' } },
+  doors: [{ id: 'appCredentials', method: 'POST', path: '/_twin/app-credentials', note: 'Issue the World application key' },
+    { id: 'publishCatalog', method: 'POST', path: '/_twin/catalog', note: 'Google publishes fonts without a Developer API create operation; import its actual catalog/CSS/blob snapshot' }],
+  descriptor: { protocol: '3', transport: 'rest', archetype: 'crud', bin: 'world-googlefonts-api',
+    resources: [], specSource: 'api/spec/SOURCE.md', description: 'Google Fonts Developer API',
+    adoption: { sdks: [], envStems: [] }, hosts: [{ host: 'webfonts.googleapis.com' }, { host: 'www.googleapis.com', pathPattern: '^/webfonts/v1/webfonts$' }],
+    endpointEnvNone: 'The application hardcodes this vendor lane host.' },
+};

package/api/src/semantics/doors.ts

@@ -0,0 +1,131 @@
+// 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';
+
+// source: https://developers.google.com/fonts/docs/developer_api
+export async function appCredentials(ctx: HandlerContext): Promise<Response> {
+  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);
+  const key = await ctx.accountKey('api-key', KEY, {
+    make: async () => {
+      const row = await ctx.create(KEY, { _project: project.id, name: ctx.deployment() || 'world' }, 'api_key.create');
+      const id = String(row.id), secret = await value(id);
+      await ctx.record(KEY, { sha256: ctx.crypto.digest('sha256', secret) }, id);
+      return id;
+    },
+    read: async row => {
+      if (row._project !== project.id) return undefined;
+      const secret = await value(String(row.id));
+      return row.sha256 === ctx.crypto.digest('sha256', secret) ? secret : undefined;
+    },
+  });
+  return Response.json({ api_key: key.secret });
+}
+
+// source: https://developers.google.com/fonts/docs/developer_api
+export async function publishCatalog(ctx: HandlerContext): Promise<Response> {
+  // There is no Developer API create-font operation. This explicit publisher
+  // door imports real vendor-shaped objects and their representations.
+  const input = object(ctx.body), catalog = object(input.catalog);
+  const fonts = Array.isArray(catalog.items) ? catalog.items.map(object) : [];
+  const sheets = Array.isArray(input.stylesheets) ? input.stylesheets.map(object) : [];
+  const files = Array.isArray(input.assets) ? input.assets.map(object) : [];
+  // CSS2 serves Google's whole library by its query, not only the Developer API items published here.
+  const sheets2 = Array.isArray(input.stylesheets2) ? input.stylesheets2.map(object) : [];
+  if (catalog.kind !== 'webfonts#webfontList' || fonts.length === 0)
+    return googleError(400, 'A webfonts#webfontList catalog is required');
+  const names = new Set<string>();
+  const strings = (value: unknown): value is string[] => Array.isArray(value) && value.length > 0 &&
+    value.every(v => typeof v === 'string' && v.length > 0) && new Set(value).size === value.length;
+  const decoded = new Map<string, { url: string; contentType: string; bytes: Uint8Array; hash: string }>();
+  try {
+    for (const file of files) {
+      if (typeof file.url !== 'string' || typeof file.contentType !== 'string' ||
+          !/^[a-zA-Z0-9.+-]+\/[a-zA-Z0-9.+-]+(?:;[^\r\n]*)?$/.test(file.contentType) ||
+          typeof file.base64 !== 'string' || !file.base64 ||
+          !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(file.base64))
+        throw new Error('Each asset needs its gstatic URL, Content-Type and complete base64 bytes');
+      const key = assetKey(file.url);
+      if (!/^\/s\/[^?]+$|^\/l\/font\?/.test(key) || decoded.has(key)) throw new Error('Invalid or duplicate asset URL');
+      const bytes = Uint8Array.from(atob(file.base64), c => c.charCodeAt(0));
+      if (bytes.length === 0) throw new Error('Font bytes must not be empty');
+      decoded.set(key, { url: file.url, contentType: file.contentType, bytes, hash: ctx.crypto.digest('sha256', bytes) });
+    }
+    for (const font of fonts) {
+      if (typeof font.family !== 'string' || !font.family || names.has(font.family) ||
+          font.kind !== 'webfonts#webfont' || !strings(font.variants) || !strings(font.subsets) ||
+          typeof font.category !== 'string' || typeof font.version !== 'string' ||
+          typeof font.lastModified !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(font.lastModified))
+        throw new Error('Invalid or duplicate vendor font item');
+      names.add(font.family);
+      const fileMap = object(font.files);
+      for (const variant of font.variants) {
+        if (typeof fileMap[variant] !== 'string' || !decoded.has(assetKey(fileMap[variant] as string)))
+          throw new Error('Every advertised variant file must have a genuine supplied blob');
+      }
+      if (font.menu !== undefined && (typeof font.menu !== 'string' || !decoded.has(assetKey(font.menu))))
+        throw new Error('An advertised menu URL must have a supplied blob');
+    }
+    const representations = new Set<string>();
+    for (const sheet of sheets) {
+      if (typeof sheet.family !== 'string' || typeof sheet.subset !== 'string' ||
+          typeof sheet.userAgent !== 'string' || !sheet.userAgent || typeof sheet.css !== 'string' ||
+          !sheet.css.includes('@font-face')) throw new Error('Invalid stylesheet representation');
+      const split = sheet.family.lastIndexOf(':');
+      const family = split < 0 ? sheet.family : sheet.family.slice(0, split);
+      const variant = split < 0 ? 'regular' : sheet.family.slice(split + 1);
+      const font = fonts.find(f => f.family === family);
+      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');
+      const key = cssKey(ctx, sheet.family, sheet.subset, sheet.userAgent);
+      if (representations.has(key)) throw new Error('Duplicate stylesheet request');
+      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))))
+        throw new Error('Every stylesheet src URL must have a supplied blob');
+    }
+    for (const sheet of sheets2) {
+      const pairs = typeof sheet.query === 'string' ? css2Query(new URLSearchParams(sheet.query)) : undefined;
+      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');
+      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))))
+        throw new Error('Every stylesheet src URL must have a supplied blob');
+    }
+    // A content-addressed font URL keeps its bytes across publications.
+    for (const [key, file] of decoded) {
+      const prior = ctx.row(FILE, key);
+      if (prior && prior.sha256 !== file.hash) return googleError(409, 'Published font URL already names other bytes', 'ALREADY_EXISTS');
+    }
+  } catch (cause) { return googleError(400, cause instanceof Error ? cause.message : 'Invalid catalog publication'); }
+  const fingerprint = ctx.crypto.digest('sha256', JSON.stringify(input));
+  if (ctx.row(CATALOG, 'published')?.fingerprint === fingerprint) return Response.json({ families: [...names] });
+  // Validation precedes all writes. Publish the catalog pointer last: readers
+  // select only this generation's metadata and stylesheet records.
+  for (const [key, file] of decoded) {
+    const blob = 'font-' + file.hash;
+    await ctx.blobs.put(blob, file.bytes);
+    await ctx.record(FILE, { url: file.url, contentType: file.contentType, sha256: file.hash, blob }, key);
+  }
+  // A font item is the vendor's resource, not bookkeeping: written as the publication that made it.
+  for (const font of fonts) await ctx.write(FONT, fingerprint + ':' + font.family, font, 'webfont.publish');
+  for (const sheet of sheets) {
+    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);
+  }
+  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(CATALOG, { families: [...names], fingerprint }, 'published');
+  return Response.json({ families: [...names] }, { status: 201 });
+}

package/api/src/semantics/index.ts

@@ -0,0 +1,8 @@
+// GENERATED by scripts/create-pack.ts --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';
+
+export const apiSemantics: Record<string, Handler> = {
+  "webfonts.webfonts.list": webfonts.webfonts_webfonts_list,
+};

package/api/src/semantics/shared.ts

@@ -0,0 +1 @@
+export * from '../../../src/semantics/shared.ts';

package/api/src/semantics/states.ts

@@ -0,0 +1,6 @@
+// The catalog and its immutable representations have no status transition.
+// Keys are issued once and stored as hashes; this scope has no key revocation API.
+export const states = {
+  webfont: { notState: ['family', 'variants', 'subsets', 'category', 'version', 'lastModified'] },
+  _api_key: { notState: ['sha256'] },
+};

package/api/src/semantics/webfonts.ts

@@ -0,0 +1,32 @@
+import type { HandlerContext } from '@volter/world-core';
+import { FONT, CATALOG, googleError } from './shared.ts';
+
+// source: spec:webfonts.webfonts.list "Retrieves the list of fonts currently served by the Google Fonts Developer API."
+export async function webfonts_webfonts_list(ctx: HandlerContext): Promise<Response> {
+  const query = new URL(ctx.call.request.url).searchParams;
+  // Where this scope stops: the demand selects the default static-TTF catalog.
+  // VF/WOFF2/FAMILY_TAGS need an independently published capability snapshot.
+  if (query.getAll('capability').some(c => c && c !== 'CAPABILITY_UNSPECIFIED'))
+    return googleError(400, 'This published catalog does not provide the requested capability');
+  const published = ctx.row(CATALOG, 'published');
+  const names = Array.isArray(published?.families) ? published.families : [];
+  let items = names.flatMap(family => {
+    const row = ctx.row(FONT, String(published?.fingerprint) + ':' + String(family));
+    return row ? [ctx.own(row)] : [];
+  });
+  for (const field of ['family', 'subset', 'category']) {
+    const asked = query.getAll(field);
+    if (asked.length) items = items.filter(item => asked.some(value => field === 'subset'
+      ? Array.isArray(item.subsets) && item.subsets.includes(value) : item[field] === value));
+  }
+  // source: https://developers.google.com/fonts/docs/developer_api
+  const sort = (query.get('sort') ?? 'alpha').toLowerCase();
+  if (!['sort_undefined', 'alpha', 'date', 'popularity', 'style', 'trending'].includes(sort))
+    return googleError(400, 'Invalid sort value');
+  if (sort === 'alpha' || sort === 'sort_undefined') items.sort((a,b) => String(a.family).localeCompare(String(b.family), 'en'));
+  else if (sort === 'date') items.sort((a,b) => String(b.lastModified).localeCompare(String(a.lastModified)));
+  else if (sort === 'style') items.sort((a,b) => (Array.isArray(b.variants) ? b.variants.length : 0) - (Array.isArray(a.variants) ? a.variants.length : 0));
+  // Popularity/trending retain the publisher's catalog order. The reference
+  // snapshot is one actual font, not a manufactured global popularity ranking.
+  return Response.json({ kind: 'webfonts#webfontList', items });
+}

package/assets/spec/SOURCE.md

@@ -0,0 +1,11 @@
+# Google Fonts font files
+
+Google's CSS API guide https://developers.google.com/fonts/docs/getting_started
+describes the stylesheet link and font selection. The retained vendor responses
+for the exact application user agents (vendor/inputs.json) bind each actual src URL
+to its font file; EOT and SVG use /l/font with kit/skey/v, the other representations
+use /s/<family>/<version>/<file>. All bytes and Content-Type values are unchanged
+vendor answers, retained under their source hashes. No format conversion occurs.
+Only GET is demanded; unsupported operations remain gaps.
+
+SHA-256 `openapi.json`: a008d26adacbeaa5027767e9fa6eadce49ef5b8bdefcb6aa8f3ed9ee07347ac5

package/assets/spec/openapi.json

@@ -0,0 +1,162 @@
+{
+  "openapi": "3.0.3",
+  "info": {
+    "title": "Google Fonts font-file hosts",
+    "version": "2026-10-12"
+  },
+  "servers": [
+    {
+      "url": "https://fonts.gstatic.com"
+    }
+  ],
+  "paths": {
+    "/s/{file}": {
+      "get": {
+        "operationId": "getFontFile",
+        "description": "Download the font-file bytes named by a Google Fonts stylesheet src URL.",
+        "parameters": [
+          {
+            "name": "file",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The font-file bytes at the returned stylesheet URL",
+            "content": {
+              "font/eot": {
+                "schema": {
+                  "type": "string",
+                  "format": "binary"
+                }
+              },
+              "font/ttf": {
+                "schema": {
+                  "type": "string",
+                  "format": "binary"
+                }
+              },
+              "font/woff": {
+                "schema": {
+                  "type": "string",
+                  "format": "binary"
+                }
+              },
+              "font/woff2": {
+                "schema": {
+                  "type": "string",
+                  "format": "binary"
+                }
+              },
+              "image/svg+xml": {
+                "schema": {
+                  "type": "string",
+                  "format": "binary"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Font file not found",
+            "content": {
+              "text/html": {
+                "schema": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        },
+        "tags": [
+          "files"
+        ]
+      }
+    },
+    "/l/font": {
+      "get": {
+        "operationId": "getLegacyFontFile",
+        "description": "Download the font-file bytes named by a Google Fonts stylesheet src URL for a legacy browser.",
+        "parameters": [
+          {
+            "name": "kit",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "skey",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "v",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The font-file bytes at the returned stylesheet URL",
+            "content": {
+              "font/eot": {
+                "schema": {
+                  "type": "string",
+                  "format": "binary"
+                }
+              },
+              "font/ttf": {
+                "schema": {
+                  "type": "string",
+                  "format": "binary"
+                }
+              },
+              "font/woff": {
+                "schema": {
+                  "type": "string",
+                  "format": "binary"
+                }
+              },
+              "font/woff2": {
+                "schema": {
+                  "type": "string",
+                  "format": "binary"
+                }
+              },
+              "image/svg+xml": {
+                "schema": {
+                  "type": "string",
+                  "format": "binary"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Font file not found",
+            "content": {
+              "text/html": {
+                "schema": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        },
+        "tags": [
+          "files"
+        ]
+      }
+    }
+  }
+}

package/assets/spec/sources.json

@@ -0,0 +1 @@
+{}

package/assets/src/fetch.ts

@@ -0,0 +1,14 @@
+// GENERATED by scripts/create-pack.ts (--init, --index): a fixed file. The kernel serves the discovery door, the clock,
+// the World's doors, the vendor's screens and the API from the pack's parts (architecture, "The pack contract").
+import { createPackFetch, type DerivedFetch, type DerivedSurface, type PackFetchOptions } from '@volter/world-core';
+import surface from './generated/surface.gen.json' with { type: 'json' };
+import { manifest } from './manifest.ts';
+import { assetsSemantics } from './semantics/index.ts';
+
+export function createAssetsLaneFetch(options: PackFetchOptions = {}): DerivedFetch {
+  return createPackFetch({
+    manifest,
+    surface: surface as DerivedSurface,
+    handlers: assetsSemantics,
+  }, options);
+}

package/assets/src/generated/surface.gen.json

@@ -0,0 +1 @@
+{"generatedBy":"scripts/derive-pack.ts","spec":"openapi.json","format":"openapi","version":"2026-10-12","resources":[],"operations":[{"id":"getLegacyFontFile","method":"get","path":"/l/font","pathParams":[],"query":[{"name":"kit","type":"string","required":true},{"name":"skey","type":"string","required":true},{"name":"v","type":"string","required":true}],"body":[],"bodyEncoding":"none","successStatus":200,"responseMedia":{"200":["image/svg+xml"]},"class":"computed"},{"id":"getFontFile","method":"get","path":"/s/{file}","pathParams":["file"],"query":[],"body":[],"bodyEncoding":"none","successStatus":200,"responseMedia":{"200":["image/svg+xml"]},"class":"computed"}]}

package/assets/src/generated/ui.gen.json

@@ -0,0 +1 @@
+{"generatedBy":"scripts/derive-pack.ts","resources":{}}

package/assets/src/index.ts

@@ -0,0 +1,3 @@
+// The assets lane of the googlefonts pack: the vendor's manifest routes its requests here.
+export { createAssetsLaneFetch } from './fetch.ts';
+export { manifest } from './manifest.ts';

package/assets/src/manifest.ts

@@ -0,0 +1,19 @@
+// Vendor wire facts; the surface is derived from the retained spec.
+import type { DerivedManifest } from '@volter/world-core';
+export const manifest: DerivedManifest = {
+  vendor: 'googlefonts', service: 'googlefonts', body: { json: 'always' },
+  ids: { template: '{uuid}' }, time: 'iso',
+  error: { error: { code: '{status}', message: '{message}', status: '{kind}' } },
+  readOnly: { status: 403, kind: 'PERMISSION_DENIED', message: 'Read-only World' },
+  notFound: { status: 404, kind: 'NOT_FOUND', message: 'Not Found' },
+  gap: { status: 404, kind: 'NOT_FOUND', message: 'Not Found' },
+  list: { style: 'envelope', envelope: { items: '{data}' }, limit: { param: 'limit', default: 100, max: 100 } },
+  deleted: {},
+  resources: {},
+  discovery: { twinOf: 'Google Fonts font bytes', stores: 'Published catalog and font representations in the shared googlefonts store' },
+  spanning: ['file'],
+  descriptor: { protocol: '3', transport: 'rest', archetype: 'crud', bin: 'world-googlefonts-assets',
+    resources: [], specSource: 'assets/spec/SOURCE.md', description: 'Google Fonts font bytes',
+    adoption: { sdks: [], envStems: [] }, hosts: [{ host: 'fonts.gstatic.com', pathPattern: '^/(s/|l/font$)' }],
+    endpointEnvNone: 'The application hardcodes this vendor lane host.' },
+};

package/assets/src/semantics/index.ts

@@ -0,0 +1,10 @@
+// GENERATED by scripts/create-pack.ts --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';
+import * as s from './s.ts';
+
+export const assetsSemantics: Record<string, Handler> = {
+  getFontFile: s.getFontFile,
+  getLegacyFontFile: l.getLegacyFontFile,
+};

package/assets/src/semantics/l.ts

@@ -0,0 +1,4 @@
+import type { HandlerContext } from '@volter/world-core';
+import { downloadFont } from './shared.ts';
+// source: spec:getLegacyFontFile "Download the font-file bytes named by a Google Fonts stylesheet src URL for a legacy browser."
+export async function getLegacyFontFile(ctx: HandlerContext): Promise<Response> { return downloadFont(ctx); }

package/assets/src/semantics/s.ts

@@ -0,0 +1,4 @@
+import type { HandlerContext } from '@volter/world-core';
+import { downloadFont } from './shared.ts';
+// source: spec:getFontFile "Download the font-file bytes named by a Google Fonts stylesheet src URL."
+export async function getFontFile(ctx: HandlerContext): Promise<Response> { return downloadFont(ctx); }

package/assets/src/semantics/shared.ts

@@ -0,0 +1,13 @@
+import type { HandlerContext } from '@volter/world-core';
+import { FILE, assetKey, htmlError } from '../../../src/semantics/shared.ts';
+
+export async function downloadFont(ctx: HandlerContext): Promise<Response> {
+  const request = new URL(ctx.call.request.url);
+  const vendorUrl = new URL(request.pathname + request.search, 'https://fonts.gstatic.com');
+  const row = ctx.row(FILE, assetKey(vendorUrl.href));
+  if (!row) return htmlError(404, 'Font file not found');
+  const body = await ctx.blobs.get(String(row.blob));
+  if (!body) return htmlError(404, 'Font file not found');
+  return new Response(Uint8Array.from(body).buffer, { headers: { 'content-type': String(row.contentType), 'content-length': String(body.length),
+    'access-control-allow-origin': '*', 'cache-control': 'public, max-age=31536000, immutable' } });
+}

package/css/spec/SOURCE.md

@@ -0,0 +1,15 @@
+# Google Fonts CSS API v1 and CSS2
+
+This contract is written from Google's https://developers.google.com/fonts/docs/getting_started,
+https://developers.google.com/fonts/docs/css2 and the retained responses in vendor/inputs.json,
+vendor/inter.json and vendor/noto-sans-sc-text.json. google-webfonts-helper calls
+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.
+The supplied representations retain actual vendor CSS. Requests without a
+published representation 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/spec/openapi.json

@@ -0,0 +1,142 @@
+{
+  "openapi": "3.0.3",
+  "info": {
+    "title": "Google Fonts CSS API",
+    "version": "v1"
+  },
+  "servers": [
+    {
+      "url": "https://fonts.googleapis.com"
+    }
+  ],
+  "paths": {
+    "/css": {
+      "get": {
+        "operationId": "getStylesheet",
+        "description": "The Google Fonts API provides the regular version of the requested fonts by default. To request other styles or weights, append a colon to the name of the font. The subset parameter specifies script subsets. The representation is selected for the requesting browser.",
+        "parameters": [
+          {
+            "name": "family",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "subset",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "User-Agent",
+            "in": "header",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "A stylesheet referring to font-file URLs",
+            "content": {
+              "text/css": {
+                "schema": {
+                  "type": "string"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad font request",
+            "content": {
+              "text/html": {
+                "schema": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/css2": {
+      "get": {
+        "operationId": "getStylesheet2",
+        "description": "It all starts with a new base URL: https://fonts.googleapis.com/css2 The syntax for specifying styles within each family has changed to describe variable font ‘design spaces.’ To request multiple families, specify the family= param for each family. Please note that the 'text=' parameter can only be specified once. It applies to all families in the request. As a general note, the updated CSS API is more strict about what requests are accepted than the original CSS API. The representation is selected for the requesting browser.",
+        "parameters": [
+          {
+            "name": "family",
+            "in": "query",
+            "required": true,
+            "style": "form",
+            "explode": true,
+            "description": "<family_name>[:<axis_tag_list>@<axis_tuple_list>]",
+            "schema": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          },
+          {
+            "name": "text",
+            "in": "query",
+            "required": false,
+            "description": "The text that will be displayed in the requested typeface",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "display",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "enum": [
+                "auto",
+                "block",
+                "swap",
+                "fallback",
+                "optional"
+              ]
+            }
+          },
+          {
+            "name": "User-Agent",
+            "in": "header",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "A stylesheet referring to font-file URLs",
+            "content": {
+              "text/css": {
+                "schema": {
+                  "type": "string"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad font request",
+            "content": {
+              "text/html": {
+                "schema": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/css/spec/sources.json

@@ -0,0 +1 @@
+{}