@volter/twin-googlefonts 0.0.0-stage → 1.0.2

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 @@
+{}

package/css/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 { cssSemantics } from './semantics/index.ts';
+
+export function createCssLaneFetch(options: PackFetchOptions = {}): DerivedFetch {
+  return createPackFetch({
+    manifest,
+    surface: surface as DerivedSurface,
+    handlers: cssSemantics,
+  }, options);
+}

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

@@ -0,0 +1 @@
+{"generatedBy":"scripts/derive-pack.ts","spec":"openapi.json","format":"openapi","version":"v1","resources":[],"operations":[{"id":"getStylesheet","method":"get","path":"/css","pathParams":[],"query":[{"name":"family","type":"string","required":true},{"name":"subset","type":"string","required":false}],"body":[],"bodyEncoding":"none","successStatus":200,"class":"computed"},{"id":"getStylesheet2","method":"get","path":"/css2","pathParams":[],"query":[{"name":"display","type":"string","required":false},{"name":"family","type":"array","required":true},{"name":"text","type":"string","required":false}],"body":[],"bodyEncoding":"none","successStatus":200,"class":"computed"}]}

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

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

package/css/src/index.ts

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

package/css/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 browser-selected CSS', stores: 'Published catalog and font representations in the shared googlefonts store' },
+  
+  descriptor: { protocol: '3', transport: 'rest', archetype: 'crud', bin: 'world-googlefonts-css',
+    resources: [], specSource: 'css/spec/SOURCE.md', description: 'Google Fonts browser-selected CSS',
+    adoption: { sdks: [], envStems: [] }, hosts: [{ host: 'fonts.googleapis.com', pathPattern: '^/css2?$' }],
+    endpointEnvNone: 'The application hardcodes this vendor lane host.' },
+};

package/css/src/semantics/css.ts

@@ -0,0 +1,19 @@
+import type { HandlerContext } from '@volter/world-core';
+import { 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> {
+  const query = new URL(ctx.call.request.url).searchParams;
+  const family = query.get('family'), subset = query.get('subset') ?? 'latin';
+  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') ?? '');
+  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');
+  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

@@ -0,0 +1,20 @@
+import type { HandlerContext } from '@volter/world-core';
+import { 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> {
+  const pairs = css2Query(new URL(ctx.call.request.url).searchParams);
+  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');
+  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

@@ -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 css from './css.ts';
+import * as css2 from './css2.ts';
+
+export const cssSemantics: Record<string, Handler> = {
+  getStylesheet: css.getStylesheet,
+  getStylesheet2: css2.getStylesheet2,
+};

package/css/src/semantics/shared.ts

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

package/dist/api/spec/SOURCE.md

@@ -0,0 +1,17 @@
+# Google Fonts Developer API
+
+The unchanged Discovery document is Google's webfonts v1 contract, fetched
+2026-10-12 from https://www.googleapis.com/discovery/v1/apis/webfonts/v1/rest.
+It is converted by twin-world/scripts/spec-discovery-to-openapi.ts with that
+explicit date, retaining its revision, method id, schemas and parameter metadata.
+The vendor's documentation is https://developers.google.com/fonts/docs/developer_api.
+The application uses the documented older www.googleapis.com/webfonts prefix;
+the manifest's pathPrefix strips that prefix before the same derived operation.
+The Discovery base webfonts.googleapis.com/v1/webfonts is also served. Sort values
+are case-normalized, because the documentation and actual pinned app use lowercase
+popularity while Discovery lists uppercase enums. Advanced capabilities are outside
+this static-TTF catalog's demanded path and return a named refusal.
+
+SHA-256 `openapi.json`: 81395430e46dbeba78ab69301daa459d4e8fcfe80dfdf493118ce1c6e5a255b1
+
+SHA-256 `discovery.json`: `9dfed5186ad6ee434a82a33737af9ddc3a157005d7d6922820ac5d42ccef41f1`.

package/dist/api/spec/discovery.json

@@ -0,0 +1,306 @@
+{
+  "revision": "20260903",
+  "title": "Web Fonts Developer API",
+  "resources": {
+    "webfonts": {
+      "methods": {
+        "list": {
+          "parameterOrder": [],
+          "parameters": {
+            "capability": {
+              "location": "query",
+              "repeated": true,
+              "enum": [
+                "CAPABILITY_UNSPECIFIED",
+                "WOFF2",
+                "VF",
+                "FAMILY_TAGS"
+              ],
+              "description": "Controls the font urls in `Webfont.files`, by default, static ttf fonts are sent.",
+              "type": "string",
+              "enumDescriptions": [
+                "Default means static ttf fonts.",
+                "Use WOFF2(Compressed)instead of ttf.",
+                "Prefer variable font files instead of static fonts instantiated at standard weights.",
+                "Include tags that apply to the entire family in the response."
+              ]
+            },
+            "category": {
+              "type": "string",
+              "description": "Filters by Webfont.category, if category is found in Webfont.categories. If not set, returns all families.",
+              "location": "query"
+            },
+            "subset": {
+              "description": "Filters by Webfont.subset, if subset is found in Webfont.subsets. If not set, returns all families.",
+              "type": "string",
+              "location": "query"
+            },
+            "sort": {
+              "type": "string",
+              "description": "Enables sorting of the list.",
+              "location": "query",
+              "enumDescriptions": [
+                "No sorting specified, use the default sorting method.",
+                "Sort alphabetically",
+                "Sort by date added",
+                "Sort by popularity",
+                "Sort by number of styles",
+                "Sort by trending"
+              ],
+              "enum": [
+                "SORT_UNDEFINED",
+                "ALPHA",
+                "DATE",
+                "POPULARITY",
+                "STYLE",
+                "TRENDING"
+              ]
+            },
+            "family": {
+              "description": "Filters by Webfont.family, using literal match. If not set, returns all families",
+              "type": "string",
+              "location": "query",
+              "repeated": true
+            }
+          },
+          "response": {
+            "$ref": "WebfontList"
+          },
+          "httpMethod": "GET",
+          "description": "Retrieves the list of fonts currently served by the Google Fonts Developer API.",
+          "id": "webfonts.webfonts.list",
+          "path": "v1/webfonts",
+          "flatPath": "v1/webfonts"
+        }
+      }
+    }
+  },
+  "basePath": "",
+  "parameters": {
+    "quotaUser": {
+      "location": "query",
+      "description": "Available to use for quota purposes for server-side applications. Can be any arbitrary string assigned to a user, but should not exceed 40 characters.",
+      "type": "string"
+    },
+    "uploadType": {
+      "location": "query",
+      "type": "string",
+      "description": "Legacy upload protocol for media (e.g. \"media\", \"multipart\")."
+    },
+    "access_token": {
+      "description": "OAuth access token.",
+      "location": "query",
+      "type": "string"
+    },
+    "callback": {
+      "description": "JSONP",
+      "location": "query",
+      "type": "string"
+    },
+    "key": {
+      "description": "API key. Your API key identifies your project and provides you with API access, quota, and reports. Required unless you provide an OAuth 2.0 token.",
+      "location": "query",
+      "type": "string"
+    },
+    "prettyPrint": {
+      "description": "Returns response with indentations and line breaks.",
+      "location": "query",
+      "type": "boolean",
+      "default": "true"
+    },
+    "alt": {
+      "description": "Data format for response.",
+      "type": "string",
+      "default": "json",
+      "enum": [
+        "json",
+        "media",
+        "proto"
+      ],
+      "location": "query",
+      "enumDescriptions": [
+        "Responses with Content-Type of application/json",
+        "Media download with context-dependent Content-Type",
+        "Responses with Content-Type of application/x-protobuf"
+      ]
+    },
+    "upload_protocol": {
+      "description": "Upload protocol for media (e.g. \"raw\", \"multipart\").",
+      "type": "string",
+      "location": "query"
+    },
+    "oauth_token": {
+      "type": "string",
+      "description": "OAuth 2.0 token for the current user.",
+      "location": "query"
+    },
+    "fields": {
+      "description": "Selector specifying which fields to include in a partial response.",
+      "type": "string",
+      "location": "query"
+    },
+    "$.xgafv": {
+      "type": "string",
+      "location": "query",
+      "enum": [
+        "1",
+        "2"
+      ],
+      "enumDescriptions": [
+        "v1 error format",
+        "v2 error format"
+      ],
+      "description": "V1 error format."
+    }
+  },
+  "rootUrl": "https://webfonts.googleapis.com/",
+  "batchPath": "batch",
+  "discoveryVersion": "v1",
+  "protocol": "rest",
+  "mtlsRootUrl": "https://webfonts.mtls.googleapis.com/",
+  "servicePath": "",
+  "kind": "discovery#restDescription",
+  "ownerName": "Google",
+  "canonicalName": "Webfonts",
+  "id": "webfonts:v1",
+  "documentationLink": "https://developers.google.com/fonts/docs/developer_api",
+  "baseUrl": "https://webfonts.googleapis.com/",
+  "name": "webfonts",
+  "ownerDomain": "google.com",
+  "description": "The Google Web Fonts Developer API lets you retrieve information about web fonts served by Google.",
+  "icons": {
+    "x16": "http://www.google.com/images/icons/product/search-16.gif",
+    "x32": "http://www.google.com/images/icons/product/search-32.gif"
+  },
+  "schemas": {
+    "WebfontList": {
+      "properties": {
+        "items": {
+          "type": "array",
+          "items": {
+            "$ref": "Webfont"
+          },
+          "description": "The list of fonts currently served by the Google Fonts API."
+        },
+        "kind": {
+          "description": "This kind represents a list of webfont objects in the webfonts service.",
+          "type": "string"
+        }
+      },
+      "type": "object",
+      "id": "WebfontList",
+      "description": "Response containing the list of fonts currently served by the Google Fonts API."
+    },
+    "Tag": {
+      "description": "Metadata for a tag.",
+      "type": "object",
+      "id": "Tag",
+      "properties": {
+        "weight": {
+          "format": "float",
+          "type": "number",
+          "description": "The weight of the tag."
+        },
+        "name": {
+          "description": "The name of the tag.",
+          "type": "string"
+        }
+      }
+    },
+    "Webfont": {
+      "description": "Metadata describing a family of fonts.",
+      "id": "Webfont",
+      "type": "object",
+      "properties": {
+        "colorCapabilities": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "The color format(s) available for this family."
+        },
+        "category": {
+          "type": "string",
+          "description": "The category of the font."
+        },
+        "tags": {
+          "items": {
+            "$ref": "Tag"
+          },
+          "type": "array",
+          "description": "The tags that apply to this family."
+        },
+        "files": {
+          "additionalProperties": {
+            "type": "string"
+          },
+          "type": "object",
+          "description": "The font files (with all supported scripts) for each one of the available variants, as a key : value map."
+        },
+        "variants": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array",
+          "description": "The available variants for the font."
+        },
+        "lastModified": {
+          "description": "The date (format \"yyyy-MM-dd\") the font was modified for the last time.",
+          "type": "string"
+        },
+        "subsets": {
+          "description": "The scripts supported by the font.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "axes": {
+          "description": "Axis for variable fonts.",
+          "type": "array",
+          "items": {
+            "$ref": "Axis"
+          }
+        },
+        "kind": {
+          "type": "string",
+          "description": "This kind represents a webfont object in the webfonts service."
+        },
+        "menu": {
+          "description": "Font URL for menu subset, a subset of the font that is enough to display the font name",
+          "type": "string"
+        },
+        "version": {
+          "description": "The font version.",
+          "type": "string"
+        },
+        "family": {
+          "type": "string",
+          "description": "The name of the font."
+        }
+      }
+    },
+    "Axis": {
+      "type": "object",
+      "id": "Axis",
+      "properties": {
+        "start": {
+          "format": "float",
+          "type": "number",
+          "description": "minimum value"
+        },
+        "tag": {
+          "description": "tag name.",
+          "type": "string"
+        },
+        "end": {
+          "format": "float",
+          "description": "maximum value",
+          "type": "number"
+        }
+      },
+      "description": "Metadata for a variable font axis."
+    }
+  },
+  "version": "v1"
+}