@thomas.f/prnext 0.1.0-alpha.1

package/build/font-files.mjs

@@ -0,0 +1,221 @@
+import { readFile, writeFile, mkdir, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import googleFonts from './font-data.json' with { type: 'json' };
+
+const formats = { woff: 'woff', woff2: 'woff2', ttf: 'truetype', otf: 'opentype', eot: 'embedded-opentype' };
+const types = { woff: 'font/woff', woff2: 'font/woff2', ttf: 'font/ttf', otf: 'font/otf', eot: 'application/vnd.ms-fontobject' };
+const MAX_FONT = 16 * 1024 * 1024;
+const quote = value => JSON.stringify(String(value));
+const list = value => value === undefined ? [] : Array.isArray(value) ? value : [value];
+const commonOptions = ['display', 'preload', 'fallback', 'variable', 'adjustFontFallback', 'weight', 'style'];
+const safeValue = value => typeof value === 'string' && !/[;{}\u0000-\u001f\u007f]/.test(value);
+function fail(message) { throw new Error(`next/font: ${message}`); }
+function weight(value) {
+  if (typeof value !== 'string' || !/^(?:normal|bold|[1-9]\d{0,2}|1000)(?: (?:[1-9]\d{0,2}|1000))?$/.test(value)) fail(`Invalid font weight ${JSON.stringify(value)}.`);
+  const values = value.split(' ').map(Number);
+  if (values.length > 1 && values[0] > values[1]) fail('Font weight ranges must be increasing.');
+  return value;
+}
+function style(value) {
+  if (!['normal', 'italic', 'oblique'].includes(value)) fail(`Invalid font style ${JSON.stringify(value)}.`);
+  return value;
+}
+function validate(kind, options) {
+  if (!options || typeof options !== 'object' || Array.isArray(options)) fail('Expected an options object.');
+  const allowed = new Set([...commonOptions, ...(kind === 'local' ? ['src', 'declarations'] : ['subsets', 'axes'])]);
+  for (const key of Object.keys(options)) if (!allowed.has(key)) fail(`Unsupported ${kind} font option ${key}.`);
+  const result = { display: 'swap', preload: true, fallback: [], ...options };
+  if (!['auto', 'block', 'swap', 'fallback', 'optional'].includes(result.display)) fail('Invalid display option.');
+  if (typeof result.preload !== 'boolean') fail('preload must be a boolean.');
+  if (!Array.isArray(result.fallback) || result.fallback.some(value => !safeValue(value) || !value)) fail('fallback must be an array of font family names.');
+  if (result.variable !== undefined && (typeof result.variable !== 'string' || !/^--[A-Za-z_][A-Za-z0-9_-]*$/.test(result.variable))) fail('variable must be a CSS custom property, such as --font-body.');
+  if (kind === 'google' ? result.adjustFontFallback !== undefined && typeof result.adjustFontFallback !== 'boolean'
+    : result.adjustFontFallback !== undefined && ![false, 'Arial', 'Times New Roman'].includes(result.adjustFontFallback)) fail(`Invalid adjustFontFallback option for ${kind} fonts.`);
+  return result;
+}
+
+async function responseBytes(url, maximum, accept) {
+  const response = await fetch(url, { signal: AbortSignal.timeout(15_000), headers: { accept,
+    'user-agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36' } });
+  if (!response.ok) { await response.body?.cancel(); fail(`Unable to download ${url}: HTTP ${response.status}.`); }
+  if (Number(response.headers.get('content-length')) > maximum) { await response.body?.cancel(); fail(`Font resource exceeds ${maximum} bytes.`); }
+  const reader = response.body?.getReader();
+  if (!reader) fail(`Empty font resource at ${url}.`);
+  const chunks = []; let length = 0;
+  try {
+    for (;;) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      length += value.byteLength;
+      if (length > maximum) fail(`Font resource exceeds ${maximum} bytes.`);
+      chunks.push(value);
+    }
+  } catch (error) { await reader.cancel().catch(() => {}); throw error; }
+  finally { reader.releaseLock(); }
+  if (!length) fail(`Empty font resource at ${url}.`);
+  return Buffer.concat(chunks, length);
+}
+
+async function emit(bytes, ext, stage, assetBase) {
+  const hash = createHash('sha256').update(bytes).digest('hex').slice(0, 24);
+  const filename = `font-${hash}.${ext}`;
+  await mkdir(path.join(stage, 'assets'), { recursive: true });
+  await writeFile(path.join(stage, 'assets', filename), bytes);
+  return { href: `${assetBase}/${filename}`, type: types[ext], crossOrigin: 'anonymous' };
+}
+
+async function local(options, context) {
+  const sources = typeof options.src === 'string' ? [{ path: options.src, weight: options.weight, style: options.style }] : options.src;
+  if (!Array.isArray(sources) || !sources.length || sources.length > 64) fail('src must be a font path or a nonempty array of at most 64 font descriptors.');
+  if (options.weight !== undefined) weight(options.weight);
+  if (options.style !== undefined) style(options.style);
+  const declarations = options.declarations || [];
+  if (!Array.isArray(declarations)) fail('declarations must be an array.');
+  for (const item of declarations) {
+    if (!item || !/^[a-z][a-z-]*$/.test(item.prop) || ['src', 'font-display', 'font-weight', 'font-style'].includes(item.prop) || !safeValue(item.value)) fail('Invalid font-face declaration.');
+  }
+  const faces = [];
+  let total = 0;
+  for (const item of sources) {
+    if (!item || typeof item.path !== 'string' || !item.path || /^(?:https?:|data:)/i.test(item.path) || item.path.includes('\0')) fail('Local fonts require a local file path.');
+    for (const key of Object.keys(item)) if (!['path', 'weight', 'style'].includes(key)) fail(`Invalid local font descriptor property ${key}.`);
+    const ext = path.extname(item.path).slice(1).toLowerCase();
+    if (!formats[ext]) fail(`Unsupported local font extension in ${item.path}.`);
+    const filename = path.resolve(path.dirname(context.file), item.path);
+    const size = (await stat(filename)).size;
+    if (size > MAX_FONT || (total += size) > 64 * 1024 * 1024) fail('Local fonts exceed the build resource limit (16 MiB per file, 64 MiB per call).');
+    const bytes = await readFile(filename);
+    if (!bytes.length) fail(`Empty local font ${item.path}.`);
+    const resource = await emit(bytes, ext, context.stage, context.assetBase);
+    const fontWeight = item.weight ?? options.weight, fontStyle = item.style ?? options.style;
+    if (fontWeight !== undefined) weight(fontWeight);
+    if (fontStyle !== undefined) style(fontStyle);
+    const descriptors = [...declarations.map(item => `${item.prop}:${item.value}`),
+      ...(declarations.some(item => item.prop === 'font-family') ? [] : [`font-family:${quote(context.family)}`]),
+      `src:url(${quote(resource.href)}) format(${quote(formats[ext])})`, `font-display:${options.display}`,
+      ...(fontWeight ? [`font-weight:${fontWeight}`] : []), ...(fontStyle ? [`font-style:${fontStyle}`] : [])];
+    faces.push({ css: `@font-face{${descriptors.join(';')};}`, bytes, resource, preload: options.preload, weight: fontWeight, style: fontStyle });
+  }
+  return { faces, weight: sources.length === 1 ? faces[0].weight : undefined, style: sources.length === 1 ? faces[0].style : undefined };
+}
+
+function googleOptions(name, options) {
+  const family = name.replaceAll('_', ' '), metadata = googleFonts[family];
+  if (!metadata) fail(`Unknown Google font ${name}.`);
+  const weights = [...new Set(list(options.weight))], styles = [...new Set(list(options.style))];
+  if (!weights.length) {
+    if (!metadata.weights.includes('variable')) fail(`Missing weight for ${family}. Available: ${metadata.weights.join(', ')}.`);
+    weights.push('variable');
+  }
+  if (weights.some(value => !metadata.weights.includes(value)) || (weights.length > 1 && weights.includes('variable'))) fail(`Invalid weight for ${family}. Available: ${metadata.weights.join(', ')}.`);
+  if (!styles.length) styles.push(metadata.styles.length === 1 ? metadata.styles[0] : 'normal');
+  if (styles.some(value => !metadata.styles.includes(value))) fail(`Invalid style for ${family}.`);
+  const subsets = options.subsets || [];
+  if (!Array.isArray(subsets) || subsets.some(value => !metadata.subsets.includes(value))) fail(`Invalid subset for ${family}. Available: ${metadata.subsets.join(', ')}.`);
+  const preload = options.preload && metadata.subsets.length > 0;
+  if (preload && !subsets.length) fail(`Preload is enabled for ${family}: specify subsets or preload:false.`);
+  const axes = options.axes || [];
+  if (!Array.isArray(axes) || (axes.length && weights[0] !== 'variable')) fail('axes requires a variable font.');
+  const extraAxes = [];
+  for (const tag of new Set(axes)) {
+    const axis = metadata.axes?.find(axis => axis.tag === tag && axis.tag !== 'wght');
+    if (!axis) fail(`Unknown variable axis ${tag} for ${family}.`);
+    extraAxes.push([tag, `${axis.min}..${axis.max}`]);
+  }
+  const variableWeight = metadata.axes?.find(axis => axis.tag === 'wght');
+  const variants = [];
+  for (const currentStyle of styles) for (const currentWeight of weights) {
+    const entries = [...extraAxes];
+    if (styles.includes('italic')) entries.push(['ital', currentStyle === 'italic' ? '1' : '0']);
+    if (currentWeight !== 'variable') entries.push(['wght', currentWeight]);
+    else if (variableWeight) entries.push(['wght', `${variableWeight.min}..${variableWeight.max}`]);
+    entries.sort(([a], [b]) => (/^[a-z]/.test(a) === /^[a-z]/.test(b)) ? a.localeCompare(b, 'en', { sensitivity: 'variant' }) : /^[a-z]/.test(a) ? -1 : 1);
+    variants.push(entries);
+  }
+  const values = variants.map(entries => entries.map(([, value]) => value).join(',')).sort((a, b) => {
+    const left = a.split(',').map(parseFloat), right = b.split(',').map(parseFloat);
+    for (let index = 0; index < left.length; index++) if (left[index] !== right[index]) return left[index] - right[index];
+    return 0;
+  });
+  const axesQuery = variants[0].length ? `:${variants[0].map(([tag]) => tag).join(',')}@${[...new Set(values)].join(';')}` : '';
+  return { url: `https://fonts.googleapis.com/css2?family=${family.replaceAll(' ', '+')}${axesQuery}&display=${options.display}`, preload, subsets,
+    weight: weights.length === 1 && weights[0] !== 'variable' ? weights[0] : undefined, style: styles.length === 1 ? styles[0] : undefined };
+}
+
+async function google(name, options, context) {
+  const normalized = googleOptions(name, options);
+  const css = (await responseBytes(normalized.url, 1024 * 1024, 'text/css')).toString('utf8');
+  const faces = [], downloaded = new Map();
+  let total = 0;
+  const facePattern = /(?:\/\*\s*([^*]+?)\s*\*\/\s*)?@font-face\s*\{([^}]+)\}/g;
+  for (const match of css.matchAll(facePattern)) {
+    if (faces.length >= 128) fail('Google font CSS has too many font faces.');
+    const subset = match[1]?.trim();
+    const urls = [...match[2].matchAll(/url\(\s*(['"]?)([^)'"\s]+)\1\s*\)/g)];
+    if (!urls.length) fail('Google font face is missing its source.');
+    let content = match[2].replace(/font-family\s*:[^;]+;/i, `font-family:${quote(context.family)};`);
+    let representative;
+    for (const urlMatch of urls) {
+      const url = new URL(urlMatch[2]);
+      if (url.protocol !== 'https:' || url.hostname !== 'fonts.gstatic.com' || url.username || url.password) fail('Google font CSS referenced an unexpected font origin.');
+      if (!downloaded.has(url.href)) {
+        if (downloaded.size >= 64) fail('Google font call exceeds 64 files.');
+        const bytes = await responseBytes(url.href, MAX_FONT, 'font/woff2,font/woff,*/*');
+        total += bytes.length;
+        if (total > 64 * 1024 * 1024) fail('Google font call exceeds 64 MiB.');
+        const ext = path.extname(url.pathname).slice(1).toLowerCase();
+        if (!formats[ext]) fail(`Unsupported Google font extension ${ext}.`);
+        downloaded.set(url.href, { bytes, resource: await emit(bytes, ext, context.stage, context.assetBase) });
+      }
+      const source = downloaded.get(url.href);
+      representative ||= source;
+      content = content.replace(urlMatch[0], `url(${quote(source.resource.href)})`);
+    }
+    const fontWeight = /font-weight\s*:\s*([^;]+)/i.exec(content)?.[1]?.trim();
+    const fontStyle = /font-style\s*:\s*([^;]+)/i.exec(content)?.[1]?.trim();
+    faces.push({ css: `@font-face{${content}}`, ...representative, preload: normalized.preload && normalized.subsets.includes(subset), weight: fontWeight, style: fontStyle });
+  }
+  if (!faces.length) fail(`No font faces returned for ${name}.`);
+  return { faces, weight: normalized.weight, style: normalized.style };
+}
+
+async function fallbackMetrics(faces, fallbackName) {
+  const { create } = await import('fontkit');
+  // Prefer an upright face near the normal text weight for a shared fallback.
+  const candidates = [...faces].sort((a, b) => Number(a.style === 'italic') - Number(b.style === 'italic') || Math.abs((parseFloat(a.weight) || 400) - 400) - Math.abs((parseFloat(b.weight) || 400) - 400));
+  for (const face of candidates) {
+    let font;
+    try { font = create(face.bytes); } catch { continue; }
+    if (!font.unitsPerEm) continue;
+    const sample = 'aaabcdeeeefghiijklmnnoopqrrssttuvwxyz      ';
+    let size = 1;
+    if ([...sample].every(character => font.hasGlyphForCodePoint(character.codePointAt(0)))) {
+      const glyphs = font.glyphsForString(sample);
+      const average = glyphs.reduce((sum, glyph) => sum + glyph.advanceWidth, 0) / glyphs.length;
+      size = average / font.unitsPerEm / ((fallbackName === 'Times New Roman' ? 854.3953488372093 : 934.5116279069767) / 2048);
+    }
+    if (!Number.isFinite(size) || size <= 0) size = 1;
+    const percent = value => `${Math.abs(value * 100).toFixed(2)}%`;
+    return `src:local(${quote(fallbackName)});ascent-override:${percent(font.ascent / font.unitsPerEm / size)};descent-override:${percent(font.descent / font.unitsPerEm / size)};line-gap-override:${percent(font.lineGap / font.unitsPerEm / size)};size-adjust:${percent(size)};`;
+  }
+  return null;
+}
+
+export async function compileFont({ kind, name, options: input, ...context }) {
+  const options = validate(kind, input);
+  const declaredFamily = kind === 'local' && options.declarations?.find(item => item?.prop === 'font-family')?.value;
+  const family = declaredFamily ? String(declaredFamily).replace(/['"]/g, '') : `__prnext_${kind === 'google' ? name : 'local'}_${context.id}`;
+  const compiled = await (kind === 'local' ? local(options, { ...context, family }) : google(name, options, { ...context, family }));
+  const fallback = options.adjustFontFallback === false ? null : await fallbackMetrics(compiled.faces, options.adjustFontFallback === 'Times New Roman' ? 'Times New Roman' : 'Arial');
+  const familyList = [quote(family), ...(fallback ? [quote(family + '_Fallback')] : []), ...options.fallback].join(',');
+  const className = `__font_${context.id}`, variable = options.variable ? `__variable_${context.id}` : undefined;
+  const fontWeight = compiled.weight && !compiled.weight.includes(' ') ? (compiled.weight === 'normal' ? 400 : compiled.weight === 'bold' ? 700 : Number(compiled.weight)) : undefined;
+  const fontStyle = compiled.style;
+  const value = { className, style: { fontFamily: familyList, ...(fontWeight !== undefined ? { fontWeight } : {}), ...(fontStyle ? { fontStyle } : {}) }, ...(variable ? { variable } : {}) };
+  const classRules = `font-family:${familyList};${fontWeight !== undefined ? `font-weight:${fontWeight};` : ''}${fontStyle ? `font-style:${fontStyle};` : ''}`;
+  const css = compiled.faces.map(face => face.css).join('\n') + (fallback ? `\n@font-face{font-family:${quote(family + '_Fallback')};${fallback}}` : '')
+    + `\n.${className}{${classRules}}` + (variable ? `\n.${variable}{${options.variable}:${familyList};}` : '');
+  const preloads = [...new Map(compiled.faces.filter(face => face.preload).map(face => [face.resource.href, face.resource])).values()];
+  return { value, css, preloads };
+}

package/build/fonts.mjs

@@ -0,0 +1,131 @@
+import {generateMapped} from './source-maps.mjs';
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { parse } from '@babel/parser';
+import traverseModule from '@babel/traverse';
+import generateModule from '@babel/generator';
+import * as t from '@babel/types';
+import { compileFont } from './font-files.mjs';
+
+const traverse = traverseModule.default || traverseModule;
+const generate = generateModule.default || generateModule;
+const fontImport = /^(?:next|prnext|@thomas\.f\/prnext)\/font\/(local|google)(?:\.js)?$/;
+const hash = value => createHash('sha256').update(value).digest('hex').slice(0, 20);
+
+function literal(node, file) {
+  while (t.isTSAsExpression(node) || t.isTSSatisfiesExpression(node) || t.isTSNonNullExpression(node)) node = node.expression;
+  if (t.isStringLiteral(node) || t.isBooleanLiteral(node) || t.isNumericLiteral(node)) return node.value;
+  if (t.isNullLiteral(node)) return null;
+  if (t.isUnaryExpression(node, { operator: '-' }) && t.isNumericLiteral(node.argument)) return -node.argument.value;
+  if (t.isArrayExpression(node)) return node.elements.map(item => literal(item, file));
+  if (t.isObjectExpression(node)) {
+    const result = Object.create(null);
+    for (const item of node.properties) {
+      if (!t.isObjectProperty(item) || item.computed || item.method) throw new Error(`Font options must contain only literal properties (${file}).`);
+      const key = t.isIdentifier(item.key) ? item.key.name : item.key.value;
+      result[key] = literal(item.value, file);
+    }
+    return result;
+  }
+  throw new Error(`Font options must be statically written literals, without variables, spreads or function calls (${file}).`);
+}
+
+/** Fonts are compiled once per build; generated modules contain only objects and CSS imports. */
+export function createFonts({ projectRoot, stage, assetBase }) {
+  const sources = new Map(), compilations = new Map(), modules = new Map(), styles = new Set(), graph = new Map();
+  async function prepare(kind, name, options, file, position) {
+    const id = hash(JSON.stringify([path.relative(projectRoot, file), position, kind, name, options]));
+    if (!compilations.has(id)) compilations.set(id, (async () => {
+      const compiled = await compileFont({ kind, name, options, file, id, stage, assetBase });
+      const moduleFile = path.join(stage, '.entries', `font-${id}.mjs`);
+      const cssFile = path.join(stage, '.entries', `font-${id}.css`);
+      await mkdir(path.dirname(moduleFile), { recursive: true });
+      await writeFile(cssFile, compiled.css);
+      await writeFile(moduleFile, `import ${JSON.stringify(cssFile)};\nexport default ${JSON.stringify(compiled.value)};\n`);
+      modules.set(moduleFile, compiled.preloads);
+      styles.add(cssFile);
+      return moduleFile;
+    })());
+    return compilations.get(id);
+  }
+  async function transformSource(source, file) {
+    if (/(?:^|[/\\])pages[/\\]_document\.[cm]?[jt]sx?$/.test(file)) throw new Error('next/font cannot be used in pages/_document. Define fonts in pages/_app or a page component.');
+    const ast = parse(source, { sourceType: 'unambiguous', sourceFilename: file, plugins: ['jsx', ...(/\.tsx?$/.test(file) ? ['typescript'] : [])] });
+    let program;
+    traverse(ast, { Program(value) { program = value; value.stop(); } });
+    const imports = [], calls = [];
+    for (const statement of program.get('body')) {
+      if (!statement.isImportDeclaration() || !fontImport.test(statement.node.source.value) || statement.node.importKind === 'type') continue;
+      const kind = fontImport.exec(statement.node.source.value)[1];
+      for (const item of statement.node.specifiers) {
+        if (item.importKind === 'type') continue;
+        if (kind === 'local' ? !t.isImportDefaultSpecifier(item) : !t.isImportSpecifier(item)) throw new Error(`${statement.node.source.value} requires ${kind === 'local' ? 'a default import' : 'named font imports'} (${file}).`);
+        const name = kind === 'local' ? 'local' : item.imported.name || item.imported.value;
+        const binding = program.scope.getBinding(item.local.name);
+        for (const reference of binding.referencePaths) {
+          const call = reference.parentPath;
+          const declaration = call.parentPath;
+          const variable = declaration?.parentPath;
+          const owner = variable?.parentPath?.isExportNamedDeclaration() ? variable.parentPath.parentPath : variable?.parentPath;
+          if (!call.isCallExpression() || call.node.callee !== reference.node || !declaration.isVariableDeclarator() || declaration.node.init !== call.node || !t.isIdentifier(declaration.node.id) || !variable.isVariableDeclaration({ kind: 'const' }) || !owner?.isProgram()) {
+            throw new Error(`Font loaders must be called and assigned to a const at module scope (${file}).`);
+          }
+          if (call.node.arguments.length > 1) throw new Error(`Font loaders accept a single options object (${file}).`);
+          const options = call.node.arguments.length ? literal(call.node.arguments[0], file) : {};
+          const identifier = program.scope.generateUidIdentifier('prnextFont');
+          calls.push({ kind, name, options, position: call.node.start, call, identifier });
+        }
+      }
+      imports.push(statement);
+    }
+    if (!imports.length) return source;
+    for (const item of calls) {
+      const moduleFile = await prepare(item.kind, item.name, item.options, file, item.position);
+      item.call.replaceWith(item.identifier);
+      program.node.body.unshift(t.importDeclaration([t.importDefaultSpecifier(item.identifier)], t.stringLiteral(moduleFile)));
+    }
+    for (const statement of imports) statement.remove();
+    return generateMapped(generate, ast, { retainLines: true }, source, file);
+  }
+  const normalize = file => path.isAbsolute(file) ? file : path.resolve(projectRoot, file);
+  return {
+    transform(source, file) {
+      if (!/(?:next|prnext|@thomas\.f\/prnext)\/font\//.test(source)) return source;
+      const key = `${file}\0${hash(source)}`;
+      if (!sources.has(key)) sources.set(key, transformSource(source, file));
+      return sources.get(key);
+    },
+    plugin() {
+      return { name: 'prnext-font-assets', setup(build) {
+        build.onResolve({ filter: /font-[a-f0-9]+\.mjs$/ }, args => modules.has(args.path) ? { path: args.path } : undefined);
+        // Generated CSS must not run through application PostCSS plugins again.
+        build.onLoad({ filter: /\.css$/, namespace: 'file' }, async args => styles.has(args.path) ? { contents: await readFile(args.path, 'utf8'), loader: 'css', resolveDir: path.dirname(args.path) } : undefined);
+        build.onResolve({ filter: /^\// }, args => args.kind === 'url-token' && styles.has(args.importer) ? { path: args.path, external: true } : undefined);
+        build.onResolve({ filter: /^https?:\/\// }, args => args.kind === 'url-token' && styles.has(args.importer) ? { path: args.path, external: true } : undefined);
+      } };
+    },
+    record(metafile) {
+      for (const [file, input] of Object.entries(metafile.inputs)) {
+        const key = normalize(file);
+        if (!graph.has(key)) graph.set(key, new Set());
+        for (const dependency of input.imports) if (!dependency.external) graph.get(key).add(normalize(dependency.path));
+      }
+    },
+    attach(manifest) {
+      for (const route of manifest.routes) {
+        if (route.kind !== 'page') continue;
+        const pending = [path.join(stage, '.entries', `${route.id}.server.mjs`)];
+        const visited = new Set(), preloads = new Map();
+        while (pending.length) {
+          const file = pending.pop();
+          if (visited.has(file)) continue;
+          visited.add(file);
+          for (const preload of modules.get(file) || []) preloads.set(preload.href, preload);
+          for (const dependency of graph.get(file) || []) pending.push(dependency);
+        }
+        if (preloads.size) route.fonts = [...preloads.values()];
+      }
+    },
+  };
+}

package/build/framework-imports.mjs

@@ -0,0 +1,17 @@
+const adapters = new Map([
+  ['dist/shared/lib/router-context.shared-runtime','next-router-context'],
+  ['dist/shared/lib/router-context','next-router-context'],
+  ['dist/shared/lib/app-router-context.shared-runtime','next-app-router-context'],
+]);
+// Keep the historical import alias for existing applications. npm's scoped
+// package name adds a slash of its own, so strip the entire package prefix.
+export const frameworkPackages = ['next', 'prnext', '@thomas.f/prnext'];
+export const frameworkImportPattern = /^(?:next|prnext|@thomas\.f\/prnext)(?:\/|$)/;
+export const frameworkSubpathPattern = /^(?:next|prnext|@thomas\.f\/prnext)\//;
+export const frameworkRuntimeImportPattern = /^(?:next(?:\/|$)|(?:prnext|@thomas\.f\/prnext)\/)/;
+// Only explicit, tested private contracts are adapted. Unknown internals still
+// fail instead of silently importing a second framework runtime from npm.
+export function frameworkImportName(specifier) {
+  const name=specifier.replace(frameworkSubpathPattern, '').replace(/\.js$/,'');
+  return adapters.get(name) || name;
+}

package/build/i18n.mjs

@@ -0,0 +1,39 @@
+import { localePath, withLocale } from '../compat/locale.cjs';
+export { localizedStaticPaths } from '../runtime/pages-paths.mjs';
+
+export function validateI18n(input) {
+  if (input === undefined) return undefined;
+  const fail = message => {throw new TypeError('i18n: '+message)};
+  if (!input || typeof input !== 'object' || Array.isArray(input)) fail('expected an object');
+  for (const key of Object.keys(input)) if (!['locales','defaultLocale','localeDetection','domains'].includes(key)) fail(`unknown option ${key}`);
+  const {locales,defaultLocale,localeDetection=true,domains=[]}=input;
+  if (!Array.isArray(locales)||!locales.length||locales.length>100||locales.some(value=>typeof value!=='string'||!/^[A-Za-z][A-Za-z0-9-]{0,63}$/.test(value))) fail('locales must contain 1–100 locale identifiers');
+  if (new Set(locales.map(value=>value.toLowerCase())).size!==locales.length) fail('duplicate locales');
+  if (!locales.includes(defaultLocale)) fail('defaultLocale must belong to locales');
+  if (typeof localeDetection!=='boolean') fail('localeDetection must be boolean');
+  if (!Array.isArray(domains)||domains.length>100) fail('domains must contain at most 100 entries');
+  const hosts=new Set(), defaults=new Set();
+  for (const value of domains) {
+    if (!value||typeof value!=='object'||Object.keys(value).some(key=>!['domain','defaultLocale','locales','http'].includes(key))) fail('invalid domain entry');
+    if (typeof value.domain!=='string'||value.domain.length>256||!/^[a-zA-Z0-9.-]+(?::[0-9]{1,5})?$/.test(value.domain)||hosts.has(value.domain.toLowerCase())) fail('invalid or duplicate domain');
+    if (!locales.includes(value.defaultLocale)||defaults.has(value.defaultLocale)) fail('invalid or duplicate domain defaultLocale');
+    if (value.http!==undefined&&typeof value.http!=='boolean') fail('domain http must be boolean');
+    if (value.locales!==undefined&&(!Array.isArray(value.locales)||value.locales.length>100||value.locales.some(locale=>!locales.includes(locale)))) fail('domain locales must belong to locales');
+    hosts.add(value.domain.toLowerCase());defaults.add(value.defaultLocale);
+  }
+  return {locales:[...locales],defaultLocale,localeDetection,domains};
+}
+export function expandLocales(manifest) {
+  const i18n=manifest.config.i18n;
+  if (!i18n) return;
+  if (manifest.routes.length * i18n.locales.length > 100000) throw new Error('i18n route expansion exceeds 100000 routes');
+  const occupied=new Set(manifest.routes.map(route=>route.pattern));
+  manifest.routes=manifest.routes.flatMap(route=>{
+    if(route.kind!=='page'||route.router==='app'||route.internal && !route.errorStatus && route.pattern !== '/_error') return [route];
+    return i18n.locales.map(locale=>{
+      const pattern=withLocale(route.pattern,locale,i18n.defaultLocale);
+      if(locale!==i18n.defaultLocale&&occupied.has(pattern)) throw new Error(`i18n route conflicts with ${pattern}`);
+      return {...route,pattern,locale,originalPattern:route.pattern,id:locale===i18n.defaultLocale?route.id:route.id+'-locale-'+locale};
+    });
+  });
+}

package/build/images-config.mjs

@@ -0,0 +1,62 @@
+const defaults = {
+  deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840], imageSizes: [32, 48, 64, 96, 128, 256, 384],
+  loader: 'default', loaderFile: '', domains: [], disableStaticImages: false, minimumCacheTTL: 14400,
+  formats: ['image/webp'], maximumDiskCacheSize: 256 * 1024 * 1024, maximumRedirects: 3, maximumResponseBody: 50_000_000,
+  dangerouslyAllowLocalIP: false, dangerouslyAllowSVG: false, contentSecurityPolicy: "script-src 'none'; frame-src 'none'; sandbox;",
+  contentDispositionType: 'attachment', remotePatterns: [], qualities: [75], unoptimized: false,
+};
+const keys = new Set([...Object.keys(defaults), 'localPatterns', 'path']);
+function patterns(values, remote) {
+  if (!Array.isArray(values) || values.length > 50) throw new Error(`images.${remote ? 'remote' : 'local'}Patterns must be an array of at most 50 patterns`);
+  return values.map(value => {
+    if (value instanceof URL) value = { protocol: value.protocol.slice(0, -1), hostname: value.hostname, port: value.port, pathname: value.pathname, search: value.search };
+    if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Image patterns must be objects or URL instances');
+    const allowed = remote ? ['protocol', 'hostname', 'port', 'pathname', 'search'] : ['pathname', 'search'];
+    for (const key of Object.keys(value)) if (!allowed.includes(key)) throw new Error(`Unsupported image pattern field ${key}`);
+    const pattern = { ...value };
+    for (const key of allowed) if (pattern[key] !== undefined && (typeof pattern[key] !== 'string' || pattern[key].length > 4096 || /[\u0000-\u001f\u007f\\]/.test(pattern[key]))) throw new Error(`Invalid image pattern ${key}`);
+    if (remote && (!pattern.hostname || /[\s/:?#]/.test(pattern.hostname.replace(/^\[.*\]$/, 'ipv6')))) throw new Error('Image remotePatterns require a hostname');
+    if (pattern.protocol !== undefined && !['http', 'https'].includes(pattern.protocol)) throw new Error('Image remotePatterns protocol must be http or https');
+    if (pattern.port !== undefined && !/^(?:\d{1,5})?$/.test(pattern.port)) throw new Error('Invalid image remotePatterns port');
+    if (pattern.pathname !== undefined && (!pattern.pathname.startsWith('/') && !pattern.pathname.startsWith('*') || /[{}[\]()!]/.test(pattern.pathname))) throw new Error('Image pattern pathname must start with / and use only * or ** wildcards');
+    if (pattern.hostname && /[{}[\]()!]/.test(pattern.hostname) && !/^\[[a-f\d:]+\]$/i.test(pattern.hostname)) throw new Error('Image pattern hostname supports only * or ** wildcards');
+    if (pattern.search !== undefined && pattern.search !== '' && !pattern.search.startsWith('?')) throw new Error('Image pattern search must be empty or start with ?');
+    return pattern;
+  });
+}
+export function validateImagesConfig(input = {}, { basePath = '', assetPrefix = '', trailingSlash = false } = {}) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) throw new Error('images must be a configuration object');
+  for (const key of Object.keys(input)) if (!keys.has(key)) throw new Error(`images.${key} is not supported`);
+  const config = { ...defaults, path: `${basePath}/_prnext/image`, ...Object.fromEntries(Object.entries(input).filter(([,value]) => value !== undefined)) };
+  for (const key of ['deviceSizes', 'imageSizes', 'qualities']) {
+    const value = config[key], max = key === 'qualities' ? 100 : 10000;
+    if (!Array.isArray(value) || (key !== 'imageSizes' && !value.length) || value.length > 50 || value.some(item => !Number.isSafeInteger(item) || item < 1 || item > max)) throw new Error(`images.${key} must contain 1 to 50 integers between 1 and ${max}`);
+    config[key] = [...new Set(value)].sort((a, b) => a - b);
+  }
+  if (!['default', 'custom'].includes(config.loader)) throw new Error('images.loader supports default or custom; pass a loader function for another image service');
+  if (typeof config.loaderFile !== 'string') throw new Error('images.loaderFile must be a project-relative path');
+  if (typeof config.path !== 'string' || !config.path.startsWith('/') || config.path.startsWith('//') || /[\s\\?#]/.test(config.path)) throw new Error('images.path must be a local URL pathname');
+  for (const key of ['disableStaticImages', 'dangerouslyAllowLocalIP', 'dangerouslyAllowSVG', 'unoptimized']) if (typeof config[key] !== 'boolean') throw new Error(`images.${key} must be boolean`);
+  for (const [key, max] of [['minimumCacheTTL', 31536000], ['maximumDiskCacheSize', 4 * 1024 ** 3], ['maximumRedirects', 20], ['maximumResponseBody', 100 * 1024 ** 2]]) {
+    if (!Number.isSafeInteger(config[key]) || config[key] < (key === 'maximumResponseBody' ? 1 : 0) || config[key] > max) throw new Error(`images.${key} must be an integer from ${key === 'maximumResponseBody' ? 1 : 0} to ${max}`);
+  }
+  if (!Array.isArray(config.formats) || !config.formats.length || config.formats.length > 2 || config.formats.some(value => !['image/avif', 'image/webp'].includes(value))) throw new Error('images.formats must contain image/avif and/or image/webp');
+  if (!['attachment', 'inline'].includes(config.contentDispositionType)) throw new Error('images.contentDispositionType must be attachment or inline');
+  if (typeof config.contentSecurityPolicy !== 'string' || /[\r\n]/.test(config.contentSecurityPolicy)) throw new Error('images.contentSecurityPolicy must be a single-line string');
+  if (!Array.isArray(config.domains) || config.domains.length > 50 || config.domains.some(value => typeof value !== 'string' || !value || /[\s/?#]/.test(value))) throw new Error('images.domains must be an array of hostnames');
+  if (trailingSlash && !config.path.endsWith('/')) config.path += '/';
+  config.remotePatterns = patterns(config.remotePatterns, true);
+  if (/^https?:\/\//.test(assetPrefix)) {
+    const url = new URL(assetPrefix);
+    if (!config.remotePatterns.some(pattern => pattern.hostname === url.hostname && pattern.protocol === url.protocol.slice(0, -1) && pattern.port === url.port && pattern.pathname === undefined && pattern.search === undefined)) config.remotePatterns.push({ protocol: url.protocol.slice(0, -1), hostname: url.hostname, port: url.port });
+  }
+  if (config.localPatterns !== undefined) {
+    config.localPatterns = patterns(config.localPatterns, false);
+    if (!/^https?:\/\//.test(assetPrefix)) {
+      const prefix = (assetPrefix || basePath).replace(/\/$/, '');
+      const pathname = `${prefix}/_prnext/assets/**`;
+      if (!config.localPatterns.some(pattern => pattern.pathname === pathname && pattern.search === '')) config.localPatterns.push({ pathname, search: '' });
+    }
+  } else config.localPatterns = [{ pathname: '**', search: '' }];
+  return config;
+}

package/build/images.mjs

@@ -0,0 +1,86 @@
+import { createHash } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { mkdir, readFile, writeFile, realpath, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { build as bundle } from 'esbuild';
+import { validateImagesConfig } from './images-config.mjs';
+import { resolveNativeBinary } from '../native/resolve.mjs';
+const execute = promisify(execFile);
+const packageRoot = fileURLToPath(new URL('../', import.meta.url));
+const imageExtension = /\.(?:png|jpe?g|webp|avif|gif|ico|bmp|tiff?|svg)$/i;
+export async function createImages({ projectRoot, stage, assetBase, config: input }) {
+  // Project configuration is already normalized, including generated static/CDN patterns.
+  const config = input || validateImagesConfig();
+  const cache = new Map();
+  let active = 0;
+  const waiting = [];
+  async function bounded(operation) {
+    if (active >= 2) await new Promise(resolve => waiting.push(resolve));
+    active++;
+    try { return await operation(); }
+    finally { active--; waiting.shift()?.(); }
+  }
+  const configured = path.join(stage, 'compat', 'image-config.cjs');
+  await mkdir(path.dirname(configured), { recursive: true });
+  const clientConfig = { deviceSizes: config.deviceSizes, imageSizes: config.imageSizes, qualities: config.qualities, path: config.path, loader: config.loader, unoptimized: config.unoptimized, dangerouslyAllowSVG: config.dangerouslyAllowSVG, localPatterns: config.localPatterns, remotePatterns: config.remotePatterns, domains: config.domains };
+  let loaderSource = '';
+  if (config.loaderFile) {
+    const file = await realpath(path.resolve(projectRoot, config.loaderFile));
+    const root = await realpath(projectRoot);
+    if (file !== root && !file.startsWith(root + path.sep)) throw new Error('images.loaderFile must be inside the project');
+    loaderSource = `\nconst custom=require(${JSON.stringify(file)});module.exports.customLoader=custom.default||custom;`;
+  }
+  await writeFile(configured, `'use strict';module.exports=${JSON.stringify(clientConfig)};${loaderSource}\n`);
+  if (loaderSource) {
+    const result = await bundle({ entryPoints: [configured], bundle: true, write: false, format: 'cjs', platform: 'neutral', target: 'es2022', logLevel: 'silent' });
+    await writeFile(configured, result.outputFiles[0].contents);
+  }
+  const files = new Map();
+  async function loadFile(filename) {
+    const size = (await stat(filename)).size;
+    if (size > 50_000_000) throw new Error(`Static image exceeds 50 MB: ${filename}`);
+    const bytes = await readFile(filename);
+    const hash = createHash('sha256').update(bytes).digest('hex').slice(0, 20);
+    const extension = path.extname(filename).toLowerCase();
+    const key = hash + extension;
+    if (!cache.has(key)) cache.set(key, (async () => {
+      let info;
+      if (extension === '.svg') {
+        const source = bytes.toString('utf8');
+        const svg = /<svg\b([^>]*)>/i.exec(source)?.[1] || '';
+        const attribute = name => new RegExp(`(?:^|\\s)${name}\\s*=\\s*["']([^"']+)["']`, 'i').exec(svg)?.[1];
+        const viewbox = (attribute('viewBox') || '').trim().split(/[\s,]+/).map(Number);
+        const dimension = name => /^\d+(?:\.\d+)?(?:px)?$/.test(attribute(name) || '') ? parseFloat(attribute(name)) : undefined;
+        info = { width: dimension('width') || viewbox[2], height: dimension('height') || viewbox[3] };
+        if (!info.width || !info.height) throw new Error(`Static SVG ${filename} requires dimensions or a viewBox`);
+      } else {
+        const binary = await resolveNativeBinary();
+        const { stdout } = await execute(binary, ['image-info', filename], { timeout: 30_000, maxBuffer: 64 * 1024 });
+        info = JSON.parse(stdout);
+      }
+      const name = `image-${hash}${extension}`;
+      await mkdir(path.join(stage, 'assets'), { recursive: true });
+      await writeFile(path.join(stage, 'assets', name), bytes);
+      return { src: `${assetBase}/${name}`, ...info };
+    })());
+    return cache.get(key);
+  }
+  function load(filename) {
+    if (!files.has(filename)) files.set(filename, bounded(() => loadFile(filename)));
+    return files.get(filename);
+  }
+  return { plugin() { return { name: 'prnext-images', setup(build) {
+    build.onResolve({ filter: /(?:^|\/)image-config\.cjs$/ }, args => args.importer && path.resolve(args.importer) === path.join(packageRoot, 'compat/image-shared.cjs') ? { path: configured } : undefined);
+    if (config.disableStaticImages) return;
+    build.onResolve({ filter: imageExtension }, async args => {
+      if (args.kind !== 'import-statement' && args.kind !== 'require-call' && args.kind !== 'dynamic-import') return;
+      if (args.pluginData?.prnextImageResolve) return;
+      const result = await build.resolve(args.path, { kind: args.kind, resolveDir: args.resolveDir, importer: args.importer, pluginData: { ...args.pluginData, prnextImageResolve: true } });
+      if (result.errors.length || result.external || !result.path) return;
+      return { path: result.path, namespace: 'prnext-image' };
+    });
+    build.onLoad({ filter: /.*/, namespace: 'prnext-image' }, async args => ({ contents: `export default ${JSON.stringify(await load(args.path))};`, loader: 'js', watchFiles: [args.path] }));
+  } }; } };
+}