@volter/twin-googlefonts 0.0.0-stage → 1.0.2

package/journeys/decisions.json

@@ -0,0 +1,64 @@
+{
+  "about": "Source-bound decisions before handler implementation; each lane shares one googlefonts store. Qualification remains separate.",
+  "decisions": [
+    {
+      "operation": "webfonts.webfonts.list",
+      "lane": "api",
+      "mechanism": "handler",
+      "demand": "Pinned production startup",
+      "why": "Read unchanged vendor font items in the stored catalog order; alpha/date/style sorting and family/subset/category filtering consume the Developer API fields. first-use axios catalog call asserts the list and derives all later selections from its returned item. Never return a full-live-catalog claim."
+    },
+    {
+      "operation": "getStylesheet",
+      "lane": "css",
+      "mechanism": "handler",
+      "demand": "All five pinned config.ts UAs",
+      "why": "Use exact published CSS per request/UA, with the real font-family/style/weight/src consumed by fetchCSS; first-use downloads every returned src. Unsupported representations answer a refusal."
+    },
+    {
+      "operation": "getStylesheet2",
+      "lane": "css",
+      "mechanism": "handler",
+      "demand": "Dub's Inter weights and Rallly's CJK text subsets, both from a server; Rallly's and Cal.diy's next/font/google build of Inter's variable weights, with next/font's browser User-Agent",
+      "why": "Use the exact published CSS per ordered CSS2 query and User-Agent; a non-browser agent without its own representation reads the one published for no agent, as Google answered the same CSS to none, node and undici. Unpublished families, text subsets and browser representations answer a refusal; text= and display= given twice, or another parameter, are a bad request."
+    },
+    {
+      "operation": "getFontFile",
+      "lane": "assets",
+      "mechanism": "handler",
+      "demand": "Archive stream for returned /s URL; the woff2 faces next/font/google self-hosts at build",
+      "why": "Resolve the actual vendor URL to its resource blob and preserve Content-Type/bytes; no conversion or placeholder font."
+    },
+    {
+      "operation": "getLegacyFontFile",
+      "lane": "assets",
+      "mechanism": "handler",
+      "demand": "EOT/SVG src uses /l/font query URL",
+      "why": "Same blob mechanism; preserve kit/skey/v and ignore the SVG fragment as HTTP does."
+    },
+    {
+      "operation": "door:appCredentials",
+      "lane": "api",
+      "mechanism": "door",
+      "demand": "World boot credential fill",
+      "why": "Google issues the key outside the Fonts read-only API: a standard API key belongs to a Google Cloud project, made on that project's Credentials page, and associates each request with the project for billing and quota; the Developer API takes it as key= and nothing else. The door keeps a project per World organization (ctx.tenant) and one key per deployment under it (ctx.accountKey), drawn from the World's seed so a World returned to its seed issues the same key; only its hash is recorded.",
+      "sourceRules": [
+        {
+          "source": "https://developers.google.com/fonts/docs/developer_api",
+          "means": "the Developer API identifies the application by an API key, key= on every request, made on the Cloud console's Credentials page"
+        },
+        {
+          "source": "https://docs.cloud.google.com/docs/authentication/api-keys",
+          "means": "a standard API key associates a request with a project for billing and quota; keys are listed and created per project (console, gcloud services api-keys, keys.create)"
+        }
+      ]
+    },
+    {
+      "operation": "door:publishCatalog",
+      "lane": "api",
+      "mechanism": "door",
+      "demand": "Vendor-side prerequisite for a reference-data World",
+      "why": "There is no Developer API create-font endpoint. Validate a complete vendor-shaped catalog/CSS/blob publication before recording it; the default seed and first-use supply retained genuine bytes. This is an explicit publisher door, not a handler pretending a vendor mutation."
+    }
+  ]
+}

package/journeys/demand.json

@@ -0,0 +1,101 @@
+{
+  "measured": "2026-10-12: source-only read of every non-test server TS file at ff245dc87cfcbaeacd4120cf1b4a7443b59db42f, image 77e89ea9. No application or vendor-key request was executed. The normal start fetches the Developer API catalog; font detail/download reaches CSS for all five configured UAs and downloads its returned URLs. GOOGLE_FONTS_USE_TEST_JSON is excluded, and is not set. 2026-10-15: source-only read of Dub 7e01013 and Rallly 3e63239 Open Graph routes; Google's CSS2 answers retained with no User-Agent, node and undici (vendor/inter.json).",
+  "applications": [
+    {
+      "name": "majodev/google-webfonts-helper",
+      "commit": "ff245dc87cfcbaeacd4120cf1b4a7443b59db42f",
+      "client": "axios 1.20.0, unchanged production server",
+      "backend": [
+        {
+          "call": "GET www.googleapis.com/webfonts/v1/webfonts?sort=popularity&key=<issued key>",
+          "operation": "webfonts.webfonts.list",
+          "evidence": "server/logic/fetchGoogleFonts.ts:62"
+        },
+        {
+          "call": "GET fonts.googleapis.com/css?family=<family>:<variant>&subset=<subsets>, User-Agent from config.ts",
+          "operation": "getStylesheet",
+          "evidence": "server/logic/fetchCSS.ts:19"
+        },
+        {
+          "call": "GET fonts.gstatic.com/s/... bytes returned in the CSS",
+          "operation": "getFontFile",
+          "evidence": "server/logic/fetchFontSubsetArchive.ts:104"
+        },
+        {
+          "call": "GET fonts.gstatic.com/l/font?kit=...&skey=...&v=... for EOT/SVG representations",
+          "operation": "getLegacyFontFile",
+          "evidence": "server/logic/fetchFontURLs.ts:61; vendor/inputs.json retained Google EOT/SVG CSS"
+        }
+      ]
+    },
+    {
+      "name": "dubinc/dub",
+      "commit": "7e01013",
+      "client": "Next.js server fetch, no browser User-Agent",
+      "backend": [
+        {
+          "call": "GET fonts.googleapis.com/css2?family=Inter:wght@<500|600|700>",
+          "operation": "getStylesheet2",
+          "evidence": "apps/web/app/api/og/load-google-font.ts:2-3; callers apps/web/app/api/og/program/route.tsx:29, analytics/route.tsx:18, partner-earnings/route.tsx:27, program/categories/route.tsx:34, partner-rewind/route.tsx:29"
+        },
+        {
+          "call": "GET fonts.gstatic.com/s/... truetype URL returned in the CSS",
+          "operation": "getFontFile",
+          "evidence": "apps/web/app/api/og/load-google-font.ts:9"
+        }
+      ]
+    },
+    {
+      "name": "lukevella/rallly",
+      "commit": "3e63239",
+      "client": "Next.js server fetch, no browser User-Agent",
+      "backend": [
+        {
+          "call": "GET fonts.googleapis.com/css2?family=Noto+Sans+SC:wght@<400|700>&text=<rendered CJK text>",
+          "operation": "getStylesheet2",
+          "evidence": "apps/landing/src/app/[locale]/opengraph-image.tsx:26-27 (CJK locales only)"
+        },
+        {
+          "call": "GET fonts.gstatic.com truetype URL returned in the CSS",
+          "operation": "getFontFile",
+          "evidence": "apps/landing/src/app/[locale]/opengraph-image.tsx:38"
+        }
+      ]
+    },
+    {
+      "name": "lukevella/rallly",
+      "commit": "195877a38de4fb96bce921011668871da1121174",
+      "client": "next build (Next.js 16.1.6, Turbopack's next/font: crates/next-core/src/next_font/google, User-Agent USER_AGENT_FOR_GOOGLE_FONTS)",
+      "backend": [
+        {
+          "call": "GET fonts.googleapis.com/css2?family=Inter:wght@100..900&display=swap",
+          "operation": "getStylesheet2",
+          "evidence": "apps/web/src/app/[locale]/layout.tsx:8,31-34 (Inter, subsets latin, display swap); also at 65fb551012078fc3058d8a23b3fa4be1846fd056 (layout.tsx:8,28-31)"
+        },
+        {
+          "call": "GET fonts.gstatic.com/s/inter/v20/... woff2, each URL returned in the CSS",
+          "operation": "getFontFile",
+          "evidence": "the same build"
+        }
+      ]
+    },
+    {
+      "name": "calcom/cal.diy",
+      "commit": "5918e66cc56b3a36c1e7205c7fc00eaad50dece8",
+      "client": "next build (Next.js 15.5.8, next/font's packages/font/src/google/fetch-resource.ts, the same User-Agent)",
+      "backend": [
+        {
+          "call": "GET fonts.googleapis.com/css2?family=Inter:wght@100..900&display=swap",
+          "operation": "getStylesheet2",
+          "evidence": "apps/web/app/layout.tsx:2,18; apps/web/components/PageWrapper.tsx:13,36"
+        },
+        {
+          "call": "GET fonts.gstatic.com/s/inter/v20/... woff2, each URL returned in the CSS",
+          "operation": "getFontFile",
+          "evidence": "the same build"
+        }
+      ]
+    }
+  ],
+  "notDemanded": "OAuth, font submission/publishing UI, effects and advanced catalog capabilities are outside these client paths."
+}

package/journeys/first-use.json

@@ -0,0 +1,20 @@
+{
+  "schemaVersion": 1,
+  "source": "majodev/google-webfonts-helper ff245dc87cfcbaeacd4120cf1b4a7443b59db42f package.json axios1.20.0 and server/logic/fetchGoogleFonts.ts, fetchCSS.ts, fetchFontSubsetArchive.ts; Google Developer API guide",
+  "about": "The default seed publishes the attributed vendor snapshot through its publisher door. The customer reads the issued key and authenticates with the real axios client, consuming metadata/CSS/src bytes. Retention re-reads without writes. This entry is not run during source construction.",
+  "files": {
+    "package.json": "{\"type\": \"module\", \"dependencies\": {\"axios\": \"1.20.0\"}}\n",
+    ".env.example": "GOOGLE_FONTS_API_KEY=\n",
+    "app.mjs": "import axios from 'axios';\nimport assert from 'node:assert/strict';\nconst key = process.env.GOOGLE_FONTS_API_KEY;\nassert.ok(key, 'World-issued GOOGLE_FONTS_API_KEY is required');\nconst res = await axios.get(`https://www.googleapis.com/webfonts/v1/webfonts?sort=popularity&key=${key}`, { responseType: 'json', maxRedirects: 0 });\nassert.equal(res.data.kind, 'webfonts#webfontList');\nconst item = res.data.items.find(f => f.family === 'Antic');\nassert.ok(item); assert.ok(item.variants.includes('regular')); assert.ok(item.subsets.includes('latin'));\nconst agents = {\"0\": \"Mozilla/5.0 (compatible; MSIE 8.0; Windows NT 6.1; Trident/4.0)\", \"1\": \"Mozilla/5.0 (Windows NT 6.1; WOW64; rv:27.0) Gecko/20100101 Firefox/27.0\", \"2\": \"Mozilla/5.0 (Windows NT 6.3; rv:39.0) Gecko/20100101 Firefox/39.0\", \"3\": \"Mozilla/4.0 (iPad; CPU OS 4_0_1 like Mac OS X) AppleWebKit/534.46 (KHTML, like Gecko) Version/4.1 Mobile/9A405 Safari/7534.48.3\", \"4\": \"Mozilla/5.0 (Unknown; Linux x86_64) AppleWebKit/538.1 (KHTML, like Gecko) Safari/538.1 Daum/4.1\"};\nfor (const agent of Object.values(agents)) {\n const css = await axios.get('http://fonts.googleapis.com/css?family='+encodeURIComponent(item.family+':regular')+'&subset=latin', { responseType: 'text', maxRedirects: 0, headers: { Accept: 'text/css,*/*;q=0.1', 'User-Agent': agent } });\n assert.match(css.data, /@font-face/);\n const url = css.data.match(/url\\((https?:\\/\\/[^)]+)\\)/)?.[1]; assert.ok(url);\n const file = await axios.get(url.replace('http://','https://'), { responseType: 'arraybuffer', maxRedirects: 0 });\n assert.ok(file.data.length > 0); assert.ok(file.headers['content-type']);\n}\nconsole.log('Read retained Google Fonts catalog, CSS and bytes through unchanged axios calls');\n"
+  },
+  "run": [
+    "node",
+    "app.mjs"
+  ],
+  "retention": {
+    "readback": [
+      "node",
+      "app.mjs"
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@volter/twin-googlefonts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.2",
+  "description": "The googlefonts twin (Protocol 3).",
+  "author": "Volter (https://github.com/volter-ai)",
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "bin": {
+    "world-googlefonts": "dist/src/cli.js"
+  },
+  "files": [
+    "src",
+    "dist",
+    "generated",
+    "spec",
+    "css/src",
+    "css/spec",
+    "api/src",
+    "api/spec",
+    "assets/src",
+    "assets/spec",
+    "README.md",
+    "!**/*.test.ts",
+    "vendor",
+    "LICENSE",
+    "journeys/customer-life.json",
+    "journeys/decisions.json",
+    "journeys/demand.json",
+    "journeys/first-use.json"
+  ],
+  "peerDependencies": {
+    "@volter/world-core": "^3.0.185"
+  },
+  "engines": {
+    "node": ">=22.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/twin-packs-p3.git",
+    "directory": "googlefonts"
+  },
+  "packageManager": "pnpm@12.15.0",
+  "devEngines": {
+    "packageManager": {
+      "name": "pnpm",
+      "version": "12.15.0",
+      "onFail": "error"
+    }
+  },
+  "volterRelease": {
+    "commit": "c41b6615f37f0e7d69753fd85ff9568d9f4c8174"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+// world-googlefonts: serve the googlefonts twin.
+import { parseArgs } from 'node:util';
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+import { createGooglefontsTwinServer } from './server.ts';
+
+const { values, positionals } = parseArgs({ options: { port: { type: 'string' }, root: { type: 'string' }, 'read-only': { type: 'boolean' }, database: { type: 'string' } }, allowPositionals: true, strict: true });
+if (positionals.length > 1) throw new Error('Expected one command');
+const [cmd] = positionals;
+const port = Number(values.port ?? '0') || undefined;
+const root = values.root;
+const readOnly = Boolean(values['read-only']);
+// the selected twin's private Postgres, which the runtime binds a pack declaring managedDatabase to
+const database = values.database;
+
+if (cmd === 'serve' || cmd === undefined) {
+  const s = await createGooglefontsTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}), ...(database ? { database } : {}) });
+  process.stdout.write(`googlefonts twin${readOnly ? ' [read-only]' : ''} at http://127.0.0.1:${s.port}\n`);
+  await keepProcessAlive();
+} else {
+  process.stdout.write('Usage: world-googlefonts serve [--port N] [--root DIR] [--read-only] [--database URL]\n');
+}

package/src/fetch.ts

@@ -0,0 +1,11 @@
+// GENERATED by scripts/create-pack.ts (--init, --index): a fixed file. The kernel serves the vendor's discovery door and
+// sends each request to the lane its manifest's routes name (architecture, "Other wires: lanes").
+import { createVendorFetch, type DerivedFetch, type PackFetchOptions } from '@volter/world-core';
+import { manifest } from './manifest.ts';
+import { createApiLaneFetch, manifest as api_manifest } from '../api/src/index.ts';
+import { createAssetsLaneFetch, manifest as assets_manifest } from '../assets/src/index.ts';
+import { createCssLaneFetch, manifest as css_manifest } from '../css/src/index.ts';
+
+export function createGooglefontsFetch(options: PackFetchOptions = {}): DerivedFetch {
+  return createVendorFetch(manifest, { "api": { fetch: createApiLaneFetch(options), manifest: api_manifest }, "assets": { fetch: createAssetsLaneFetch(options), manifest: assets_manifest }, "css": { fetch: createCssLaneFetch(options), manifest: css_manifest } });
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+// @volter/twin-googlefonts — the googlefonts twin (Protocol 3). A fixed file (create-pack): the descriptor is the manifest's, and the
+// kernel derives the vendor-backed half from the generated surface, unless the manifest declares none (vendorBacked.none;
+// architecture, "The real-system adapters").
+import { packOf, registerPack, type DerivedSurface } from '@volter/world-core';
+import { manifest } from './manifest.ts';
+import { manifest as apiManifest } from '../api/src/manifest.ts';
+import apiSurface from '../api/src/generated/surface.gen.json' with { type: 'json' };
+import { manifest as assetsManifest } from '../assets/src/manifest.ts';
+import assetsSurface from '../assets/src/generated/surface.gen.json' with { type: 'json' };
+import { manifest as cssManifest } from '../css/src/manifest.ts';
+import cssSurface from '../css/src/generated/surface.gen.json' with { type: 'json' };
+
+export { createGooglefontsFetch } from './fetch.ts';
+export { createGooglefontsTwinServer } from './server.ts';
+export { manifest };
+
+export const pack = registerPack(packOf(manifest, { "api": { manifest: apiManifest, surface: apiSurface as unknown as DerivedSurface }, "assets": { manifest: assetsManifest, surface: assetsSurface as unknown as DerivedSurface }, "css": { manifest: cssManifest, surface: cssSurface as unknown as DerivedSurface } }));

package/src/manifest.ts

@@ -0,0 +1,29 @@
+// Google Fonts: one store, with catalog, browser-selected CSS and font-file lanes.
+import type { VendorManifest } from '@volter/world-core';
+export const manifest: VendorManifest = {
+  vendor: 'googlefonts',
+  discovery: { twinOf: 'Google Fonts Developer API, the CSS and CSS2 APIs and the font URLs they return',
+    stores: 'published vendor-shaped font items, exact browser CSS, font blobs and World-issued key hashes' },
+  lanes: { routes: [
+    { lane: 'css', host: '^fonts[.]googleapis[.]com$' },
+    { lane: 'assets', host: '^fonts[.]gstatic[.]com$' },
+    { lane: 'api', host: '^(www|webfonts)[.]googleapis[.]com$' },
+  ], default: 'api' },
+  descriptor: {
+    protocol: '3', transport: 'rest', archetype: 'crud', bin: 'world-googlefonts',
+    resources: ['webfont', '_api_key', '_font_catalog', '_stylesheet', '_font_file'],
+    specSource: 'api/spec/SOURCE.md: unchanged Google Discovery; css/spec/SOURCE.md and assets/spec/SOURCE.md: Google documentation and retained font responses',
+    description: 'Google Fonts catalog, exact published CSS representations and genuine font bytes; a World-issued query API key. Seed data is the attributed Antic reference catalog and the CSS2 weights 500-700 of Inter, not the complete live Google catalog.',
+    // next/font/google fetches the font's stylesheet and files from Google at an app's build (twin-world architecture,
+    // Selection: a module that reaches the vendor by itself is evidence, as an SDK is)
+    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$)' },
+    ],
+    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' } },
+    endpointEnvNone: 'Pinned helper hardcodes the vendor API and CSS hosts, then downloads their returned gstatic URLs. Scoped host routing preserves these URLs.',
+  },
+};