@volter/twin-googlefonts 0.0.0-stage → 1.0.2

package/dist/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/dist/css/spec/sources.json

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

package/dist/css/src/fetch.d.ts

@@ -0,0 +1,2 @@
+import { type DerivedFetch, type PackFetchOptions } from '@volter/world-core';
+export declare function createCssLaneFetch(options?: PackFetchOptions): DerivedFetch;

package/dist/css/src/fetch.js

@@ -0,0 +1,13 @@
+// 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 } from '@volter/world-core';
+import surface from './generated/surface.gen.json' with { type: 'json' };
+import { manifest } from "./manifest.js";
+import { cssSemantics } from "./semantics/index.js";
+export function createCssLaneFetch(options = {}) {
+    return createPackFetch({
+        manifest,
+        surface: surface,
+        handlers: cssSemantics,
+    }, options);
+}

package/dist/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/dist/css/src/generated/ui.gen.json

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

package/dist/css/src/index.d.ts

@@ -0,0 +1,2 @@
+export { createCssLaneFetch } from './fetch.js';
+export { manifest } from './manifest.js';

package/dist/css/src/index.js

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

package/dist/css/src/manifest.d.ts

@@ -0,0 +1,2 @@
+import type { DerivedManifest } from '@volter/world-core';
+export declare const manifest: DerivedManifest;

package/dist/css/src/manifest.js

@@ -0,0 +1,16 @@
+export const manifest = {
+    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/dist/css/src/semantics/css.d.ts

@@ -0,0 +1,2 @@
+import type { HandlerContext } from '@volter/world-core';
+export declare function getStylesheet(ctx: HandlerContext): Promise<Response>;

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

@@ -0,0 +1,19 @@
+import { 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;
+    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/dist/css/src/semantics/css2.d.ts

@@ -0,0 +1,2 @@
+import type { HandlerContext } from '@volter/world-core';
+export declare function getStylesheet2(ctx: HandlerContext): Promise<Response>;

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

@@ -0,0 +1,21 @@
+import { 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);
+    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) => 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/dist/css/src/semantics/index.d.ts

@@ -0,0 +1,2 @@
+import type { Handler } from '@volter/world-core';
+export declare const cssSemantics: Record<string, Handler>;

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

@@ -0,0 +1,6 @@
+import * as css from "./css.js";
+import * as css2 from "./css2.js";
+export const cssSemantics = {
+    getStylesheet: css.getStylesheet,
+    getStylesheet2: css2.getStylesheet2,
+};

package/dist/css/src/semantics/shared.d.ts

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

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

@@ -0,0 +1 @@
+export * from "../../../src/semantics/shared.js";

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": []
+}